{ "openapi": "3.1.0", "info": { "title": "Volter World platform", "version": "1", "description": "The hosted product's doors: orgs, worlds, members, billing, tokens, activity, support, and the operator's. Every twin's vendor API and every world's own endpoints are under the world's address, documented in the HTTP API reference." }, "servers": [ { "url": "{platform}", "variables": { "platform": { "default": "https://app.example.com", "description": "the platform's origin: Volter's cloud, or one you run" } } } ], "components": { "securitySchemes": { "session": { "type": "apiKey", "in": "cookie", "name": "volter_console_session", "description": "a signed-in browser session: the platform's own, started by signing in with its access provider" }, "token": { "type": "http", "scheme": "bearer", "description": "a personal token (tok_p_), an org token (tok_o_) or a support session (tok_su_), with scopes object:action" }, "operatorToken": { "type": "apiKey", "in": "header", "name": "x-volter-token", "description": "the platform's operator token" } } }, "paths": { "/-/health": { "get": { "summary": "Whether the platform is up, and which hosts it knows.", "description": "Who: anyone. Answers { ok, hosts[] }.", "security": [], "responses": { "200": { "description": "{ ok, hosts[] }" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/.well-known/jwks.json": { "get": { "summary": "The public keys this platform signs passes with, for the hosts that trust it.", "description": "Who: anyone. Answers { keys[] }.", "security": [], "responses": { "200": { "description": "{ keys[] }" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/platform": { "get": { "summary": "What the pages need before anyone signs in: the access provider people continue with (and their account page there, when it has one), whether the platform bills, whether the Help form is on, and the product site's address when there is one.", "description": "Who: anyone. Answers { name, provider: { kind, name, account? }, billing, support, site? }.", "security": [], "responses": { "200": { "description": "{ name, provider: { kind, name, account? }, billing, support, site? }" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/sign-in": { "get": { "summary": "Start signing in at the access provider (the authorization code with PKCE); `?next=` names a path of this platform to return to.", "description": "Who: anyone. Answers 302 to the provider.", "security": [], "responses": { "200": { "description": "302 to the provider" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/sign-out": { "post": { "summary": "End your session here (not at the provider), from the platform's own page (a GET is refused with 405).", "description": "Who: anyone. Answers 302 to the front page.", "security": [], "responses": { "200": { "description": "302 to the front page" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/status": { "get": { "summary": "The status page's source: each host up or down, the operator's notice, the clock's last runs.", "description": "Who: anyone. Answers { ok, platform, hosts[], notice, clock, askedAt }.", "security": [], "responses": { "200": { "description": "{ ok, platform, hosts[], notice, clock, askedAt }" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/status/notice": { "post": { "summary": "Set or clear the notice the status page shows.", "description": "Who: operator. Answers { notice }.", "security": [ { "operatorToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ text | null }" } } } }, "responses": { "200": { "description": "{ notice }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/openapi.json": { "get": { "summary": "This table as an OpenAPI 3.1 document.", "description": "Who: anyone. Answers OpenAPI.", "security": [], "responses": { "200": { "description": "OpenAPI" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/vendors": { "get": { "summary": "The twins a new World may have: what the host Worlds are made on serves, as it answers.", "description": "Who: person. Answers { host, vendors[] }.", "security": [ { "session": [] }, { "token": [] } ], "responses": { "200": { "description": "{ host, vendors[] }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/worlds": { "get": { "summary": "The worlds your orgs hold that you reach, with their addresses, twins and how many changesets have landed in each (landed, when the World answered).", "description": "Who: person. A token needs `worlds:read`. Answers { worlds[] }.", "security": [ { "session": [] }, { "token": [ "worlds:read" ] } ], "responses": { "200": { "description": "{ worlds[] }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } }, "post": { "summary": "Provision a world into an org, on an enrolled host; where the platform bills, refused at the plan's limits with 402.", "description": "Who: person. A token needs `worlds:write`. Answers { name, base, host }.", "security": [ { "session": [] }, { "token": [ "worlds:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ org, world, vendors[] }" } } } }, "responses": { "200": { "description": "{ name, base, host }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/worlds/sample": { "post": { "summary": "Make the org's sample World (`/sample`, Stripe and Slack where the host serves them) and seed it through the vendors' own APIs: a World like any other, metered and deletable; 409 when it exists.", "description": "Who: person. A token needs `worlds:write`. Answers { name, base, host, seeded: { : { seeded[] } | { error } } }.", "security": [ { "session": [] }, { "token": [ "worlds:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ org }" } } } }, "responses": { "200": { "description": "{ name, base, host, seeded: { : { seeded[] } | { error } } }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/worlds/{org}/{world}": { "delete": { "summary": "Delete a world through its host.", "description": "Who: admin. A token needs `worlds:write`. Answers { deleted }.", "security": [ { "session": [] }, { "token": [ "worlds:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "world", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ deleted }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/worlds/{org}/{world}/open": { "get": { "summary": "Open the world as yourself: a pass for it, signed for you and for the world's own origin, spent on a session there (write for a member, read for a support session or a token without worlds:write); 409 for a world whose host gives it no origin of its own. A redirect to the page with the pass in its fragment; JSON asks for the address.", "description": "Who: person. A token needs `worlds:read`. Answers 303 to the world's page, or { url, scope, expiresIn }.", "security": [ { "session": [] }, { "token": [ "worlds:read" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "world", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "303 to the world's page, or { url, scope, expiresIn }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/worlds/{org}/{world}/previews": { "get": { "summary": "The world's previews: named branches made for CI (a pull request each), with where each lives and a link that opens it.", "description": "Who: person. A token needs `worlds:read`. Answers { world, previews: [{ label, branch, expiresAt, open, live, base?, origin? }] }.", "security": [ { "session": [] }, { "token": [ "worlds:read" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "world", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ world, previews: [{ label, branch, expiresAt, open, live, base?, origin? }] }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/worlds/{org}/{world}/previews/{label}": { "put": { "summary": "Make a preview: a branch of the world named `label` (pr-12), made with a key the platform mints in the world for the caller (for the person; recorded against the token that asked, so logout, revoking the token or leaving the org ends the preview); ends after ttlDays (7 by default, at most 7). Answers a key to the branch for a token (never the branch's own token; none for a browser session). Asked again, the same preview and a fresh key, unless replace asks for a fresh one; at most 20 previews of a world at once (409).", "description": "Who: person. A token needs `worlds:write`. Answers 201 { label, branch, base, origin?, open, token?, expiresAt, created: true }, or 200 with created: false.", "security": [ { "session": [] }, { "token": [ "worlds:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "world", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "label", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ ttlDays?: 1-7, replace?: true }" } } } }, "responses": { "200": { "description": "201 { label, branch, base, origin?, open, token?, expiresAt, created: true }, or 200 with created: false" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } }, "delete": { "summary": "Remove a preview and its branch (a pull request closed).", "description": "Who: person. A token needs `worlds:write`. Answers { removed, branch }.", "security": [ { "session": [] }, { "token": [ "worlds:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "world", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "label", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ removed, branch }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/worlds/{org}/{world}/previews/{label}/open": { "get": { "summary": "Open a preview as yourself: a pass for its branch, as opening the world gives one; 410 once it has ended.", "description": "Who: person. A token needs `worlds:read`. Answers 303 to the preview's page, or { url, scope, expiresIn }.", "security": [ { "session": [] }, { "token": [ "worlds:read" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "world", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "label", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "303 to the preview's page, or { url, scope, expiresIn }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/cli/device": { "post": { "summary": "Begin signing the volter command in through the browser (the device authorization grant): a code for the person to approve, and where.", "description": "Who: anyone. Answers { device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval }.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ name? }" } } } }, "responses": { "200": { "description": "{ device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval }" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/cli/approve": { "get": { "summary": "The page where a signed-in person approves or refuses a code the volter command shows (signing in first when needed).", "description": "Who: person. Answers a page.", "security": [ { "session": [] }, { "token": [] } ], "responses": { "200": { "description": "a page" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } }, "post": { "summary": "Approve or refuse a code, from the approval page itself in a signed-in browser (never with a token, never a support session).", "description": "Who: person. Answers a page.", "security": [ { "session": [] }, { "token": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "form: code, decision (approve or deny)" } } } }, "responses": { "200": { "description": "a page" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/cli/token": { "post": { "summary": "The volter command collects its personal token once the person approved its code (30 days, named for the machine, scoped orgs:read, worlds:read and worlds:write); authorization_pending until then.", "description": "Who: anyone. Answers { token, name, expiresAt, person }.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ device_code }" } } } }, "responses": { "200": { "description": "{ token, name, expiresAt, person }" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/worlds/{org}/{world}/keys": { "post": { "summary": "Make a key in a World of your org, for an app or a job, shown once: for you, ending in 90 days unless you say otherwise, and revoked when you leave the org; made with a personal token, it ends no later than the token and is revoked with it. A browser session on the World itself makes no keys.", "description": "Who: person. A token needs `worlds:write`. Answers { world, base, id, name, scope, expiresAt, key }.", "security": [ { "session": [] }, { "token": [ "worlds:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "world", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ name, scope?: read | write, expiresInDays?: 1-365 | null }" } } } }, "responses": { "200": { "description": "{ world, base, id, name, scope, expiresAt, key }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/worlds/{org}/{world}/access": { "get": { "summary": "Who reaches the world: the whole org, or only the listed members (admins always). A world kept from the caller answers 404.", "description": "Who: admin. A token needs `members:read`. Answers { world, restricted, members: [userId] }.", "security": [ { "session": [] }, { "token": [ "members:read" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "world", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ world, restricted, members: [userId] }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } }, "put": { "summary": "Keep the world to named members, or open it to the whole org again. Keeping it revokes, at once, the world keys held there by the members it leaves out (and the previews those keys made). Webhook: world.access_changed.", "description": "Who: admin. A token needs `members:write`. Answers { world, restricted, members, revokedFor }.", "security": [ { "session": [] }, { "token": [ "members:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "world", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ restricted: boolean, members?: [userId] }" } } } }, "responses": { "200": { "description": "{ world, restricted, members, revokedFor }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/worlds/{org}/{world}/token": { "get": { "summary": "A named key for the volter command (`volter remote add`), made in the world and shown once: for a token only, never a browser or a support session; write for a token with worlds:write, else read. Listed and revoked alone in the world's Settings.", "description": "Who: person. A token needs `worlds:read`. Answers { name, base, scope, token, keyId }.", "security": [ { "session": [] }, { "token": [ "worlds:read" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "world", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ name, base, scope, token, keyId }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/orgs": { "get": { "summary": "Who you are and the orgs you belong to, each with its worlds, security switches and whether it is held, and the invitations to your address still pending, where the provider keeps them.", "description": "Who: person. A token needs `orgs:read`. Answers { person, orgs[], invitations[] }.", "security": [ { "session": [] }, { "token": [ "orgs:read" ] } ], "responses": { "200": { "description": "{ person, orgs[], invitations[] }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } }, "post": { "summary": "Create an org, you its admin; where the platform has a site, its terms accepted. A name the pages use (account, help, new, …) is refused.", "description": "Who: person. A token needs `orgs:write`. Answers { id, slug, name }.", "security": [ { "session": [] }, { "token": [ "orgs:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ name, accepted? }" } } } }, "responses": { "200": { "description": "{ id, slug, name }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/invitations/{id}/join": { "post": { "summary": "Join the org a pending invitation to your address names, in its role, when your identity owns that address.", "description": "Who: person. A token needs `orgs:write`. Answers { joined, role }.", "security": [ { "session": [] }, { "token": [ "orgs:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ joined, role }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/orgs/{org}": { "get": { "summary": "The org and its worlds.", "description": "Who: person. A token needs `orgs:read`. Answers { id, slug, name, role, worlds[] }.", "security": [ { "session": [] }, { "token": [ "orgs:read" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ id, slug, name, role, worlds[] }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } }, "patch": { "summary": "Rename the org (the display name only; the address stays).", "description": "Who: admin. A token needs `orgs:write`. Answers { id, name }.", "security": [ { "session": [] }, { "token": [ "orgs:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ name }" } } } }, "responses": { "200": { "description": "{ id, name }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } }, "delete": { "summary": "Delete the org; refused while it holds worlds unless `?everything=1`, which deletes them through their hosts first.", "description": "Who: admin. A token needs `orgs:write`. Answers { deleted }.", "security": [ { "session": [] }, { "token": [ "orgs:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ deleted }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/orgs/{org}/billing": { "get": { "summary": "Where the platform bills: the org's plan, usage this period (and by day), restriction, pending checkout, the plans on offer.", "description": "Who: person. A token needs `billing:read`. Answers { plan, plans[], usage, usageByDay[], restriction, pendingCheckout, paid, lastTickAt }.", "security": [ { "session": [] }, { "token": [ "billing:read" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ plan, plans[], usage, usageByDay[], restriction, pendingCheckout, paid, lastTickAt }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } }, "patch": { "summary": "Where the platform bills, the spend cap (Team): on, the plan's hours restrict after the grace; off, hours beyond the plan are billed at the metered price.", "description": "Who: admin. A token needs `billing:write`. Answers { spendCap }.", "security": [ { "session": [] }, { "token": [ "billing:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ spendCap: boolean }" } } } }, "responses": { "200": { "description": "{ spendCap }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/orgs/{org}/checkout": { "post": { "summary": "Where the platform bills: open (or answer the open) Polar checkout for the Team plan.", "description": "Who: admin. A token needs `billing:write`. Answers { id, url, pending? }.", "security": [ { "session": [] }, { "token": [ "billing:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ id, url, pending? }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/orgs/{org}/billing-portal": { "post": { "summary": "Where the platform bills: a session for Polar's customer portal: invoices, payment method, cancellation.", "description": "Who: admin. A token needs `billing:write`. Answers { url }.", "security": [ { "session": [] }, { "token": [ "billing:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ url }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/orgs/{org}/members": { "get": { "summary": "The members and their roles, and the pending invitations.", "description": "Who: person. A token needs `members:read`. Answers { members[], pending[] }.", "security": [ { "session": [] }, { "token": [ "members:read" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ members[], pending[] }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } }, "post": { "summary": "Add a member the directory knows, or invite an address it does not (pending until that address signs in; mailed), as a member or (by an admin) an admin. Members may invite by email when the security page allows; adding by id is an admin's, and answers to the approved domains by the person's address. Not both at once.", "description": "Who: admin. A token needs `members:write`. Answers { added } | { invited, pending: true, id }.", "security": [ { "session": [] }, { "token": [ "members:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ email, role? } | { sub, role? }" } } } }, "responses": { "200": { "description": "{ added } | { invited, pending: true, id }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/orgs/{org}/members/{userId}": { "patch": { "summary": "Change a member's role; the org's only admin may not become a member (409).", "description": "Who: admin. A token needs `members:write`. Answers { userId, role }.", "security": [ { "session": [] }, { "token": [ "members:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ role: admin | member }" } } } }, "responses": { "200": { "description": "{ userId, role }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } }, "delete": { "summary": "Remove a member (an admin), or leave the org yourself (any member); the org's only admin cannot be removed or leave.", "description": "Who: admin. A token needs `members:write`. Answers { removed }.", "security": [ { "session": [] }, { "token": [ "members:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ removed }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/orgs/{org}/invitations/{id}/resend": { "post": { "summary": "Send a pending invitation again: a fresh one to the same address and role, for another week (its id may change). An admin, or a member where the security page lets members invite, for a member's invitation only; the approved domains apply.", "description": "Who: admin. A token needs `members:write`. Answers { invited, pending, id, role, expiresAt }.", "security": [ { "session": [] }, { "token": [ "members:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ invited, pending, id, role, expiresAt }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/orgs/{org}/invitations/{id}": { "delete": { "summary": "Revoke a pending invitation.", "description": "Who: admin. A token needs `members:write`. Answers { revoked }.", "security": [ { "session": [] }, { "token": [ "members:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ revoked }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/orgs/{org}/tokens": { "get": { "summary": "The org's tokens (for CI), without their secrets.", "description": "Who: admin. A token needs `tokens:read`. Answers { tokens[] }.", "security": [ { "session": [] }, { "token": [ "tokens:read" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ tokens[] }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } }, "post": { "summary": "Make an org token: bound to the org, scoped (read only by default), expiring; shown once.", "description": "Who: admin. A token needs `tokens:write`. Answers { token, id, scopes, expiresAt }.", "security": [ { "session": [] }, { "token": [ "tokens:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ name, scopes?, expiresInDays? }" } } } }, "responses": { "200": { "description": "{ token, id, scopes, expiresAt }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/orgs/{org}/tokens/{id}": { "delete": { "summary": "Revoke an org token.", "description": "Who: admin. A token needs `tokens:write`. Answers { revoked }.", "security": [ { "session": [] }, { "token": [ "tokens:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ revoked }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/orgs/{org}/security": { "get": { "summary": "The org's security switches.", "description": "Who: person. A token needs `orgs:read`. Answers { security }.", "security": [ { "session": [] }, { "token": [ "orgs:read" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ security }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } }, "patch": { "summary": "Set the switches: members may invite, personal tokens allowed, approved email domains.", "description": "Who: admin. A token needs `orgs:write`. Answers { security }.", "security": [ { "session": [] }, { "token": [ "orgs:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ membersCanInvite?, membersCanUsePersonalTokens?, approvedEmailDomains? }" } } } }, "responses": { "200": { "description": "{ security }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/orgs/{org}/support-access": { "get": { "summary": "Whether, and until when, support may open the org.", "description": "Who: person. A token needs `orgs:read`. Answers { supportAccess }.", "security": [ { "session": [] }, { "token": [ "orgs:read" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ supportAccess }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } }, "delete": { "summary": "Revoke support access.", "description": "Who: admin. A token needs `orgs:write`. Answers { revoked }.", "security": [ { "session": [] }, { "token": [ "orgs:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ revoked }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/orgs/{org}/labs": { "get": { "summary": "The early-access features, which are on for the org, and the early-adopter switch.", "description": "Who: person. A token needs `orgs:read`. Answers { features[], earlyAdopter, flags }.", "security": [ { "session": [] }, { "token": [ "orgs:read" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ features[], earlyAdopter, flags }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } }, "patch": { "summary": "Turn an early-access feature on or off, or turn on every new one with the early-adopter switch.", "description": "Who: admin. A token needs `orgs:write`. Answers { flags, earlyAdopter }.", "security": [ { "session": [] }, { "token": [ "orgs:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ flags?: { key: boolean }, earlyAdopter? }" } } } }, "responses": { "200": { "description": "{ flags, earlyAdopter }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/orgs/{org}/webhooks": { "get": { "summary": "The org's webhook endpoints and their state, and the event names.", "description": "Who: admin. A token needs `orgs:read`. Answers { webhooks[], events[] }.", "security": [ { "session": [] }, { "token": [ "orgs:read" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ webhooks[], events[] }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } }, "post": { "summary": "Add an endpoint: a URL and the events it wants; the secret is answered once (Standard Webhooks signing).", "description": "Who: admin. A token needs `orgs:write`. Answers { id, url, events, secret }.", "security": [ { "session": [] }, { "token": [ "orgs:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ url, events?: [\"*\" | names], description? }" } } } }, "responses": { "200": { "description": "{ id, url, events, secret }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/orgs/{org}/webhooks/{id}": { "patch": { "summary": "Change an endpoint's events or description, or enable/disable it.", "description": "Who: admin. A token needs `orgs:write`. Answers { id, … }.", "security": [ { "session": [] }, { "token": [ "orgs:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ events?, description?, enabled? }" } } } }, "responses": { "200": { "description": "{ id, … }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } }, "delete": { "summary": "Remove an endpoint.", "description": "Who: admin. A token needs `orgs:write`. Answers { deleted }.", "security": [ { "session": [] }, { "token": [ "orgs:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ deleted }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/orgs/{org}/webhooks/{id}/test": { "post": { "summary": "Send a `ping` event now and answer the delivery with its attempt.", "description": "Who: admin. A token needs `orgs:write`. Answers { delivery }.", "security": [ { "session": [] }, { "token": [ "orgs:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ delivery }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/orgs/{org}/webhooks/{id}/deliveries": { "get": { "summary": "The endpoint's last fifty deliveries, each attempt with its status and the response's first 2 KB.", "description": "Who: admin. A token needs `orgs:read`. Answers { deliveries[] }.", "security": [ { "session": [] }, { "token": [ "orgs:read" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ deliveries[] }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/orgs/{org}/audit": { "get": { "summary": "The org's activity: every admin act, newest first.", "description": "Who: admin. A token needs `activity:read`. Answers { entries[] }.", "security": [ { "session": [] }, { "token": [ "activity:read" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ entries[] }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/orgs/{org}/audit.jsonl": { "get": { "summary": "The activity as the file kept, one act a line.", "description": "Who: admin. A token needs `activity:read`. Answers JSON lines.", "security": [ { "session": [] }, { "token": [ "activity:read" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON lines" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/orgs/{org}/export": { "get": { "summary": "What the platform knows about the org: the record, the worlds, the members, the activity.", "description": "Who: admin. A token needs `activity:read`. Answers JSON.", "security": [ { "session": [] }, { "token": [ "activity:read" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/tokens": { "get": { "summary": "Your personal access tokens, without their secrets.", "description": "Who: person. A token needs `tokens:read`. Answers { tokens[] }.", "security": [ { "session": [] }, { "token": [ "tokens:read" ] } ], "responses": { "200": { "description": "{ tokens[] }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } }, "post": { "summary": "Make a personal access token: scoped, expiring (30 days by default); shown once.", "description": "Who: person. A token needs `tokens:write`. Answers { token, id, scopes, expiresAt }.", "security": [ { "session": [] }, { "token": [ "tokens:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ name, expiresInDays?, scopes? }" } } } }, "responses": { "200": { "description": "{ token, id, scopes, expiresAt }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/tokens/{id}": { "delete": { "summary": "Revoke one of your tokens.", "description": "Who: person. A token needs `tokens:write`. Answers { revoked }.", "security": [ { "session": [] }, { "token": [ "tokens:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ revoked }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/support": { "post": { "summary": "Write to support; an admin may allow support to open the org for a while.", "description": "Who: person. A token needs `orgs:write`. Answers { id, at, emailed, copyTo, access }.", "security": [ { "session": [] }, { "token": [ "orgs:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ category, severity, subject, message, org?, world?, allowAccessDays? }" } } } }, "responses": { "200": { "description": "{ id, at, emailed, copyTo, access }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/operator/sweep-members": { "post": { "summary": "Revoke, in every org's Worlds, the keys (and the branches they made) of people who are no longer members of that org: someone removed at the identity service directly, not through the platform. The clock runs it hourly.", "description": "Who: operator. Answers { revoked }.", "security": [ { "operatorToken": [] } ], "responses": { "200": { "description": "{ revoked }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/meter/tick": { "post": { "summary": "Run the hourly billing tick now (the clock runs it on its own); 404 where the platform does not bill.", "description": "Who: operator. Answers { ticked, worlds, inserted, duplicates, restrictions }.", "security": [ { "operatorToken": [] } ], "responses": { "200": { "description": "{ ticked, worlds, inserted, duplicates, restrictions }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/backup": { "post": { "summary": "Archive the platform's state to the bucket now (the clock does it nightly).", "description": "Who: operator. Answers { key, bytes }.", "security": [ { "operatorToken": [] } ], "responses": { "200": { "description": "{ key, bytes }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/backups": { "get": { "summary": "The archives in the bucket.", "description": "Who: operator. Answers { keys[] }.", "security": [ { "operatorToken": [] } ], "responses": { "200": { "description": "{ keys[] }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/restore": { "post": { "summary": "Restore the platform's state from an archive.", "description": "Who: operator. Answers { files }.", "security": [ { "operatorToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ key }" } } } }, "responses": { "200": { "description": "{ files }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/hosts": { "get": { "summary": "The hosts enrolled.", "description": "Who: operator. Answers { hosts[] }.", "security": [ { "operatorToken": [] } ], "responses": { "200": { "description": "{ hosts[] }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } }, "post": { "summary": "Enroll a host by address: its admin endpoints must answer the token.", "description": "Who: operator. Answers { id, base }.", "security": [ { "operatorToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ id, base, adminToken }" } } } }, "responses": { "200": { "description": "{ id, base }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/hosts/{id}": { "delete": { "summary": "Stop provisioning onto a host; its worlds stay where they are.", "description": "Who: operator. Answers { removed }.", "security": [ { "operatorToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ removed }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/operator/overview": { "get": { "summary": "The operator's page source: orgs with plan, restriction, worlds, hosts and consents; support requests; the clock.", "description": "Who: operator. Answers { orgs[], support[], hosts[], clock, notice }.", "security": [ { "operatorToken": [] } ], "responses": { "200": { "description": "{ orgs[], support[], hosts[], clock, notice }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/operator/unclaimed": { "get": { "summary": "The worlds enrolled hosts serve that no org holds (made on a host before the platform, or on the host itself).", "description": "Who: operator. Answers { worlds: [{ host, name, twins, owner? }] }.", "security": [ { "operatorToken": [] } ], "responses": { "200": { "description": "{ worlds: [{ host, name, twins, owner? }] }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/operator/claim": { "post": { "summary": "Claim a world an enrolled host serves into an org whose slug it is served under: without `confirm: true` only when its host already records that org as its owner (slugs are first come), and never when the host records another. The host records the owner; its apps keep their token. Recorded in the org's activity.", "description": "Who: operator. Answers { name, org, host }.", "security": [ { "operatorToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ world, org, confirm? }" } } } }, "responses": { "200": { "description": "{ name, org, host }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/operator/open-org": { "post": { "summary": "A one-hour read-only support session for an org that has allowed it, with a category and a reason; recorded in the org's activity.", "description": "Who: operator. Answers { token, until, console }.", "security": [ { "operatorToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ org, category, reason }" } } } }, "responses": { "200": { "description": "{ token, until, console }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } }, "/-/operator/support/{id}": { "patch": { "summary": "Close or reopen a support request.", "description": "Who: operator. Answers { request }.", "security": [ { "operatorToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "{ status: open | closed }" } } } }, "responses": { "200": { "description": "{ request }" }, "401": { "description": "sign in, or the token expired" }, "403": { "description": "not yours, held by the org's security, or the token lacks the scope (named)" }, "429": { "description": "rate limited; Retry-After and X-RateLimit-* say when" } } } } } }