---
title: "Submit a Catalog record change or an Agent Readiness declaration through the one authenticated submission transport."
method: POST
path: "/v1/submissions"
tags: ["Catalog"]
---

# Submit a Catalog record change or an Agent Readiness declaration through the one authenticated submission transport.

`POST /v1/submissions`

## Request

- Base URL: `https://api.sourcey.com`
- URL: `https://api.sourcey.com/v1/submissions`
- Auth: one of:
  - API key in cookie `sourcey_session`
  - HTTP bearer

## Headers

- `idempotency-key` string, required

## Request body

- union
  - object
    - `authority` union, required
      - object
        - `kind` 'authenticated_form', required
      - object
        - `kind` 'paid_agent', required
        - `request_id` string, required
      - object
        - `admission_artifact_digests` string[], required
        - `approval_digest` string, nullable, required
        - `command_digest` string, required
        - `grant_digest` string, required
        - `kind` 'governed_ops', required
        - `run_receipt_digest` string, required
    - `payload` object, required
      - `asset_submissions` object[], required
        - `entity_id` string, required
        - `expected_current_binding_event_id` string, nullable, required
        - `redistribution` object, required
          - `basis` 'vendor-approved' | 'redistributable-license' | 'nominative-use' | 'sourcey-owned', required
          - `fallback_reason` string
          - `license` string, required
          - `notice` string, required
          - `trademark_owner` string, required
        - `role` 'icon', required
        - `source` union, required
          - object
            - `bytes` integer, required
            - `kind` 'upload', required
            - `media_type` 'image/jpeg' | 'image/png' | 'image/webp' | 'image/svg+xml', required
            - `original_digest` string, required
            - `upload_receipt_digest` string, required
          - object
            - `kind` 'official_url', required
            - `url` string, uri, required
        - `submitter_context` object, required
          - `authority_asserted` boolean, required
          - `relationship` 'vendor-representative' | 'community-contributor', required
      - `authoring_files` object[], required
        - `content` string, required
        - `path` string, required
      - `expected_current_entities` object[]
        - `entity_id` string, required
        - `snapshot_digest` string, nullable, required
      - `remove_entity_ids` string[], required
    - `product` 'catalog_record', required
  - object
    - `authority` union, required
      - object
        - `kind` 'authenticated_form', required
      - object
        - `kind` 'paid_agent', required
        - `request_id` string, required
      - object
        - `admission_artifact_digests` string[], required
        - `approval_digest` string, nullable, required
        - `command_digest` string, required
        - `grant_digest` string, required
        - `kind` 'governed_ops', required
        - `run_receipt_digest` string, required
    - `payload` object, required
      - `account_operations` object[]
        - `operation` object, required
          - `endpoint_id` string, required
          - `interface_id` string, required
          - `method` 'POST' | 'PUT' | 'PATCH', required
          - `operation_id` string, required
          - `role` 'registration' | 'top_up', required
          - `spec_url` string, uri, required
          - `url` string, uri, required
        - `source_uris` string[], required
      - `authority_intent` 'entity' | 'community'
      - `base_authoring_file` object
        - `content` string, required
        - `content_digest` string, required
        - `path` string, required
      - `command_contract` 'sourcey.agent-readiness-declaration-draft/v1alpha1', required
      - `declared_at` string, date-time
      - `endpoints` object[], required
        - `allowed_redirect_hosts` string[]
        - `endpoint_id` string, required
        - `operated_by_participant_id` string, required
        - `roles` string[], required
        - `source_uris` string[], required
        - `standard_bindings` object[], required
          - `namespace` string, required
          - `relation` 'declares' | 'describes' | 'implements' | 'uses', required
          - `version` string, required
        - `transport` 'http' | 'websocket' | 'grpc', required
        - `uri` string, uri, required
      - `interfaces` object[], required
        - `endpoint_ids` string[], required
        - `functions` string[], required
        - `interface_id` string, required
        - `modality` 'web_application' | 'network_api' | 'command_line' | 'software_library' | 'tool_server' | 'agent_service', required
        - `operated_by_participant_id` string, required
        - `resource_ids` string[], required
        - `source_uris` string[], required
        - `standard_bindings` object[], required
          - `namespace` string, required
          - `relation` 'declares' | 'describes' | 'implements' | 'uses', required
          - `version` string, required
      - `job_bindings` object[], required
        - `binding` object, required
          - `assertions` object[], required
            - `assertion` string, required
            - `observations` object[], required
              - …
          - `binding_id` string, required
          - `calls` union[], required
            - union
              - …
          - `cleanup` union[], required
            - union
              - …
          - `delegation` union, required
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
          - `interface_id` string, required
          - `payment` union, required
            - object
              - …
            - object
              - …
            - object
              - …
        - `source_uris` string[], required
      - `job_operations` object[], required
        - `operation` union, required
          - object
            - `body` object, nullable, required
              - …
            - `endpoint_id` string, required
            - `headers` object[], required
              - …
            - `interface_id` string, required
            - `kind` 'http', required
            - `method` 'GET' | 'POST' | 'PUT' | 'PATCH', required
            - `operation_id` string, required
            - `spec` object, nullable, required
              - …
            - `url` string, uri, required
          - object
            - `endpoint_id` string, required
            - `interface_id` string, required
            - `kind` 'mcp', required
            - `operation_id` string, required
            - `tool` string, required
          - object
            - `interface_id` string, required
            - `key_operations` object, nullable, required
              - …
            - `kind` 'spec', required
            - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', required
            - `operation_id` string, required
            - `path` string, required
            - `spec_url` string, uri, required
        - `source_uris` string[], required
      - `offer_relations` object[], required
        - `offer_id` string, required
        - `offer_relation_proposal_id` string, required
        - `purpose` 'application_path' | 'redemption_path' | 'operating_path', required
        - `source_uris` string[], required
      - `participants` object[], required
        - `identity` union, required
          - object
            - `entity_id` string, required
            - `kind` 'entity_id', required
          - object
            - `kind` 'origin_uri', required
            - `uri` string, uri, required
        - `participant_id` string, required
        - `roles` string[], required
        - `source_uris` string[], required
      - `relations` object[], required
        - `from` object, required
          - `node_id` string, required
          - `node_kind` 'resource' | 'endpoint' | 'interface' | 'surface_exclusion', required
        - `kind` 'describes' | 'authenticates' | 'requires' | 'alternative_to' | 'precedes', required
        - `relation_id` string, required
        - `source_uris` string[], required
        - `to` object, required
          - `node_id` string, required
          - `node_kind` 'resource' | 'endpoint' | 'interface' | 'surface_exclusion', required
      - `resources` object[], required
        - `allowed_redirect_hosts` string[]
        - `operated_by_participant_id` string, required
        - `resource_id` string, required
        - `roles` string[], required
        - `source_uris` string[], required
        - `standard_bindings` object[], required
          - `namespace` string, required
          - `relation` 'declares' | 'describes' | 'implements' | 'uses', required
          - `version` string, required
        - `uri` string, uri, required
      - `scope` object
        - `job` object, required
          - `key` string, required
          - `name` string, required
        - `product` object, required
          - `key` string, required
          - `name` string, required
      - `scope_source_uris` string[], required
      - `subject` union
        - object
          - `kind` 'entity_id', required
          - `value` string, required
        - object
          - `kind` 'slug', required
          - `value` string, required
        - object
          - `kind` 'domain', required
          - `value` string, required
      - `subject_roles` string[], required
      - `surface_exclusions` object[], required
        - `exclusion_id` string, required
        - `rationale` string, required
        - `role` 'discovery' | 'terms' | 'eligibility' | 'pricing' | 'access' | 'checkout' | 'provisioning' | 'operations' | 'recovery' | 'authentication' | 'descriptor' | 'documentation' | 'policy' | 'status', required
        - `source_uris` string[], required
    - `product` 'agent_readiness', required

