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: overridesxai.api.key.base-url: overridesxai.base.url.management-api-key: overridesxai.management.api.key, used by the::xai::collectionsmanagement calls.management-base-url: overridesxai.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"
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"})
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) })
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"})
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"
})
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
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"
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
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
}