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

# Create or update a regulatory source watch



## OpenAPI

````yaml /openapi.json post /api/v1/regulatory-monitoring/source-watches
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/regulatory-monitoring/source-watches:
    post:
      tags:
        - Regulatory Monitoring API
      summary: Create or update a regulatory source watch
      operationId: create_source_watch_api_v1_regulatory_monitoring_source_watches_post
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourceWatchCreateRequest'
      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:
    SourceWatchCreateRequest:
      properties:
        domain_pack_id:
          type: string
          maxLength: 160
          minLength: 2
          title: Domain Pack Id
        source_asset_id:
          type: string
          maxLength: 240
          title: Source Asset Id
          default: ''
        source_uri:
          type: string
          maxLength: 2000
          minLength: 2
          title: Source Uri
        source_kind:
          type: string
          enum:
            - binding
            - guidance
            - watchlist
            - context
          title: Source Kind
          default: binding
        authority_type:
          type: string
          enum:
            - binding
            - non_binding
            - watchlist
            - context
          title: Authority Type
          default: binding
        expected_hash_sha256:
          type: string
          maxLength: 128
          title: Expected Hash Sha256
          default: ''
        expected_etag:
          type: string
          maxLength: 256
          title: Expected Etag
          default: ''
        expected_last_modified:
          type: string
          maxLength: 256
          title: Expected Last Modified
          default: ''
        check_interval_seconds:
          type: integer
          minimum: 60
          title: Check Interval Seconds
          default: 86400
        status:
          type: string
          enum:
            - active
            - paused
            - retired
          title: Status
          default: active
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
      additionalProperties: false
      type: object
      required:
        - domain_pack_id
        - source_uri
      title: SourceWatchCreateRequest
      example:
        authority_type: binding
        check_interval_seconds: 86400
        domain_pack_id: UK-DATA-PROTECTION-PRIVACY
        expected_hash_sha256: known-source-hash
        source_asset_id: src_uk_ico_data_protection_guidance
        source_kind: binding
        source_uri: https://ico.org.uk/for-organisations/uk-gdpr-guidance-and-resources/
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Client API key issued by Esheria.
      x-default: YOUR_ESHERIA_API_KEY

````