Skip to main content

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.

naturali list-agents \
--project-id proj_V1StGXR8Z5jdHi6B \
--limit 50 \
--cursor "$NEXT_CURSOR"

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.