<!-- source: https://secondlayer.tools/docs/api-reference#v1-discovery-object -->

## The API discovery object

The public read surfaces and how to page them.

| Field | Type | Description |
| --- | --- | --- |
| `surfaces` | array of object | Each surface's `name`, base `path`, a one-line `description`, and its `auth` rule. |
| `openapi` | string | Path of this OpenAPI document. |
| `envelope_examples` | object | An illustrative cursor-paginated list envelope. |
| `cursor_format` | string | Index and Streams cursor format. |

```json
{
  "surfaces": [
    {
      "name": "index",
      "path": "/v1/index",
      "description": "Decoded chain events via /v1/index/events?event_type=… (stx/ft/nft transfers, mints, burns, stacking locks, and contract prints), with typed ft-transfers/nft-transfers aliases.",
      "auth": "open on this instance"
    },
    {
      "name": "streams",
      "path": "/v1/streams",
      "description": "Raw, ordered, cursor-paginated firehose with reorg awareness.",
      "auth": "open on this instance"
    },
    {
      "name": "subgraphs",
      "path": "/v1/subgraphs",
      "description": "Custom indexed views. Unique local name. Cursor envelope: { rows, next_cursor, tip }.",
      "auth": "open on this instance"
    },
    {
      "name": "proofs",
      "path": "/v1/proofs",
      "description": "Chain proofs to check Index rows without trusting this API: state witnesses, signed blocks, MARF proofs, burn-block preimages, Bitcoin headers. Proxied unchanged from the node and its proof sidecar. Never metered.",
      "auth": "open on this instance"
    },
    {
      "name": "instance",
      "path": "/v1/instance",
      "description": "Local catalog: instance status, subgraphs, webhooks, and default features. No signup or pricing.",
      "auth": "open on this instance"
    }
  ],
  "openapi": "/v1/openapi.json",
  "envelope_examples": {
    "cursor_paginated": {
      "events": [
        "..."
      ],
      "next_cursor": "7960000:42",
      "tip": {
        "block_height": 7978686,
        "lag_seconds": 12
      },
      "reorgs": [
        {
          "detected_at": "2026-05-16T00:00:00Z",
          "new_canonical_tip": "7960000:42",
          "new_canonical_height": 7960000,
          "new_canonical_event_index": 42
        }
      ]
    }
  },
  "cursor_format": "<block_height>:<event_index> (opaque resume token)"
}
```