openapi: 3.1.0

info:
  title: Ordius File Fingerprinting API
  version: 1.0.0
  summary: Deterministic SHA-256 File Fingerprinting API
  description: |
    The Ordius File Fingerprinting API generates deterministic SHA-256
    fingerprints together with globally stable Ordius Identifiers.

    The same binary file always produces the same fingerprint
    and the same Ordius Identifier.

    Every successful fingerprint request consumes one API credit.

servers:
  - url: https://api.ordius.net
    description: Production

tags:
  - name: File Fingerprinting

paths:

  /v1/fingerprint:

    post:

      tags:
        - File Fingerprinting

      summary: Generate File Fingerprint

      description: |
        Upload a single file to generate a deterministic SHA-256 fingerprint
        and a stable Ordius Identifier.

      parameters:

        - in: header
          name: Authorization
          required: true

          schema:
            type: string

          description: |
            Bearer API Key.

            Example:

            Bearer ORD_live_xxxxxxxxxxxxxxxxxxxxxxxxx

      requestBody:

        required: true

        content:

          multipart/form-data:

            schema:

              type: object

              required:
                - file

              properties:

                file:
                  type: string
                  format: binary
                  description: Binary file to fingerprint.

      responses:

        "200":

          description: Fingerprint successfully generated.

          headers:

            X-Ordius-Credits-Remaining:

              description: Remaining API credits.

              schema:
                type: integer

          content:

            application/json:

              schema:

                type: object

                properties:

                  success:
                    type: boolean
                    example: true

                  data:

                    type: object

                    properties:

                      ordiusId:
                        type: string
                        example: ORD-CJAB-2TTB-X6LR

                      sha256:
                        type: string
                        example: 12401d4e61bf971feceb87cecd66a421745006657af7bc7c2765f6c15c61f122

                      algorithm:
                        type: string
                        example: SHA-256

                      size:
                        type: integer
                        example: 1878

                      mimeType:
                        type: string
                        example: application/pdf

                      createdAt:
                        type: string
                        format: date-time

        "400":

          description: File missing.

          content:

            application/json:

              examples:

                FileRequired:

                  value:

                    success: false

                    error:

                      code: FILE_REQUIRED

                      message: Request must include one uploaded file using the 'file' form field.

        "401":

          description: Authentication failed.

          content:

            application/json:

              examples:

                MissingKey:

                  value:

                    success: false

                    error:

                      code: API_KEY_REQUIRED

                      message: Authorization header with Bearer API Key is required.

                InvalidKey:

                  value:

                    success: false

                    error:

                      code: INVALID_API_KEY

                      message: The supplied API Key is invalid.

        "402":

          description: Credits exhausted.

          content:

            application/json:

              example:

                success: false

                error:

                  code: CREDITS_EXHAUSTED

                  message: Your Ordius Credits have been exhausted.

        "413":

          description: Uploaded file exceeds the maximum allowed size.

        "500":

          description: Internal server error.

          content:

            application/json:

              example:

                success: false

                error:

                  code: INTERNAL_ERROR

                  message: Failed to generate fingerprint.