openapi: 3.0.3
info:
  title: naturali.ai — Assistant API
  version: 1.0.0
  description: >
    The Naturali Assistant is the first-party agent you talk to on a messaging
    channel — Discord, WhatsApp, Slack — to operate your naturali account:
    inspect projects, check usage, manage agents and channels. This API is the
    consent layer in front of it: which channel identities are allowed to act on
    your account, and how one becomes allowed.

    A grant is account-scoped and carries no project. It is a consent record,
    not a permission boundary: 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. Revoking takes effect on the next
    message, not at some expiry.

    Grants are managed with a session access JWT or an account-wide API key. A
    credential confined to a single project cannot manage them: a grant is
    account-level, so a project-scoped key acting on one would reach past its
    own confinement.

    Linking starts on the channel, never here. 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 with
    `GET /v1/assistant/link` and, on an explicit click, redeems it with
    `POST /v1/assistant/link`. There is no endpoint that mints a link — a
    caller who could mint one could invite an identity that never asked to be
    invited.
  contact:
    name: naturali.ai
    url: https://naturali.ai
servers:
  - url: '{baseUrl}'
    description: Host of your naturali.ai deployment; every path carries the /v1 prefix.
    variables:
      baseUrl:
        description: Base host URL.
        default: https://api.naturali.ai
tags:
  - name: Assistant
    description: >
      Link and revoke the channel identities allowed to operate your naturali
      account through the Naturali Assistant.
security:
  - bearerAuth: []
  - oauth2:
      - mcp:access
