# ARD Discovery

5 operations on the Logion v1 API.

- [Browse catalog entries](#browse-catalog-entries) — `GET /v1/ard/agents`
- [ARD registry introspection](#ard-registry-introspection) — `POST /v1/ard/explore`
- [ARD semantic search](#ard-semantic-search) — `POST /v1/ard/search`
- [Record a pinned source snapshot](#record-a-pinned-source-snapshot) — `POST /v1/ard/sources`
- [Source snapshot status](#source-snapshot-status) — `GET /v1/ard/sources/status`

## Browse catalog entries

```http
GET /v1/ard/agents
```

Deterministic, cacheable listing of catalog entries.

Gated on the ``ard.discovery`` feature flag.  Uses strict database
filtering without relevance-based sorting.

Operation id: `list_agents`

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `filter` | query | string, optional | no |
| `orderBy` | query | string, optional | no |
| `pageSize` | query | integer | no |
| `pageToken` | query | string, optional | no |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Successful list | `ListAgentsResponse` |
| `403` | ARD discovery is disabled | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

Returns `ListAgentsResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `items` | AgentListItem[] | no |  |
| `pageToken` | string, optional | no |  |
| `total` | integer, optional | no |  |

## ARD registry introspection

```http
POST /v1/ard/explore
```

Aggregate statistical facets over the matched search space.

Gated on the ``ard.discovery`` feature flag.

Operation id: `explore`

**Request body**

Body `ExploreRequest`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `query` | object, optional | no |  |
| `resultType` | object | yes |  |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Successful explore | `ExploreResponse` |
| `400` | Invalid request | `ARDError` |
| `403` | ARD discovery is disabled | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |
| `501` | Not implemented | `ARDError` |

Returns `ExploreResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `facets` | object | no |  |
| `resultType` | string | no | default `"facets"` |

## ARD semantic search

```http
POST /v1/ard/search
```

Search the registry for matching catalog entries.

Gated on the ``ard.discovery`` feature flag.  Returns catalog
entries ranked by relevance score with an ETag for caching.

Operation id: `search`

**Request body**

Body `SearchRequest`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `federation` | string | no | default `"auto"` |
| `pageSize` | integer | no | default `10`; min 1.0; max 100.0 |
| `pageToken` | string, optional | no |  |
| `query` | SearchQueryModel | yes |  |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Successful search | `SearchResponse` |
| `400` | Invalid request | `ARDError` |
| `403` | ARD discovery is disabled | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

Returns `SearchResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `pageToken` | string, optional | no |  |
| `referrals` | RegistryReferral[] | no |  |
| `results` | SearchResultItem[] | no |  |

## Record a pinned source snapshot

```http
POST /v1/ard/sources
```

Pin one fetched snapshot of a connector source.

Gated on the ``ard.connectors_sync`` feature flag.

Operation id: `record_source_snapshot`

Takes an [`Authorization`](/docs/api/overview#authentication) header.

**Request body**

Body `RecordSourceSnapshotRequest`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `commit_sha` | string, optional | no |  |
| `file_digest` | string, optional | no |  |
| `last_good` | boolean | no | default `false` |
| `schema_version` | string, optional | no |  |
| `source_type` | string | yes | max length 32 |
| `source_uri` | string | yes |  |
| `upstream_repo` | string, optional | no |  |
| `validation_result` | string | no | default `"pending"`; max length 32 |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `201` | Snapshot recorded | `RecordSourceSnapshotResponse` |
| `401` | Unauthorized | `ErrorResponse` |
| `403` | ARD connectors sync is disabled | `ErrorResponse` |
| `422` | Unknown validation_result | `ErrorResponse` |

Returns `RecordSourceSnapshotResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `commit_sha` | string, optional | no |  |
| `file_digest` | string, optional | no |  |
| `id` | string(uuid) | yes |  |
| `last_good` | boolean | yes |  |
| `source_type` | string | yes |  |
| `source_uri` | string | yes |  |
| `validation_result` | string | yes |  |

## Source snapshot status

```http
GET /v1/ard/sources/status
```

List source snapshot metadata without leaking secrets.

Gated on the ``ard.connectors_sync`` feature flag.  Returns
public-safe fields only — no credentials, tokens, or raw secrets.

Operation id: `get_source_status`

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `source_type` | query | string, optional | no |
| `limit` | query | integer | no |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Source snapshot status | `GetSourceStatusResponse` |
| `403` | ARD connectors sync is disabled | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

Returns `GetSourceStatusResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `items` | SourceSnapshotStatus[] | no |  |
| `total` | integer, optional | no |  |