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

# List one registry agent's versions

The change events recorded for the agent, oldest first, one page at a time. Each carries `from_version`, `to_version` and the entry as it stood at `to_version`. Pass `next_cursor` back as `cursor` for the next page; it is null on the last page.

> Page: https://langwatch.ai/docs/api-reference/governance-agent-registry/list-one-registry-agent-s-versions
> Source: https://github.com/langwatch/langwatch/blob/main/docs/api-reference/governance-agent-registry/list-one-registry-agent-s-versions.mdx
> Index of all pages: https://langwatch.ai/docs/llms.txt

## Endpoint

`GET https://app.langwatch.ai/api/v1/governance/registry/agents/{agentId}/versions`

## Authentication

### admin_api_key

Admin API key for organization-level operations (managing projects, API keys). Create one in Settings > API Keys or via POST /api/api-keys. Format: sk-lw-{id}_{secret}.

```json
{"id":"admin_api_key","type":"http","scheme":"bearer"}
```

## Parameters

### agentId (path, required)

```json
{"type":"string","minLength":1}
```

### limit (query, optional)

```json
{"default":100,"type":"integer","minimum":1,"maximum":200}
```

### cursor (query, optional)

```json
{"type":"string"}
```

## Request example

```bash
curl --request GET \
  --url 'https://app.langwatch.ai/api/v1/governance/registry/agents/<agentId>/versions' \
  --header "Authorization: Bearer $LANGWATCH_API_KEY"
```

## Responses

### 200

Success

#### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {"type":"string"},
          "sequence": {"type":"string"},
          "type": {
            "type": "string",
            "enum": [
              "governance.agent.registered",
              "governance.agent.versioned",
              "governance.agent.removed",
              "governance.agent.tool_deprecated",
              "governance.agent.flagged_shadow"
            ]
          },
          "organization_id": {"type":"string"},
          "agent_id": {"type":"string"},
          "from_version": {
            "anyOf": [
              {"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},
              {"type":"null"}
            ]
          },
          "to_version": {
            "anyOf": [
              {"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},
              {"type":"null"}
            ]
          },
          "tool": {"type":["string","null"]},
          "occurred_at": {"type":"string"},
          "agent": {
            "type": "object",
            "properties": {
              "id": {"type":"string"},
              "source": {
                "type": "string",
                "enum": ["langwatch","databricks","copilot_studio","traffic"]
              },
              "management": {"type":"string","enum":["managed","discovered","observed"]},
              "kind": {"type":"string"},
              "name": {"type":"string"},
              "description": {"type":["string","null"]},
              "status": {"type":"string","enum":["active","removed"]},
              "shadow": {"type":"boolean"},
              "version": {"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},
              "source_version": {"type":["string","null"]},
              "project_id": {"type":["string","null"]},
              "environment": {"type":["string","null"]},
              "owner": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "user_id": {"type":"string"},
                      "name": {"type":["string","null"]}
                    },
                    "required": ["user_id","name"],
                    "additionalProperties": false
                  },
                  {"type":"null"}
                ]
              },
              "endpoints": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "kind": {"type":"string","enum":["invoke","definition","console"]},
                    "url": {"type":"string"},
                    "protocol": {"type":"string"}
                  },
                  "required": ["kind","url","protocol"],
                  "additionalProperties": false
                }
              },
              "model": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "provider": {"type":["string","null"]},
                      "model": {"type":"string"},
                      "parameters": {
                        "type": "object",
                        "propertyNames": {"type":"string"},
                        "additionalProperties": {"type":["string","number","boolean"]}
                      }
                    },
                    "required": ["provider","model","parameters"],
                    "additionalProperties": false
                  },
                  {"type":"null"}
                ]
              },
              "instructions": {"type":["string","null"]},
              "capabilities": {"type":"array","items":{"type":"string"}},
              "tools": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {"type":"string"},
                    "description": {"type":["string","null"]},
                    "input_schema": {
                      "type": "object",
                      "propertyNames": {"type":"string"},
                      "additionalProperties": {}
                    },
                    "output_schema": {
                      "anyOf": [
                        {
                          "type": "object",
                          "propertyNames": {"type":"string"},
                          "additionalProperties": {}
                        },
                        {"type":"null"}
                      ]
                    },
                    "status": {"type":"string","enum":["active","deprecated"]},
                    "deprecated_in_version": {
                      "anyOf": [
                        {
                          "type": "integer",
                          "exclusiveMinimum": 0,
                          "maximum": 9007199254740991
                        },
                        {"type":"null"}
                      ]
                    },
                    "deprecated_at": {"type":["string","null"]}
                  },
                  "required": [
                    "name",
                    "description",
                    "input_schema",
                    "output_schema",
                    "status",
                    "deprecated_in_version",
                    "deprecated_at"
                  ],
                  "additionalProperties": false
                }
              },
              "first_seen_at": {"type":"string"},
              "last_seen_at": {"type":["string","null"]},
              "updated_at": {"type":"string"},
              "removed_at": {"type":["string","null"]}
            },
            "required": [
              "id",
              "source",
              "management",
              "kind",
              "name",
              "description",
              "status",
              "shadow",
              "version",
              "source_version",
              "project_id",
              "environment",
              "owner",
              "endpoints",
              "model",
              "instructions",
              "capabilities",
              "tools",
              "first_seen_at",
              "last_seen_at",
              "updated_at",
              "removed_at"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "id",
          "sequence",
          "type",
          "organization_id",
          "agent_id",
          "from_version",
          "to_version",
          "tool",
          "occurred_at",
          "agent"
        ],
        "additionalProperties": false
      }
    },
    "next_cursor": {"type":["string","null"]}
  },
  "required": ["data","next_cursor"],
  "additionalProperties": false
}
```

### 400

Bad Request

#### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "type": {"type":"string"},
    "code": {"type":"string"},
    "message": {"type":"string"},
    "retryable": {"type":"boolean"},
    "meta": {
      "type": "object",
      "propertyNames": {"type":"string"},
      "additionalProperties": {}
    },
    "trace_id": {"type":"string"},
    "span_id": {"type":"string"},
    "trace": {
      "type": "object",
      "properties": {
        "traceId": {"type":"string"},
        "spanId": {"type":"string"},
        "traceUrl": {"type":"string"},
        "logsUrl": {"type":"string"}
      }
    },
    "tips": {"type":"array","items":{"type":"string"}},
    "docs_url": {"type":"string"},
    "fault": {
      "type": "string",
      "enum": ["customer","platform","provider","presumed_platform"]
    },
    "reasons": {"type":"array","items":{}}
  },
  "required": ["type","code","message","retryable"]
}
```

