Zum Inhalt springen
decidio — Digitale Bürgerbeteiligung

API-Referenz

Vollständige Referenz der öffentlichen decidio-REST-API: Authentifizierung, Paginierung, Ratenbegrenzung, Endpunkte und Fehler.

Authentifizierung

Jede authentifizierte Anfrage trägt einen API-Schlüssel als Bearer-Token im Authorization Header. Schlüssel beginnen mit sk_, werden im Admin unter „Integrationen / API-Schlüssel“ ausgegeben, sind pro Mandant beschränkt und jederzeit widerrufbar.

curl -H "Authorization: Bearer sk_example_0000000000000000" https://api.decidio.de/api/v1/me

Paginierung

Listen verwenden Cursor-Paginierung. Übergeben Sie ?cursor=<opaque> aus dem letzten Antwort-Envelope und optional ?limit=<1..100> (Standard 20). Die Antwort liefert { data: [...], pagination: { next_cursor, has_more } }; folgen Sie next_cursor so lange, bis has_more === false.

Ratenbegrenzung

Jeder API-Schlüssel darf 1 000 Anfragen pro Stunde absetzen. Jede Antwort enthält X-RateLimit-Limit und X-RateLimit-Remaining. Bei Überschreitung antwortet decidio mit 429 Too Many Requests, dem Header Retry-After (Sekunden bis zum Fensterende) sowie X-RateLimit-Reset (Unix-Zeitstempel des Reset).

Jede Antwort trägt außerdem die Sicherheits-Header X-Content-Type-Options: nosniff sowie Cache-Control: no-store; der Content-Type ist immer application/json; charset=utf-8. Cachen Sie Antworten daher nicht clientseitig.

Endpunkte

health

GET /health

Service health check

Returns the API status and version. Unauthenticated; safe for liveness probes and uptime monitors.

Anfrage

curl https://api.decidio.de/api/v1/health

Antwort (200)

{
  "status": "ok",
  "version": "1.0.0"
}

me

GET /me

Inspect the authenticated API key

Returns the organization the API key is scoped to and the key’s descriptive metadata.

Anfrage

curl -H "Authorization: Bearer sk_example_0000000000000000" https://api.decidio.de/api/v1/me

Antwort (200)

{
  "organization_id": "00000000-0000-0000-0000-000000000001",
  "key_prefix": "sk_example_",
  "key_name": "Mein Integrations-Key"
}

Mögliche Fehler-Status: 400, 401, 429

submissions

GET /submissions

List submissions

Cursor-paginated list of citizen submissions scoped to the API key’s municipality. Optional filtering by status and topic.

NameInErforderlichBeschreibung
cursorqueryneinstring
limitqueryneininteger
statusqueryneinstring
topicqueryneinstring

Anfrage

curl -H "Authorization: Bearer sk_example_0000000000000000" https://api.decidio.de/api/v1/submissions

Antwort (200)

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "referenceNumber": null,
      "description": "Example description (synthetic)",
      "status": "eingegangen",
      "topicCategoryName": null,
      "priorityLevel": "normal",
      "supportCount": 1,
      "hasAttachments": false,
      "protocolUrl": null,
      "createdAt": "2026-01-01T12:00:00.000Z",
      "statusChangedAt": "eingegangen"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}

Mögliche Fehler-Status: 400, 401, 429

GET /submissions/{id}

Fetch a single submission

NameInErforderlichBeschreibung
idpathjastring — Resource UUID

Anfrage

curl -H "Authorization: Bearer sk_example_0000000000000000" https://api.decidio.de/api/v1/submissions/00000000-0000-0000-0000-000000000001

Antwort (200)

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000001",
    "referenceNumber": null,
    "description": "Example description (synthetic)",
    "status": "eingegangen",
    "topicCategoryName": null,
    "priorityLevel": "normal",
    "supportCount": 1,
    "hasAttachments": false,
    "protocolUrl": null,
    "createdAt": "2026-01-01T12:00:00.000Z",
    "statusChangedAt": "eingegangen"
  }
}

Mögliche Fehler-Status: 400, 401, 404, 429

