Transport for the xAI API: the bearer Authorization header, the base URLs, and the credential resolvers.

Per-call credentials. Every typed function takes a trailing opts: Map, which wins over ctx for that call. Nothing is kept in ctx, so one run can serve many tenants and parallel flows don't share keys.

  • api-key: overrides xai.api.key.
  • base-url: overrides xai.base.url.
  • management-api-key: overrides xai.management.api.key, used by the ::xai::collections management calls.
  • management-base-url: overrides xai.management.base.url.

A base URL in opts needs its matching key in opts too: a ctx key is never sent to a per-call URL. A base URL and key both set in ctx work as usual.

Call records. A key passed in opts is masked in the run's call records, including inside strings like Bearer ${key}. A key shorter than 8 bytes is masked only as a whole value.

Functions

base-url

fn (): Str
fn (opts: Map): Str

The base URL main API calls go to: opts.base-url, then the xai.base.url ctx variable, then https://api.x.ai/v1. Set it to route calls through a proxy or gateway.

Example

::xai::api/base-url()                                        // => "https://api.x.ai/v1"
::xai::api/base-url({base-url: "https://gw.example.com/v1"}) // => "https://gw.example.com/v1"
Context Vars: xai.base.url

build-headers

fn (resolved: Map, has-body: Bool): Map

Request headers from resolved settings (see resolve), pure: Authorization: Bearer, and Content-Type when there is a body. Exposed for testing.

Example

::api ::xai::api

::api/build-headers({api-key: "test-key"}, false)  // {Authorization: "Bearer test-key"}
::api/build-headers({api-key: "test-key"}, true).Content-Type  // "application/json"

build-request

fn (method: Str, url: Str, additional-headers: Map, body: Any, resolved: Map): ::hot::http/HttpRequest

The outgoing HttpRequest for resolved settings, pure. additional-headers override the defaults. An empty or null body sends no body at all. Exposed for testing.

Example

resolved ::xai::api/resolve-from({api-key: "k"}, {})
req ::xai::api/build-request("GET", "https://api.x.ai/v1/models", {}, "", resolved)
req.headers  // {Authorization: "Bearer k"}

call

fn (method: Str, path: Str, additional-headers: Map, body: Any, opts: Map): ::hot::http/HttpResponse

Resolve opts and send a request to path under the resolved base URL. The typed functions in this package go through here.

Example

response ::xai::api/call("GET", "/models", {}, "", {api-key: "tenant-key"})
Context Vars: xai.api.key, xai.base.url

call-stream

fn (method: Str, path: Str, additional-headers: Map, body: Any, format: Str, opts: Map): ::hot::http/StreamingHttpResponse

Streaming counterpart to call. Returns a StreamingHttpResponse whose body is an iterator of parsed SSE or NDJSON events.

Example

::api ::xai::api

response ::api/call-stream("POST", "/responses", {}, {model: "grok-3", input: "Hello", stream: true}, "sse", {})
for-each(response.body, (event) { println(event) })
Context Vars: xai.api.key, xai.base.url

management-call

fn (method: Str, path: Str, additional-headers: Map, body: Any, opts: Map): ::hot::http/HttpResponse

call for the Management API: resolves management-api-key and management-base-url (see resolve-management).

Example

response ::xai::api/management-call("GET", "/v1/collections", {}, "", {management-api-key: "tenant-key"})
Context Vars: xai.management.api.key, xai.management.base.url

non-blank

fn (value: Any): Any

value, or null when it is null or a blank Str.

Example

::api ::xai::api

::api/non-blank("  ")  // null
::api/non-blank("grok-3")  // "grok-3"

normalize-base-url

fn (url: Str?): Str
fn (url: Str?, default-url: Str): Str

Normalize a base URL: trims whitespace, drops trailing slashes, and falls back to default-url (::xai/BASE_URL when not given) when the value is null or empty.

Example

::xai::api/normalize-base-url("https://gateway.example.com/v1/")  // => "https://gateway.example.com/v1"
::xai::api/normalize-base-url(null)                               // => "https://api.x.ai/v1"

request