### 401

Unauthorized

#### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "type": {"type":"string"},
    "code": {"type":"string"},
    "message": {"type":"string"},
    "retryable": {"type":"boolean"},
    "meta": {
      "type": "object",
      "propertyNames": {"type":"string"},
      "additionalProperties": {}
    },
    "trace_id": {"type":"string"},
    "span_id": {"type":"string"},
    "trace": {
      "type": "object",
      "properties": {
        "traceId": {"type":"string"},
        "spanId": {"type":"string"},
        "traceUrl": {"type":"string"},
        "logsUrl": {"type":"string"}
      }
    },
    "tips": {"type":"array","items":{"type":"string"}},
    "docs_url": {"type":"string"},
    "fault": {
      "type": "string",
      "enum": ["customer","platform","provider","presumed_platform"]
    },
    "reasons": {"type":"array","items":{}}
  },
  "required": ["type","code","message","retryable"]
}
```

### 403

Forbidden

#### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "type": {"type":"string"},
    "code": {"type":"string"},
    "message": {"type":"string"},
    "retryable": {"type":"boolean"},
    "meta": {
      "type": "object",
      "propertyNames": {"type":"string"},
      "additionalProperties": {}
    },
    "trace_id": {"type":"string"},
    "span_id": {"type":"string"},
    "trace": {
      "type": "object",
      "properties": {
        "traceId": {"type":"string"},
        "spanId": {"type":"string"},
        "traceUrl": {"type":"string"},
        "logsUrl": {"type":"string"}
      }
    },
    "tips": {"type":"array","items":{"type":"string"}},
    "docs_url": {"type":"string"},
    "fault": {
      "type": "string",
      "enum": ["customer","platform","provider","presumed_platform"]
    },
    "reasons": {"type":"array","items":{}}
  },
  "required": ["type","code","message","retryable"]
}
```

### 404

Not Found

#### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "type": {"type":"string"},
    "code": {"type":"string"},
    "message": {"type":"string"},
    "retryable": {"type":"boolean"},
    "meta": {
      "type": "object",
      "propertyNames": {"type":"string"},
      "additionalProperties": {}
    },
    "trace_id": {"type":"string"},
    "span_id": {"type":"string"},
    "trace": {
      "type": "object",
      "properties": {
        "traceId": {"type":"string"},
        "spanId": {"type":"string"},
        "traceUrl": {"type":"string"},
        "logsUrl": {"type":"string"}
      }
    },
    "tips": {"type":"array","items":{"type":"string"}},
    "docs_url": {"type":"string"},
    "fault": {
      "type": "string",
      "enum": ["customer","platform","provider","presumed_platform"]
    },
    "reasons": {"type":"array","items":{}}
  },
  "required": ["type","code","message","retryable"]
}
```

### 422

Unprocessable Entity

#### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "type": {"type":"string"},
    "code": {"type":"string"},
    "message": {"type":"string"},
    "retryable": {"type":"boolean"},
    "meta": {
      "type": "object",
      "propertyNames": {"type":"string"},
      "additionalProperties": {}
    },
    "trace_id": {"type":"string"},
    "span_id": {"type":"string"},
    "trace": {
      "type": "object",
      "properties": {
        "traceId": {"type":"string"},
        "spanId": {"type":"string"},
        "traceUrl": {"type":"string"},
        "logsUrl": {"type":"string"}
      }
    },
    "tips": {"type":"array","items":{"type":"string"}},
    "docs_url": {"type":"string"},
    "fault": {
      "type": "string",
      "enum": ["customer","platform","provider","presumed_platform"]
    },
    "reasons": {"type":"array","items":{}}
  },
  "required": ["type","code","message","retryable"]
}
```

### 500

Internal Server Error

#### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "type": {"type":"string"},
    "code": {"type":"string"},
    "message": {"type":"string"},
    "retryable": {"type":"boolean"},
    "meta": {
      "type": "object",
      "propertyNames": {"type":"string"},
      "additionalProperties": {}
    },
    "trace_id": {"type":"string"},
    "span_id": {"type":"string"},
    "trace": {
      "type": "object",
      "properties": {
        "traceId": {"type":"string"},
        "spanId": {"type":"string"},
        "traceUrl": {"type":"string"},
        "logsUrl": {"type":"string"}
      }
    },
    "tips": {"type":"array","items":{"type":"string"}},
    "docs_url": {"type":"string"},
    "fault": {
      "type": "string",
      "enum": ["customer","platform","provider","presumed_platform"]
    },
    "reasons": {"type":"array","items":{}}
  },
  "required": ["type","code","message","retryable"]
}
```