> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ticksupply.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference Overview

> Complete reference for the Ticksupply REST API

# API Reference

The Ticksupply API is organized around REST principles. It uses predictable resource-oriented URLs, accepts JSON request bodies, returns JSON responses, and uses standard HTTP response codes and authentication.

## Base URL

All API requests are made to:

```
https://api.ticksupply.com
```

## API versioning

The API is versioned via URL path. The current version is `v1`:

```
https://api.ticksupply.com/v1/exchanges
```

<Note>
  We maintain backward compatibility within a major version. Breaking changes require a new major version.
</Note>

## Authentication

Authenticate requests by including your API key in the `X-Api-Key` header:

```bash theme={"system"}
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://api.ticksupply.com/v1/exchanges
```

See the [Authentication guide](/getting-started/authentication) for details.

## Resource IDs

Resources use prefixed IDs for easy identification. The format is `{prefix}_{hex}` where the prefix indicates the resource type:

| Prefix | Resource          | Example                                |
| ------ | ----------------- | -------------------------------------- |
| `sub_` | Subscription      | `sub_0194a1b2c3d4e5f6a7b8c9d0e1f2a3b4` |
| `exp_` | Export Job        | `exp_0194a1b2c3d4e5f6a7b8c9d0e1f2a3b4` |
| `art_` | Export Artifact   | `art_0194a1b2c3d4e5f6a7b8c9d0e1f2a3b4` |
| `sch_` | Export Schema     | `sch_0194a1b2c3d4e5f6a7b8c9d0e1f2a3b4` |
| `spn_` | Subscription Span | `spn_0194a1b2c3d4e5f6a7b8c9d0e1f2a3b4` |

<Tip>
  Treat IDs as opaque strings. Store and pass them exactly as returned by the API.
</Tip>

## Request format

### Headers

| Header            | Required | Description                 |
| ----------------- | -------- | --------------------------- |
| `X-Api-Key`       | Yes      | Your API key                |
| `Content-Type`    | For POST | Set to `application/json`   |
| `Idempotency-Key` | Optional | Unique key for safe retries |

### Request body

POST requests accept JSON bodies:

```bash theme={"system"}
curl -X POST -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"datastream_id": 123}' \
  https://api.ticksupply.com/v1/subscriptions
```

## Response format

All responses are JSON with these headers:

| Header          | Description                             |
| --------------- | --------------------------------------- |
| `Content-Type`  | `application/json`                      |
| `X-Request-Id`  | Unique request identifier for debugging |
| `X-RateLimit-*` | Rate limiting information               |

### Success responses

Successful responses return appropriate status codes:

| Code             | Meaning                                               |
| ---------------- | ----------------------------------------------------- |
| `200 OK`         | Request succeeded, body contains result               |
| `201 Created`    | Resource created successfully                         |
| `202 Accepted`   | Request accepted for async processing (e.g., exports) |
| `204 No Content` | Request succeeded, no body                            |

### Error responses

Errors return a structured JSON body:

```json theme={"system"}
{
  "error": {
    "code": "not_found",
    "message": "Subscription not found"
  }
}
```

See the [Error Handling guide](/guides/error-handling) for all error codes.

## Endpoint categories

<CardGroup cols={2}>
  <Card title="Catalog" icon="book" href="/api-reference/catalog/list-exchanges">
    Browse exchanges, instruments, and data stream types
  </Card>

  <Card title="Subscriptions" icon="bell" href="/api-reference/subscriptions/create-subscription">
    Create and manage data subscriptions
  </Card>

  <Card title="Export Schemas" icon="table-columns" href="/api-reference/export-schemas/list-export-schemas">
    Define custom column mappings for exports
  </Card>

  <Card title="Exports" icon="download" href="/api-reference/exports/create-export">
    Export historical data to files
  </Card>

  <Card title="Availability" icon="chart-bar" href="/api-reference/availability/get-data-availability">
    Query data availability
  </Card>
</CardGroup>

## Catalog

Explore available data sources.

| Method | Endpoint                                                        | Description                        |
| ------ | --------------------------------------------------------------- | ---------------------------------- |
| GET    | `/v1/exchanges`                                                 | List all public exchanges          |
| GET    | `/v1/exchanges/{exchange}/instruments`                          | List instruments for an exchange   |
| GET    | `/v1/datastreams`                                               | List datastreams                   |
| GET    | `/v1/exchanges/{exchange}/datastreams`                          | List datastreams for an exchange   |
| GET    | `/v1/exchanges/{exchange}/instruments/{instrument}/datastreams` | List datastreams for an instrument |

