﻿---
title: "Stallfreunde API (v1) | Stallfreunde"
description: "Read only access to your stable's data in Stallfreunde for your own scripts: tokens, the tasks endpoint, filters, response and errors."
url: https://www.stallfreunde.app/en/api
language: en
---

# Stallfreunde API (v1)

Read only access to your stable's data for your own scripts, e.g. a daily check of which stable duties were left open. The API works independently of the app.

## Access

- A token belongs to **one account in one stable**. It sees exactly what that account sees in the app, never more: for example no private tasks of others, and without the right for tasks or stable duties only the account's own.
- You get the token from us (email to [app.reitstall@gmail.com](mailto:app.reitstall@gmail.com)). It is shown once; we only store a hash and cannot look it up again.
- The token is valid until we revoke it, until an agreed expiry date, or until the account leaves the stable.
- Treat it like a password: keep it only in an environment variable or a secret store, not in code and not in a URL.

Every request sends the token in the header:

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

## Versions

The version is part of the path (`/api/v1/…`). Within v1, at most **new** fields and new filter values are added; existing ones are not renamed or removed. So ignore fields you do not know. An incompatible change would come as `/api/v2/…`, and v1 keeps running.

## GET /api/v1/tasks

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

Tasks with a due day in the period (days in the stable's time zone, Europe/Berlin). Tasks without a due day are not returned.

| Parameter | Required | Values |
|---|---|---|
| `from`, `to` | yes | `YYYY-MM-DD`, both inclusive, at most 31 days |
| `stable_duties_only` | | `true`: only tasks from stable duties |
| `stable_duty_id` | | only the tasks of this stable duty |
| `status` | | `open`, `done`, `needs_people` (open and nobody signed up yet, or fewer people than the stable duty needs) |
| `assigned_to` | | `me`, `nobody` or the ID of a person |
| `scope` | | comma separated from `ORGANIZATION` (whole stable), `HORSE`, `HORSE_POSITION` (box), `RIDING_GROUP`, `PERSONAL` |
| `scope_id` | | ID of the horse, box or riding group |

Filters only narrow the result. An unknown parameter or value is not silently ignored but rejected with 400.

**Example: open stable duties from yesterday**

```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"
```

### Response (anonymized)

```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"
    }
  ]
}
```

| Field | Meaning |
|---|---|
| `id` | permanent ID of the task |
| `scope.type` | who the task applies to (values as in the `scope` filter; new values may be added) |
| `scope.name` | name of the horse, box or riding group, otherwise `null` |
| `stable_duty` | the stable duty the task comes from, otherwise `null` |
| `due_date` | due day (stable's time zone) |
| `all_day`, `start_time`, `end_time` | stable duties have the time of their duty, other tasks apply all day (`start_time`/`end_time` are then `null`) |
| `assignees` | signed up people; `name`/`surname` are `null` for people who left the stable |
| `is_done`, `closed_at` | done, and when |
| `needs_people` | open and still missing people |

## Errors

All errors come as JSON: `{ "error": { "code": "…", "message": "…" } }`

| Status | `code` | When |
|---|---|---|
| 400 | `invalid_parameter` | a parameter is missing, unknown or invalid (the message says which) |
| 401 | `unauthorized` | token missing, wrong, revoked, expired, or the account is no longer in the stable |
| 403 | `missing_scope` | the token may not use this endpoint |
| 404 | `not_found` | unknown path or unknown version |
| 405 | `method_not_allowed` | only `GET` (and `HEAD`) |
| 500 | `internal_error` | error on our side; please try again later |

Please do not query more than once per minute: for a daily check, one call per day is enough.