## Response `202`

Successful response.

- CreateCatalogSubmissionResponse202
  - `api_contract` 'sourcey.catalog-api/v1', required
  - `artifact_sha256` string, required
  - `data` union, required
    - object
      - `authentication_digest` string, required
      - `change_set_digest` string, nullable, required
      - `created_at` string, date-time, required
      - `ingress` 'authenticated_form' | 'paid_agent' | 'catalog_operator' | 'governed_ops', required
      - `links` object, required
        - `self` string, required
      - `live_parent_release_id` string, required
      - `payload_digest` string, required
      - `product` 'catalog_record', required
      - `proposal_digest` string, nullable, required
      - `publication_release_id` string, nullable, required
      - `stages` object[], required
        - `diagnostics` object[], required
          - `code` string, required
          - `message` string, required
          - `path` string
          - `stage` 'validation' | 'evidence' | 'identity' | 'readiness' | 'authorization' | 'publication' | 'readback', required
        - `stage` 'validation' | 'evidence' | 'identity' | 'readiness' | 'authorization' | 'publication' | 'readback', required
        - `status` 'pending' | 'passed' | 'failed' | 'not_required' | 'invalidated', required
      - `state` 'queued' | 'active' | 'awaiting_review' | 'awaiting_admission' | 'awaiting_authorization' | 'rejected' | 'invalidated' | 'published', required
      - `submission_id` string, required
      - `telemetry` object, required
        - `active_ms` integer, required
        - `cache_reuse` object, required
          - `created` integer, required
          - `reused` integer, required
        - `closure_cardinality` integer, required
        - `live_readback_ms` integer, nullable, required
        - `queued_ms` integer, required
        - `stages_invoked` string[], required
      - `updated_at` string, date-time, required
    - object
      - `authoring_blob_digest` string, nullable, required
      - `created_at` string, date-time, required
      - `diagnostics` object[], required
        - `code` 'required' | 'invalid' | 'ambiguous_identity' | 'cross_entity_offer' | 'base_authoring_mismatch', required
        - `message` string, required
        - `path` string, starts_with, required
      - `ingress` 'authenticated_form' | 'paid_agent' | 'catalog_operator' | 'governed_ops', required
      - `links` object, required
        - `self` string, required
      - `payload_digest` string, required
      - `product` 'agent_readiness', required
      - `state` 'queued' | 'admitted' | 'refused', required
      - `subject` object, nullable, required
        - `declaration_ids` string[], required
        - `entity_id` string, required
      - `submission_id` string, required
      - `updated_at` string, date-time, required
  - `release_id` string, required

## Other responses

- `400`: Invalid request.
- `401`: HTTP 401 response.
- `403`: HTTP 403 response.
- `405`: HTTP 405 response.
- `409`: HTTP 409 response.
- `429`: HTTP 429 response.
- `500`: HTTP 500 response.
- `503`: HTTP 503 response.

---

[API](https://skmtc.dev/sourcey/apis/sourcey-public-api.md) · [All operations](https://skmtc.dev/sourcey/apis/sourcey-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sourcey/apis/sourcey-public-api/revisions/437166b51fa5?raw)