# Conventions

The rules every Kelly API call follows, from the base URL and versions to paging, request IDs and rate-limit headers.

Every operation follows the same conventions, so once you've made one call you know how the rest behave.

## Base URL and versions
The base URL is `https://api.askkelly.ai`. Send the dated version you built against in `Api-Version`; omitted means `2026-10-05`, and the versions served today are `2026-10-05`. An unsupported version is refused with `unsupported_api_version`.

```http Request headers
Api-Version: 2026-10-05
```

## Authentication header

`Authorization: Bearer $KELLY_API_KEY`. See [authentication](/concepts/authentication).

## IDs

IDs are opaque strings. Compare them as strings and don't parse them; a prefix such as `mkt_` names the kind of object.

## Timestamps and dates

Times are RFC 3339 date-times in UTC, such as `as_of`. Dates without a time, such as `retrieved_at` on a reference source, are `YYYY-MM-DD`.

## Units and money

Prices and probabilities are numbers computed by Kelly's engine; each field's description says its unit. Kelly serves no per-book price off askkelly.ai.

## Enums

Every enum is open: new values may be added in the same version. Treat an unknown value as "other" rather than failing.

## Paging

Every list is a page, never a bare array: `data` holds the items, `has_more` says whether another page follows, and `next_cursor` is an opaque [cursor](/glossary#cursor) for the next page. Send it back as `cursor` with the same filters; changed filters are refused with `invalid_request`. For `GET /v1/reference`, `limit` is 1 to 25, default 10.

## Filtering and sorting

Lists filter by the query parameters each operation lists in the [reference](/reference). There is no sort parameter today; each list documents its order.

## Idempotency

`GET` requests are safe to repeat. A non-idempotent request that accepts an `Idempotency-Key` header can be retried with the same key and gets the first result back; the definition marks which operations accept it. See [retries](/policies/retries).

## The response envelope

Every resource carries its [provenance](/glossary#provenance) beside its fields: `as_of` (when the value was true) and `source` (who produced it), plus `object` (the resource's type) and `request_id`.

## Request IDs

Every response carries a `Request-Id` header, the [request ID](/glossary#request-id). Send your own `Client-Request-Id` and it is echoed back when well formed. Quote the request ID to support.

## Rate-limit and usage headers

Metered calls count [credits](/glossary#credit) against your plan, and the definition names the headers that report them, such as `X-RateLimit-Remaining`, `RateLimit` and `X-Credits-Used`. See [limits](/policies/limits).

---

Last updated October 16, 2026

Support: support@askkelly.ai · Security and disclosure: https://docs.askkelly.ai/security

Information is the edge. Odds are information, not advice · 21+ · Get help