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 call
  • api-version: the X-Pinecone-Api-Version for 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

Optional
  • pinecone.api.key
  • pinecone.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"
Context Vars: 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.