sessions

GET /sessions

List committee sessions

Cursor-paginated list of council/committee sessions scoped to the API key’s municipality.

NameInErforderlichBeschreibung
cursorqueryneinstring
limitqueryneininteger

Anfrage

curl -H "Authorization: Bearer sk_example_0000000000000000" https://api.decidio.de/api/v1/sessions

Antwort (200)

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "committeeName": "Beispiel-Ausschuss",
      "date": "2026-01-01",
      "timeSlot": null,
      "submissionCount": 1,
      "createdAt": "2026-01-01T12:00:00.000Z"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}

Mögliche Fehler-Status: 400, 401, 429

GET /sessions/{id}

Fetch a single session with submissions

NameInErforderlichBeschreibung
idpathjastring — Resource UUID

Anfrage

curl -H "Authorization: Bearer sk_example_0000000000000000" https://api.decidio.de/api/v1/sessions/00000000-0000-0000-0000-000000000001

Antwort (200)

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000001",
    "committeeName": "Beispiel-Ausschuss",
    "date": "2026-01-01",
    "timeSlot": null,
    "submissionCount": 1,
    "createdAt": "2026-01-01T12:00:00.000Z",
    "submissions": [
      {
        "id": "00000000-0000-0000-0000-000000000001",
        "referenceNumber": null,
        "description": "Example description (synthetic)",
        "status": "eingegangen",
        "topicCategoryName": null,
        "priorityLevel": "normal",
        "supportCount": 1,
        "hasAttachments": false,
        "protocolUrl": null,
        "createdAt": "2026-01-01T12:00:00.000Z",
        "statusChangedAt": "eingegangen"
      }
    ]
  }
}

Mögliche Fehler-Status: 400, 401, 404, 429

support

GET /support

List submission support counts

Cursor-paginated list of per-submission support tallies. Filter by submission ID to narrow down.

NameInErforderlichBeschreibung
cursorqueryneinstring
limitqueryneininteger
submission_idqueryneinstring

Anfrage

curl -H "Authorization: Bearer sk_example_0000000000000000" https://api.decidio.de/api/v1/support

Antwort (200)

{
  "data": [
    {
      "submissionId": "example",
      "referenceNumber": null,
      "supportCount": 1,
      "createdAt": "2026-01-01T12:00:00.000Z"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}

Mögliche Fehler-Status: 400, 401, 429

surveys

GET /surveys/{id}/results

Fetch survey results

Aggregated, anonymized survey results scoped to the API key’s municipality.

NameInErforderlichBeschreibung
idpathjastring — Resource UUID

Anfrage

curl -H "Authorization: Bearer sk_example_0000000000000000" https://api.decidio.de/api/v1/surveys/00000000-0000-0000-0000-000000000001/results

Antwort (200)

{
  "data": {
    "surveyId": "example",
    "title": "Beispiel-Umfrage",
    "status": "eingegangen",
    "totalResponses": 1,
    "questions": [
      {
        "questionText": "Beispielfrage?",
        "questionType": "single_choice",
        "options": [
          {
            "optionText": "Option A",
            "responseCount": 1
          }
        ]
      }
    ]
  }
}

Mögliche Fehler-Status: 400, 401, 404, 429

Fehler

Fehler folgen einem einheitlichen Envelope mit error (Klartext) und code (Maschinen-ID):

  • 400 BAD_REQUEST — ungültige Query-Parameter oder Cursor.
  • 401 UNAUTHORIZED — fehlender oder ungültiger API-Schlüssel.
  • 404 NOT_FOUND — Ressource existiert nicht oder ist nicht sichtbar für den Mandanten.
  • 429 RATE_LIMITED — Ratenfenster ausgeschöpft. Lesen Sie Retry-After und wiederholen Sie die Anfrage nach Ablauf.
{
  "error": "Invalid API key",
  "code": "UNAUTHORIZED"
}

OpenAPI-Dokument

Diese Referenz wird aus einem maschinenlesbaren OpenAPI-3.1-Dokument generiert. Sie können das Dokument direkt herunterladen:

https://decidio.de/openapi.json