Conventions
These hold across every module; a module page calls out exceptions.
Base URL and versioning
https://api.naturali.ai/v1. The API is versioned in the path, and a client
should ignore fields and enum values it does not recognise. /v1 is not yet
stable: what may change in it, and where each breaking change is announced, is
in Versioning.
Resources that belong to a project live under
/v1/projects/{project_id}/…. Account-level ones — your user, API keys,
billing — live directly under /v1.
Fields and IDs
Wire casing is snake_case (project_id, created_at). Timestamps are ISO 8601
date-times.
Public IDs are prefixed per resource — proj_, agent_, tool_, sess_, … —
so an ID says what it names. Treat the rest as opaque.
A query parameter the operation does not declare is 400; meta lists
unknown_query_parameters and accepted_query_parameters. The project is the
one in the path, so project_id is never a query parameter.
Pagination
Every list endpoint is paginated by cursor: send limit and, after the first
page, cursor; the response is { data, next_cursor }, and the list ends when
next_cursor is null.
limit is 1 to 100 (default 50); a value above 100 is clamped to 100, and one
below 1 or not an integer is 400.
A cursor is opaque: pass back the next_cursor you were given, never one you
built. One the list did not issue is 400.
- CLI
- SDK
- curl
naturali list-agents \
--project-id proj_V1StGXR8Z5jdHi6B \
--limit 50 \
--cursor "$NEXT_CURSOR"
const { data: page } = await naturali.agents.listAgents({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
query: { limit: 50, cursor: nextCursor },
});
// Stop once page.next_cursor is null.
curl "https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/agents?limit=50&cursor=$NEXT_CURSOR" \
-H "Authorization: Bearer $NATURALI_TOKEN"
Idempotency
Where a duplicate would be expensive, a mutating POST takes an
idempotency_key in its body: the first request under a key does the work, a
repeat returns that same result. It is on
creating a project, connecting a
channel and starting an orchestration
run, not on every POST — a module page says so
where it applies.