ЗОРЯ

Завдання/OpenAPI

OpenAPI частини 1

Zaria Battle.net, part 1 · 1.0.0. Машинний контракт API частини 1. Той самий файл сервер віддає на GET /openapi.json.

HTTP API of the Zaria Battle.net for the part 1 client. All routes are relative to /api/v1; bodies are JSON. Authorization: Bearer <token> from register or login. Errors are {"error":{"code","field?"}}; 5xx also carry requestId. CORS: participant routes accept bearer requests without cookies from any origin and answer Access-Control-Allow-Origin: *. A request that carries a cookie from a foreign origin is refused (403 origin-not-allowed). The organizer desk is not part of this contract and accepts only configured origins. Retry-After and X-Request-Id are exposed to browsers. Ether: until the registration window the hub answers every route here except /auth/login with noise or a sealed Envelope (HTTP 200 on /ether and /ether/roll, 503 elsewhere). Only an Envelope whose Ed25519 seal verifies with the published public key is a signal. GET /ether/key returns that key without noise; check its fingerprint against the task text. 429 is never noise: wait Retry-After seconds and retry the same request. Codes are jammed (the address is jammed for exceeding 20 requests per minute), rate-limited (account or login/registration limit exceeded) and authentication-busy (password check queue is full on /auth/register and /auth/login, Retry-After: 5, not a rate-limit strike). Unknown response fields may appear; ignore them.

Маршрути

