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
    (design: CHANNELS-ROUTING.md §3.1/§3.7). 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>`).

    `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 (CHANNELS-ROUTING.md §3.6) — `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).
security:
  - bearerAuth: []
paths:
  /v1/projects/{project_id}/addresses:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      tags: [Channels]
      summary: List addresses
      operationId: listAddresses
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of addresses.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '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
      operationId: getAddress
      responses:
        '200':
          description: The address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags: [Channels]
      summary: Set or clear this address's own action
      description: >
        Upserts the address and its `action` in one call. `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`).
      operationId: setAddressAction
      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'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags: [Channels]
      summary: Erase an address
      description: >
        Removes the address, its conversations, and its runtime actor and
        sessions.
      operationId: deleteAddress
      responses:
        '204':
          description: Address erased.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '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:
                type: object
                required: [data, next_cursor]
                properties:
                  data:
                    type: array
                    items:
                      type: object
                  next_cursor:
                    type: string
                    nullable: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A naturali API key (nat_sk_…) or a session JWT.
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum items per page — an integer from 1 to 100 (default 20).
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    Cursor:
      name: cursor
      in: query
      required: false
      description: Opaque pagination cursor from a previous response's next_cursor.
      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>`), URL-encoded.
      schema:
        type: string
        example: 'instagram:dm:17841400000000000'
  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'
    NotFound:
      description: The resource does not exist (existence is not leaked).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
              example: bad_request
            message:
              type: string
              example: '`action` is required (`null` clears it, deferring back to the route table).'
            details:
              type: object
              additionalProperties: true
    Address:
      type: object
      properties:
        id:
          type: string
          example: addr_V1StGXR8Z5jdHi6B
        project_id:
          type: string
          example: proj_V1StGXR8Z5jdHi6B
        identifier:
          type: string
          example: 'whatsapp:dm:5511999998888'
        display_name:
          type: string
          nullable: true
          example: Ana
        actor_id:
          type: string
          nullable: true
          description: The runtime actor this address speaks as; null until it has needed one.
          example: actor_V1StGXR8Z5jdHi6B
        action:
          type: string
          nullable: true
          enum: [agent, message, silence, null]
          description: This address's own decision, when it has one — beats every route.
          example: null
        agent_id:
          type: string
          nullable: true
          example: null
        text:
          type: string
          nullable: true
          example: null
        repeat:
          description: Null unless `action` is `message`.
          oneOf:
            - type: string
              enum: [every, once]
            - type: object
              required: [after_seconds]
              properties:
                after_seconds:
                  type: integer
        language:
          type: string
          nullable: true
        config:
          type: object
          nullable: true
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - project_id
        - identifier
        - display_name
        - actor_id
        - action
        - agent_id
        - text
        - repeat
        - language
        - config
        - created_at
        - updated_at
    AddressActionSet:
      type: object
      description: >
        `action` is required — one of `agent` / `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`.
      required:
        - action
      properties:
        action:
          type: string
          nullable: true
          enum: [agent, message, silence, null]
          example: agent
        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: pt-BR
        config:
          type: object
          additionalProperties: true
        display_name:
          type: string
          description: Set only when the address is created by this call.
          example: Ana
    AddressList:
      type: object
      required: [data, next_cursor]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Address'
        next_cursor:
          type: string
          nullable: true
          example: null