openapi: 3.1.0
info:
  title: Amigo Account Intake Upload API
  version: 0.1.0
servers:
- url: https://api.amigo.ai
- url: https://internal-api.amigo.ai
- url: https://api-eu-central-1.amigo.ai
- url: https://api-ap-southeast-2.amigo.ai
- url: https://api-ca-central-1.amigo.ai
security:
- Bearer-Authorization: []
  Bearer-Authorization-Organization: []
  Basic: []
tags:
- name: Intake Upload
paths:
  /upload/{link_token}/info:
    get:
      tags:
      - Intake Upload
      summary: Get Link Info
      operationId: get-intake-link-info
      parameters:
      - name: link_token
        in: path
        required: true
        schema:
          type: string
          maxLength: 64
          title: Link Token
      responses:
        '200':
          description: Link metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkInfoResponse'
        '400':
          description: Invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkErrorResponse'
        '404':
          description: Link not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkErrorResponse'
        '410':
          description: Link expired or exhausted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkErrorResponse'
        '429':
          description: Rate limited
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /upload/{link_token}/files:
    post:
      tags:
      - Intake Upload
      summary: Receive Upload
      operationId: upload-intake-file-via-link
      parameters:
      - name: link_token
        in: path
        required: true
        schema:
          type: string
          maxLength: 64
          title: Link Token
      - name: x-amigo-intake-filename
        in: header
        required: true
        schema:
          type: string
          maxLength: 256
          title: X-Amigo-Intake-Filename
      - name: x-amigo-intake-content-type
        in: header
        required: true
        schema:
          type: string
          maxLength: 128
          title: X-Amigo-Intake-Content-Type
      responses:
        '201':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadFileResponse'
        '404':
          description: Link not found
        '410':
          description: Link expired
        '413':
          description: File too large
        '422':
          description: Invalid filename or content type
        '429':
          description: Rate limited or upload limit reached
components:
  schemas:
    UploadDuplicateInfo:
      properties:
        id:
          type: string
          maxLength: 64
          title: Id
          description: UUID of the existing upload row.
        received_at:
          type: string
          maxLength: 64
          title: Received At
          description: ISO-8601 timestamp the original upload was received.
      type: object
      required:
      - id
      - received_at
      title: UploadDuplicateInfo
      description: Pointer to an existing upload row when content-hash dedup fires.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    UploadFileResponse:
      properties:
        id:
          type: string
          maxLength: 64
          title: Id
          description: UUID of the newly created upload row.
        filename:
          type: string
          maxLength: 256
          title: Filename
          description: Stored filename.
        sha256:
          type: string
          maxLength: 128
          title: Sha256
          description: SHA-256 of the uploaded bytes (lowercase hex).
        size_bytes:
          type: integer
          minimum: 0.0
          title: Size Bytes
          description: Stored size in bytes.
        scan_status:
          type: string
          maxLength: 32
          title: Scan Status
          description: Virus-scan status (e.g. ``clean``, ``skipped``).
        duplicate_of:
          anyOf:
          - $ref: '#/components/schemas/UploadDuplicateInfo'
          - type: 'null'
          description: Set when this upload's content hash matched a prior upload; otherwise null.
      type: object
      required:
      - id
      - filename
      - sha256
      - size_bytes
      - scan_status
      title: UploadFileResponse
      description: Receipt for a successful upload via an intake link.
    LinkInfoResponse:
      properties:
        display_name:
          $ref: '#/components/schemas/DescriptionString'
          description: Human-readable display name (falls back to customer slug).
        customer_slug:
          type: string
          maxLength: 128
          title: Customer Slug
          description: Stable URL-safe customer identifier.
        max_upload_bytes:
          type: integer
          minimum: 0.0
          title: Max Upload Bytes
          description: Maximum allowed upload size in bytes.
        allowed_content_types:
          items:
            type: string
          type: array
          maxItems: 64
          title: Allowed Content Types
          description: Allowed Content-Type values for uploads, sorted lexicographically.
      type: object
      required:
      - display_name
      - customer_slug
      - max_upload_bytes
      title: LinkInfoResponse
      description: Public metadata for an intake upload link, returned to the forms app.
    DescriptionString:
      type: string
      maxLength: 2000
    LinkErrorResponse:
      properties:
        error_code:
          type: string
          enum:
          - invalid_token
          - link_not_found
          - link_expired
          - link_exhausted
          title: Error Code
          description: Machine-readable error code.
        message:
          type: string
          maxLength: 512
          title: Message
          description: Human-readable error message.
      type: object
      required:
      - error_code
      - message
      title: LinkErrorResponse
      description: Error envelope returned for token / link validation failures.
  securitySchemes:
    Bearer-Authorization:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the [`SignInWithAPIKey`](sign-in-with-api-key) endpoint.
    Bearer-Authorization-Organization:
      type: apiKey
      in: header
      name: X-ORG-ID
      description: An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
    Basic:
      type: http
      scheme: basic
      description: The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.