> ## Documentation Index
> Fetch the complete documentation index at: https://docs.watchdog.no/llms.txt
> Use this file to discover all available pages before exploring further.

# Authorize a batch of document uploads

> Accepts metadata for 1–100 files. Returns Document IDs, upload URLs, required headers and expiry in request order. The whole request is validated and all placeholders are created in one transaction. PUT each file directly to its upload_url before expires_at; no completion endpoint is needed. This creates new Documents on each request, just like single upload preparation.



## OpenAPI

````yaml /openapi-preview.json post /v1/documents/upload/batch
openapi: 3.1.0
info:
  title: Watchdog API (preview)
  version: 1.0.0
  description: >-
    Development preview for agreements, price items, document relationships,
    canonical invoices, alerts and alert topics, claims and attached alerts,
    shared entity activity and comments, Document uploads, invoice imports,
    explicit invoice-agreement matching, and workflow runs. This contract is
    under development and is not served by api.watchdog.no. Request bodies are
    limited to 2 MiB (2,097,152 bytes), including all JSON fields and line data,
    except POST /v1/support/contact which permits 32 MiB for base64 attachments.
    File bytes are uploaded directly to storage. The existing public REST
    service retains its separate contract.
servers:
  - url: http://localhost:3500
    description: Local development Worker
