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

# Search the registry (ARD search)

ARD `POST /search`: `query.text` is matched against names, capabilities, descriptions, instructions and tools; `query.filter` keys are term paths (`tags`, `capabilities`, `data.source`, `data.shadow`), values within a key are OR-ed and keys AND-ed. Results carry a 0 to 100 relevance `score`. Searches the 1,000 active agents changed most recently. Federation is not performed.

> Page: https://langwatch.ai/docs/api-reference/governance-agent-registry/search-the-registry-ard-search
> Source: https://github.com/langwatch/langwatch/blob/main/docs/api-reference/governance-agent-registry/search-the-registry-ard-search.mdx
> Index of all pages: https://langwatch.ai/docs/llms.txt

## Endpoint

`POST https://app.langwatch.ai/api/v1/governance/registry/ard/search`

## 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"}
```

## Request body (required)

#### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "object",
      "properties": {
        "text": {"type":"string","minLength":1},
        "filter": {
          "type": "object",
          "propertyNames": {"type":"string"},
          "additionalProperties": {
            "anyOf": [{"type":"string"},{"type":"array","items":{"type":"string"}}]
          }
        }
      },
      "required": ["text"]
    },
    "federation": {"type":"string","enum":["auto","referrals","none"]},
    "pageSize": {"default":10,"type":"integer","minimum":1,"maximum":100},
    "pageToken": {"type":"string","pattern":"^\\d+$"}
  },
  "required": ["query"]
}
```

## Request example

```bash
curl --request POST \
  --url 'https://app.langwatch.ai/api/v1/governance/registry/ard/search' \
  --header "Authorization: Bearer $LANGWATCH_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"query":{"text":"string","filter":{}},"federation":"auto","pageSize":10,"pageToken":"string"}'
```

## Responses

### 200

Success

#### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "@context": {
            "type": "string",
            "const": "https://agenticresourcediscovery.org/context/v1"
          },
          "identifier": {"type":"string"},
          "displayName": {"type":"string"},
          "type": {"type":"string","const":"application/agent-card+json"},
          "description": {"type":"string"},
          "version": {"type":"string"},
          "updatedAt": {"type":"string"},
          "tags": {"type":"array","items":{"type":"string"}},
          "capabilities": {"type":"array","items":{"type":"string"}},
          "data": {
            "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
          },
          "metadata": {
            "type": "object",
            "propertyNames": {"type":"string"},
            "additionalProperties": {"type":"string"}
          },
          "score": {"type":"number","minimum":0,"maximum":100},
          "source": {"type":"string"}
        },
        "required": [
          "@context",
          "identifier",
          "displayName",
          "type",
          "version",
          "updatedAt",
          "tags",
          "capabilities",
          "data",
          "metadata",
          "score",
          "source"
        ],
        "additionalProperties": false
      }
    },
    "pageToken": {"type":"string"}
  },
  "required": ["results"],
  "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"]
}
```

### 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"]
}
```