openapi: 3.0.3
info:
  title: naturali.ai — Addresses API
  version: 1.0.0
  description: >
    An address is what an identifier names: a place a conversation can happen
    — sometimes a person's DM, sometimes a room a Discord server shares. It is project-scoped, keyed by the
    prefixed, self-describing identifier a channel adapter produces
    (`whatsapp:dm:<phone>`, `discord:dm:<user_id>`,
    `discord:thread:<guild_id>:<channel_id>`, `x:dm:<user_id>`).

    `PUT` is the write the customer's own application makes when it learns
    something about this identifier — a payment cleared, a plan lapsed, an
    abuse report — one idempotent call, keyed by an identifier it already has.
    No read first, no 404 for someone who has never written: the address is
    created here if it does not exist yet. Its `action`, when set, beats every
    route — `action: silence` is how you block
    someone, and `action: null` forgets the exception and defers back to the
    route table.

    `DELETE` is erasure (§3.2): a narrower promise than "erase this human
    everywhere", since without a merge graph naturali does not know that two
    identifiers are the same person.
  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: Channels
    description: Connect and manage a project's messaging surfaces (WhatsApp, Discord, X).
security:
  - bearerAuth: []
  - oauth2:
      - mcp:access
paths:
  /v1/projects/{project_id}/addresses:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      tags: [Channels]
      summary: List addresses
      description: >
        Every identifier this project has seen. An address appears the first
        time a message arrives from it, so this is what naturali has observed
        rather than a roster you maintain — most rows carry no `action` of their
        own and defer to the route table.
      operationId: listAddresses
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of addresses.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Page'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Address'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/projects/{project_id}/addresses/{identifier}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/Identifier'
    get:
      tags: [Channels]
      summary: Get an address
      description: >
        Reads one identifier's own action, if it has one. An identifier naturali
        has never seen is a `404`; to set an action without knowing whether it
        exists, use
        [`PUT /v1/projects/{project_id}/addresses/{identifier}`](/docs/api/addresses/set-address),
        which upserts.
      operationId: getAddress
      responses:
        '200':
          description: The address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags: [Channels]
      summary: Set or clear this address's own action or actor
      description: >
        Upserts the address with its `action`, the actor it speaks as, or both;
        a field left out is left alone. `action: null` forgets the exception and
        defers back to the route table; any other `action` requires the same
        fields a route or channel default would (`agent_id` for `agent`, `text`
        for `message`).


        `actor_id` binds an actor of this project, so the address speaks as the
        same actor your own sessions use. A changed actor deletes the address's
        conversations and their sessions — a session's actor is fixed — and the
        next message opens a fresh one; the actor naturali created for the
        address is deleted with them. An actor you bind is never deleted here.


        An identifier no channel kind produces is `400`.
      operationId: setAddress
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressActionSet'
      responses:
        '200':
          description: Action updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        '201':
          description: Address created with this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: >
            `ACTOR_MINTED_FOR_ADDRESS`: `actor_id` names the actor naturali
            created for another address, which erasing that address would
            delete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [Channels]
      summary: Erase an address
      description: >
        Removes the address, its conversations and their sessions, and the
        actor naturali created for it. An actor bound with `actor_id` is yours
        and is kept.
      operationId: deleteAddress
      responses:
        '204':
          description: Address erased.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/projects/{project_id}/addresses/{identifier}/conversations:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/Identifier'
    get:
      tags: [Channels]
      summary: List an address's conversations
      description: >
        Every conversation this address has had, across every channel it has
        ever messaged — an address is project-scoped, not channel-scoped.
      operationId: listAddressConversations
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of conversations.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Page'
                  - properties:
                      data:
                        type: array
                        items:
                          type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
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
    ProjectId:
      name: project_id
      in: path
      required: true
      description: Project public ID (proj_ prefix).
      schema:
        type: string
        example: proj_V1StGXR8Z5jdHi6B
    Identifier:
      name: identifier
      in: path
      required: true
      description: >
        The prefixed, self-describing channel identifier
        (`whatsapp:dm:<phone>`, `discord:dm:<user_id>`,
        `discord:thread:<guild_id>:<channel_id>`, `x:dm:<user_id>`), URL-encoded.
      schema:
        type: string
        example: 'whatsapp:dm:5511999999999'
  responses:
    Unauthorized:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: The request was malformed or failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: >-
        The credential is scoped to a different project, or the caller's role in
        the project does not carry this action.
      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'
  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.
    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`.
    Address:
      allOf:
        - $ref: '#/components/schemas/ChannelAction'
        - type: object
          properties:
            id:
              type: string
              description: "Public address ID."
              example: addr_V1StGXR8Z5jdHi6B
            project_id:
              type: string
              description: "The owning project."
              example: proj_V1StGXR8Z5jdHi6B
            identifier:
              type: string
              description: "The prefixed, self-describing channel identifier."
              example: 'whatsapp:dm:5511999998888'
            display_name:
              type: string
              description: "A human-friendly name, as the channel reported it."
              nullable: true
              example: Ana
            actor_id:
              type: string
              nullable: true
              description: >-
                The actor this address speaks as: the one bound with `actor_id`,
                else one naturali creates when it first needs it (null until then).
              example: actor_V1StGXR8Z5jdHi6B
            created_at:
              type: string
              format: date-time
            updated_at:
              type: string
              format: date-time
          required:
            - id
            - project_id
            - identifier
            - display_name
            - actor_id
            - created_at
            - updated_at
    AddressActionSet:
      type: object
      description: >
        At least one of `action` and `actor_id`. `action` is one of `agent` /
        `oneshot` / `message` / `silence`, or `null` to clear it. `agent_id` is
        required when it is `agent`, `text` when it is `message`; `repeat` is
        only valid alongside `action: message`.
      properties:
        actor_id:
          type: string
          nullable: true
          example: actor_V1StGXR8Z5jdHi6B
          description: >
            An actor of this project for the address to speak as, `404` when
            the project has none by that id. Create it with your own user id as
            its `external_id`: every tool call in the address's sessions carries
            that actor's `actor_id` and `actor_external_id` as tool context, set
            by the runtime and never by the caller, so a tool knows which of
            your users is talking.


            `null` releases a bound actor (kept, not deleted); the next message
            gets an actor naturali creates.
        action:
          type: string
          nullable: true
          enum: [agent, oneshot, message, silence, null]
          example: agent
          description: >
            What an inbound message becomes.


            `agent` is a dialogue: the identity behind the message gets a
            session, and every later message on it continues the same one.
            `oneshot` runs the agent once and keeps nothing — no address, no
            actor, no session, no conversation — so each message is answered on
            its own. Choose it for work that is filed rather than discussed;
            choose `agent` when the answer depends on what came before.


            `message` delivers fixed text without running an agent, and
            `silence` answers nothing.
        agent_id:
          type: string
          example: agent_V1StGXR8Z5jdHi6B
        text:
          type: string
          example: 'Subscribe at https://example.com/pricing'
        repeat:
          oneOf:
            - type: string
              enum: [every, once]
            - type: object
              required: [after_seconds]
              properties:
                after_seconds:
                  type: integer
                  minimum: 1
          example: every
        language:
          type: string
          example: en-US
        config:
          type: object
          additionalProperties: true
          description: >
            Conversation config bag — media handling, persona overrides, the
            Discord allowlist, and how a `oneshot` answers.


            `discord.reply` picks the delivery: `react` (the default) adds
            `discord.reaction` — `\u2705` unless named — to the message that
            triggered the run, `mention` answers beside it addressing whoever
            asked, `react_or_mention` reacts when the agent writes nothing and
            answers like `mention` when it writes a line, `thread` opens a
            thread and answers inside it, and `none` delivers nothing at all.
            A run that fails delivers nothing in every mode, so a reaction
            always means the work was done; there is no failure marker.


            A mention with nothing else in it is ignored unless the action
            says otherwise, for any action. `discord.use_replied_message:
            true` takes the text of the message it replies to, so replying to
            a message with only the mention files that message.
            `discord.empty_mention_text` answers any other bare mention with
            that fixed text, addressing the sender, without running the agent.


            `discord.forward_user_id: true` hands the sender's Discord user id
            to the agent's tools as the `discord_user_id` tool context, which
            a tool's `headers` read as `{{context:discord_user_id}}`. It is
            the id Discord reported for the message's author, never text the
            model wrote, so a tool can act for whoever sent it. Off unless
            set, because tool context reaches every tool the agent has.


            Read only for `oneshot`. A conversational `agent` in a guild *is*
            its thread — that is what its session is keyed on — so it always
            opens one.
        display_name:
          type: string
          description: Set only when the address is created by this call.
          example: Ana
    ChannelAction:
      type: object
      description: >
        What an inbound message resolves to — a channel's `default`, a route,
        or an address's own action, one shape on all three. For a Discord
        channel, `config.discord.allowed_role_ids` / `allowed_user_ids`
        restrict who may invoke the agent in a server — either list admits,
        empty or absent lists mean everyone, decided before the agent is
        invoked so an unlisted member costs nothing.
      properties:
        action:
          type: string
          nullable: true
          enum: [agent, oneshot, message, silence, null]
          example: agent
          description: >
            What an inbound message becomes; `null` only on an address with no
            action of its own, which the route table then decides.


            `agent` is a dialogue: the identity behind the message gets a
            session, and every later message on it continues the same one.
            `oneshot` runs the agent once and keeps nothing — no address, no
            actor, no session, no conversation — so each message is answered on
            its own. Choose it for work that is filed rather than discussed;
            choose `agent` when the answer depends on what came before.


            `message` delivers fixed text without running an agent, and
            `silence` answers nothing.
        agent_id:
          type: string
          nullable: true
          description: The agent that answers, when `action` is `agent` or `oneshot`.
          example: agent_V1StGXR8Z5jdHi6B
        text:
          type: string
          nullable: true
          description: The fixed text delivered, when `action` is `message`.
          example: 'Subscribe at https://example.com/pricing'
        repeat:
          description: >
            How often a `message` fires: `every` (default), `once`, or
            `{ after_seconds }`. Null unless `action` is `message`.
          oneOf:
            - type: string
              enum: [every, once]
            - type: object
              nullable: true
              required: [after_seconds]
              properties:
                after_seconds:
                  type: integer
                  minimum: 1
          example: every
        language:
          type: string
          nullable: true
          description: Preferred reply language; null lets the agent decide.
          example: en-US
        config:
          type: object
          nullable: true
          additionalProperties: true
          description: >
            Conversation config bag — media handling, persona overrides, the
            Discord allowlist, and how a `oneshot` answers.


            `discord.reply` picks the delivery: `react` (the default) adds
            `discord.reaction` — `\u2705` unless named — to the message that
            triggered the run, `mention` answers beside it addressing whoever
            asked, `react_or_mention` reacts when the agent writes nothing and
            answers like `mention` when it writes a line, `thread` opens a
            thread and answers inside it, and `none` delivers nothing at all.
            A run that fails delivers nothing in every mode, so a reaction
            always means the work was done; there is no failure marker.


            A mention with nothing else in it is ignored unless the action
            says otherwise, for any action. `discord.use_replied_message:
            true` takes the text of the message it replies to, so replying to
            a message with only the mention files that message.
            `discord.empty_mention_text` answers any other bare mention with
            that fixed text, addressing the sender, without running the agent.


            `discord.forward_user_id: true` hands the sender's Discord user id
            to the agent's tools as the `discord_user_id` tool context, which
            a tool's `headers` read as `{{context:discord_user_id}}`. It is
            the id Discord reported for the message's author, never text the
            model wrote, so a tool can act for whoever sent it. Off unless
            set, because tool context reaches every tool the agent has.


            Read only for `oneshot`. A conversational `agent` in a guild *is*
            its thread — that is what its session is keyed on — so it always
            opens one.
          example:
            media:
              audio: transcribe
            discord:
              allowed_role_ids: ['1290000000000000042']
      required:
        - action
        - agent_id
        - text
        - repeat
        - language
        - config
