docs/API_CONTRACT.md

API Contract (ORIGINAL REFERENCE)

STATUS: the project's authoritative API-contract reference, preserved from the source repository where the documentation-guard tests validate it. It is included here because those tests and several documents refer to it by name.

For the release-facing description of the same contract — including the shipped topology, the gateway mirror, the error taxonomy and the entrypoint requirements — see architecture/08-api-contract.md. Where the two differ in emphasis, that chapter describes the shipped system.

---

SatQuery AI — Backend API Contract (v1)

Status: SPECIFICATION — the backend implementation is described in docs/DEPLOYMENT_ARCHITECTURE.md; endpoints below are the contract the frontend MUST be built against.

Audience: the frontend agent (Cloudflare Pages), and any other API consumer.

Authority: the request/response shapes are not invented here. They are the existing, tested Pydantic models in core/schemas.py. This document describes them; it does not define new ones. Where a shape is described, the model name is given so it can be read directly in the source.

---

1. Conventions

Aspect	Value
Scheme	HTTPS only (the gateway redirects plain HTTP)
Base path	/v1/
Content types	Requests: application/json (or multipart/form-data for image upload). Responses: application/json
Character encoding	UTF-8
Timestamps	ISO 8601 with Z offset, e.g. 2026-09-22T04:12:21.000Z
Field naming	snake_case throughout (matches the Pydantic models)
Versioning	Path version (/v1/). A change that removes a field, changes a field's type or meaning, or adds a required field moves to /v2/. A purely additive field that existing clients can ignore does not bump the version — but see §1.1: because the server forbids unknown fields on write, adding an input field is a breaking change for old servers, not for old clients
Schema version	Every response carries schema_version. Currently "1.0" (core/schemas.py:21)
Machine-readable errors	Every error body carries a stable code string from the taxonomy in §5

1.1 Unknown fields are REJECTED, on read and on write

CORRECTED 2026-09-22 (C-2). This section previously claimed that consumers "MUST tolerate unknown fields on read (forward compatibility)" and that only the write direction was strict. That was wrong, and the code is authoritative.

ResultEnvelope, HealthStatus, AnalysisRequest and every other contract-facing model in core/schemas.py sets extra="forbid" — with exactly one exception, GeoMetadata, which sets extra="allow" (see below). Pydantic applies forbid symmetrically: an unknown field in a request body is a 422, and an unknown field in a response body raised during model_validate is a ValidationError. A client that parses a response through these models does not get forward compatibility — it gets a hard failure the moment the server emits a field it has never heard of.

The one exception, and why it is deliberate. GeoMetadata (core/schemas.py:120) sets extra="allow" and is the only model in the codebase that does. It is the geospatial descriptor attached to AssetMetadata.geo and SpecialistResult.geospatial, so it is reachable in every /v1/analyze response. The reason is that a raster reader supplies whatever tags the source file carries, and forbidding unknown keys there would discard provenance a caller may need.

What this means for a client. The strictness rule above holds for every shape except the contents of a geospatial/geo object. A strict validator will reject an unexpected top-level field, but must not reject an unexpected key inside geospatial — the server may legitimately add one without a version bump. Treat that sub-object as the single open surface in the contract.

This exception was recorded in docs/STEP7_BACKEND_CHAIN_REPORT.md but had never reached this document, which is the one a client author reads. Recorded here by the STEP 8 audit as finding C-8.

The consequences, stated plainly because they are easy to get wrong:

• Additive changes are not free. Adding a field to a response breaks any client that validates strictly. This is why §2.1's modalities field could not simply be dropped into the capability entry without recording it here.
• A version bump is required when a field is added, not only when one is removed. The old row in the table above said the opposite; the corrected row says what the code does.
• Clients should be written permissively even though the server is strict. That is a client-side robustness measure, not a server guarantee, and the server must not be documented as if it provided one.

The direction of this correction matters: the documentation was the wrong half, so the documentation was fixed and extra="forbid" was left alone. Loosening the schema to match the prose would have replaced a clear failure with a silently-ignored field, which is worse for a machine-readable contract.

---

2. Endpoints

The surface is four endpoints. The plan fixed three; the owner ruling of 2026-09-22 added the fourth by choosing Option A for upload (§2.5).

Method	Path	Purpose	Auth
GET	/v1/health	Liveness + which models are loaded	none
GET	/v1/capabilities	What this deployment can actually do right now	none
POST	/v1/analyze	Run one analysis request	none (see §7)
POST	/v1/assets	Upload one image out of band; returns an opaque handle	none (see §7, §2.5)

---

2.1 GET /v1/health

Liveness probe. Cheap. Must not load a model, must not touch the GPU.

Response 200 — shape is HealthStatus (core/schemas.py:392). This is the measured output of a deployment where the CROMA checkpoint is not shipped:

{
  "status": "degraded",
  "schema_version": "1.0",
  "models": {
    "caption": "not_requested",
    "change": "not_requested",
    "change_vqa": "not_requested",
    "grounding": "not_requested",
    "optical_sar": "absent",
    "vqa": "not_requested"
  },
  "device": "cpu",
  "gpu_available": false
}

