D
beaconDeutschlandGPT
Docs

API Reference

Explore the public Beacon API. All endpoints return JSON responses and require no authentication.

Health Check

GET/api/health

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

Response

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

NameTypeRequiredDescription
tagstringNoFilter by tag. One of: api, chat, workflows.
sincestringNoOnly return changelogs newer than this semantic version (e.g. "1.2.3").
breakingstringNoFilter by breaking changes. "true" or "false".
limitintegerNoNumber of entries to return. Defaults to 25. Min: 1, Max: 100.
offsetintegerNoNumber of entries to skip. Defaults to 0.

Response

Returns an array of published changelog objects, each containing version info, content, tags, and timestamps.

json
[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "New API Rate Limiting",
    "content": "We've introduced rate limiting across all public endpoints...",
    "version": "2.14.0",
    "status": "published",
    "versionType": "minor",
    "tags": ["api"],
    "isBreakingChange": false,
    "publishedAt": "2026-02-13T18:45:00.000Z",
    "createdAt": "2026-02-13T12:00:00.000Z",
    "updatedAt": "2026-02-13T18:45:00.000Z"
  }
]

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

NameTypeRequiredDescription
idUUIDYesThe unique identifier of the changelog.

Response

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

json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "New API Rate Limiting",
  "content": "We've introduced rate limiting across all public endpoints...",
  "version": "2.14.0",
  "status": "published",
  "versionType": "minor",
  "tags": ["api"],
  "isBreakingChange": false,
  "publishedAt": "2026-02-13T18:45:00.000Z",
  "createdAt": "2026-02-13T12:00:00.000Z",
  "updatedAt": "2026-02-13T18:45:00.000Z"
}

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.

Response

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.

Response

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.

Request Body

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

Response

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 recent check history.

Response

Returns an array of monitor objects with their current status, response metrics, and up to 90 recent check results in the history array.

json
[
  {
    "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
    "name": "API Server",
    "description": "Main API health check",
    "url": "https://api.example.com/health",
    "group": "Core Services",
    "currentStatus": "operational",
    "responseTime": 42,
    "statusCode": 200,
    "lastChecked": "2026-02-14T10:22:15.000Z",
    "history": [
      {
        "status": "operational",
        "checkedAt": "2026-02-14T10:22:15.000Z",
        "responseTime": 42
      }
    ]
  }
]