ENTITY developer reference
Problem
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.
This is the public candidate schema reading view. Read it with the operation that uses it; a representable field does not establish enabled coverage or entitlement.
Delivery overflow reports actual financial state: not_started/unchanged before new work, released only after confirmed release, uncertain with the owned original operation when commitment cannot be proved. No new debit may be settled for an undeliverable billed result. Access denials remain opaque. Reserved usage requires the original authorised operation/status path and poll-or-same-operation retry. Opaque denials expose no operation, held/settled amount or internal financial state: not_started describes pre-admission refusal, unchanged means this refused request made no new change and does not assert anything about prior settlement. Server-side reconciliation continues and any original permitted finance status remains available through its own authorised projection. Unauthenticated/not_started with null references is strictly a pre-admission refusal. The final current-authority check fences admission/commit. After any business effect is admitted or its outcome becomes uncertain, no REST or MCP typed refusal may claim not_started or no effect. If current delivery authority is absent after admission, disclose no protected result and close/abort the response without a fabricated API Problem, whether or not headers were sent. The caller retains the original key, creation time, intent and any already known status ID, reauthenticates and reconciles under current ownership; never mint a new key because an acknowledgement was lost. MCP may use its protocol-only401/403 challenge before headers, but that transport status carries no business no-effect guarantee; after an attempted call clients still reconcile the original intent. The server preserves the original effect and its bounded recovery work independently of the client connection.
Declared type: "object"
Declared fields
This list shows only properties declared directly in this schema. Required labels refer only to this schema’s own required array. Referenced, composed and conditional rules can add constraints; a field not listed as required here is not guaranteed to be optional.
type
Listed in this schema’s required array.
- Declared type
"string"- Declared format
"uri-reference"
Reading definition for type
{
"type": "string",
"format": "uri-reference",
"x-profile-maxLength": "string_characters_max"
}title
Listed in this schema’s required array.
- Declared type
"string"
Reading definition for title
{
"type": "string",
"maxLength": 180,
"x-profile-maxLength": "string_characters_max"
}status
Listed in this schema’s required array.
- Declared type
"integer"
Reading definition for status
{
"type": "integer",
"minimum": 400,
"maximum": 599
}detail
Not listed in this schema’s required array.
- Declared type
"string"
Reading definition for detail
{
"type": "string",
"maxLength": 1200,
"x-profile-maxLength": "string_characters_max"
}instance
Not listed in this schema’s required array.
- Declared type
"string"- Declared format
"uri-reference"
Reading definition for instance
{
"type": "string",
"format": "uri-reference",
"x-profile-maxLength": "string_characters_max"
}code
Listed in this schema’s required array.
- Declared type
"string"
Reading definition for code
{
"type": "string",
"enum": [
"authority_revoked",
"budget_exhausted",
"change_history_expired",
"completion_uncertain",
"concurrency_limited",
"correction_pending",
"cursor_expired",
"dependency_unavailable",
"entitlement_denied",
"idempotency_conflict",
"internal_error",
"invalid_identifier",
"invalid_request",
"limit_out_of_range",
"operation_expired",
"operation_in_progress",
"operation_timeout",
"payload_too_large",
"permission_denied",
"rate_limited",
"resource_not_found",
"result_expired",
"result_invalidated",
"revision_conflict",
"unauthenticated",
"unsupported_scope"
],
"x-profile-maxLength": "string_characters_max",
"x-documentation-scope": "This shared enum contains change_history_expired and revision_conflict for private surfaces. Neither is an allowed error of the 25 public operations. Only an operation’s explicit response enum/x-error-codes authorises a public code; feedback If-Match uses stale_revision/412."
}request_id
Listed in this schema’s required array.
- Declared type
"string"- Declared format
"uuid"
Reading definition for request_id
{
"type": "string",
"format": "uuid",
"x-profile-maxLength": "string_characters_max"
}operation_id
Listed in this schema’s required array.
- Declared type
- Not declared directly; consult the complete field definition.
Reading definition for operation_id
{
"anyOf": [
{
"type": "string",
"format": "uuid",
"x-profile-maxLength": "string_characters_max"
},
{
"type": "null"
}
]
}retry_action
Listed in this schema’s required array.
- Declared type
"string"
Reading definition for retry_action
{
"type": "string",
"enum": [
"correct_request",
"reauthenticate",
"wait_then_retry_same_operation",
"poll_operation",
"start_new_operation_explicitly",
"do_not_retry"
],
"x-profile-maxLength": "string_characters_max"
}usage_state
Listed in this schema’s required array.
- Declared type
"string"
Reading definition for usage_state
{
"type": "string",
"enum": [
"not_started",
"reserved",
"settled",
"released",
"uncertain",
"unchanged"
],
"x-profile-maxLength": "string_characters_max"
}status_path
Not listed in this schema’s required array.
- Declared type
- Not declared directly; consult the complete field definition.
Reading definition for status_path
{
"anyOf": [
{
"type": "string",
"x-profile-maxLength": "string_characters_max"
},
{
"type": "null"
}
]
}invalid_fields
Not listed in this schema’s required array.
- Declared type
"array"
Reading definition for invalid_fields
{
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"maxLength": 240,
"x-profile-maxLength": "string_characters_max"
},
"reason": {
"type": "string",
"maxLength": 240,
"x-profile-maxLength": "string_characters_max"
}
},
"required": [
"path",
"reason"
],
"additionalProperties": false
},
"maxItems": 32,
"x-profile-maxItems": "collection_items_max"
}recovery
Not listed in this schema’s required array.
- Declared type
- Not declared directly; consult the complete field definition.
Reading definition for recovery
{
"$ref": "#/components/schemas/RecoveryGuidance"
}admission_reason
Not listed in this schema’s required array.
- Declared type
"string"
Reading definition for admission_reason
{
"type": "string",
"enum": [
"refresh_interval",
"serving_limit",
"internal_work_limit"
],
"x-profile-maxLength": "string_characters_max"
}next_eligible_at
Not listed in this schema’s required array.
- Declared type
- Not declared directly; consult the complete field definition.
Reading definition for next_eligible_at
{
"anyOf": [
{
"type": "string",
"format": "date-time",
"x-profile-maxLength": "string_characters_max"
},
{
"type": "null"
}
]
}delivery_limit
Not listed in this schema’s required array.
- Declared type
- Not declared directly; consult the complete field definition.
Reading definition for delivery_limit
{
"$ref": "#/components/schemas/DeliveryLimitGuidance"
}Schema reading view
Read all retained constraints, including any allOf, oneOf, anyOf, conditional and additional-property constraints. The field list does not combine branches. Explicitly marked private-only omissions mean this view is not an executable substitute for the original schema or a released contract.
{
"type": "object",
"properties": {
"type": {
"type": "string",
"format": "uri-reference",
"x-profile-maxLength": "string_characters_max"
},
"title": {
"type": "string",
"maxLength": 180,
"x-profile-maxLength": "string_characters_max"
},
"status": {
"type": "integer",
"minimum": 400,
"maximum": 599
},
"detail": {
"type": "string",
"maxLength": 1200,
"x-profile-maxLength": "string_characters_max"
},
"instance": {
"type": "string",
"format": "uri-reference",
"x-profile-maxLength": "string_characters_max"
},
"code": {
"type": "string",
"enum": [
"authority_revoked",
"budget_exhausted",
"change_history_expired",
"completion_uncertain",
"concurrency_limited",
"correction_pending",
"cursor_expired",
"dependency_unavailable",
"entitlement_denied",
"idempotency_conflict",
"internal_error",
"invalid_identifier",
"invalid_request",
"limit_out_of_range",
"operation_expired",
"operation_in_progress",
"operation_timeout",
"payload_too_large",
"permission_denied",
"rate_limited",
"resource_not_found",
"result_expired",
"result_invalidated",
"revision_conflict",
"unauthenticated",
"unsupported_scope"
],
"x-profile-maxLength": "string_characters_max",
"x-documentation-scope": "This shared enum contains change_history_expired and revision_conflict for private surfaces. Neither is an allowed error of the 25 public operations. Only an operation’s explicit response enum/x-error-codes authorises a public code; feedback If-Match uses stale_revision/412."
},
"request_id": {
"type": "string",
"format": "uuid",
"x-profile-maxLength": "string_characters_max"
},
"operation_id": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"x-profile-maxLength": "string_characters_max"
},
{
"type": "null"
}
]
},
"retry_action": {
"type": "string",
"enum": [
"correct_request",
"reauthenticate",
"wait_then_retry_same_operation",
"poll_operation",
"start_new_operation_explicitly",
"do_not_retry"
],
"x-profile-maxLength": "string_characters_max"
},
"usage_state": {
"type": "string",
"enum": [
"not_started",
"reserved",
"settled",
"released",
"uncertain",
"unchanged"
],
"x-profile-maxLength": "string_characters_max"
},
"status_path": {
"anyOf": [
{
"type": "string",
"x-profile-maxLength": "string_characters_max"
},
{
"type": "null"
}
]
},
"invalid_fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"maxLength": 240,
"x-profile-maxLength": "string_characters_max"
},
"reason": {
"type": "string",
"maxLength": 240,
"x-profile-maxLength": "string_characters_max"
}
},
"required": [
"path",
"reason"
],
"additionalProperties": false
},
"maxItems": 32,
"x-profile-maxItems": "collection_items_max"
},
"recovery": {
"$ref": "#/components/schemas/RecoveryGuidance"
},
"admission_reason": {
"type": "string",
"enum": [
"refresh_interval",
"serving_limit",
"internal_work_limit"
],
"x-profile-maxLength": "string_characters_max"
},
"next_eligible_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"x-profile-maxLength": "string_characters_max"
},
{
"type": "null"
}
]
},
"delivery_limit": {
"$ref": "#/components/schemas/DeliveryLimitGuidance"
}
},
"required": [
"type",
"title",
"status",
"code",
"request_id",
"operation_id",
"retry_action",
"usage_state"
],
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"code": {
"const": "invalid_request"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 400
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "unauthenticated"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 401
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "permission_denied"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 403
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "entitlement_denied"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 403
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "authority_revoked"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 403
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "resource_not_found"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 404
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "idempotency_conflict"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 409
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "operation_in_progress"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 409
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "revision_conflict"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 409
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "result_invalidated"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 409
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "operation_expired"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 410
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "result_expired"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 410
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "cursor_expired"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 410
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "change_history_expired"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 410
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "payload_too_large"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 413
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "unsupported_scope"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 422
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "invalid_identifier"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 422
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "limit_out_of_range"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 422
},
"usage_state": {
"enum": [
"not_started",
"unchanged",
"released",
"uncertain"
]
},
"retry_action": {
"enum": [
"correct_request",
"poll_operation",
"do_not_retry"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "rate_limited"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 429
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "concurrency_limited"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 429
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "budget_exhausted"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 429
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "dependency_unavailable"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 503
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "correction_pending"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 503
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "completion_uncertain"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 503
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "operation_timeout"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 504
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "internal_error"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 500
}
}
}
},
{
"if": {
"properties": {
"code": {
"enum": [
"invalid_request",
"invalid_identifier",
"unsupported_scope",
"payload_too_large",
"budget_exhausted"
]
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"usage_state": {
"const": "not_started"
},
"retry_action": {
"type": "string",
"enum": [
"correct_request",
"do_not_retry"
],
"x-profile-maxLength": "string_characters_max"
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "operation_in_progress"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"usage_state": {
"const": "reserved"
},
"retry_action": {
"type": "string",
"enum": [
"poll_operation",
"wait_then_retry_same_operation"
],
"x-profile-maxLength": "string_characters_max"
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "completion_uncertain"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"usage_state": {
"type": "string",
"enum": [
"reserved",
"uncertain"
],
"x-profile-maxLength": "string_characters_max"
},
"retry_action": {
"const": "poll_operation"
}
}
}
},
{
"if": {
"properties": {
"operation_id": {
"type": "null"
}
},
"required": [
"operation_id"
]
},
"then": {
"properties": {
"status_path": {
"type": "null"
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "unauthenticated"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"operation_id": {
"type": "null"
},
"status_path": {
"type": "null"
},
"usage_state": {
"const": "not_started"
}
}
}
},
{
"if": {
"required": [
"recovery"
]
},
"then": {
"properties": {
"code": {
"enum": [
"invalid_request",
"invalid_identifier",
"unsupported_scope"
]
},
"usage_state": {
"const": "not_started"
}
}
}
},
{
"if": {
"properties": {
"retry_action": {
"const": "poll_operation"
}
},
"required": [
"retry_action"
]
},
"then": {
"properties": {
"operation_id": {
"type": "string",
"format": "uuid",
"x-profile-maxLength": "string_characters_max"
},
"status_path": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"pattern": "^/v1/",
"x-profile-maxLength": "string_characters_max"
}
},
"required": [
"status_path"
]
}
},
{
"if": {
"properties": {
"admission_reason": {
"enum": [
"serving_limit",
"refresh_interval"
]
}
},
"required": [
"admission_reason"
]
},
"then": {
"properties": {
"status": {
"const": 429
},
"code": {
"const": "rate_limited"
},
"usage_state": {
"const": "not_started"
},
"retry_action": {
"const": "wait_then_retry_same_operation"
}
},
"required": [
"next_eligible_at"
]
}
},
{
"if": {
"properties": {
"code": {
"const": "limit_out_of_range"
}
},
"required": [
"code"
]
},
"then": {
"required": [
"delivery_limit"
]
}
},
{
"if": {
"properties": {
"code": {
"const": "limit_out_of_range"
},
"delivery_limit": {
"properties": {
"phase": {
"const": "input"
}
},
"required": [
"phase"
]
}
},
"required": [
"code",
"delivery_limit"
]
},
"then": {
"properties": {
"usage_state": {
"const": "not_started"
}
}
}
},
{
"if": {
"properties": {
"usage_state": {
"const": "uncertain"
}
},
"required": [
"usage_state"
]
},
"then": {
"properties": {
"retry_action": {
"const": "poll_operation"
},
"operation_id": {
"type": "string",
"format": "uuid"
},
"status_path": {
"type": "string",
"minLength": 1,
"pattern": "^/v1/operations/"
}
},
"required": [
"operation_id",
"status_path"
]
}
},
{
"if": {
"properties": {
"usage_state": {
"const": "reserved"
}
},
"required": [
"usage_state"
]
},
"then": {
"properties": {
"operation_id": {
"type": "string",
"format": "uuid"
},
"retry_action": {
"enum": [
"poll_operation",
"wait_then_retry_same_operation"
]
},
"status_path": {
"type": "string",
"pattern": "^/v1/operations/"
}
},
"required": [
"operation_id",
"status_path"
]
}
},
{
"if": {
"properties": {
"code": {
"enum": [
"rate_limited",
"concurrency_limited",
"cursor_expired"
]
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"usage_state": {
"const": "not_started"
}
}
}
},
{
"if": {
"properties": {
"code": {
"enum": [
"permission_denied",
"entitlement_denied",
"authority_revoked",
"resource_not_found"
]
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
},
"operation_id": {
"type": "null"
},
"status_path": {
"type": "null"
},
"retry_action": {
"const": "do_not_retry"
}
}
}
},
{
"if": {
"properties": {
"admission_reason": {
"const": "internal_work_limit"
}
},
"required": [
"admission_reason"
]
},
"then": {
"properties": {
"code": {
"const": "dependency_unavailable"
},
"status": {
"const": 503
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "operation_expired"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"usage_state": {
"const": "unchanged"
},
"retry_action": {
"const": "do_not_retry"
},
"operation_id": {
"type": "null"
},
"status_path": {
"type": "null"
}
}
}
}
],
"description": "Delivery overflow reports actual financial state: not_started/unchanged before new work, released only after confirmed release, uncertain with the owned original operation when commitment cannot be proved. No new debit may be settled for an undeliverable billed result. Access denials remain opaque. Reserved usage requires the original authorised operation/status path and poll-or-same-operation retry. Opaque denials expose no operation, held/settled amount or internal financial state: not_started describes pre-admission refusal, unchanged means this refused request made no new change and does not assert anything about prior settlement. Server-side reconciliation continues and any original permitted finance status remains available through its own authorised projection. Unauthenticated/not_started with null references is strictly a pre-admission refusal. The final current-authority check fences admission/commit. After any business effect is admitted or its outcome becomes uncertain, no REST or MCP typed refusal may claim not_started or no effect. If current delivery authority is absent after admission, disclose no protected result and close/abort the response without a fabricated API Problem, whether or not headers were sent. The caller retains the original key, creation time, intent and any already known status ID, reauthenticates and reconciles under current ownership; never mint a new key because an acknowledgement was lost. MCP may use its protocol-only401/403 challenge before headers, but that transport status carries no business no-effect guarantee; after an attempted call clients still reconcile the original intent. The server preserves the original effect and its bounded recovery work independently of the client connection."
}