Assistant
The channel identities allowed to operate your naturali account.
Overview
The Naturali Assistant is the first-party agent you talk to on a messaging channel — Discord, WhatsApp, Slack — to run your account: inspect projects, check usage, manage agents and channels. This API is the consent layer in front of it: a grant is one channel identity authorized to act as one naturali account.
A grant is account-scoped and carries no project. Every project-scoped
operation still resolves ownership per request, so a linked identity reaches
exactly what you already see in the app and nothing more. Its scopes bound
what it does there: without manage, the Assistant only reads (GET), and any
other call answers 403 FORBIDDEN. The runtime holds it to the same: a
call such a grant relays goes upstream on a credential that carries read
actions only.
The Assistant's tool calls carry no credential of their own. Each is resolved to its account, and to the grant behind it, from the session the runtime's signed tool assertion names, on every call, so revoking a grant stops the next call.
See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Assistant.
Data Model
AssistantGrant
| Field | Type | Description |
|---|---|---|
id | string | Public grant ID (agr_ prefix). |
channel | discord | whatsapp | slack | The channel the linked identity lives on. The app is never a value here: a signed-in web session already is the identity, so it needs no grant. |
identifier | string | The channel identity as an address identifier (discord:dm:<user_id>, whatsapp:dm:<phone>), the one grammar channels use on the wire. One identity operates one account. |
display_name | string, nullable | The identity as its channel reported it, when it reported one — what a person recognizes instead of an opaque id. Null when the channel offers nothing better than the identifier. |
scopes | array of read | manage | What the Assistant may do on the account. Deliberately coarse: the consent for a specific dangerous action is asked for when it happens, through the approval queue, rather than pre-granted here. A link grants read. |
status | active | revoked | Whether the Assistant currently answers this identity. |
last_used_at | string (date-time), nullable | When the Assistant last acted under this grant; null if never. |
created_at | string (date-time) |
Key Concepts
Linking starts on the channel, not here
There is no endpoint that creates a link. Message the Assistant from an unlinked identity and it replies with a single-use link back to the app; that link lands on a confirmation screen which resolves the identity and, on an explicit click, redeems it.
Two calls make up that screen: GET /v1/assistant/link resolves a token
without consuming it, so the screen can name the identity before anyone
commits, and POST /v1/assistant/link redeems it. Reading is separate from
redeeming on purpose — a single-use nonce must not be spent by a URL scanner or
a browser prefetch.
One identity, one account
The same Discord user cannot be linked to two naturali accounts. Re-pointing an
identity means revoking the existing grant first, which is explicit and
auditable; redeeming a link for an identity that is already linked answers
409 IDENTITY_ALREADY_LINKED.
A dead link answers 400 with LINK_INVALID (unknown or already redeemed) or
LINK_EXPIRED (it simply ran out of time — ask the Assistant for a fresh one).
Revoking is immediate
The grant is resolved on every inbound message, so revoking stops the Assistant
on the next one rather than at some expiry. Work a read link started in a
project (a paused generation) fails WORK_AUTHORITY_MISSING on its next step;
if the runtime does not record that, the revoke answers 502 and the grant
stays active. The row stays as consent history, and the identity is free to
link again afterwards.
Removing the account from a project revokes its grants in that project only (Projects).
Conversations are sessions
Every conversation is a session of its own, marked with the channel it runs on. An account can hold many, on every channel.
In the app the signed-in account is the identity, so there is nothing to link.
POST /v1/assistant/sessions
starts a conversation,
GET /v1/assistant/sessions
lists them newest first, and
POST /v1/assistant/sessions/{session_id}/messages
and
GET /v1/assistant/sessions/{session_id}/messages
send a turn and read the conversation back — both lists page by limit and
cursor, and order=desc reads a conversation from its newest message. The
first message names the
session unless
PATCH /v1/assistant/sessions/{session_id}
named it first.
DELETE /v1/assistant/sessions/{session_id}
deletes one and its messages; what its turns cost stays on your usage. An app
session never expires. A
credential confined to one project cannot hold the conversations, and a
deployment that serves no Assistant answers 503 ASSISTANT_UNAVAILABLE.
On a channel, a linked identity's messages continue its open session. A
session left idle for 24 hours expires, and the next message starts a new one.
Send /nova (or /new) to start over at once; it costs nothing.
A message can carry the page it was sent from
In the app the Assistant also opens beside any screen, and each message sent
there carries that screen's path as context.path, so "this playbook" means
the one on screen. Pages can be added to a message too, as context.attached
(up to 10 app paths): replies link the app pages they name, and each link's
+ adds its page to the next message. The turn reads both back with
GET /v1/assistant/context, with
the resource ids each path names (project_id, playbook_id, channel_id),
then reads the pages themselves from the API. Only paths travel, and only to the
turn that message started; any other caller reads path: null and no pages.
Your turns are paid from your credit
Every turn the Assistant answers on a linked identity is charged to your
account's credit, at the same rate as managed model usage, and appears on your
ledger as Assistant usage. When your balance is below zero the Assistant
answers with a link to billing instead of running — in the app,
402 INSUFFICIENT_CREDIT — and answers again once you top up.
Examples
List the identities linked to your account:
- CLI
- SDK
- curl
naturali list-assistant-grants
const { data: page } = await naturali.assistant.listAssistantGrants();
curl https://api.naturali.ai/v1/assistant/grants \
-H "Authorization: Bearer $NATURALI_TOKEN"
Revoke one, disabling the Assistant for that identity:
- CLI
- SDK
- curl
naturali revoke-assistant-grant --grant-id agr_V1StGXR8Z5jdHi6B
await naturali.assistant.revokeAssistantGrant({
path: { grant_id: 'agr_V1StGXR8Z5jdHi6B' },
});
curl -X DELETE https://api.naturali.ai/v1/assistant/grants/agr_V1StGXR8Z5jdHi6B \
-H "Authorization: Bearer $NATURALI_TOKEN"
Start a conversation as your account, then message it:
- CLI
- SDK
- curl
naturali create-assistant-session
naturali send-assistant-session-message --session-id sess_V1StGXR8Z5jdHi6B \
--content "List my projects."
const { data: session } = await naturali.assistant.createAssistantSession();
const { data: turn } = await naturali.assistant.sendAssistantSessionMessage({
path: { session_id: session!.id },
body: { content: 'List my projects.' },
});
curl -X POST https://api.naturali.ai/v1/assistant/sessions \
-H "Authorization: Bearer $NATURALI_TOKEN"
curl -X POST https://api.naturali.ai/v1/assistant/sessions/sess_V1StGXR8Z5jdHi6B/messages \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{"content": "List my projects."}'