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/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"
        }
      ]
    }
  ]
}