Low-level Pinecone HTTP client: Api-Key auth, the
X-Pinecone-Api-Version header, error decoding, and the pure URL
helpers the other modules share.
Per-call credentials. Every API-calling function in this package
takes an optional trailing opts Map, resolved by resolve: opts
first, then context, then the defaults. Nothing from opts is written
to ctx, so one run can act for many projects and parallel flows don't
share credentials. Credentials in opts are masked in call records. An
api-key present but blank or null is an error, never a fallback to
context.
api-key: the API key for this callapi-version: theX-Pinecone-Api-Versionfor this call
An index host is a per-call URL. pinecone.api.key only goes to
https://*.pinecone.io, such as the host from describe-index: any
other host, like Pinecone Local, needs an api-key in the call's opts.
Context Vars
pinecone.api.keypinecone.api.version
Functions
build-request
fn (method: Str, url: Str, encoded: Str, content-type: Any, resolved: Map): ::hot::http/HttpRequest
The outgoing HttpRequest from resolved settings (see resolve). Pure;
exposed for testing.
Example
req ::pinecone::api/build-request("GET", "https://api.pinecone.io/indexes", "", null, {api-key: "test-key", api-version: "2026-07"})
req.url // "https://api.pinecone.io/indexes"
req.headers.X-Pinecone-Api-Version // "2026-07"
compact
fn (m: Map): Map
Drop null values from a Map, so unset options are omitted instead of sent as JSON null. Exposed for testing.
Example
::pinecone::api/compact({a: 1, b: null}) // {a: 1}
control-url
fn (segments: Str): Str
A control-plane URL: ::pinecone/CONTROL_URL plus the path, with each
path segment URL-encoded. Exposed for testing.
Example
::pinecone::api/control-url("indexes") // "https://api.pinecone.io/indexes"
data-url
fn (host: Str, segments: Vec, query: Map): Str
A data-plane URL on an index host: segments are URL-encoded and
joined, then the optional query (a Map; nulls dropped) is appended.
Exposed for testing.
Example
::pinecone::api/data-url("docs-abc.svc.pinecone.io", ["vectors", "list"], {limit: 10}) // "https://docs-abc.svc.pinecone.io/vectors/list?limit=10"
error-message
fn (status: Int, body: Any): Str
Readable text for a failed response, e.g. Pinecone API error 400 (INVALID_ARGUMENT): Index name must .... Exposed for testing.
Example
::pinecone::api/error-message(400, {error: {code: "INVALID_ARGUMENT", message: "Bad name"}}) // "Pinecone API error 400 (INVALID_ARGUMENT): Bad name"
::pinecone::api/error-message(503, "") // "Pinecone API error 503"
is-pinecone-url
fn (url: Str): Bool
True for an https:// URL on a pinecone.io host: the only place a
context key is sent. Exposed for testing.
Example
::pinecone::api/is-pinecone-url("https://docs-abc.svc.pinecone.io") // true
::pinecone::api/is-pinecone-url("http://localhost:5080") // false
json
fn (method: Str, url: Str, body: Any): Any
fn (method: Str, url: Str, body: Any, api-key: Str?): Any
fn (method: Str, url: Str, body: Any, opts: Map): Any
Make an authenticated Pinecone request against a full URL and
unwrap it: the decoded JSON body on 2xx (null for an empty body),
an Err carrying HttpError otherwise, or the transport Err. Pass
"" as body for requests without one. Sends Api-Key and
X-Pinecone-Api-Version (see resolve).
Example
url ::pinecone::api/control-url("indexes")
out ::pinecone::api/json("GET", url, "")
map(out.indexes, %.name)
// With another project's key
::pinecone::api/json("GET", url, "", {api-key: ::hot::ctx/get("tenant.pinecone.api.key")})
ndjson
fn (url: Str, records: Vec): Any
fn (url: Str, records: Vec, api-key: Str?): Any
fn (url: Str, records: Vec, opts: Map): Any
POST newline-delimited JSON (one record per line), as the Records upsert
endpoint requires. Returns like json.
Example
host ::pinecone::indexes/describe-index("docs").host
url ::pinecone::api/data-url(host, ["records", "namespaces", "notes", "upsert"], {})
::pinecone::api/ndjson(url, [{_id: "n1", chunk_text: "Hot runs workflows."}])
ndjson-body
fn (records: Vec): Str
Encode records as newline-delimited JSON. Exposed for testing.
Example
::pinecone::api/ndjson-body([{id: "a"}, {id: "b"}]) // "{\"id\":\"a\"}\n{\"id\":\"b\"}"
normalize-host
fn (host: Str): Str
Accept a bare index host (docs-abc123.svc...pinecone.io) or a full URL
and return the https:// base, without a trailing slash. Exposed for
testing.
Example
::pinecone::api/normalize-host("docs-abc.svc.pinecone.io/") // "https://docs-abc.svc.pinecone.io"
resolve
fn (opts: Map): Map
fn (opts: Map, url: Str): Map
Credentials and settings for one call (see resolve-from), optionally
for a url. An api-key from opts is masked in this run's records
and never written to ctx.
Example
::pinecone::api/resolve({api-key: ::hot::ctx/get("tenant.pinecone.api.key")}).api-version // "2026-07"
pinecone.api.key, pinecone.api.version
resolve-from
fn (opts: Map, ctx-values: Map): Map
fn (opts: Map, ctx-values: Map, url: Str): Map
The one resolver, pure: {api-key, api-version} for a call from opts
first, then ctx-values (a Map of context variables), then defaults.
An Err when no API key is set, or when api-key is in opts but blank
or null (that never falls back to context). With a url, also an Err
when it isn't a Pinecone URL and opts has no api-key. Exposed for
testing; resolve feeds it the context.
Example
::pinecone::api/resolve-from({api-key: "test-key"}, {}).api-version // "2026-07"
is-err(::pinecone::api/resolve-from({}, {})) // true
Types
HttpError
HttpError type {
status: Int,
message: Str,
headers: Map,
body: Any
}
A non-2xx Pinecone response. message is readable text built from
Pinecone's error body ({error: {code, message}, status} on the
control plane, {code, message} on the data plane); the raw body
is kept in body.