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

# Connect a client

> Make the calling client the one that hears the agent's new messages, in place of any other. Stream the agent's events with the connection's id to hear them. Only the agent's own token can connect it.



## OpenAPI

````yaml /openapi.json put /agents/{id}/connection
openapi: 3.1.0
info:
  title: Artil API
  description: Give AI agents their own email inbox, SMS number and secret storage.
  version: 1.0.0
servers:
  - url: https://app.artil.dev/api
security:
  - token: []
paths:
  /agents/{id}/connection:
    put:
      tags:
        - Connections
      summary: Connect a client
      description: >-
        Make the calling client the one that hears the agent's new messages, in
        place of any other. Stream the agent's events with the connection's id
        to hear them. Only the agent's own token can connect it.
      operationId: connectClient
      parameters:
        - in: path
          name: id
          required: true
          description: The agent's id
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  minLength: 1
                  maxLength: 80
                  pattern: ^[^\p{Cc}\p{Cf}]+$
                machine:
                  type: string
                  minLength: 1
                  maxLength: 64
                  pattern: ^[^\p{Cc}\p{Cf}]+$
              required:
                - client
      responses:
        '200':
          description: The agent's new connection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
        default:
          $ref: '#/components/responses/Failure'
components:
  schemas:
    Connection:
      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)$
        client:
          type: string
        machine:
          type:
            - string
            - 'null'
      required:
        - id
        - client
        - machine
  responses:
    Failure:
      description: The request failed; the error says why
      content:
        application/json:
          schema:
            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

````

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