Errors, limits & paging

Conventions every endpoint follows: JSON shapes, error types, rate limits, pagination, dates and versioning.

#Requests and responses

• Base URL https://api.aceversity.com/v1. JSON in, JSON out (Content-Type: application/json).
• GET and DELETE take query parameters; POST, PUT and PATCH take a JSON body. Path parameters are always ids.
• PATCH changes only the fields you send. Send null to clear an optional field (e.g. "due_on": null).
• PUT /v1/courses/{id}/grade-categories replaces the whole list.
• Successful creates return 201 with the new object; deletes return 200 {"id": "…", "deleted": true}.
• Unknown fields are ignored. Ids are UUIDs.

#Dates and time zones

• Calendar dates are YYYY-MM-DD (due_on). Timestamps are ISO 8601 in UTC (created_at).
• "Today" is the member's today in their profile time zone — GET /v1/me returns it as today. days_until and /v1/agenda use it, so a student in Los Angeles at 7 pm on the 12th still sees the 12th.

#Errors

Every error has the same shape:

{
  "error": {
    "type": "validation_failed",
    "message": "`due_on`: Invalid ISO date",
    "request_id": "req_8f2a1c9b0d3e4f5a6b7c",
    "details": [{ "field": "due_on", "message": "Invalid ISO date" }]
  }
}

Every response has an X-Request-Id header. Quote it to support@aceversity.com.

#Rate limits

120 requests per minute per credential (each API key or OAuth token), fixed one-minute windows. Every response tells you where you are:

RateLimit-Limit: 120
RateLimit-Remaining: 117
RateLimit-Reset: 42

Over the limit you get 429 with Retry-After. The OAuth endpoints have their own per-IP limits (token: 60/min, registration: 20/hour). Sign-in pages: 15 attempts per 10 minutes per IP.

Recommended client behaviour: on 429 sleep Retry-After; on 5xx or network errors retry up to 3 times with exponential backoff (1 s, 2 s, 4 s) — only for GET, PUT, PATCH and DELETE, which are idempotent. Don't blindly retry POST (you could create a duplicate).

#Pagination

List endpoints return:

{ "data": [ … ], "has_more": true, "next_cursor": "MjU" }

Pass limit (1–100, default 25) and cursor=<next_cursor> for the next page. Stop when has_more is false. Small collections (courses, decks, milestones) return everything in one page.

#Polling for changes

For automations ("when a new deadline is added, do X"), call GET /v1/items?created_after=<ISO timestamp of your last run> on a schedule. Store the newest created_at you saw and pass it next time. (Webhooks are on the roadmap.)

#Versioning

• The version is in the path: /v1. Within v1 we only make additive changes — new endpoints, new optional parameters, new response fields, new enum values (handle unknown kind values gracefully).
• Breaking changes would ship as /v2 with at least 6 months of overlap, announced in the changelog and by email to members with active keys.
• info.version in openapi.json follows semver.