REFERENCE

API reference

The normal decision flow is question-first: provide state plus the typed JEV question once. Geltre uses that same question contract to select evidence, then JEV answers it from the reduced state.

POST /v1/decide

Field	Type	Meaning
state	EvidenceUnit[]	Supplied evidence with stable refs.
questions	object	Typed JEV questions. Supported types: `noul`, `choice`, and `score`.
budget	integer	Advanced Geltre evidence budget. ServiceOps default is application-controlled; CodeOps alpha is locked to 5.
profile	string	`serviceops` or explicit `codeops` alpha.

{
  "state":[
    {"ref":"policy:1","source":"policy","text":"restart policy is on-failure"},
    {"ref":"status:1","source":"status","text":"target service failed after the latest start attempt"}
  ],
  "questions":{
    "should_restart":{
      "type":"noul",
      "instructions":"Should the target service be restarted after this failure?",
      "criteria":{"true":"Restart is appropriate.","false":"Do not restart."}
    }
  },
  "budget":2,
  "profile":"serviceops"
}

There is no separate Geltre task in the paired flow. The server derives Geltre's selector objective from questions, preserves those questions unchanged, selects exact evidence, then sends reduced state + the same questions to ~typesafe/jev-latest through OpenRouter.

Pipeline response

The response contains geltre selection/metering data, jev typed answers and downstream usage/cost, plus decision_request showing exactly what reduced state and questions were sent to JEV.

GET /v1/decision/status

Reports whether the hosted Geltre + JEV lane is enabled and which OpenRouter model alias is configured.

POST /v1/orient Geltre only

The low-level selector endpoint remains available for applications that want Geltre without JEV. It accepts task, state, budget, target="decision", and profile. In the console's Geltre-only mode, the selector task is derived from the typed question so users still define the objective only once.

EvidenceUnit

{"ref":"context:2","source":"context","text":"target service failed after the latest start attempt"}

Selection invariants

Every returned ref exists in the submitted state.
Returned evidence respects the validated profile contract.
Equal inputs under deterministic model versions produce equal selection output.
Duplicate input refs are rejected.

Authentication and API keys

Sign in at console.nicholsai.com with email/password, email code, or Google OAuth. The console exchanges the Supabase account session for a customer-scoped console session. Legacy one-time invite access remains available for controlled preview/promo accounts.

Signed-in developers create separate named machine credentials for applications. Production keys use the gt_live_... prefix. The full secret is shown once; Nichols AI stores only its keyed hash plus non-secret metadata such as name, creation time, last-used time, mode, and revocation time.

GET /v1/account/api-keys

Uses the signed-in Supabase account session and returns machine-key metadata only. Full API-key secrets are never returned.

POST /v1/account/api-keys

{"name":"Production"}

Creates a named live machine key and returns the complete key once.

POST /v1/account/api-keys/revoke

{"key_id":"key_..."}

Revokes one machine key owned by the signed-in customer. Existing clients using that key stop authenticating.

GET /v1/account/activity

Returns the current prepaid balance, machine-key metadata, recent metered usage receipts, and recent credit-ledger events for the signed-in account.

GET /v1/balance

Returns the prepaid balance when authenticated with a Geltre API key.

Billing

Billable input is metered by Geltre and deducted atomically from the internal prepaid ledger only after a valid selection request. Malformed requests are validated before charging and insufficient balance fails closed.

GET /v1/billing/status

Returns the active unit price, approved prepaid packs, and Stripe checkout readiness. The current hosted preview reports checkout enabled at $0.05 per 1 million billable input tokens with $10, $25, and $100 refill packs. A dedicated restricted live Stripe key and endpoint-specific signed webhook back the money-in path.

POST /v1/billing/checkout

Requires a Geltre API key and one approved credit_cents value. The returned Stripe-hosted Checkout URL is tied to the authenticated Geltre customer. Credits are added only after the signed checkout.session.completed webhook confirms payment.

Account and money flow

Supabase account
  → Geltre customer
  → named gt_live_... machine key(s)
  → Stripe prepaid credits
  → /v1/decide or /v1/orient requests
  → per-key usage receipts
  → shared customer balance

One customer can have multiple independently revocable machine keys. All keys draw from the same prepaid customer balance, while each metered request records the specific key that generated the usage. Stripe is the money-in processor; Geltre's internal ledger remains the balance and usage source of truth.

Geltre + JEV →