Spedy Docs

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

Die Spedy-API ermoeglicht es dir, Boards, Tickets, Nutzer und alles andere in deiner Organisation programmatisch zu verwalten. Sie folgt REST-Konventionen und gibt JSON fuer alle Antworten zurueck.

Basis-URL

Alle API-Anfragen sind auf die Subdomain deiner Organisation beschraenkt:

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

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

Alle API-Anfragen muessen mit einem Personal Access Token (PAT) authentifiziert werden. Erstelle ein PAT in deinen Kontoeinstellungen in der Spedy-Oberflaeche. PATs laufen nicht ab, es sei denn, du widerrufst sie -- ideal fuer Skripte, CI/CD-Pipelines und langlebige Integrationen.

Fuege dein Token im Authorization-Header jeder Anfrage ein:

Authorization: Bearer spedy_pat_abc123...

PATs erben die Berechtigungen des Nutzers, der sie erstellt hat. Siehe die Authentifizierungsseite fuer Details zum Erstellen und Verwalten von Tokens.

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.

Verfuegbare API-Bereiche

Bereich	Beschreibung
Authentifizierung	Personal Access Tokens erstellen und verwalten
OAuth 2.0	OAuth 2.0 mit PKCE fuer externe Anwendungen und KI-Tools
Organisation	Organisationseinstellungen und Details
Nutzer	Nutzer auflisten und Aktivitaeten einsehen
Teams	Teamverwaltung
Boards	Board-CRUD und Einstellungen
Board-Mitglieder	Board-Mitgliedschaft verwalten
Board-Status	Board-spezifische Status konfigurieren
Status	Globale Statusdefinitionen
Ticket-Typen	Ticket-Typ-Konfiguration
Tickets	Tickets erstellen und verwalten
Untertickets	Eltern-Kind-Ticket-Beziehungen
Ticket-Verknuepfungen	Verwandte Tickets verknuepfen
Kommentare	Ticket-Kommentare
Labels	Label-Verwaltung
Beobachter	Ticket-Beobachter
Anhaenge	Datei-Anhaenge
Meilensteine	Meilenstein-Tracking
Releases	Release-Verwaltung
Zeiterfassung	Zeiteintraege auf Tickets
Suche	Ressourcenuebergreifende Suche
Wiki	Wiki-Spaces, Seiten und Ordner
Kunden	Kundenverwaltung
Webhook-Endpunkte	Events per Webhooks abonnieren

Paginierung

Listen-Endpunkte geben paginierte Ergebnisse zurueck. 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	Eintraege 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 zurueck:

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

Haeufige Statuscodes:

Code	Bedeutung
400	Bad Request -- ungueltige Eingabe oder Constraint-Verletzung
401	Unauthorized -- fehlendes oder ungueltiges Token
403	Forbidden -- unzureichende Berechtigungen
404	Not Found -- Ressource existiert nicht oder ist nicht zugaenglich
409	Conflict -- doppelter Name oder ungueltiger Statusuebergang
429	Too Many Requests -- Rate-Limit ueberschritten

Rate Limiting

Bestimmte Endpunkte haben Rate-Limits zum Schutz der Plattform. Wenn du ein Limit ueberschreitest, erhaeltst du eine 429-Antwort. Rate-Limits werden pro Token angewendet und variieren je nach Endpunkt.

Multi-Tenancy

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

Soft Deletes

Die meisten Ressourcen verwenden Soft-Deletion. Geloeschte Eintraege werden standardmaessig aus Listen-Responses ausgeschlossen, koennen aber mit dem Query-Parameter includeDeleted eingeschlossen werden, wo unterstuetzt. Soft-geloeschte Ressourcen behalten ihre IDs und koennen teilweise wiederhergestellt werden.

Berechtigungen

Die Zugriffskontrolle wird auf zwei Ebenen durchgesetzt:

Organisationsrolle -- Admin, TeamMember oder Customer. Admins haben vollen Zugriff; Kunden haben eingeschraenkte Sichtbarkeit (z.B. keine geheimen Kommentare).
Feature-Berechtigungen -- granulare Faehigkeiten wie tickets:edit, milestones:view oder time-tracking:manage. Diese werden pro Endpunkt geprueft und auf jeder Ressourcenseite dokumentiert.

Einige Features (Teams, Webhook-Endpunkte) erfordern ein Pro-Plan-Abonnement.

Feature Guards

Bestimmte Endpunkte sind hinter Board-Level-Feature-Flags geschuetzt. Zum Beispiel erfordern Meilensteine und Releases, dass das Feature Meilensteine & Releases auf dem Board aktiviert ist, und Zeiterfassung erfordert, dass das Feature Zeiterfassung fuer die Organisation aktiviert ist. Wenn ein Feature nicht aktiviert ist, geben Anfragen an diese Endpunkte 403 Forbidden zurueck.

API-Uebersicht