Unisson documents API

openapi: 3.1.0
info:
  title: Unisson agent-evals documents API
  version: 1.0.0
tags:
- name: documents
paths:
  /api/v1/customers/{customer_id}/documents:
    get:
      tags:
      - documents
      summary: List Documents
      description: List all documents linked to a customer.
      operationId: list_documents_api_v1_customers__customer_id__documents_get
      security:
      - HTTPBearer: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Customer Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - documents
      summary: Add Document
      description: Link a document to a customer.
      operationId: add_document_api_v1_customers__customer_id__documents_post
      security:
      - HTTPBearer: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Customer Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentCreateRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/customers/{customer_id}/documents/upload:
    post:
      tags:
      - documents
      summary: Upload Document
      description: 'Upload a document from the user''s device into a customer.


        Stores the original file (downloadable via ``/download``), extracts text

        where possible, and kicks off background summarization. Non-extractable

        types (images, slide decks) are still stored — they just show up

        unsummarized.'
      operationId: upload_document_api_v1_customers__customer_id__documents_upload_post
      security:
      - HTTPBearer: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Customer Id
      - name: document_type
        in: query
        required: false
        schema:
          type: string
          pattern: ^(proposal|sow|technical_spec|architecture|contract|other)$
          default: other
          title: Document Type
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_document_api_v1_customers__customer_id__documents_upload_post'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/customers/{customer_id}/documents/{document_id}/download:
    get:
      tags:
      - documents
      summary: Download Document
      description: 'Return a short-lived presigned URL for an uploaded document''s file.


        Only ``provider="upload"`` rows carry an ``s3_key``; Drive/Notion rows keep

        their provider ``file_url`` and never hit this endpoint.'
      operationId: download_document_api_v1_customers__customer_id__documents__document_id__download_get
      security:
      - HTTPBearer: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Customer Id
      - name: document_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Document Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/customers/{customer_id}/documents/{document_id}/file:
    get:
      tags:
      - documents
      summary: Get Document File
      description: 'Stream an uploaded document''s raw bytes for the in-app previewer.


        Proxied through the backend (rather than the presigned URL) so the browser

        fetch isn''t blocked by S3 CORS, and served with the stored mime type —

        the presigned URL carries ``Content-Disposition: attachment``, which would

        force a download instead of rendering.'
      operationId: get_document_file_api_v1_customers__customer_id__documents__document_id__file_get
      security:
      - HTTPBearer: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Customer Id
      - name: document_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Document Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/customers/{customer_id}/documents/{document_id}:
    delete:
      tags:
      - documents
      summary: Remove Document
      description: Remove a document link from a customer (soft delete).
      operationId: remove_document_api_v1_customers__customer_id__documents__document_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Customer Id
      - name: document_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Document Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    DocumentListResponse:
      properties:
        documents:
          items:
            $ref: '#/components/schemas/DocumentResponse'
          type: array
          title: Documents
        total:
          type: integer
          title: Total
      type: object
      required:
      - documents
      - total
      title: DocumentListResponse
      description: List of documents for a customer.
    DocumentResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        organization_id:
          type: string
          format: uuid
          title: Organization Id
        customer_id:
          type: string
          format: uuid
          title: Customer Id
        title:
          type: string
          title: Title
        document_type:
          type: string
          title: Document Type
        provider:
          type: string
          title: Provider
        provider_file_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider File Id
        file_url:
          anyOf:
          - type: string
          - type: 'null'
          title: File Url
        mime_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Mime Type
        summary:
          anyOf:
          - type: string
          - type: 'null'
          title: Summary
        summary_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Summary Status
        added_by_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Added By Id
        source_conversation_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Source Conversation Id
        source_agent_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Source Agent Id
        source_agent_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Agent Name
        source_agent_icon:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Agent Icon
        source_agent_gradient:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Agent Gradient
        file_name:
          anyOf:
          - type: string
          - type: 'null'
          title: File Name
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
      type: object
      required:
      - id
      - organization_id
      - customer_id
      - title
      - document_type
      - provider
      - created_at
      title: DocumentResponse
      description: Full document response.
    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
    DocumentCreateRequest:
      properties:
        title:
          type: string
          maxLength: 500
          minLength: 1
          title: Title
        document_type:
          type: string
          pattern: ^(proposal|sow|technical_spec|architecture|contract|other)$
          title: Document Type
          default: other
        provider:
          type: string
          title: Provider
          default: google_drive
        provider_file_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider File Id
        file_url:
          anyOf:
          - type: string
          - type: 'null'
          title: File Url
        mime_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Mime Type
      type: object
      required:
      - title
      title: DocumentCreateRequest
      description: Schema for linking a document to a customer.
    Body_upload_document_api_v1_customers__customer_id__documents_upload_post:
      properties:
        file:
          type: string
          contentMediaType: application/octet-stream
          title: File
      type: object
      required:
      - file
      title: Body_upload_document_api_v1_customers__customer_id__documents_upload_post
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer