# DeltaX Hosted Bounded Review Evaluation API

## Current hosted soak — beta2

Hosted Evaluate is in controlled free soak (2026-09-16.beta2). Access is restricted. Selection is not execution. The offline kit is the pinned beta1 teaching snapshot.

- Live API version: `2026-09-16.beta2`.
- Route: `POST /v1/evaluations`.
- Profile: `deltax-hosted-bounded-review-evaluation-v1`.
- Restricted access; x402 off; not GA. No public signup, pricing, or SLA.
- Responses do not execute candidates or grant downstream authority.

## Historical / pinned kit contract — beta1

**Snapshot version:** `2026-09-16.beta1`

**OpenAPI:** `3.1.0` · `openapi.yaml` remains beta1, not the live beta2 specification.

**Public OpenAPI SHA-256:** `4a638426371640b0833c6db0bebaede3e1070ce0d6b6ad89b62e4d1117ad6c1e`

**Historical snapshot status:** `frozen_design_contract_c0_m0_no_live_endpoint`

The sections below document the pinned beta1 teaching snapshot. Its C0/M0,
placeholder identity configuration, and false availability/authority fields
are historical snapshot metadata, not the current hosted product status.
Hosted callers use their approved beta2 contract and access configuration.

## Beta1 snapshot boundary

This contract accepts one bounded objective, bounded scalar context, and a finite candidate set. It returns either one selected submitted candidate or the service-generated governed_noop_refusal. A response does not perform, authorize, publish, deploy, certify, or make safe any candidate. This historical C0/M0 design snapshot grants no service access or release authority.

Historical beta1 recorded `https://api.deltaxevaluate.com` as a planned hostname.
Its placeholder token URL and unavailable-endpoint fields apply only to that
snapshot. The current product status is the restricted beta2 soak above.

### Authority state

| Field | Value |
|---|---|
| `semantic_conformance_level` | `C0` |
| `operational_maturity_level` | `M0` |
| `implementation_authorized` | `false` |
| `evaluation_execution_authorized` | `false` |
| `customer_access_authorized` | `false` |
| `customer_data_collection_authorized` | `false` |
| `account_action_authorized` | `false` |
| `credential_action_authorized` | `false` |
| `tenant_onboarding_authorized` | `false` |
| `spend_authorized` | `false` |
| `external_effect_authorized` | `false` |
| `learning_or_state_mutation_authorized` | `false` |
| `release_authorized` | `false` |
| `publication_authorized` | `false` |
| `deployment_authorized` | `false` |
| `downstream_action_authorized` | `false` |
| `consequential_action_authorized` | `false` |

## Endpoint

| Method | Path | Operation |
|---|---|---|
| `POST` | `/v1/evaluations` | `createBoundedEvaluation` |

Authenticates a machine caller, derives tenant and principal identity from server-owned allowlist state, validates a closed request, and returns either a selected submitted candidate or governed_noop_refusal after a tenant-bound trace commit. The operation never executes the submitted candidate and grants no downstream authority.

No other route or method is part of this contract.

## Authentication and identity

- OAuth 2.0 machine-to-machine client credentials.
- Required scope: `deltax:evaluate`.
- Token URL is a non-routable placeholder: `https://auth.deltax.invalid/oauth/token`.
- The identity provider and issuer were not assigned in this historical beta1 snapshot.
- Tenant and principal IDs are derived from verified server-owned mappings; neither is accepted in the request.
- Authentication identifies and constrains a caller. It does not grant candidate or downstream authority.

## Required request headers

| Header | Exact rule |
|---|---|
| `X-DeltaX-API-Version` | Required; must equal `2026-09-16.beta1`. |
| `Idempotency-Key` | Required; 16–128 characters; pattern `^[A-Za-z0-9._~-]+$`. |

Only `application/json` request content is admitted. JSON must be UTF-8;
duplicate object keys and non-finite numbers are rejected.

## Request body

`EvaluationRequest` is closed with `additionalProperties: false`.

| Field | Required | Exact shape |
|---|---:|---|
| `profile_id` | yes | string constant `deltax-hosted-bounded-review-evaluation-v1` |
| `objective` | yes | string 1–1024 characters |
| `context` | yes | BoundedScalarContext |
| `candidates` | yes | 1–8 `Candidate` items |

Candidate objects are closed and require `candidate_id`, `semantic_class`,
`description`, and `operator_reported_support`. Candidate IDs must be unique
inside one request; semantic validation failures return `422`.

### Candidate catalog

- Selectable: `analyze`, `compare`, `draft`, `validate`.
- Shadow-only and never selectable: `external`.
- Service-generated fallback: `governed_noop_refusal`.
- Unknown class: `422_fail_closed`.

### Frozen request and admission limits