GET/public/config Season settings and the GitHub account to inviteбез токена
Відповіді
200Success Config400Stable error code Error401Stable error code Error403Stable error code Error404Stable error code Error409Stable error code Error413Stable error code Error415Stable error code Error422Stable error code Error429Stable error code Error500Stable error code Error503Stable error code Envelope | Error
POST/auth/register Register during the window with a repository from the admission list; optional lang (uk or en, default uk) sets the language of server texts; returns a sessionбез токена
Тіло запиту
ПолеТипЩо означає
username обов'язковоstring
password обов'язковоstring
displayName обов'язковоstring
repositoryUrl обов'язковоstring
lang"uk" | "en" uk en
Відповіді
201Success Session400Stable error code Error401Stable error code Error403Stable error code Error404Stable error code Error409Stable error code Error413Stable error code Error415Stable error code Error422Stable error code Error429Stable error code Error500Stable error code Error503Stable error code Envelope | Error
POST/auth/login Create a bearer sessionбез токена
Тіло запиту
ПолеТипЩо означає
username обов'язковоstring
password обов'язковоstring
Відповіді
200Success Session400Stable error code Error401Stable error code Error403Stable error code Error404Stable error code Error409Stable error code Error413Stable error code Error415Stable error code Error422Stable error code Error429Stable error code Error500Stable error code Error503Stable error code Envelope | Error
POST/auth/logout Revoke the current session or tokenпотрібен токен
Тіло запиту
ПолеТипЩо означає
Відповіді
204Success400Stable error code Error401Stable error code Error403Stable error code Error404Stable error code Error409Stable error code Error413Stable error code Error415Stable error code Error422Stable error code Error429Stable error code Error500Stable error code Error503Stable error code Envelope | Error
GET/me Own accountпотрібен токен
Відповіді
200Success object400Stable error code Error401Stable error code Error403Stable error code Error404Stable error code Error409Stable error code Error413Stable error code Error415Stable error code Error422Stable error code Error429Stable error code Error500Stable error code Error503Stable error code Envelope | Error
PATCH/me Change own settings: lang (uk or en) of server texts, letters and admission reasonsпотрібен токен
Тіло запиту
ПолеТипЩо означає
lang"uk" | "en" uk en
Відповіді
200Success object400Stable error code Error401Stable error code Error403Stable error code Error404Stable error code Error409Stable error code Error413Stable error code Error415Stable error code Error422Stable error code Error429Stable error code Error500Stable error code Error503Stable error code Envelope | Error
GET/me/repository Own repository and its access reviewпотрібен токен
Відповіді
200Success object400Stable error code Error401Stable error code Error403Stable error code Error404Stable error code Error409Stable error code Error413Stable error code Error415Stable error code Error422Stable error code Error429Stable error code Error500Stable error code Error503Stable error code Envelope | Error
PUT/me/repository Change the repository; login sessions only (client tokens get 403); a new URL resets the review to pendingпотрібен токен
Тіло запиту
ПолеТипЩо означає
url обов'язковоstring
Відповіді
200Success object400Stable error code Error401Stable error code Error403Stable error code Error404Stable error code Error409Stable error code Error413Stable error code Error415Stable error code Error422Stable error code Error429Stable error code Error500Stable error code Error503Stable error code Envelope | Error
GET/me/summary Cheap poll: counters and change stampsпотрібен токен
Відповіді
200Success Summary400Stable error code Error401Stable error code Error403Stable error code Error404Stable error code Error409Stable error code Error413Stable error code Error415Stable error code Error422Stable error code Error429Stable error code Error500Stable error code Error503Stable error code Envelope | Error
GET/news Published news, pagedпотрібен токен
Параметри
ПолеТипЩо означає
limitinteger query
offsetinteger query
Відповіді
200Success object400Stable error code Error401Stable error code Error403Stable error code Error404Stable error code Error409Stable error code Error413Stable error code Error415Stable error code Error422Stable error code Error429Stable error code Error500Stable error code Error503Stable error code Envelope | Error
GET/inbox Own deliveries, pagedпотрібен токен
Параметри
ПолеТипЩо означає
limitinteger query
offsetinteger query
Відповіді
200Success object400Stable error code Error401Stable error code Error403Stable error code Error404Stable error code Error409Stable error code Error413Stable error code Error415Stable error code Error422Stable error code Error429Stable error code Error500Stable error code Error503Stable error code Envelope | Error
GET/inbox/{id} One delivery; reading does not mark it readпотрібен токен
Параметри
ПолеТипЩо означає
id обов'язковоstring path
Відповіді
200Success object400Stable error code Error401Stable error code Error403Stable error code Error404Stable error code Error409Stable error code Error413Stable error code Error415Stable error code Error422Stable error code Error429Stable error code Error500Stable error code Error503Stable error code Envelope | Error
POST/inbox/{id}/read Mark a delivery readпотрібен токен
Параметри
ПолеТипЩо означає
id обов'язковоstring path
Тіло запиту
ПолеТипЩо означає
Відповіді
200Success object400Stable error code Error401Stable error code Error403Stable error code Error404Stable error code Error409Stable error code Error413Stable error code Error415Stable error code Error422Stable error code Error429Stable error code Error500Stable error code Error503Stable error code Envelope | Error
GET/stages Released task parts: excerpts instead of bodiesпотрібен токен
Відповіді
200Success object400Stable error code Error401Stable error code Error403Stable error code Error404Stable error code Error409Stable error code Error413Stable error code Error415Stable error code Error422Stable error code Error429Stable error code Error500Stable error code Error503Stable error code Envelope | Error
GET/stages/{id} One released part with body and errata; an unreleased ID is 404потрібен токен
Параметри
ПолеТипЩо означає
id обов'язковоstring path
Відповіді
200Success object400Stable error code Error401Stable error code Error403Stable error code Error404Stable error code Error409Stable error code Error413Stable error code Error415Stable error code Error422Stable error code Error429Stable error code Error500Stable error code Error503Stable error code Envelope | Error
POST/stages/{id}/ack Acknowledge receipt; it releases nothingпотрібен токен
Параметри
ПолеТипЩо означає
id обов'язковоstring path
Тіло запиту
ПолеТипЩо означає
Відповіді
200Success object400Stable error code Error401Stable error code Error403Stable error code Error404Stable error code Error409Stable error code Error413Stable error code Error415Stable error code Error422Stable error code Error429Stable error code Error500Stable error code Error503Stable error code Envelope | Error
POST/developer/check Authenticated exact Unicode JSON echoпотрібен токен
Тіло запиту
ПолеТипЩо означає
echo обов'язковоstring
Відповіді
200Success object400Stable error code Error401Stable error code Error403Stable error code Error404Stable error code Error409Stable error code Error413Stable error code Error415Stable error code Error422Stable error code Error429Stable error code Error500Stable error code Error503Stable error code Envelope | Error
GET/ether Listen to the ether: noise before the window, or a sealed Envelopeбез токена
Відповіді
200Success Envelope400Stable error code Error401Stable error code Error403Stable error code Error404Stable error code Error409Stable error code Error413Stable error code Error415Stable error code Error422Stable error code Error429Stable error code Error500Stable error code Error503Stable error code Envelope | Error
GET/ether/roll On-air log: public order of coming on air, as a sealed Envelopeбез токена
Відповіді
200Success Envelope400Stable error code Error401Stable error code Error403Stable error code Error404Stable error code Error409Stable error code Error413Stable error code Error415Stable error code Error422Stable error code Error429Stable error code Error500Stable error code Error503Stable error code Envelope | Error
GET/ether/key Seal public key: algorithm, key id, raw Ed25519 key and its SHA-256 fingerprint; never noise, outside the ether rate limitбез токена
Відповіді
200Success EtherKey400Stable error code Error401Stable error code Error403Stable error code Error404Stable error code Error409Stable error code Error413Stable error code Error415Stable error code Error422Stable error code Error429Stable error code Error500Stable error code Error503Stable error code Envelope | Error

Схеми

Config

ПолеТипЩо означає
apiVersion обов'язковоobject
title обов'язковоstring
season обов'язковоstring
registrationOpen обов'язковоboolean
inviteRequired обов'язковоboolean
repositoryRequired обов'язковоboolean
repositoryAccess обов'язковоobject | null
webClient обов'язковоboolean

Envelope

Sealed ether frame. seal is an Ed25519 signature of the UTF-8 bytes of the frame string, base64url without padding; key is the first 16 hex digits of SHA-256 of the raw public key. Verify before parsing frame.

ПолеТипЩо означає
frame обов'язковоstring
seal обов'язковоstring
key обов'язковоstring

