DDeutschlandGPT
Dokumentation

API-Referenz

Erkunden Sie die öffentliche Beacon-API. Alle Endpunkte geben JSON-Antworten zurück und erfordern keine Authentifizierung.

TypeScript SDK

Bevorzugen Sie einen typsicheren Client gegenüber direkten HTTP-Aufrufen? Installieren Sie das offizielle Beacon SDK und interagieren Sie mit allen Endpunkten über eine einfache, typisierte API.

Installation

bash
pnpm add @deutschlandgpt/beacon-sdk

Schnellstart

typescript
import { BeaconClient } from "@deutschlandgpt/beacon-sdk";

const beacon = new BeaconClient({
  baseUrl: "https://your-beacon-instance.com",
});

const changelogs = await beacon.changelogs.list();

Auf npm ansehen: @deutschlandgpt/beacon-sdk

Health Check

GET/api/health

Returns the current health status of the API. Useful for uptime monitoring and liveness probes.

Antwort

Returns a JSON object with the current status of the API.

json
{
  "status": "ok"
}

List Changelogs

GET/api/v1/changelogs

Returns a list of published changelogs. Supports filtering by tag, version, and breaking changes, with pagination via limit and offset.

Query Parameters

NameTypErforderlichBeschreibung
tagstringNeinFilter by tag. One of: api, chat, workflows.
sincestringNeinOnly return changelogs newer than this semantic version (e.g. "1.2.3").
breakingstringNeinFilter by breaking changes. "true" or "false".
limitintegerNeinNumber of entries to return. Defaults to 25. Min: 1, Max: 100.
offsetintegerNeinNumber of entries to skip. Defaults to 0.

Antwort

Returns an array of published changelog objects, each containing version info, the title and content in the requested locale, tags, and timestamps. headerImage is a signed URL or null. features lists the headline changes in order, each with a title, a Markdown description and optional media (type image or video, signed url, optional posterUrl for videos, width and height when known).

json
[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "version": "2.14.0",
    "versionType": "minor",
    "isBreakingChange": false,
    "headerImage": null,
    "publishedAt": "2026-02-13T18:45:00.000Z",
    "updatedAt": "2026-02-13T18:45:00.000Z",
    "title": "New API Rate Limiting",
    "content": "We've introduced rate limiting across all public endpoints...",
    "features": [
      {
        "title": "Rate limits per API key",
        "description": "Each key now has its own quota...",
        "media": {
          "type": "video",
          "url": "https://storage.example.de/...",
          "posterUrl": "https://storage.example.de/...",
          "width": 1920,
          "height": 1080
        }
      }
    ],
    "tags": [
      { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "name": "api", "color": "#3b82f6" }
    ]
  }
]

Get Changelog

GET/api/v1/changelogs/:id

Returns a single published changelog by its ID. Returns 404 if the changelog does not exist or is not published.

Path Parameters

NameTypErforderlichBeschreibung
idUUIDJaThe unique identifier of the changelog.

Antwort

Returns a single changelog object. Returns 404 if the changelog is not found or not published.

json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "version": "2.14.0",
  "versionType": "minor",
  "isBreakingChange": false,
  "headerImage": null,
  "publishedAt": "2026-02-13T18:45:00.000Z",
  "updatedAt": "2026-02-13T18:45:00.000Z",
  "title": "New API Rate Limiting",
  "content": "We've introduced rate limiting across all public endpoints...",
  "features": [],
  "tags": [
    { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "name": "api", "color": "#3b82f6" }
  ]
}

Changelogs RSS Feed

GET/api/v1/changelogs/rss

Returns an RSS 2.0 feed of published changelogs. Use this URL in any feed reader to track new releases. Requires the changelog feature to be enabled.

Antwort

Returns RSS 2.0 XML with Content-Type application/rss+xml. Returns 403 if the changelog feature is disabled.

xml
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
  <channel>
    <title>Changelog</title>
    <link>https://example.com/changelogs</link>
    <description>Latest product changelog entries</description>
    <lastBuildDate>Tue, 18 Feb 2026 12:00:00 GMT</lastBuildDate>
    <item>
      <title>v2.14.0 - New API Rate Limiting</title>
      <link>https://example.com/changelogs</link>
      <description><![CDATA[We've introduced rate limiting...]]></description>
      <pubDate>Thu, 13 Feb 2026 18:45:00 GMT</pubDate>
      <guid isPermaLink="false">a1b2c3d4-e5f6-7890-abcd-ef1234567890</guid>
      <category>api</category>
    </item>
  </channel>
</rss>

Incidents RSS Feed

GET/api/v1/incidents/rss

Returns an RSS 2.0 feed of published incidents. Use this URL in any feed reader to track service incidents and outages. Requires the incident feature to be enabled.

Query Parameters

NameTypErforderlichBeschreibung
localestringNeinLanguage of titles and descriptions. One of: de, en, ar, es, hu, pl, sk, tr, uk, zh. Incidents are machine-translated shortly after they are published or changed; until then, and without this parameter, the original text is returned.

Antwort

Returns RSS 2.0 XML with Content-Type application/rss+xml. Returns 403 if the incident feature is disabled.

xml
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
  <channel>
    <title>Incidents</title>
    <link>https://example.com/status</link>
    <description>Service incident reports and status updates</description>
    <lastBuildDate>Tue, 18 Feb 2026 12:00:00 GMT</lastBuildDate>
    <item>
      <title>[CRITICAL] Database connectivity issues</title>
      <link>https://example.com/status</link>
      <description><![CDATA[Database connection pool exhausted...

Status: monitoring]]></description>
      <pubDate>Tue, 18 Feb 2026 09:30:00 GMT</pubDate>
      <guid isPermaLink="false">f1e2d3c4-b5a6-7890-abcd-ef1234567890</guid>
    </item>
  </channel>
</rss>

Subscribe

POST/api/v1/subscribers

Registers a new email subscriber. The subscriber will receive updates based on the selected subscription types.

Anfragekörper

email must be a valid email address. subscribeTo is an array with at least one value from: changelogs, status_updates, newsletters.

json
{
  "email": "user@example.com",
  "subscribeTo": ["changelogs", "status_updates"]
}

Antwort

Returns 201 on success. Returns 400 with validation details if the request body is invalid.

json
{
  "success": true
}

Get Monitor Status

GET/api/v1/monitors/status

Returns the current status of all monitors, including response times and a daily uptime history.

Antwort

Returns an array of monitor objects with their current status, response metrics, the uptime over the last 90 days (null without checks), and one entry per day for those 90 days in the dailySummaries array.

json
[
  {
    "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
    "name": "API Server",
    "description": "Main API health check",
    "group": "Core Services",
    "currentStatus": "operational",
    "responseTime": 42,
    "statusCode": 200,
    "lastChecked": "2026-02-14T10:22:15.000Z",
    "uptimePercent": "99.95",
    "dailySummaries": [
      {
        "date": "2026-02-14",
        "status": "operational",
        "totalChecks": 288,
        "operationalChecks": 288,
        "degradedChecks": 0,
        "outageChecks": 0,
        "avgResponseTimeMs": 45
      }
    ]
  }
]