<!-- Agent Datasets docs · Platform REST endpoints · canonical: https://www.agentdatasets.com/docs/rest/platform · rendered from https://www.agentdatasets.com -->

# Platform REST endpoints

Catalog and freshness metadata for the Agent Datasets platform.

2 endpoints. Paths are relative to `https://api.agentdatasets.com`. Every endpoint mirrors an MCP tool over the same service layer — https://www.agentdatasets.com/docs/tools.md documents the same operations for MCP clients.

## GET /v1/platform/catalog

Platform Catalog

Return the data catalog: categories, datasets, licensing posture, and tool summaries.

Categories are always returned in full (small fixed list). Datasets are
paginated by ``(category, dataset)`` keyset cursor. Default limit 50, max
100; all current datasets fit on one default page. Pass
``pagination.next_cursor`` as ``cursor`` to advance pages.

Each dataset row carries ``posture`` (``"public"`` or ``"internal"``),
``redistributable`` flag, ``coverage`` description, ``cadence``, live
``freshness`` snapshot, and the MCP ``tools`` that serve it.

``meta.source`` is ``"platform_catalog"`` (public posture) — public-surface
credentials receive 200; individual dataset rows may describe internal
sources but the catalog metadata itself is not restricted.

### Parameters

| Parameter | In | Type | Required | Default | Constraints | Description |
| --- | --- | --- | --- | --- | --- | --- |
| limit | query | `integer` | no | 50 | min 1, max 100 | — |
| cursor | query | `string \| null` | no | — | — | — |

### Example request

Required parameters only, with values taken from the schema.

```bash
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/platform/catalog"
```

### Response

`200` Successful Response — `CatalogResult`.

- `data` `CatalogData` (required) — Top-level data object: always-complete category list + paginated datasets.
  - `categories` `array<CategoryEntry>` (required)
    - `key` `string` (required)
    - `display_name` `string` (required)
    - `status` `"live" | "soon"` (required)
    - `description` `string` (required)
    - `exempt` `boolean` (required)
  - `datasets` `array<DatasetEntry>` (required)
    - `dataset` `string` (required)
    - `display_name` `string` (required)
    - `category` `string` (required)
    - `source_tag` `string` (required)
    - `source_name` `string` (required)
    - `license` `string` (required)
    - `posture` `"public" | "internal"` (required)
    - `redistributable` `boolean` (required)
    - `coverage` `string` (required)
    - `cadence` `string` (required)
    - `freshness` `FreshnessSubobject` (required) — Freshness sub-object reusing the exact vocabulary from DatasetFreshness.
      - `status` `string` (required)
      - `stale` `boolean` (required)
      - `status_reason` `string | null`
      - `last_refresh` `string (date-time) | null`
      - `latest_as_of` `string (date-time) | null`
    - `tools` `array<ToolSummary>` (required)
      - `name` `string` (required)
      - `summary` `string` (required)
- `meta` `Meta` (required) — Result-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
  - `source` `string` (required)
  - `as_of` `string (date-time) | string (date) | null`
- `pagination` `Pagination | null`
  - `limit` `integer` (required)
  - `has_more` `boolean` (required)
  - `next_cursor` `string | null`

Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json

## GET /v1/platform/freshness

Platform Freshness

### Parameters

| Parameter | In | Type | Required | Default | Constraints | Description |
| --- | --- | --- | --- | --- | --- | --- |
| limit | query | `integer` | no | 50 | min 1, max 100 | — |
| cursor | query | `string \| null` | no | — | — | — |

### Example request

Required parameters only, with values taken from the schema.

```bash
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/platform/freshness"
```

### Response

`200` Successful Response — `PlatformFreshnessResult`.

- `data` `PlatformFreshnessData` (required)
  - `datasets` `array<DatasetFreshness>` (required)
    - `dataset` `string` (required)
    - `display_name` `string` (required)
    - `category` `string` (required)
    - `source` `string` (required)
    - `cadence` `string` (required)
    - `status` `"fresh" | "stale" | "never_ran" | "manual" | "live"` (required)
    - `stale` `boolean` (required)
    - `status_reason` `string | null` (required)
    - `last_refresh` `string (date-time) | null` (required)
    - `latest_as_of` `string (date-time) | null` (required)
    - `non_redistributable` `boolean` (required)
    - `tools` `array<string>` (required)
  - `checked_at` `string (date-time)` (required)
- `meta` `Meta` (required) — Result-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
  - `source` `string` (required)
  - `as_of` `string (date-time) | string (date) | null`
- `pagination` `Pagination | null`
  - `limit` `integer` (required)
  - `has_more` `boolean` (required)
  - `next_cursor` `string | null`

Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json