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

# Create Case

> Create a new case for document analysis with optional file placeholders.

A case acts as a container for documents that need to be analysed together. You can create a case with or without file placeholders.

**With file placeholders:** Pre-define expected files and get upload URLs immediately.
**Without file placeholders:** Create case first, then add files later.

<Warning>
  **Important:** Cases are designed for single-batch file uploads. Once you begin uploading files, the case locks to ensure complete analysis. Plan to upload all your files together.
</Warning>

## Best Practices

1. **Descriptive Labels**: Use clear, descriptive case labels like claim numbers or policy numbers for easy identification.
2. **Unique Labels (Case-Insensitive)**: Case labels must be unique per user regardless of letter casing. Creating a case with a label that only differs by case will return a `409 Conflict` response.
3. **File Planning**: Pre-define expected files when possible to get upload URLs immediately.
4. **Batch Operations**: Create cases in advance for high-volume processing.


## OpenAPI

````yaml POST /cases
openapi: 3.1.0
info:
  title: Veridox Core API
  description: Veridox Core Platform API
  version: 0.0.1
  contact: {}
servers:
  - url: https://api.uk.veridox.ai
    description: Live (UK)
  - url: https://api.ca.veridox.ai
    description: Live (CA)
security: []
tags:
  - name: Status
    description: System status and health check endpoints
  - name: Cases
    description: Case and case file management
  - name: Organisations
    description: Organisation management
  - name: Document Requests
    description: Document request management
  - name: Search
    description: Search functionality
  - name: Admin
    description: Administrative endpoints
paths:
  /cases:
    post:
      tags:
        - Cases
      summary: Create a new case or add files to an existing one
      description: >-
        Creates a new case for the authenticated user, or adds files to an
        existing case via label-upsert. If file_labels are provided, SAS upload
        URLs are generated. If the label matches an existing case owned by the
        user and existing_case_id is not provided, a 409 label-conflict-creator
        is returned with the existing case ID so the client can confirm intent.
        Re-submit with existing_case_id to add files to the existing case. If
        existing_case_id is provided but belongs to a different user or does not
        exist, a 404 is returned. label-case-mismatch (400) only fires when
        existing_case_id refers to a case owned by the caller. current_context
        is creation-only and is silently ignored on the existing-case reuse
        path.
      operationId: CasesController_createCase
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCaseDto'
      responses:
        '201':
          description: Case created or files added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCaseResponseDto'
        '400':
          description: >-
            Invalid input, or existing_case_id belongs to the caller but the
            label does not match that case (label-case-mismatch)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        '401':
          description: Unauthorized (invalid or missing authentication token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        '403':
          description: >-
            current_context was provided but the case-context feature flag is
            not enabled for the organisation (not applicable on the
            existing-case reuse path, where context is always ignored)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        '404':
          description: existing_case_id does not exist or belongs to a different user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        '409':
          description: >-
            Label already exists for this user. Returns label-conflict-creator
            with the existing case ID; re-submit with existing_case_id to
            confirm adding files to it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        '429':
          description: Too many requests (rate limit exceeded)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
      security:
        - api-key: []
components:
  schemas:
    CreateCaseDto:
      type: object
      properties:
        label:
          type: string
          minLength: 1
          maxLength: 255
        file_labels:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 255
        existing_case_id:
          type: string
          format: uuid
          pattern: >-
            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        current_context:
          type: string
          minLength: 1
          maxLength: 2000
      required:
        - label
    CreateCaseResponseDto:
      type: object
      properties:
        case_id:
          type: string
          format: uuid
          pattern: >-
            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
        is_locked:
          type: boolean
        files:
          type: array
          items:
            type: object
            properties:
              file_id:
                type: string
                format: uuid
                pattern: >-
                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
              label:
                type: string
              sas_url:
                type: string
                format: uri
              expires_at:
                type: string
                format: date-time
                pattern: >-
                  ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
            required:
              - file_id
              - label
              - sas_url
              - expires_at
        stream_url:
          type: string
      required:
        - case_id
        - is_locked
        - stream_url
    ErrorDto:
      type: object
      properties:
        error_code:
          type: string
          description: Machine-readable error code for programmatic handling
          examples:
            - request.cases.file.missing-risk-score
            - request.authentication.invalid-token
            - request.forbidden
            - request.cases.case.not-found
            - request.cases.case.already-locked
        error_message:
          type: string
          description: Human-readable error message explaining what went wrong
          example: >-
            User tried to perform an invalid operation on a file without a risk
            score.
        error_details:
          type: object
          example:
            field: email_address
      required:
        - error_code
        - error_message
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: x-api-key

````