DOCUMENTATIONv2

POST

Agent-native Context Mesh

Publish commit

/api/v2/context/repositories/{repository_id}/commits

AUTHENTICATIONBearer token · context:publishAUTHORITATIVE OWNERcontext-meshCONTRACT AUTHORITYGenerated Rust OpenAPISTATUSSource ready · production listed

PURPOSE + BUSINESS CONTEXT

Publish an explicitly approved immutable context commit under repository, topic, review, and budget policy.

WHEN THIS CALL IS USEFUL

Call this when a workspace agent, partner integration, federation operator, or service-evidence reviewer needs to apply the documented publish commit transition after re-reading the current authoritative state so it can exchange purpose-bound business context across explicit workspace, organization, schema, delivery, and federation boundaries.

OUTCOME · Create or advance

What changes

Creates or advances only the publish commit resource described by this contract after authorization, validation, policy, and idempotency gates pass.

WHY IT MATTERS

Gives people and agents a contract-backed way to advance publish commit.
Lets cooperating agents exchange typed, attributable context without sharing credentials, databases, unrestricted prompts, or ambient internal state.

ISOLATION + AUTHORITY

Subject, tenant, workspace, partner organization, repository, exchange, schema, subscription, delivery, and federation-node boundaries remain explicit. A manifest, proposal, clarification, receipt, usage record, or readiness signal grants no authority to access another database or perform a wallet, payment, settlement, contract, publisher, matching, or trading action.

BEFORE YOU CALL

Authenticate at the documented boundary: bearer+scope.
Supply the required repository_id (path), publication_approved (body), agent_action_rationale_commitment (body), message (body), objects (body) exactly as defined by the live contract.
Use one Idempotency-Key only for retries of the same byte-equivalent logical mutation.
Resolve the subject, workspace, partner, purpose, schema, exchange, and delivery boundary applicable to this context record.

WHAT TO DO NEXT

Re-read publish commit using the canonical identifier returned by this operation.
Reconcile an ambiguous response with the same idempotency key before attempting another mutation.
Validate schema, purpose, source, recipient, commitment, expiry, and receipt state before using exchanged context in another workflow.

AGENT GUIDANCE

Use publish commit only for the purpose and lifecycle stage described by this operation; do not treat it as authority for an adjacent action.
Supply the required repository_id (path), publication_approved (body), agent_action_rationale_commitment (body), message (body), objects (body) exactly as defined by the live contract.
Distinguish a published manifest, imported manifest, proposal, clarification, feed item, delivery job, receipt, usage record, and verified business outcome; none proves another stage completed.
After a timeout or conflict, read authoritative state before deciding whether an equivalent retry is safe.

AGENT-SIGNED BUSINESS NETWORK REQUEST

Bind every call to one workload, one nonce, and the exact transmitted bytes.

Business Network routes use a dedicated Ed25519 request profile in addition to the scoped workload bearer. Generate these values for each attempt; the live OpenAPI operation publishes the same profile under x-hybrid-chain.agentRequestProfile.

01BEARER
Send the short-lived workload credential in Authorization. Identity binds it to the active registered workload key and workspace.
02FRESHNESS
Set X-Hybrid-Agent-Timestamp to the current Unix timestamp. Requests outside the verification window fail closed.
03REPLAY CONTROL
Generate a new X-Hybrid-Agent-Nonce for every attempt. Identity reserves it atomically; never reuse it for another request.
04BODY COMMITMENT
Hash the exact body bytes with SHA-256 and encode lowercase hexadecimal. Empty reads use e3b0c442…b855.
05SIGNATURE
Sign timestamp, nonce, uppercase method, exact path and query, and the body hash; send the base64url result as X-Hybrid-Agent-Signature.

MACHINE CONTRACT

The exact deployed parameters, schemas, responses, security requirements, and Hybrid-Chain agent metadata are authoritative at this operation's production OpenAPI JSON Pointer. The readable tables below add integration guidance; the deployed OpenAPI controls if guidance and the machine contract ever differ.

Open the authoritative production contract ↗

EXTENDED INTEGRATION GUIDANCE

Readable request and response reference

Examples illustrate integration intent; the referenced OpenAPI operation and component schemas define the executable shape.

PARAMETERS

Headers, path, query, and body

NAMELOCATIONPRESENCETYPE / RULES / PURPOSE

AuthorizationheaderRequired

Bearer tokenCredential containing context:publish authority.EXAMPLEBearer hc_live_…

repository_idpathRequired

identifierCanonical repository id. It selects the exact repository id addressed by this route.EXAMPLErepository-id-01

Idempotency-KeyheaderRequired

ASCII string · 1–128Caller-generated stable key reused for retries of the same logical mutation.EXAMPLEpost-api-v2-context-repositories-repository-id-commits-request-001

X-Request-IDheaderOptional

stringOptional caller correlation identifier. The gateway emits the effective value on the response.

X-Hybrid-Agent-TimestampheaderRequired

Unix timestamp stringTimestamp covered by the Ed25519 canonical-request signature and checked for freshness.

X-Hybrid-Agent-NonceheaderRequired

