ENTITY developer reference
Inspect capabilities and coverage
Candidate documentation for reading and synthetic examples. Account creation, live API access, SDKs, collections and MCP are not available here. A released service profile and matching integration instructions are required before use.
This is a documentation reading view of an unreleased candidate, not a downloadable replacement schema. Public wire names, types and constraints are retained except for the explicitly marked private-only subsets and route patterns. Private governance references are explained in public language. Use only a separately released, verified generation for clients. Read the explicit exclusions.
GET /v1/capabilities
Operation identifier: getCapabilities
This pure owned read creates no new business effect or debit. Its failure reports only not_started/unchanged with null operation/status references. Existing underlying financial uncertainty is shown in the successful owned status envelope; unavailable read dependencies use the existing dependency_unavailable retry path. Never report a new reservation/settlement or invent a polling operation for this read. Original-resource disclosure: No original-object relation; current explicit integration grant controls the permitted capability projection. API integration never borrows a human or another integration relation. Every current credential/action/profile/source/retention guard still applies.
Entity-Service-Profile carries the accepted profile_id; the endpoint pins its separate immutable revision. The retained template parameter description says “revision”; follow this current interpretation when reading that historical wording. No reserved example URL in the definitions is a live service destination.
Authentication
Apply the operation’s security requirement when present, otherwise the contract default below. These definitions do not provision access or qualify an authentication flow.
[
{
"bearerAuth": []
}
]Security scheme definitions
{
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Validated OAuth access token, never an ID token. Issuer/audience/token endpoint and scope mapping are deployment-profile values. ENTITY current role, data and budget policy additionally applies."
}
}Request parameters
Headers, path and query parameters from the candidate contract. Operation-specific definitions take precedence over inherited definitions with the same name and location. Request body fields appear in the reading view below.
This operation declares no header, path or query parameters.
Request and response contract
The candidate operation is shown below with the declared documentation-only public-meaning projection. References open the corresponding public schema. No server URL or credential is supplied by this page.
{
"operationId": "getCapabilities",
"summary": "Inspect capabilities and coverage",
"parameters": [],
"responses": {
"200": {
"description": "Successful governed response; examples are synthetic and no endpoint is deployed by this specification.",
"headers": {
"Cache-Control": {
"schema": {
"const": "private, no-store"
}
},
"Entity-Request-Id": {
"schema": {
"type": "string",
"format": "uuid"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CapabilitiesResponse"
},
"example": {
"data": {
"profiles": [],
"as_of": "2026-09-07T10:00:00Z"
},
"meta": {
"request_id": "00000007-1111-4111-8111-000000000007",
"served_at": "2026-09-07T10:00:00Z",
"profile_revision": "synthetic-review-1",
"synthetic": true,
"replayed": false,
"warnings": [
"Illustration only; limits, retention and units are not approved production terms."
]
}
}
}
}
},
"400": {
"description": "invalid_request",
"headers": {
"Cache-Control": {
"schema": {
"const": "private, no-store"
}
},
"Entity-Request-Id": {
"schema": {
"type": "string",
"format": "uuid"
}
},
"Retry-After": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
},
"WWW-Authenticate": {
"schema": {
"type": "string"
},
"description": "Bearer challenge for 401 responses."
}
},
"content": {
"application/problem+json": {
"schema": {
"allOf": [
{
"allOf": [
{
"$ref": "#/components/schemas/Problem"
},
{
"properties": {
"code": {
"enum": [
"invalid_request"
]
},
"status": {
"const": 400
}
}
}
]
},
{
"properties": {
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
},
"operation_id": {
"type": "null"
},
"status_path": {
"type": "null"
},
"code": {
"not": {
"enum": [
"operation_in_progress",
"operation_reconciling",
"completion_uncertain",
"budget_exhausted",
"funding_window_too_short"
]
}
}
}
}
]
},
"example": {
"type": "urn:sustema:entity:problem:invalid_request",
"title": "Malformed JSON, duplicate keys, timestamp, header or structural input.",
"status": 400,
"code": "invalid_request",
"request_id": "00000007-1111-4111-8111-000000000007",
"operation_id": null,
"retry_action": "do_not_retry",
"usage_state": "not_started"
}
}
},
"x-error-codes": [
"invalid_request"
]
},
"401": {
"description": "unauthenticated",
"headers": {
"Cache-Control": {
"schema": {
"const": "private, no-store"
}
},
"Entity-Request-Id": {
"schema": {
"type": "string",
"format": "uuid"
}
},
"Retry-After": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
},
"WWW-Authenticate": {
"schema": {
"type": "string"
},
"description": "Bearer challenge for 401 responses."
}
},
"content": {
"application/problem+json": {
"schema": {
"allOf": [
{
"allOf": [
{
"$ref": "#/components/schemas/Problem"
},
{
"properties": {
"code": {
"enum": [
"unauthenticated"
]
},
"status": {
"const": 401
}
}
}
]
},
{
"properties": {
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
},
"operation_id": {
"type": "null"
},
"status_path": {
"type": "null"
},
"code": {
"not": {
"enum": [
"operation_in_progress",
"operation_reconciling",
"completion_uncertain",
"budget_exhausted",
"funding_window_too_short"
]
}
}
}
}
]
},
"example": {
"type": "urn:sustema:entity:problem:unauthenticated",
"title": "Missing/invalid access token; no protected resource details.",
"status": 401,
"code": "unauthenticated",
"request_id": "00000007-1111-4111-8111-000000000007",
"operation_id": null,
"retry_action": "reauthenticate",
"usage_state": "not_started"
}
}
},
"x-error-codes": [
"unauthenticated"
]
},
"403": {
"description": "permission_denied; authority_revoked",
"headers": {
"Cache-Control": {
"schema": {
"const": "private, no-store"
}
},
"Entity-Request-Id": {
"schema": {
"type": "string",
"format": "uuid"
}
},
"Retry-After": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
},
"WWW-Authenticate": {
"schema": {
"type": "string"
},
"description": "Bearer challenge for 401 responses."
}
},
"content": {
"application/problem+json": {
"schema": {
"allOf": [
{
"allOf": [
{
"$ref": "#/components/schemas/Problem"
},
{
"properties": {
"code": {
"enum": [
"permission_denied",
"authority_revoked"
]
},
"status": {
"const": 403
}
}
}
]
},
{
"properties": {
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
},
"operation_id": {
"type": "null"
},
"status_path": {
"type": "null"
},
"code": {
"not": {
"enum": [
"operation_in_progress",
"operation_reconciling",
"completion_uncertain",
"budget_exhausted",
"funding_window_too_short"
]
}
}
}
}
]
},
"example": {
"type": "urn:sustema:entity:problem:permission_denied",
"title": "Authenticated principal lacks the action/resource grant.",
"status": 403,
"code": "permission_denied",
"request_id": "00000007-1111-4111-8111-000000000007",
"operation_id": null,
"retry_action": "do_not_retry",
"usage_state": "not_started"
}
}
},
"x-error-codes": [
"permission_denied",
"authority_revoked"
]
},
"404": {
"description": "resource_not_found",
"headers": {
"Cache-Control": {
"schema": {
"const": "private, no-store"
}
},
"Entity-Request-Id": {
"schema": {
"type": "string",
"format": "uuid"
}
},
"Retry-After": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
},
"WWW-Authenticate": {
"schema": {
"type": "string"
},
"description": "Bearer challenge for 401 responses."
}
},
"content": {
"application/problem+json": {
"schema": {
"allOf": [
{
"allOf": [
{
"$ref": "#/components/schemas/Problem"
},
{
"properties": {
"code": {
"enum": [
"resource_not_found"
]
},
"status": {
"const": 404
}
}
}
]
},
{
"properties": {
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
},
"operation_id": {
"type": "null"
},
"status_path": {
"type": "null"
},
"code": {
"not": {
"enum": [
"operation_in_progress",
"operation_reconciling",
"completion_uncertain",
"budget_exhausted",
"funding_window_too_short"
]
}
}
}
}
]
},
"example": {
"type": "urn:sustema:entity:problem:resource_not_found",
"title": "Unknown resource, or tenant-private reference intentionally concealed.",
"status": 404,
"code": "resource_not_found",
"request_id": "00000007-1111-4111-8111-000000000007",
"operation_id": null,
"retry_action": "do_not_retry",
"usage_state": "not_started"
}
}
},
"x-error-codes": [
"resource_not_found"
]
},
"422": {
"description": "Bounded zero-unit refusal: input-phase not_started; delivery-phase unchanged; no financial effect or reverse operation reference.",
"headers": {
"Cache-Control": {
"schema": {
"const": "private, no-store"
}
},
"Entity-Request-Id": {
"schema": {
"type": "string",
"format": "uuid"
}
},
"Retry-After": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
},
"WWW-Authenticate": {
"schema": {
"type": "string"
},
"description": "Bearer challenge for 401 responses."
}
},
"content": {
"application/problem+json": {
"schema": {
"allOf": [
{
"allOf": [
{
"allOf": [
{
"allOf": [
{
"$ref": "#/components/schemas/Problem"
},
{
"properties": {
"code": {
"enum": [
"invalid_request",
"unauthenticated",
"permission_denied",
"authority_revoked",
"resource_not_found",
"rate_limited",
"concurrency_limited",
"dependency_unavailable",
"internal_error",
"limit_out_of_range"
]
}
}
}
]
},
{
"properties": {
"code": {
"const": "limit_out_of_range"
},
"status": {
"const": 422
},
"retry_action": {
"const": "do_not_retry"
},
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
}
}
},
{
"properties": {
"operation_id": {
"type": "null"
},
"status_path": {
"type": "null"
}
}
}
]
},
{
"properties": {
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
},
"operation_id": {
"type": "null"
},
"status_path": {
"type": "null"
},
"code": {
"not": {
"enum": [
"operation_in_progress",
"operation_reconciling",
"completion_uncertain",
"budget_exhausted",
"funding_window_too_short"
]
}
}
}
}
]
},
{
"if": {
"properties": {
"code": {
"const": "limit_out_of_range"
},
"delivery_limit": {
"properties": {
"phase": {
"const": "delivery"
}
},
"required": [
"phase"
]
}
},
"required": [
"code",
"delivery_limit"
]
},
"then": {
"properties": {
"usage_state": {
"const": "unchanged"
}
}
}
}
]
}
}
}
},
"429": {
"description": "rate_limited; concurrency_limited",
"headers": {
"Cache-Control": {
"schema": {
"const": "private, no-store"
}
},
"Entity-Request-Id": {
"schema": {
"type": "string",
"format": "uuid"
}
},
"Retry-After": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
},
"WWW-Authenticate": {
"schema": {
"type": "string"
},
"description": "Bearer challenge for 401 responses."
}
},
"content": {
"application/problem+json": {
"schema": {
"allOf": [
{
"allOf": [
{
"$ref": "#/components/schemas/Problem"
},
{
"properties": {
"code": {
"enum": [
"rate_limited",
"concurrency_limited"
]
},
"status": {
"const": 429
}
}
}
]
},
{
"properties": {
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
},
"operation_id": {
"type": "null"
},
"status_path": {
"type": "null"
},
"code": {
"not": {
"enum": [
"operation_in_progress",
"operation_reconciling",
"completion_uncertain",
"budget_exhausted",
"funding_window_too_short"
]
}
}
}
}
]
},
"example": {
"type": "urn:sustema:entity:problem:rate_limited",
"title": "Throughput admission refused.",
"status": 429,
"code": "rate_limited",
"request_id": "00000007-1111-4111-8111-000000000007",
"operation_id": null,
"retry_action": "wait_then_retry_same_operation",
"usage_state": "not_started"
}
}
},
"x-error-codes": [
"rate_limited",
"concurrency_limited"
]
},
"500": {
"description": "internal_error",
"headers": {
"Cache-Control": {
"schema": {
"const": "private, no-store"
}
},
"Entity-Request-Id": {
"schema": {
"type": "string",
"format": "uuid"
}
},
"Retry-After": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
},
"WWW-Authenticate": {
"schema": {
"type": "string"
},
"description": "Bearer challenge for 401 responses."
}
},
"content": {
"application/problem+json": {
"schema": {
"allOf": [
{
"allOf": [
{
"$ref": "#/components/schemas/Problem"
},
{
"properties": {
"code": {
"enum": [
"internal_error"
]
},
"status": {
"const": 500
}
}
}
]
},
{
"properties": {
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
},
"operation_id": {
"type": "null"
},
"status_path": {
"type": "null"
},
"code": {
"not": {
"enum": [
"operation_in_progress",
"operation_reconciling",
"completion_uncertain",
"budget_exhausted",
"funding_window_too_short"
]
}
}
}
}
]
},
"example": {
"type": "urn:sustema:entity:problem:internal_error",
"title": "Safe internal failure; no stack or protected payload.",
"status": 500,
"code": "internal_error",
"request_id": "00000007-1111-4111-8111-000000000007",
"operation_id": null,
"retry_action": "wait_then_retry_same_operation",
"usage_state": "not_started"
}
}
},
"x-error-codes": [
"internal_error"
]
},
"503": {
"description": "dependency_unavailable",
"headers": {
"Cache-Control": {
"schema": {
"const": "private, no-store"
}
},
"Entity-Request-Id": {
"schema": {
"type": "string",
"format": "uuid"
}
},
"Retry-After": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
},
"WWW-Authenticate": {
"schema": {
"type": "string"
},
"description": "Bearer challenge for 401 responses."
}
},
"content": {
"application/problem+json": {
"schema": {
"allOf": [
{
"allOf": [
{
"$ref": "#/components/schemas/Problem"
},
{
"properties": {
"code": {
"enum": [
"dependency_unavailable"
]
},
"status": {
"const": 503
}
}
}
]
},
{
"properties": {
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
},
"operation_id": {
"type": "null"
},
"status_path": {
"type": "null"
},
"code": {
"not": {
"enum": [
"operation_in_progress",
"operation_reconciling",
"completion_uncertain",
"budget_exhausted",
"funding_window_too_short"
]
}
}
}
}
]
},
"example": {
"type": "urn:sustema:entity:problem:dependency_unavailable",
"title": "Required policy, publication, ledger or search dependency unavailable.",
"status": 503,
"code": "dependency_unavailable",
"request_id": "00000007-1111-4111-8111-000000000007",
"operation_id": null,
"retry_action": "wait_then_retry_same_operation",
"usage_state": "not_started"
}
}
},
"x-error-codes": [
"dependency_unavailable"
]
},
"default": {
"description": "RFC 9457 problem; exact code/status/usage rules in errors.json. Current authority applies to all errors and replay.",
"headers": {
"Cache-Control": {
"schema": {
"const": "private, no-store"
}
},
"Entity-Request-Id": {
"schema": {
"type": "string",
"format": "uuid"
}
},
"Retry-After": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
},
"WWW-Authenticate": {
"schema": {
"type": "string"
},
"description": "Bearer challenge for 401 responses."
}
},
"content": {
"application/problem+json": {
"schema": {
"allOf": [
{
"allOf": [
{
"$ref": "#/components/schemas/Problem"
},
{
"properties": {
"code": {
"enum": [
"invalid_request",
"unauthenticated",
"permission_denied",
"authority_revoked",
"resource_not_found",
"rate_limited",
"concurrency_limited",
"dependency_unavailable",
"internal_error",
"limit_out_of_range"
]
}
}
}
]
},
{
"properties": {
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
},
"operation_id": {
"type": "null"
},
"status_path": {
"type": "null"
},
"code": {
"not": {
"enum": [
"operation_in_progress",
"operation_reconciling",
"completion_uncertain",
"budget_exhausted",
"funding_window_too_short"
]
}
}
}
}
]
}
}
}
}
},
"x-permission": "capabilities.read",
"x-billable": false,
"x-cross-adapter-bound": {
"operation": "getCapabilities",
"rule": "#/x-delivery-bound-contract",
"before_settlement": true
},
"description": "This pure owned read creates no new business effect or debit. Its failure reports only not_started/unchanged with null operation/status references. Existing underlying financial uncertainty is shown in the successful owned status envelope; unavailable read dependencies use the existing dependency_unavailable retry path. Never report a new reservation/settlement or invent a polling operation for this read. Original-resource disclosure: No original-object relation; current explicit integration grant controls the permitted capability projection. API integration never borrows a human or another integration relation. Every current credential/action/profile/source/retention guard still applies.",
"x-original-resource-relation": "No original-object relation; current explicit integration grant controls the permitted capability projection. API integration never borrows a human or another integration relation. Every current credential/action/profile/source/retention guard still applies."
}Referenced schemas
Includes schemas used by this operation and its shared or inherited parameters. Open a schema to follow its related definitions.
Shared parameter definitions
{
"Cursor": {
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 4096,
"x-profile-maxLength": "string_characters_max"
},
"description": "Opaque signed cursor bound to query, organisation, environment, profile, rights and index/publication generation."
},
"IdempotencyKey": {
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"maxLength": 36
},
"description": "Random UUID for one logical operation, including billed GETs. Same request/key/time replays without a second charge; ENTITY application semantics."
},
"Manifest": {
"name": "manifest_id",
"in": "query",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"maxLength": 36
},
"description": "Manifest returned by identity/search. A compatibility-bound follow-on read, not unrestricted historical query. Current rights and retention apply."
},
"MaxUnits": {
"name": "Entity-Max-Units",
"in": "header",
"required": false,
"schema": {
"$ref": "#/components/schemas/Units"
},
"description": "Caller ceiling in the accepted offer atomic unit; cannot increase organisation authority."
},
"OperationCreated": {
"name": "Entity-Operation-Created-At",
"in": "header",
"required": true,
"schema": {
"type": "string",
"format": "date-time",
"maxLength": 35
},
"description": "Original creation instant, unchanged on retry. New keys outside the profile admission/skew window are refused even after tombstone expiry."
},
"PageSize": {
"name": "page_size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"x-profile-maximum": "page_size_max"
},
"description": "Default and maximum from the active profile."
},
"ReceiptContext": {
"name": "Entity-Receipt-Context",
"in": "header",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"maxLength": 36
},
"description": "Readable own-organisation receipt containing the requested entity/manifest. Binds follow-on evidence/module reads to a known permitted result within its retention window; this is not unrestricted historical access."
},
"ServiceProfile": {
"name": "Entity-Service-Profile",
"in": "header",
"required": true,
"schema": {
"type": "string",
"maxLength": 4096,
"x-profile-maxLength": "string_characters_max"
},
"description": "Accepted immutable service-profile revision; missing/unknown profiles cannot activate an operation."
}
}Inherited path parameters
[]