| Limit | Value |
|---|---:|
| `encoded_body_bytes` | `32768` |
| `aggregate_header_bytes` | `16384` |
| `header_count` | `32` |
| `objective_characters` | `1024` |
| `context_entries` | `16` |
| `context_key_characters` | `64` |
| `context_string_characters` | `256` |
| `candidates_minimum` | `1` |
| `candidates_maximum` | `8` |
| `candidate_description_characters` | `512` |
| `request_deadline_milliseconds` | `5000` |
| `tenant_requests_per_60_seconds` | `60` |
| `tenant_concurrent_requests` | `4` |
| `idempotency_retention_seconds` | `86400` |
| `retry_after_seconds_maximum` | `60` |
| `spend_ceiling` | `not_configured_fail_closed` |

A missing configured spend ceiling fails closed; nothing in this contract
authorizes spend.

## Idempotency

- Required header: `Idempotency-Key`.
- Scope: `authenticated_tenant_id`, `authenticated_principal_id`, `HTTP_method`, `route`, `API_version`, `profile_id`, `release_set_digest`.
- Same scoped key and digest: `return_exact_committed_response_zero_duplicate_evaluation_work`.
- Same scoped key with a different digest: `409_idempotency_conflict`.
- Cross-tenant or principal collision: `independent_keyspace_no_disclosure`.
- Retention: `86400` seconds.

## Success response (`200`)

`EvaluationResponse` is closed with `additionalProperties: false` and requires:

- `request_id`
- `api_version`
- `profile_id`
- `outcome`
- `selected_candidate_id`
- `reason_codes`
- `trace`
- `authority`

Outcomes are exactly `selected` or `governed_noop_refusal`.
`selected_candidate_id` is a submitted, non-`external` candidate ID only
when the outcome is `selected`; it is `null` for `governed_noop_refusal`.

Every eligible response reports all 12 `HES-G01`–`HES-G12` lambda
decisions and a committed trace summary. The trace explicitly states:
`submitted_candidate_executed=false`, `external_effect=false`,
`learning_applied=false`, and `operator_reported_context_verified=false`.

## Error contract

| Status | Code | Meaning | Retryable | Retry-After |
|---:|---|---|---:|---:|
| `400` | `invalid_request` | malformed JSON, duplicate key, unknown field, missing field, invalid header, or schema violation. | `false` | no |
| `401` | `unauthenticated` | bearer token missing, invalid, expired, wrong issuer/audience, or cryptographically unacceptable. | `false` | no |
| `403` | `forbidden` | known principal lacks exact scope, active allowlist, tenant mapping, profile, or request authority. | `false` | no |
| `408` | `request_timeout` | the bounded five-second request deadline elapsed before a committed response. | `true` | no |
| `409` | `idempotency_conflict` | the same scoped Idempotency-Key was used with a different canonical request digest. | `false` | no |
| `413` | `payload_too_large` | encoded request body exceeds 32768 bytes. | `false` | no |
| `415` | `unsupported_media_type` | Content-Type is not application/json with UTF-8-compatible encoding. | `false` | no |
| `422` | `unprocessable_content` | structurally valid content violates candidate uniqueness, closed catalog, scalar, or semantic constraints. | `false` | no |
| `429` | `rate_limited` | edge rate, tenant quota, concurrency, or approved spend guard denies admission before evaluation. | `true` | required |
| `431` | `headers_too_large` | header count, an individual header, or aggregate request headers exceed the frozen limits. | `false` | no |
| `500` | `internal_failure` | fail-closed internal error; no candidate result is returned and no submitted candidate is executed. | `false` | no |
| `503` | `service_unavailable` | overload, unavailable trace/database dependency, closed release gate, or safe shutdown blocks evaluation. | `true` | required |

Errors use `application/problem+json` and the closed `ErrorResponse` schema.
Messages are bounded and must not expose tokens, tenant data, stack traces,
queries, secrets, or raw payloads. Only `408`, `429`, and `503` are
retryable; `Retry-After` is required on `429` and `503`.

## Versioning and drift

- `style`: `path_major_plus_required_calendar_contract_header`
- `breaking_change`: `new_major_path_or_new_exact_contract_version_and_separate_release_review`
- `unknown_version`: `400_fail_closed`
- `deprecation`: `no_implicit_deprecation_or_sunset; requires_versioned_notice_and_release_record`

Any route, method, field, schema, catalog, limit, auth, error, idempotency,
version, claim, effect, evidence, or authority change invalidates the public
reference, SDK fixtures, tests, and release set until they are regenerated and
revalidated.

## Evidence and claim limits

- This file and the OpenAPI source are design artifacts, not implementation or operational evidence.
- Operator-reported context and support remain operator-reported unless separately verified.
- A selected candidate is neither executed nor established as correct or safe.
- A trace is inspectable lineage, not certification or legal non-repudiation.
- Tests, staging, signatures, and green gates remain evidence and do not authorize release or deployment.