Glossary

Ringside reuses a small vocabulary across auth, billing, retrieval and the OpenAI-compatible shim. A few of these words look familiar from other APIs but mean something specific here. A customer is a billing subject, not a person with a login. A run executes an assistant on a thread; it is not an HTTP request. Read an entry, then follow the link for the mechanics.

A

API key

Your developer credential, literally ko_ followed by 64 hex chars, sent as Authorization: Bearer ko_<key> and SHA-256 hashed at rest; there is no test-vs-live split, create and revoke keys in the dashboard at /app/api-keys. See Authentication.

Assistant

A reusable, OpenAI-compatible config (id asst_) holding a model, instructions, tools and tool_resources but no conversation state, with name unique per developer (409 assistant_name_in_use on collision). See Assistants, threads and runs.

B

Batch

An asynchronous bulk job (id batch_) over a JSONL input_file_id, run against /v1/chat/completions, /v1/embeddings or /v1/moderations with completion_window:"24h", capped at 50,000 requests and billed at half the synchronous per-call price. See Batch processing.

Billable amount

The amount actually metered for a call, which defaults to raw provider cost but can be overridden per request with the X-FC-Billable-Amount header (micro-dollars) or per customer via billable defaults, so you can resell at your own price. See Metering and billing.

Brain

A managed long-term memory store (id brn_) with a fixed embedding model, a memory_policy and scope-isolated entries; recall injects relevant memory into a completion and a learn pass files durable facts back. See Brains and RAG.

Budget

A customer's monthly_budget_usd ceiling; once spend crosses it the next attributed call returns 402 customer_budget_exceeded until the calendar month rolls. See The customer and spend model.

C

Client token

A short-lived browser credential (jti prefix ctok_) minted server-side via POST /v1/customers/{id}/client_tokens and sent as Authorization: Client <jwt> using the Client scheme, not Bearer; ttl defaults to 900s (min 60, max 3600) and rpm defaults to 60 (max 600, also clamped to the customer rpm). See Authentication.

Customer

A first-class billing subject (id cus_) representing one of your end-users, carrying budget, rate limits, a prepaid wallet and markup defaults; attribute a call to one with the FC-Customer header. See The customer and spend model.

Customer wallet

A customer's prepaid balance topped up via /wallet/topup and corrected via /wallet/adjust; when a call is attributed to that customer the charge comes from here, and an empty wallet returns 402 customer_wallet_empty. See Metering and billing.

Conversation

A persisted message container (id conv_) with a message cap of 5,000 and a metadata budget of 2 KB; an active turn holds a lock for up to 10 minutes. See Limits and quotas.

D

Decay anchor

The timestamp a Brain memory's recency is measured from — created, updated or last_used. last_used gives spaced repetition (a fact you keep using stays fresh); created keeps short-lived facts expiring on their own clock. Set brain-wide via memory_policy.decay_anchor or per type via type_taxonomy[].anchor. See Add agent memory.

Developer wallet

Your own prepaid balance, debited by every call that is not attributed to a customer wallet; an empty developer wallet returns 402 wallet_empty, and the running balance plus the exact charge come back in the X-Ringside-Wallet-Balance and X-Ringside-Wallet-Deducted response headers. See Metering and billing.

dyn: ref

A model reference of the form dyn:<name> that resolves through a dynamic profile at request time, with the resolution surfaced in the X-Ringside-Dynamic-Profile and X-Ringside-Dynamic-Reason response headers. See Model references and resolution.

E

Embedding

A vector produced by /v1/embeddings from text, used to index documents in a vector store; the input array accepts up to 2,048 items of up to 100,000 chars each. See Retrieval-augmented generation.

Entry

One item stored in a Brain (a reference doc, a memory fact, or a policy), filed at a scope with a type and trust level. Reference entries are chunked and embedded; memory entries carry use_count/last_used that drive recall ranking. See Brains API.

F

fc: ref

A pinned model reference of the form fc:<provider>/<model> (for example fc:openai/gpt-4o-mini) that always routes to that exact model, and the only ref form that accepts a region suffix. See Model references and resolution.

File

An uploaded object (id file_) up to 512 MB, with a purpose (for example batch) that determines how it is used; download content via /v1/files/{id}/content. See Limits and quotas.

file_search

