# Generated from openapi.json by scripts/sync-spec.js; do not edit
openapi: 3.1.0
info:
  title: eCourtDate Electronic Warrants API
  version: 1.0.0
  summary: Draft, submit, route, and sign electronic warrant applications, with a complete audit trail.
  description: |-
    The eCourtDate Electronic Warrants API is the programmatic interface to the
    eCourtDate electronic warrant workflow: applications are drafted from a
    template, submitted for review, routed to a judge, and signed or rejected,
    with every action written to an immutable audit trail.

    ## Base URL

    ```
    https://api.warrants.ecourtdate.com/v1
    ```

    ## Authentication

    Every authenticated request carries an API key in the `x-api-key` header.
    Keys are issued per agency and carry scopes; the required scope is listed on
    each operation. Write operations also require `X-On-Behalf-Of`, naming the
    person the call is made for, which is recorded in the audit trail.

    ```
    x-api-key: $API_KEY
    X-On-Behalf-Of: judge.alvarez@example.gov
    ```

    The endpoints tagged **Public** back public warrant links and take no key.

    ## Errors

    Every error returns the same envelope with a stable `code`:

    ```json
    {
      "error": {
        "message": "Warrant application not found.",
        "type": "invalid_request_error",
        "code": "not_found",
        "param": null,
        "request_id": "req_01HZY5R2K3Q9"
      }
    }
    ```

    The full registry is in the [errors guide](https://docs.warrants.ecourtdate.com/guides/errors).

    ## Conventions

    Identifiers are UUIDs, timestamps are RFC 3339 in UTC, and list endpoints
    page with `skip` and `limit`. Warrant contents are encrypted at rest and
    decrypted only for callers entitled to read them.
  termsOfService: https://docs.warrants.ecourtdate.com/terms
servers:
  - url: https://api.warrants.ecourtdate.com
    description: Production
security:
  - apiKeyAuth: []
tags:
  - name: Warrants
    description: "Warrant applications: create, read, update, and list them, and find the judges an application can be routed to. The workflow transitions live under Warrant workflow."
  - name: Warrant workflow
    description: "The state transitions a warrant application moves through: submit for review, sign, reject, reopen a rejected application, route it to a judge, and set priority, visibility, or trash state."
  - name: Comments
    description: The comment thread on a warrant application, including internal comments that are hidden from the applicant.
  - name: Locks
    description: Advisory edit locks that stop two people from editing the same warrant application at once.
  - name: Templates
    description: "Warrant form definitions: the elements an application collects and the workflow rules that apply to it."
  - name: Document styles
    description: The page styles available when a warrant document is rendered.
  - name: Files
    description: Attachments on warrant applications, uploaded directly to storage with a presigned URL and then confirmed.
  - name: Locations
    description: Facilities, courts, and other places an agency refers to from a warrant application.
  - name: Users
    description: The people in an agency and the role each of them holds.
  - name: Roles
    description: Built-in and custom roles, and the catalog of permissions a custom role can grant.
  - name: Agency settings
    description: Agency-wide configuration for the warrant workflow.
  - name: Audit
    description: "The audit trail: every action taken on a warrant application, by whom, and when."
  - name: Public
    description: Unauthenticated endpoints that back public warrant links. They take no API key and expose only what an agency has chosen to publish.
  - name: Status
    description: Service liveness.
paths:
  /health:
    get:
      operationId: getHealth
      summary: Service health
      description: Liveness probe. Takes no API key. A `200` means the service is up; it does not assert that every dependency is healthy.
      tags:
        - Status
      security: []
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema: {}
              example: {}
          headers:
            RateLimit-Limit: &a1
              description: Requests permitted in the current window.
              schema:
                type: integer
              example: 600
            RateLimit-Remaining: &a2
              description: Requests left in the current window.
              schema:
                type: integer
              example: 597
            RateLimit-Reset: &a3
              description: Seconds until the current window resets.
              schema:
                type: integer
              example: 42
            X-Request-ID: &a4
              description: Identifier for this request, for support and log correlation.
              schema:
                type: string
              example: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/audit/logs:
    get:
      operationId: listAuditLogs
      summary: List audit entries
      description: Lists audit entries, newest first, filtered by `action`, `resource_type`, `user_id`, or `warrant_id`. Every state-changing call in this API writes one.
      tags:
        - Audit
      parameters:
        - name: action
          in: query
          required: false
          schema:
            anyOf:
              - $ref: "#/components/schemas/AuditAction"
              - type: "null"
            title: Action
          description: Filter by audit action.
          example: CREATE
        - name: resource_type
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            title: Resource Type
          description: Filter by the kind of resource the entry refers to.
          example: warrant
        - name: user_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: uuid
              - type: "null"
            title: User Id
          description: Filter to actions taken by one person.
          example: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
        - name: warrant_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: uuid
              - type: "null"
            title: Warrant Id
          description: Filter to one warrant application.
          example: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
        - name: skip
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
            title: Skip
          description: Number of records to skip. Use with `limit` to page through results.
          example: 0
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 500
            minimum: 1
            default: 100
            title: Limit
          description: Maximum number of records to return.
          example: 50
      x-scope: audit:read
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AuditLogEntry"
                title: Response List Audit Logs V1 Audit Logs Get
              example:
                - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                  agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                  user_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                  warrant_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                  action: CREATE
                  resource_type: warrant
                  resource_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                  details: &a5
                    from: SUBMITTED
                    to: SIGNED
                  ip_address: 198.51.100.24
                  user_agent: eCourtDate-Integration/1.4 (+https://example.gov)
                  created_at: 2026-08-19T14:32:07Z
                  user_name: Hon. Maria Alvarez
                  user_email: judge.alvarez@example.gov
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/audit/logs/{logId}:
    get:
      operationId: getAuditLog
      summary: Retrieve an audit entry
      description: Returns one audit entry, including the actor, the resource, and the request context recorded with it.
      tags:
        - Audit
      parameters:
        - name: logId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Log Id
          description: The log id.
          example: d61f9a37-5b28-4c40-9e13-7a4c8d2f6b95
      x-scope: audit:read
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuditLogEntry"
              example:
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                user_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                warrant_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                action: CREATE
                resource_type: warrant
                resource_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                details: *a5
                ip_address: 198.51.100.24
                user_agent: eCourtDate-Integration/1.4 (+https://example.gov)
                created_at: 2026-08-19T14:32:07Z
                user_name: Hon. Maria Alvarez
                user_email: judge.alvarez@example.gov
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/audit/users/{userId}:
    get:
      operationId: listUserActivity
      summary: List a user's activity
      description: The audit entries written by one person, newest first.
      tags:
        - Audit
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: User Id
          description: Filter to actions taken by one person.
          example: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
        - name: skip
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
            title: Skip
          description: Number of records to skip. Use with `limit` to page through results.
          example: 0
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 500
            minimum: 1
            default: 100
            title: Limit
          description: Maximum number of records to return.
          example: 50
      x-scope: audit:read
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AuditLogEntry"
                title: Response Get User Activity V1 Audit Users  User Id  Get
              example:
                - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                  agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                  user_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                  warrant_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                  action: CREATE
                  resource_type: warrant
                  resource_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                  details: *a5
                  ip_address: 198.51.100.24
                  user_agent: eCourtDate-Integration/1.4 (+https://example.gov)
                  created_at: 2026-08-19T14:32:07Z
                  user_name: Hon. Maria Alvarez
                  user_email: judge.alvarez@example.gov
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/audit/warrants/{warrantId}:
    get:
      operationId: listWarrantHistory
      summary: List a warrant's history
      description: The complete history of one warrant application in order, from creation through every transition to its current state.
      tags:
        - Audit
      parameters:
        - name: warrantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Warrant Id
          description: Filter to one warrant application.
          example: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
      x-scope: audit:read
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AuditLogEntry"
                title: Response Get Warrant Audit History V1 Audit Warrants  Warrant Id  Get
              example:
                - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                  agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                  user_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                  warrant_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                  action: CREATE
                  resource_type: warrant
                  resource_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                  details: *a5
                  ip_address: 198.51.100.24
                  user_agent: eCourtDate-Integration/1.4 (+https://example.gov)
                  created_at: 2026-08-19T14:32:07Z
                  user_name: Hon. Maria Alvarez
                  user_email: judge.alvarez@example.gov
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/document-styles:
    get:
      operationId: listDocumentStyles
      summary: List document styles
      description: Lists the page styles a template can render with, such as page size and margins.
      tags:
        - Document styles
      x-scope: templates:read
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/DocumentStyle"
                title: Response List Document Styles V1 Document Styles Get
              example:
                - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                  slug: ew-2026-004182-f3a91c
                  name: Emergency Detention (Form MH-101)
                  description: Statutory emergency detention application used by hospital staff.
                  agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                  css: "@page { size: letter; margin: 0.75in; }"
                  is_active: true
                  is_system: false
                  created_at: 2026-08-19T14:32:07Z
                  updated_at: 2026-08-19T15:04:51Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/files:
    get:
      operationId: listFiles
      summary: List attachments
      description: Lists confirmed attachments, optionally filtered to one resource with `resource_type` and `resource_id`.
      tags:
        - Files
      parameters:
        - name: resource_type
          in: query
          required: false
          schema:
            anyOf:
              - $ref: "#/components/schemas/FileResourceType"
              - type: "null"
            title: Resource Type
          description: Filter by the kind of resource the entry refers to.
          example: SIGNATURE
        - name: resource_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: uuid
              - type: "null"
            title: Resource Id
          description: Filter to one resource.
          example: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
        - name: skip
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
            title: Skip
          description: Number of records to skip. Use with `limit` to page through results.
          example: 0
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 200
            minimum: 1
            default: 50
            title: Limit
          description: Maximum number of records to return.
          example: 50
      x-scope: files:read
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FileList"
              example:
                files:
                  - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    original_filename: physician-certificate.pdf
                    content_type: application/pdf
                    file_size: 284913
                    resource_type: SIGNATURE
                    resource_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    download_url: https://files.warrants.ecourtdate.com/agencies/4f0c9d2e/warrants/9d2b6e14/physician-certificate.pdf?expires=1755616800&signature=…
                    uploaded_by: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    created_at: 2026-08-19T14:32:07Z
                total: 3
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/files/{fileId}:
    get:
      operationId: getFile
      summary: Retrieve an attachment
      description: Returns the attachment record together with a short-lived download URL. Fetching the URL is recorded in the audit trail.
      tags:
        - Files
      parameters:
        - name: fileId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: File Id
          description: The file id.
          example: 51d3c8a4-9e2b-4d17-a6f0-3b8c5e1f7d29
      x-scope: files:read
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/File"
              example:
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                original_filename: physician-certificate.pdf
                content_type: application/pdf
                file_size: 284913
                resource_type: SIGNATURE
                resource_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                download_url: https://files.warrants.ecourtdate.com/agencies/4f0c9d2e/warrants/9d2b6e14/physician-certificate.pdf?expires=1755616800&signature=…
                uploaded_by: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                created_at: 2026-08-19T14:32:07Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
    delete:
      operationId: deleteFile
      summary: Delete an attachment
      description: Deletes an attachment and the stored object behind it.
      tags:
        - Files
      parameters:
        - name: fileId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: File Id
          description: The file id.
          example: 51d3c8a4-9e2b-4d17-a6f0-3b8c5e1f7d29
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: files:write
      responses:
        "204":
          description: Deleted. No content is returned.
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/files/confirm:
    post:
      operationId: confirmUpload
      summary: Confirm an upload
      description: Verifies that the bytes arrived and marks the attachment confirmed. An attachment that is never confirmed is not visible on the warrant application.
      tags:
        - Files
      parameters:
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: files:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConfirmUploadRequest"
            example:
              file_id: 51d3c8a4-9e2b-4d17-a6f0-3b8c5e1f7d29
              storage_key: agencies/4f0c9d2e/warrants/9d2b6e14/physician-certificate.pdf
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/File"
              example:
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                original_filename: physician-certificate.pdf
                content_type: application/pdf
                file_size: 284913
                resource_type: SIGNATURE
                resource_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                download_url: https://files.warrants.ecourtdate.com/agencies/4f0c9d2e/warrants/9d2b6e14/physician-certificate.pdf?expires=1755616800&signature=…
                uploaded_by: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                created_at: 2026-08-19T14:32:07Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "422":
          description: The request body failed validation. `param` names the field.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: form_data is required.
                  type: invalid_request_error
                  code: validation_failed
                  param: form_data
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/files/presign:
    post:
      operationId: presignUpload
      summary: Start an upload
      description: "Returns a short-lived URL to `PUT` the file bytes to, and records a pending attachment. Uploads never pass through this API: send the bytes to the returned URL, then call [confirmUpload](#tag/files/operation/confirmUpload)."
      tags:
        - Files
      parameters:
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: files:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PresignRequest"
            example:
              filename: physician-certificate.pdf
              content_type: application/pdf
              resource_type: ATTACHMENT
              resource_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PresignedUpload"
              example:
                file_id: 51d3c8a4-9e2b-4d17-a6f0-3b8c5e1f7d29
                upload_url: https://uploads.warrants.ecourtdate.com/agencies/4f0c9d2e/warrants/9d2b6e14/physician-certificate.pdf?signature=…
                storage_key: agencies/4f0c9d2e/warrants/9d2b6e14/physician-certificate.pdf
                expires_in: 900
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "422":
          description: The request body failed validation. `param` names the field.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: form_data is required.
                  type: invalid_request_error
                  code: validation_failed
                  param: form_data
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/locations:
    post:
      operationId: createLocation
      summary: Create a location
      description: Creates a location, such as a hospital, jail, or courthouse, that warrant applications can refer to.
      tags:
        - Locations
      parameters:
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: locations:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LocationCreate"
            example:
              name: Mercy General Hospital
              type: HOSPITAL
              address: 1201 Red River Street
              city: Austin
              state: TX
              zip_code: "78701"
              county: Travis
              phone: +1-512-555-0142
              contact_person: Records Office
      responses:
        "201":
          description: Created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Location"
              example:
                name: Emergency Detention (Form MH-101)
                type: text
                address: 1201 Red River Street
                city: Austin
                state: TX
                zip_code: "78701"
                county: Travis
                phone: +1-512-555-0142
                fax: +1-512-555-0143
                email: judge.alvarez@example.gov
                contact_person: Records Office
                notes: Emergency department intake, third floor.
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                is_active: true
                created_at: 2026-08-19T14:32:07Z
                updated_at: 2026-08-19T15:04:51Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "422":
          description: The request body failed validation. `param` names the field.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: form_data is required.
                  type: invalid_request_error
                  code: validation_failed
                  param: form_data
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
    get:
      operationId: listLocations
      summary: List locations
      description: Lists the agency's locations. Set `active_only=false` to include retired ones, or filter by `type`.
      tags:
        - Locations
      parameters:
        - name: active_only
          in: query
          required: false
          schema:
            type: boolean
            description: Filter to active locations only
            default: true
            title: Active Only
          description: Filter to active locations only
          example: true
        - name: type
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: Filter by location type
            title: Type
          description: Filter by location type
          example: text
      x-scope: locations:read
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/LocationListItem"
                title: Response List Locations V1 Locations Get
              example:
                - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                  agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                  name: Emergency Detention (Form MH-101)
                  type: text
                  is_active: true
                  address: 1201 Red River Street
                  city: Austin
                  state: TX
                  zip_code: "78701"
                  county: Travis
                  phone: +1-512-555-0142
                  fax: +1-512-555-0143
                  email: judge.alvarez@example.gov
                  contact_person: Records Office
                  notes: Emergency department intake, third floor.
                  created_at: 2026-08-19T14:32:07Z
                  updated_at: 2026-08-19T15:04:51Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/locations/{locationId}:
    get:
      operationId: getLocation
      summary: Retrieve a location
      description: Returns one location with its full contact details.
      tags:
        - Locations
      parameters:
        - name: locationId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Location Id
          description: The location id.
          example: 8a5d2f61-4c93-4e08-b71a-6f2e9c4b3d57
      x-scope: locations:read
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Location"
              example:
                name: Emergency Detention (Form MH-101)
                type: text
                address: 1201 Red River Street
                city: Austin
                state: TX
                zip_code: "78701"
                county: Travis
                phone: +1-512-555-0142
                fax: +1-512-555-0143
                email: judge.alvarez@example.gov
                contact_person: Records Office
                notes: Emergency department intake, third floor.
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                is_active: true
                created_at: 2026-08-19T14:32:07Z
                updated_at: 2026-08-19T15:04:51Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
    put:
      operationId: updateLocation
      summary: Update a location
      description: Updates a location in place.
      tags:
        - Locations
      parameters:
        - name: locationId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Location Id
          description: The location id.
          example: 8a5d2f61-4c93-4e08-b71a-6f2e9c4b3d57
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: locations:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LocationUpdate"
            example:
              name: Emergency Detention (Form MH-101)
              type: text
              is_active: true
              address: 1201 Red River Street
              city: Austin
              state: TX
              zip_code: "78701"
              county: Travis
              phone: +1-512-555-0142
              fax: +1-512-555-0143
              email: judge.alvarez@example.gov
              contact_person: Records Office
              notes: Emergency department intake, third floor.
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Location"
              example:
                name: Emergency Detention (Form MH-101)
                type: text
                address: 1201 Red River Street
                city: Austin
                state: TX
                zip_code: "78701"
                county: Travis
                phone: +1-512-555-0142
                fax: +1-512-555-0143
                email: judge.alvarez@example.gov
                contact_person: Records Office
                notes: Emergency department intake, third floor.
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                is_active: true
                created_at: 2026-08-19T14:32:07Z
                updated_at: 2026-08-19T15:04:51Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "422":
          description: The request body failed validation. `param` names the field.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: form_data is required.
                  type: invalid_request_error
                  code: validation_failed
                  param: form_data
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
    delete:
      operationId: deleteLocation
      summary: Delete a location
      description: Deletes a location. Applications that already reference it keep the values they captured.
      tags:
        - Locations
      parameters:
        - name: locationId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Location Id
          description: The location id.
          example: 8a5d2f61-4c93-4e08-b71a-6f2e9c4b3d57
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: locations:write
      responses:
        "204":
          description: Deleted. No content is returned.
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/permissions:
    get:
      operationId: listPermissions
      summary: List permissions
      description: The catalog of permissions a custom role can grant, grouped by area, with a human-readable label for each.
      tags:
        - Roles
      x-scope: users:read
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionCatalog"
              example:
                categories:
                  - category: string
                    permissions:
                      - key: records-clerk
                        label: Subject name
                        description: Statutory emergency detention application used by hospital staff.
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/public/branding/{fileId}:
    get:
      operationId: getPublicBrandingAsset
      summary: Retrieve a branding asset
      description: Redirects to an agency's published logo or seal. Takes no API key.
      tags:
        - Public
      parameters:
        - name: fileId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: File Id
          description: The file id.
          example: 51d3c8a4-9e2b-4d17-a6f0-3b8c5e1f7d29
      security: []
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema: {}
              example: {}
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/roles:
    get:
      operationId: listRoles
      summary: List roles
      description: "Lists the roles available in the agency: the four built-in roles and any custom roles. Set `include_system=false` to list only custom roles."
      tags:
        - Roles
      parameters:
        - name: include_system
          in: query
          required: false
          schema:
            type: boolean
            description: Include global system roles
            default: true
            title: Include System
          description: Include global system roles
          example: true
        - name: active_only
          in: query
          required: false
          schema:
            type: boolean
            description: Exclude archived roles
            default: true
            title: Active Only
          description: Exclude archived roles
          example: true
        - name: search
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: Case-insensitive name filter
            title: Search
          description: Case-insensitive name filter
          example: string
      x-scope: users:read
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Role"
                title: Response List Roles V1 Roles Get
              example:
                - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                  agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                  key: records-clerk
                  name: Emergency Detention (Form MH-101)
                  description: Statutory emergency detention application used by hospital staff.
                  is_system: false
                  is_active: true
                  color: "#3979AC"
                  icon: gavel
                  scope: AGENCY
                  permissions:
                    - string
                  created_at: 2026-08-19T14:32:07Z
                  updated_at: 2026-08-19T15:04:51Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
    post:
      operationId: createRole
      summary: Create a custom role
      description: Creates a custom role from a set of permissions. Use [listPermissions](#tag/roles/operation/listPermissions) to discover the permissions that can be granted.
      tags:
        - Roles
      parameters:
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: users:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RoleCreate"
            example:
              name: Records Clerk
              description: Reads warrant applications and the audit trail, and files attachments.
              permissions:
                - warrant:view_all
                - file:upload
                - audit:view
              color: "#3979AC"
      responses:
        "201":
          description: Created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Role"
              example:
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                key: records-clerk
                name: Emergency Detention (Form MH-101)
                description: Statutory emergency detention application used by hospital staff.
                is_system: false
                is_active: true
                color: "#3979AC"
                icon: gavel
                scope: AGENCY
                permissions:
                  - string
                created_at: 2026-08-19T14:32:07Z
                updated_at: 2026-08-19T15:04:51Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "422":
          description: The request body failed validation. `param` names the field.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: form_data is required.
                  type: invalid_request_error
                  code: validation_failed
                  param: form_data
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/roles/{roleId}:
    get:
      operationId: getRole
      summary: Retrieve a role
      description: Returns one role and the permissions it grants.
      tags:
        - Roles
      parameters:
        - name: roleId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Role Id
          description: The role id.
          example: 2c9f4b18-3a7e-4d51-b8c6-9e0a2f5d1c73
      x-scope: users:read
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Role"
              example:
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                key: records-clerk
                name: Emergency Detention (Form MH-101)
                description: Statutory emergency detention application used by hospital staff.
                is_system: false
                is_active: true
                color: "#3979AC"
                icon: gavel
                scope: AGENCY
                permissions:
                  - string
                created_at: 2026-08-19T14:32:07Z
                updated_at: 2026-08-19T15:04:51Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
    put:
      operationId: updateRole
      summary: Update a custom role
      description: Updates a custom role. Built-in roles cannot be modified. Changes apply immediately to everyone holding the role.
      tags:
        - Roles
      parameters:
        - name: roleId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Role Id
          description: The role id.
          example: 2c9f4b18-3a7e-4d51-b8c6-9e0a2f5d1c73
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: users:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RoleUpdate"
            example:
              name: Emergency Detention (Form MH-101)
              description: Statutory emergency detention application used by hospital staff.
              color: "#3979AC"
              icon: gavel
              is_active: true
              permissions:
                - string
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Role"
              example:
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                key: records-clerk
                name: Emergency Detention (Form MH-101)
                description: Statutory emergency detention application used by hospital staff.
                is_system: false
                is_active: true
                color: "#3979AC"
                icon: gavel
                scope: AGENCY
                permissions:
                  - string
                created_at: 2026-08-19T14:32:07Z
                updated_at: 2026-08-19T15:04:51Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "422":
          description: The request body failed validation. `param` names the field.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: form_data is required.
                  type: invalid_request_error
                  code: validation_failed
                  param: form_data
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
    delete:
      operationId: deleteRole
      summary: Delete a custom role
      description: "Deletes a custom role. A role that people still hold cannot be deleted: move them to another role first."
      tags:
        - Roles
      parameters:
        - name: roleId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Role Id
          description: The role id.
          example: 2c9f4b18-3a7e-4d51-b8c6-9e0a2f5d1c73
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: users:write
      responses:
        "204":
          description: Deleted. No content is returned.
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/settings:
    get:
      operationId: getAgencySettings
      summary: Retrieve agency settings
      description: "Returns the agency's warrant configuration: which templates are enabled, how submitted applications are routed, and the escalation and public-link rules."
      tags:
        - Agency settings
      x-scope: settings:read
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgencySettings"
              example: &a6
                agencyName: string
                address: 1201 Red River Street
                city: Austin
                county: Travis
                state: TX
                zipCode: string
                courtName: string
                timezone: America/Chicago
                contactPhone: string
                logoUrl: https://example.gov/resource
                isConfigured: true
                judgeNotifyMethod: BLAST
                notifyOnStandard: true
                notifyOnUrgent: true
                escalationTimeoutMinutes: 1
                escalationTimeoutMinutesUrgent: 1
                enabledTemplates:
                  - string
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
    put:
      operationId: updateAgencySettings
      summary: Update agency settings
      description: Updates agency settings. Only the keys present in the request are changed.
      tags:
        - Agency settings
      parameters:
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: settings:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AgencySettingsUpdate"
            example:
              judgeNotifyMethod: BLAST
              escalationTimeoutMinutesUrgent: 15
              enabledTemplates:
                - emergency-detention
                - search-warrant
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgencySettings"
              example: *a6
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "422":
          description: The request body failed validation. `param` names the field.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: form_data is required.
                  type: invalid_request_error
                  code: validation_failed
                  param: form_data
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/settings/public/{slug}:
    get:
      operationId: getPublicAgency
      summary: Retrieve public agency details
      description: Returns the public identity of an agency, so a public warrant link can be rendered with the right name and branding. Takes no API key.
      tags:
        - Public
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
            title: Slug
          description: Public link identifier.
          example: ew-2026-004182-f3a91c
      security: []
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicAgency"
              example:
                name: Emergency Detention (Form MH-101)
                address: 1201 Red River Street
                county: Travis
                state: TX
                court_name: Travis County District Court
                timezone: America/Chicago
                contact_phone: +1-512-555-0142
                logo: https://files.warrants.ecourtdate.com/agencies/4f0c9d2e/logo.png
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/templates:
    post:
      operationId: createTemplate
      summary: Create a template
      description: Creates a warrant template. `elements` declares the fields an application collects, and `workflow_config` sets the review rules that apply to applications made from it.
      tags:
        - Templates
      parameters:
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: templates:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TemplateCreate"
            example:
              name: Emergency Detention (Form MH-101)
              description: Statutory emergency detention application used by hospital staff.
              base_image: https://files.warrants.ecourtdate.com/templates/c47b2a91/base.png
              base_document_content_type: application/pdf
              template_html: <section data-field="subject_name"></section>
              elements:
                - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                  type: text
                  x: 72
                  y: 144
                  width: 320
                  height: 24
                  content: Application for Emergency Detention
                  fieldId: subject_name
                  label: Subject name
                  dataType: text
                  required: true
                  defaultValue: Jordan Rivera
                  options:
                    - string
                  fontSize: 12
                  fontFamily: Open Sans
                  fieldMapping: subject.name
              workflow:
                requiresJudgeApproval: true
                notifyOnSubmission: true
                autoExpireHours: 48
                allowedRoles:
                  - PHYSICIAN
              allow_editing_per_warrant: true
              style_preset: letter-portrait
      responses:
        "201":
          description: Created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Template"
              example:
                name: Emergency Detention (Form MH-101)
                description: Statutory emergency detention application used by hospital staff.
                base_image: https://files.warrants.ecourtdate.com/templates/c47b2a91/base.png
                base_document_content_type: application/pdf
                template_html: <section data-field="subject_name"></section>
                elements:
                  - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    type: text
                    x: 72
                    y: 144
                    width: 320
                    height: 24
                    content: Application for Emergency Detention
                    fieldId: subject_name
                    label: Subject name
                    dataType: text
                    required: true
                    defaultValue: Jordan Rivera
                    options:
                      - string
                    fontSize: 12
                    fontFamily: Open Sans
                    fieldMapping: subject.name
                workflow:
                  requiresJudgeApproval: true
                  notifyOnSubmission: true
                  autoExpireHours: 48
                  allowedRoles:
                    - PHYSICIAN
                allow_editing_per_warrant: true
                style_preset: letter-portrait
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                created_by_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                is_active: true
                is_system_template: false
                created_at: 2026-08-19T14:32:07Z
                updated_at: 2026-08-19T15:04:51Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "422":
          description: The request body failed validation. `param` names the field.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: form_data is required.
                  type: invalid_request_error
                  code: validation_failed
                  param: form_data
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
    get:
      operationId: listTemplates
      summary: List templates
      description: Lists the templates available to the agency, including the system templates eCourtDate maintains. Set `active_only=false` to include retired templates.
      tags:
        - Templates
      parameters:
        - name: active_only
          in: query
          required: false
          schema:
            type: boolean
            default: true
            title: Active Only
          description: Return only active records.
          example: true
      x-scope: templates:read
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Template"
                title: Response List Templates V1 Templates Get
              example:
                - name: Emergency Detention (Form MH-101)
                  description: Statutory emergency detention application used by hospital staff.
                  base_image: https://files.warrants.ecourtdate.com/templates/c47b2a91/base.png
                  base_document_content_type: application/pdf
                  template_html: <section data-field="subject_name"></section>
                  elements:
                    - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                      type: text
                      x: 72
                      y: 144
                      width: 320
                      height: 24
                      content: Application for Emergency Detention
                      fieldId: subject_name
                      label: Subject name
                      dataType: text
                      required: true
                      defaultValue: Jordan Rivera
                      options:
                        - string
                      fontSize: 12
                      fontFamily: Open Sans
                      fieldMapping: subject.name
                  workflow:
                    requiresJudgeApproval: true
                    notifyOnSubmission: true
                    autoExpireHours: 48
                    allowedRoles:
                      - PHYSICIAN
                  allow_editing_per_warrant: true
                  style_preset: letter-portrait
                  id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                  agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                  created_by_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                  is_active: true
                  is_system_template: false
                  created_at: 2026-08-19T14:32:07Z
                  updated_at: 2026-08-19T15:04:51Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/templates/{templateId}:
    get:
      operationId: getTemplate
      summary: Retrieve a template
      description: Returns one template with its full `elements` array, which is the contract for the `form_data` of any application created from it.
      tags:
        - Templates
      parameters:
        - name: templateId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Template Id
          description: The template id.
          example: c47b2a91-5e3d-4f88-b0a2-7d1c6e9f4a53
      x-scope: templates:read
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Template"
              example:
                name: Emergency Detention (Form MH-101)
                description: Statutory emergency detention application used by hospital staff.
                base_image: https://files.warrants.ecourtdate.com/templates/c47b2a91/base.png
                base_document_content_type: application/pdf
                template_html: <section data-field="subject_name"></section>
                elements:
                  - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    type: text
                    x: 72
                    y: 144
                    width: 320
                    height: 24
                    content: Application for Emergency Detention
                    fieldId: subject_name
                    label: Subject name
                    dataType: text
                    required: true
                    defaultValue: Jordan Rivera
                    options:
                      - string
                    fontSize: 12
                    fontFamily: Open Sans
                    fieldMapping: subject.name
                workflow:
                  requiresJudgeApproval: true
                  notifyOnSubmission: true
                  autoExpireHours: 48
                  allowedRoles:
                    - PHYSICIAN
                allow_editing_per_warrant: true
                style_preset: letter-portrait
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                created_by_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                is_active: true
                is_system_template: false
                created_at: 2026-08-19T14:32:07Z
                updated_at: 2026-08-19T15:04:51Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
    put:
      operationId: updateTemplate
      summary: Update a template
      description: "Updates an agency template. System templates cannot be edited: duplicate one first."
      tags:
        - Templates
      parameters:
        - name: templateId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Template Id
          description: The template id.
          example: c47b2a91-5e3d-4f88-b0a2-7d1c6e9f4a53
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: templates:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TemplateUpdate"
            example:
              name: Emergency Detention (Form MH-101)
              description: Statutory emergency detention application used by hospital staff.
              base_image: https://files.warrants.ecourtdate.com/templates/c47b2a91/base.png
              base_document_content_type: application/pdf
              template_html: <section data-field="subject_name"></section>
              elements:
                - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                  type: text
                  x: 72
                  y: 144
                  width: 320
                  height: 24
                  content: Application for Emergency Detention
                  fieldId: subject_name
                  label: Subject name
                  dataType: text
                  required: true
                  defaultValue: Jordan Rivera
                  options:
                    - string
                  fontSize: 12
                  fontFamily: Open Sans
                  fieldMapping: subject.name
              workflow:
                requiresJudgeApproval: true
                notifyOnSubmission: true
                autoExpireHours: 48
                allowedRoles:
                  - PHYSICIAN
              is_active: true
              allow_editing_per_warrant: true
              style_preset: letter-portrait
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Template"
              example:
                name: Emergency Detention (Form MH-101)
                description: Statutory emergency detention application used by hospital staff.
                base_image: https://files.warrants.ecourtdate.com/templates/c47b2a91/base.png
                base_document_content_type: application/pdf
                template_html: <section data-field="subject_name"></section>
                elements:
                  - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    type: text
                    x: 72
                    y: 144
                    width: 320
                    height: 24
                    content: Application for Emergency Detention
                    fieldId: subject_name
                    label: Subject name
                    dataType: text
                    required: true
                    defaultValue: Jordan Rivera
                    options:
                      - string
                    fontSize: 12
                    fontFamily: Open Sans
                    fieldMapping: subject.name
                workflow:
                  requiresJudgeApproval: true
                  notifyOnSubmission: true
                  autoExpireHours: 48
                  allowedRoles:
                    - PHYSICIAN
                allow_editing_per_warrant: true
                style_preset: letter-portrait
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                created_by_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                is_active: true
                is_system_template: false
                created_at: 2026-08-19T14:32:07Z
                updated_at: 2026-08-19T15:04:51Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "422":
          description: The request body failed validation. `param` names the field.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: form_data is required.
                  type: invalid_request_error
                  code: validation_failed
                  param: form_data
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
    delete:
      operationId: deleteTemplate
      summary: Delete a template
      description: Deletes an agency template. Applications already created from it keep working.
      tags:
        - Templates
      parameters:
        - name: templateId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Template Id
          description: The template id.
          example: c47b2a91-5e3d-4f88-b0a2-7d1c6e9f4a53
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: templates:write
      responses:
        "204":
          description: Deleted. No content is returned.
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/templates/{templateId}/duplicate:
    post:
      operationId: duplicateTemplate
      summary: Duplicate a template
      description: Copies a template into a new, editable agency template. This is how a system template is customized.
      tags:
        - Templates
      parameters:
        - name: templateId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Template Id
          description: The template id.
          example: c47b2a91-5e3d-4f88-b0a2-7d1c6e9f4a53
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: templates:write
      responses:
        "201":
          description: Created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Template"
              example:
                name: Emergency Detention (Form MH-101)
                description: Statutory emergency detention application used by hospital staff.
                base_image: https://files.warrants.ecourtdate.com/templates/c47b2a91/base.png
                base_document_content_type: application/pdf
                template_html: <section data-field="subject_name"></section>
                elements:
                  - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    type: text
                    x: 72
                    y: 144
                    width: 320
                    height: 24
                    content: Application for Emergency Detention
                    fieldId: subject_name
                    label: Subject name
                    dataType: text
                    required: true
                    defaultValue: Jordan Rivera
                    options:
                      - string
                    fontSize: 12
                    fontFamily: Open Sans
                    fieldMapping: subject.name
                workflow:
                  requiresJudgeApproval: true
                  notifyOnSubmission: true
                  autoExpireHours: 48
                  allowedRoles:
                    - PHYSICIAN
                allow_editing_per_warrant: true
                style_preset: letter-portrait
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                created_by_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                is_active: true
                is_system_template: false
                created_at: 2026-08-19T14:32:07Z
                updated_at: 2026-08-19T15:04:51Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/templates/process-document:
    post:
      operationId: processTemplateDocument
      summary: Convert an uploaded document
      description: Converts an uploaded document so it can back a template. Word documents are converted to PDF; images and PDFs are returned unchanged.
      tags:
        - Templates
      parameters:
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: templates:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProcessDocumentRequest"
            example:
              storage_key: agencies/4f0c9d2e/warrants/9d2b6e14/physician-certificate.pdf
              content_type: application/pdf
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcessedDocument"
              example:
                storage_key: agencies/4f0c9d2e/warrants/9d2b6e14/physician-certificate.pdf
                content_type: application/pdf
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "422":
          description: The request body failed validation. `param` names the field.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: form_data is required.
                  type: invalid_request_error
                  code: validation_failed
                  param: form_data
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/users:
    post:
      operationId: createUser
      summary: Add a user
      description: Adds a person to the agency with a role. They can sign in once they have completed identity setup; until then the record exists and can be assigned work.
      tags:
        - Users
      parameters:
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: users:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserCreate"
            example:
              email: clerk.hayes@example.gov
              full_name: Dana Hayes
              title: Records Clerk
              role: OFFICER
      responses:
        "201":
          description: Created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
              example:
                email: judge.alvarez@example.gov
                full_name: Hon. Maria Alvarez
                title: Attending Physician
                role: PHYSICIAN
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                is_active: true
                is_verified: true
                last_login: 2026-08-19T13:58:44Z
                created_at: 2026-08-19T14:32:07Z
                updated_at: 2026-08-19T15:04:51Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "422":
          description: The request body failed validation. `param` names the field.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: form_data is required.
                  type: invalid_request_error
                  code: validation_failed
                  param: form_data
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
    get:
      operationId: listUsers
      summary: List users
      description: Lists the people in the agency, optionally filtered by `role`. Results are paginated with `skip` and `limit`.
      tags:
        - Users
      parameters:
        - name: role
          in: query
          required: false
          schema:
            anyOf:
              - $ref: "#/components/schemas/UserRole"
              - type: "null"
            title: Role
          description: Filter by the role held in this agency.
          example: PHYSICIAN
        - name: active_only
          in: query
          required: false
          schema:
            type: boolean
            default: true
            title: Active Only
          description: Return only active records.
          example: true
        - name: skip
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
            title: Skip
          description: Number of records to skip. Use with `limit` to page through results.
          example: 0
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 500
            minimum: 1
            default: 100
            title: Limit
          description: Maximum number of records to return.
          example: 50
      x-scope: users:read
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
                title: Response List Users V1 Users Get
              example:
                - email: judge.alvarez@example.gov
                  full_name: Hon. Maria Alvarez
                  title: Attending Physician
                  role: PHYSICIAN
                  id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                  agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                  is_active: true
                  is_verified: true
                  last_login: 2026-08-19T13:58:44Z
                  created_at: 2026-08-19T14:32:07Z
                  updated_at: 2026-08-19T15:04:51Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/users/{userId}:
    get:
      operationId: getUser
      summary: Retrieve a user
      description: Returns one person's record and their role in this agency.
      tags:
        - Users
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: User Id
          description: Filter to actions taken by one person.
          example: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
      x-scope: users:read
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
              example:
                email: judge.alvarez@example.gov
                full_name: Hon. Maria Alvarez
                title: Attending Physician
                role: PHYSICIAN
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                is_active: true
                is_verified: true
                last_login: 2026-08-19T13:58:44Z
                created_at: 2026-08-19T14:32:07Z
                updated_at: 2026-08-19T15:04:51Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
    put:
      operationId: updateUser
      summary: Update a user
      description: Updates a person's profile details.
      tags:
        - Users
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: User Id
          description: Filter to actions taken by one person.
          example: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: users:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserUpdate"
            example:
              full_name: Hon. Maria Alvarez
              title: Attending Physician
              role: PHYSICIAN
              is_active: true
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
              example:
                email: judge.alvarez@example.gov
                full_name: Hon. Maria Alvarez
                title: Attending Physician
                role: PHYSICIAN
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                is_active: true
                is_verified: true
                last_login: 2026-08-19T13:58:44Z
                created_at: 2026-08-19T14:32:07Z
                updated_at: 2026-08-19T15:04:51Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "422":
          description: The request body failed validation. `param` names the field.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: form_data is required.
                  type: invalid_request_error
                  code: validation_failed
                  param: form_data
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
    delete:
      operationId: deactivateUser
      summary: Deactivate a user
      description: Deactivates a person's membership. The record and everything they did are kept for the audit trail; they simply can no longer act.
      tags:
        - Users
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: User Id
          description: Filter to actions taken by one person.
          example: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: users:write
      responses:
        "204":
          description: Deleted. No content is returned.
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/users/{userId}/role:
    put:
      operationId: changeUserRole
      summary: Change a user's role
      description: Changes the role a person holds in this agency, which changes what they may do immediately.
      tags:
        - Users
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: User Id
          description: Filter to actions taken by one person.
          example: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
        - name: role
          in: query
          required: true
          schema:
            $ref: "#/components/schemas/UserRole"
          description: Filter by the role held in this agency.
          example: PHYSICIAN
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: users:write
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
              example:
                email: judge.alvarez@example.gov
                full_name: Hon. Maria Alvarez
                title: Attending Physician
                role: PHYSICIAN
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                is_active: true
                is_verified: true
                last_login: 2026-08-19T13:58:44Z
                created_at: 2026-08-19T14:32:07Z
                updated_at: 2026-08-19T15:04:51Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/users/members:
    get:
      operationId: listMembers
      summary: List members
      description: A compact directory of the agency's members, suitable for populating pickers. It carries less detail than [listUsers](#tag/users/operation/listUsers).
      tags:
        - Users
      x-scope: users:read
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Member"
                title: Response List Members V1 Users Members Get
              example:
                - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                  full_name: Hon. Maria Alvarez
                  role: string
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/warrants:
    post:
      operationId: createWarrant
      summary: Create a warrant application
      description: Creates a warrant application from a template. The `form_data` object carries the values for the elements the template declares, and is stored encrypted. A new application starts in `DRAFT`; submit it for review with [submitWarrant](#tag/warrant-workflow/operation/submitWarrant).
      tags:
        - Warrants
      parameters:
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: warrants:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WarrantCreate"
            example:
              template_id: c47b2a91-5e3d-4f88-b0a2-7d1c6e9f4a53
              form_data: &a7
                subject_name: Jordan Rivera
                subject_dob: 1994-03-11
                facility: Mercy General Hospital
                county: Travis
                grounds: Subject presented to the emergency department in acute crisis and meets the statutory criteria for emergency detention.
                physician_name: Dr. Alex Chen
                physician_license: TX-448120
                examination_time: 2026-08-19T13:55:00Z
              priority: URGENT
              title: "Emergency detention: Rivera"
      responses:
        "201":
          description: Created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Warrant"
              example:
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                creator_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                template_id: c47b2a91-5e3d-4f88-b0a2-7d1c6e9f4a53
                warrant_number: EW-2026-004182
                status: DRAFT
                priority: LOW
                visibility: PUBLIC
                slug: ew-2026-004182-f3a91c
                form_data: *a7
                judge_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                judge_name: Hon. Maria Alvarez
                judge_signature: &a8
                  type: DRAWN
                  data: data:image/png;base64,iVBORw0KGgo…
                assigned_user_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                assigned_user_name: Hon. Maria Alvarez
                assigned_at: 2026-08-19T14:41:22Z
                assigned_by_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                assignment_mode: MANUAL
                created_at: 2026-08-19T14:32:07Z
                submitted_at: 2026-08-19T14:41:19Z
                signed_at: 2026-08-19T15:04:51Z
                expires_at: 2026-08-26T15:04:51Z
                deleted_at: null
                comments:
                  - text: Attaching the signed physician certificate.
                    is_internal: false
                    id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    warrant_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    author_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    author_name: Dr. Alex Chen
                    author_role: PHYSICIAN
                    mentions:
                      - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                        full_name: Hon. Maria Alvarez
                        role: PHYSICIAN
                    created_at: 2026-08-19T14:32:07Z
                creator_name: Dr. Alex Chen
                creator_role: PHYSICIAN
                warnings:
                  - string
                document_html: <article class="warrant"><h1>Application for Emergency Detention</h1></article>
                document_updated_at: 2026-08-19T15:04:51Z
                allow_document_editing: false
                pdf_url: https://files.warrants.ecourtdate.com/warrants/9d2b6e14/document.pdf?expires=1755616800&signature=…
                attachments:
                  - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    original_filename: physician-certificate.pdf
                    content_type: application/pdf
                    file_size: 284913
                    resource_type: SIGNATURE
                    resource_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    download_url: https://files.warrants.ecourtdate.com/agencies/4f0c9d2e/warrants/9d2b6e14/physician-certificate.pdf?expires=1755616800&signature=…
                    uploaded_by: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    created_at: 2026-08-19T14:32:07Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "422":
          description: The request body failed validation. `param` names the field.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: form_data is required.
                  type: invalid_request_error
                  code: validation_failed
                  param: form_data
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
    get:
      operationId: listWarrants
      summary: List warrant applications
      description: Lists warrant applications visible to the key, newest first. Filter by `status` to build a review queue, or set `trashed_only` to list the trash. Results are paginated with `skip` and `limit`.
      tags:
        - Warrants
      parameters:
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - $ref: "#/components/schemas/WarrantStatus"
              - type: "null"
            title: Status
          description: Return only applications in this state.
          example: DRAFT
        - name: trashed_only
          in: query
          required: false
          schema:
            type: boolean
            default: false
            title: Trashed Only
          description: Return trashed applications instead of active ones.
          example: false
        - name: assigned_to_me
          in: query
          required: false
          schema:
            type: boolean
            default: false
            title: Assigned To Me
          description: Return only applications routed to the calling agency member.
          example: false
        - name: skip
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
            title: Skip
          description: Number of records to skip. Use with `limit` to page through results.
          example: 0
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 500
            minimum: 1
            default: 100
            title: Limit
          description: Maximum number of records to return.
          example: 50
      x-scope: warrants:read
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/WarrantListItem"
                title: Response List Warrants V1 Warrants Get
              example:
                - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                  agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                  creator_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                  template_id: c47b2a91-5e3d-4f88-b0a2-7d1c6e9f4a53
                  warrant_number: EW-2026-004182
                  status: DRAFT
                  priority: LOW
                  visibility: PUBLIC
                  form_data_summary:
                    subject_name: Jordan Rivera
                    facility: Mercy General Hospital
                  assigned_user_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                  assigned_at: 2026-08-19T14:41:22Z
                  assignment_mode: MANUAL
                  created_at: 2026-08-19T14:32:07Z
                  submitted_at: 2026-08-19T14:41:19Z
                  signed_at: 2026-08-19T15:04:51Z
                  deleted_at: null
                  creator_name: Dr. Alex Chen
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/warrants/{warrantId}:
    get:
      operationId: getWarrant
      summary: Retrieve a warrant application
      description: Returns one warrant application, including its decrypted `form_data`, its signature state, and the identifiers of its attachments.
      tags:
        - Warrants
      parameters:
        - name: warrantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Warrant Id
          description: Filter to one warrant application.
          example: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
      x-scope: warrants:read
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Warrant"
              example:
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                creator_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                template_id: c47b2a91-5e3d-4f88-b0a2-7d1c6e9f4a53
                warrant_number: EW-2026-004182
                status: DRAFT
                priority: LOW
                visibility: PUBLIC
                slug: ew-2026-004182-f3a91c
                form_data: *a7
                judge_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                judge_name: Hon. Maria Alvarez
                judge_signature: *a8
                assigned_user_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                assigned_user_name: Hon. Maria Alvarez
                assigned_at: 2026-08-19T14:41:22Z
                assigned_by_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                assignment_mode: MANUAL
                created_at: 2026-08-19T14:32:07Z
                submitted_at: 2026-08-19T14:41:19Z
                signed_at: 2026-08-19T15:04:51Z
                expires_at: 2026-08-26T15:04:51Z
                deleted_at: null
                comments:
                  - text: Attaching the signed physician certificate.
                    is_internal: false
                    id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    warrant_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    author_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    author_name: Dr. Alex Chen
                    author_role: PHYSICIAN
                    mentions:
                      - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                        full_name: Hon. Maria Alvarez
                        role: PHYSICIAN
                    created_at: 2026-08-19T14:32:07Z
                creator_name: Dr. Alex Chen
                creator_role: PHYSICIAN
                warnings:
                  - string
                document_html: <article class="warrant"><h1>Application for Emergency Detention</h1></article>
                document_updated_at: 2026-08-19T15:04:51Z
                allow_document_editing: false
                pdf_url: https://files.warrants.ecourtdate.com/warrants/9d2b6e14/document.pdf?expires=1755616800&signature=…
                attachments:
                  - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    original_filename: physician-certificate.pdf
                    content_type: application/pdf
                    file_size: 284913
                    resource_type: SIGNATURE
                    resource_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    download_url: https://files.warrants.ecourtdate.com/agencies/4f0c9d2e/warrants/9d2b6e14/physician-certificate.pdf?expires=1755616800&signature=…
                    uploaded_by: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    created_at: 2026-08-19T14:32:07Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
    put:
      operationId: updateWarrant
      summary: Update a warrant application
      description: "Updates a warrant application in place. `SIGNED` and `REJECTED` applications are locked and return `409`: reopen a rejected application first. Claim the [edit lock](#tag/locks) before writing if other people may be working on the same application."
      tags:
        - Warrants
      parameters:
        - name: warrantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Warrant Id
          description: Filter to one warrant application.
          example: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: warrants:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WarrantUpdate"
            example:
              template_id: c47b2a91-5e3d-4f88-b0a2-7d1c6e9f4a53
              form_data: *a7
              priority: LOW
              document_html: <article class="warrant"><h1>Application for Emergency Detention</h1></article>
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Warrant"
              example:
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                creator_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                template_id: c47b2a91-5e3d-4f88-b0a2-7d1c6e9f4a53
                warrant_number: EW-2026-004182
                status: DRAFT
                priority: LOW
                visibility: PUBLIC
                slug: ew-2026-004182-f3a91c
                form_data: *a7
                judge_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                judge_name: Hon. Maria Alvarez
                judge_signature: *a8
                assigned_user_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                assigned_user_name: Hon. Maria Alvarez
                assigned_at: 2026-08-19T14:41:22Z
                assigned_by_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                assignment_mode: MANUAL
                created_at: 2026-08-19T14:32:07Z
                submitted_at: 2026-08-19T14:41:19Z
                signed_at: 2026-08-19T15:04:51Z
                expires_at: 2026-08-26T15:04:51Z
                deleted_at: null
                comments:
                  - text: Attaching the signed physician certificate.
                    is_internal: false
                    id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    warrant_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    author_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    author_name: Dr. Alex Chen
                    author_role: PHYSICIAN
                    mentions:
                      - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                        full_name: Hon. Maria Alvarez
                        role: PHYSICIAN
                    created_at: 2026-08-19T14:32:07Z
                creator_name: Dr. Alex Chen
                creator_role: PHYSICIAN
                warnings:
                  - string
                document_html: <article class="warrant"><h1>Application for Emergency Detention</h1></article>
                document_updated_at: 2026-08-19T15:04:51Z
                allow_document_editing: false
                pdf_url: https://files.warrants.ecourtdate.com/warrants/9d2b6e14/document.pdf?expires=1755616800&signature=…
                attachments:
                  - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    original_filename: physician-certificate.pdf
                    content_type: application/pdf
                    file_size: 284913
                    resource_type: SIGNATURE
                    resource_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    download_url: https://files.warrants.ecourtdate.com/agencies/4f0c9d2e/warrants/9d2b6e14/physician-certificate.pdf?expires=1755616800&signature=…
                    uploaded_by: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    created_at: 2026-08-19T14:32:07Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "422":
          description: The request body failed validation. `param` names the field.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: form_data is required.
                  type: invalid_request_error
                  code: validation_failed
                  param: form_data
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
    delete:
      operationId: deleteWarrant
      summary: Delete a warrant application
      description: Permanently deletes a warrant application and its audit-visible record of deletion. Only trashed applications, or untrashed `DRAFT` applications, can be deleted. Prefer [trashWarrant](#tag/warrant-workflow/operation/trashWarrant), which is reversible.
      tags:
        - Warrants
      parameters:
        - name: warrantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Warrant Id
          description: Filter to one warrant application.
          example: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: warrants:write
      responses:
        "204":
          description: Deleted. No content is returned.
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/warrants/{warrantId}/assign:
    patch:
      operationId: assignWarrant
      summary: Assign to a judge
      description: "Routes a `SUBMITTED` application to a judge. Assignment is a routing hint, not a lock: the application stays actionable by any judge in the agency. The audit trail then shows who was asked and who signed."
      tags:
        - Warrant workflow
      parameters:
        - name: warrantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Warrant Id
          description: Filter to one warrant application.
          example: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: warrants:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WarrantAssignRequest"
            example:
              judge_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
              reason: On call for the overnight bench rotation.
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Warrant"
              example:
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                creator_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                template_id: c47b2a91-5e3d-4f88-b0a2-7d1c6e9f4a53
                warrant_number: EW-2026-004182
                status: DRAFT
                priority: LOW
                visibility: PUBLIC
                slug: ew-2026-004182-f3a91c
                form_data: *a7
                judge_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                judge_name: Hon. Maria Alvarez
                judge_signature: *a8
                assigned_user_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                assigned_user_name: Hon. Maria Alvarez
                assigned_at: 2026-08-19T14:41:22Z
                assigned_by_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                assignment_mode: MANUAL
                created_at: 2026-08-19T14:32:07Z
                submitted_at: 2026-08-19T14:41:19Z
                signed_at: 2026-08-19T15:04:51Z
                expires_at: 2026-08-26T15:04:51Z
                deleted_at: null
                comments:
                  - text: Attaching the signed physician certificate.
                    is_internal: false
                    id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    warrant_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    author_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    author_name: Dr. Alex Chen
                    author_role: PHYSICIAN
                    mentions:
                      - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                        full_name: Hon. Maria Alvarez
                        role: PHYSICIAN
                    created_at: 2026-08-19T14:32:07Z
                creator_name: Dr. Alex Chen
                creator_role: PHYSICIAN
                warnings:
                  - string
                document_html: <article class="warrant"><h1>Application for Emergency Detention</h1></article>
                document_updated_at: 2026-08-19T15:04:51Z
                allow_document_editing: false
                pdf_url: https://files.warrants.ecourtdate.com/warrants/9d2b6e14/document.pdf?expires=1755616800&signature=…
                attachments:
                  - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    original_filename: physician-certificate.pdf
                    content_type: application/pdf
                    file_size: 284913
                    resource_type: SIGNATURE
                    resource_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    download_url: https://files.warrants.ecourtdate.com/agencies/4f0c9d2e/warrants/9d2b6e14/physician-certificate.pdf?expires=1755616800&signature=…
                    uploaded_by: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    created_at: 2026-08-19T14:32:07Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "422":
          description: The request body failed validation. `param` names the field.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: form_data is required.
                  type: invalid_request_error
                  code: validation_failed
                  param: form_data
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
    delete:
      operationId: unassignWarrant
      summary: Clear the assignment
      description: Removes the routing hint from a `SUBMITTED` application, returning it to the unassigned queue.
      tags:
        - Warrant workflow
      parameters:
        - name: warrantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Warrant Id
          description: Filter to one warrant application.
          example: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: warrants:write
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Warrant"
              example:
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                creator_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                template_id: c47b2a91-5e3d-4f88-b0a2-7d1c6e9f4a53
                warrant_number: EW-2026-004182
                status: DRAFT
                priority: LOW
                visibility: PUBLIC
                slug: ew-2026-004182-f3a91c
                form_data: *a7
                judge_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                judge_name: Hon. Maria Alvarez
                judge_signature: *a8
                assigned_user_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                assigned_user_name: Hon. Maria Alvarez
                assigned_at: 2026-08-19T14:41:22Z
                assigned_by_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                assignment_mode: MANUAL
                created_at: 2026-08-19T14:32:07Z
                submitted_at: 2026-08-19T14:41:19Z
                signed_at: 2026-08-19T15:04:51Z
                expires_at: 2026-08-26T15:04:51Z
                deleted_at: null
                comments:
                  - text: Attaching the signed physician certificate.
                    is_internal: false
                    id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    warrant_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    author_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    author_name: Dr. Alex Chen
                    author_role: PHYSICIAN
                    mentions:
                      - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                        full_name: Hon. Maria Alvarez
                        role: PHYSICIAN
                    created_at: 2026-08-19T14:32:07Z
                creator_name: Dr. Alex Chen
                creator_role: PHYSICIAN
                warnings:
                  - string
                document_html: <article class="warrant"><h1>Application for Emergency Detention</h1></article>
                document_updated_at: 2026-08-19T15:04:51Z
                allow_document_editing: false
                pdf_url: https://files.warrants.ecourtdate.com/warrants/9d2b6e14/document.pdf?expires=1755616800&signature=…
                attachments:
                  - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    original_filename: physician-certificate.pdf
                    content_type: application/pdf
                    file_size: 284913
                    resource_type: SIGNATURE
                    resource_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    download_url: https://files.warrants.ecourtdate.com/agencies/4f0c9d2e/warrants/9d2b6e14/physician-certificate.pdf?expires=1755616800&signature=…
                    uploaded_by: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    created_at: 2026-08-19T14:32:07Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/warrants/{warrantId}/comments:
    post:
      operationId: createComment
      summary: Add a comment
      description: Adds a comment to a warrant application. Set `is_internal` to keep it visible only to reviewers.
      tags:
        - Comments
      parameters:
        - name: warrantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Warrant Id
          description: Filter to one warrant application.
          example: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: warrants:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CommentCreate"
            example:
              text: Attaching the signed physician certificate.
              is_internal: false
      responses:
        "201":
          description: Created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Comment"
              example:
                text: Attaching the signed physician certificate.
                is_internal: false
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                warrant_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                author_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                author_name: Dr. Alex Chen
                author_role: PHYSICIAN
                mentions:
                  - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    full_name: Hon. Maria Alvarez
                    role: PHYSICIAN
                created_at: 2026-08-19T14:32:07Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "422":
          description: The request body failed validation. `param` names the field.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: form_data is required.
                  type: invalid_request_error
                  code: validation_failed
                  param: form_data
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
    get:
      operationId: listComments
      summary: List comments
      description: Lists the comment thread, oldest first. Internal comments are only returned to keys that may read them.
      tags:
        - Comments
      parameters:
        - name: warrantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Warrant Id
          description: Filter to one warrant application.
          example: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
      x-scope: warrants:read
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Comment"
                title: Response List Comments V1 Warrants  Warrant Id  Comments Get
              example:
                - text: Attaching the signed physician certificate.
                  is_internal: false
                  id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                  warrant_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                  author_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                  author_name: Dr. Alex Chen
                  author_role: PHYSICIAN
                  mentions:
                    - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                      full_name: Hon. Maria Alvarez
                      role: PHYSICIAN
                  created_at: 2026-08-19T14:32:07Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/warrants/{warrantId}/comments/{commentId}:
    delete:
      operationId: deleteComment
      summary: Delete a comment
      description: Deletes one comment from the thread. The deletion is audited.
      tags:
        - Comments
      parameters:
        - name: warrantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Warrant Id
          description: Filter to one warrant application.
          example: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
        - name: commentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Comment Id
          description: The comment id.
          example: 7e4a1c93-8b6d-42f5-9a08-1d3f5b7c9e21
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: warrants:write
      responses:
        "204":
          description: Deleted. No content is returned.
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/warrants/{warrantId}/lock:
    get:
      operationId: getWarrantLock
      summary: Read lock state
      description: Returns the current edit lock without claiming it, so a client can decide whether editing is safe.
      tags:
        - Locks
      parameters:
        - name: warrantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Warrant Id
          description: Filter to one warrant application.
          example: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
      x-scope: warrants:read
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WarrantLock"
              example:
                is_mine: true
                locked_by_user_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                locked_by_name: Dr. Alex Chen
                locked_at: 2026-08-19T14:38:02Z
                expires_in_seconds: 240
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
    post:
      operationId: claimWarrantLock
      summary: Claim or refresh the lock
      description: Claims the edit lock, or refreshes it when the caller already holds it. If someone else holds a fresh lock the call returns `409` with the holder's details; a stale lock is taken over.
      tags:
        - Locks
      parameters:
        - name: warrantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Warrant Id
          description: Filter to one warrant application.
          example: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: warrants:write
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WarrantLock"
              example:
                is_mine: true
                locked_by_user_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                locked_by_name: Dr. Alex Chen
                locked_at: 2026-08-19T14:38:02Z
                expires_in_seconds: 240
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
    delete:
      operationId: releaseWarrantLock
      summary: Release the lock
      description: Releases the edit lock. It is a no-op when the caller does not hold it, unless the caller may force-release other people's locks.
      tags:
        - Locks
      parameters:
        - name: warrantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Warrant Id
          description: Filter to one warrant application.
          example: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: warrants:write
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WarrantLock"
              example:
                is_mine: true
                locked_by_user_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                locked_by_name: Dr. Alex Chen
                locked_at: 2026-08-19T14:38:02Z
                expires_in_seconds: 240
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/warrants/{warrantId}/priority:
    patch:
      operationId: updateWarrantPriority
      summary: Set priority
      description: Sets the priority of an application to `LOW`, `STANDARD`, or `URGENT`. Priority orders review queues and drives escalation.
      tags:
        - Warrant workflow
      parameters:
        - name: warrantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Warrant Id
          description: Filter to one warrant application.
          example: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: warrants:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WarrantPriorityRequest"
            example:
              priority: URGENT
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Warrant"
              example:
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                creator_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                template_id: c47b2a91-5e3d-4f88-b0a2-7d1c6e9f4a53
                warrant_number: EW-2026-004182
                status: DRAFT
                priority: LOW
                visibility: PUBLIC
                slug: ew-2026-004182-f3a91c
                form_data: *a7
                judge_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                judge_name: Hon. Maria Alvarez
                judge_signature: *a8
                assigned_user_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                assigned_user_name: Hon. Maria Alvarez
                assigned_at: 2026-08-19T14:41:22Z
                assigned_by_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                assignment_mode: MANUAL
                created_at: 2026-08-19T14:32:07Z
                submitted_at: 2026-08-19T14:41:19Z
                signed_at: 2026-08-19T15:04:51Z
                expires_at: 2026-08-26T15:04:51Z
                deleted_at: null
                comments:
                  - text: Attaching the signed physician certificate.
                    is_internal: false
                    id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    warrant_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    author_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    author_name: Dr. Alex Chen
                    author_role: PHYSICIAN
                    mentions:
                      - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                        full_name: Hon. Maria Alvarez
                        role: PHYSICIAN
                    created_at: 2026-08-19T14:32:07Z
                creator_name: Dr. Alex Chen
                creator_role: PHYSICIAN
                warnings:
                  - string
                document_html: <article class="warrant"><h1>Application for Emergency Detention</h1></article>
                document_updated_at: 2026-08-19T15:04:51Z
                allow_document_editing: false
                pdf_url: https://files.warrants.ecourtdate.com/warrants/9d2b6e14/document.pdf?expires=1755616800&signature=…
                attachments:
                  - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    original_filename: physician-certificate.pdf
                    content_type: application/pdf
                    file_size: 284913
                    resource_type: SIGNATURE
                    resource_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    download_url: https://files.warrants.ecourtdate.com/agencies/4f0c9d2e/warrants/9d2b6e14/physician-certificate.pdf?expires=1755616800&signature=…
                    uploaded_by: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    created_at: 2026-08-19T14:32:07Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "422":
          description: The request body failed validation. `param` names the field.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: form_data is required.
                  type: invalid_request_error
                  code: validation_failed
                  param: form_data
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/warrants/{warrantId}/regenerate-pdf:
    post:
      operationId: regenerateWarrantDocument
      summary: Regenerate the signed document
      description: "Re-renders the document for an application that is already `SIGNED`. Nothing is re-signed: the stored signature, signer, and signing time are replayed as-is, and only the rendered file is rebuilt. Use it when a signed application has no document because rendering failed."
      tags:
        - Warrant workflow
      parameters:
        - name: warrantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Warrant Id
          description: Filter to one warrant application.
          example: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: warrants:write
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Warrant"
              example:
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                creator_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                template_id: c47b2a91-5e3d-4f88-b0a2-7d1c6e9f4a53
                warrant_number: EW-2026-004182
                status: DRAFT
                priority: LOW
                visibility: PUBLIC
                slug: ew-2026-004182-f3a91c
                form_data: *a7
                judge_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                judge_name: Hon. Maria Alvarez
                judge_signature: *a8
                assigned_user_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                assigned_user_name: Hon. Maria Alvarez
                assigned_at: 2026-08-19T14:41:22Z
                assigned_by_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                assignment_mode: MANUAL
                created_at: 2026-08-19T14:32:07Z
                submitted_at: 2026-08-19T14:41:19Z
                signed_at: 2026-08-19T15:04:51Z
                expires_at: 2026-08-26T15:04:51Z
                deleted_at: null
                comments:
                  - text: Attaching the signed physician certificate.
                    is_internal: false
                    id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    warrant_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    author_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    author_name: Dr. Alex Chen
                    author_role: PHYSICIAN
                    mentions:
                      - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                        full_name: Hon. Maria Alvarez
                        role: PHYSICIAN
                    created_at: 2026-08-19T14:32:07Z
                creator_name: Dr. Alex Chen
                creator_role: PHYSICIAN
                warnings:
                  - string
                document_html: <article class="warrant"><h1>Application for Emergency Detention</h1></article>
                document_updated_at: 2026-08-19T15:04:51Z
                allow_document_editing: false
                pdf_url: https://files.warrants.ecourtdate.com/warrants/9d2b6e14/document.pdf?expires=1755616800&signature=…
                attachments:
                  - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    original_filename: physician-certificate.pdf
                    content_type: application/pdf
                    file_size: 284913
                    resource_type: SIGNATURE
                    resource_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    download_url: https://files.warrants.ecourtdate.com/agencies/4f0c9d2e/warrants/9d2b6e14/physician-certificate.pdf?expires=1755616800&signature=…
                    uploaded_by: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    created_at: 2026-08-19T14:32:07Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/warrants/{warrantId}/reject:
    patch:
      operationId: rejectWarrant
      summary: Reject a warrant
      description: Rejects a `SUBMITTED` application with a reason, moving it to `REJECTED`. The reason is added to the comment thread so the applicant can act on it, and the application can be reopened for correction.
      tags:
        - Warrant workflow
      parameters:
        - name: warrantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Warrant Id
          description: Filter to one warrant application.
          example: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: warrants:sign
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WarrantRejectRequest"
            example:
              reason: The examination time predates the reported incident. Correct the timeline and resubmit.
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Warrant"
              example:
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                creator_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                template_id: c47b2a91-5e3d-4f88-b0a2-7d1c6e9f4a53
                warrant_number: EW-2026-004182
                status: DRAFT
                priority: LOW
                visibility: PUBLIC
                slug: ew-2026-004182-f3a91c
                form_data: *a7
                judge_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                judge_name: Hon. Maria Alvarez
                judge_signature: *a8
                assigned_user_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                assigned_user_name: Hon. Maria Alvarez
                assigned_at: 2026-08-19T14:41:22Z
                assigned_by_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                assignment_mode: MANUAL
                created_at: 2026-08-19T14:32:07Z
                submitted_at: 2026-08-19T14:41:19Z
                signed_at: 2026-08-19T15:04:51Z
                expires_at: 2026-08-26T15:04:51Z
                deleted_at: null
                comments:
                  - text: Attaching the signed physician certificate.
                    is_internal: false
                    id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    warrant_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    author_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    author_name: Dr. Alex Chen
                    author_role: PHYSICIAN
                    mentions:
                      - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                        full_name: Hon. Maria Alvarez
                        role: PHYSICIAN
                    created_at: 2026-08-19T14:32:07Z
                creator_name: Dr. Alex Chen
                creator_role: PHYSICIAN
                warnings:
                  - string
                document_html: <article class="warrant"><h1>Application for Emergency Detention</h1></article>
                document_updated_at: 2026-08-19T15:04:51Z
                allow_document_editing: false
                pdf_url: https://files.warrants.ecourtdate.com/warrants/9d2b6e14/document.pdf?expires=1755616800&signature=…
                attachments:
                  - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    original_filename: physician-certificate.pdf
                    content_type: application/pdf
                    file_size: 284913
                    resource_type: SIGNATURE
                    resource_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    download_url: https://files.warrants.ecourtdate.com/agencies/4f0c9d2e/warrants/9d2b6e14/physician-certificate.pdf?expires=1755616800&signature=…
                    uploaded_by: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    created_at: 2026-08-19T14:32:07Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "422":
          description: The request body failed validation. `param` names the field.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: form_data is required.
                  type: invalid_request_error
                  code: validation_failed
                  param: form_data
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/warrants/{warrantId}/reopen:
    patch:
      operationId: reopenWarrant
      summary: Reopen a rejected warrant
      description: Returns a `REJECTED` application to `DRAFT` so it can be corrected and submitted again. The document, its attachments, and the whole comment thread including the rejection reason are kept.
      tags:
        - Warrant workflow
      parameters:
        - name: warrantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Warrant Id
          description: Filter to one warrant application.
          example: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: warrants:write
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Warrant"
              example:
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                creator_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                template_id: c47b2a91-5e3d-4f88-b0a2-7d1c6e9f4a53
                warrant_number: EW-2026-004182
                status: DRAFT
                priority: LOW
                visibility: PUBLIC
                slug: ew-2026-004182-f3a91c
                form_data: *a7
                judge_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                judge_name: Hon. Maria Alvarez
                judge_signature: *a8
                assigned_user_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                assigned_user_name: Hon. Maria Alvarez
                assigned_at: 2026-08-19T14:41:22Z
                assigned_by_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                assignment_mode: MANUAL
                created_at: 2026-08-19T14:32:07Z
                submitted_at: 2026-08-19T14:41:19Z
                signed_at: 2026-08-19T15:04:51Z
                expires_at: 2026-08-26T15:04:51Z
                deleted_at: null
                comments:
                  - text: Attaching the signed physician certificate.
                    is_internal: false
                    id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    warrant_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    author_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    author_name: Dr. Alex Chen
                    author_role: PHYSICIAN
                    mentions:
                      - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                        full_name: Hon. Maria Alvarez
                        role: PHYSICIAN
                    created_at: 2026-08-19T14:32:07Z
                creator_name: Dr. Alex Chen
                creator_role: PHYSICIAN
                warnings:
                  - string
                document_html: <article class="warrant"><h1>Application for Emergency Detention</h1></article>
                document_updated_at: 2026-08-19T15:04:51Z
                allow_document_editing: false
                pdf_url: https://files.warrants.ecourtdate.com/warrants/9d2b6e14/document.pdf?expires=1755616800&signature=…
                attachments:
                  - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    original_filename: physician-certificate.pdf
                    content_type: application/pdf
                    file_size: 284913
                    resource_type: SIGNATURE
                    resource_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    download_url: https://files.warrants.ecourtdate.com/agencies/4f0c9d2e/warrants/9d2b6e14/physician-certificate.pdf?expires=1755616800&signature=…
                    uploaded_by: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    created_at: 2026-08-19T14:32:07Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/warrants/{warrantId}/restore:
    patch:
      operationId: restoreWarrant
      summary: Restore from trash
      description: Restores a trashed application to its previous state.
      tags:
        - Warrant workflow
      parameters:
        - name: warrantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Warrant Id
          description: Filter to one warrant application.
          example: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: warrants:write
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Warrant"
              example:
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                creator_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                template_id: c47b2a91-5e3d-4f88-b0a2-7d1c6e9f4a53
                warrant_number: EW-2026-004182
                status: DRAFT
                priority: LOW
                visibility: PUBLIC
                slug: ew-2026-004182-f3a91c
                form_data: *a7
                judge_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                judge_name: Hon. Maria Alvarez
                judge_signature: *a8
                assigned_user_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                assigned_user_name: Hon. Maria Alvarez
                assigned_at: 2026-08-19T14:41:22Z
                assigned_by_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                assignment_mode: MANUAL
                created_at: 2026-08-19T14:32:07Z
                submitted_at: 2026-08-19T14:41:19Z
                signed_at: 2026-08-19T15:04:51Z
                expires_at: 2026-08-26T15:04:51Z
                deleted_at: null
                comments:
                  - text: Attaching the signed physician certificate.
                    is_internal: false
                    id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    warrant_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    author_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    author_name: Dr. Alex Chen
                    author_role: PHYSICIAN
                    mentions:
                      - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                        full_name: Hon. Maria Alvarez
                        role: PHYSICIAN
                    created_at: 2026-08-19T14:32:07Z
                creator_name: Dr. Alex Chen
                creator_role: PHYSICIAN
                warnings:
                  - string
                document_html: <article class="warrant"><h1>Application for Emergency Detention</h1></article>
                document_updated_at: 2026-08-19T15:04:51Z
                allow_document_editing: false
                pdf_url: https://files.warrants.ecourtdate.com/warrants/9d2b6e14/document.pdf?expires=1755616800&signature=…
                attachments:
                  - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    original_filename: physician-certificate.pdf
                    content_type: application/pdf
                    file_size: 284913
                    resource_type: SIGNATURE
                    resource_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    download_url: https://files.warrants.ecourtdate.com/agencies/4f0c9d2e/warrants/9d2b6e14/physician-certificate.pdf?expires=1755616800&signature=…
                    uploaded_by: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    created_at: 2026-08-19T14:32:07Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/warrants/{warrantId}/sign:
    patch:
      operationId: signWarrant
      summary: Sign a warrant
      description: Signs a `SUBMITTED` application, moving it to `SIGNED`, and renders the signed document. Signing applies the signing judge's stored signature and is recorded in the audit trail against that person, so the call must identify them with `X-On-Behalf-Of`. A warrant can only be signed once.
      tags:
        - Warrant workflow
      parameters:
        - name: warrantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Warrant Id
          description: Filter to one warrant application.
          example: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: warrants:sign
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Warrant"
              example:
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                creator_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                template_id: c47b2a91-5e3d-4f88-b0a2-7d1c6e9f4a53
                warrant_number: EW-2026-004182
                status: DRAFT
                priority: LOW
                visibility: PUBLIC
                slug: ew-2026-004182-f3a91c
                form_data: *a7
                judge_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                judge_name: Hon. Maria Alvarez
                judge_signature: *a8
                assigned_user_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                assigned_user_name: Hon. Maria Alvarez
                assigned_at: 2026-08-19T14:41:22Z
                assigned_by_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                assignment_mode: MANUAL
                created_at: 2026-08-19T14:32:07Z
                submitted_at: 2026-08-19T14:41:19Z
                signed_at: 2026-08-19T15:04:51Z
                expires_at: 2026-08-26T15:04:51Z
                deleted_at: null
                comments:
                  - text: Attaching the signed physician certificate.
                    is_internal: false
                    id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    warrant_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    author_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    author_name: Dr. Alex Chen
                    author_role: PHYSICIAN
                    mentions:
                      - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                        full_name: Hon. Maria Alvarez
                        role: PHYSICIAN
                    created_at: 2026-08-19T14:32:07Z
                creator_name: Dr. Alex Chen
                creator_role: PHYSICIAN
                warnings:
                  - string
                document_html: <article class="warrant"><h1>Application for Emergency Detention</h1></article>
                document_updated_at: 2026-08-19T15:04:51Z
                allow_document_editing: false
                pdf_url: https://files.warrants.ecourtdate.com/warrants/9d2b6e14/document.pdf?expires=1755616800&signature=…
                attachments:
                  - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    original_filename: physician-certificate.pdf
                    content_type: application/pdf
                    file_size: 284913
                    resource_type: SIGNATURE
                    resource_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    download_url: https://files.warrants.ecourtdate.com/agencies/4f0c9d2e/warrants/9d2b6e14/physician-certificate.pdf?expires=1755616800&signature=…
                    uploaded_by: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    created_at: 2026-08-19T14:32:07Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/warrants/{warrantId}/submit:
    patch:
      operationId: submitWarrant
      summary: Submit for review
      description: Moves a `DRAFT` application to `SUBMITTED` and routes it for review. Pass `assigned_judge_id` to route to a specific judge; omit the body to let the agency's routing mode decide. Only the person who created the application can submit it.
      tags:
        - Warrant workflow
      parameters:
        - name: warrantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Warrant Id
          description: Filter to one warrant application.
          example: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: warrants:submit
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
                - $ref: "#/components/schemas/WarrantSubmitRequest"
                - type: "null"
              title: Submit Data
            example:
              assigned_judge_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
        required: true
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Warrant"
              example:
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                creator_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                template_id: c47b2a91-5e3d-4f88-b0a2-7d1c6e9f4a53
                warrant_number: EW-2026-004182
                status: DRAFT
                priority: LOW
                visibility: PUBLIC
                slug: ew-2026-004182-f3a91c
                form_data: *a7
                judge_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                judge_name: Hon. Maria Alvarez
                judge_signature: *a8
                assigned_user_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                assigned_user_name: Hon. Maria Alvarez
                assigned_at: 2026-08-19T14:41:22Z
                assigned_by_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                assignment_mode: MANUAL
                created_at: 2026-08-19T14:32:07Z
                submitted_at: 2026-08-19T14:41:19Z
                signed_at: 2026-08-19T15:04:51Z
                expires_at: 2026-08-26T15:04:51Z
                deleted_at: null
                comments:
                  - text: Attaching the signed physician certificate.
                    is_internal: false
                    id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    warrant_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    author_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    author_name: Dr. Alex Chen
                    author_role: PHYSICIAN
                    mentions:
                      - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                        full_name: Hon. Maria Alvarez
                        role: PHYSICIAN
                    created_at: 2026-08-19T14:32:07Z
                creator_name: Dr. Alex Chen
                creator_role: PHYSICIAN
                warnings:
                  - string
                document_html: <article class="warrant"><h1>Application for Emergency Detention</h1></article>
                document_updated_at: 2026-08-19T15:04:51Z
                allow_document_editing: false
                pdf_url: https://files.warrants.ecourtdate.com/warrants/9d2b6e14/document.pdf?expires=1755616800&signature=…
                attachments:
                  - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    original_filename: physician-certificate.pdf
                    content_type: application/pdf
                    file_size: 284913
                    resource_type: SIGNATURE
                    resource_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    download_url: https://files.warrants.ecourtdate.com/agencies/4f0c9d2e/warrants/9d2b6e14/physician-certificate.pdf?expires=1755616800&signature=…
                    uploaded_by: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    created_at: 2026-08-19T14:32:07Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "422":
          description: The request body failed validation. `param` names the field.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: form_data is required.
                  type: invalid_request_error
                  code: validation_failed
                  param: form_data
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/warrants/{warrantId}/trash:
    patch:
      operationId: trashWarrant
      summary: Move to trash
      description: Soft-deletes an application. Trashed applications stay listable with `trashed_only=true` and can be restored.
      tags:
        - Warrant workflow
      parameters:
        - name: warrantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Warrant Id
          description: Filter to one warrant application.
          example: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: warrants:write
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Warrant"
              example:
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                creator_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                template_id: c47b2a91-5e3d-4f88-b0a2-7d1c6e9f4a53
                warrant_number: EW-2026-004182
                status: DRAFT
                priority: LOW
                visibility: PUBLIC
                slug: ew-2026-004182-f3a91c
                form_data: *a7
                judge_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                judge_name: Hon. Maria Alvarez
                judge_signature: *a8
                assigned_user_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                assigned_user_name: Hon. Maria Alvarez
                assigned_at: 2026-08-19T14:41:22Z
                assigned_by_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                assignment_mode: MANUAL
                created_at: 2026-08-19T14:32:07Z
                submitted_at: 2026-08-19T14:41:19Z
                signed_at: 2026-08-19T15:04:51Z
                expires_at: 2026-08-26T15:04:51Z
                deleted_at: null
                comments:
                  - text: Attaching the signed physician certificate.
                    is_internal: false
                    id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    warrant_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    author_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    author_name: Dr. Alex Chen
                    author_role: PHYSICIAN
                    mentions:
                      - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                        full_name: Hon. Maria Alvarez
                        role: PHYSICIAN
                    created_at: 2026-08-19T14:32:07Z
                creator_name: Dr. Alex Chen
                creator_role: PHYSICIAN
                warnings:
                  - string
                document_html: <article class="warrant"><h1>Application for Emergency Detention</h1></article>
                document_updated_at: 2026-08-19T15:04:51Z
                allow_document_editing: false
                pdf_url: https://files.warrants.ecourtdate.com/warrants/9d2b6e14/document.pdf?expires=1755616800&signature=…
                attachments:
                  - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    original_filename: physician-certificate.pdf
                    content_type: application/pdf
                    file_size: 284913
                    resource_type: SIGNATURE
                    resource_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    download_url: https://files.warrants.ecourtdate.com/agencies/4f0c9d2e/warrants/9d2b6e14/physician-certificate.pdf?expires=1755616800&signature=…
                    uploaded_by: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    created_at: 2026-08-19T14:32:07Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/warrants/{warrantId}/visibility:
    patch:
      operationId: updateWarrantVisibility
      summary: Set visibility
      description: Sets an application to `PUBLIC` or `PRIVATE`. A `PUBLIC` application is readable through its [public link](#tag/public/operation/getPublicWarrant) without a key. Read [public links](https://docs.warrants.ecourtdate.com/guides/public-links) before publishing anything.
      tags:
        - Warrant workflow
      parameters:
        - name: warrantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Warrant Id
          description: Filter to one warrant application.
          example: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
        - name: X-On-Behalf-Of
          in: header
          required: true
          description: The person this call is made for, as an email address or user id. Recorded in the audit trail against the resulting action.
          schema:
            type: string
            minLength: 1
            maxLength: 128
          example: judge.alvarez@example.gov
      x-scope: warrants:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WarrantVisibilityRequest"
            example:
              visibility: PUBLIC
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Warrant"
              example:
                id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                agency_id: 4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40
                creator_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                template_id: c47b2a91-5e3d-4f88-b0a2-7d1c6e9f4a53
                warrant_number: EW-2026-004182
                status: DRAFT
                priority: LOW
                visibility: PUBLIC
                slug: ew-2026-004182-f3a91c
                form_data: *a7
                judge_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                judge_name: Hon. Maria Alvarez
                judge_signature: *a8
                assigned_user_id: a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90
                assigned_user_name: Hon. Maria Alvarez
                assigned_at: 2026-08-19T14:41:22Z
                assigned_by_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                assignment_mode: MANUAL
                created_at: 2026-08-19T14:32:07Z
                submitted_at: 2026-08-19T14:41:19Z
                signed_at: 2026-08-19T15:04:51Z
                expires_at: 2026-08-26T15:04:51Z
                deleted_at: null
                comments:
                  - text: Attaching the signed physician certificate.
                    is_internal: false
                    id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    warrant_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    author_id: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    author_name: Dr. Alex Chen
                    author_role: PHYSICIAN
                    mentions:
                      - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                        full_name: Hon. Maria Alvarez
                        role: PHYSICIAN
                    created_at: 2026-08-19T14:32:07Z
                creator_name: Dr. Alex Chen
                creator_role: PHYSICIAN
                warnings:
                  - string
                document_html: <article class="warrant"><h1>Application for Emergency Detention</h1></article>
                document_updated_at: 2026-08-19T15:04:51Z
                allow_document_editing: false
                pdf_url: https://files.warrants.ecourtdate.com/warrants/9d2b6e14/document.pdf?expires=1755616800&signature=…
                attachments:
                  - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    original_filename: physician-certificate.pdf
                    content_type: application/pdf
                    file_size: 284913
                    resource_type: SIGNATURE
                    resource_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    download_url: https://files.warrants.ecourtdate.com/agencies/4f0c9d2e/warrants/9d2b6e14/physician-certificate.pdf?expires=1755616800&signature=…
                    uploaded_by: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    created_at: 2026-08-19T14:32:07Z
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "409":
          description: The resource is not in a state that allows this operation, or another caller holds the edit lock.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: The warrant application is not in a state that allows this operation.
                  type: conflict_error
                  code: invalid_transition
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "422":
          description: The request body failed validation. `param` names the field.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: form_data is required.
                  type: invalid_request_error
                  code: validation_failed
                  param: form_data
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/warrants/assignable-judges:
    get:
      operationId: listAssignableJudges
      summary: List assignable judges
      description: Lists the judges in the agency that a submitted application can be routed to, with the count of applications already assigned to each. Use it to populate a routing picker.
      tags:
        - Warrants
      x-scope: warrants:read
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AssignableJudge"
                title: Response Get Assignable Judges V1 Warrants Assignable Judges Get
              example:
                - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                  full_name: Hon. Maria Alvarez
                  email: judge.alvarez@example.gov
                  on_dnd: false
                  open_warrants: 2
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "400":
          description: The request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Priority must be one of LOW, STANDARD, URGENT.
                  type: invalid_request_error
                  code: invalid_request
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "401":
          description: No API key was supplied, or the key is invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: No API key supplied. Send your key in the x-api-key header.
                  type: authentication_error
                  code: missing_api_key
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "403":
          description: The key is valid but lacks the scope or permission this operation requires.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: This key does not carry the required scope.
                  type: permission_error
                  code: insufficient_scope
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
  /v1/warrants/public/{slug}:
    get:
      operationId: getPublicWarrant
      summary: Retrieve a public warrant
      description: Returns a warrant application that has been published with a public link. Takes no API key and returns only the published fields. Applications that are not `PUBLIC` return `404`.
      tags:
        - Public
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
            title: Slug
          description: Public link identifier.
          example: ew-2026-004182-f3a91c
      security: []
      responses:
        "200":
          description: Success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicWarrant"
              example:
                slug: ew-2026-004182-f3a91c
                warrant_number: EW-2026-004182
                status: DRAFT
                template_id: c47b2a91-5e3d-4f88-b0a2-7d1c6e9f4a53
                form_data: *a7
                document_html: <article class="warrant"><h1>Application for Emergency Detention</h1></article>
                judge_name: Hon. Maria Alvarez
                judge_signature: *a8
                created_at: 2026-08-19T14:32:07Z
                signed_at: 2026-08-19T15:04:51Z
                expires_at: 2026-08-26T15:04:51Z
                agency_name: Travis County Health District
                pdf_url: https://files.warrants.ecourtdate.com/warrants/9d2b6e14/document.pdf?expires=1755616800&signature=…
                attachments:
                  - id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    original_filename: physician-certificate.pdf
                    content_type: application/pdf
                    file_size: 284913
                    resource_type: SIGNATURE
                    resource_id: 9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10
                    download_url: https://files.warrants.ecourtdate.com/agencies/4f0c9d2e/warrants/9d2b6e14/physician-certificate.pdf?expires=1755616800&signature=…
                    uploaded_by: 6b1e8f22-0d4c-4a7e-8f31-2a9c5d0b7e64
                    created_at: 2026-08-19T14:32:07Z
                template:
                  name: Emergency Detention (Form MH-101)
                  base_image: https://files.warrants.ecourtdate.com/templates/c47b2a91/base.png
                  base_document_content_type: application/pdf
                  elements:
                    - {}
                  template_html: <section data-field="subject_name"></section>
          headers:
            RateLimit-Limit: *a1
            RateLimit-Remaining: *a2
            RateLimit-Reset: *a3
            X-Request-ID: *a4
        "404":
          description: No such resource in this agency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Warrant application not found.
                  type: invalid_request_error
                  code: not_found
                  param: null
                  request_id: req_01HZY5R2K3Q9
        "429":
          description: Too many requests. Back off and retry after the interval in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Rate limit exceeded. Retry after 30 seconds.
                  type: rate_limit_error
                  code: rate_limit_exceeded
                  param: null
                  request_id: req_01HZY5R2K3Q9
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 30
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  message: Something went wrong on our end.
                  type: server_error
                  code: server_error
                  param: null
                  request_id: req_01HZY5R2K3Q9
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: "API key issued for your agency. Send it on every authenticated request. Keys are secrets: keep them server-side."
  schemas:
    AgencySettings:
      type: object
      title: AgencySettings
      description: Agency-wide warrant configuration. Unknown keys are accepted and returned unchanged, so an agency can carry its own settings alongside these.
      additionalProperties: true
      properties:
        agencyName:
          type: string
          description: Agency name shown on documents and public links.
        address:
          type: string
          description: Street address.
        city:
          type: string
          description: City.
        county:
          type: string
          description: County.
        state:
          type: string
          description: Two-letter state code.
        zipCode:
          type: string
          description: Postal code.
        courtName:
          type: string
          description: Name of the court that signs warrants, for example "District Court".
        timezone:
          type: string
          description: IANA timezone used to localize signing times, for example "America/Chicago".
        contactPhone:
          type: string
          description: Public contact number.
        logoUrl:
          type: string
          description: URL of the agency logo used on documents and public links.
        isConfigured:
          type: boolean
          description: Whether agency onboarding is complete.
        judgeNotifyMethod:
          type: string
          enum:
            - BLAST
            - ROUND_ROBIN
            - MANUAL
          description: "How a submitted application is routed: to the whole bench, to the next judge in rotation, or to a judge chosen at submission."
        notifyOnStandard:
          type: boolean
          description: Notify judges for STANDARD priority applications.
        notifyOnUrgent:
          type: boolean
          description: Notify judges for URGENT priority applications.
        escalationTimeoutMinutes:
          type: integer
          description: Minutes before an assigned but unactioned STANDARD application escalates to the whole bench. 0 disables escalation.
        escalationTimeoutMinutesUrgent:
          type: integer
          description: Minutes before an assigned but unactioned URGENT application escalates to the whole bench. 0 disables escalation.
        enabledTemplates:
          type: array
          items:
            type: string
          description: Identifiers of the templates an applicant may choose from.
    AgencySettingsUpdate:
      type: object
      title: AgencySettingsUpdate
      description: Agency settings to change. Only the keys present in the request are updated; everything else is left as it is.
      additionalProperties: true
      properties:
        agencyName:
          type: string
          description: Agency name shown on documents and public links.
        address:
          type: string
          description: Street address.
        city:
          type: string
          description: City.
        county:
          type: string
          description: County.
        state:
          type: string
          description: Two-letter state code.
        zipCode:
          type: string
          description: Postal code.
        courtName:
          type: string
          description: Name of the court that signs warrants, for example "District Court".
        timezone:
          type: string
          description: IANA timezone used to localize signing times, for example "America/Chicago".
        contactPhone:
          type: string
          description: Public contact number.
        logoUrl:
          type: string
          description: URL of the agency logo used on documents and public links.
        isConfigured:
          type: boolean
          description: Whether agency onboarding is complete.
        judgeNotifyMethod:
          type: string
          enum:
            - BLAST
            - ROUND_ROBIN
            - MANUAL
          description: "How a submitted application is routed: to the whole bench, to the next judge in rotation, or to a judge chosen at submission."
        notifyOnStandard:
          type: boolean
          description: Notify judges for STANDARD priority applications.
        notifyOnUrgent:
          type: boolean
          description: Notify judges for URGENT priority applications.
        escalationTimeoutMinutes:
          type: integer
          description: Minutes before an assigned but unactioned STANDARD application escalates to the whole bench. 0 disables escalation.
        escalationTimeoutMinutesUrgent:
          type: integer
          description: Minutes before an assigned but unactioned URGENT application escalates to the whole bench. 0 disables escalation.
        enabledTemplates:
          type: array
          items:
            type: string
          description: Identifiers of the templates an applicant may choose from.
    AssignableJudge:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        full_name:
          anyOf:
            - type: string
            - type: "null"
          title: Full Name
        email:
          type: string
          title: Email
        on_dnd:
          type: boolean
          title: On Dnd
          default: false
        open_warrants:
          type: integer
          title: Open Warrants
          default: 0
      type: object
      required:
        - id
        - email
      title: AssignableJudge
      description: A judge who can receive an assignment, with the context to choose one.
    AuditAction:
      type: string
      enum:
        - CREATE
        - UPDATE
        - DELETE
        - VIEW
        - SUBMIT
        - SIGN
        - REJECT
        - LOGIN
        - LOGOUT
        - UPLOAD
        - DOWNLOAD
        - RECORDING_CONSENT
        - CALL_STARTED
        - CALL_JOINED
        - CALL_LEFT
        - CALL_ENDED
        - CALL_INVITED
        - RECORDING_STARTED
        - RECORDING_STOPPED
        - TRASH
        - RESTORE
        - COLLABORATE
        - ASSIGN
        - REASSIGN
        - UNASSIGN
        - ESCALATE
      title: AuditAction
      description: Audit action types
    AuditLogEntry:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        agency_id:
          type: string
          format: uuid
          title: Agency Id
        user_id:
          anyOf:
            - type: string
              format: uuid
            - type: "null"
          title: User Id
        warrant_id:
          anyOf:
            - type: string
              format: uuid
            - type: "null"
          title: Warrant Id
        action:
          $ref: "#/components/schemas/AuditAction"
        resource_type:
          type: string
          title: Resource Type
        resource_id:
          anyOf:
            - type: string
              format: uuid
            - type: "null"
          title: Resource Id
        details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Details
        ip_address:
          anyOf:
            - type: string
            - type: "null"
          title: Ip Address
        user_agent:
          anyOf:
            - type: string
            - type: "null"
          title: User Agent
        created_at:
          type: string
          format: date-time
          title: Created At
        user_name:
          anyOf:
            - type: string
            - type: "null"
          title: User Name
        user_email:
          anyOf:
            - type: string
            - type: "null"
          title: User Email
      type: object
      required:
        - id
        - agency_id
        - user_id
        - warrant_id
        - action
        - resource_type
        - resource_id
        - details
        - ip_address
        - user_agent
        - created_at
      title: AuditLogEntry
    Comment:
      properties:
        text:
          type: string
          maxLength: 10000
          minLength: 1
          title: Text
        is_internal:
          type: boolean
          title: Is Internal
          default: false
        id:
          type: string
          format: uuid
          title: Id
        warrant_id:
          type: string
          format: uuid
          title: Warrant Id
        author_id:
          anyOf:
            - type: string
              format: uuid
            - type: "null"
          title: Author Id
        author_name:
          anyOf:
            - type: string
            - type: "null"
          title: Author Name
        author_role:
          anyOf:
            - $ref: "#/components/schemas/UserRole"
            - type: "null"
        mentions:
          anyOf:
            - items:
                $ref: "#/components/schemas/MentionedUser"
              type: array
            - type: "null"
          title: Mentions
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - text
        - id
        - warrant_id
        - author_id
        - created_at
      title: Comment
      description: Comment response schema
    CommentCreate:
      properties:
        text:
          type: string
          maxLength: 10000
          minLength: 1
          title: Text
        is_internal:
          type: boolean
          title: Is Internal
          default: false
        mention_ids:
          anyOf:
            - items:
                type: string
                format: uuid
              type: array
            - type: "null"
          title: Mention Ids
      type: object
      required:
        - text
      title: CommentCreate
      description: Create comment schema
    ConfirmUploadRequest:
      properties:
        file_id:
          type: string
          format: uuid
          title: File Id
        storage_key:
          type: string
          title: Storage Key
      type: object
      required:
        - file_id
        - storage_key
      title: ConfirmUploadRequest
      description: Confirms that an upload arrived, so the attachment becomes part of the warrant application.
    DocumentStyle:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        slug:
          type: string
          title: Slug
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: "null"
          title: Description
        agency_id:
          anyOf:
            - type: string
              format: uuid
            - type: "null"
          title: Agency Id
        css:
          type: string
          title: Css
        is_active:
          type: boolean
          title: Is Active
        is_system:
          type: boolean
          title: Is System
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - id
        - slug
        - name
        - css
        - is_active
        - is_system
        - created_at
        - updated_at
      title: DocumentStyle
      description: Shape returned by GET /v1/document-styles.
    Error:
      type: object
      title: Error
      description: Every error response uses this envelope. `code` is stable and safe to branch on; `message` is written for a person and may change.
      required:
        - error
      additionalProperties: false
      properties:
        error:
          type: object
          required:
            - message
            - type
            - code
          additionalProperties: false
          properties:
            message:
              type: string
              description: Human-readable description of what went wrong.
            type:
              type: string
              enum:
                - invalid_request_error
                - authentication_error
                - permission_error
                - conflict_error
                - rate_limit_error
                - server_error
              description: Broad class of the error.
            code:
              type: string
              description: Stable machine-readable code. See the errors guide for the registry.
              enum:
                - missing_api_key
                - invalid_api_key
                - insufficient_scope
                - insufficient_permission
                - missing_actor
                - unknown_actor
                - not_found
                - invalid_request
                - validation_failed
                - invalid_transition
                - warrant_locked
                - lock_held
                - already_exists
                - rate_limit_exceeded
                - server_error
            param:
              type:
                - string
                - "null"
              description: The request field the error refers to, in bracket form (`form_data[patient_name]`), or null.
            request_id:
              type:
                - string
                - "null"
              description: Identifier of this request, echoed in the `X-Request-ID` header. Quote it in support requests.
    File:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        original_filename:
          type: string
          title: Original Filename
        content_type:
          type: string
          title: Content Type
        file_size:
          anyOf:
            - type: integer
            - type: "null"
          title: File Size
        resource_type:
          $ref: "#/components/schemas/FileResourceType"
        resource_id:
          anyOf:
            - type: string
              format: uuid
            - type: "null"
          title: Resource Id
        download_url:
          anyOf:
            - type: string
            - type: "null"
          title: Download Url
        uploaded_by:
          anyOf:
            - type: string
              format: uuid
            - type: "null"
          title: Uploaded By
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - id
        - original_filename
        - content_type
        - resource_type
        - created_at
      title: File
      description: File metadata response.
    FileList:
      properties:
        files:
          items:
            $ref: "#/components/schemas/File"
          type: array
          title: Files
        total:
          type: integer
          title: Total
      type: object
      required:
        - files
        - total
      title: FileList
      description: Paginated file list response.
    FileResourceType:
      type: string
      enum:
        - SIGNATURE
        - ATTACHMENT
        - RECORDING
        - TRANSCRIPT
        - WARRANT_PDF
        - TEMPLATE_DOCUMENT
        - BRANDING_LOGO
        - BRANDING_ICON
        - BRANDING_SEAL
      title: FileResourceType
    Location:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
        type:
          anyOf:
            - type: string
              maxLength: 100
            - type: "null"
          title: Type
        address:
          type: string
          maxLength: 255
          minLength: 1
          title: Address
        city:
          type: string
          maxLength: 100
          minLength: 1
          title: City
        state:
          type: string
          maxLength: 50
          minLength: 1
          title: State
        zip_code:
          type: string
          maxLength: 20
          minLength: 1
          title: Zip Code
        county:
          anyOf:
            - type: string
              maxLength: 100
            - type: "null"
          title: County
        phone:
          anyOf:
            - type: string
              maxLength: 20
            - type: "null"
          title: Phone
        fax:
          anyOf:
            - type: string
              maxLength: 20
            - type: "null"
          title: Fax
        email:
          anyOf:
            - type: string
              format: email
            - type: "null"
          title: Email
        contact_person:
          anyOf:
            - type: string
              maxLength: 255
            - type: "null"
          title: Contact Person
        notes:
          anyOf:
            - type: string
            - type: "null"
          title: Notes
        id:
          type: string
          format: uuid
          title: Id
        agency_id:
          type: string
          format: uuid
          title: Agency Id
        is_active:
          type: boolean
          title: Is Active
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - name
        - address
        - city
        - state
        - zip_code
        - id
        - agency_id
        - is_active
        - created_at
        - updated_at
      title: Location
      description: Full location response schema
    LocationCreate:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
        type:
          anyOf:
            - type: string
              maxLength: 100
            - type: "null"
          title: Type
        address:
          type: string
          maxLength: 255
          minLength: 1
          title: Address
        city:
          type: string
          maxLength: 100
          minLength: 1
          title: City
        state:
          type: string
          maxLength: 50
          minLength: 1
          title: State
        zip_code:
          type: string
          maxLength: 20
          minLength: 1
          title: Zip Code
        county:
          anyOf:
            - type: string
              maxLength: 100
            - type: "null"
          title: County
        phone:
          anyOf:
            - type: string
              maxLength: 20
            - type: "null"
          title: Phone
        fax:
          anyOf:
            - type: string
              maxLength: 20
            - type: "null"
          title: Fax
        email:
          anyOf:
            - type: string
              format: email
            - type: "null"
          title: Email
        contact_person:
          anyOf:
            - type: string
              maxLength: 255
            - type: "null"
          title: Contact Person
        notes:
          anyOf:
            - type: string
            - type: "null"
          title: Notes
        is_active:
          type: boolean
          title: Is Active
          default: true
      type: object
      required:
        - name
        - address
        - city
        - state
        - zip_code
      title: LocationCreate
      description: Schema for creating a new location
    LocationListItem:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        agency_id:
          type: string
          format: uuid
          title: Agency Id
        name:
          type: string
          title: Name
        type:
          anyOf:
            - type: string
            - type: "null"
          title: Type
        is_active:
          type: boolean
          title: Is Active
        address:
          type: string
          title: Address
        city:
          type: string
          title: City
        state:
          type: string
          title: State
        zip_code:
          type: string
          title: Zip Code
        county:
          anyOf:
            - type: string
            - type: "null"
          title: County
        phone:
          anyOf:
            - type: string
            - type: "null"
          title: Phone
        fax:
          anyOf:
            - type: string
            - type: "null"
          title: Fax
        email:
          anyOf:
            - type: string
              format: email
            - type: "null"
          title: Email
        contact_person:
          anyOf:
            - type: string
            - type: "null"
          title: Contact Person
        notes:
          anyOf:
            - type: string
            - type: "null"
          title: Notes
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - id
        - agency_id
        - name
        - type
        - is_active
        - address
        - city
        - state
        - zip_code
        - county
        - phone
        - fax
        - email
        - contact_person
        - notes
        - created_at
        - updated_at
      title: LocationListItem
      description: Location response for list views.
    LocationUpdate:
      properties:
        name:
          anyOf:
            - type: string
              maxLength: 255
              minLength: 1
            - type: "null"
          title: Name
        type:
          anyOf:
            - type: string
              maxLength: 100
            - type: "null"
          title: Type
        is_active:
          anyOf:
            - type: boolean
            - type: "null"
          title: Is Active
        address:
          anyOf:
            - type: string
              maxLength: 255
              minLength: 1
            - type: "null"
          title: Address
        city:
          anyOf:
            - type: string
              maxLength: 100
              minLength: 1
            - type: "null"
          title: City
        state:
          anyOf:
            - type: string
              maxLength: 50
              minLength: 1
            - type: "null"
          title: State
        zip_code:
          anyOf:
            - type: string
              maxLength: 20
              minLength: 1
            - type: "null"
          title: Zip Code
        county:
          anyOf:
            - type: string
              maxLength: 100
            - type: "null"
          title: County
        phone:
          anyOf:
            - type: string
              maxLength: 20
            - type: "null"
          title: Phone
        fax:
          anyOf:
            - type: string
              maxLength: 20
            - type: "null"
          title: Fax
        email:
          anyOf:
            - type: string
              format: email
            - type: "null"
          title: Email
        contact_person:
          anyOf:
            - type: string
              maxLength: 255
            - type: "null"
          title: Contact Person
        notes:
          anyOf:
            - type: string
            - type: "null"
          title: Notes
      type: object
      title: LocationUpdate
      description: Schema for updating a location - all fields optional
    Member:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        full_name:
          type: string
          title: Full Name
        role:
          type: string
          title: Role
      type: object
      required:
        - id
        - full_name
        - role
      title: Member
      description: Lightweight member info for @mention autocomplete
    MentionedUser:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        full_name:
          type: string
          title: Full Name
        role:
          anyOf:
            - $ref: "#/components/schemas/UserRole"
            - type: "null"
      type: object
      required:
        - id
        - full_name
      title: MentionedUser
      description: Resolved mention user info
    Permission:
      properties:
        key:
          type: string
          title: Key
        label:
          type: string
          title: Label
        description:
          type: string
          title: Description
      type: object
      required:
        - key
        - label
        - description
      title: Permission
    PermissionCatalog:
      properties:
        categories:
          items:
            $ref: "#/components/schemas/PermissionCategory"
          type: array
          title: Categories
      type: object
      required:
        - categories
      title: PermissionCatalog
      description: Grouped permission catalog for the role-builder UI.
    PermissionCategory:
      properties:
        category:
          type: string
          title: Category
        permissions:
          items:
            $ref: "#/components/schemas/Permission"
          type: array
          title: Permissions
      type: object
      required:
        - category
        - permissions
      title: PermissionCategory
    PresignedUpload:
      properties:
        file_id:
          type: string
          format: uuid
          title: File Id
        upload_url:
          type: string
          title: Upload Url
        storage_key:
          type: string
          title: Storage Key
        expires_in:
          type: integer
          title: Expires In
      type: object
      required:
        - file_id
        - upload_url
        - storage_key
        - expires_in
      title: PresignedUpload
      description: A short-lived URL to upload file bytes to, and the identifiers needed to confirm the upload afterwards.
    PresignRequest:
      properties:
        filename:
          type: string
          maxLength: 255
          minLength: 1
          title: Filename
        content_type:
          type: string
          maxLength: 100
          minLength: 1
          title: Content Type
        resource_type:
          $ref: "#/components/schemas/FileResourceType"
        resource_id:
          anyOf:
            - type: string
              format: uuid
            - type: "null"
          title: Resource Id
      type: object
      required:
        - filename
        - content_type
        - resource_type
      title: PresignRequest
      description: Request a presigned upload URL.
    ProcessDocumentRequest:
      properties:
        storage_key:
          type: string
          title: Storage Key
        content_type:
          type: string
          title: Content Type
      type: object
      required:
        - storage_key
        - content_type
      title: ProcessDocumentRequest
      description: An uploaded document to convert so it can back a template.
    ProcessedDocument:
      properties:
        storage_key:
          type: string
          title: Storage Key
        content_type:
          type: string
          title: Content Type
      type: object
      required:
        - storage_key
        - content_type
      title: ProcessedDocument
      description: The converted document, ready to be set as a template's base document.
    PublicAgency:
      properties:
        name:
          type: string
          title: Name
        address:
          anyOf:
            - type: string
            - type: "null"
          title: Address
        county:
          anyOf:
            - type: string
            - type: "null"
          title: County
        state:
          anyOf:
            - type: string
            - type: "null"
          title: State
        court_name:
          anyOf:
            - type: string
            - type: "null"
          title: Court Name
        timezone:
          type: string
          title: Timezone
          default: America/Chicago
        contact_phone:
          anyOf:
            - type: string
            - type: "null"
          title: Contact Phone
        logo:
          anyOf:
            - type: string
            - type: "null"
          title: Logo
      type: object
      required:
        - name
      title: PublicAgency
      description: Public agency response - minimal info for public warrant display
    PublicTemplate:
      properties:
        name:
          type: string
          title: Name
        base_image:
          anyOf:
            - type: string
            - type: "null"
          title: Base Image
        base_document_content_type:
          anyOf:
            - type: string
            - type: "null"
          title: Base Document Content Type
        elements:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Elements
          default: []
        template_html:
          anyOf:
            - type: string
            - type: "null"
          title: Template Html
      type: object
      required:
        - name
      title: PublicTemplate
      description: Template info included in public warrant responses for custom templates.
    PublicWarrant:
      properties:
        slug:
          type: string
          title: Slug
        warrant_number:
          anyOf:
            - type: string
            - type: "null"
          title: Warrant Number
        status:
          $ref: "#/components/schemas/WarrantStatus"
        template_id:
          anyOf:
            - type: string
            - type: "null"
          title: Template Id
        form_data:
          additionalProperties: true
          type: object
          title: Form Data
        document_html:
          anyOf:
            - type: string
            - type: "null"
          title: Document Html
        judge_name:
          anyOf:
            - type: string
            - type: "null"
          title: Judge Name
        judge_signature:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Judge Signature
        created_at:
          type: string
          format: date-time
          title: Created At
        signed_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Signed At
        expires_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Expires At
        agency_name:
          type: string
          title: Agency Name
        pdf_url:
          anyOf:
            - type: string
            - type: "null"
          title: Pdf Url
        attachments:
          items:
            $ref: "#/components/schemas/File"
          type: array
          title: Attachments
          default: []
        template:
          anyOf:
            - $ref: "#/components/schemas/PublicTemplate"
            - type: "null"
      type: object
      required:
        - slug
        - warrant_number
        - status
        - form_data
        - created_at
        - signed_at
        - agency_name
      title: PublicWarrant
      description: Public warrant response - equivalent to PDF form. Only exposes information needed for public verification of signed warrants.
    Role:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        agency_id:
          anyOf:
            - type: string
              format: uuid
            - type: "null"
          title: Agency Id
        key:
          type: string
          title: Key
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: "null"
          title: Description
        is_system:
          type: boolean
          title: Is System
        is_active:
          type: boolean
          title: Is Active
        color:
          anyOf:
            - type: string
            - type: "null"
          title: Color
        icon:
          anyOf:
            - type: string
            - type: "null"
          title: Icon
        scope:
          type: string
          title: Scope
        permissions:
          items:
            type: string
          type: array
          title: Permissions
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - id
        - key
        - name
        - is_system
        - is_active
        - scope
        - permissions
        - created_at
        - updated_at
      title: Role
      description: Shape returned by the roles endpoints.
    RoleCreate:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
        description:
          anyOf:
            - type: string
            - type: "null"
          title: Description
        key:
          anyOf:
            - type: string
              maxLength: 100
            - type: "null"
          title: Key
        color:
          anyOf:
            - type: string
              maxLength: 32
            - type: "null"
          title: Color
        icon:
          anyOf:
            - type: string
              maxLength: 64
            - type: "null"
          title: Icon
        permissions:
          items:
            type: string
          type: array
          title: Permissions
      type: object
      required:
        - name
      title: RoleCreate
      description: Payload for creating a custom role.
    RoleUpdate:
      properties:
        name:
          anyOf:
            - type: string
              maxLength: 255
              minLength: 1
            - type: "null"
          title: Name
        description:
          anyOf:
            - type: string
            - type: "null"
          title: Description
        color:
          anyOf:
            - type: string
              maxLength: 32
            - type: "null"
          title: Color
        icon:
          anyOf:
            - type: string
              maxLength: 64
            - type: "null"
          title: Icon
        is_active:
          anyOf:
            - type: boolean
            - type: "null"
          title: Is Active
        permissions:
          anyOf:
            - items:
                type: string
              type: array
            - type: "null"
          title: Permissions
      type: object
      title: RoleUpdate
      description: Partial update for a custom role. Only provided fields change.
    Template:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
        description:
          anyOf:
            - type: string
              maxLength: 2000
            - type: "null"
          title: Description
        base_image:
          anyOf:
            - type: string
              maxLength: 1000
            - type: "null"
          title: Base Image
        base_document_content_type:
          anyOf:
            - type: string
              maxLength: 255
            - type: "null"
          title: Base Document Content Type
        template_html:
          anyOf:
            - type: string
              maxLength: 2000000
            - type: "null"
          title: Template Html
        elements:
          items:
            $ref: "#/components/schemas/TemplateElement"
          type: array
          maxItems: 1000
          title: Elements
        workflow:
          $ref: "#/components/schemas/TemplateWorkflow"
          default:
            requiresJudgeApproval: true
            notifyOnSubmission: true
            autoExpireHours: 48
            allowedRoles: []
        allow_editing_per_warrant:
          type: boolean
          title: Allow Editing Per Warrant
          default: false
        style_preset:
          anyOf:
            - type: string
            - type: "null"
          title: Style Preset
        id:
          type: string
          format: uuid
          title: Id
        agency_id:
          anyOf:
            - type: string
              format: uuid
            - type: "null"
          title: Agency Id
        created_by_id:
          anyOf:
            - type: string
              format: uuid
            - type: "null"
          title: Created By Id
        is_active:
          type: boolean
          title: Is Active
        is_system_template:
          type: boolean
          title: Is System Template
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - name
        - id
        - agency_id
        - created_by_id
        - is_active
        - is_system_template
        - created_at
        - updated_at
      title: Template
      description: Template response schema
    TemplateCreate:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
        description:
          anyOf:
            - type: string
              maxLength: 2000
            - type: "null"
          title: Description
        base_image:
          anyOf:
            - type: string
              maxLength: 1000
            - type: "null"
          title: Base Image
        base_document_content_type:
          anyOf:
            - type: string
              maxLength: 255
            - type: "null"
          title: Base Document Content Type
        template_html:
          anyOf:
            - type: string
              maxLength: 2000000
            - type: "null"
          title: Template Html
        elements:
          items:
            $ref: "#/components/schemas/TemplateElement"
          type: array
          maxItems: 1000
          title: Elements
        workflow:
          $ref: "#/components/schemas/TemplateWorkflow"
          default:
            requiresJudgeApproval: true
            notifyOnSubmission: true
            autoExpireHours: 48
            allowedRoles: []
        allow_editing_per_warrant:
          type: boolean
          title: Allow Editing Per Warrant
          default: false
        style_preset:
          anyOf:
            - type: string
            - type: "null"
          title: Style Preset
      type: object
      required:
        - name
      title: TemplateCreate
      description: Create template schema.
    TemplateElement:
      properties:
        id:
          type: string
          title: Id
        type:
          type: string
          title: Type
        x:
          anyOf:
            - type: number
            - type: "null"
          title: X
          default: 0
        y:
          anyOf:
            - type: number
            - type: "null"
          title: Y
          default: 0
        width:
          anyOf:
            - type: number
            - type: "null"
          title: Width
          default: 0
        height:
          anyOf:
            - type: number
            - type: "null"
          title: Height
          default: 0
        content:
          anyOf:
            - type: string
            - type: "null"
          title: Content
        fieldId:
          anyOf:
            - type: string
            - type: "null"
          title: Fieldid
        label:
          anyOf:
            - type: string
            - type: "null"
          title: Label
        dataType:
          anyOf:
            - type: string
            - type: "null"
          title: Datatype
        required:
          anyOf:
            - type: boolean
            - type: "null"
          title: Required
        defaultValue:
          anyOf:
            - {}
            - type: "null"
          title: Defaultvalue
        options:
          anyOf:
            - items:
                type: string
              type: array
            - type: "null"
          title: Options
        fontSize:
          anyOf:
            - type: number
            - type: "null"
          title: Fontsize
        fontFamily:
          anyOf:
            - type: string
            - type: "null"
          title: Fontfamily
        fieldMapping:
          anyOf:
            - type: string
            - type: "null"
          title: Fieldmapping
      type: object
      required:
        - id
        - type
      title: TemplateElement
      description: Template element, field metadata for warrant form generation.
    TemplateUpdate:
      properties:
        name:
          anyOf:
            - type: string
              maxLength: 255
              minLength: 1
            - type: "null"
          title: Name
        description:
          anyOf:
            - type: string
              maxLength: 2000
            - type: "null"
          title: Description
        base_image:
          anyOf:
            - type: string
              maxLength: 1000
            - type: "null"
          title: Base Image
        base_document_content_type:
          anyOf:
            - type: string
              maxLength: 255
            - type: "null"
          title: Base Document Content Type
        template_html:
          anyOf:
            - type: string
              maxLength: 2000000
            - type: "null"
          title: Template Html
        elements:
          anyOf:
            - items:
                $ref: "#/components/schemas/TemplateElement"
              type: array
              maxItems: 1000
            - type: "null"
          title: Elements
        workflow:
          anyOf:
            - $ref: "#/components/schemas/TemplateWorkflow"
            - type: "null"
        is_active:
          anyOf:
            - type: boolean
            - type: "null"
          title: Is Active
        allow_editing_per_warrant:
          anyOf:
            - type: boolean
            - type: "null"
          title: Allow Editing Per Warrant
        style_preset:
          anyOf:
            - type: string
            - type: "null"
          title: Style Preset
      type: object
      title: TemplateUpdate
      description: Update template schema
    TemplateWorkflow:
      properties:
        requiresJudgeApproval:
          type: boolean
          title: Requiresjudgeapproval
          default: true
        notifyOnSubmission:
          type: boolean
          title: Notifyonsubmission
          default: true
        autoExpireHours:
          type: integer
          title: Autoexpirehours
          default: 48
        allowedRoles:
          items:
            $ref: "#/components/schemas/UserRole"
          type: array
          title: Allowedroles
          default: []
      type: object
      title: TemplateWorkflow
      description: Template workflow configuration - matches frontend TemplateWorkflow interface
    User:
      properties:
        email:
          type: string
          format: email
          title: Email
        full_name:
          type: string
          maxLength: 255
          minLength: 1
          title: Full Name
        title:
          anyOf:
            - type: string
            - type: "null"
          title: Title
        role:
          $ref: "#/components/schemas/UserRole"
        id:
          type: string
          format: uuid
          title: Id
        agency_id:
          type: string
          format: uuid
          title: Agency Id
        is_active:
          type: boolean
          title: Is Active
        is_verified:
          type: boolean
          title: Is Verified
        last_login:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Last Login
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - email
        - full_name
        - role
        - id
        - agency_id
        - is_active
        - is_verified
        - last_login
        - created_at
        - updated_at
      title: User
      description: User response schema
    UserCreate:
      properties:
        email:
          type: string
          format: email
          title: Email
        full_name:
          type: string
          maxLength: 255
          minLength: 1
          title: Full Name
        title:
          anyOf:
            - type: string
            - type: "null"
          title: Title
        role:
          $ref: "#/components/schemas/UserRole"
      type: object
      required:
        - email
        - full_name
        - role
      title: UserCreate
      description: A person to add to the agency, with the role they hold. They can sign in once they have completed identity setup.
    UserRole:
      type: string
      enum:
        - PHYSICIAN
        - JUDGE
        - ADMIN
        - OFFICER
      title: UserRole
      description: User role enum matching frontend TypeScript enum
    UserUpdate:
      properties:
        full_name:
          anyOf:
            - type: string
            - type: "null"
          title: Full Name
        title:
          anyOf:
            - type: string
            - type: "null"
          title: Title
        role:
          anyOf:
            - $ref: "#/components/schemas/UserRole"
            - type: "null"
        is_active:
          anyOf:
            - type: boolean
            - type: "null"
          title: Is Active
      additionalProperties: false
      type: object
      title: UserUpdate
      description: Update user schema.
    Warrant:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        agency_id:
          type: string
          format: uuid
          title: Agency Id
        creator_id:
          anyOf:
            - type: string
              format: uuid
            - type: "null"
          title: Creator Id
        template_id:
          anyOf:
            - type: string
            - type: "null"
          title: Template Id
        warrant_number:
          anyOf:
            - type: string
            - type: "null"
          title: Warrant Number
        status:
          $ref: "#/components/schemas/WarrantStatus"
        priority:
          $ref: "#/components/schemas/WarrantPriority"
        visibility:
          $ref: "#/components/schemas/WarrantVisibility"
          default: PRIVATE
        slug:
          anyOf:
            - type: string
            - type: "null"
          title: Slug
        form_data:
          additionalProperties: true
          type: object
          title: Form Data
        judge_id:
          anyOf:
            - type: string
              format: uuid
            - type: "null"
          title: Judge Id
        judge_name:
          anyOf:
            - type: string
            - type: "null"
          title: Judge Name
        judge_signature:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Judge Signature
        assigned_user_id:
          anyOf:
            - type: string
              format: uuid
            - type: "null"
          title: Assigned User Id
        assigned_user_name:
          anyOf:
            - type: string
            - type: "null"
          title: Assigned User Name
        assigned_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Assigned At
        assigned_by_id:
          anyOf:
            - type: string
              format: uuid
            - type: "null"
          title: Assigned By Id
        assignment_mode:
          anyOf:
            - type: string
            - type: "null"
          title: Assignment Mode
        created_at:
          type: string
          format: date-time
          title: Created At
        submitted_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Submitted At
        signed_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Signed At
        expires_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Expires At
        deleted_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Deleted At
        comments:
          items:
            $ref: "#/components/schemas/Comment"
          type: array
          title: Comments
          default: []
        creator_name:
          anyOf:
            - type: string
            - type: "null"
          title: Creator Name
        creator_role:
          anyOf:
            - $ref: "#/components/schemas/UserRole"
            - type: "null"
        warnings:
          items:
            type: string
          type: array
          title: Warnings
          default: []
        document_html:
          anyOf:
            - type: string
            - type: "null"
          title: Document Html
        document_updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Document Updated At
        allow_document_editing:
          type: boolean
          title: Allow Document Editing
          default: true
        pdf_url:
          anyOf:
            - type: string
            - type: "null"
          title: Pdf Url
        attachments:
          items:
            $ref: "#/components/schemas/File"
          type: array
          title: Attachments
          default: []
      type: object
      required:
        - id
        - agency_id
        - creator_id
        - template_id
        - warrant_number
        - status
        - priority
        - form_data
        - created_at
      title: Warrant
      description: Warrant response schema
    WarrantAssignRequest:
      properties:
        judge_id:
          type: string
          format: uuid
          title: Judge Id
        reason:
          anyOf:
            - type: string
              maxLength: 500
            - type: "null"
          title: Reason
      type: object
      required:
        - judge_id
      title: WarrantAssignRequest
      description: Assign or reassign a warrant to a judge.
    WarrantCreate:
      properties:
        template_id:
          anyOf:
            - type: string
              maxLength: 100
            - type: "null"
          title: Template Id
        form_data:
          additionalProperties: true
          type: object
          title: Form Data
        priority:
          $ref: "#/components/schemas/WarrantPriority"
          default: STANDARD
        document_source:
          type: string
          enum:
            - template
            - blank
            - upload
          title: Document Source
          default: template
        title:
          anyOf:
            - type: string
            - type: "null"
          title: Title
      type: object
      required:
        - form_data
      title: WarrantCreate
      description: Create warrant schema
    WarrantListItem:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        agency_id:
          type: string
          format: uuid
          title: Agency Id
        creator_id:
          anyOf:
            - type: string
              format: uuid
            - type: "null"
          title: Creator Id
        template_id:
          anyOf:
            - type: string
            - type: "null"
          title: Template Id
        warrant_number:
          anyOf:
            - type: string
            - type: "null"
          title: Warrant Number
        status:
          $ref: "#/components/schemas/WarrantStatus"
        priority:
          $ref: "#/components/schemas/WarrantPriority"
        visibility:
          $ref: "#/components/schemas/WarrantVisibility"
          default: PRIVATE
        form_data_summary:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Form Data Summary
        assigned_user_id:
          anyOf:
            - type: string
              format: uuid
            - type: "null"
          title: Assigned User Id
        assigned_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Assigned At
        assignment_mode:
          anyOf:
            - type: string
            - type: "null"
          title: Assignment Mode
        created_at:
          type: string
          format: date-time
          title: Created At
        submitted_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Submitted At
        signed_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Signed At
        deleted_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Deleted At
        creator_name:
          anyOf:
            - type: string
            - type: "null"
          title: Creator Name
      type: object
      required:
        - id
        - agency_id
        - creator_id
        - template_id
        - warrant_number
        - status
        - priority
        - created_at
      title: WarrantListItem
      description: Warrant list item response (without comments/call_logs for performance)
    WarrantLock:
      properties:
        is_mine:
          type: boolean
          title: Is Mine
        locked_by_user_id:
          anyOf:
            - type: string
            - type: "null"
          title: Locked By User Id
        locked_by_name:
          anyOf:
            - type: string
            - type: "null"
          title: Locked By Name
        locked_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Locked At
        expires_in_seconds:
          type: integer
          title: Expires In Seconds
          default: 0
      type: object
      required:
        - is_mine
      title: WarrantLock
      description: Response for lock claim / release / status endpoints (Phase 4).
    WarrantPriority:
      type: string
      enum:
        - LOW
        - STANDARD
        - URGENT
      title: WarrantPriority
      description: Warrant priority level enum
    WarrantPriorityRequest:
      properties:
        priority:
          $ref: "#/components/schemas/WarrantPriority"
      type: object
      required:
        - priority
      title: WarrantPriorityRequest
      description: Request to update warrant priority
    WarrantRejectRequest:
      properties:
        reason:
          type: string
          maxLength: 5000
          minLength: 1
          title: Reason
          description: Reason for rejection
      type: object
      required:
        - reason
      title: WarrantRejectRequest
      description: Request to reject a warrant
    WarrantStatus:
      type: string
      enum:
        - DRAFT
        - SUBMITTED
        - SIGNED
        - REJECTED
      title: WarrantStatus
      description: Warrant status enum matching frontend TypeScript enum
    WarrantSubmitRequest:
      properties:
        assigned_judge_id:
          anyOf:
            - type: string
              format: uuid
            - type: "null"
          title: Assigned Judge Id
        reason:
          anyOf:
            - type: string
              maxLength: 500
            - type: "null"
          title: Reason
      type: object
      title: WarrantSubmitRequest
      description: Optional body for PATCH /{id}/submit, route to a specific judge at submit time, so only that judge is notified instead of the whole bench.
    WarrantUpdate:
      properties:
        template_id:
          anyOf:
            - type: string
              maxLength: 100
            - type: "null"
          title: Template Id
        form_data:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Form Data
        priority:
          anyOf:
            - $ref: "#/components/schemas/WarrantPriority"
            - type: "null"
        document_html:
          anyOf:
            - type: string
              maxLength: 2000000
            - type: "null"
          title: Document Html
      type: object
      title: WarrantUpdate
      description: Update warrant schema (for DRAFT or SUBMITTED status)
    WarrantVisibility:
      type: string
      enum:
        - PUBLIC
        - PRIVATE
      title: WarrantVisibility
      description: Warrant visibility enum
    WarrantVisibilityRequest:
      properties:
        visibility:
          $ref: "#/components/schemas/WarrantVisibility"
      type: object
      required:
        - visibility
      title: WarrantVisibilityRequest
      description: Request to update warrant visibility