DocImprint Collections API

openapi: 3.2.0
info:
  title: DocImprint Collections API
  version: 1.0.0
  description: Verifiable document intelligence for AI agents. Extract, summarize, translate, or fact-check any URL or document. Responses include cryptographic evidence bundles with on-chain attestation. Pay per call in USDC via x402 or use an API key.
servers:
- url: https://api.docimprint.com
security:
- ApiKeyAuth:
  - read
  - write
- ApiKeyHeader:
  - read
  - write
tags:
- name: Collections
paths:
  /v1/collections:
    post:
      summary: Create a document collection
      operationId: createCollection
      responses:
        '201':
          description: '{ collection_id, name }'
      tags:
      - Collections
    get:
      summary: List collections for wallet
      operationId: listCollections
      parameters:
      - $ref: '#/components/parameters/PaymentSignature'
      responses:
        '200':
          description: '{ collections[] }'
        '401':
          $ref: '#/components/responses/WalletRequired'
      tags:
      - Collections
  /v1/collections/{id}/search:
    get:
      summary: Semantic search within a collection
      operationId: searchCollection
      parameters:
      - $ref: '#/components/parameters/PaymentSignature'
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: q
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Ranked chunk results
      tags:
      - Collections
  /v1/collections/{id}:
    get:
      summary: Get collection details by ID
      operationId: getCollection
      parameters:
      - $ref: '#/components/parameters/PaymentSignature'
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Collection record
      tags:
      - Collections
  /v1/collections/{id}/documents:
    post:
      summary: Add a document bundle to a collection for indexing
      operationId: addCollectionDocument
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - bundle_id
              properties:
                bundle_id:
                  type: string
                  description: Evidence bundle ID to index
      responses:
        '200':
          description: '{ success: true, bundle_id, status }'
      tags:
      - Collections
  /v1/collections/{id}/documents/{bundleId}:
    delete:
      summary: Remove a document from a collection
      operationId: removeCollectionDocument
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: bundleId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '{ success: true, bundle_id, removed: true }'
      tags:
      - Collections
  /v1/collections/{id}/documents/{bundleId}/reindex:
    post:
      summary: Re-index a document in a collection
      operationId: reindexCollectionDocument
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: bundleId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '{ success: true, bundle_id, status: "indexing" }'
      tags:
      - Collections
  /v1/collections/{id}/ask:
    post:
      summary: Cross-document QA with citations
      operationId: askCollection
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Answer with sources and retrieval
      tags:
      - Collections
components:
  responses:
    WalletRequired:
      description: '{ error: "Wallet identity required", code: "WALLET_REQUIRED", hint: "Pay-per-call (x402): payment-signature from your POST payment. Subscription: Authorization Bearer dr_live_..." }'
  parameters:
    PaymentSignature:
      name: payment-signature
      in: header
      required: false
      schema:
        type: string
      description: Verified x402 payment authorization (base64 JSON from the x402 protocol). Required on owner-scoped GET/DELETE when not using an API key. Must correspond to the payer that created the resource. X-Wallet-Address is deprecated and ignored.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Bearer dr_live_... (or use X-API-Key header). Scopes: read (GET), write (POST/PUT/DELETE), admin (admin endpoints). Create keys at https://docimprint.com/pricing or via admin API.'
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Alternative to Authorization: Bearer header. Scopes same as ApiKeyAuth.'