openapi: 3.0.3
info:
  title: naturali.ai — Channel Routes API
  version: 1.0.0
  description: >
    The route table: `(surface, conditions) → action`. A route belongs to one channel and
    optionally narrows to one of its adapter-declared surfaces
    (`GET /v1/channel-kinds`); its `match` bag is a set of predicates, ANDed,
    drawn from that same registry.

    On every inbound, after the address's own action (if it has one) and
    before the channel's default, the resolver loads a channel's active
    routes, discards those whose `surface` disagrees and whose `match` does
    not fully evaluate true, and takes the most specific survivor: highest
    count of matched predicates, then `surface` set before `surface` null,
    then highest `priority`, then oldest `created_at`.

    Two active routes may not claim the identical `(surface, match)` cell —
    `409 ROUTE_CONFLICT` at write time.
  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}/channels/{channel_id}/routes:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ChannelId'
    get:
      tags: [Channels]
      summary: List a channel's routes
      description: >
        One channel's routes, newest first, `disabled` ones included — only
        `active` routes take part in resolution. For every route in the project
        in one read, use
        [`GET /v1/projects/{project_id}/channel-routes`](/docs/api/channel-routes/list-project-channel-routes).
      operationId: listChannelRoutes
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of routes.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Page'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/ChannelRoute'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags: [Channels]
      summary: Create a route
      description: >
        `action` is required; `agent_id` is required when it is `agent`,
        `text` when it is `message`; `repeat` is only valid alongside
        `action: message`. `surface`, when present, must be one this
        channel's kind serves (`GET /v1/channel-kinds`) — otherwise
        `400 UNKNOWN_SURFACE`. `match` keys must be predicates that kind's
        registry declares — otherwise `400 UNKNOWN_PREDICATE`. Writing a
        route for a surface whose transport mode is off (e.g. a Discord
        `guild_thread` route before `mention_threads` is enabled) still
        succeeds, with `unreachable_surface` in the response `warnings`.
      operationId: createChannelRoute
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChannelRouteWrite'
      responses:
        '201':
          description: Route created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelRoute'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
  /v1/projects/{project_id}/channels/{channel_id}/routes/{route_id}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ChannelId'
      - $ref: '#/components/parameters/RouteId'
    get:
      tags: [Channels]
      summary: Get a route
      description: >
        A route id is only meaningful inside its own channel: the same id under
        another `channel_id` is a `404`. A conversation's `route_id` may instead
        be one of the two sentinels for the address's own action and the channel
        default — those name no route and are not readable here.
      operationId: getChannelRoute
      responses:
        '200':
          description: The route.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelRoute'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags: [Channels]
      summary: Replace a route
      description: >
        Full replace, the same validation as create: an omitted field takes
        its create default. Where that default would widen a value the route
        sets, omission is `400 REPLACE_OMITS_FIELDS`, naming the fields in
        `meta.fields`, and nothing is written: a set `surface` (the default
        is any surface), a non-empty `match` (every message), a non-empty
        `config` (it carries the Discord allowlist), and `status` on a
        `disabled` route (the default re-activates it). Send the value to keep
        it, or `"surface": null`, `"match": {}`, `"config": null`,
        `"status": "active"` to clear it.
      operationId: replaceChannelRoute
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChannelRouteWrite'
      responses:
        '200':
          description: Route replaced.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelRoute'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
    delete:
      tags: [Channels]
      summary: Delete a route
      description: >
        Conversations opened under this route keep its id and stay where they
        are; the next inbound resolves to the next most specific route, or the
        channel default, and opens a new conversation there. To stop a route
        from matching while keeping it readable, `PATCH` it to
        `status: disabled` instead.
      operationId: deleteChannelRoute
      responses:
        '204':
          description: Route deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/projects/{project_id}/channel-routes:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      tags: [Channels]
      summary: Read the whole route table
      description: >
        Every route across every channel in the project, one read — the table
        is small by construction, so this is
        unpaginated.
      operationId: listProjectChannelRoutes
      responses:
        '200':
          description: Every route in the project.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ChannelRoute'
        '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
    ChannelId:
      name: channel_id
      in: path
      required: true
      description: Channel public ID (chan_ prefix).
      schema:
        type: string
        example: chan_V1StGXR8Z5jdHi6B
    RouteId:
      name: route_id
      in: path
      required: true
      description: Route public ID (route_ prefix).
      schema:
        type: string
        example: route_V1StGXR8Z5jdHi6B
  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'
    Conflict:
      description: The request conflicts with the resource's current state.
      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`.
    ChannelRoute:
      allOf:
        - $ref: '#/components/schemas/ChannelAction'
        - type: object
          properties:
            id:
              type: string
              description: "Public route ID."
              example: route_V1StGXR8Z5jdHi6B
            project_id:
              type: string
              description: "The owning project."
              example: proj_V1StGXR8Z5jdHi6B
            channel_id:
              type: string
              description: "The channel this route belongs to."
              example: chan_V1StGXR8Z5jdHi6B
            surface:
              type: string
              nullable: true
              description: The surface this route matches, or null for "any" (`GET /v1/channel-kinds`).
              example: guild_thread
            match:
              type: object
              additionalProperties: true
              description: The predicate bag, ANDed. `{}` matches every message on this surface.
              example:
                guild_id: '9988776655'
            priority:
              type: integer
              description: Tiebreak only, after specificity and `surface`.
              example: 0
            status:
              type: string
              enum: [active, disabled]
              example: active
            created_at:
              type: string
              format: date-time
            updated_at:
              type: string
              format: date-time
            warnings:
              type: array
              description: >
                On a create or update response only, and only when non-empty.
                `unreachable_surface`: the channel's transport mode does not
                deliver this surface yet.
              items:
                type: string
                enum: [unreachable_surface]
          required:
            - id
            - project_id
            - channel_id
            - surface
            - match
            - priority
            - status
            - created_at
            - updated_at
    ChannelRouteWrite:
      type: object
      required: [action]
      properties:
        surface:
          type: string
          nullable: true
          example: guild_thread
        match:
          type: object
          additionalProperties: true
          example:
            guild_id: '9988776655'
        priority:
          type: integer
          default: 0
        action:
          type: string
          enum: [agent, oneshot, message, silence]
          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
          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.
        status:
          type: string
          enum: [active, disabled]
          default: active
    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