Every capability the registry resolves appears in models, and the set is identical to capabilities[].task in §2.2 — the two endpoints are generated from one source, so they cannot enumerate different capabilities. A key is never absent; a capability that cannot be served is reported with a state, not by omission.

Field	Type	Notes
status	"ok" | "degraded" | "error"	degraded = the service is up but at least one capability is not servable. Derived, not asserted: any absent capability makes the service degraded; any unavailable makes it error
schema_version	string	Always present
models	object<string,string>	Per-capability state. Values are strings, not booleans, so a reason can be carried. See §2.3 for the vocabulary
device	string | null	"cpu", "cuda", "mps", or null if unknown
gpu_available	boolean	Whether a CUDA/MPS device was detected. false is normal on ZeroGPU Spaces until a request is executing

device is a closed set, and null means the value was not understood. F-8, corrected here (2026-09-22). This row has always published four legal values, but the reader accepted any string and echoed it into the field, so SATQUERY_DEVICE=garbage served {"device": "garbage"} — a value the frontend has no rendering for. The reader now casefolds and validates against the set above; anything unrecognised is served as null. null is deliberately not a silent "cpu": reporting the CPU because the operator mistyped would be a false statement about the deployment, and it is the same mistake that F-7 fixed in a different variable. The case of the operator's input is also no longer significant: before this fix SATQUERY_DEVICE=CUDA resolved differently from SATQUERY_DEVICE=cuda, which let one payload claim gpu_available: true alongside device: "CUDA".

Invariant the frontend may rely on: if device == "cuda" then gpu_available is true. The converse does not hold — a GPU may exist while device is "cpu" (the operator chose it, or the config did).

Important for the frontend: gpu_available: false on a ZeroGPU Space is expected, not an error. ZeroGPU allocates the GPU only for the duration of a decorated call. Do not surface this as a fault.

This endpoint is answered without loading any model and without importing torch — the device is resolved from configuration, not by probing the runtime. A liveness probe that built the world would consume GPU quota to say "I am alive".

---

2.2 GET /v1/capabilities

What the deployment can do right now, derived from actual artifact presence — not from what the code could theoretically do.

Every capability the registry resolves is listed, including ones this deployment cannot serve. A capability that cannot be served is reported available: false with a reason, never omitted: omitting it would make it invisible to the frontend, which cannot disable an affordance it was never told about.

Response 200 — this is the measured output of a deployment where four of the six capabilities lack their runtime dependencies and optical_sar lacks its CROMA checkpoint:

{
  "schema_version": "1.0",
  "capabilities": [
    {
      "task": "change",
      "available": true,
      "reason": null,
      "requires_pair": true,
      "max_assets": 2
    },
    {
      "task": "change_vqa",
      "available": true,
      "reason": null,
      "requires_pair": true,
      "max_assets": 2
    },
    {
      "task": "optical_sar",
      "available": false,
      "reason": "the CROMA backbone checkpoint (CROMA_base.pt) is not present in this deployment; without it optical/SAR fusion degrades to sensor-only; the trained optical/SAR fusion head is not present in this deployment; without it no fused prediction is produced",
      "requires_pair": true,
      "max_assets": 2,
      "modalities": ["optical", "sar"]
    },
    {
      "task": "caption",
      "available": true,
      "reason": "the SmolVLM weights are fetched from the Hugging Face Hub on first use and no local checkpoint_path is configured in this deployment",
      "requires_pair": false,
      "max_assets": 1
    }
  ],
  "deployment": {
    "platform": "huggingface-spaces",
    "zerogpu": true,
    "lazy_load": true,
    "cache_max_models": 1,
    "torch_compile": false
  }
}

