---
title: "GET /api/v1"
method: GET
path: "/api/v1"
tags: ["contracts"]
---

# GET /api/v1

`GET /api/v1`

## Request

- Base URL: `https://api.metagraph.sh`
- URL: `https://api.metagraph.sh/api/v1`
- Auth: none required

List backend API routes and response envelope metadata.

## Response `200`

Canonical artifact wrapped in the Metagraphed API envelope.

- object
  - `data` object, required
    - `artifact_contracts` object[], required
      - `content_type` string
      - `contract_version` string, required
      - `description` string
      - `id` string, required
      - `path` string, required
      - `retirement` object, nullable
        - `code` string, required
        - `http_status` integer, required
        - `message` string, required
      - `schema_ref` string, nullable, required
      - `status` 'live' | 'retired', required
      - `storage_tier` 'dual' | 'git' | 'r2', required
    - `base_path` '/api/v1', required
    - `contract_version` string
    - `feeds` object[], required
      - `content_types` string[], required: Parallel to `formats`: a feed is rendered live and emits RSS/Atom/JSON Feed, not a stored artifact in the success envelope, and an agent that treated one like the other would parse XML as JSON.
      - `description` string, required
      - `formats` string[], required
      - `id` string, required
      - `kind` string, required: The FeedTarget kind `parseFeedPath` resolves this path to. The derived contract test matches on this rather than the path string, so a rename cannot silently orphan an entry.
      - `method` 'GET', required
      - `path` string, required
      - `path_parameters` object[], required
        - `description` string
        - `name` string, required
        - `schema` object, required
      - `public` true, required
      - `query_parameters` object[], required
        - `description` string
        - `name` string, required
        - `schema` object, required
    - `generated_at` string, required
    - `networks` object, required: The network dimension (#8698), carried by both machine-readable surfaces -- this contract for MCP agents and the API index for route consumers -- from one builder, so they cannot disagree.
      - `aliases` string[], required
      - `data_aliases` string[], required
      - `default` 'mainnet', required
      - `mainnet_only_route_count` integer, required
      - `note` string, required
      - `path_form` '/api/v1/{network}/...', required
    - `notes` union: Public-safe notes; may be a string or a string list depending on the adapter.
      - string
      - string[]
    - `openapi_url` '/metagraph/openapi.json', required
    - `primary_domain` 'api.metagraph.sh', required
    - `response_envelope` object, required
      - `error_schema_ref` '#/components/schemas/ErrorEnvelope', required
      - `fields` string[], required
      - `notes` string, required
      - `schema_version` 1, required
      - `success_schema_ref` '#/components/schemas/SuccessEnvelope', required
    - `routes` object[], required
      - `artifact_path` string, required
      - `cache` 'short' | 'standard' | 'static', required
      - `description` string, required
      - `id` string, required
      - `mainnet_only` boolean
      - `method` 'GET' | 'POST', required
      - `networks` string[]
      - `path` string, required
      - `public` true, required
      - `query_collection` string, nullable
      - `query_filter_names` string[]
      - `query_parameters` object[], required
        - `description` string
        - `name` string, required
        - `schema` object, required
    - `schema_version` 1, required
    - `type_definitions_url` '/metagraph/types.d.ts', required
  - `meta` ResponseMeta, required
    - `artifact_path` string
    - `cache` 'short' | 'standard' | 'static'
    - `catalog_paging` object
      - `reason` 'catalog_changed' | 'catalog_budget_exceeded' | 'catalog_unavailable', required
    - `contract_version` string, required
    - `generated_at` string, nullable: Deterministic build content marker (epoch by default); not a wall clock. Use published_at for human-facing freshness.
    - `observed_through` string, date-time, nullable: How far the tier that answered this request has observed at all. A payload reporting no activity at or before this time is a measured absence; one whose subject is newer is outside coverage, not empty. Null when the horizon is unreadable.
    - `pagination` PaginationMeta
      - `collection` string, required
      - `cursor` integer, required
      - `limit` integer, required
      - `next_cursor` integer, nullable, required
      - `order` 'asc' | 'desc'
      - `returned` integer, required
      - `snapshot` string: Present only for page_snapshot paging. Echo as page_snapshot on subsequent pages; a changed collection or query requires a restart.
      - `sort` string, nullable
      - `total` integer, required
    - `published_at` string, date-time, nullable: Real publish time from the KV latest pointer, distinct from generated_at. Null before the first publish or when the control KV is unbound.
    - `source` string
    - `stale_contract` object: Present ONLY when the served artifact was built under an older contract than the live one (serve-time drift, #1001) — the body may predate a schema change. Mirrored on the x-metagraph-stale-contract response header for monitoring.
      - `built_under` string, required: Contract version the served artifact was built under.
      - `live` string, required: Current (live) contract version the Worker is running.
  - `ok` true, required
  - `schema_version` 1, required

## Other responses

- `304`: ETag matched and the cached response is still valid.
- `400`: Query parameters were malformed or unsupported.
- `404`: Artifact or API route was not found.
- `405`: HTTP method is not supported.
- `500`: Unexpected backend error.

---

[API](https://skmtc.dev/metagraph/apis/metagraphed-api.md) · [All operations](https://skmtc.dev/metagraph/apis/metagraphed-api/llms.txt) · [OpenAPI document](https://skmtc.dev/metagraph/apis/metagraphed-api/revisions/e29036024bb1?raw)