Provider Announcement API

OpenAPI 3.1 reference for relay sites publishing public announcements to Hvoy AI.

Method

GET

Recommended endpoint

/api/provider/announcements

Schema Version

1.0

Optional HMAC authentication

Sign the current Unix-seconds timestamp with HMAC-SHA256. The accepted clock skew is 60 seconds.

X-Hvoy-Ts: 1747886400
X-Hvoy-Sign: 88ce4832...e6becbc

Response requirements

Return exact HTTP 200, UTF-8 application/json, Cache-Control: no-store, and an uncompressed body no larger than 512 KiB within 10 seconds.

response

Field	Type	Rule	Description
schema_version	string	Required	Protocol version; always 1.0 for v1.
success	boolean	Required	Always true for a successful snapshot.
message	string	Optional	Optional information; normally an empty string on success.
data	object	Required	The complete current announcement snapshot.

data

Field	Type	Rule	Description
notice	string	Required	The site-wide notice; use an empty string when absent. Internal line breaks are preserved.
announcements	array	Required	Current announcements; use an empty array when absent, up to 500 records.

data.announcements[]

Field	Type	Rule	Description
id	string	Required	Stable, never-reused ID matching [A-Za-z0-9._:-]{1,160}.
title	string	Optional	Optional plain-text title, at most 120 Unicode code points.
content	string	Required	Required plain text, at most 900 Unicode code points; internal line breaks are preserved.
publishDate	string	Optional	Optional timezone-aware timestamp in the restricted ISO 8601 format.
type	string	Optional	Optional type. Standard values are general, maintenance, incident, pricing, and promotion; unknown nonempty values are normalized to general.

Success example

{
  "schema_version": "1.0",
  "success": true,
  "message": "",
  "data": {
    "notice": "Planned maintenance\n02:00-03:00 UTC",
    "announcements": [
      {
        "id": "incident-20260805-001",
        "title": "Service recovery",
        "content": "The affected channel has recovered.\nRequests are operating normally.",
        "publishDate": "2026-08-05T09:30:00Z",
        "type": "incident"
      }
    ]
  }
}