Spedy Docs

Alles, was du für die Integration mit der Spedy-API brauchst -- Authentifizierung, Request-Format, Paginierung und Fehlerbehandlung.

Die Spedy-API ermöglicht es dir, Boards, Tickets, Nutzer und alles andere in deiner Organisation programmatisch zu verwalten. Sie folgt REST-Konventionen und gibt JSON für alle Antworten zurück.

Basis-URL

Alle API-Anfragen sind auf die Subdomain deiner Organisation beschränkt:

https://{org-slug}.spedy.ai/api/v1

Ersetze {org-slug} mit dem Slug deiner Organisation (zum Beispiel acme-corp).

Authentifizierung

Jede Anfrage muss ein gültiges Access-Token enthalten. Spedy unterstützt zwei Authentifizierungsmethoden:

Bearer Token (JWT)

Erhalte ein Token durch Aufruf des Login-Endpunkts mit deiner E-Mail und deinem Passwort. Füge es dann in jede Anfrage ein:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

JWTs laufen nach kurzer Zeit ab. Nutze den Refresh-Endpunkt, um ein neues Token ohne erneute Anmeldung zu erhalten.

Für Skripte, CI/CD-Pipelines und langlebige Integrationen erstelle ein Personal Access Token in deinen Kontoeinstellungen. PATs laufen nicht ab, es sei denn, du widerrufst sie. Füge sie auf die gleiche Weise ein:

Authorization: Bearer spedy_pat_abc123...

Alle Details zu beiden Methoden findest du auf der Authentifizierungsseite.

Request-Format

Sende Request-Bodies als JSON mit dem Content-Type: application/json-Header.
Datei-Uploads verwenden stattdessen multipart/form-data.
Query-Parameter verwenden Standard-URL-Encoding.

Paginierung

Listen-Endpunkte geben paginierte Ergebnisse zurück. Verwende die Query-Parameter page und limit, um das Fenster zu steuern:

Parameter	Typ	Standard	Beschreibung
page	number	1	Seitennummer (beginnt bei 1)
limit	number	20	Einträge pro Seite (max. 100)

Paginierte Antworten haben diese Struktur:

{
  "data": [],
  "total": 142,
  "page": 1,
  "pageSize": 20,
  "totalPages": 8
}

Fehlerbehandlung

Bei Fehlern gibt die API ein einheitliches Fehlerobjekt zurück:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Häufige Statuscodes:

Code	Bedeutung
400	Bad Request -- ungültige Eingabe oder Constraint-Verletzung
401	Unauthorized -- fehlendes oder ungültiges Token
403	Forbidden -- unzureichende Berechtigungen
404	Not Found -- Ressource existiert nicht oder ist nicht zugänglich
409	Conflict -- doppelter Name oder ungültiger Statusübergang
429	Too Many Requests -- Rate-Limit überschritten

Rate Limiting

Bestimmte Endpunkte haben Rate-Limits zum Schutz der Plattform. Wenn du ein Limit überschreitest, erhältst du eine 429-Antwort. Rate-Limits werden pro IP-Adresse angewendet und variieren je nach Endpunkt -- zum Beispiel sind Login-Versuche strikter limitiert als Leseoperationen.

Multi-Tenancy

Spedy ist eine Multi-Tenant-Plattform. Jede Ressource gehört zu einer Organisation, und alle API-Antworten sind automatisch auf die Organisation des authentifizierten Nutzers beschränkt. Du kannst nicht auf Ressourcen anderer Organisationen zugreifen.

API-Übersicht