Gateway completions

POST /v1/gateway/completions proxies a chat completion to an upstream provider and bills your org for provider cost × (1 + markup). Requires scope gateway:write.

This is not an OpenAI-compatible endpoint. The envelope is Almanac's own:

• Fields are camelCase: maxTokens, topP (not max_tokens, top_p). Unknown fields — including snake_case ones — are rejected with 400.
• The response contains a single output string, not a choices[] array.
• Billing metadata (costMicro, markupBps, balanceAfterMicro) is part of every response.
• Streaming is not currently exposed.

Request

{
	"provider": "openrouter",
	"model": "anthropic/claude-3.5-sonnet",
	"messages": [
		{ "role": "system", "content": "You are a forecasting assistant." },
		{ "role": "user", "content": "Assess the probability of X by Friday." }
	],
	"maxTokens": 1024,
	"temperature": 0.7,
	"topP": 0.9,
	"stop": ["\n\n"]
}

Response

{
	"provider": "openrouter",
	"model": "anthropic/claude-3.5-sonnet",
	"output": "…completion text…",
	"usage": {
		"promptTokens": 412,
		"completionTokens": 187,
		"totalTokens": 599
	},
	"costMicro": "12500",
	"providerCostMicro": "10000",
	"markupBps": 2500,
	"balanceAfterMicro": "987500"
}

usage token counts of -1 mean the provider didn't report that figure. When a provider reports cache-aware usage, cacheReadInputTokens / cacheCreationInputTokens appear too. Micro-credit amounts are strings — see Credits & billing.

Every successful response also sets X-Sub41-Credits-Remaining to your post-debit balance.

Idempotency

Send an optional Idempotency-Key header (1–255 chars, scoped to your org) to make retries safe:

• A repeat request whose key already produced a successful completion is rejected with 409 — no provider call, no debit.
• Failed calls don't consume the key, so you can retry the same key after an error.

Use one key per logical request (e.g. a UUID per task), not per attempt.

Miner attribution

If your org runs miners, gateway usage can be attributed to one. Resolution order:

1. minerHotkey in the request payload (must be an active miner registered to your org, else 400)
2. The API key's pinned miner (set when issuing the key)
3. The org's default miner
4. None

Failure modes

The important ones (full table in Errors): 402 insufficient credits (checked before the provider call), 404 unknown provider/model, 429 upstream rate limit, 502/504 upstream failure/timeout — none of which bill you, and none of which consume an idempotency key.