Requests, responses and pagination

The conventions every endpoint shares, and how to walk a list.

Send JSON with Content-Type: application/json; responses are JSON, UTF-8. Timestamps are ISO 8601 in UTC with a Z suffix. Fields a request body does not define are ignored; metadata is free-form and stored as sent.

Anywhere an endpoint takes a model, in a path or a body, you may pass the id (mdl_…) or the slug (credit-risk-v3). Projects work the same way. Other objects are addressed by id. Your own prediction_id values (up to 64 characters) are accepted when logging, so predictions can carry the id your system already uses.

List endpoints return a page: data holds the items, total the number of matches, and has_more says whether offset + limit would return more. Pass limit and offset to walk the list. Each endpoint has its own maximum limit: 200 for models, explanations, analyses and projects, 500 for predictions and insights.

Two lists are not pages: GET /v1/api-keys returns a bare array, and POST /v1/predictions/batch returns the created predictions with a count. GET /v1/models/{model}/versions returns every version in one page.

Deletes return {"id", "object", "deleted": true}. Creates return 201 (202 for an analysis, which runs in the background). Empty responses use 204.

page = client.models.list(limit=2)
print(page.total, page.has_more)          # 5 True
for model in page.data:
    print(model.slug)

# follow has_more automatically
for model in client.models.iterate(status="active"):
    print(model.slug, model.task)

# pages and records are also plain mappings
page.to_dict()["data"][0]["slug"]

curl "https://api.kaimei.ai/v1/models?limit=2&offset=0" \
  -H "Authorization: Bearer $KAIMEI_API_KEY"

200 OKResponse

{
  "object": "list",
  "data": [
    {
      "object": "model",
      "id": "mdl_8f795e8afd954a787785",
      "slug": "cats-dogs-v1",
      …: …
    },
    {
      "object": "model",
      "id": "mdl_1f25e80f10e86a8a9f01",
      "slug": "equity-alpha-v1",
      …: …
    }
  ],
  "total": 5,
  "limit": 2,
  "offset": 0,
  "has_more": true
}