security: []
paths:
  /v1/documents/upload/batch:
    post:
      tags:
        - Documents
      summary: Authorize a batch of document uploads
      description: >-
        Accepts metadata for 1–100 files. Returns Document IDs, upload URLs,
        required headers and expiry in request order. The whole request is
        validated and all placeholders are created in one transaction. PUT each
        file directly to its upload_url before expires_at; no completion
        endpoint is needed. This creates new Documents on each request, just
        like single upload preparation.
      operationId: uploadDocumentsBatch
      parameters:
        - name: X-Organization-Id
          in: header
          required: false
          schema:
            type: string
          description: >-
            Required for personal API keys. Target one organization you have
            access to. Migrated keys may omit it to use their original
            organization. For Clerk sessions, it must match the active
            organization.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                entries:
                  type: array
                  items:
                    type: object
                    properties:
                      category:
                        type: string
                        enum:
                          - invoice
                          - agreement
                          - other
                      file_name:
                        type: string
                        minLength: 1
                        maxLength: 255
                      mime_type:
                        type: string
                        maxLength: 255
                        pattern: ^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$
                      file_size:
                        type: integer
                        minimum: 100
                        maximum: 52428800
                    required:
                      - file_name
                      - mime_type
                      - file_size
                    additionalProperties: false
                  minItems: 1
                  maxItems: 100
              required:
                - entries
              additionalProperties: false
      responses:
        '201':
          description: Upload capabilities in request order.
          headers:
            X-Request-Id:
              schema:
                type: string
              required: true
              description: >-
                Request identifier for support and diagnostics; also included in
                error bodies.
            Cache-Control:
              schema:
                type: string
                enum:
                  - private, no-store
              required: false
              description: >-
                Organization-scoped API responses must not be cached. May be
                absent for requests rejected before routing.
            X-RateLimit-Limit:
              schema:
                type: string
                example: '120'
              required: false
              description: >-
                Requests per minute for the applicable limiter, when evaluated.
                Authenticated requests use the credential limit; an IP rejection
                uses the IP limit.
          content:
            application/json:
              schema:
                type: object
                properties:
                  entries:
                    type: array
                    items:
                      type: object
                      properties:
                        document_id:
                          type: string
                          format: uuid
                        upload_url:
                          type: string
                          format: uri
                        headers:
                          type: object
                          additionalProperties:
                            type: string
                        expires_at:
                          type: string
                          format: date-time
                      required:
                        - document_id
                        - upload_url
                        - headers
                        - expires_at
                    minItems: 1
                    maxItems: 100
                required:
                  - entries
        '400':
          description: >-
            Invalid request format, parameters, or body. Details contain up to
            20 actionable field errors; the complete encoded request body must
            be at most 2 MiB (2,097,152 bytes).
          headers:
            X-Request-Id:
              schema:
                type: string
              required: true
              description: >-
                Request identifier for support and diagnostics; also included in
                error bodies.
            Cache-Control:
              schema:
                type: string
                enum:
                  - private, no-store
              required: false
              description: >-
                Organization-scoped API responses must not be cached. May be
                absent for requests rejected before routing.
            X-RateLimit-Limit:
              schema:
                type: string
                example: '120'
              required: false
              description: >-
                Requests per minute for the applicable limiter, when evaluated.
                Authenticated requests use the credential limit; an IP rejection
                uses the IP limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_validation_error'
              example:
                error:
                  code: validation_error
                  message: >-
                    Invalid request format, parameters, or body. Details contain
                    up to 20 actionable field errors; the complete encoded
                    request body must be at most 2 MiB (2,097,152 bytes).
                  request_id: req_example
        '401':
          description: Missing or invalid bearer credential.
          headers:
            X-Request-Id:
              schema:
                type: string
              required: true
              description: >-
                Request identifier for support and diagnostics; also included in
                error bodies.
            Cache-Control:
              schema:
                type: string
                enum:
                  - private, no-store
              required: false
              description: >-
                Organization-scoped API responses must not be cached. May be
                absent for requests rejected before routing.
            X-RateLimit-Limit:
              schema:
                type: string
                example: '120'
              required: false
              description: >-
                Requests per minute for the applicable limiter, when evaluated.
                Authenticated requests use the credential limit; an IP rejection
                uses the IP limit.
            WWW-Authenticate:
              schema:
                type: string
              required: false
              description: Bearer authentication challenge, when supplied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_invalid_token'
              example:
                error:
                  code: invalid_token
                  message: Missing or invalid bearer credential.
                  request_id: req_example
        '403':
          description: >-
            Access denied: forbidden, token_disabled, organization_required,
            insufficient_role, or mfa_required. Check the error code and
            effective permissions.
          headers:
            X-Request-Id:
              schema:
                type: string
              required: true
              description: >-
                Request identifier for support and diagnostics; also included in
                error bodies.
            Cache-Control:
              schema:
                type: string
                enum:
                  - private, no-store
              required: false
              description: >-
                Organization-scoped API responses must not be cached. May be
                absent for requests rejected before routing.
            X-RateLimit-Limit:
              schema:
                type: string
                example: '120'
              required: false
              description: >-
                Requests per minute for the applicable limiter, when evaluated.
                Authenticated requests use the credential limit; an IP rejection
                uses the IP limit.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required
              example:
                error:
                  code: forbidden
                  message: >-
                    Access denied: forbidden, token_disabled,
                    organization_required, insufficient_role, or mfa_required.
                    Check the error code and effective permissions.
                  request_id: req_example
        '429':
          description: The IP or authenticated credential exceeded its request limit.
          headers:
            X-Request-Id:
              schema:
                type: string
              required: true
              description: >-
                Request identifier for support and diagnostics; also included in
                error bodies.
            Cache-Control:
              schema:
                type: string
                enum:
                  - private, no-store
              required: false
              description: >-
                Organization-scoped API responses must not be cached. May be
                absent for requests rejected before routing.
            X-RateLimit-Limit:
              schema:
                type: string
                example: '120'
              required: false
              description: >-
                Requests per minute for the applicable limiter, when evaluated.
                Authenticated requests use the credential limit; an IP rejection
                uses the IP limit.
            Retry-After:
              schema:
                type: string
                example: '60'
              required: true
              description: Seconds to wait before retrying the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_rate_limit_exceeded'
              example:
                error:
                  code: rate_limit_exceeded
                  message: >-
                    The IP or authenticated credential exceeded its request
                    limit.
                  request_id: req_example
        '500':
          description: >-
            Unexpected server failure. Include the request ID when contacting
            support.
          headers:
            X-Request-Id:
              schema:
                type: string
              required: true
              description: >-
                Request identifier for support and diagnostics; also included in
                error bodies.
            Cache-Control:
              schema:
                type: string
                enum:
                  - private, no-store
              required: false
              description: >-
                Organization-scoped API responses must not be cached. May be
                absent for requests rejected before routing.
            X-RateLimit-Limit:
              schema:
                type: string
                example: '120'
              required: false
              description: >-
                Requests per minute for the applicable limiter, when evaluated.
                Authenticated requests use the credential limit; an IP rejection
                uses the IP limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_internal_error'
              example:
                error:
                  code: internal_error
                  message: >-
                    Unexpected server failure. Include the request ID when
                    contacting support.
                  request_id: req_example
        '503':
          description: Upload signing is temporarily unavailable.
          headers:
            X-Request-Id:
              schema:
                type: string
              required: true
              description: >-
                Request identifier for support and diagnostics; also included in
                error bodies.
            Cache-Control:
              schema:
                type: string
                enum:
                  - private, no-store
              required: false
              description: >-
                Organization-scoped API responses must not be cached. May be
                absent for requests rejected before routing.
            X-RateLimit-Limit:
              schema:
                type: string
                example: '120'
              required: false
              description: >-
                Requests per minute for the applicable limiter, when evaluated.
                Authenticated requests use the credential limit; an IP rejection
                uses the IP limit.
            Retry-After:
              schema:
                type: string
                example: '60'
              required: true
              description: Seconds to wait before retrying the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_service_unavailable'
              example:
                error:
                  code: service_unavailable
                  message: Upload signing is temporarily unavailable.
                  request_id: req_example
      security:
        - ApiKeyBearer: []
        - ClerkSessionBearer: []