The OpenAI-compatible retrieval tool you attach to an assistant run via tool_resources.file_search.vector_store_ids; it returns chunk citations, plus a facts[] array of subject/predicate/object triples when the store has GraphRAG enabled. See Retrieval-augmented generation.

Fallback cascade

A model array (cheap-to-expensive) on a chat call where Ringside tries each ref in order until one succeeds, surfacing the result in the X-Ringside-Model-Used, X-Ringside-Models-Tried and X-Ringside-Fallback-Triggered response headers; a cascade cannot be combined with stream:true (400 fallback_with_stream_unsupported), a response_format json_schema or an idempotency key. See Idempotency and reliability.

G

GraphRAG

A retrieval mode you opt into per store with graphrag_enabled:true, which builds a knowledge graph alongside the vector index so file_search returns relationship triples next to citations; it bills as a per-GB-day line with the first 1 GB-day per store per day free. See GraphRAG.

I

Idempotency key

A client-chosen value sent in the exact-cased idempotency-key header that makes a retried call return the original result within a 24 h replay window, scoped to (developer, customer, key); it cannot be combined with a model:[] fallback cascade (400 fallback_with_idempotency_unsupported). See Idempotency and reliability.

M

Margin

The difference between the billable amount and the raw provider cost on a call, accumulated per customer and read back via GET /v1/customers/{id}/margin. See Metering and billing.

Markup

A percentage uplift on raw cost set per customer as default_billable_markup_pct, mutually exclusive with the flat default_billable_amount_usd (set both and you get billable_defaults_mutex). See The customer and spend model.

Metering

The act of pricing each call and deducting it from the right wallet, with the deducted amount and remaining balance returned in X-Ringside-Wallet-Deducted and X-Ringside-Wallet-Balance. See Metering and billing.

Moderation

Content screening, either the free standalone POST /v1/moderations endpoint (meters at $0) or inline on a chat call via the moderation body param (none, pre, post or pre_and_post, default none). See Webhooks and events.

Mount

A brain reading one Pack version as a read-only base layer (id mnt_), in reference mode (live cross-store read, no copy) or materialize mode (a re-sealed copy imported into the brain), remapped through a scope_map. Writes only ever land in the brain's own native layer. See Brain Packs API.

P

Pack (Brain Pack)

An immutable, versioned snapshot minted from a brain (id pack_): its entries, chunks, vectors, graph and frozen policy and tier weights. The unit of sharing a base of knowledge across many brains, one Pack per source brain in v1, published with POST /v1/brains/{id}/publish. See Brain Packs API.

parent_brain_id (superseded)

Not a real field. The earlier "sub-brains" or brain-inheritance proposal (a brain inheriting from a parent_brain_id) was superseded by Brain Packs: a brain mounts an immutable published Pack rather than inheriting from a parent. See Brain Packs and mounts.

Prompt caching

Reuse of a stable prefix on Anthropic-routed models, turned on with cache_control {type:ephemeral, ttl 5m|1h} on a message or prompt_cache:"auto", where cached reads bill about 10% of input price after a one-time write at about 1.25x and the minimum cacheable prefix is around 4,000 tokens. See Prompt caching.

R

RAG

Retrieval-augmented generation: grounding a model in your own documents by embedding them into a vector store and querying that store with file_search at answer time. See Retrieval-augmented generation.

Rate limit (RPM/TPM)

A ceiling on requests per minute and tokens per minute enforced across four layers (edge per-IP, per-client-token, per-developer, per-customer) where the lowest applicable limit wins; X-RateLimit-Remaining reports headroom and a 429 carries Retry-After in integer seconds. See Rate limiting and quotas.

Recall

A read-only Brains query (POST /v1/brains/{id}/recall) that scores entries at a scope and its ancestors and returns the top matches; ranking is per-query and ephemeral, so recall never mutates use_count or last_used (only the learn pass does). Pass explain:true to see each hit's scoring factors. See Brains API.

Region suffix

A data-residency tag @<region> appended to an fc: ref only, choosing where inference runs (@eu/@us for OpenAI in-region, @eu-bedrock/@us-bedrock for Claude on AWS Bedrock, @eu-vertex/@us-vertex for Claude on Google Vertex); an unsupported suffix returns 400. See Regions and data residency.

