Conxai documents API

openapi: 3.0.0
info:
  description: Customer API provide base methods for create company, projects, users, add users to projects, end etc.
  title: Customer annotations documents API
  termsOfService: http://swagger.io/terms/
  contact:
    name: Dmytro Kabachenko
    email: dmytro.kabachenko@conxai.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: '1.0'
servers:
- url: //customer.conxai.ai
tags:
- name: documents
paths:
  /projects/{projectId}/use-cases/{useCaseId}/document-types/{documentTypeId}:
    post:
      security:
      - BearerAuth: []
      description: This endpoint provides a presigned URL for clients to upload a document or image directly to an S3 bucket. In the follow-up PUT request to the presigned URL the file should be the raw binary body of the request. It is important to resend the Content-Type header as well as the Content-Disposition header including the original filename. PNGs and JPGs will be considered a single page document and PDFs will be split into pages.
      tags:
      - documents
      summary: Upload a document
      parameters:
      - description: Unique id of the project.
        name: projectId
        in: path
        required: true
        schema:
          type: string
      - description: Unique id of the use case.
        name: useCaseId
        in: path
        required: true
        schema:
          type: string
      - description: Unique id of the document type id.
        name: documentTypeId
        in: path
        required: true
        schema:
          type: string
      - description: Content-Type of the document file. Must be application/pdf, image/png or image/jpeg
        name: Content-Type
        in: header
        required: true
        schema:
          type: string
      - description: Content-Disposition of the document file. Must be attachment; filename=<filename>
        name: Content-Disposition
        in: header
        required: true
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/conxai_com_docs-api_structures_api.PostCreateDocumentRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conxai_com_docs-api_structures_api.CreateDocumentResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: string
  /projects/{projectId}/use-cases/{useCaseId}/document-types/{documentTypeId}/samples/{sampleId}/validated:
    put:
      security:
      - BearerAuth: []
      description: Load validated document
      tags:
      - documents
      summary: Load validated document
      parameters:
      - description: Project UUID
        name: projectId
        in: path
        required: true
        schema:
          type: string
      - description: Use Case Id
        name: useCaseId
        in: path
        required: true
        schema:
          type: string
      - description: Document Type Id
        name: documentTypeId
        in: path
        required: true
        schema:
          type: string
      - description: Sample Id
        name: sampleId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/conxai_com_docs-api_structures_api.PutDocumentValidated'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conxai_com_docs-api_structures_api.PutDocumentValidated'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: felt bad
          content:
            application/json:
              schema:
                type: string
  /projects/{projectId}/use-cases/{useCaseId}/document-types/{documentTypeId}/status-list:
    post:
      security:
      - BearerAuth: []
      description: Return sample loading and splitting status
      tags:
      - documents
      summary: Get sample status list
      parameters:
      - description: Project UUID
        name: projectId
        in: path
        required: true
        schema:
          type: string
      - description: Use Case Id
        name: useCaseId
        in: path
        required: true
        schema:
          type: string
      - description: Document Type Id
        name: documentTypeId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/api_documents_handlers.MultiFileStatusRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/api_documents_handlers.FileStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: felt bad
          content:
            application/json:
              schema:
                type: string
        '504':
          description: Splitter waiting timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /projects/{projectId}/use-cases/{useCaseId}/document-types/{documentTypeId}/{fileId}/status:
    get:
      security:
      - BearerAuth: []
      description: Return sample loading and splitting status
      tags:
      - documents
      summary: Get sample status
      parameters:
      - description: Project UUID
        name: projectId
        in: path
        required: true
        schema:
          type: string
      - description: Use Case Id
        name: useCaseId
        in: path
        required: true
        schema:
          type: string
      - description: Document Type Id
        name: documentTypeId
        in: path
        required: true
        schema:
          type: string
      - description: File Id
        name: fileId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conxai_com_docs-api_structures_api.GetDocumentStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: felt bad
          content:
            application/json:
              schema:
                type: string
        '504':
          description: Splitter waiting timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /projects/{projectId}/use-cases/{useCaseId}/documents:
    get:
      security:
      - BearerAuth: []
      description: 'Retrieves a list of documents for a specific use case within a standard project. Returns document metadata including page status, document type information, and processing status. The response includes training sync status (is_training_version_synced) which can be: nil (samples not copied), true (synced and up-to-date), or false (synced but not latest version). This endpoint is used for standard projects (non-master projects) to fetch document information.'
      tags:
      - documents
      summary: Get documents for standard project
      parameters:
      - description: Standard project UUID (must not start with '00')
        name: projectId
        in: path
        required: true
        schema:
          type: string
      - description: Use case UUID
        name: useCaseId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Empty array when no documents found
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '404':
          description: Project or use case not found
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: string
    post:
      security:
      - BearerAuth: []
      description: This endpoint provides a presigned URL for clients to upload a document or image directly to an S3 bucket. In the follow-up PUT request to the presigned URL the file should be the raw binary body of the request. It is important to resend the Content-Type header as well as the Content-Disposition header including the original filename. PNGs and JPGs will be considered a single page document and PDFs will be split into pages.
      tags:
      - documents
      summary: Upload a document to standard project
      parameters:
      - description: Unique id of the project.
        name: projectId
        in: path
        required: true
        schema:
          type: string
      - description: Unique id of the use case.
        name: useCaseId
        in: path
        required: true
        schema:
          type: string
      - description: Content-Type of the document file. Must be application/pdf, image/png or image/jpeg
        name: Content-Type
        in: header
        required: true
        schema:
          type: string
      - description: Content-Disposition of the document file. Must be attachment; filename=<filename>
        name: Content-Disposition
        in: header
        required: true
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/conxai_com_docs-api_structures_api.PostCreateDocumentRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conxai_com_docs-api_structures_api.CreateDocumentResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: string
    delete:
      security:
      - BearerAuth: []
      description: Delete all documents in a use case. Documents are deleted in parallel using a goroutine pool.
      tags:
      - documents
      summary: Delete all documents in a use case
      parameters:
      - description: Project UUID
        name: projectId
        in: path
        required: true
        schema:
          type: string
      - description: Use Case Id
        name: useCaseId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conxai_com_docs-api_structures_api.PostUseCaseFinishProcessingResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: string
  /projects/{projectId}/use-cases/{useCaseId}/documents/bulk-delete:
    post:
      security:
      - BearerAuth: []
      description: 'Delete multiple documents by ID in parallel. Errors per document are captured in the response but do not interrupt other deletions.

        Example response: [{"a1b2c3d4-e5f6-7890-abcd-ef1234567890": {"status": "deleted"}}, {"b2c3d4e5-f6a7-8901-bcde-f12345678901": {"status": "error", "message": "failed to delete S3 files"}}]'
      tags:
      - documents
      summary: Bulk delete documents
      parameters:
      - description: Project UUID
        name: projectId
        in: path
        required: true
        schema:
          type: string
      - description: Use Case Id
        name: useCaseId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/conxai_com_docs-api_structures_api.BulkDocumentRequest'
        description: List of document IDs to delete
        required: true
      responses:
        '200':
          description: Per-document delete results
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties:
                    $ref: '#/components/schemas/conxai_com_docs-api_structures_api.BulkDocumentOperationStatus'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: string
  /projects/{projectId}/use-cases/{useCaseId}/documents/bulk-process:
    post:
      security:
      - BearerAuth: []
      description: 'Trigger reprocessing for multiple documents in parallel. Processing is always asynchronous (fire-and-forget). Errors per document are captured in the response but do not interrupt other documents_handlers.

        Example response: [{"a1b2c3d4-e5f6-7890-abcd-ef1234567890": {"status": "processing"}}, {"b2c3d4e5-f6a7-8901-bcde-f12345678901": {"status": "error", "message": "failed to send cloud event"}}]'
      tags:
      - documents
      summary: Bulk reprocess documents
      parameters:
      - description: Project UUID
        name: projectId
        in: path
        required: true
        schema:
          type: string
      - description: Use Case Id
        name: useCaseId
        in: path
        required: true
        schema:
          type: string
      - description: Remove all result, draft and validated files before reprocessing
        name: reset
        in: query
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/conxai_com_docs-api_structures_api.BulkDocumentRequest'
        description: List of document IDs to reprocess
        required: true
      responses:
        '200':
          description: Per-document processing results
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties:
                    $ref: '#/components/schemas/conxai_com_docs-api_structures_api.BulkDocumentOperationStatus'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: string
  /projects/{projectId}/use-cases/{useCaseId}/documents/{documentId}:
    delete:
      security:
      - BearerAuth: []
      description: Delete document standard project
      tags:
      - documents
      summary: Delete document standard project
      parameters:
      - description: Project UUID
        name: projectId
        in: path
        required: true
        schema:
          type: string
      - description: Use Case Id
        name: useCaseId
        in: path
        required: true
        schema:
          type: string
      - description: Document Id
        name: documentId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: "Server\tfelt bad"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /projects/{projectId}/use-cases/{useCaseId}/documents/{documentId}/download:
    get:
      security:
      - BearerAuth: []
      description: Returns a presigned download link for the original document or a generated PDF with markups/bounding boxes.
      tags:
      - documents
      summary: Download document (original or with markups)
      parameters:
      - description: Project UUID
        name: projectId
        in: path
        required: true
        schema:
          type: string
      - description: Use Case Id
        name: useCaseId
        in: path
        required: true
        schema:
          type: string
      - description: Document Id
        name: documentId
        in: path
        required: true
        schema:
          type: string
      - description: If true, includes markups in the generated PDF. Default is false.
        name: markup
        in: query
        schema:
          type: boolean
      - description: If true, includes bounding boxes in the generated PDF. Default is false.
        name: boundingbox
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conxai_com_docs-api_structures_api.DownloadLinkResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: string
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: string
  /projects/{projectId}/use-cases/{useCaseId}/documents/{documentId}/download-link:
    get:
      security:
      - BearerAuth: []
      tags:
      - documents
      summary: Get presigned download link for original document (standard project)
      parameters:
      - description: Project UUID
        name: projectId
        in: path
        required: true
        schema:
          type: string
      - description: Use Case Id
        name: useCaseId
        in: path
        required: true
        schema:
          type: string
      - description: Document Id
        name: documentId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conxai_com_docs-api_structures_api.DownloadLinkResponse'
  /projects/{projectId}/use-cases/{useCaseId}/documents/{documentId}/finish:
    post:
      security:
      - BearerAuth: []
      description: Finish document processing by validating all pages. This will copy draft files (if they exist) or result files to validated files, prioritizing user edits over AI results.
      tags:
      - documents
      summary: Finish document processing by validating all pages
      parameters:
      - description: Project UUID
        name: projectId
        in: path
        required: true
        schema:
          type: string
      - description: Use Case Id
        name: useCaseId
        in: path
        required: true
        schema:
          type: string
      - description: Document Type Id
        name: documentId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: string
        '500':
          description: felt bad
          content:
            application/json:
              schema:
                type: string
  /projects/{projectId}/use-cases/{useCaseId}/documents/{documentId}/markup/{pageIndex}:
    get:
      security:
      - BearerAuth: []
      description: Retrieve markup data for a specific page of a document
      tags:
      - documents
      summary: Get markup data for a document page
      parameters:
      - description: Project UUID
        name: projectId
        in: path
        required: true
        schema:
          type: string
      - description: Use Case Id
        name: useCaseId
        in: path
        required: true
        schema:
          type: string
      - description: Document Id
        name: documentId
        in: path
        required: true
        schema:
          type: string
      - description: Page Index
        name: pageIndex
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      security:
      - BearerAuth: []
      description: Store markup data for a specific page of a document
      tags:
      - documents
      summary: Store markup data for a document page
      parameters:
      - description: Project UUID
        name: projectId
        in: path
        required: true
        schema:
          type: string
      - description: Use Case Id
        name: useCaseId
        in: path
        required: true
        schema:
          type: string
      - description: Document Id
        name: documentId
        in: path
        required: true
        schema:
          type: string
      - description: Page Index
        name: pageIndex
        in: path
        required: true
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/Request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conxai_com_docs-api_api_shared_handlers.StatusOkStruct'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /projects/{projectId}/use-cases/{useCaseId}/documents/{documentId}/page-dimensions:
    get:
      security:
      - BearerAuth: []
      description: Receive page dimensions for a document with optional pagination.
      tags:
      - documents
      summary: Get document page dimensions
      parameters:
      - description: Project UUID
        name: projectId
        in: path
        required: true
        schema:
          type: string
      - description: Use Case Id
        name: useCaseId
        in: path
        required: true
        schema:
          type: string
      - description: Document Id
        name: documentId
        in: path
        required: true
        schema:
          type: string
      - description: Pagination offset
        name: offset
        in: query
        schema:
          type: integer
      - description: Pagination limit (0 or omitted returns all pages)
        name: limit
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conxai_com_docs-api_structures_api.GetPageDimensionsResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conxai_com_docs-api_structures_api.GetPageDimensionsResponse'
        '500':
          description: felt bad
          content:
            application/json:
              schema:
                type: string
  /projects/{projectId}/use-cases/{useCaseId}/documents/{documentId}/pages:
    get:
      security:
      - BearerAuth: []
      description: Receive a list of document pages with proper status and prediction structure.
      tags:
      - documents
      summary: Get document pages
      parameters:
      - description: Project UUID
        name: projectId
        in: path
        required: true
        schema:
          type: string
      - description: Use Case Id
        name: useCaseId
        in: path
        required: true
        schema:
          type: string
      - description: Document Id
        name: documentId
        in: path
        required: true
        schema:
          type: string
      - description: Pagination offset
        name: offset
        in: query
        schema:
          type: integer
      - description: Pagination limit
        name: limit
        in: query
        schema:
          type: integer
      - description: Set false to turn off predictions
        name: predictions
        in: query
        schema:
          type: boolean
      - description: Set false to turn off pages
        name: pages
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conxai_com_docs-api_structures_api.GetDocumentPagesResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conxai_com_docs-api_structures_api.GetDocumentPagesResponse'
        '500':
          description: felt bad
          content:
            application/json:
              schema:
                type: string
  /projects/{projectId}/use-cases/{useCaseId}/documents/{documentId}/pages/{pageNum}:
    get:
      security:
      - BearerAuth: []
      description: Receive an individual document page with proper status and prediction structure.
      tags:
      - documents
      summary: Get document page
      parameters:
      - description: Project UUID
        name: projectId
        in: path
        required: true
        schema:
          type: string
      - description: Use Case Id
        name: useCaseId
        in: path
        required: true
        schema:
          type: string
      - description: Document Id
        name: documentId
        in: path
        required: true
        schema:
          type: string
      - description: Page number
        name: pageNum
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conxai_com_docs-api_structures_api.DocumentPage'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conxai_com_docs-api_structures_api.DocumentPage'
        '500':
          description: felt bad
          content:
            application/json:
              schema:
                type: string
    put:
      security:
      - BearerAuth: []
      description: Update validated document by page
      tags:
      - documents
      summary: Update validated document by page
      parameters:
      - description: Project UUID
        name: projectId
        in: path
        required: true
        schema:
          type: string
      - description: Use Case Id
        name: useCaseId
        in: path
        required: true
        schema:
          type: string
      - description: Document Id
        name: documentId
        in: path
        required: true
        schema:
          type: string
      - description: Page Num
        name: pageNum
        in: path
        required: true
        schema:
          type: string
      - description: Finalize all pages, will create empty validated files
        name: finalize
        in: query
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/conxai_com_docs-api_structures_api.ValidatedPageTableRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conxai_com_docs-api_api_shared_handlers.StatusOkStruct'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: felt bad
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /projects/{projectId}/use-cases/{useCaseId}/documents/{documentId}/pages/{pageNum}/draft:
    put:
      security:
      - BearerAuth: []
      description: Update draft document by page
      tags:
      - documents
      summary: Update draft document by page
      parameters:
      - description: Project UUID
        name: projectId
        in: path
        required: true
        schema:
          type: string
      - description: Use Case Id
        name: useCaseId
        in: path
        required: true
        schema:
          type: string
      - description: Document Id
        name: documentId
        in: path
        required: true
        schema:
          type: string
      - description: Page Num
        name: pageNum
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/conxai_com_docs-api_structures_api.ValidatedPageTableRequest'
        description: Draft document request body
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conxai_com_docs-api_api_shared_handlers.StatusOkStruct'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: felt bad
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /projects/{projectId}/use-cases/{useCaseId}/documents/{documentId}/pages/{pageNum}/validated:
    put:
      security:
      - BearerAuth: []
      description: Load standard project validated document
      tags:
      - documents
      summary: Load standard project validated document
      parameters:
      - description: Project UUID
        name: projectId
        in: path
        required: true
        schema:
          type: string
      - description: Use Case Id
        name: useCaseId
        in: path
        required: true
        schema:
          type: string
      - description: Document Id
        name: documentId
        in: path
        required: true
        schema:
          type: string
      - description: Page number
        name: pageNum
        in: path
        required: true
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBod

# --- truncated at 32 KB (58 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/conxai/refs/heads/main/openapi/conxai-documents-api-openapi.yml