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

# Update tenant-owned lifecycle state for a customer obligation instance



## OpenAPI

````yaml /openapi.json patch /api/v1/customer-obligation-instances/{customer_obligation_instance_id}
openapi: 3.1.0
info:
  title: Esheria Regulatory API
  version: 1.0.0
  description: >-
    Citation-backed regulatory pack API for pack discovery, obligations,
    applicability checks, version history, diffs, change events, evidence
    requirements, filing rules, penalty facts, legal review audit metadata,
    graph queries, and claim verification.
servers:
  - url: https://api.esheria.ai
    description: Production API
  - url: http://127.0.0.1:8080
    description: Local development runtime
security: []
paths:
  /api/v1/customer-obligation-instances/{customer_obligation_instance_id}:
    patch:
      tags:
        - Customer Applicability API
      summary: Update tenant-owned lifecycle state for a customer obligation instance
      operationId: >-
        update_customer_obligation_instance_api_v1_customer_obligation_instances__customer_obligation_instance_id__patch
      parameters:
        - name: customer_obligation_instance_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Customer Obligation Instance Id
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerObligationInstanceUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                status: error
                errors:
                  - code: unauthorized
                    message: Invalid API key
                trace_id: trace-123
        '402':
          description: Credits exhausted
          content:
            application/json:
              example:
                status: error
                errors:
                  - code: credits_exhausted
                    message: API credits exhausted
                trace_id: trace-123
        '409':
          description: Conflict
          content:
            application/json:
              example:
                status: error
                errors:
                  - code: duplicate_token_name
                    message: An active data token already uses that name.
                trace_id: trace-123
        '422':
          description: Validation error
          content:
            application/json:
              example:
                status: error
                errors:
                  - code: validation_error
                    message: Invalid payload
                    field: body.name
                trace_id: trace-123
        '503':
          description: Billing or dependency unavailable
          content:
            application/json:
              example:
                status: error
                errors:
                  - code: billing_unavailable
                    message: Billing ledger is unavailable
                trace_id: trace-123
      security:
        - ApiKeyAuth: []
components:
  parameters:
    IdempotencyKey:
      name: idempotency-key
      in: header
      required: true
      schema:
        type: string
      description: Unique key for mutating request replay protection.
      example: claim-verify-2026-06-01T120000Z
  schemas:
    CustomerObligationInstanceUpdateRequest:
      properties:
        status:
          anyOf:
            - type: string
              enum:
                - candidate
                - accepted
                - not_applicable
                - monitoring
                - retired
            - type: 'null'
          title: Status
        owner_user_id:
          anyOf:
            - type: string
              maxLength: 160
            - type: 'null'
          title: Owner User Id
        owner_label:
          anyOf:
            - type: string
              maxLength: 240
            - type: 'null'
          title: Owner Label
        due_date:
          anyOf:
            - type: string
              maxLength: 32
            - type: 'null'
          title: Due Date
        priority:
          anyOf:
            - type: string
              enum:
                - low
                - normal
                - high
                - urgent
            - type: 'null'
          title: Priority
        status_reason:
          anyOf:
            - type: string
              maxLength: 1000
            - type: 'null'
          title: Status Reason
        status_updated_by:
          anyOf:
            - type: string
              maxLength: 160
            - type: 'null'
          title: Status Updated By
        lifecycle_metadata:
          additionalProperties: true
          type: object
          title: Lifecycle Metadata
      additionalProperties: false
      type: object
      title: CustomerObligationInstanceUpdateRequest
      example:
        due_date: '2026-07-31'
        lifecycle_metadata:
          ticket_id: COMP-42
        owner_label: Compliance lead
        owner_user_id: usr_123
        priority: high
        status: monitoring
        status_reason: Accepted into the compliance work queue.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Client API key issued by Esheria.
      x-default: YOUR_ESHERIA_API_KEY

````