Getting started
Create a key, make requests, permissions, pages, limits and errors of the API.
With the API, your own programs reach the data of your account, for example to take over models from another system or to transfer inquiries into accounting. The API is meant for programs on a server, not for the browser: it does not allow calls from other websites (no CORS).
Address: https://api.casttool.net/v1. All endpoints are listed in the API reference, machine-readable at https://api.casttool.net/v1/openapi.json (OpenAPI 3.1, available without a key).
Create a key
Only the owner creates keys, under API keys:
Give it a Name saying what the key is for.
Under Permissions, only select what the program needs, see Permissions.
Choose the Validity: 30 days, 90 days, 1 year or until revoked.
Create key and store the key safely right away. It is shown only this once, and CastTool cannot read it afterwards either.
The list shows for each key who created it and when, and when it was last used. Revoke blocks it immediately, admins may do this too. An account has at most 25 active keys.
Make requests
The key goes into the Authorization header, never into the address:
curl https://api.casttool.net/v1/me \
-H "Authorization: Bearer ctk_…"GET /v1/me shows which account the key belongs to and which permissions it has. Every key only reaches the data of its own account.
Permissions
| Permission | Allows |
|---|---|
models:read | Read models, without contact details. Includes inactive models and applications. |
models:private | Additionally contact details, date of birth and origin. Only works together with models:read. |
models:write | Create and change models. Publishing still only happens in the management area. |
inquiries:read | Read inquiries, with the clients' contact details. |
bookings:read | Read confirmed bookings. |
A new model created through the API is inactive. You change status, visibility on the website and images in the management area, where approvals and consents live. Inquiries and bookings are read-only.
Pages
Lists return data and nextCursor. With limit (1 to 100) you choose the size of a page, and for the next one you pass nextCursor as cursor. On the last page nextCursor is null.
Limits
Each key may make 120 requests per minute, each account 600. Every response states the current position in RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Above that, the API answers with 429 and Retry-After in seconds.
Errors
Errors always come in the same shape:
{ "error": { "code": "validation_failed", "message": "The request is invalid.", "issues": [{ "path": "cursor", "message": "Invalid cursor" }] } }| Status | code | Meaning |
|---|---|---|
| 400 | validation_failed, invalid_json | The request does not match the description. issues names the fields. |
| 401 | invalid_api_key | Key missing, unknown, revoked or expired. |
| 402 | billing_read_only | The account is read-only because of the subscription, writing is not possible. |
| 403 | insufficient_scope | The key lacks the required permission. |
| 403 | tenant_suspended | The account is suspended, reading is not possible either. |
| 404 | not_found | Does not exist, or belongs to another account. |
| 429 | rate_limited, too_many_failed_attempts | Too many requests or failed attempts, see Retry-After. |
Before launch
The address api.casttool.net is not set up yet. The limits are a first technical setting and not a promise of any plan.