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

> ## Agent Instructions
> If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details.

# Create Register

> Register the connected agents of a process over HTTP, for a network that blocks WebSockets. The body is the register frame of the connect protocol. Answers with the registered frame and the instance token the poll and frames endpoints are addressed with, or with a refused frame.



## OpenAPI

````yaml POST /api/v1/agents/connect/register
openapi: 3.1.0
info:
  title: LangWatch API
  version: 1.0.0
  description: LangWatch openapi spec
servers:
  - url: https://app.langwatch.ai
security:
  - project_api_key: []
paths:
  /api/v1/agents/connect/register:
    post:
      tags:
        - Agents
      description: >-
        Register the connected agents of a process over HTTP, for a network that
        blocks WebSockets. The body is the register frame of the connect
        protocol. Answers with the registered frame and the instance token the
        poll and frames endpoints are addressed with, or with a refused frame.
      operationId: registerConnectedAgentInstance
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                protocol:
                  type: number
                  enum:
                    - 1
                type:
                  type: string
                  enum:
                    - register
                sdk:
                  type: object
                  properties:
                    name:
                      type: string
                      minLength: 1
                      maxLength: 64
                    version:
                      type: string
                      minLength: 1
                      maxLength: 64
                    language:
                      type: string
                      minLength: 1
                      maxLength: 32
                  required:
                    - name
                    - version
                    - language
                  additionalProperties: false
                instance:
                  type: object
                  properties:
                    id:
                      type: string
                      minLength: 1
                      maxLength: 128
                    hostname:
                      type: string
                      maxLength: 255
                    username:
                      type: string
                      maxLength: 255
                    pid:
                      type: integer
                      minimum: 0
                    startedAt:
                      type: string
                      maxLength: 64
                    label:
                      type: string
                      maxLength: 128
                    inFlightCallIds:
                      type: array
                      items:
                        type: string
                        maxLength: 128
                      maxItems: 1000
                      default: []
                    maxConcurrency:
                      type: integer
                      exclusiveMinimum: true
                      minimum: 0
                      maximum: 1000
                  required:
                    - id
                    - hostname
                    - username
                    - pid
                    - startedAt
                  additionalProperties: false
                agents:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        minLength: 1
                        maxLength: 255
                      environment:
                        type: string
                        minLength: 1
                        maxLength: 64
                      description:
                        type: string
                        maxLength: 2000
                      parameters:
                        type: object
                        additionalProperties: {}
                        default: {}
                      concurrency:
                        type: integer
                        exclusiveMinimum: true
                        minimum: 0
                        maximum: 1000
                      timeoutMs:
                        type: integer
                        exclusiveMinimum: true
                        minimum: 0
                      sticky:
                        type: boolean
                    required:
                      - name
                      - environment
                    additionalProperties: false
                  minItems: 1
                  maxItems: 100
              required:
                - protocol
                - type
                - sdk
                - instance
                - agents
              additionalProperties: false
      responses:
        '200':
          description: The instance is registered
          content:
            application/json:
              schema:
                type: object
                properties:
                  frame:
                    anyOf:
                      - type: object
                        properties:
                          protocol:
                            type: number
                            const: 1
                          type:
                            type: string
                            const: registered
                          agents:
                            type: array
                            items:
                              type: object
                              properties:
                                name:
                                  type: string
                                environment:
                                  type: string
                                id:
                                  type: string
                                url:
                                  type: string
                                parameterNotes:
                                  type: array
                                  items:
                                    type: string
                              required:
                                - name
                                - environment
                                - id
                                - url
                                - parameterNotes
                          heartbeatIntervalMs:
                            type: integer
                            exclusiveMinimum: 0
                          instanceId:
                            type: string
                        required:
                          - protocol
                          - type
                          - agents
                          - heartbeatIntervalMs
                          - instanceId
                      - type: object
                        properties:
                          protocol:
                            type: number
                            const: 1
                          type:
                            type: string
                            const: refused
                          code:
                            type: string
                            enum:
                              - api_key_invalid
                              - project_required
                              - permission_denied
                              - key_type_not_allowed
                              - replica_count_unsupported
                              - parameters_invalid
                              - environment_invalid
                              - protocol_invalid
                          message:
                            type: string
                          meta:
                            type: object
                            additionalProperties: {}
                        required:
                          - protocol
                          - type
                          - code
                          - message
                    description: >-
                      The registered frame, or the refused frame with its
                      reason.
                  instanceToken:
                    type: string
                    description: >-
                      The token the poll and frames endpoints are addressed
                      with, in the X-Agent-Instance-Token header. Present when
                      the register was accepted.
                required:
                  - frame
        '401':
          description: 'The API key is not valid: a refused frame'
        '403':
          description: >-
            The key type or its permissions cannot connect an agent: a refused
            frame
        '422':
          description: >-
            The body is not a register frame, or an agent of it is not valid: a
            refused frame
        '503':
          description: 'The deployment runs several replicas without Redis: a refused frame'
      security:
        - project_api_key: []
components:
  securitySchemes:
    project_api_key:
      type: apiKey
      in: header
      name: X-Auth-Token
      description: >-
        Project API key for sending traces and accessing project-scoped
        resources. Format: sk-lw-... (no underscore). Obtain one by creating a
        project via the Admin API or the LangWatch UI.

````