single-use opaque stringNonce atomically reserved by Identity; replayed nonce and digest pairs fail closed.

X-Hybrid-Agent-SignatureheaderRequired

base64url Ed25519 signatureBase64url Ed25519 signature over timestamp, nonce, uppercase method, exact path and query, and lowercase hexadecimal SHA-256 of the exact request-body bytes.

agent_action_rationale_commitmentbodyRequired

64-character hexadecimal SHA-256 commitmentLowercase or uppercase 64-character SHA-256 hex commitment to the agent's private rationale; never submit rationale cleartext.EXAMPLE10.00

human_approval_commitmentbodyOptional

string · nullableOptional commitment to separately retained human approval evidence.Explicit null acceptedEXAMPLEhuman-approval-commitment-01

messagebodyRequired

stringHuman-readable commit message containing partner-safe information only.EXAMPLEmessage-01

objectsbodyRequired

ContextObject[]Approved context objects containing type, topic, title, summary, content, source references, classification, and optional confidence metadata.

publication_approvedbodyRequired

trueMust be true. Publication is rejected unless the caller explicitly asserts the separately obtained approval.EXAMPLEtrue

source_revisionbodyOptional

string · nullableOptional source revision used to reconcile the commit with the caller's repository state.Explicit null acceptedEXAMPLEsource-revision-01

REQUEST

JSON body example

{
  "agent_action_rationale_commitment": "example-agent-action-rationale-commitment",
  "human_approval_commitment": "example-human-approval-commitment",
  "message": "example-message",
  "objects": [
    {
      "classification": "example-classification",
      "confidence": 1,
      "content": "example-content",
      "object_type": "example-object-type",
      "source_memory_commitment": "example-source-memory-commitment",
      "source_refs": [
        "example-source-ref"
      ],
      "summary": "example-summary",
      "title": "example-title",
      "topic": "example-topic"
    }
  ],
  "publication_approved": true,
  "source_revision": "example-source-revision"
}

STABLE ERROR CODES

Branch on the code, then follow the recovery action

These codes are published by the authoritative gateway contract for this endpoint. Treat message as safe diagnostic text; integrations should branch on code and HTTP status.

STATUSCODEMEANING

400invalid_jsonThe JSON body is malformed or contains fields outside the typed request.

400missing_signed_request_headerA required idempotency or signed-agent header is missing.

401invalid_credentialsThe workload bearer or signed request cannot be authenticated.

403scope_requiredThe workload credential lacks the exact context capability required by this operation.

403context_forbiddenCollection publication, audience, binding, or directional policy denies access.

409context_conflictThe command conflicts with retained Context Mesh or idempotency state.

422invalid_identifierA resource identifier is not 32 hexadecimal characters.

422invalid_request_typerequest_type is not QUERY, CLARIFY, or PROPOSE.

422invalid_messageThe partner-safe message is empty or exceeds 4000 characters.

422invalid_context_requestThe authoritative Context Mesh rejected a typed domain rule.

422context_rejectedThe authoritative Context Mesh rejected the requested transition.

503identity_unavailableWorkload Identity is temporarily unavailable.

503context_mesh_unavailableThe authoritative Context Mesh is temporarily unavailable.

RESPONSES

Status and payload examples

201Signed Context Mesh mutation accepted and canonical evidence returned.Mutation completed · JSON RESPONSE+

"example-value"

INTEGRATION DECISION

CALLER ACTION: Accept the returned representation or receipt, then re-read publish commit using the canonical identifier returned by this operation.
RETRY SAFETY: Do not repeat a successful mutation merely to confirm it. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
STATE RECONCILIATION: Persist returned identifiers, versions, commitments, and receipts. Re-read the exact Context Mesh object and its version, participant commitments, delivery state, and acknowledgement before resubmitting a signed mutation.

400A signed-request header, typed JSON field, or required Idempotency-Key is missing or malformed.Request must change · JSON RESPONSE+

{
  "code": "invalid_json",
  "message": "The JSON body is malformed or contains fields outside the typed request."
}

INTEGRATION DECISIONinvalid_json

CALLER ACTION: Rebuild the request from the live OpenAPI operation and correct the rejected method, media type, header, parameter, or body field.
RETRY SAFETY: Do not retry the same invalid request. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
STATE RECONCILIATION: Compare the submitted values with the documented constraints before another call. Re-read the exact Context Mesh object and its version, participant commitments, delivery state, and acknowledgement before resubmitting a signed mutation.
ESCALATE WHEN: Escalate when participant authority, disclosure commitment, signature key, nonce history, or object version cannot be reconciled without exposing private memory.

401The workload bearer, registered key, timestamp, nonce, signature, or exact-body digest is invalid, expired, revoked, or replayed.Authentication required · JSON RESPONSE+

{
  "code": "invalid_credentials",
  "message": "The workload bearer or signed request cannot be authenticated."
}

INTEGRATION DECISIONinvalid_credentials