components:
  schemas:
    Error_validation_error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - validation_error
            message:
              type: string
            request_id:
              type: string
            description:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - code
                  - field
                  - message
              maxItems: 20
            workflow_run_id:
              type: string
              format: uuid
            import_id:
              type: string
              format: uuid
            existing_party:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - supplier
                    - recipient
                id:
                  type: string
                  format: uuid
              required:
                - type
                - id
          required:
            - code
            - message
            - request_id
      required:
        - error
    Error_invalid_token:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - invalid_token
            message:
              type: string
            request_id:
              type: string
            description:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - code
                  - field
                  - message
              maxItems: 20
            workflow_run_id:
              type: string
              format: uuid
            import_id:
              type: string
              format: uuid
            existing_party:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - supplier
                    - recipient
                id:
                  type: string
                  format: uuid
              required:
                - type
                - id
          required:
            - code
            - message
            - request_id
      required:
        - error
    Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - forbidden
                - token_disabled
                - organization_required
                - insufficient_role
                - mfa_required
            message:
              type: string
            request_id:
              type: string
            description:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - code
                  - field
                  - message
              maxItems: 20
            workflow_run_id:
              type: string
              format: uuid
            import_id:
              type: string
              format: uuid
            existing_party:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - supplier
                    - recipient
                id:
                  type: string
                  format: uuid
              required:
                - type
                - id
          required:
            - code
            - message
            - request_id
      required:
        - error
    Error_rate_limit_exceeded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - rate_limit_exceeded
            message:
              type: string
            request_id:
              type: string
            description:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - code
                  - field
                  - message
              maxItems: 20
            workflow_run_id:
              type: string
              format: uuid
            import_id:
              type: string
              format: uuid
            existing_party:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - supplier
                    - recipient
                id:
                  type: string
                  format: uuid
              required:
                - type
                - id
          required:
            - code
            - message
            - request_id
      required:
        - error
    Error_internal_error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - internal_error
            message:
              type: string
            request_id:
              type: string
            description:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - code
                  - field
                  - message
              maxItems: 20
            workflow_run_id:
              type: string
              format: uuid
            import_id:
              type: string
              format: uuid
            existing_party:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - supplier
                    - recipient
                id:
                  type: string
                  format: uuid
              required:
                - type
                - id
          required:
            - code
            - message
            - request_id
      required:
        - error
    Error_service_unavailable:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - service_unavailable
            message:
              type: string
            request_id:
              type: string
            description:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - code
                  - field
                  - message
              maxItems: 20
            workflow_run_id:
              type: string
              format: uuid
            import_id:
              type: string
              format: uuid
            existing_party:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - supplier
                    - recipient
                id:
                  type: string
                  format: uuid
              required:
                - type
                - id
          required:
            - code
            - message
            - request_id
      required:
        - error
  securitySchemes:
    ApiKeyBearer:
      type: http
      scheme: bearer
      description: >-
        Personal API key. Send X-Organization-Id. The required cumulative level
        is listed in x-watchdog-permission.
    ClerkSessionBearer:
      type: http
      scheme: bearer
      description: Clerk session with an active organization.

````