Einstieg
Schlüssel anlegen, Anfragen stellen, Rechte, Seiten, Grenzen und Fehler der API.
Mit der API greifen eigene Programme auf die Daten Ihres Kontos zu, etwa um Models aus einem anderen System zu übernehmen oder Anfragen in eine Buchhaltung zu übertragen. Die API ist für Programme auf einem Server gedacht, nicht für den Browser: Sie erlaubt keine Aufrufe aus fremden Websites (kein CORS).
Adresse: https://api.casttool.net/v1. Alle Endpunkte stehen in der API-Referenz, maschinenlesbar unter https://api.casttool.net/v1/openapi.json (OpenAPI 3.1, ohne Schlüssel abrufbar).
Schlüssel anlegen
Nur der Inhaber legt Schlüssel an, unter API-Schlüssel:
Einen Name vergeben, wofür der Schlüssel ist.
Unter Rechte nur auswählen, was das Programm braucht, siehe Rechte.
Die Gültigkeit wählen: 30 Tage, 90 Tage, 1 Jahr oder bis zur Rücknahme.
Schlüssel anlegen und den Schlüssel sofort sicher speichern. Er wird nur dieses eine Mal angezeigt, auch CastTool kann ihn danach nicht mehr lesen.
Die Liste zeigt je Schlüssel, wer ihn wann angelegt hat und wann er zuletzt benutzt wurde. Zurücknehmen sperrt ihn sofort, das dürfen auch Administratoren. Ein Konto hat höchstens 25 aktive Schlüssel.
Anfragen stellen
Der Schlüssel steht im Header Authorization, nie in der Adresse:
curl https://api.casttool.net/v1/me \
-H "Authorization: Bearer ctk_…"GET /v1/me zeigt, zu welchem Konto der Schlüssel gehört und welche Rechte er hat. Jeder Schlüssel kommt nur an die Daten seines eigenen Kontos.
Rechte
| Recht | Erlaubt |
|---|---|
models:read | Models lesen, ohne Kontaktdaten. Auch inaktive Models und Bewerbungen. |
models:private | Zusätzlich Kontaktdaten, Geburtsdatum und Angaben zur Herkunft. Wirkt nur zusammen mit models:read. |
models:write | Models anlegen und ändern. Veröffentlicht wird weiter nur in der Verwaltung. |
inquiries:read | Anfragen lesen, mit den Kontaktdaten der Kunden. |
bookings:read | Bestätigte Buchungen lesen. |
Ein neues Model aus der API ist inaktiv. Status, Sichtbarkeit auf der Website und Bilder ändern Sie in der Verwaltung, dort stehen Freigaben und Einwilligungen. Anfragen und Buchungen sind nur lesbar.
Seiten
Listen liefern data und nextCursor. Mit limit (1 bis 100) wählen Sie die Größe einer Seite, für die nächste geben Sie nextCursor als cursor mit. Auf der letzten Seite ist nextCursor null.
Grenzen
Je Schlüssel gehen 120 Anfragen in der Minute, je Konto 600. Jede Antwort nennt den Stand in RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset. Darüber antwortet die API mit 429 und Retry-After in Sekunden.
Fehler
Fehler kommen immer in derselben Form:
{ "error": { "code": "validation_failed", "message": "The request is invalid.", "issues": [{ "path": "cursor", "message": "Invalid cursor" }] } }| Status | code | Bedeutung |
|---|---|---|
| 400 | validation_failed, invalid_json | Die Anfrage passt nicht zur Beschreibung. issues nennt die Felder. |
| 401 | invalid_api_key | Schlüssel fehlt, ist unbekannt, zurückgenommen oder abgelaufen. |
| 402 | billing_read_only | Das Konto ist wegen des Abos nur lesbar, Schreiben geht nicht. |
| 403 | insufficient_scope | Dem Schlüssel fehlt das nötige Recht. |
| 403 | tenant_suspended | Das Konto ist gesperrt, auch Lesen geht nicht. |
| 404 | not_found | Gibt es nicht, oder es gehört zu einem anderen Konto. |
| 429 | rate_limited, too_many_failed_attempts | Zu viele Anfragen oder Fehlversuche, siehe Retry-After. |
Vor dem Start
Die Adresse api.casttool.net ist noch nicht eingerichtet. Die Grenzen sind eine erste technische Festlegung und keine Zusage eines Tarifs.