## Subscriptions

Manage your data subscriptions.

| Method | Endpoint                        | Description               |
| ------ | ------------------------------- | ------------------------- |
| POST   | `/v1/subscriptions`             | Create a subscription     |
| GET    | `/v1/subscriptions`             | List all subscriptions    |
| GET    | `/v1/subscriptions/{id}`        | Get subscription details  |
| DELETE | `/v1/subscriptions/{id}`        | Delete a subscription     |
| POST   | `/v1/subscriptions/{id}/pause`  | Pause data collection     |
| POST   | `/v1/subscriptions/{id}/resume` | Resume data collection    |
| GET    | `/v1/subscriptions/{id}/spans`  | Get collection time spans |

## Export Schemas

Define custom column mappings for exports.

| Method | Endpoint                  | Description             |
| ------ | ------------------------- | ----------------------- |
| GET    | `/v1/export-schemas`      | List all export schemas |
| POST   | `/v1/export-schemas`      | Create a custom schema  |
| GET    | `/v1/export-schemas/{id}` | Get schema details      |
| DELETE | `/v1/export-schemas/{id}` | Delete a custom schema  |

## Exports

Create and download data exports.

| Method | Endpoint                    | Description                    |
| ------ | --------------------------- | ------------------------------ |
| POST   | `/v1/exports`               | Create an export job           |
| GET    | `/v1/exports`               | List all exports               |
| GET    | `/v1/exports/{id}`          | Get export details             |
| DELETE | `/v1/exports/{id}`          | Delete an export               |
| POST   | `/v1/exports/{id}/cancel`   | Cancel a queued/running export |
| GET    | `/v1/exports/{id}/download` | Get download URLs              |

## Availability

Query data coverage.

| Method | Endpoint           | Description           |
| ------ | ------------------ | --------------------- |
| GET    | `/v1/availability` | Get data availability |

## Common patterns

### Pagination

List endpoints support cursor-based pagination:

```bash theme={"system"}
# First page
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.ticksupply.com/v1/subscriptions?limit=20"

# Next page
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.ticksupply.com/v1/subscriptions?limit=20&page_token=TOKEN"
```

See the [Pagination guide](/guides/pagination) for details.

### Rate limiting

All endpoints are rate limited:

* **200 requests/minute** per account
* **10,000 requests/hour** per account

Monitor usage via response headers:

```
X-RateLimit-Limit-Minute: 200
X-RateLimit-Remaining-Minute: 195
```

See the [Rate Limiting guide](/guides/rate-limiting) for details.

### Idempotency

Use the `Idempotency-Key` header for safe retries:

```bash theme={"system"}
curl -X POST -H "X-Api-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: unique-key-123" \
  -H "Content-Type: application/json" \
  -d '{"datastream_id": 123}' \
  https://api.ticksupply.com/v1/subscriptions
```

See the [Idempotency guide](/guides/idempotency) for details.

## Timestamps

Response timestamps come in two shapes depending on what they represent.

**Event timestamps** — `created_at`, `started_at`, `finished_at`, `updated_at`, and subscription span `started_at` / `ended_at` — are ISO 8601 strings:

```json theme={"system"}
{ "created_at": "2024-12-21T12:00:00Z" }
```

**Data-range timestamps** — export `start_time` / `end_time` and availability range `from` / `to` — are int64 nanoseconds since Unix epoch:

```json theme={"system"}
{ "start_time": 1703116800000000000, "end_time": 1703203200000000000 }
```

Request parameters that specify a data range use nanoseconds since Unix epoch (pass as strings to preserve precision in JavaScript):

```json theme={"system"}
{
  "start_time": "1703116800000000000",
  "end_time": "1703203200000000000"
}
```

[Create Export](/api-reference/exports/create-export) additionally accepts ISO 8601 strings for `start_time` / `end_time`.

<Tip>
  Convert between formats:

  * To nanoseconds: `timestamp_ns = unix_seconds * 1_000_000_000`
  * From nanoseconds: `unix_seconds = timestamp_ns / 1_000_000_000`
</Tip>