Request id

The per-request trace id (prefix req_) returned in the X-Request-Id response header and never in the body, the one value to quote in support tickets and to log on every call. See Observability.

Run

One execution of an assistant on a thread (id run_), progressing through queued, in_progress, requires_action, cancelling, cancelled, completed, failed or expired, with only one active run per thread (409 thread_locked otherwise). See Assistants, threads and runs.

S

Scope

A path like /acme/support that isolates Brain entries: recall at a scope sees that scope and its ancestors, never its siblings, so per-tenant knowledge filed under sibling scopes stays separate. Learning writes to the pinned scope. Opt into reading a whole subtree with the Brain-Subtree header. See Brains and RAG.

Sealed store (managed)

A vector store created with encryption:"managed" so chunks and vectors are encrypted at rest under a Ringside-held key, with vector_sealing defaulting to full. See Sealed RAG and encryption.

Sealed store (BYOK)

A vector store created with encryption:"byok" whose key is a passphrase you supply (key {type:passphrase, passphrase}, min 12 chars) that is never persisted; you take a lease via POST .../unlock or pass the FC-Vector-Store-Key header per call, and the store idle-locks when neither is present. See Sealed RAG and encryption.

slot: ref

A model reference of the form slot:<alias> that resolves through a developer-defined alias, letting you swap the underlying model without touching calling code. See Model references and resolution.

T

Thread

A message container (id thread_) capped at 5,000 messages that a run executes against; set metadata.customer_id or metadata.customer_external_id on it to attribute the run's spend. See Assistants, threads and runs.

Tier

A Brain memory type's decay class: A/B (evergreen — age by supersession, not the clock), C (spaced repetition — fades unless reused, tuned by last_used), and D (short half-life, "right now" status meant to go stale). A type's tier sets its default decay curve; type_taxonomy overrides it per type. See Brains and RAG.

match: ref

A model reference of the form match:<provider>/<family> (for example match:anthropic/sonnet>=4) that resolves to the best-fitting current model in that family at request time. See Model references and resolution.

V

Vector store

A per-customer-isolated index (id vs_) holding embedded document chunks, created with a fixed embedding_model (changed only via POST .../migrate) and queried with file_search; cross-tenant access returns 404, not 403. See Retrieval-augmented generation.

Vector sealing

The vector_sealing mode on a sealed store (none, source or full) controlling how much of the index is encrypted, defaulting to full when the store is sealed and ignored when encryption:"none"; the ivf index requires a sealed store. See Sealed RAG and encryption.

W

Webhook

An HTTPS endpoint (id wh_) you register at POST /v1/webhooks to receive a non-empty subset of the event taxonomy (for example customer.budget_exceeded, wallet.low, chat.completion.finished); its signing secret (whsec_) is shown once on create and once on rotate_secret, and a sustained failure streak auto-disables it (disabled_after_failures). See Webhooks and events.

X

X-FC-Signature

The webhook delivery signature header carrying t=<unix>,v1=<hex> where v1 is the HMAC-SHA256 of the raw body keyed by the endpoint secret; verify it constant-time, reject stale timestamps and during a rotation grace accept either of the two v1= digests present. See Receive and verify webhooks.

Identifier prefixes at a glance

Every object id is prefixed so you can tell types apart in logs without context. These prefixes are stable.

curl https://api.fightclub.pro/v1/chat/completions \
  -H "Authorization: Bearer ko_<key>" \
  -H "FC-Customer: cus_42" \
  -H "X-FC-Billable-Amount: 4200" \
  -H "idempotency-key: invoice-2026-06-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fc:openai/gpt-4o-mini@eu",
    "messages": [{"role":"user","content":"Summarize this ticket."}]
  }'

# Response headers you will see:
#   X-Request-Id: req_...
#   X-Ringside-Model-Resolved: openai/gpt-4o-mini
#   X-Ringside-Wallet-Deducted: 0.0042
#   X-Ringside-Wallet-Balance: 88.6310
#   X-RateLimit-Remaining: 59

That single request touches the API key, a customer (cus_42), a billable amount override, an idempotency key, an fc: ref with a region suffix, the request id header and the metering headers. Each is defined above. If cus_42 were over its budget you would get 402 customer_budget_exceeded instead, and the metering headers would be absent.