Conventions

Every REST endpoint in this reference shares the conventions on this page. Endpoint-specific pages document only what differs.

Base URL and versioning

https://api.t17.capital/v1

/v1 is the major version and appears in every path. Breaking schema or signed-payload changes require a new major version (see Compatibility). The base host is a production configuration placeholder — Draft v0.1 does not publish a real domain.

Media type

All requests and responses use application/json unless an endpoint explicitly documents otherwise. Request bodies use UTF-8 JSON.

Identifiers

• Resource IDs are stable, opaque strings with a human-readable type prefix (for example idx_, mkt_, ord_, fill_). Clients MUST NOT derive semantics from the prefix.
• Slugs and symbols are mutable presentation fields, never foreign keys.
• Counters and sequence numbers are JSON integers, used only while guaranteed to stay within an interoperable integer range.

Field naming

All JSON fields use snake_case.

Fixed-point decimal strings

Monetary values, probabilities, index levels, quantities, weights, rates, fees, and P&L are base-10 strings, never floating-point JSON numbers, plus explicit scale/unit metadata where ambiguity is possible.

{
  "level": "128.4500000000",
  "unit": "index_points",
  "quantity": "150.00",
  "price": "0.6400",
  "fee": "0.32"
}

Binary market probabilities/prices fall within [0, 1]; Time Seventeen does not assume an integer-cent representation.

Timestamps

Primary human-readable timestamps are RFC 3339 UTC with a trailing Z. Latency-sensitive events additionally include a Unix epoch millisecond integer in a *_ts_ms field.

{
  "published_at": "2026-08-31T12:00:00Z",
  "published_at_ts_ms": 1788350400000
}

Missing vs. zero

Missing means unavailable or not applicable. Zero means a measured zero. Endpoints do not coerce missing data to zero — a missing field is omitted or explicitly null, never silently defaulted.

Response envelopes

Single resource:

{
  "data": {},
  "meta": {
    "request_id": "req_demo_001",
    "published_at": "2026-08-31T12:00:00Z",
    "schema_version": "1.0"
  }
}

Collection:

{
  "data": [],
  "page": {
    "next_cursor": null,
    "has_more": false
  },
  "meta": {}
}

Every response includes meta.request_id, which also appears as the T17-Request-Id response header and inside every error envelope for support/trace correlation.

Query behavior

• Cursor pagination is used for mutable or high-volume collections. Cursors are opaque and bound to the filters/sort in effect when they were issued — changing filters invalidates a cursor.
• Default ordering and supported sort fields are documented per endpoint; unsupported sort fields return a validation error.
• Time ranges use an inclusive start_time and an exclusive end_time.
• as_of requests a point-in-time view and MUST NOT silently return the current version.
• expand embeds named related resources inline; otherwise relationships are represented as IDs/links only.
• Unknown filters, enum values, expansion paths, and sort fields return a VALIDATION_* error rather than being silently ignored.

GET /markets?status=open&venue=ven_demo_001&cursor=opaque_cursor_abc&limit=50
GET /indexes/idx_demo_conflict_001/prices?start_time=2026-08-01T00:00:00Z&end_time=2026-08-31T00:00:00Z
GET /indexes/idx_demo_conflict_001/versions/ver_demo_001/constituents?expand=market

Reliability

• Safe (read) requests are retryable with bounded exponential backoff and jitter.
• Mutating requests require an Idempotency-Key header. An identical replay of the same key and canonical body returns the original semantic result; reuse of the same key with a different canonical body returns IDEMPOTENCY_CONFLICT. Idempotency-key retention is a production configuration value, not fixed by Draft v0.1.
• Rate-limit headers expose limit class, remaining capacity, reset/retry timing, and request cost. Draft v0.1 defines the header shape only — no numeric quota is specified.

T17-RateLimit-Limit-Class: market_data
T17-RateLimit-Remaining: 42
T17-RateLimit-Reset: 1788350460
T17-RateLimit-Cost: 1

• Public immutable data (published Index Versions, superseded price observations, historical ratings/severity records) permits long-lived caching and ETag/If-None-Match conditional requests. Current prices and states instead expose an explicit freshness indicator such as max_age_ms so a client can judge how live a “current” read is.

Batch semantics

Batch endpoints are item-addressable: each item in the request maps to an independently reported success or failure in the response, so a partial failure never hides which items succeeded.

{
  "data": [
    { "index": 0, "status": "accepted", "order_id": "ord_demo_001" },
    { "index": 1, "status": "rejected", "error": { "code": "ORDER_TICK_SIZE_INVALID" } }
  ],
  "meta": { "request_id": "req_demo_002" }
}

Errors

See Errors for the full structured error model and code families.

Compatibility and evolution

• The major version lives in the URL path and, for signed order/authorization payloads, in the EIP-712 domain.
• Additive response fields are allowed within a major version. Clients ignore unknown fields but MUST NOT ignore unknown enum values that change economic behavior (for example an unrecognized order status or time-in-force value).
• Stream messages carry an independent event schema version (see WebSocket).
• Deprecation announcements and coexistence windows are production policy, not fixed by this draft.
• Historical records remain readable using the schema and methodology version that produced them.