API contract details
Use the base URL https://api.redgold.ai and authenticate as described in the authentication guide. The V1 route inventory is generated independently from deployed route manifests.
POST /v1/chat/completions
Request: An OpenAI-compatible chat-completions object. model and messages are required; stream selects complete JSON or SSE delivery.
Response: An OpenAI-compatible chat-completion envelope when stream is false, or chat-completion chunks when it is true.
Streaming: Set stream to true for server-sent events. Consume each data: event until the terminal marker. A failure after headers can arrive in-band.
Errors: Uses the OpenAI-compatible error envelope. Common statuses are 400, 401, 402, 429, 502, and 529; see the errors page.
Limits: Model context, output, account-credit, and request-rate limits apply. Use bounded backoff for retryable statuses.
Compatibility: Designed for standard OpenAI SDK clients. Redgold model identifiers, availability, metering, and some provider-specific optional fields differ.
Example request
{
"model": "redgold-flint",
"messages": [
{
"role": "user",
"content": "Hello"
}
],
"stream": false
}
Example response
{
"id": "response-id",
"object": "chat.completion",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Hello"
},
"finish_reason": "stop"
}
]
}
GET /v1/credits
Request: No request body. Send the API key as a bearer token.
Response: The available account balance in integer micro-units and decimal US dollars.
Streaming: This endpoint is unary and does not stream.
Errors: Returns the standard OpenAI-compatible error envelope. Authentication failures use 401.
Limits: Normal account and key request limits apply.
Compatibility: This is a Redgold account endpoint and has no upstream OpenAI or Anthropic equivalent.
Example response
{
"balance_micros": 1000000,
"balance_usd": 1
}
POST /v1/decisions
Request: Send a platform sk-rg API key as a bearer token and JSON with arbitrary state plus 1–64 named questions. Questions use type: choice with instructions and named, described criteria, or type: noul with instructions. Optional task normalizes state to {task, context: original_state}. Optional model must be typesafe/jev-1.13.
Response: The Jev provider JSON, including named answers and usage with input_tokens, output_tokens and USD cost. Choice answers contain a supplied candidate id, confidence and candidate probabilities; noul answers contain a probability. The engine validates answers and usage before returning success.
Streaming: Unary JSON only. stream: true is rejected.
Errors: Malformed requests return 400; missing platform identity returns 401. Gateway authentication, spend and rate-limit errors retain their HTTP status. Invalid or oversized successful upstream responses return 502; gateway configuration or connection failures return 503.
Limits: Requests are limited to 24 KB and responses to 64 KB. Each choice accepts 1–64 criteria. Gateway account, key and spend limits apply, with a bounded provider deadline. The engine and rac client do not retry automatically.
Compatibility: Jev choice/noul decision JSON with an optional task shorthand. State-only requests retain their original state. This route always forwards through the authenticated gateway, including when other LLM routes use direct upstream or BYOK settings. Decisions do not execute tasks.
Example request
{
"task": "Identify the failed job",
"state": {
"jobs": [
{
"id": "test",
"status": "failed"
}
]
},
"questions": {
"next": {
"type": "choice",
"instructions": "Choose the job requiring attention from state.context.jobs.",
"criteria": {
"test": "Test job",
"none": "No job requires attention"
}
},
"failed": {
"type": "noul",
"instructions": "Does the evidence show a failed job?"
}
}
}
Example response
{
"answers": {
"next": {
"type": "choice",
"choice": "test",
"confidence": 0.99,
"probabilities": {
"test": 0.99,
"none": 0.01
}
},
"failed": {
"type": "noul",
"noul": 0.99
}
},
"usage": {
"input_tokens": 30,
"output_tokens": 10,
"cost": 0.00001
}
}
POST /v1/messages
Request: An Anthropic-compatible Messages object. model, max_tokens, and messages are required; stream selects complete JSON or SSE delivery.
Response: An Anthropic-compatible message object when stream is false, or Messages API events when it is true.
Streaming: Set stream to true for server-sent Messages events. Clients must handle an in-band error after the stream begins.
Errors: Uses the Anthropic-compatible error envelope. Common statuses are 400, 401, 402, 429, 502, and 529; see the errors page.
Limits: Model context, max_tokens, account-credit, and request-rate limits apply. Use bounded backoff for retryable statuses.
Compatibility: Designed for Anthropic SDK clients when the API key is supplied as an Authorization bearer token. Model availability and metering are Redgold-specific.
Example request
{
"model": "model-id-from-v1-models",
"max_tokens": 256,
"messages": [
{
"role": "user",
"content": "Hello"
}
],
"stream": false
}
Example response
{
"id": "message-id",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Hello"
}
],
"stop_reason": "end_turn"
}
GET /v1/models
Request: No request body. Send the API key as a bearer token.
Response: An OpenAI-compatible model-list envelope. Use an id returned for the authenticated account rather than assuming every model is available.
Streaming: This endpoint is unary and does not stream.
Errors: Returns the standard OpenAI-compatible error envelope. Authentication failures use 401.
Limits: Account and key request limits apply; cache briefly when selecting models for repeated calls.
Compatibility: The list envelope follows the OpenAI model-list shape. Availability and model metadata are Redgold-specific.
Example response
{
"object": "list",
"data": [
{
"id": "model-id",
"object": "model",
"owned_by": "redgold"
}
]
}
GET /v1/models/{model}
Request: No request body. Send the API key as a bearer token and the model id as the path segment.
Response: A single OpenAI-compatible model object for the requested id, scoped to the authenticated account.
Streaming: This endpoint is unary and does not stream.
Errors: Returns the standard OpenAI-compatible error envelope. Authentication failures use 401; an id not available to the account returns 404.
Limits: Account and key request limits apply; prefer the list endpoint plus brief caching over per-id polling.
Compatibility: The object follows the OpenAI model shape. Availability and model metadata are Redgold-specific.
Example response
{
"id": "model-id",
"object": "model",
"owned_by": "redgold"
}
POST /v1/responses
Request: An OpenAI-compatible Responses object. model and input are required; stream selects complete JSON or SSE delivery.
Response: An OpenAI-compatible response object when stream is false, or Responses API events when it is true.
Streaming: Set stream to true for server-sent response events. A failure after headers can arrive in-band.
Errors: Uses the OpenAI-compatible error envelope. Common statuses are 400, 401, 402, 429, 502, and 529; see the errors page.
Limits: Model context, output, account-credit, and request-rate limits apply. Use bounded backoff for retryable statuses.
Compatibility: Supports the core Responses request/response flow. Optional tools and provider-specific fields depend on the selected model and may differ from OpenAI.
Example request
{
"model": "redgold-flint",
"input": "Hello",
"stream": false
}
Example response
{
"id": "response-id",
"object": "response",
"status": "completed",
"output": [
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "Hello"
}
]
}
]
}