Responses
Requests and responses are JSON, except GET /brands/{brand}/markdown, which returns text/markdown. Every response carries X-Tarkle-Api-Version: v1 and is sent with Cache-Control: no-store.
Failures are problem documents (application/problem+json). Branch on the code member.
Paging
List calls such as GET /brands, GET /brands/{brand}/requests and GET /files return one page at a time and take limit and cursor.
limitis a whole number: 1 to 100 for brand lists (default 25), 1 to 1,000 forGET /files(default 100). A value outside the range or one that is not a whole number answers400. Tarkle does not round it.- Each page returns
next_cursor. Send it back unchanged ascursorto get the next page. It isnullon the last page, and there is no empty page after it. - The cursor is opaque. It marks the place after the last row you saw, so rows added or removed between two calls are not skipped or repeated, and there is no limit on how deep you can page.
- A cursor that Tarkle did not issue answers
400 invalid_request(“Invalid cursor”).
Rate limits
Limits are per token. Brand calls allow 120 requests a minute. Files calls and GET /workspaces allow 600 a minute. These are working values, so read the limit from the headers instead of hard-coding it.
Every authenticated response carries:
| Header | Meaning |
|---|---|
X-RateLimit-Limit |
Requests allowed per minute in this token’s bucket. |
X-RateLimit-Remaining |
Requests left in the current minute. |
X-RateLimit-Reset |
When the current window ends, in Unix seconds. |
When a token goes over its limit the answer is 429 rate_limited with Retry-After in whole seconds, the exact time left in the window (never less than 1). Wait that long, then retry.
Only valid tokens are counted: a missing or invalid token answers 401 first. The limit runs before the scope check, so 403 answers count.
Versions
The version is in the path (/api/v1). Inside v1 Tarkle only adds things, so ignore fields and error codes you do not know. A change that could break a client ships as a new version, and the old one keeps working for at least six months after its end is announced, with Deprecation and Sunset headers on its responses.