DOCUMENTATIONv2

GET

Agent-native Context Mesh

Read usage

/api/v2/context/platform/usage

AUTHENTICATIONBearer token · platform:readAUTHORITATIVE OWNERcontext-meshCONTRACT AUTHORITYGenerated Rust OpenAPISTATUSSource ready · production listed

PURPOSE + BUSINESS CONTEXT

Read content-free workspace usage totals produced by idempotent meter evidence.

WHEN THIS CALL IS USEFUL

Call this when a workspace agent, partner integration, federation operator, or service-evidence reviewer needs to discover read usage and choose a canonical record for a later step so it can exchange purpose-bound business context across explicit workspace, organization, schema, delivery, and federation boundaries.

OUTCOME · Discover

What changes

Read-only projection; it grants no mutation, settlement, traffic, or authority change.

WHY IT MATTERS

Gives people and agents a contract-backed way to discover read usage.
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.
Use the live OpenAPI schema as the authority for the exact request shape and response model.
Resolve the subject, workspace, partner, purpose, schema, exchange, and delivery boundary applicable to this context record.

WHAT TO DO NEXT

Select one canonical identifier from the response and open its detail operation when the live contract exposes one.
Validate schema, purpose, source, recipient, commitment, expiry, and receipt state before using exchanged context in another workflow.

AGENT GUIDANCE

Use read usage only for the purpose and lifecycle stage described by this operation; do not treat it as authority for an adjacent action.
Use the live OpenAPI schema as the authority for the exact request shape and response model.
Distinguish a published manifest, imported manifest, proposal, clarification, feed item, delivery job, receipt, usage record, and verified business outcome; none proves another stage completed.
Use response links and canonical identifiers instead of constructing internal service URLs or scraping the website.

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 platform:read authority.EXAMPLEBearer hc_live_…

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.

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

200Permission-filtered canonical Context Mesh projection.Read completed · JSON RESPONSE+

"example-value"

INTEGRATION DECISION

CALLER ACTION: Accept the returned representation or receipt, then select one canonical identifier from the response and open its detail operation when the live contract exposes one.
RETRY SAFETY: Repeat only when the integration needs a fresher authoritative projection.
STATE RECONCILIATION: Use returned identifiers and versions as the comparison point for later reads. 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. A corrected read may be sent as a new attempt.
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. Do not replay an expired signature.
STATE RECONCILIATION: Authentication failed before an authoritative read was returned 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.

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. Preserve the original filters when validating a refreshed read.
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. A corrected read may be sent as a new attempt.
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: Treat the failure as transient and preserve the last known good representation without presenting it as fresh.
RETRY SAFETY: Retry with bounded exponential backoff and jitter; stop after the integration's failure budget is exhausted.
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

Read content-free workspace usage totals produced by idempotent meter evidence. Authoritative owner: context-mesh.
The Rust gateway validates the public contract and routes only to the authoritative owner; clients never address internal services directly.
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 ↗