Error

ПолеТипЩо означає
error обов'язковоobject

EtherKey

Seal public key. publicKey is the raw 32-byte Ed25519 key in base64url without padding; fingerprint is SHA-256 of those 32 bytes in hex, key its first 16 digits. Compare fingerprint with the task text before trusting the key.

ПолеТипЩо означає
algorithm обов'язковоobject
key обов'язковоstring
publicKey обов'язковоstring
fingerprint обов'язковоstring

Frame

ПолеТипЩо означає
v обов'язковоobject
kind обов'язково"signal" | "roll" signal roll
station обов'язковоobject
at обов'язковоstring (date-time)
phase обов'язково"static" | "window" | "after" static window after
window обов'язковоobject | null
harbinger обов'язковоobject | null
fragment обов'язковоobject | null
onAir обов'язковоinteger
rollRollEntry[]

Message

ПолеТипЩо означає
id обов'язковоstring (uuid)
messageId обов'язковоstring | null
stageId обов'язковоstring | null
kind обов'язково"message" | "stage" message stage
title обов'язковоstring
body обов'язковоstring
createdAt обов'язковоstring (date-time)
readAt обов'язковоstring | null
notice обов'язковоNotice | null

News

ПолеТипЩо означає
id обов'язковоstring (uuid)
title обов'язковоstring
body обов'язковоstring
createdAt обов'язковоstring (date-time)
updatedAt обов'язковоstring (date-time)
publishedAt обов'язковоstring | null
archivedAt обов'язковоstring | null

Notice

Typed notification generated by the hub. In part 1 the type is repository: every change of your repository status. Show an unknown type as a plain message by its title and body.

RepositoryNotice | object

Repository

ПолеТипЩо означає
url обов'язковоstring
accessStatus обов'язково"pending" | "verified" | "needs-attention" pending verified needs-attention
checkedAt обов'язковоstring | null
reason обов'язковоstring | nullIn the account language; a decision made by the organizer keeps the organizer text
reasonCode обов'язково"inviter-mismatch" | "marker-found" | "marker-other" | "marker-absent" | "organizer" | nullMachine reason: inviter-mismatch (the invitation came from another GitHub account), marker-found (.zoria names this account), marker-other (.zoria names another account), marker-absent (no .zoria yet), organizer (decided by the organizer by hand, reason is the organizer text); null - none inviter-mismatch marker-found marker-other marker-absent organizer null
updatedAt обов'язковоstring (date-time)
verifiedElsewhere обов'язковоboolean

RepositoryNotice

ПолеТипЩо означає
type обов'язковоobject
url обов'язковоstring
accessStatus обов'язково"pending" | "verified" | "needs-attention" pending verified needs-attention
reason обов'язковоstring | null
reasonCode обов'язково"inviter-mismatch" | "marker-found" | "marker-other" | "marker-absent" | "organizer" | nullMachine reason: inviter-mismatch (the invitation came from another GitHub account), marker-found (.zoria names this account), marker-other (.zoria names another account), marker-absent (no .zoria yet), organizer (decided by the organizer by hand, reason is the organizer text); null - none inviter-mismatch marker-found marker-other marker-absent organizer null

RollEntry

ПолеТипЩо означає
n обов'язковоinteger
at обов'язковоstring (date-time)
sinceOpen обов'язковоinteger
name обов'язковоstring

Session

ПолеТипЩо означає
token обов'язковоstring
sessionId обов'язковоstring (uuid)
expiresAt обов'язковоstring (date-time)
user обов'язковоUser

Stage

ПолеТипЩо означає
id обов'язковоstring (uuid)
position обов'язковоinteger
title обов'язковоstring
body обов'язковоstring
publishedAt обов'язковоstring (date-time)
releasedAt обов'язковоstring (date-time)
acknowledgedAt обов'язковоstring | null
errata обов'язковоstring | null
errataAt обов'язковоstring | null

StageSummary

ПолеТипЩо означає
id обов'язковоstring (uuid)
position обов'язковоinteger
title обов'язковоstring
excerpt обов'язковоstring
publishedAt обов'язковоstring (date-time)
releasedAt обов'язковоstring (date-time)
acknowledgedAt обов'язковоstring | null
errataAt обов'язковоstring | null

Summary

Cheap poll. repositoryAt moves on every change of your repository or its review: reread /me/repository only then. The server may add fields of later parts; ignore unknown fields.

ПолеТипЩо означає
unread обов'язковоinteger
releasedStages обов'язковоinteger
acknowledgedStages обов'язковоinteger
latestNews обов'язковоstring | null
repositoryAt обов'язковоstring | null
serverTime обов'язковоstring (date-time)

User

ПолеТипЩо означає
id обов'язковоstring (uuid)
username обов'язковоstring
displayName обов'язковоstring
role обов'язково"admin" | "participant" admin participant
disabled обов'язковоboolean
createdAt обов'язковоstring (date-time)
lang обов'язково"uk" | "en"Language of server texts for this account: letters and admission reasons uk en