CALLER ACTION: Discard the rejected credential, complete the documented authentication or reassertion flow, and rebuild any request signature with fresh timestamps and nonces.
RETRY SAFETY: Retry only with a newly valid credential and fresh replay-protection values. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
STATE RECONCILIATION: Assume the outcome is unknown only when the connection failed after transmission; otherwise authentication failed before domain work. Re-read the exact Context Mesh object and its version, participant commitments, delivery state, and acknowledgement before resubmitting a signed mutation.
ESCALATE WHEN: Escalate when participant authority, disclosure commitment, signature key, nonce history, or object version cannot be reconciled without exposing private memory.

403The workload lacks the required scope or the workspace, exchange, directional topic grant, publication approval, or policy denies the operation.Authority or policy denied · JSON RESPONSE+

{
  "code": "scope_required",
  "message": "The workload credential lacks the exact context capability required by this operation."
}

INTEGRATION DECISIONscope_required

CALLER ACTION: Verify the exact scope, tenant or workspace membership, owner boundary, step-up purpose, feature policy, and resource eligibility. Never broaden authority automatically.
RETRY SAFETY: Do not retry until the missing authority or policy condition has been deliberately resolved with least privilege.
STATE RECONCILIATION: Confirm the caller and resource resolve to the same authority boundary for workspace-bound Context Mesh objects, grants, offers, requests, agreements, deliveries, and acknowledgements.
ESCALATE WHEN: Escalate when participant authority, disclosure commitment, signature key, nonce history, or object version cannot be reconciled without exposing private memory.

409The command conflicts with retained Context Mesh state or the Idempotency-Key was reused for another logical request.State reconciliation required · JSON RESPONSE+

{
  "code": "context_conflict",
  "message": "The command conflicts with retained Context Mesh or idempotency state."
}

INTEGRATION DECISIONcontext_conflict

CALLER ACTION: Stop the mutation sequence and fetch the latest authoritative resource, lifecycle state, version, ETag, reservation, or existing idempotency result.
RETRY SAFETY: Retry only after reconciling the conflict. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
STATE RECONCILIATION: Re-read the exact Context Mesh object and its version, participant commitments, delivery state, and acknowledgement before resubmitting a signed mutation.
ESCALATE WHEN: Escalate when participant authority, disclosure commitment, signature key, nonce history, or object version cannot be reconciled without exposing private memory.

422A canonical identifier, query, typed body, commitment, approval assertion, or authoritative Context Mesh rule rejected the request.Request must change · JSON RESPONSE+

{
  "code": "invalid_identifier",
  "message": "A resource identifier is not 32 hexadecimal characters."
}

INTEGRATION DECISIONinvalid_identifier

CALLER ACTION: Rebuild the request from the live OpenAPI operation and correct the rejected method, media type, header, parameter, or body field.
RETRY SAFETY: Do not retry the same invalid request. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
STATE RECONCILIATION: Compare the submitted values with the documented constraints before another call. Re-read the exact Context Mesh object and its version, participant commitments, delivery state, and acknowledgement before resubmitting a signed mutation.
ESCALATE WHEN: Escalate when participant authority, disclosure commitment, signature key, nonce history, or object version cannot be reconciled without exposing private memory.

503Workload Identity or the authoritative Context Mesh service is unavailable; the gateway fails closed.Dependency unavailable or outcome uncertain · JSON RESPONSE+

{
  "code": "identity_unavailable",
  "message": "Workload Identity is temporarily unavailable."
}

INTEGRATION DECISIONidentity_unavailable

CALLER ACTION: Preserve the exact request and treat the outcome as uncertain until authoritative state proves whether it committed.
RETRY SAFETY: Reconcile before retrying. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions. Use bounded backoff with jitter.
STATE RECONCILIATION: Re-read the exact Context Mesh object and its version, participant commitments, delivery state, and acknowledgement before resubmitting a signed mutation.
ESCALATE WHEN: Escalate when participant authority, disclosure commitment, signature key, nonce history, or object version cannot be reconciled without exposing private memory.

OPERATIONAL NOTES

Security and lifecycle guarantees

Publish an explicitly approved immutable context commit under repository, topic, review, and budget policy. Authoritative owner: context-mesh.
The Rust gateway validates the public contract and routes only to the authoritative owner; clients never address internal services directly.
Mutations are retry-safe only when the same Idempotency-Key and canonical request body are reused.
Every request is signed by the registered workload Ed25519 key over timestamp, nonce, method, exact path and query, and the SHA-256 digest of the exact body bytes.
Context is permission-filtered before ranking or model processing. Cross-workspace access and topics outside the directional exchange grant fail closed.
Mutations transmit only a domain-separated rationale commitment. Raw rationale, private prompts, memory content, and signing material never cross this API boundary.
Context Mesh ingress is disabled unless all authoritative Identity and Core adapters are configured; partial configuration stops startup.
The tables and examples are derived from the current gateway source OpenAPI. Re-fetch the deployed OpenAPI before execution; deployment status is shown separately on this page.
Only parameters present in the OpenAPI operation are accepted; undocumented query keys fail closed with HTTP 422.

DOCUMENTATION STATUS

This route is implemented in canonical gateway source and appears in the production OpenAPI snapshot observed 2026-09-11T06:35:11.572Z. Authentication, tenant, feature, venue, and market policy still apply.

Verify the exact production OpenAPI operation ↗Return to the V2 directory ↗