API reference

Overview

• Base URL. Given with your invitation. Routes are written relative to it. By design the service answers only direct calls from allowed private networks; see access.
• Format. Request and response bodies are JSON (Content-Type: application/json). Responses carry Cache-Control: no-store.
• Versions. The route prefix is v1. Every record carries engine_version (today ge-decisions/1.1.0), so you can tell which scorer produced it.
• Schema. The service has its own OpenAPI document, kept out of any public schema. Invited callers can ask for it.

Authentication

Every call carries a gst1 service token as a bearer credential. It proves which service is calling, which tenant it acts for and that the proof is still fresh.

Authorization: Bearer gst1.<base64url claims>.<base64url signature>

The token is gst1., then the base64url-encoded JSON claims, then a base64url HMAC-SHA256 signature over "gst1." + claims. You do not build tokens yourself: a GodEngine operator issues them, and there is no self-serve token endpoint.

• Lifetime. 24 hours by default and 7 days at most, with 60 seconds of clock skew allowed. Fetch a fresh token well before expiry rather than holding a long-lived one.
• Revocation. One token can be revoked by its jti before it expires; rotating the signing secret revokes every token at once. A revoked token is a 401.
• Checks. The signature is compared in constant time, then every claim is checked against the formats above. A well-signed token with a malformed claim is still a 401.
• Order. The token is checked before the body is read, so an unauthenticated caller learns nothing about the schema.

Tenants

A tenant id is an organisation id where one exists, otherwise u: followed by a user id. Allowed characters are A-Z a-z 0-9 : _ . @ -, up to 128.

A malformed tenant id is 422. Reads always filter on the id and the tenant: an unknown id and another tenant's id get the same 404.

POST /v1/decisions

Makes a decision and stores it, or returns the stored record when the idempotency key was used before with the same inputs.

Request body

From evidence text the engine reads budgets (“budget”, “can spend”, “at most” or “approved” near an amount), deadlines (“within 3 months”) and quotes that name exactly one option. A quote fills a cost the option is missing, and the record notes it. When evidence gives conflicting budgets, the tightest one is used. At most 20 amounts and 20 deadlines are read from any one text, and the record says when a text had more. Evidence is free-form: a value that cannot be read is left out of the model and named in the assumptions.

Responses

• 201 Created, header Idempotent-Replay: false: a new DecisionRecord.
• 200 OK, header Idempotent-Replay: true: the stored record for a reused key with the same inputs.
• 409 Conflict: the key was used with different inputs. See idempotency.
• Errors: see status codes. The body shape is described on the DecisionRecord page.

Constraints

These are the only keys. Any other key, a typo such as budgte included, is 422 at ["body", "constraints", "<key>"].

A malformed weights or exclude_options is 422 too: a non-object, an unknown dimension, a negative, non-numeric, boolean or non-finite weight, all weights zero, a non-list, or an id that names no option.

Option params

The model reads these params, under any of the listed names. Any other param is reported in modelled_constraints.options.<id>.ignored_params and in the assumptions; it is never dropped silently. A known param whose value cannot be read is 422.

A dimension that no option gives is left out of the score. A dimension some options give and others do not is filled with a neutral 0.5 for the others, counted in coverage.defaulted_cells.

Amounts

Amounts are read the way people write them. Lakh and crore imply INR. Nothing is converted between currencies: an option priced in another currency is not compared with the budget, and the record says so.

In free text, a number counts as money only when it carries a currency or a magnitude word, so “over the next 2 years” is read as a horizon. In evidence, a spaced L, m or b needs a currency marker to count as a magnitude, because {"value": 500, "unit": "L"} from a tank gauge is litres.

Money fields are strict

constraints.budget and an option's money params (cost, monthly_cost, annual_cost, expected_value and their other names) must be exactly one amount: a JSON number, a string like those above, or {"value": 10, "unit": "lakh"}. A spaced single letter counts there ("10 L" is ₹10 lakh). Anything else is 422 with the field's location in detail[0].loc, and nothing is computed or stored.

The same rule holds for the other known fields: horizon, deadline, max_risk, risk_tolerance, budget_basis, currency, an option's time and its level params such as risk and upside.

GET /v1/decisions/{id}

• id: the record's UUID, as returned by the POST.
• Authorization: a token with decisions:read.
• X-Tenant-Id: required with a broker token; with a concrete token it may be left out.

200 returns the record as it was issued. 404 means the record is not found for this tenant; the answer is the same whether the id does not exist or belongs to someone else.

Idempotency

The key travels in the body as idempotency_key. There is no Idempotency-Key header. A key is scoped to the calling service within a tenant: (tenant_id, svc, idempotency_key). Two services in one tenant that both pick order-1 stay independent; neither replays the other's record or gets a 409 because of it. Records are still tenant data, so either service can GET the other's record by id.

“Same inputs” means the same inputs_digest: a SHA-256 over the canonical question (whitespace collapsed), evidence, options, constraints and task_id when given. The check happens before anything is computed. If two retries race, a unique index settles it and the loser is answered from the winning record. Replays count towards the rate limit.

Validation and limits

The ceilings keep every derived number, such as total spend over the horizon or budget use, finite. As a last check, the store refuses any record that is not strict JSON, so nothing non-finite is ever stored and the idempotency key stays free for a corrected request. Reading a request costs time linear in its size; a worst-case body at the evidence cap is answered in tens of milliseconds.

Rate limits

Writes are limited per tenant and calling service. The default limits are 120 a minute and 3,000 an hour; a deployment can set others. Replays count.

• Over the limit: 429 with Retry-After in seconds. Retry with the same idempotency key.
• When the rate limiter is required and unavailable: 503 with Retry-After: 5.

Status codes

Error bodies

Errors use a detail field. Validation errors are a list with a loc path to the field; messages never echo the value you sent.

{
  "detail": [
    {"type": "value_error", "loc": ["body", "options", 0, "params", "cost"], "msg": "…"}
  ]
}

{
  "detail": [
    {"type": "json_invalid", "loc": ["body"],
     "msg": "Body must be JSON with finite numbers only, and integers no larger than 10^15"}
  ]
}