> ## 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.

# List Cases

> Retrieve a list of cases belonging to the authenticated user, with optional exact-match label lookup.

Retrieve a list of cases belonging to the authenticated user. Cases are returned in reverse chronological order (newest first).

## Finding a case by label

Pass the optional `label` query parameter to fetch the case (or cases) whose label matches exactly. The match is case-sensitive and applies to the same access scope as the unfiltered list: you see only your own cases unless your organisation has shared cases enabled, in which case you see any matching case in the organisation.

```bash theme={null}
curl -H "x-api-key: $API_KEY" \
  "https://api.uk.veridox.ai/cases?label=Claim%20POLICY-12345"
```

A typical integration uses this to check whether a case already exists for an external reference before creating a new one, making the create-or-fetch flow safely idempotent.

## Best Practices

1. **Use List for Overview**: Use `GET /cases` for dashboards and case selection.
2. **Use Details for Specifics**: Use `GET /cases/{id}` when you need file-level information.
3. **Use Label Lookup for Idempotency**: Use `GET /cases?label=...` when you have an external reference (claim number, policy ID) and want to find or create a case by that identifier without paginating.
4. **Use Search for Discovery**: For partial or fuzzy matching across case labels and file names, use `GET /search` instead. `?label=` on this endpoint is exact-match only.
5. **Monitor Status**: Check `file_analysis_status` for processing updates.


## OpenAPI

````yaml GET /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:
    get:
      tags:
        - Cases
      summary: List all cases
      description: >-
        Returns all cases belonging to the authenticated user, including
        metadata, lock status, and file analysis status. Supports an optional
        `label` query parameter for exact-match lookup by case label (useful for
        idempotent integrations checking whether a case already exists).
      operationId: CasesController_listCases
      parameters:
        - name: limit
          required: false
          in: query
          description: Maximum number of cases to return
          x-nestjs_zod-parent-additional-properties: false
          schema:
            minimum: 1
            maximum: 100
            default: 20
            type: integer
        - name: offset
          required: false
          in: query
          description: Number of cases to skip for pagination
          x-nestjs_zod-parent-additional-properties: false
          schema:
            minimum: 0
            maximum: 9007199254740991
            default: 0
            type: integer
        - name: label
          required: false
          in: query
          x-nestjs_zod-parent-additional-properties: false
          schema:
            type: string
            minLength: 1
            maxLength: 255
      responses:
        '200':
          description: List of cases retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaseListResponseDto'
        '400':
          description: Invalid pagination or label query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        '401':
          description: Unauthorized (invalid or missing authentication token)
          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:
    CaseListResponseDto:
      type: object
      properties:
        cases:
          type: array
          items:
            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})$
              label:
                anyOf:
                  - type: string
                  - type: 'null'
              metadata:
                anyOf:
                  - type: object
                    propertyNames:
                      type: string
                    additionalProperties: {}
                  - type: 'null'
              is_locked:
                type: boolean
              locked_at:
                anyOf:
                  - 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))$
                  - type: 'null'
              file_analysis_status:
                type: string
                enum:
                  - waiting_for_file_analysis
                  - file_analysis_complete
              file_analysis_completed_at:
                anyOf:
                  - 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))$
                  - type: 'null'
              created_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))$
              updated_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))$
              team_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)$
              team_name:
                type: string
            required:
              - case_id
              - label
              - metadata
              - is_locked
              - locked_at
              - file_analysis_status
              - file_analysis_completed_at
              - created_at
              - updated_at
          x-nestjs_zod-uses-3-point-1-syntax: true
        total:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          x-nestjs_zod-uses-3-point-1-syntax: true
        limit:
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
          x-nestjs_zod-uses-3-point-1-syntax: true
        offset:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          x-nestjs_zod-uses-3-point-1-syntax: true
      required:
        - cases
        - total
        - limit
        - offset
    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

````