Transport for the Notion API.

Per-call credentials. Every API-calling function in this package takes an optional trailing opts Map, resolved by resolve: opts first, then the notion.token context variable, then the defaults. Nothing from opts is written to ctx, so one run can act for many workspaces and parallel flows don't share credentials. A token present but blank or null is an error, never a fallback to context.

  • token: the integration secret or OAuth access token for this call
  • api-version: the Notion-Version for this call
  • base-url: another API root, such as a proxy. It needs a token in the same opts: notion.token is never sent to a per-call URL.

Context Vars

Optional
  • notion.token

Functions

blank-credential

fn (opts: Map, names: Vec): Str?

The first of names that opts has but with a blank or null value, else null. Such a key is an error, never a fallback to context: a tenant whose key is missing must not run on the project's credentials.

Example

::notion::api/blank-credential({token: "  "}, ["token"])  // "token"
::notion::api/blank-credential({token: "ntn_test"}, ["token"])  // null

build-request

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

The outgoing HttpRequest from resolved settings (see resolve). additional-headers win over the defaults, and a "" body sends no Content-Type. Pure; exposed for testing.

Example

resolved {token: "test-token", base-url: "https://api.notion.com/v1", api-version: "2022-06-28"}
req ::notion::api/build-request("POST", "/search", {}, {query: "roadmap"}, resolved)
req.url  // "https://api.notion.com/v1/search"
req.headers.Authorization  // "Bearer test-token"

json

fn (method: Str, path: Str): Any
fn (method: Str, path: Str, additional-headers: Map, body: Any): Any
fn (method: Str, path: Str, additional-headers: Map, body: Any, token: Str): Any
fn (method: Str, path: Str, additional-headers: Map, body: Any, opts: Map): Any

Like request, but unwraps: the decoded JSON body on 2xx, or an Err carrying HttpError (Notion's error code/message are in body).

Example

me ::notion::api/json("GET", "/users/me")
me.name

// Per-call credentials
found ::notion::api/json("POST", "/search", {}, {query: "roadmap"}, {
  token: ::hot::ctx/get("tenant.notion.token")
})
found.results

request

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

Make an authenticated request to the Notion API. path is relative to api.notion.com/v1. Sends the required Notion-Version header.

Example

response ::notion::api/request("GET", "/users/me")
response.status

// Per-call credentials
::notion::api/request("POST", "/search", {}, {query: "roadmap"}, {
  token: ::hot::ctx/get("tenant.notion.token")
})

resolve

fn (opts: Map): Map

Credentials and settings for one call (see resolve-from). opts values are never written to ctx. A credential from opts is masked in the run's call records.

Example

::notion::api/resolve({token: "ntn_tenant_b"}).api-version  // "2022-06-28"
Context Vars: notion.token

resolve-from

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

The one resolver, pure: {token, base-url, api-version} for a call from opts first, then ctx-values (a Map of context variables), then defaults. An Err when no token is set, when token is in opts but blank or null (that never falls back to context), or when opts has base-url without token. Exposed for testing; resolve feeds it the context.

Example

ctx-values {"notion.token": "ctx-token"}
::notion::api/resolve-from({}, ctx-values).token  // "ctx-token"
::notion::api/resolve-from({token: "call-token"}, ctx-values).token  // "call-token"
is-err(::notion::api/resolve-from({token: ""}, ctx-values))  // true

settings-from

fn (opts: Map): Map

The non-credential settings of a call (pure): {base-url, api-version} from opts, else the package defaults.

Example

::notion::api/settings-from({api-version: "2025-09-03"}).api-version  // "2025-09-03"
::notion::api/settings-from({base-url: "https://proxy.example.com/v1/"}).base-url  // "https://proxy.example.com/v1"

Types

HttpError

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