Skip to main content

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​

FieldTypeDescription
idstringPublic grant ID (agr_ prefix).
channeldiscord | whatsapp | slackThe 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.
identifierstringThe 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_namestring, nullableThe 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.
scopesarray of read | manageWhat 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.
statusactive | revokedWhether the Assistant currently answers this identity.
last_used_atstring (date-time), nullableWhen the Assistant last acted under this grant; null if never.
created_atstring (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:

naturali list-assistant-grants

Revoke one, disabling the Assistant for that identity:

naturali revoke-assistant-grant --grant-id agr_V1StGXR8Z5jdHi6B

Start a conversation as your account, then message it:

naturali create-assistant-session
naturali send-assistant-session-message --session-id sess_V1StGXR8Z5jdHi6B \
--content "List my projects."