(Abridged: the real response lists all six. grounding and vqa are omitted here only to keep the example readable. The two reasons shown are verbatim -- note that optical_sar's names two missing artifacts, because two are required and both are absent.)

Field	Type	Notes
capabilities[].task	string	One of the Task enum values (§3.1)
capabilities[].available	boolean	Whether the task can be served on this deployment right now
capabilities[].reason	string | null	Required when available is false. A bare false with no reason is not compliant
capabilities[].modalities	string[]	Optional; present only for optical_sar. Valid pairings for a modality-sensitive task
capabilities[].requires_pair	boolean	Whether two assets are required
capabilities[].max_assets	integer	Maximum assets accepted
deployment.platform	string	Deployment target, e.g. "huggingface-spaces"
deployment.zerogpu	boolean	Whether GPU work runs under ZeroGPU's per-call allocation
deployment.lazy_load	boolean	true means models load on first use; this is what makes not_requested the normal state (§2.3.1)
deployment.cache_max_models	integer	Resident-model cap. 1 means requests serialize — see the obligation below
deployment.torch_compile	boolean	Always false. torch.compile is unsupported on ZeroGPU and the config loader hard-fails on true (finding C-8). Echoed here so an operator can confirm the constraint from a single response

A reason on an available capability is not a defect. Three capabilities above are available: true and still carry a reason — it reads "…fetched from the Hub on first use, no local checkpoint configured". That is not an error; it is a disclosure that the first request will be slow and will need egress. A frontend that treats a non-null reason as a failure will mislay every cold start.

Contract obligations:

• The frontend MUST build its UI affordances from this response, not from a hardcoded list. A capability that is available: false must be shown as disabled with its reason displayed — never hidden, never silently downgraded to a different task.
• The deployment block echoes configs/deploy.yaml. Note cache_max_models: 1: at most one model is resident. Concurrent requests for different specialists will evict each other, so the frontend must not assume parallel throughput.

---

2.3 Capability state vocabulary

Used in GET /v1/health → models, and consistent with capabilities.

These five words are the complete permitted vocabulary. They are the contract's vocabulary and are not the registry's — see §2.3.1.

Value	Meaning
"loaded"	Resident and ready
"absent"	The artifact is not present in this deployment. Permanent for this revision; not retryable
"unavailable"	Present but could not be loaded (corrupt, incompatible, dependency missing). This is a defect, distinct from absent
"not_requested"	Nothing has attempted to load it yet (normal with lazy_load: true)
"evicted"	Was loaded, was unloaded to make room (cache_max_models: 1)

absent and unavailable must not be conflated in the UI. Absent means "this build does not ship it"; unavailable means "this build ships it and it is broken".

---

2.3.1 Why there is a translation layer, and what it must never leak

Added 2026-09-22 by owner ruling. This is the section that explains the otherwise-odd fact that the system has two capability vocabularies.

The registry — the component that resolves specialists — speaks a different language from this contract.

The adapter derives the contract state; it does not read a live registry state. This is the one fact about the layer that is easy to get backwards, so it is stated first. app/deployment.py inspects the registry's declared spec table and the filesystem and derives the contract state from what it finds. It never calls build()/build_all(), because requirement 4 (DEPLOYMENT_ARCHITECTURE.md §3.3) forbids loading a model to answer a metadata request. A live registry state is therefore not observable on this path, and the registry's word is reconstructed from the contract state — not translated into it.

That inversion has one visible consequence: loaded is never emitted, and neither is degraded. A capability whose artifacts are all present and which has not yet been asked for is reported not_requested, not loaded, because "a model is resident" is a claim no process can honestly make without having loaded it. The following table is exhaustive — it lists every state the adapter can produce:

Contract state	When it is emitted	available	Why
not_requested	All declared shipped artifacts are present, and nothing has attempted a load. The normal healthy state under lazy_load: true	true	Nothing is missing. Emitting loaded here would claim a model was resident, which cannot be known without loading one (requirement 4)
absent	A required shipped artifact is not on disk in this deployment	false	Nothing is broken; the deployment does not ship it. The reason names the specific artifact
unavailable	Construction was attempted in this process and failed (defect path only)	false	Present but broken — a genuine defect, which the contract keeps distinct from absent
evicted	(never emitted)	—	A runtime model-cache fact. No static inspection can observe it, so the server never claims it
loaded	(never emitted)	—	See above. Note the vocabulary is closed, so a client must still be prepared to read it if a future revision emits it

available: true and models: "not_requested" coexist by design, and that is not a contradiction. The two fields answer different questions: available is "can this deployment serve this capability?" and not_requested is "has anything loaded it yet?". Under lazy_load: true the healthy answer to the second is no, not yet — for every capability, including ones that will work perfectly on the first request. A frontend that treats not_requested as a fault will mislabel a fully working deployment.

Two consequences the frontend must internalise:

1. unavailable means the opposite thing on each side of the layer. To the registry it is "no builder could be constructed" — a benign state that includes simply not having the artifact. To this contract it is "present but broken, therefore a defect". The same spelling, opposite severity. This is precisely why the layer exists, and why the table above is the only definition a client may rely on. Note the important corollary: the benign registry meaning does not surface as unavailable here — a missing artifact surfaces as absent, which is a different word and a different remedy.
2. A capability is never omitted for being unservable. It is reported available: false with a reason. The registry resolves six capabilities regardless of what this host can run.

The registry's own vocabulary is internal and is never served on any endpoint. /v1/health and /v1/capabilities are the only sources a client needs, and both are generated from the contract vocabulary above.

---

2.4 POST /v1/analyze

Run one analysis. This is the only endpoint that can consume GPU quota.

Request (JSON)

Shape is AnalysisRequest (core/schemas.py:374). extra="forbid".

{
  "assets": ["asset_0", "asset_1"],
  "query": "How has the built-up area changed between these two dates?",
  "force_task": "change_vqa",
  "run_id": "9f2c1c0e-4a5b-4f5e-9a2c-1b3d4e5f6a7b"
}

Field	Type	Required	Notes
assets	string[]	yes	Minimum length 1. Values are asset handles returned by the upload step (§2.5), not base64 and not URLs
query	string	yes	Natural language. Empty string is permitted by the schema but will route to an unsupported_query error in practice
force_task	string | null	no	One of the Task values (§3.1). Bypasses the intent router
run_id	string | null	no	Client-supplied correlation id. If omitted the server generates one. The server always echoes a run_id in the response, so the client should record whichever value comes back

Request (multipart/form-data) — the upload path

When images are uploaded directly, use:

POST /v1/analyze
Content-Type: multipart/form-data

Part	Type	Notes
assets	file, repeatable	1–2 image files. Field name repeats for the pair
request	text	A JSON string of the AnalysisRequest body with assets omitted

Not yet implemented. The multipart entry point is part of the gateway's contract but the reference implementation serves the JSON form only. See §8 for the status boundary. Build the frontend against the JSON form, which pairs with POST /v1/assets.

---

2.5 POST /v1/assets — IMPLEMENTED (Option A)

Superseded decision record. The paragraphs below originally recorded this endpoint as an unresolved gap with two options. The owner ruling of 2026-09-22 chose Option A (out-of-band upload with opaque ephemeral handles). The endpoint is built and is part of the served surface. The original reasoning is retained verbatim underneath, because the reason the fourth endpoint exists at all is the argument in it.

AnalyzeRequest.assets is list[str] — asset handles, not bytes — and the plan defines no upload endpoint. Those two facts cannot both hold without a fourth endpoint, so there is one.

Request. multipart/form-data with exactly one part, the file. The Content-Type of the part is the declared type.

Response 201.

{
  "asset_id": "asset_7c6f64a4a4c821e25d518467a1cc5d47",
  "content_type": "image/png",
  "bytes": 20481,
  "expires_at": "2026-09-22T04:42:21.000Z"
}

Three guarantees the frontend depends on, and the shape of each:

Concern	Guarantee
Opacity	asset_id is asset_ + 32 hex characters, from secrets.token_hex(16). It is 128 bits of entropy and carries no information about the upload — no filename, no type, no index, no position. There is no auth in v1 (§7), so this handle is the access control for the uploaded bytes
Size limit	A per-file byte cap, configurable per deployment (see §2.5.1). It is enforced at two layers and a client should rely on both. The gateway refuses an over-limit body from a declared Content-Length and, since the F-6 fix, while reading the bytes — so omitting the header does not evade it (gateway/app.py::_read_body_bounded). The Space does the same: since the F-9 fix it refuses while reading via the shared gateway/assets.py::read_body_bounded, rather than buffering the body and leaving the cap to store.put(). Both layers therefore refuse an over-limit body without holding it in full, and either one alone is sufficient — a client that reaches the Space directly is covered, not only one that goes through the gateway. An over-limit upload gets 413 and writes nothing

F-6, corrected here (2026-09-22). This row previously read "enforced on the received bytes — not on a declared Content-Length". That described the store correctly and the gateway incorrectly: at the gateway the cap was applied only to the header, because policy.admit runs before the body is read and the header is the only evidence it has. Measured through the real ASGI stack with the cap at 8 MiB and a 12 MiB body: a declared Content-Length drew 413 (peak 0.2 MiB, 0 bytes read) but an omitted one drew 502 with a peak of 13.9 MiB — the whole body buffered past the cap. Allocation then tracked body size exactly with no ceiling (1/8/16/32/64 MiB in → 3.0/8.1/16.0/32.0/64.0 MiB allocated). The gateway now enforces the cap while reading, and pinning tests assert both the refusal and that the boundary is still inclusive at exactly the cap.

F-7, corrected here (2026-09-22). The cap is set by one variable, SATQUERY_MAX_FILE_BYTES, read by both layers — and until this fix each layer parsed it separately, so "one variable" did not mean "one value". Measured on four inputs (probe probe_f7_cap_parsers.py): 'abc' and '4e6' made the gateway raise at startup while the Space silently returned the 4 MiB default; '0' and '-1' were accepted by the gateway while the Space rejected them only when the first upload arrived. Neither layer was right in both directions. Both now refuse an unparsable or non-positive value, naming the variable, and a cross-layer agreement test drives the whole matrix through both real parsers. A deployment whose cap is malformed no longer starts at all, at either layer, instead of quietly running on a limit nobody chose. | Content-type allowlist | A closed list of exactly five types: image/tiff · image/geotiff · image/png · image/jpeg · application/octet-stream. A request with no declared type is refused rather than defaulted — defaulting is how a PDF reaches a raster reader. A disallowed type gets 415. Media-type parameters are ignored, so image/tiff; charset=binary is accepted (gateway/assets.py::_normalise_content_type). image/tiff is the type the geospatial specialists need — a client that uploads only PNG/JPEG can serve the VQA, caption and grounding tasks but not the change or optical/SAR ones | | Retries | There is no idempotency key. A retry is a new upload that mints a new handle; the previous handle is not reused and is not revoked, it simply lapses on its TTL. A client that retries must therefore use the latest handle, and should expect the abandoned one to occupy a slot until it expires |

Errors. 413 over the size limit · 415 unsupported or absent content type · 503 the asset store is not configured on this deployment · 400 for a malformed body. All use the §5 envelope.

Lifetime. Handles expire on a TTL and are refused on read once lapsed — a lapsed handle is rejected even if nothing has swept it, so a client never succeeds by racing a cleanup job. Capacity is bounded, and a live handle is never evicted to make room: when the store is full it refuses (503) rather than invalidating a handle a client is about to use. A handle is single-use in practice — consuming it in /v1/analyze does not consume it, so the same handle may be analysed repeatedly until it expires.

What asset_id is not. It is not a path, and the response never discloses one. The stored filename is derived from the content type, never from the client's filename, so a client-supplied ../../ cannot influence where bytes land.

---

2.5.1 Original decision record (retained)

The gap this section originally recorded was stated as "NOT IN THE PLAN": the plan fixes the surface at three endpoints, none of which accepts a file, yet AnalyzeRequest.assets is list[str] of handles. Both cannot be true without a fourth endpoint. The phrase is preserved here because it is the finding, and a decision record that deletes the problem it solved is not a record.

Option	Shape	Trade-off
A. Out-of-band upload — CHOSEN	POST /v1/assets → {"asset_id": "...", "expires_at": "..."}. Frontend uploads first, then calls /v1/analyze with the returned ids	Keeps /v1/analyze JSON-only and lets the gateway enforce a size limit before the JSON body is parsed. Costs one extra round trip
B. Inline multipart — not chosen	/v1/analyze accepts multipart/form-data directly (§2.4)	One round trip. Couples upload and analysis; a retry re-uploads

The three things the frontend needs — a per-file size limit, a content-type allowlist, and an idempotency story for retries — are specified in the table above. Note that "idempotency story" resolved to "there is none, a retry mints a new handle", which is a decision rather than an omission: with no request key in the contract, a deduplicating server would have to hash payloads, and a content-hash handle is exactly the guessable identifier §2.5 forbids.

---

Response 200

Shape is ResultEnvelope (core/schemas.py:383).

{
  "run_id": "9f2c1c0e-4a5b-4f5e-9a2c-1b3d4e5f6a7b",
  "schema_version": "1.0",
  "result": {
    "task": "change_vqa",
    "answer": "The built-up area increased...",
    "labels": [],
    "regions": [],
    "boxes": [
      {
        "x1": 0.12, "y1": 0.34, "x2": 0.56, "y2": 0.78,
        "label": "expanded built-up area",
        "score": 0.81,
        "coordinate_system": "normalized_0_1"
      }
    ],
    "masks": [],
    "change_map": null,
    "evidence": [
      {
        "evidence_id": "ev_001",
        "type": "change_map",
        "score": 0.72,
        "source_specialist": "change_vqa",
        "coordinate_system": "normalized_0_1",
        "coordinates": [0.12, 0.34, 0.56, 0.78],
        "artifact_ref": null,
        "payload": {}
      }
    ],
    "confidence": {
      "raw": 0.991,
      "calibrated": 0.987,
      "method": "temperature_scaling",
      "components": {},
      "degraded": false,
      "degradation_reason": null
    },
    "geospatial": {},
    "execution_trace": null,
    "schema_version": "1.0",
    "warnings": [],
    "degraded": false
  },
  "trace": {
    "run_id": "9f2c1c0e-4a5b-4f5e-9a2c-1b3d4e5f6a7b",
    "task": "change_vqa",
    "intent": null,
    "query": "How has the built-up area changed?",
    "modalities": ["optical"],
    "workflow": [],
    "steps": [],
    "timings": {},
    "selected_models": [],
    "parameters": {},
    "config_hash": "78f1e3700da15aa1",
    "inputs": [],
    "outputs": [],
    "errors": [],
    "fallbacks": [],
    "contradiction": false,
    "validation": {},
    "confidence": null,
    "started_at": "2026-09-22T04:12:21.000Z",
    "finished_at": "2026-09-22T04:12:29.400Z",
    "schema_version": "1.0"
  }
}

trace above lists every field ExecutionTrace defines. Fields left null or empty here are genuinely optional, not omitted from the contract — the model uses defaults, so they will normally be present in a real response. The frontend should read only the ones it needs and tolerate the rest.

The fields the frontend must read correctly

Field	Why it matters
result.confidence.value	NOT a JSON field. It is a Python @property on ConfidenceBreakdown and is not serialised (verified: model_dump() yields only calibrated, components, degradation_reason, degraded, method, raw). To get the number the user should see, read calibrated if it is non-null, otherwise raw
result.confidence.method	"uncalibrated" or "temperature_scaling". See §4
result.confidence.degraded / degradation_reason	Whether the confidence is trustworthy. Display the reason verbatim when set
result.degraded + result.warnings	The result is served but something was degraded. Warnings are for the operator, not the end user
result.answer	"" for non-VQA tasks. Empty is valid
result.boxes[].coordinate_system	Read this per box. See §3.2
result.boxes[] flat geometry	x1, y1, x2, y2 are flat fields on the box, not a nested box object. Region is the one with a nested box
result.evidence[] shape	Every evidence item carries: evidence_id (unique within a result), type, score, source_specialist, coordinate_system, coordinates, artifact_ref, payload. Note score — not value — and source_specialist — not source. artifact_ref is always null in v1 — see "Artifact refs — null in v1, and why" above
result.evidence[].type	One of 11 EvidenceType values: image_crop, tile, bounding_box, mask, change_map, optical_view, sar_view, joint_feature_region, statistic, geolocation, availability_mask
trace.steps[].state	ControllerState — the pipeline stage. detail and duration_ms accompany it
trace.steps	Observable facts only. Never chain-of-thought (plan section 26). Safe to display
trace.config_hash	The frozen config identity. 78f1e3700da15aa1 for this revision

Artifact refs — null in v1, and why

Every artifact_ref and change_map in a v1 response is null. This is a deliberate contract, not a missing value.

F-16 (owner ruling 2026-09-23): never expose filesystem paths. The specialists do render their artifacts — the change map and the optical/SAR views are written server-side — but their location is an operator fact, not a client-facing one. A response that carried the server's path would disclose the deployment's directory layout to an unauthenticated caller, and nothing the frontend can do requires it.

No artifact:// URI is fabricated in its place. v1 has no artifact-serving endpoint, so a URI would be a promise the service cannot keep — strictly worse than null, because the frontend would build a link that 404s. The earlier revision of this document showed "artifact_ref": "artifact://run/9f2c.../change_map.png"; no production file ever emitted one, which is exactly how the divergence survived. The example above now shows the ruled shape.

What replaces the ref:

Removed	Replaced by
change_map path	null, plus the change statistics in the CHANGE_MAP evidence's payload (total_change_pixels, n_components_kept, threshold)
view artifact_ref path	null, plus payload.rendered / payload.retrievable / payload.retrieval
—	an explicit warnings[] entry saying the artifact is NOT retrievable

The frontend must therefore treat artifact_ref as always null in v1 and read the payload statistics instead. A non-null ref appearing here in future means an artifact-serving endpoint was added, and this section changes with it.

---

3. Enumerations

These are fixed by core/schemas.py. The frontend must treat them as closed sets for display, but must not assume they will never grow — an unknown value should render as its raw string, not crash.

3.1 Task (core/schemas.py:35)

Seven values. Note unsupported is a Task, not an error — it is how "I do not know what you asked" is represented.

Value	Meaning	Assets
vqa	Answer a question about one image	1
caption	Describe the image	1
grounding	Locate a described object	1
change	Detect change between two dates	2
optical_sar	Fuse optical and SAR	2
change_vqa	Answer a question about the change	2
unsupported	The router could not map the request to a specialist	0

3.2 Coordinate systems

CoordinateSystem is an explicit enum on every spatial field. This is a correctness-critical distinction and a documented source of silent bugs.

Value	Meaning	Rendering
normalized_0_1	[0, 1], origin top-left	Multiply by image width/height
pixel	Absolute pixel coordinates	Use directly
geo	CRS coordinates (usually EPSG:4326)	Requires a map, not a 2-D canvas

VRSBench annotations arrive normalised to 0–100, not 0–1; evaluation.metrics.grounding.benchmark_to_normalized performs the conversion. The frontend must read the coordinate_system field on each Box/Region and must not assume one convention. A box drawn with the wrong assumption lands in plausible-looking wrong places.

The raw enum values are the exact strings above. Earlier drafts of this document used shorthand (normalized, geographic); those are wrong and would fail schema validation, since extra="forbid" and the enum is closed.

3.3 Modality (core/schemas.py:50)

Value	Meaning
optical	Optical only
sar	SAR only
optical_sar	Both fused
unknown	Undetermined

---

4. The confidence contract

This is the subtlest part of the API and the easiest to mis-render.

ConfidenceBreakdown (core/schemas.py) has:

Field	Meaning
raw	The uncalibrated score
calibrated	The post-calibration score, or null
method	"uncalibrated" or "temperature_scaling"
components	A string -> float map of the individual signals that fed the confidence. May be empty. Diagnostic only — do not compute a confidence from it
degraded	Whether this confidence should be trusted
degradation_reason	Why, when degraded is true

Rules the frontend MUST follow:

1. Display calibrated when it is not null; otherwise display raw.
2. Display method next to the value. temperature_scaling means a fitted correction was applied; uncalibrated means it was not.
3. Never present a confidence as a percentage without its method. A raw 0.99 and a calibrated 0.99 do not mean the same thing.
4. When degraded is true, show degradation_reason. Confidence that is degraded is not a quality signal.

Measured caveat, recorded honestly. The R-02 calibration fit (artifacts/calibration_v001.json, T = 0.9772731820958189, 16,441 Val rows) found that the raw softmax was already near-calibrated (ECE 0.013755) and that temperature scaling made ECE very slightly worse (0.014929) while improving NLL marginally (0.689741 → 0.689631). The frontend must not imply that temperature_scaling is inherently "more accurate" than uncalibrated.

---

5. Error contract

Every non-2xx response body has this shape:

{
  "error": {
    "code": "pair_misaligned",
    "message": "The images are not sufficiently co-registered for spatial analysis.",
    "detail": "RMSE 4.21 px exceeds the 2.0 px budget",
    "recoverable": false,
    "request_id": "req_01H...",
    "run_id": "9f2c1c0e-..."
  }
}

code is stable and comes from core/errors.py. message is operator-safe (SatQueryError.user_message). detail is technical and may be absent.

5.1 HTTP status mapping

Status	When	recoverable
400	Malformed JSON, missing required field, or a malformed upload body	false
404	The path is not an endpoint at all (routing_error)	false
405	The path exists but not for this method (routing_error). GET /v1/assets is the common case: §2.5 defines it for POST only	false
413	Upload exceeds the per-file size limit	false
415	Upload's content type is absent or not on the allowlist	false
422	Schema violation (unknown field with extra="forbid", wrong enum value, assets empty)	false
429	Rate limited. Honours Retry-After	true
500	Unexpected internal failure	false
503	A required model is absent or unavailable; or GPU quota exhausted; or the asset store is unconfigured or full	depends
504	The specialist exceeded its budget (specialist_timeout)	true

413 and 415 are upload-only (POST /v1/assets). A 415 is the expected answer to an upload with no declared Content-Type — the server refuses rather than guessing (§2.5).

404 and 405 carry this same envelope, which is worth stating because they are the two statuses a proxy framework raises before any handler runs. A client should therefore not special-case them: parse error.code as usual. This was made true on 2026-09-22 (the gateway previously returned the framework's own {"detail": "Not Found"} for both, which broke any client that assumed §5); docs/STEP8_FINAL_CONFORMANCE_AUDIT.md records the finding as F-3.

A trailing slash is a 307, not an error — and this is a real footgun. Starlette's default redirect_slashes behaviour applies: GET /v1/analyze/ answers 307 with Location: http://<gateway-host>/v1/analyze. Two consequences a client must handle, both verified against the running app on 2026-09-22:

• The Location is built from the gateway's own host, not from the client's request URL, so a redirect followed naively after a POST may not land where the caller expects. Do not rely on it.
• A 307 preserves the method and body, so a POST /v1/analyze/ will re-send the body to /v1/analyze — which is fine, but it is a second request against the rate limiter, and /v1/analyze is a COSTLY_ROUTE.

Use exact paths with no trailing slash. This is also why the runbook's SATQUERY_SPACE_URL is normalised with a trailing-slash strip (docs/BACKEND_DEPLOYMENT_RUNBOOK.md §4.1.1).

5.2 The complete code taxonomy

From core/errors.py. The frontend should map these to user-facing copy; the user_message field is a safe default.

code	Meaning	Suggested UX
satquery_error	Base class — the fallback when a more specific code does not apply	Generic failure. Treat an unexpected occurrence as a defect
input_error	The uploaded input could not be read	Ask the user to re-upload
raster_read_error	Not a readable TIFF/GeoTIFF	"This file is not a readable GeoTIFF"
missing_crs	No coordinate reference system	"This image has no georeferencing"
unsupported_bands	Band layout unsupported	Explain expected bands
oversized_image	Exceeds the pixel budget	Offer downsampling
pair_incompatible	The two images do not match	Prompt for a better pair
pair_misaligned	Not co-registered	Explain alignment requirement
temporal_pair_invalid	Two distinct acquisitions required	Ask for a second date
routing_error	Request could not be interpreted	Offer force_task
unsupported_query	No specialist supports this	Show the capability list
invalid_request	Inputs do not support the task	Suggest a valid task
workflow_plan_error	Workflow could not be planned	Retry; report if persistent
specialist_error	A specialist failed	Generic failure
model_load_error	A model could not be loaded	Defect — surface it
model_unavailable	Model not available in this environment	Disable the capability
out_of_memory	OOM; retry at reduced resolution	Suggest a smaller image
specialist_timeout	Processing timed out	Offer retry
schema_validation_error	The system produced a malformed result	Defect — always report
coordinate_error	Invalid spatial coordinates	Defect
confidence_range_error	Confidence out of range	Defect
leakage_violation	A data isolation rule was violated	Defect — never user-facing
benchmark_freeze_error	The benchmark is not frozen	Evaluation-only

Render user_message as the default and override specific codes with better copy. Do not invent a mapping from detail — it is not stable.

5.3 Gateway-origin codes (a separate set from §5.2)

There is exactly one code a client can receive that is not in the table above, and it does not come from core/errors.py:

code	Meaning	Suggested UX
rate_limited	Gateway-origin. The proxy's per-IP rate limit refused the request; it never reached the Space. 429, and Retry-After is set	Wait Retry-After seconds, then retry. Not a bug — see §7

Why it is a separate set rather than a §5.2 row: tests/unit/test_gateway_responsibilities.py asserts that §5.2 and core/errors.py are in exact one-to-one correspondence (23 codes), and tests/unit/test_gateway_policy.py asserts that a gateway-origin code may never shadow a taxonomy code. Both hold only if the two sets stay disjoint — so rate_limited is documented here, beside the taxonomy rather than inside it, and the correspondence test keeps its meaning.

The gateway mints this code and only for errors that originate in the gateway; a code arriving from the Space is never replaced. rate_limited is declared in gateway/policy.py (GATEWAY_ORIGIN_CODES) because §5.1 maps HTTP 429 to "Rate limited" while the core/errors.py taxonomy — which covers the analysis pipeline, not the proxy — assigns that status no code. Recorded here on 2026-09-22, after a check of this document found the code reachable by every throttled caller yet absent from every client-facing table. docs/PHASE19_FINAL_HARDENING.md is the implementation record; this is the client-facing one.

---

6. Latency, quotas and the realities of this deployment

Constraint	Value	Source
ZeroGPU free tier	5 GPU-minutes/day	plan section 48; configs/deploy.yaml
Declared GPU durations	vqa 20 s · grounding 45 s · change 30 s · optical_sar 45 s	configs/deploy.yaml
Resident models	1 (cache_max_models: 1)	configs/deploy.yaml
torch.compile	Disabled — ZeroGPU does not support it (finding C-8)	configs/deploy.yaml
Lazy loading	Enabled — first request for a capability pays a cold start	configs/deploy.yaml
Server budget	agent.timeout_seconds	configs/base.yaml

Frontend obligations:

1. Show a progress state. A cold start can take tens of seconds. There is no streaming API in v1; the client sends one request and waits.
2. Do not poll /v1/health aggressively. Every /v1/analyze costs GPU quota; health checks cost CPU. Polling health in a loop is fine; retrying analyze in a loop is not.
3. Serialize requests. With cache_max_models: 1, two concurrent analyses for different tasks will evict each other and make both slower. If the UI allows a queue, process it one at a time.
4. Handle 429 and 503 as normal states, not as bugs. Quota exhaustion is an expected condition on the free tier.

---

7. Authentication

There is no authentication in v1. This is a recorded boundary, not an oversight.

Plan section 74 (Production Readiness Boundary) explicitly excludes auth, multi-tenancy, distributed queues and autoscaling from scope. Consequently:

• The API must not be exposed on the open internet without a gateway-imposed control. The intended control is the Railway gateway (§docs/DEPLOYMENT_ARCHITECTURE.md).
• Any credentials (HF token, gateway allowlist) live server-side only and are never sent to the browser.
• The frontend must not embed an HF token, an API key, or any secret. It talks only to the gateway.

Do not build a login screen. There is no auth to log into.

7.1 CORS

The gateway sets CORS explicitly to the deployed frontend origin. It does not use a wildcard. A preflight OPTIONS is answered by the gateway, not by the HF Space.

---

8. Status of this contract

Element	Status
Endpoint surface (/v1/health, /v1/capabilities, /v1/analyze, /v1/assets)	Fixed — 3 by the plan, the 4th by the owner ruling of 2026-09-22 (§2.5)
Request/response shapes	Existing and tested — core/schemas.py
Error taxonomy and code values	Existing and tested — core/errors.py
Error envelope ({"error": {...}})	Specified here. The gateway must produce it; the Space's own errors are translated by the gateway
POST /v1/assets	Implemented, Option A, §2.5. Upload against it
Multipart upload into /v1/analyze	Not implemented, and not chosen — Option B was rejected, §2.5.1
How the contract is verified	docs/ITEM5_INTEGRATION_SUITE_SCOPE.md records what the 26-test integration suite proves (the app's boundary, in-process) and what only a live deployment can prove (reachability, cold start, memory ceilings). Read it before treating a green tests/integration run as evidence about a deployment — no test in this repository dials a network address, including this contract's own /v1/* examples
Authentication	Deliberately absent (plan section 74)
Streaming / progress	Not in v1
Rate-limit values	Not specified by the plan. The gateway must choose them; ask the maintainer
Asset TTL, size cap and content-type allowlist values	Deployment configuration, not contract constants. The shape of each guarantee is fixed (§2.5); the value is read from the environment per deployment

Nothing in the "Status" column above may be treated as settled if it says "Not in v1", "Not implemented" or "Not specified by the plan" — unless the row also names a decision that closed it. Those are gaps this document surfaces rather than fills.

---

9. Minimal frontend integration checklist

1. GET /v1/health on load → show service state, including degraded.
2. GET /v1/capabilities → build affordances from the response. Disable unavailable tasks with their reason shown.
3. For each analysis: (a) POST /v1/assets per image → collect asset_id values; (b) POST /v1/analyze with assets, query, optional force_task.
4. Render result.answer, then confidence per §4, then result.warnings and confidence.degradation_reason if present.
5. Draw boxes/regions using each item's own coordinate_system.
6. Map errors per §5. Default to user_message; special-case the codes flagged as defects so they are reported rather than swallowed.
7. Serialize analyses. Do not retry 429/503 in a tight loop.
8. Never embed a secret. Never build a login screen.