﻿---
title: "Stallfreunde API (v1) | Stallfreunde"
description: "Lesender Zugriff auf die Daten deines Stalls in Stallfreunde für eigene Skripte: Token, Aufgaben, Filter, Antwort und Fehler."
url: https://www.stallfreunde.app/api
language: de
---

# Stallfreunde API (v1)

Lesender Zugriff auf die Daten deines Stalls für eigene Skripte, zum Beispiel eine tägliche Prüfung, welche Stalldienste offen geblieben sind. Die API funktioniert unabhängig von der App.

## Zugang

- Ein Token gehört zu **einem Konto in einem Stall**. Er sieht genau das, was dieses Konto in der App sieht, nie mehr: zum Beispiel keine privaten Aufgaben anderer, und ohne das Recht für Aufgaben oder Stalldienste nur die eigenen.
- Den Token bekommst du von uns (E-Mail an [app.reitstall@gmail.com](mailto:app.reitstall@gmail.com)). Er wird einmal angezeigt; wir speichern nur einen Hash und können ihn nicht erneut nachschlagen.
- Der Token gilt, bis wir ihn widerrufen, bis zu einem vereinbarten Ablaufdatum oder bis das Konto den Stall verlässt.
- Behandle ihn wie ein Passwort: bewahre ihn nur in einer Umgebungsvariable oder einem Secret Store auf, nicht im Code und nicht in einer URL.

Jede Anfrage schickt den Token im Header mit:

```http
Authorization: Bearer sf_…
```

## Versionen

Die Version ist Teil des Pfads (`/api/v1/…`). Innerhalb von v1 kommen höchstens **neue** Felder und neue Filterwerte dazu; bestehende werden weder umbenannt noch entfernt. Ignoriere also Felder, die du nicht kennst. Eine inkompatible Änderung käme als `/api/v2/…`, und v1 läuft weiter.

## GET /api/v1/tasks

```text
https://bgkidelbtqrzvgfokdfd.supabase.co/functions/v1/api/v1/tasks
```

Aufgaben mit einem Fälligkeitstag im Zeitraum (Tage in der Zeitzone des Stalls, Europe/Berlin). Aufgaben ohne Fälligkeitstag werden nicht geliefert.

| Parameter | Pflicht | Werte |
|---|---|---|
| `from`, `to` | ja | `YYYY-MM-DD`, beide einschließlich, höchstens 31 Tage |
| `stable_duties_only` | | `true`: nur Aufgaben aus Stalldiensten |
| `stable_duty_id` | | nur die Aufgaben dieses Stalldiensts |
| `status` | | `open`, `done`, `needs_people` (offen und noch niemand eingetragen, oder weniger Leute, als der Stalldienst braucht) |
| `assigned_to` | | `me`, `nobody` oder die ID einer Person |
| `scope` | | kommagetrennt aus `ORGANIZATION` (ganzer Stall), `HORSE`, `HORSE_POSITION` (Box), `RIDING_GROUP`, `PERSONAL` |
| `scope_id` | | ID des Pferds, der Box oder der Reitgruppe |

Filter schränken das Ergebnis nur ein. Ein unbekannter Parameter oder Wert wird nicht stillschweigend ignoriert, sondern mit 400 abgelehnt.

**Beispiel: offene Stalldienste von gestern**

```bash
curl -s -H "Authorization: Bearer $STALLFREUNDE_TOKEN" \
  "https://bgkidelbtqrzvgfokdfd.supabase.co/functions/v1/api/v1/tasks?from=2026-11-16&to=2026-11-16&stable_duties_only=true&status=open"
```

### Antwort (anonymisiert)

```json
{
  "api_version": 1,
  "orga_id": "6f1c0a52-…",
  "from": "2026-11-16",
  "to": "2026-11-16",
  "generated_at": "2026-11-17T07:00:01.204+00:00",
  "tasks": [
    {
      "id": "a14558cd-95e8-4fbb-8ce9-746b159ead60",
      "title": "Koppelservice morgens",
      "description": "Pferde auf die Koppel bringen und Wasser auffüllen",
      "scope": { "type": "ORGANIZATION", "id": null, "name": null },
      "stable_duty": { "id": "0b6e…", "name": "Koppelservice morgens" },
      "due_date": "2026-11-16",
      "all_day": false,
      "start_time": "08:00",
      "end_time": "09:00",
      "assignees": [
        { "id": "3d2a…", "name": "Vorname", "surname": "Nachname" }
      ],
      "is_done": false,
      "closed_at": null,
      "needs_people": true,
      "created_at": "2026-11-02T03:00:12.551+00:00",
      "updated_at": "2026-11-15T18:21:40.002+00:00"
    }
  ]
}
```

| Feld | Bedeutung |
|---|---|
| `id` | dauerhafte ID der Aufgabe |
| `scope.type` | für wen die Aufgabe gilt (Werte wie beim Filter `scope`; neue Werte können dazukommen) |
| `scope.name` | Name des Pferds, der Box oder der Reitgruppe, sonst `null` |
| `stable_duty` | der Stalldienst, aus dem die Aufgabe stammt, sonst `null` |
| `due_date` | Fälligkeitstag (Zeitzone des Stalls) |
| `all_day`, `start_time`, `end_time` | Stalldienste haben die Uhrzeit ihres Diensts, andere Aufgaben gelten ganztägig (`start_time`/`end_time` sind dann `null`) |
| `assignees` | eingetragene Personen; `name`/`surname` sind `null` bei Personen, die den Stall verlassen haben |
| `is_done`, `closed_at` | erledigt, und wann |
| `needs_people` | offen, und es fehlen noch Leute |

## Fehler

Alle Fehler kommen als JSON: `{ "error": { "code": "…", "message": "…" } }`

| Status | `code` | Wann |
|---|---|---|
| 400 | `invalid_parameter` | ein Parameter fehlt, ist unbekannt oder ungültig (die Meldung sagt, welcher) |
| 401 | `unauthorized` | Token fehlt, ist falsch, widerrufen oder abgelaufen, oder das Konto ist nicht mehr im Stall |
| 403 | `missing_scope` | der Token darf diesen Endpunkt nicht nutzen |
| 404 | `not_found` | unbekannter Pfad oder unbekannte Version |
| 405 | `method_not_allowed` | nur `GET` (und `HEAD`) |
| 500 | `internal_error` | Fehler bei uns; bitte versuche es später noch einmal |

Bitte frag höchstens einmal pro Minute ab: für eine tägliche Prüfung reicht ein Aufruf am Tag.