fn (method: Str, url: Str): ::hot::http/HttpResponse
fn (method: Str, url: Str, additional-headers: Map): ::hot::http/HttpResponse
fn (method: Str, url: Str, additional-headers: Map, body: Any): ::hot::http/HttpResponse
fn (method: Str, url: Str, additional-headers: Map, body: Any, api-key: Str): ::hot::http/HttpResponse
fn (method: Str, url: Str, additional-headers: Map, body: Any, opts: Map): ::hot::http/HttpResponse

Make an authenticated HTTP request to the xAI API.

Automatically includes the Authorization header using the xai.api.key from context. Additional headers can be provided to merge/override defaults. When a body is provided, Content-Type is set to application/json and the body is serialized.

Supports 2 to 5 arguments: (method, url), (method, url, headers), (method, url, headers, body), or (method, url, headers, body, api-key). The last argument can also be an opts Map (see resolve).

Example

// Simple GET request
response ::xai::api/request("GET", "https://api.x.ai/v1/models")

// POST with body
response ::xai::api/request("POST", "https://api.x.ai/v1/responses", {}, {
    model: "grok-3-mini",
    input: "Hello"
})
Context Vars: xai.api.key

request-stream

fn (method: Str, url: Str, additional-headers: Map, body: Any): ::hot::http/StreamingHttpResponse
fn (method: Str, url: Str, additional-headers: Map, body: Any, format: Str): ::hot::http/StreamingHttpResponse
fn (method: Str, url: Str, additional-headers: Map, body: Any, format: Str, api-key: Str): ::hot::http/StreamingHttpResponse
fn (method: Str, url: Str, additional-headers: Map, body: Any, format: Str, opts: Map): ::hot::http/StreamingHttpResponse

Make an authenticated streaming HTTP request to the xAI API.

Returns a StreamingHttpResponse with an iterator body for processing SSE events. Automatically includes the Authorization header using the xai.api.key from context.

Supports 4 to 6 arguments: (method, url, headers, body), (method, url, headers, body, format), or (method, url, headers, body, format, api-key). The last argument can also be an opts Map (see resolve).

Example

response ::xai::api/request-stream("POST", "https://api.x.ai/v1/responses", {}, {
    model: "grok-3-mini",
    input: "Hello",
    stream: true
})

events collect(response.body)
// events is a Vec of SSE event objects
Context Vars: xai.api.key

resolve

fn (): Map
fn (opts: Map): Map

Settings for one main API call: opts over ctx over defaults (see resolve-from). With an api-key in opts, the ctx key is not read, and a blank one is an Err rather than a fallback to ctx. Nothing is written to ctx, and the key from opts is masked in the run's call records.

Example

::xai::api/resolve({api-key: "tenant-key"}).base-url  // => "https://api.x.ai/v1"
Context Vars: xai.api.key, xai.base.url

resolve-from

fn (opts: Map, ctx-values: Map): Map

The resolver for the main API, pure: settings for a call from opts first, then ctx-values (a Map of context variables), then defaults. Returns {api-key, base-url}, or an Err when no API key is set, when api-key in opts is blank (never a fallback to ctx, so a tenant with a missing key can't run on the project's key), or when opts has a base-url but no api-key (the ctx key is never sent to a per-call URL). Exposed for testing; resolve feeds it the context.

Example

::xai::api/resolve-from({api-key: "k"}, {}).base-url  // => "https://api.x.ai/v1"

resolve-management

fn (opts: Map): Map

Settings for one Management API call (see resolve-management-from). With a management-api-key in opts, the ctx key is not read, and a blank one is an Err rather than a fallback to ctx. Nothing is written to ctx, and the key from opts is masked in the run's call records.

Example

::api ::xai::api

settings ::api/resolve-management({management-api-key: ::hot::ctx/get("tenant.xai.management.key")})
settings.base-url
Context Vars: xai.management.api.key, xai.management.base.url

resolve-management-from

fn (opts: Map, ctx-values: Map): Map

resolve-from for the Management API: management-api-key and management-base-url from opts, then ctx-values, then defaults. Returns {api-key, base-url}, or an Err when no management key is set, when management-api-key in opts is blank, or when opts has a management-base-url but no management-api-key. An api-key in opts is not used here: the two keys are different credentials.

Example

::xai::api/resolve-management-from({management-api-key: "k"}, {}).base-url  // => "https://management-api.x.ai"

Types

HttpError

HttpError type {
    status: Int,
    headers: Map,
    body: Any
}