ENTITY developer reference
Retrieve governed identity
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/entities/{entity_id}
Operation identifier: getEntity
Retrieve governed identity
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.
Entity-Service-Profile
header · Required
Accepted immutable service-profile revision; missing/unknown profiles cannot activate an operation.
Reading definition for Entity-Service-Profile
{
"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."
}Idempotency-Key
header · Required
Random UUID for one logical operation, including billed GETs. Same request/key/time replays without a second charge; ENTITY application semantics.
Reading definition for Idempotency-Key
{
"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."
}Entity-Operation-Created-At
header · Required
Original creation instant, unchanged on retry. New keys outside the profile admission/skew window are refused even after tombstone expiry.
Reading definition for Entity-Operation-Created-At
{
"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."
}Entity-Max-Units
header · Optional
Caller ceiling in the accepted offer atomic unit; cannot increase organisation authority.
Schema: Units
Reading definition for Entity-Max-Units
{
"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."
}entity_id
path · Required
Reading definition for entity_id
{
"name": "entity_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"maxLength": 36
}
}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": "getEntity",
"summary": "Retrieve governed identity",
"parameters": [
{
"$ref": "#/components/parameters/ServiceProfile"
},
{
"$ref": "#/components/parameters/IdempotencyKey"
},
{
"$ref": "#/components/parameters/OperationCreated"
},
{
"$ref": "#/components/parameters/MaxUnits"
},
{
"name": "entity_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"maxLength": 36
}
}
],
"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/EntityResponse"
},
"example": {
"data": {
"subject": {
"entity_id": "00000001-1111-4111-8111-000000000001",
"environment": "synthetic-review",
"manifest_id": "00000002-1111-4111-8111-000000000002",
"subject_type": "legal_entity"
},
"lifecycle": {
"state": "active",
"successors": [],
"reason": null,
"recorded_at": "2026-09-01T12:10:00Z"
},
"publication": {
"manifest_id": "00000002-1111-4111-8111-000000000002",
"published_at": "2026-09-01T12:15:00Z",
"identity_revision": "synthetic-identity-1",
"source_checkpoint_refs": [
"synthetic-source-1"
],
"policy_revision": "synthetic-policy-1",
"relationship_revision": null,
"classification_revision": null
},
"claims": [
{
"claim_id": "00000003-1111-4111-8111-000000000003",
"claim_version_id": "00000004-1111-4111-8111-000000000004",
"predicate": "legal_name",
"availability": "available",
"value": {
"kind": "text",
"text": "Example Demonstration Limited"
},
"evidence": {
"level": "discovery",
"selection_policy_id": "synthetic-selection-1",
"linkage_policy_id": "synthetic-linkage-1",
"explanation": "Synthetic registered-name fixture; no real source or verification.",
"limitations": [
"Illustrative data only"
],
"confidence_meaning": "qualitative_policy_assessment_not_probability",
"assessment": {
"assessment_id": "90000000-0000-4000-8000-000000000001",
"method_revision": "sei-0.1",
"predicate_policy_revision": "synthetic-registered-identity-1",
"evaluated_at": "2026-09-09T12:00:00Z",
"as_of": {
"precision": "unknown"
},
"source_linkage": {
"state": "not_assessed",
"score_basis_points": null,
"display_percent": null,
"zone": null,
"zone_label": "Not assessed",
"interpretation": "We do not have a usable basis to assess this information.",
"explanation": "This older synthetic assertion has no qualified SEI evidence basis.",
"meaning": "evidence_index_not_probability",
"method_revision": "sli-0.1",
"zone_policy_revision": "sez-0.1"
},
"attribute_support": {
"state": "not_assessed",
"score_basis_points": null,
"display_percent": null,
"zone": null,
"zone_label": "Not assessed",
"interpretation": "We do not have a usable basis to assess this information.",
"explanation": "This older synthetic assertion has no qualified SEI evidence basis.",
"meaning": "evidence_index_not_probability",
"method_revision": "sei-0.1",
"zone_policy_revision": "sez-0.1"
},
"delivered_support": {
"state": "not_assessed",
"score_basis_points": null,
"display_percent": null,
"zone": null,
"zone_label": "Not assessed",
"interpretation": "We do not have a usable basis to assess this information.",
"explanation": "This older synthetic assertion has no qualified SEI evidence basis.",
"meaning": "evidence_index_not_probability",
"method_revision": "sei-0.1",
"zone_policy_revision": "sez-0.1"
},
"conflict": "not_assessed",
"explanation": {
"summary": "Earlier synthetic fact, not assessed under SEI 0.1.",
"reason_codes": [
"policy_not_qualified"
],
"limiting_factors": [
"Synthetic review example; not empirical evidence."
],
"next_checks": [
"Qualify the applicable source and service profile before live use."
],
"scope_statement": "This exact synthetic company, assertion and stated time only."
},
"calibration_status": "not_calibrated",
"disclosure": "permitted_basis",
"target": "fact_for_entity_predicate_scope_and_time",
"calculation": {
"state": "unavailable",
"reason": "No SEI basis supplied for this earlier synthetic assertion."
}
}
},
"clocks": {
"effective_from": {
"precision": "unknown"
},
"effective_until": {
"precision": "unknown"
},
"source_published": {
"precision": "unknown"
},
"acquired": {
"precision": "instant",
"value": "2026-09-01T12:00:00Z"
},
"processed": {
"precision": "instant",
"value": "2026-09-01T12:10:00Z"
},
"verified": {
"precision": "unknown"
}
},
"evidence_path": "/v1/entities/00000001-1111-4111-8111-000000000001/evidence?manifest_id=00000002-1111-4111-8111-000000000002",
"limitations": [
"Synthetic fixture"
],
"freshness": {
"state": "unknown",
"age_basis": "unknown",
"evaluated_at": "2026-09-07T10:00:00Z",
"policy_revision": "synthetic-freshness-1",
"age_min_seconds": null,
"age_max_seconds": null
}
}
],
"modules": [],
"limitations": [
"Not a real entity result"
],
"confidence_summary": {
"state": "unavailable",
"method_revision": "sei-0.1",
"rating": {
"state": "not_assessed",
"score_basis_points": null,
"display_percent": null,
"zone": null,
"zone_label": "Not assessed",
"interpretation": "We do not have a usable basis to assess this information.",
"explanation": "No qualified SEI aggregate profile supplied.",
"meaning": "evidence_index_not_probability",
"method_revision": "sei-0.1",
"zone_policy_revision": "sez-0.1"
},
"reason": "assessment_unavailable",
"explanation": "This older synthetic result has no SEI aggregate basis; no percentage is inferred."
},
"completeness": "complete_permitted_projection",
"projection_binding": {
"profile_id": "architecture-qualification-example-inactive",
"profile_revision": "1",
"slot_manifest_sha256": "a3c1747d93f81c16dcb00b5371c9bad6847feb5f39d2f33959ba3011ca4205ae",
"confidence_policy_revision": "sei-0.1"
},
"slot_outcomes": [
{
"slot_id": "identity.name",
"state": "provided",
"claim_ids": [
"00000003-1111-4111-8111-000000000003"
]
}
]
},
"receipt": {
"receipt_id": "00000005-1111-4111-8111-000000000005",
"operation_id": "00000006-1111-4111-8111-000000000006",
"environment": "synthetic-review",
"committed_at": "2026-09-07T10:00:00Z",
"accepted_offer_id": "11111111-1111-4111-8111-111111111111",
"original_period_id": "00000008-1111-4111-8111-000000000008",
"subject_versions": [
{
"entity_id": "00000001-1111-4111-8111-000000000001",
"environment": "synthetic-review",
"manifest_id": "00000002-1111-4111-8111-000000000002",
"subject_type": "legal_entity"
}
],
"profile_revision": "synthetic-review-1",
"policy_revision": "synthetic-policy-1",
"charged_units": "1",
"unit": "synthetic_operation_unit",
"unit_scale": 1,
"settlement": "settled",
"result_available_until": "2026-09-08T10:00:00Z",
"receipt_available_until": "2026-09-14T10:00:00Z",
"delivery_meaning": "authorised_delivery_commit_not_client_receipt",
"projection": "full_permitted",
"offer_binding": {
"offer_id": "11111111-1111-4111-8111-111111111111",
"offer_version": 1,
"offer_sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"policy_pins": {
"tariff": {
"id": "synthetic-policy",
"version": "1",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"terms": {
"id": "synthetic-policy",
"version": "1",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"credit": {
"id": "synthetic-policy",
"version": "1",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"refresh": {
"id": "synthetic-policy",
"version": "1",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"retrieval": {
"id": "synthetic-policy",
"version": "1",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"eligibility": {
"id": "synthetic-policy",
"version": "1",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"protection": {
"id": "synthetic-policy",
"version": "1",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"rights": {
"id": "synthetic-policy",
"version": "1",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"success": {
"id": "synthetic-policy",
"version": "1",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
},
"agreement_id": "22222222-2222-4222-8222-222222222222",
"agreement_revision": 1,
"funded_period_id": "00000008-1111-4111-8111-000000000008",
"selection_evidence_id": "22222222-2222-4222-8222-222222222222"
},
"classification_order_id": null,
"classification_item_ids": []
},
"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": [
{
"$ref": "#/components/schemas/Problem"
},
{
"properties": {
"code": {
"enum": [
"invalid_request"
]
},
"status": {
"const": 400
}
}
}
]
},
"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": [
{
"$ref": "#/components/schemas/Problem"
},
{
"properties": {
"code": {
"enum": [
"unauthenticated"
]
},
"status": {
"const": 401
}
}
}
]
},
"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; entitlement_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": [
{
"$ref": "#/components/schemas/Problem"
},
{
"properties": {
"code": {
"enum": [
"permission_denied",
"entitlement_denied",
"authority_revoked"
]
},
"status": {
"const": 403
}
}
}
]
},
"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",
"entitlement_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": [
{
"$ref": "#/components/schemas/Problem"
},
{
"properties": {
"code": {
"enum": [
"resource_not_found"
]
},
"status": {
"const": 404
}
}
}
]
},
"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"
]
},
"409": {
"description": "idempotency_conflict; operation_in_progress; result_invalidated",
"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": [
{
"$ref": "#/components/schemas/Problem"
},
{
"properties": {
"code": {
"enum": [
"idempotency_conflict",
"operation_in_progress",
"result_invalidated"
]
},
"status": {
"const": 409
}
}
}
]
},
"example": {
"type": "urn:sustema:entity:problem:idempotency_conflict",
"title": "Same key with different canonical request or creation time.",
"status": 409,
"code": "idempotency_conflict",
"request_id": "00000007-1111-4111-8111-000000000007",
"operation_id": "00000006-1111-4111-8111-000000000006",
"retry_action": "do_not_retry",
"usage_state": "unchanged"
}
}
},
"x-error-codes": [
"idempotency_conflict",
"operation_in_progress",
"result_invalidated"
]
},
"410": {
"description": "operation_expired; result_expired",
"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": [
{
"$ref": "#/components/schemas/Problem"
},
{
"properties": {
"code": {
"enum": [
"operation_expired",
"result_expired"
]
},
"status": {
"const": 410
}
}
}
]
},
"example": {
"type": "urn:sustema:entity:problem:operation_expired",
"title": "Old logical request outside retained/admission window; not newly charged.",
"status": 410,
"code": "operation_expired",
"request_id": "00000007-1111-4111-8111-000000000007",
"operation_id": null,
"retry_action": "do_not_retry",
"usage_state": "unchanged",
"status_path": null
}
}
},
"x-error-codes": [
"operation_expired",
"result_expired"
]
},
"413": {
"description": "payload_too_large",
"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": [
{
"$ref": "#/components/schemas/Problem"
},
{
"properties": {
"code": {
"enum": [
"payload_too_large"
]
},
"status": {
"const": 413
}
}
}
]
},
"example": {
"type": "urn:sustema:entity:problem:payload_too_large",
"title": "Body exceeds profile admission limit.",
"status": 413,
"code": "payload_too_large",
"request_id": "00000007-1111-4111-8111-000000000007",
"operation_id": null,
"retry_action": "do_not_retry",
"usage_state": "not_started"
}
}
},
"x-error-codes": [
"payload_too_large"
]
},
"422": {
"description": "unsupported_scope; limit_out_of_range",
"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": [
{
"$ref": "#/components/schemas/Problem"
},
{
"properties": {
"code": {
"enum": [
"unsupported_scope",
"limit_out_of_range"
]
},
"status": {
"const": 422
}
}
}
]
},
"example": {
"type": "urn:sustema:entity:problem:unsupported_scope",
"title": "Well-formed territory/identifier/module/projection is not released in profile.",
"status": 422,
"code": "unsupported_scope",
"request_id": "00000007-1111-4111-8111-000000000007",
"operation_id": null,
"retry_action": "do_not_retry",
"usage_state": "not_started"
}
}
},
"x-error-codes": [
"unsupported_scope",
"limit_out_of_range"
]
},
"429": {
"description": "rate_limited; concurrency_limited; budget_exhausted",
"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": [
{
"$ref": "#/components/schemas/Problem"
},
{
"properties": {
"code": {
"enum": [
"rate_limited",
"concurrency_limited",
"budget_exhausted"
]
},
"status": {
"const": 429
}
}
}
]
},
"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",
"budget_exhausted"
]
},
"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": [
{
"$ref": "#/components/schemas/Problem"
},
{
"properties": {
"code": {
"enum": [
"internal_error"
]
},
"status": {
"const": 500
}
}
}
]
},
"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; correction_pending; completion_uncertain",
"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": [
{
"$ref": "#/components/schemas/Problem"
},
{
"properties": {
"code": {
"enum": [
"dependency_unavailable",
"correction_pending",
"completion_uncertain"
]
},
"status": {
"const": 503
}
}
}
]
},
"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",
"correction_pending",
"completion_uncertain"
]
},
"504": {
"description": "operation_timeout",
"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": [
{
"$ref": "#/components/schemas/Problem"
},
{
"properties": {
"code": {
"enum": [
"operation_timeout"
]
},
"status": {
"const": 504
}
}
}
]
},
"example": {
"type": "urn:sustema:entity:problem:operation_timeout",
"title": "Deadline exceeded; status determines final reservation/settlement.",
"status": 504,
"code": "operation_timeout",
"request_id": "00000007-1111-4111-8111-000000000007",
"operation_id": "00000006-1111-4111-8111-000000000006",
"retry_action": "poll_operation",
"usage_state": "uncertain",
"status_path": "/v1/operations/00000006-1111-4111-8111-000000000006"
}
}
},
"x-error-codes": [
"operation_timeout"
]
},
"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": [
{
"$ref": "#/components/schemas/Problem"
},
{
"properties": {
"code": {
"enum": [
"invalid_request",
"unauthenticated",
"permission_denied",
"entitlement_denied",
"authority_revoked",
"resource_not_found",
"idempotency_conflict",
"operation_in_progress",
"result_invalidated",
"operation_expired",
"result_expired",
"payload_too_large",
"unsupported_scope",
"limit_out_of_range",
"rate_limited",
"concurrency_limited",
"budget_exhausted",
"dependency_unavailable",
"correction_pending",
"completion_uncertain",
"operation_timeout",
"internal_error"
]
}
}
}
]
}
}
}
}
},
"x-permission": "entity.read",
"x-billable": true,
"x-cross-adapter-bound": {
"operation": "getEntity",
"rule": "#/x-delivery-bound-contract",
"before_settlement": true
}
}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
[]