> ## 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

> Returns a registered frame and instance token, or refuses at the status of the reason.



## OpenAPI

````yaml POST /api/v1/agents/connect/register
openapi: 3.1.0
info:
  title: LangWatch API
  description: LangWatch openapi spec
  version: 1.0.0
servers:
  - url: https://app.langwatch.ai
security:
  - project_api_key: []
paths:
  /api/v1/agents/connect/register:
    post:
      summary: Register this process's agents
      description: >-
        Returns a registered frame and instance token, or refuses at the status
        of the reason.
      operationId: registerConnectedAgentInstance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                protocol:
                  type: number
                  const: 1
                type:
                  type: string
                  const: 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
                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
                      maximum: 9007199254740991
                    startedAt:
                      type: string
                      maxLength: 64
                    label:
                      type: string
                      maxLength: 128
                    inFlightCallIds:
                      default: []
                      maxItems: 1000
                      type: array
                      items:
                        type: string
                        maxLength: 128
                    maxConcurrency:
                      type: integer
                      exclusiveMinimum: 0
                      maximum: 1000
                  required:
                    - id
                    - hostname
                    - username
                    - pid
                    - startedAt
                agents:
                  minItems: 1
                  maxItems: 100
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        minLength: 1
                        maxLength: 255
                      environment:
                        type: string
                        minLength: 1
                        maxLength: 64
                      parameters:
                        default: {}
                        type: object
                        propertyNames:
                          type: string
                        additionalProperties: {}
                      concurrency:
                        type: integer
                        exclusiveMinimum: 0
                        maximum: 1000
                      timeoutMs:
                        type: integer
                        exclusiveMinimum: 0
                        maximum: 9007199254740991
                      sticky:
                        type: boolean
                      hooks:
                        type: object
                        properties:
                          setup:
                            type: boolean
                          teardown:
                            type: boolean
                        required:
                          - setup
                          - teardown
                    required:
                      - name
                      - environment
              required:
                - protocol
                - type
                - sdk
                - instance
                - agents
      responses:
        '200':
          description: Success
          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
                                scope:
                                  oneOf:
                                    - type: object
                                      properties:
                                        kind:
                                          type: string
                                          const: shared
                                      required:
                                        - kind
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        kind:
                                          type: string
                                          const: owner
                                      required:
                                        - kind
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        kind:
                                          type: string
                                          const: host
                                        hostLabel:
                                          type: string
                                      required:
                                        - kind
                                        - hostLabel
                                      additionalProperties: false
                              required:
                                - name
                                - environment
                                - id
                                - url
                                - parameterNotes
                                - scope
                              additionalProperties: false
                          heartbeatIntervalMs:
                            type: integer
                            exclusiveMinimum: 0
                            maximum: 9007199254740991
                          instanceId:
                            type: string
                        required:
                          - protocol
                          - type
                          - agents
                          - heartbeatIntervalMs
                          - instanceId
                        additionalProperties: false
                      - 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
                            propertyNames:
                              type: string
                            additionalProperties: {}
                        required:
                          - protocol
                          - type
                          - code
                          - message
                        additionalProperties: false
                  instanceToken:
                    type: string
                required:
                  - frame
                additionalProperties: false
      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.

````

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