ENTITY developer reference
API operations
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 25 public operations in the candidate contract. These pages describe the contract; they do not invoke a service. Operation-specific request, response and Problem schemas govern interpretation.
Field dictionary · Errors and recovery
- Search companies
POST /v1/searchessearchCompanies - Resolve one reference
POST /v1/resolutionsresolveReference - Look up an identifier
POST /v1/identifier-lookupslookupIdentifier - Retrieve governed identity
GET /v1/entities/{entity_id}getEntity - Retrieve evidence
GET /v1/entities/{entity_id}/evidencegetEvidence - Retrieve direct relationships
GET /v1/entities/{entity_id}/relationshipsgetRelationships - Retrieve bounded hierarchy
GET /v1/entities/{entity_id}/hierarchygetHierarchy - Retrieve industry classification
GET /v1/entities/{entity_id}/classificationsgetClassifications - Inspect capabilities and coverage
GET /v1/capabilitiesgetCapabilities - Inspect usage and limits
GET /v1/usagegetUsage - Inspect own operation
GET /v1/operations/{operation_id}getOperation - Inspect permitted receipt
GET /v1/receipts/{receipt_id}getReceipt - Inspect permitted classification prices, success rules and supported targets
GET /v1/classification-offerslistClassificationOffers - Quote a bounded entity/standard selection without paid research
POST /v1/classification-quotescreateClassificationQuote - Read the original immutable quote
GET /v1/classification-quotes/{quote_id}getClassificationQuote - Accept a quote against existing delegated credits
POST /v1/classification-orderscreateClassificationOrder - Read progress, credit reservation and settlement
GET /v1/classification-orders/{order_id}getClassificationOrder - Read bounded per-standard outcomes and acquired-result references
GET /v1/classification-orders/{order_id}/itemsgetClassificationOrderItems - Fence unstarted work and reconcile in-flight results
POST /v1/classification-orders/{order_id}/cancelcancelClassificationOrder - Read an owned versioned classification and permitted evidence
GET /v1/classification-acquisitions/{acquisition_id}getClassificationAcquisition - Report an owned classification debit or evidence issue without a new charge
POST /v1/classification-adjustment-requestscreateClassificationAdjustmentRequest - Read automatic verification and credit-correction outcome
GET /v1/classification-adjustment-requests/{adjustment_request_id}getClassificationAdjustmentRequest - Submit an owned field report
POST /v1/feedbacksubmitFeedback - Read an owned field report
GET /v1/feedback/{feedback_id}getFeedback - Supply requested evidence for the same report
POST /v1/feedback/{feedback_id}/evidencesupplyFeedbackEvidence
All public schemas
- CapabilitiesResponse
- ClassificationsResponse
- EntityResponse
- EvidenceResponse
- FeedbackEvidenceRequest
- FeedbackProblem
- FeedbackRequest
- FeedbackResponse
- HierarchyResponse
- ICAcquisitionResponse
- ICAdjustmentRequest
- ICAdjustmentResponse
- ICCancelRequest
- ICOffersPageResponse
- ICOrderItemsPageResponse
- ICOrderRequest
- ICOrderResponse
- ICProblem
- ICQuoteRequest
- ICQuoteResponse
- IdentifierLookupRequest
- OperationResponse
- Problem
- ReceiptResponse
- RelationshipsResponse
- ResolutionResponse
- ResolveRequest
- SearchRequest
- SearchResponse
- Units
- UsageResponse
- CapabilitiesResult
- ClassificationsResult
- DeliveryLimitGuidance
- Entity
- EvidenceResult
- FeedbackEvidence
- FeedbackResult
- FeedbackTarget
- HierarchyResult
- ICAcquisition
- ICAdjustment
- ICInputEntity
- ICOffersPage
- ICOrder
- ICOrderItemsPage
- ICQuote
- ICTarget
- ICVersionRef
- InputIdentifier
- InputReference
- Meta
- OperationResult
- PolicyPin
- PriorAssessment
- Receipt
- RecoveryGuidance
- RelationshipsResult
- ResolutionResult
- SearchResult
- SearchScope
- UsageResult
- AssessmentLineageProjection
- Availability
- Candidate
- CapabilityProfile
- Claim
- Classification
- Completeness
- ConfidenceSummary
- CreditBalances
- EntityCompleteness
- Environment
- EvidenceContribution
- EvidenceSummary
- GraphBoundary
- ICOffer
- ICOperationResult
- ICOrderAccounting
- ICOrderCounts
- ICOrderItem
- ICQuoteEntity
- ICServiceRemedyGrantStatus
- ICSuccessRule
- ICUsage
- ICValue
- IdentityConfidence
- InputAddress
- InputHints
- InputNormalisation
- KnownTime
- LegacyOperationResult
- Lifecycle
- ModuleState
- OfferBinding
- PackagePolicy
- Page
- ProjectionBinding
- Publication
- RecoveryAction
- Relationship
- SourceAttribution
- SubjectRef
- SubscriptionUsage
- UsageHeadroom
- AggregateAssessment
- AggregateTopic
- AssessmentClocksProjection
- Clocks
- ConfidenceExplanation
- EvidenceLevel
- FactConfidence
- Freshness
- FulfilmentDisposition
- ICBundleRate
- ICOutcomePrice
- ICQuoteTarget
- ICStandardRate
- Identifier
- Limits
- NormalisationIssue
- OfferPolicyPins
- OriginLineage
- PercentageScore
- PublicContractBinding
- ResolvedOfferPolicy
- SEIPercentageScore
- SupportRating
- TypedValue
- UsageBudgetHeadroom
- Address
- AggregateSlot
- AssessmentPlan
- ConfidenceCalculation
- CustomerWorkLimits
- EvidenceClock
- FreshnessBasis
- LegalForm
- LocalizedText
- OriginNode
- OutcomeTariffs
- RefreshLimits
- ServingLimits
Reading scope and explicitly excluded private details
- All 25 public operations and 143 public schema pages are retained. Private account, staff, commercial-control and integration APIs are not published here. A console recovery locator requires its separate current browser/account authority; an API credential does not grant that authority.
- DeliveryLimitGuidance.operation_name shows the public-operation subset of a shared enum. Private account-operation members are deliberately withheld, not renamed or offered as callable public APIs. The type and all other public guidance constraints remain visible.
- Private console route patterns for account_recovery_path and order_history_path are deliberately withheld. These structured locators require full-path validation against the matching qualified console binding’s exact allowlisted template before navigation, plus exact original-workspace and, for account recovery, case-ID equality. Unknown original context, unknown templates or mismatches prevent navigation. This reading view cannot supply an implementation-ready validator; use the matching separately released console binding. No public order-list or support-case endpoint is implied.
- The shared error catalogue and Problem.code include two private-only codes that are not applicable to any of the 25 public operations. Those codes remain labelled as outside public-operation applicability, not offered as public recovery instructions. Operation-specific code/status/retry/usage constraints govern.
- Internal legacy operation labels are omitted in favour of the exact public operationId. Dictionary stewardship/source-field inventory labels are omitted from term displays; their public field meanings, current semantics, scope, precision and restrictions remain visible. Private distribution details are described only to explain their separation from public API rights.
Known candidate discrepancies and qualification gaps
- getClassifications: the 409 response prose mentions operation_in_progress and the 503 prose mentions completion_uncertain, but the corresponding operation-specific error enums do not include those codes. The explicit response enums and x-error-codes govern; those prose mentions do not add allowed responses.
- PackagePolicy: its retained title says it is not current UsageResult, while UsageResult requires package_policy. Follow the explicit required property and its referenced structure; the stale title does not make the field optional.
- Units: the retained regular expression can accept a trailing newline in some validators. This documentation does not amend that original constraint or establish strict-client qualification.
- Three of the 25 operations have no inline success-response examples in the retained candidate: listClassificationOffers, createClassificationAdjustmentRequest and getClassificationAdjustmentRequest. Complete release-qualified examples and actual first-use traces remain separate acceptance work; the documentation does not imply those checks passed.
Shared candidate contract rules
These rules preserve the public disclosure, attribution, fee and recovery meanings. Private governance aliases are replaced with their public meaning. The reading view does not publish private APIs or change the underlying candidate.
{
"x-contract-revision": "0.18.0-architecture-candidate",
"x-profile-bound-schema-rule": "Generic templates carry profile annotations without synthetic literals. Compile annotations across response AND request schemas, including parameters, to selected finite values. Preserve explicit field-specific semantic caps using the smaller value and expose those caps in the compiled schemas. Reject incomplete or incoherent limits, including quote create/readback mismatch and default page beyond search capacity. Publish one immutable generation with profile, limits, API, MCP, dictionary and encoder-set content hashes. Inactive fixtures are not released schemas. Cursor responses never exceed the input Cursor maximum (4096 and profile minimum); route-specific page-size ceilings are50offers/100order-items. Explicit field semantic/protocol caps are intersected with the profile, never widened.",
"x-delivery-bound-contract": {
"status": "Documented candidate contract; runtime qualification pending.",
"encoding": "Released adapters use their pinned compact JSON encoder: no insignificant whitespace, no optional slash escaping, strict valid Unicode, stable property order, no NaN/Infinity. Count actual encoded bytes including ASCII Unicode escapes and MCP text-embedded JSON escaping; never estimate MCP as2xREST. Encoder revisions are part of adapter qualification and cannot change after admission.",
"precommit": "For every billable/replayable result, build or bounded-stream-count each released adapter representation before settlement, with worst-case allowed metadata, envelope/framing and post-acceptance/readback fields reserved. Persist sufficient immutable committed representation/binding for every authorised adapter replay. Send the checked bytes; later metadata/adapter changes cannot make a committed result undeliverable. Reject before paid work where determinable; after reservation confirm release or retain uncertainty truthfully.",
"bound_selection": "effective_bytes(operation)=operation_response_bytes_max[operation] or response_bytes_max. Use this same bound for all adapters, including complete quote creation AND readback lifecycle forms. Compiler rejects unequal quote create/readback byte/node bounds. Request/node overrides are selected independently; every advertised bound is enforced.",
"memory": "Bound decoded string length, array items, nesting, total JSON nodes and encoded buffer while reading/building, using paged queries and counting before materialisation. Stop at the first bound; an encoder bound is not permission to allocate an unbounded input graph.",
"overflow": "No arbitrary truncation of JSON, lineage, source clocks, finance or required information. Use only defined pagination/truthful graph boundaries; otherwise return typed delivery_limit guidance with actual settlement/release state.",
"schema_compilation": "Generic templates carry profile annotations without synthetic literals. Compile annotations across response AND request schemas, including parameters, to selected finite values. Preserve explicit field-specific semantic caps using the smaller value and expose those caps in the compiled schemas. Reject incomplete or incoherent limits, including quote create/readback mismatch and default page beyond search capacity. Publish one immutable generation with profile, limits, API, MCP, dictionary and encoder-set content hashes. Inactive fixtures are not released schemas.",
"adapter_set": "CapabilityProfile.adapter_set names every supported adapter and exact encoder revision, escaping policy and envelope limits. No implicit or newly added adapter after commitment. MCP id is string at most128Unicode characters or an integer in the interoperable safe range; reject longer/invalid ids before business admission without echoing them. Request _meta is subject to request/depth/node limits, is not copied to output, and can never expand the response envelope.",
"replay": "A caller selects the immutable profile/generation using the existing profile binding (and profile-bound MCP session/tools listing). Retain and route that generation with its schemas and encoder set for the complete promised result/receipt-reference lifetime. A new tighter profile is a separate opt-in generation; never substitute it for retained replay. Existing reference reads retain their original representation bounds even after new-work admission closes. Current rights/invalidation still apply. Release qualification must reject profile retirement or encoder replacement while retained references depend on it. Safe initial deployment: one compiled wire generation per endpoint. Do not replace it with tighter output byte/node/field limits or a schema rejecting any retained result or permitted lifecycle form. Compiler rejects numeric tightening against every retained profile; release acceptance also requires complete retained-generation inventory and semantic schema/encoder compatibility. Until a multiple-generation client/transport mechanism is explicitly qualified, incompatible generations cannot coexist on that endpoint. No new endpoint or automatic migration is introduced.",
"hierarchy": "Choose one deterministic permitted graph prefix fitting ALL pinned adapters with boundary/completeness metadata reserved, then commit that same logical nodes/edges/paths set. Stable traversal ordering is relationship type, destination public ID, relationship ID; resolve ties by full public edge tuple. A capacity/depth boundary means incomplete. If even root plus truthful boundary cannot fit, fail with typed guidance before settlement.",
"attribution": "Size/count exhaustion is a delivery-limit refusal, never permission to drop a licensed field or credit. Rights-based withholding is distinct and uses existing opaque availability rules. Count actual required credits/pointers and their escaped representation before commitment.",
"evidence_continuation": "If a single lawfully visible contribution cannot fit alone, return limit_out_of_range with a signed continuation_cursor immediately after it and its permitted skipped_contribution_id. Before it, return any preceding representable page normally. The cursor binds tenant, original query/receipt/snapshot, profile, rights, expiry and a sticky omission flag; advancing is explicit client choice. Later pages retain incomplete scope and delivery_limit_omission reason. Do not disclose hidden IDs or silently skip, debit twice, restart research or omit lineage. Expired cursor uses cursor_expired; new explicit retrieval starts a new view."
},
"x-owned-classification-order-projection": {
"rule": "Every visible order/operation field, revision, timestamp, count, accounting quantity, reason, error, cursor and notification is derived only from this owner's admitted actions/commitments, proved owned acquisitions/settlements and permitted published evidence. Persist the order public revision, timestamp and visible-content digest separately from private worker revisions. Hidden shared-job progress cannot advance them or make an expected_revision stale. Own accepted actions and changed permitted content atomically advance the public revision; identical replay/read does not. Item-page order_revision and cancellation expected_revision name this same owned revision. Current rights and the whole permitted publication history, including publication times, are part of the projection input.",
"cancellation": "Cancellation linearises in the existing order/acquisition transaction against the owned public order revision. Preserve only acquisitions proved committed for this order before that cut-off; cancel every target not yet committed to it and release its unearned customer reservation. Merely prepared, running, coalesced or privately published worker output earns no customer fee. Fence later attachment/acquisition for the cancelled target. Reconcile genuinely uncertain pre-cut-off owned commits before declaring final money; provider costs alone are Sustema exposure and cannot manufacture a customer financial uncertainty. A late shared result may serve another entitled customer but cannot revive this cancelled target. This binds the cancellation policy: only acquisitions committed before the cancellation cut-off retain their original charge; it does not change tariffs/refunds or cancel another customer's work.",
"storage": "Existing order row stores internal transaction revision separately from public revision, public updated_at and a SHA256 permitted-view digest. The digest covers all owned visible content excluding transport correlation and its own revision/time. The order and acquisition/settlement journal share the existing transaction guard; no worker lifecycle field is a public CAS token.",
"acceptance": "Hold caller actions, authority and permitted publication history fixed; vary private coalescing, worker start/finish and cooldown. Compare order/item/operation, pages/cursors, cancellation success or error and monetary outcome. Separately race actual owned acquisition commit against cancellation in both orders; allow only the pre-cut-off committed outcome or zero-debit cancelled target."
},
"x-attribution-bounds": "Attribution is part of the complete response bytes and JSON-node budget. Group/pointer cardinality compiles from json_nodes_max, so32different source-update dates are not an independent ceiling. Admit the entire rights-safe credited response before delivery; never truncate credits or fabricate dates. Oversized output has an explicit existing response-limit failure and a smaller bounded page/request, not a paid retry loop.",
"x-classification-retention": {
"classes": {
"a": "bounded receipt-to-subject, quote/order/item and delivery-history joins",
"b": "separately authorised finite current acquisition/remedy/contractual purpose",
"c": "subject-free financial, invoice, funding and accepted-term history",
"d": "replay/result/source payload under its shorter applicable policy"
},
"quote": "Subject-bearing ICQuote content expires by created_at + 90 days or earlier rights/deletion. Acceptance expiry still independently prevents new acceptance. getClassificationQuote returns resource_expired/410 after retained content ends; expiry never frees a consumed quote for a new order.",
"order": "ICOrder, ICOrderItem, item pages and their quote/receipt/acquisition links are class(a). Their history cutoff is no later than 90 days after the earliest original delivery in that order (accepted_at if none), or earlier applicable rights/deletion. A later group, update, retry, cancellation or financial adjustment never restarts this clock. Live work must finish within its already bounded accepted deadline; it cannot justify indefinite history.",
"operation": "At that cutoff, getOperation for a classification order returns operation_expired/410; it must not emit ICOperationResult or recover the expired order through an operation, receipt, cursor, adjustment, export, log or reverse index. Owned classification order/item/adjustment-history reads return resource_expired/410. A known irrecoverable loss before expiry retains the distinct history_unavailable rule. Opaque denial precedes every expiry response.",
"separate_purposes": "Class(b) preserves only fields necessary for its independently recorded purpose and finite authority. It does not extend the generic order/quote/status history or the class(c) finance projection. An unresolved financial case keeps subject-free amounts/identities plus only a separately authorised necessary case scope, not the whole expired order. Invoices, original debits, retained accepted terms and legitimate claims do not expire just because class(a) does.",
"tombstone": "Consumed-quote/client-reference and operation retry tombstones use the qualified nonreversible deduplication policy. They may reject an expired/reused intent but cannot reconstruct expired subjects or return the deleted order body. Fresh intent requires its own authorised current quote; reusing an expired identity creates no new debit.",
"shared_order_join_cutoff": "Every receipt-to-order/item link, finance order/adjustment-request join, ICOperationResult and generic adjustment history uses the SAME order class(a) cutoff: earliest original delivery in that order +90days, or accepted_at +90days if none, intersected with earlier rights/deletion. Later-group delivery never extends the order join. A later receipt may retain its independently lawful own subject window while classification_order_id=null and classification_item_ids=[] from the earlier order cutoff. No reverse index reconstructs the removed join.",
"expired_mutations": "After the owned retained order cutoff, identical createClassificationOrder replay, cancelClassificationOrder and createClassificationAdjustmentRequest return resource_expired/410, do_not_retry, unchanged and null operation/status; never revive a subject-linked body or create a new effect from a tombstone. Expired generic getOperation returns operation_expired/410 with unchanged, do_not_retry and null references, never uncertain/poll-to-self. Underlying uncertain effects continue server-side and survive only in authorised subject-free finance/case status. Legitimate financial claims use existing support-case intake in the signed-in console with original permitted invoice/payment/finance evidence, not expired classification IDs. Current ownership and foreign-resource opacity precede expiry."
},
"x-input-text-limit-contract": {
"counting": "Unicode code points of decoded input, before normalisation; not UTF8bytes or UTF16code units. Request-byte and JSON-node limits apply independently. No truncation or input-value logging.",
"name": "Each InputReference.name <= min(name_characters,string_characters_max).",
"identifier": "Each InputIdentifier.value <= min(identifier_characters,string_characters_max) plus released scheme shape/checksum/meaning.",
"address": "All non-null textual values in one InputAddress, including lines entries,kind,language/script/country context, sum <= address_characters; object keys/syntax do not count. Each field also respects string_characters_max.",
"refusal": "invalid_request/400,correct_request before admission for semantic aggregate overflow. The core public Problem schema uses usage_state not_started; FeedbackProblem retains zero customer_debit_units and its own reference rules. A corrected request is deliberate; do not automatically retry unchanged input.",
"outputs": "These three named limits govern input only; do not truncate or constrain output entity names/identifier values to input-specific lengths."
},
"x-post-admission-delivery-authority": "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. An ingress401/not_started after a same-key retry describes only that rejected attempt; it does not disprove an earlier admitted or uncertain effect. Keep original key/created_at and reauthenticate/reconcile. Starters must not mint a new key from that401. Under the initial single-generation endpoint, do not switch profile until every unresolved original key and its promised retry window as well as every dependent result/receipt reference has retired, unless a separately qualified compatible recovery path preserves those exact original defaults, intent and representation. Mere absence of a known operation ID is not retirement evidence. A stale/unknown profile refusal on a same-key retry describes that rejected attempt only, never proves that the original request had no effect; keep the original key/created_at and reconcile. Never mint a replacement key from that refusal."
}