INKY icon

INKY

REST API for INKY external partner integrations. Provides access to team metadata, billable usage data, and webhook event subscriptions.## StabilityEvery endpoint's path prefix states what it promises, so you can tell from the URL alone what you are depending on.- **`/v1`** is stable. A breaking change ships as a new prefix, not an edit to this one.- **`/beta`** is not yet stable. These endpoints may change shape or be removed without notice, and move to `/v2` once they settle. They are fully documented and callable, since beta means "no stability promise" rather than "hidden", but do not build a production integration against them. Every beta operation repeats this notice at the top of its description.When a beta endpoint is promoted, it answers on both prefixes for a deprecation window before the `/beta` path is retired, so an early integration is not broken by the promotion itself.## AuthenticationEvery endpoint requires an API key in the `X-API-Key` header, except `/v1/status`. `/v1/openapi.json`, which serves this document, is also unauthenticated; it is the API's reference rather than part of the API, and is not listed in `paths`.### Platform signature (partner integrations)Whether an endpoint requires an additional HMAC signature on top of the API key depends on your key's role, not on the endpoint alone.A key whose role is suffixed `_integration` (e.g. `gradient_msp_integration`) must sign every read on this API: `/v1/me`, the team and usage reads, and every `GET` on the `/beta` management families. A customer-issued key (`external_api_user`) does not. For it the check is a pass-through, and those endpoints behave exactly as the rest do. Writes are never signed.Each operation that can require a signature lists `PLATFORM_SIGNATURE_INVALID` among its `401` responses; that per-operation list is authoritative.Callers who must sign include two headers:- `X-Inky-Timestamp`, an integer unix-seconds timestamp. It must be within the server's configured skew window, 5 min by default.- `X-Inky-Signature: v1=<hex>`, the lowercase hex HMAC-SHA256 of the canonical string, whose fields are joined by a single ASCII LF (0x0A) byte: `v1 <LF> <timestamp> <LF> <METHOD_UPPERCASE> <LF> <url-decoded-path>[?<raw-query-string>] <LF> <sha256_hex(raw_body)>`. The path component is url-decoded; the query string is included in its raw, NOT url-decoded form (percent-encoded characters stay percent-encoded on both sides). The `?<raw-query-string>` segment is appended only when a query string is present, so a request with no query has no trailing `?`. Keyed with the shared platform secret.A signature is bound to the exact request body, method, and path, so it does not carry over to a request that differs in any of them. The same signature cannot be used twice inside the skew window: a repeat answers `401 PLATFORM_SIGNATURE_REPLAYED`. Because the signed timestamp is in whole seconds, two identical requests signed in the same second carry the same signature, and only the first is accepted. To send the same request again, re-sign it with a fresh timestamp. Rotation is supported via two active secrets; either one verifies during the overlap. The shared secret lives between the peer platforms and is never exposed through the dashboard or customer-issued API keys.## Common response headersThese headers are not limited to success responses. INKY sets them once the request has got far enough to produce them, so a refusal raised after that point carries them too. A `429 RATE_LIMITED` reports the rate-limit window it refused you under, and a `403` or `404` on a key expiring soon still says so.Authenticated endpoints may return:- `X-RateLimit-Limit`: requests allowed per window. Present when the call reached a rate limiter, including on the `429` that limiter raises- `X-RateLimit-Remaining`: requests remaining in the current window. `0` on a `429 RATE_LIMITED`- `X-RateLimit-Reset`: the Unix time at which the current window resets. Pace against this rather than waiting to be refused; it is absolute, so it stays true if you cache it- `X-API-Key-Expires-Soon: true`: present when the API key expires within 30 days. INKY sets it once the key is validated, so it appears on refusals as well as successes. On a `401` that means only `PLATFORM_SIGNATURE_INVALID` or `PLATFORM_SIGNATURE_REPLAYED`, where the key itself was accepted and the signature over the request was not; the `401`s raised before a key resolves carry neither header- `X-API-Key-Expires-At`: the ISO-8601 expiration timestamp, present only alongside `X-API-Key-Expires-Soon`Every response, success or error, also carries:- `X-Request-Id`: an opaque per-request identifier. Quote it when contacting INKY support so the exact request can be located in our logs. INKY generates it server-side, so a value you send in is not used.## Common error responsesEvery endpoint except `/v1/status` may return `500 Internal Server Error` with error code `INTERNAL_ERROR` for unexpected failures. `/v1/status` is a static health check that reaches no dependency, so it has no failure of its own to report. All authenticated endpoints may return `401` with error codes `INVALID_API_KEY`, `MISSING_API_KEY`, or `EXPIRED_API_KEY`.

Discussion