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 callapi-version: theNotion-Versionfor this callbase-url: another API root, such as a proxy. It needs atokenin the sameopts:notion.tokenis never sent to a per-call URL.
Context Vars
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"
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
}