> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artil.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Read an address

> Read one of an agent's addresses, with whether carriers are still registering its phone number.



## OpenAPI

````yaml /openapi.json get /agents/{id}/addresses/{addressId}
openapi: 3.1.0
info:
  title: Artil API
  description: >-
    Give AI agents their own email inbox, SMS number and secret storage.


    Artil adds to the API without notice: new endpoints, fields, values and
    error codes, which clients skip when they do not know them. Fields this
    reference lists stay. An endpoint is marked deprecated here before it is
    removed, and while deprecated it answers with a Deprecation header, plus a
    Sunset header once its removal date is set.
  version: 1.0.0
servers:
  - url: https://app.artil.ai/api
security:
  - token: []
  - oauth:
      - agent
paths:
  /agents/{id}/addresses/{addressId}:
    get:
      tags:
        - Addresses
      summary: Read an address
      description: >-
        Read one of an agent's addresses, with whether carriers are still
        registering its phone number.
      operationId: readAddress
      parameters:
        - in: path
          name: id
          required: true
          description: The agent's id
          schema:
            type: string
            format: uuid
        - schema:
            type: string
          in: path
          name: addressId
          required: true
      responses:
        '200':
          description: The address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        4XX:
          description: The request failed; the error says why
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: The request failed; the error says why
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Address:
      type: object
      properties:
        id:
          type: string
          format: uuid
          pattern: >-
            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        channel:
          type: string
          enum:
            - email
            - sms
            - telegram
        value:
          type: string
          description: The email address, phone number or Telegram bot's @username
        domainId:
          anyOf:
            - type: string
              format: uuid
              pattern: >-
                ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
            - type: 'null'
          description: The workspace's own domain the address is on
        primary:
          type: boolean
          description: Whether new messages on its channel go out from it
        registering:
          description: >-
            Whether US carriers are still registering the phone number, which
            sends nothing until they have
          type: boolean
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - channel
        - value
        - domainId
        - primary
        - createdAt
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - invalid_input
                - unauthorized
                - forbidden
                - plan_limit
                - not_found
                - conflict
                - rate_limited
                - internal
                - unavailable
            message:
              type: string
          required:
            - code
            - message
      required:
        - error
  securitySchemes:
    token:
      type: http
      scheme: bearer
    oauth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://mcp.artil.ai/oauth/authorize
          tokenUrl: https://mcp.artil.ai/oauth/token
          scopes:
            agent: Act as the agent chosen at sign-in

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.