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

We maintain backward compatibility within a major version. Breaking changes require a new major version.

Authentication

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

curl -H "X-Api-Key: YOUR_API_KEY" \
  https://api.ticksupply.com/v1/exchanges

See the Authentication guide 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`

Treat IDs as opaque strings. Store and pass them exactly as returned by the API.

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:

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:

{
  "error": {
    "code": "not_found",
    "message": "Subscription not found"
  }
}

See the Error Handling guide for all error codes.

Endpoint categories

Catalog

Browse exchanges, instruments, and data stream types

Subscriptions

Create and manage data subscriptions

Export Schemas

Define custom column mappings for exports

Exports

Export historical data to files

Availability

Query data availability

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:

# 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 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 for details.

Idempotency

Use the Idempotency-Key header for safe retries:

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 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:

{ "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:

{ "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):

{
  "start_time": "1703116800000000000",
  "end_time": "1703203200000000000"
}

Create Export additionally accepts ISO 8601 strings for start_time / end_time.

Convert between formats:

To nanoseconds: timestamp_ns = unix_seconds * 1_000_000_000
From nanoseconds: unix_seconds = timestamp_ns / 1_000_000_000

​API Reference

​Base URL

​API versioning

​Authentication

​Resource IDs

​Request format

​Headers

​Request body

​Response format

​Success responses

​Error responses

​Endpoint categories

Catalog

Subscriptions

Export Schemas

Exports

Availability

​Catalog

​Subscriptions

​Export Schemas

​Exports

​Availability

​Common patterns

​Pagination

​Rate limiting

​Idempotency

​Timestamps

API Reference

Base URL

API versioning

Authentication

Resource IDs

Request format

Headers

Request body

Response format

Success responses

Error responses

Endpoint categories

Catalog

Subscriptions

Export Schemas

Exports

Availability

Common patterns

Pagination

Rate limiting

Idempotency

Timestamps