paths:
  /v1/assistant/grants:
    get:
      tags: [Assistant]
      summary: List linked identities
      description: >
        Lists the caller's assistant grants — one per channel identity that may
        operate their account. Grants belong to the account, so this is the
        caller's own set regardless of which projects they own.
      operationId: listAssistantGrants
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of grants.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Page'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/AssistantGrant'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccountWideOnly'
  /v1/assistant/grants/{grant_id}:
    parameters:
      - $ref: '#/components/parameters/GrantId'
    delete:
      tags: [Assistant]
      summary: Revoke a linked identity
      description: >
        Revokes the grant, disabling the Assistant for that identity. The grant
        is resolved on every inbound message, so the next one from that identity
        is refused before the agent is invoked — revocation is immediate, not
        eventual. Work the grant started (a paused generation) calls no tool
        on its next step. The identity is free to link again afterwards.
      operationId: revokeAssistantGrant
      responses:
        '204':
          description: Grant revoked.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccountWideOnly'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          $ref: '#/components/responses/GrantRevocationUnavailable'
  /v1/assistant/link:
    get:
      tags: [Assistant]
      summary: Resolve a pending link
      description: >
        Resolves a link token **without consuming it**, so the confirmation
        screen can name the identity being linked ("@user on Discord") before
        anyone commits to it. Naming it is what makes a link pasted into the
        wrong hands fail the human check as well as the server-side binding.

        Reading is deliberately separate from redeeming: a single-use nonce must
        not be burned by a link preview, a URL scanner or a browser prefetch.
      operationId: previewAssistantLink
      parameters:
        - $ref: '#/components/parameters/LinkToken'
      responses:
        '200':
          description: The identity this token would link, and what it would be allowed to do.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantLinkPreview'
        '400':
          description: >
            The token is unknown, expired, or already redeemed
            (`LINK_INVALID` / `LINK_EXPIRED`). Getting a fresh one means
            messaging the Assistant again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccountWideOnly'
    post:
      tags: [Assistant]
      summary: Redeem a link token
      description: >
        Redeems a link token and creates the grant, binding the channel identity
        the token carries to the authenticated account. The identity is read from
        the token server-side — nothing in this request can point the link at a
        different one.

        The token is the idempotency key: it is single-use, so a replay of this
        request fails rather than creating a second grant.
      operationId: redeemAssistantLink
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssistantLinkRedeem'
      responses:
        '201':
          description: Grant created. The Assistant answers that identity from the next message on.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantGrant'
        '400':
          description: >
            The token is missing, unknown, expired, or already redeemed
            (`LINK_INVALID` / `LINK_EXPIRED`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccountWideOnly'
        '409':
          description: >
            The identity is already linked to an account
            (`IDENTITY_ALREADY_LINKED`). One channel identity operates one
            naturali account: re-pointing it means revoking the existing grant
            first, which is explicit and auditable rather than silent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/assistant/context:
    get:
      tags: [Assistant]
      summary: Read the turn's context
      description: >
        What the Assistant turn this call runs in was sent with: the app page
        the person had open and the pages they added to the message, each
        with the resource ids its path names. The Assistant calls it when a message points at the screen ("this
        playbook") or at what was added. Any other caller reads `path: null`
        and no pages.
      operationId: getAssistantContext
      responses:
        '200':
          description: The turn's context.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantTurnContext'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/assistant/sessions:
    get:
      tags: [Assistant]
      summary: List your conversations
      description: >
        Your conversations with the Assistant in the app, newest first. Each is
        a session of its own; a conversation on Discord or WhatsApp is not
        listed here.
      operationId: listAssistantSessions
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of sessions.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Page'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/AssistantSession'
        '400':
          description: '`limit` or `cursor` is invalid.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ConversationForbidden'
        '502':
          $ref: '#/components/responses/TurnUnavailable'
        '503':
          $ref: '#/components/responses/AssistantUnavailable'
    post:
      tags: [Assistant]
      summary: Start a conversation
      description: >
        Opens a new, empty conversation with the Assistant. It costs nothing
        until a message is sent, and it does not expire.
      operationId: createAssistantSession
      responses:
        '201':
          description: The new session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantSession'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ConversationForbidden'
        '502':
          $ref: '#/components/responses/TurnUnavailable'
        '503':
          $ref: '#/components/responses/AssistantUnavailable'
  /v1/assistant/sessions/{session_id}:
    parameters:
      - $ref: '#/components/parameters/AssistantSessionId'
    patch:
      tags: [Assistant]
      summary: Rename a conversation
      description: >
        Sets the name the conversation is listed by. A name given before the
        first message is kept.
      operationId: renameAssistantSession
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 60
                  description: Trimmed before it is stored.
                  example: Relatório diário
      responses:
        '200':
          description: The renamed session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantSession'
        '400':
          description: '`name` is missing, blank or longer than 60 characters.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ConversationForbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          $ref: '#/components/responses/TurnUnavailable'
        '503':
          $ref: '#/components/responses/AssistantUnavailable'
    delete:
      tags: [Assistant]
      summary: Delete a conversation
      description: >
        Deletes one of your conversations and its messages. What its turns cost
        stays on your usage.
      operationId: deleteAssistantSession
      responses:
        '204':
          description: The conversation is deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ConversationForbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          $ref: '#/components/responses/TurnUnavailable'
        '503':
          $ref: '#/components/responses/AssistantUnavailable'
  /v1/assistant/sessions/{session_id}/messages:
    parameters:
      - $ref: '#/components/parameters/AssistantSessionId'
    get:
      tags: [Assistant]
      summary: Read a conversation
      description: >
        A page of one conversation, oldest first unless `order=desc`. The list
        leaves out tool-only turns, so a page can hold fewer than `limit` and
        still have a `next_cursor`.
      operationId: listAssistantSessionMessages
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
        - name: order
          in: query
          required: false
          description: '`desc` reads the conversation from its newest message.'
          schema:
            type: string
            enum: [asc, desc]
            default: asc
      responses:
        '200':
          description: The conversation.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Page'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/AssistantMessage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ConversationForbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          $ref: '#/components/responses/TurnUnavailable'
        '503':
          $ref: '#/components/responses/AssistantUnavailable'
    post:
      tags: [Assistant]
      summary: Message the Assistant
      description: >
        Runs one turn as your account and answers with the messages it added:
        yours, then the Assistant's reply. The turn is paid from your credit and
        refused before it runs when the balance is below zero.
      operationId: sendAssistantSessionMessage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssistantMessageCreate'
      responses:
        '201':
          description: The messages this turn added, oldest first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantTurnMessages'
        '400':
          description: >
            `content` is missing or blank, or `context` is not an app path.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: >
            Your credit balance is below zero (`INSUFFICIENT_CREDIT`). Top up to
            message the Assistant again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          $ref: '#/components/responses/ConversationForbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: >
            The session is closed or expired (`SESSION_CLOSED`). Start a new
            conversation to continue.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          $ref: '#/components/responses/TurnUnavailable'
        '503':
          $ref: '#/components/responses/AssistantUnavailable'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A naturali API key (nat_sk_…) or a session JWT.
    oauth2:
      type: oauth2
      description: >-
        A connected app's OAuth access token, issued by this API's authorization
        server (discovery: /.well-known/oauth-authorization-server). Its one scope
        carries every operation, confined to the projects the user chose when
        approving the app.
      flows:
        authorizationCode:
          authorizationUrl: https://api.naturali.ai/authorize
          tokenUrl: https://api.naturali.ai/token
          refreshUrl: https://api.naturali.ai/token
          scopes:
            mcp:access: Every operation this API serves, on the projects the grant covers.
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      description: >-
        Results per page, 1 to 100 (default 50). Above 100 it is clamped; below 1
        or not an integer it is `400`.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    Cursor:
      name: cursor
      in: query
      required: false
      description: >-
        The previous page's `next_cursor`; omit it for the first page. A cursor
        this list did not issue is `400`.
      schema:
        type: string
    GrantId:
      name: grant_id
      in: path
      required: true
      description: Grant public ID (agr_ prefix).
      schema:
        type: string
        example: agr_V1StGXR8Z5jdHi6B
    AssistantSessionId:
      name: session_id
      in: path
      required: true
      description: Assistant session ID, as listed.
      schema:
        type: string
        example: sess_V1StGXR8Z5jdHi6B
    LinkToken:
      name: token
      in: query
      required: true
      description: The single-use token from the link the Assistant sent on the channel.
      schema:
        type: string
        example: alt_9f8e7d6c5b4a39281706
  responses:
    AccountWideOnly:
      description: >-
        `FORBIDDEN`: the credential is confined to one project. Account
        routes need an account-wide credential.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The resource does not exist (existence is not leaked).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ConversationForbidden:
      description: >
        The credential cannot hold the account's conversation
        (`FORBIDDEN`): it is confined to one project, or it is the
        Assistant's own turn credential.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    GrantRevocationUnavailable:
      description: >
        `UPSTREAM_UNAVAILABLE`: the runtime did not record the revocation, so
        the grant stays active. Retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TurnUnavailable:
      description: The turn could not be run or read (`UPSTREAM_UNAVAILABLE`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    AssistantUnavailable:
      description: >
        This deployment serves no Assistant conversation
        (`ASSISTANT_UNAVAILABLE`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    Page:
      type: object
      description:
        One page of a list. Rows inserted or removed between two calls neither repeat nor skip
        a row on the next page.
      required:
        - data
        - next_cursor
      properties:
        data:
          type: array
          description: This page's items, in the list's order.
          items: {}
        next_cursor:
          type: string
          nullable: true
          description: Pass as `cursor` to fetch the next page; `null` on the last page.
    AssistantGrant:
      type: object
      description: >
        One channel identity authorized to operate one naturali account through
        the Assistant.
      properties:
        id:
          type: string
          description: Public grant ID (agr_ prefix).
          example: agr_V1StGXR8Z5jdHi6B
        channel:
          $ref: '#/components/schemas/AssistantChannel'
        identifier:
          type: string
          description: >
            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.
          example: discord:dm:112233445566778899
        display_name:
          type: string
          nullable: true
          description: >
            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.
          example: ana
        scopes:
          type: array
          description: >
            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`.
          items:
            $ref: '#/components/schemas/AssistantScope'
          example: ['read']
        status:
          type: string
          enum: [active, revoked]
          description: Whether the Assistant currently answers this identity.
          example: active
        last_used_at:
          type: string
          format: date-time
          nullable: true
          description: When the Assistant last acted under this grant; null if never.
          example: '2026-07-17T09:12:00.000Z'
        created_at:
          type: string
          format: date-time
          example: '2026-07-17T00:00:00.000Z'
      required:
        [
          id,
          channel,
          identifier,
          display_name,
          scopes,
          status,
          last_used_at,
          created_at,
        ]
    AssistantChannel:
      type: string
      enum: [discord, whatsapp, slack]
      description: >
        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.
      example: discord
    AssistantScope:
      type: string
      enum: [read, manage]
      description: >
        `read` lists and inspects projects, agents, channels, knowledge and
        usage. `manage` additionally mutates, still subject to the approval
        queue for destructive operations. A link currently grants `read`.
      example: read
    AssistantLinkPreview:
      type: object
      description: >
        What a pending link would do, resolved from its token without consuming
        it.
      properties:
        channel:
          $ref: '#/components/schemas/AssistantChannel'
        identifier:
          type: string
          description: The channel identity this token would link, as an address identifier.
          example: discord:dm:112233445566778899
        display_name:
          type: string
          nullable: true
          description: The identity as its channel reported it, for the confirmation screen.
          example: ana
        scopes:
          type: array
          items:
            $ref: '#/components/schemas/AssistantScope'
          description: What redeeming this token would allow.
          example: ['read']
        expires_at:
          type: string
          format: date-time
          description: When the token stops being redeemable. Links are short-lived by design.
          example: '2026-07-17T00:10:00.000Z'
      required: [channel, identifier, display_name, scopes, expires_at]
    AssistantLinkRedeem:
      type: object
      required: [token]
      properties:
        token:
          type: string
          description: The single-use token from the link the Assistant sent on the channel.
          example: alt_9f8e7d6c5b4a39281706
    AssistantSession:
      type: object
      description: One conversation with the Assistant in the app.
      required: [id, name, status, created_at, last_activity_at]
      properties:
        id:
          type: string
          example: sess_V1StGXR8Z5jdHi6B
        name:
          type: string
          nullable: true
          description: >
            The name given to the conversation, else its first message cut to
            60 characters; null until either.
          example: liste quantos agentes eu tenho no projeto sandbox
        status:
          type: string
          enum: [open, closed, expired]
          description: Only an `open` session takes messages.
          example: open
        created_at:
          type: string
          format: date-time
          example: '2026-10-07T12:00:00.000Z'
        last_activity_at:
          type: string
          format: date-time
          nullable: true
          description: When the session last took a message; null until the first.
          example: '2026-10-07T12:05:00.000Z'
    AssistantMessage:
      type: object
      required: [id, role, content]
      properties:
        id:
          type: string
          example: doc_V1StGXR8Z5jdHi6B
        role:
          type: string
          enum: [user, assistant]
          example: assistant
        content:
          type: string
          example: You have two projects.
    AssistantMessageCreate:
      type: object
      required: [content]
      additionalProperties: false
      properties:
        content:
          type: string
          minLength: 1
          example: List my projects.
        context:
          $ref: '#/components/schemas/AssistantPageContext'
    AssistantPageContext:
      type: object
      description: >
        Where in the app the message was sent from, and the pages the person
        added to it. The turn can read both back with `GET /v1/assistant/context`,
        so "this playbook" means the one on screen. Only paths travel; what the
        pages show, the Assistant reads from the API itself.
      additionalProperties: false
      properties:
        path:
          type: string
          minLength: 1
          maxLength: 512
          pattern: '^/(?!/)'
          description: The app page beside the conversation, starting with `/`; never a URL.
          example: /projects/proj_V1StGXR8Z5jdHi6B/playbooks/pbk_2x7Qd9LmN4cV/cases
        attached:
          type: array
          maxItems: 10
          description: App pages the person added to this message; a repeated one counts once.
          items:
            type: string
            minLength: 1
            maxLength: 512
            pattern: '^/(?!/)'
          example: [/projects/proj_V1StGXR8Z5jdHi6B]
    AssistantTurnContext:
      type: object
      description: The context of the Assistant turn the call runs in.
      required: [path, attached, pages]
      properties:
        path:
          type: string
          nullable: true
          description: >
            The app path the turn's message was sent from; `null` outside a
            turn, or for a turn sent from no page.
          example: /projects/proj_V1StGXR8Z5jdHi6B/playbooks/pbk_2x7Qd9LmN4cV/cases
        attached:
          type: array
          description: The app pages the person added to the turn's message; empty outside a turn.
          items:
            type: string
          example: [/projects/proj_V1StGXR8Z5jdHi6B]
        pages:
          type: array
          description: >
            The page open, then each added page, with the resource ids its
            path names. Empty outside a turn.
          items:
            $ref: '#/components/schemas/AssistantContextPage'
    AssistantContextPage:
      type: object
      description: One app page of the turn's context.
      required: [path, source, ids]
      properties:
        path:
          type: string
          example: /projects/proj_V1StGXR8Z5jdHi6B/playbooks/pbk_2x7Qd9LmN4cV/cases
        source:
          type: string
          enum: [page, attached]
          description: '`page` for the page open, `attached` for one the person added.'
        ids:
          type: object
          description: The resource ids the path names; a key is absent when the path names none.
          additionalProperties: false
          properties:
            project_id:
              type: string
              example: proj_V1StGXR8Z5jdHi6B
            playbook_id:
              type: string
              example: pbk_2x7Qd9LmN4cV
            channel_id:
              type: string
    AssistantTurnMessages:
      type: object
      description: The messages one turn added — yours, then the Assistant's reply.
      required: [data]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AssistantMessage'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          description: >-
            Structured error. Every error response uses this shape, so `code` can
            be read without first checking the type of `error`.
          required:
            - code
            - message
            - hint
          properties:
            code:
              type: string
              pattern: '^[A-Z][A-Z0-9_]*$'
              description: >-
                Machine-readable error code, UPPER_SNAKE whether naturali or the
                runtime raises it.
              example: FORBIDDEN
            message:
              type: string
              description: Human-readable explanation.
              example: Your role in this project does not carry this action.
            hint:
              type: string
              description: >-
                What to do about it, naming the routes of this API to call. For
                people and agents; it may change, so branch on `code`.
              example: >-
                Use a credential whose scope includes this action, or ask a
                project `admin` or `owner` to act; the caller's role or key
                excludes it.
            meta:
              type: object
              additionalProperties: true
              description: >-
                Structured context, such as the `resource` and `limit` of a
                `PLAN_LIMIT_REACHED`.
