{ "components": { "schemas": { "Error": { "properties": { "code": { "description": "Stable and machine readable.", "type": "string" }, "message": { "description": "In the reader's language.", "type": "string" }, "requestId": { "description": "Quote this when reporting a problem.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "securitySchemes": { "stygionToken": { "description": "A STYGION token. Free, tied to an account, revocable.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Everything STYGION serves over HTTP. Errors always come back as code, message and requestId; anything a person reads follows accept-language.", "title": "STYGION API", "version": "dev" }, "openapi": "3.1.0", "paths": { "/api/v1/account/delete": { "post": { "operationId": "identity.deleteAccount", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "confirm": { "description": "The account's own display name", "type": "string" } }, "required": [ "confirm" ], "type": "object" } } }, "required": true }, "responses": { "204": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "security": [ { "stygionToken": [ "identity.read" ] } ], "summary": "Deletes the account that asked, for good. What they wrote to us stays and loses its author.", "tags": [ "identity" ] } }, "/api/v1/account/devices": { "get": { "operationId": "identity.devices", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "address": { "type": "string" }, "current": { "type": "boolean" }, "id": { "type": "string" }, "lastSeen": { "type": "string" }, "name": { "type": "string" }, "since": { "type": "string" }, "team": { "type": "boolean" } }, "required": [ "id", "name", "current", "since", "lastSeen" ], "type": "object" }, "type": "array" } }, "required": [ "items" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "security": [ { "stygionToken": [ "identity.read" ] } ], "summary": "Everywhere this account is signed in.", "tags": [ "identity" ] } }, "/api/v1/account/devices/approve": { "post": { "operationId": "identity.approveDevice", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "The code the program showed", "type": "string" }, "phrase": { "description": "For team access: the phrase the asking app shows (six digits).", "type": "string" }, "team": { "description": "True when approving team access", "type": "boolean" } }, "required": [ "code" ], "type": "object" } } }, "required": true }, "responses": { "204": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "security": [ { "stygionToken": [ "identity.read" ] } ], "summary": "Lets a program in, as you.", "tags": [ "identity" ] } }, "/api/v1/account/devices/claim": { "post": { "operationId": "identity.claimDevice", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "secret": { "type": "string" } }, "required": [ "code", "secret" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "accountId": { "type": "string" }, "name": { "type": "string" }, "token": { "type": "string" } }, "required": [ "token", "accountId", "name" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "The program collecting the token it was allowed, once.", "tags": [ "identity" ] } }, "/api/v1/account/devices/link": { "post": { "operationId": "identity.linkDevice", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "app": { "description": "What is asking", "type": "string" }, "device": { "description": "The machine it runs on", "type": "string" }, "team": { "description": "Ask for team access (STYGION Admin). Only a team account can approve it.", "type": "boolean" } }, "required": [ "app" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "expiresAt": { "type": "string" }, "phrase": { "type": "string" }, "secret": { "type": "string" }, "url": { "type": "string" } }, "required": [ "code", "secret", "url", "expiresAt" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "A downloaded program asking to be connected to an account.", "tags": [ "identity" ] } }, "/api/v1/account/devices/revoke": { "post": { "operationId": "identity.revokeDevice", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "id": { "type": "string" } }, "required": [ "id" ], "type": "object" } } }, "required": true }, "responses": { "204": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "security": [ { "stygionToken": [ "identity.read" ] } ], "summary": "Signs one device out.", "tags": [ "identity" ] } }, "/api/v1/account/devices/revoke-all": { "post": { "operationId": "identity.signOutEverywhere", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": true }, "responses": { "204": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "security": [ { "stygionToken": [ "identity.read" ] } ], "summary": "Signs out every device on this account, the launcher included.", "tags": [ "identity" ] } }, "/api/v1/account/devices/waiting": { "get": { "operationId": "identity.deviceWaiting", "parameters": [ { "in": "query", "name": "code", "required": false, "schema": { "description": "The code the program showed", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "address": { "type": "string" }, "agent": { "type": "string" }, "app": { "type": "string" }, "asked": { "type": "string" }, "country": { "type": "string" }, "device": { "type": "string" }, "needsPhrase": { "type": "boolean" }, "region": { "type": "string" }, "signInAgain": { "type": "boolean" }, "team": { "type": "boolean" } }, "required": [ "app", "asked", "team", "needsPhrase", "signInAgain" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "security": [ { "stygionToken": [ "identity.read" ] } ], "summary": "What a program is asking to be allowed, before you allow it.", "tags": [ "identity" ] } }, "/api/v1/account/export": { "get": { "operationId": "identity.export", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "account": { "additionalProperties": false, "properties": { "deleted": { "type": "string" }, "id": { "type": "string" }, "locale": { "type": "string" }, "name": { "type": "string" }, "since": { "type": "string" }, "team": { "type": "boolean" } }, "required": [ "id", "name", "locale", "team", "since" ], "type": "object" }, "devices": { "items": { "additionalProperties": false, "properties": { "address": { "type": "string" }, "current": { "type": "boolean" }, "id": { "type": "string" }, "lastSeen": { "type": "string" }, "name": { "type": "string" }, "since": { "type": "string" }, "team": { "type": "boolean" } }, "required": [ "id", "name", "current", "since", "lastSeen" ], "type": "object" }, "type": "array" }, "feedback": { "items": { "additionalProperties": false, "properties": { "body": { "type": "string" }, "id": { "type": "string" }, "kind": { "type": "string" }, "state": { "type": "string" }, "title": { "type": "string" }, "visibility": { "type": "string" }, "written": { "type": "string" } }, "required": [ "id", "kind", "title", "state", "visibility", "written" ], "type": "object" }, "type": "array" }, "links": { "items": { "additionalProperties": false, "properties": { "avatar": { "type": "string" }, "handle": { "type": "string" }, "last": { "type": "boolean" }, "provider": { "type": "string" }, "since": { "type": "string" } }, "required": [ "provider" ], "type": "object" }, "type": "array" }, "ranks": { "items": { "additionalProperties": false, "properties": { "expires": { "type": "string" }, "player": { "type": "string" }, "tier": { "type": "string" }, "world": { "type": "string" } }, "required": [ "world", "tier", "expires" ], "type": "object" }, "type": "array" }, "ratings": { "items": { "additionalProperties": false, "properties": { "helpful": { "type": "boolean" }, "page": { "type": "string" }, "written": { "type": "string" } }, "required": [ "page", "helpful", "written" ], "type": "object" }, "type": "array" }, "replies": { "items": { "additionalProperties": false, "properties": { "body": { "type": "string" }, "entry": { "type": "string" }, "written": { "type": "string" } }, "required": [ "entry", "body", "written" ], "type": "object" }, "type": "array" }, "takenAt": { "type": "string" } }, "required": [ "takenAt", "account", "links", "devices", "feedback", "replies", "ranks", "ratings" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "security": [ { "stygionToken": [ "identity.read" ] } ], "summary": "Everything we hold about the account that asked, in one object.", "tags": [ "identity" ] } }, "/api/v1/account/links": { "get": { "operationId": "identity.links", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "avatar": { "type": "string" }, "handle": { "type": "string" }, "last": { "type": "boolean" }, "provider": { "type": "string" }, "since": { "type": "string" } }, "required": [ "provider" ], "type": "object" }, "type": "array" } }, "required": [ "items" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "security": [ { "stygionToken": [ "identity.read" ] } ], "summary": "Which providers are joined to the account that asked.", "tags": [ "identity" ] } }, "/api/v1/account/links/begin": { "post": { "operationId": "identity.linkProvider", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "provider": { "description": "One of discord / microsoft / github / google.", "type": "string" }, "surface": { "description": "site or workspace. Left out it is the site.", "type": "string" } }, "required": [ "provider" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "state": { "description": "Hand this back when they return.", "type": "string" }, "url": { "description": "Where to send the person to sign in.", "type": "string" } }, "required": [ "url", "state" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "security": [ { "stygionToken": [ "identity.read" ] } ], "summary": "Starts joining another provider to the account that asked.", "tags": [ "identity" ] } }, "/api/v1/account/links/remove": { "post": { "operationId": "identity.unlinkProvider", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "provider": { "type": "string" } }, "required": [ "provider" ], "type": "object" } } }, "required": true }, "responses": { "204": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "security": [ { "stygionToken": [ "identity.read" ] } ], "summary": "Takes a provider off the account, unless it is the last way in.", "tags": [ "identity" ] } }, "/api/v1/articles": { "get": { "operationId": "content.articles", "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "description": "From the previous page's next.", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "description": "How many to return. Up to 50.", "type": "string" } }, { "in": "query", "name": "tag", "required": false, "schema": { "description": "Only articles carrying this tag.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "author": { "additionalProperties": false, "properties": { "avatar": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "body": { "type": "string" }, "cover": { "additionalProperties": false, "properties": { "alt": { "type": "string" }, "src": { "type": "string" } }, "required": [ "src", "alt" ], "type": "object" }, "id": { "type": "string" }, "product": { "type": "string" }, "publishedAt": { "type": "string" }, "readingMinutes": { "type": "integer" }, "slug": { "type": "string" }, "summary": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "slug", "title", "summary", "publishedAt", "tags" ], "type": "object" }, "type": "array" }, "next": { "type": "string" } }, "required": [ "items" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "What we have written, newest first, in the reader's language.", "tags": [ "content" ] } }, "/api/v1/articles/{slug}": { "get": { "operationId": "content.article", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "description": "The article's address in either language.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "author": { "additionalProperties": false, "properties": { "avatar": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "body": { "type": "string" }, "cover": { "additionalProperties": false, "properties": { "alt": { "type": "string" }, "src": { "type": "string" } }, "required": [ "src", "alt" ], "type": "object" }, "id": { "type": "string" }, "product": { "type": "string" }, "publishedAt": { "type": "string" }, "readingMinutes": { "type": "integer" }, "slug": { "type": "string" }, "summary": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "slug", "title", "summary", "publishedAt", "tags" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "One article, with everything it says.", "tags": [ "content" ] } }, "/api/v1/auth/begin": { "post": { "operationId": "identity.beginSignIn", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "provider": { "description": "One of discord / microsoft / github / google.", "type": "string" }, "surface": { "description": "site or workspace. Left out it is the site.", "type": "string" } }, "required": [ "provider" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "state": { "description": "Hand this back when they return.", "type": "string" }, "url": { "description": "Where to send the person to sign in.", "type": "string" } }, "required": [ "url", "state" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Starts signing in with a provider and says where to send the person.", "tags": [ "identity" ] } }, "/api/v1/auth/complete": { "post": { "operationId": "identity.completeSignIn", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "address": { "type": "string" }, "code": { "type": "string" }, "device": { "type": "string" }, "state": { "type": "string" } }, "required": [ "state", "code" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "accountId": { "type": "string" }, "linked": { "description": "Whether this joined a provider to an account that was already signed in.", "type": "boolean" }, "new": { "description": "Whether this sign-in created the account.", "type": "boolean" }, "session": { "description": "The session token. Shown once", "type": "string" } }, "required": [ "session", "accountId", "new" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Finishes signing in and hands back a session.", "tags": [ "identity" ] } }, "/api/v1/auth/sign-out": { "post": { "operationId": "identity.signOut", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": true }, "responses": { "204": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Signs out the device that asked, and only that one.", "tags": [ "identity" ] } }, "/api/v1/badges": { "get": { "operationId": "badges.catalog", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "categories": { "items": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "type": "array" }, "items": { "items": { "additionalProperties": false, "properties": { "animation": { "type": "string" }, "art": { "type": "string" }, "category": { "type": "string" }, "current": { "type": "boolean" }, "group": { "type": "string" }, "how": { "type": "string" }, "icon": { "type": "string" }, "id": { "type": "string" }, "manual": { "type": "boolean" }, "name": { "type": "string" }, "of": { "type": "integer" }, "progress": { "type": "integer" }, "quiet": { "type": "boolean" }, "reason": { "type": "string" }, "ref": { "type": "string" }, "retired": { "type": "boolean" }, "season": { "type": "string" }, "seasonName": { "type": "string" }, "secret": { "type": "boolean" }, "serial": { "type": "integer" }, "step": { "type": "integer" }, "tiers": { "items": { "additionalProperties": false, "properties": { "backfill": { "type": "boolean" }, "metal": { "type": "string" }, "new": { "type": "boolean" }, "rarity": { "type": "number" }, "threshold": { "type": "integer" }, "unlockedAt": { "type": "string" } }, "required": [ "metal" ], "type": "object" }, "type": "array" } }, "required": [ "id", "category", "icon", "name", "how", "ref", "tiers" ], "type": "object" }, "type": "array" }, "season": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" } }, "required": [ "categories", "items" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Every badge there is and what it asks for, with nobody's progress in it.", "tags": [ "badges" ] } }, "/api/v1/badges/leaderboard": { "get": { "operationId": "badges.leaderboard", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "description": "How many places", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "description": "How many places to skip. 0 is the top.", "type": "integer" } }, { "in": "query", "name": "season", "required": false, "schema": { "description": "Empty: all badges ever. 'current': the season running now. Or a season id (world:key).", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "account": { "type": "string" }, "badges": { "type": "integer" }, "gold": { "type": "integer" }, "honours": { "items": { "additionalProperties": false, "properties": { "animation": { "type": "string" }, "art": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "of": { "type": "integer" }, "seasonName": { "type": "string" }, "serial": { "type": "integer" } }, "required": [ "id", "name", "serial", "of" ], "type": "object" }, "type": "array" }, "name": { "type": "string" }, "player": { "type": "string" }, "rank": { "type": "integer" }, "rarest": { "items": { "additionalProperties": false, "properties": { "animation": { "type": "string" }, "art": { "type": "string" }, "icon": { "type": "string" }, "id": { "type": "string" }, "manual": { "type": "boolean" }, "metal": { "type": "string" }, "name": { "type": "string" }, "rarity": { "type": "number" }, "seasonName": { "type": "string" }, "secret": { "type": "boolean" } }, "required": [ "id", "name", "icon", "metal", "rarity" ], "type": "object" }, "type": "array" }, "score": { "type": "integer" } }, "required": [ "rank", "account", "name", "score", "badges", "gold", "rarest", "honours" ], "type": "object" }, "type": "array" }, "me": { "additionalProperties": false, "properties": { "account": { "type": "string" }, "badges": { "type": "integer" }, "gold": { "type": "integer" }, "honours": { "items": { "additionalProperties": false, "properties": { "animation": { "type": "string" }, "art": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "of": { "type": "integer" }, "seasonName": { "type": "string" }, "serial": { "type": "integer" } }, "required": [ "id", "name", "serial", "of" ], "type": "object" }, "type": "array" }, "name": { "type": "string" }, "player": { "type": "string" }, "rank": { "type": "integer" }, "rarest": { "items": { "additionalProperties": false, "properties": { "animation": { "type": "string" }, "art": { "type": "string" }, "icon": { "type": "string" }, "id": { "type": "string" }, "manual": { "type": "boolean" }, "metal": { "type": "string" }, "name": { "type": "string" }, "rarity": { "type": "number" }, "seasonName": { "type": "string" }, "secret": { "type": "boolean" } }, "required": [ "id", "name", "icon", "metal", "rarity" ], "type": "object" }, "type": "array" }, "score": { "type": "integer" } }, "required": [ "rank", "account", "name", "score", "badges", "gold", "rarest", "honours" ], "type": "object" }, "next": { "type": "integer" }, "players": { "type": "integer" }, "season": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "seasons": { "items": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "type": "array" }, "total": { "type": "integer" }, "updatedAt": { "type": "string" } }, "required": [ "updatedAt", "players", "seasons", "total", "items" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "The public badge board: who shares publicly, ranked by points for rare badges. Nobody needs to sign in.", "tags": [ "badges" ] } }, "/api/v1/badges/mine": { "get": { "operationId": "badges.mine", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "categories": { "items": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "type": "array" }, "counts": { "additionalProperties": false, "properties": { "brass": { "type": "integer" }, "copper": { "type": "integer" }, "gold": { "type": "integer" }, "total": { "type": "integer" }, "unlocked": { "type": "integer" } }, "required": [ "unlocked", "total", "copper", "brass", "gold" ], "type": "object" }, "enabled": { "type": "boolean" }, "hidden": { "items": { "type": "string" }, "type": "array" }, "items": { "items": { "additionalProperties": false, "properties": { "animation": { "type": "string" }, "art": { "type": "string" }, "category": { "type": "string" }, "current": { "type": "boolean" }, "group": { "type": "string" }, "how": { "type": "string" }, "icon": { "type": "string" }, "id": { "type": "string" }, "manual": { "type": "boolean" }, "name": { "type": "string" }, "of": { "type": "integer" }, "progress": { "type": "integer" }, "quiet": { "type": "boolean" }, "reason": { "type": "string" }, "ref": { "type": "string" }, "retired": { "type": "boolean" }, "season": { "type": "string" }, "seasonName": { "type": "string" }, "secret": { "type": "boolean" }, "serial": { "type": "integer" }, "step": { "type": "integer" }, "tiers": { "items": { "additionalProperties": false, "properties": { "backfill": { "type": "boolean" }, "metal": { "type": "string" }, "new": { "type": "boolean" }, "rarity": { "type": "number" }, "threshold": { "type": "integer" }, "unlockedAt": { "type": "string" } }, "required": [ "metal" ], "type": "object" }, "type": "array" } }, "required": [ "id", "category", "icon", "name", "how", "ref", "tiers" ], "type": "object" }, "type": "array" }, "onBoard": { "type": "boolean" }, "season": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "showcase": { "items": { "type": "string" }, "type": "array" }, "visibility": { "type": "string" } }, "required": [ "enabled", "visibility", "onBoard", "showcase", "hidden", "categories", "items", "counts" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Your badges, your progress and what you chose to show. Opening them counts anything new.", "tags": [ "badges" ] } }, "/api/v1/badges/people/{account}": { "get": { "operationId": "badges.of", "parameters": [ { "in": "path", "name": "account", "required": true, "schema": { "description": "The STYGION ID account id.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "account": { "type": "string" }, "categories": { "items": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "type": "array" }, "counts": { "additionalProperties": false, "properties": { "brass": { "type": "integer" }, "copper": { "type": "integer" }, "gold": { "type": "integer" }, "total": { "type": "integer" }, "unlocked": { "type": "integer" } }, "required": [ "unlocked", "total", "copper", "brass", "gold" ], "type": "object" }, "items": { "items": { "additionalProperties": false, "properties": { "animation": { "type": "string" }, "art": { "type": "string" }, "category": { "type": "string" }, "current": { "type": "boolean" }, "group": { "type": "string" }, "how": { "type": "string" }, "icon": { "type": "string" }, "id": { "type": "string" }, "manual": { "type": "boolean" }, "name": { "type": "string" }, "of": { "type": "integer" }, "progress": { "type": "integer" }, "quiet": { "type": "boolean" }, "reason": { "type": "string" }, "ref": { "type": "string" }, "retired": { "type": "boolean" }, "season": { "type": "string" }, "seasonName": { "type": "string" }, "secret": { "type": "boolean" }, "serial": { "type": "integer" }, "step": { "type": "integer" }, "tiers": { "items": { "additionalProperties": false, "properties": { "backfill": { "type": "boolean" }, "metal": { "type": "string" }, "new": { "type": "boolean" }, "rarity": { "type": "number" }, "threshold": { "type": "integer" }, "unlockedAt": { "type": "string" } }, "required": [ "metal" ], "type": "object" }, "type": "array" } }, "required": [ "id", "category", "icon", "name", "how", "ref", "tiers" ], "type": "object" }, "type": "array" }, "name": { "type": "string" }, "player": { "type": "string" }, "showcase": { "items": { "type": "string" }, "type": "array" } }, "required": [ "account", "name", "showcase", "categories", "items", "counts" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Somebody's badges, as far as they share them: public to anybody, friends-only to friends. Otherwise not found.", "tags": [ "badges" ] } }, "/api/v1/badges/players/{player}": { "get": { "operationId": "badges.player", "parameters": [ { "in": "path", "name": "player", "required": true, "schema": { "description": "The Minecraft name.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "honours": { "items": { "additionalProperties": false, "properties": { "animation": { "type": "string" }, "art": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "of": { "type": "integer" }, "seasonName": { "type": "string" }, "serial": { "type": "integer" } }, "required": [ "id", "name", "serial", "of" ], "type": "object" }, "type": "array" } }, "required": [ "honours" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "The rare badges given by hand to whoever plays under a Minecraft name on our world, if they share their badges with you.", "tags": [ "badges" ] } }, "/api/v1/badges/seen": { "post": { "operationId": "badges.seen", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "badges": { "description": "Badge ids. Empty marks everything new as seen.", "items": { "type": "string" }, "type": "array" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Marks new badges as seen, which clears the dot.", "tags": [ "badges" ] } }, "/api/v1/badges/settings": { "put": { "operationId": "badges.setSettings", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "enabled": { "description": "Count badges at all. Off keeps what was earned and shows it to nobody.", "type": "boolean" }, "hidden": { "description": "Badge ids nobody else ever sees (every season of them)", "items": { "type": "string" }, "type": "array" }, "onBoard": { "description": "Be on the public board. Off takes you off it; your collection stays as visible as visibility says.", "type": "boolean" }, "showcase": { "description": "Up to three earned badges shown first on your profile: an id", "items": { "type": "string" }, "type": "array" }, "visibility": { "description": "Who besides you sees your badges. Only public ones are on the board.", "enum": [ "public", "friends", "nobody" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "categories": { "items": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "type": "array" }, "counts": { "additionalProperties": false, "properties": { "brass": { "type": "integer" }, "copper": { "type": "integer" }, "gold": { "type": "integer" }, "total": { "type": "integer" }, "unlocked": { "type": "integer" } }, "required": [ "unlocked", "total", "copper", "brass", "gold" ], "type": "object" }, "enabled": { "type": "boolean" }, "hidden": { "items": { "type": "string" }, "type": "array" }, "items": { "items": { "additionalProperties": false, "properties": { "animation": { "type": "string" }, "art": { "type": "string" }, "category": { "type": "string" }, "current": { "type": "boolean" }, "group": { "type": "string" }, "how": { "type": "string" }, "icon": { "type": "string" }, "id": { "type": "string" }, "manual": { "type": "boolean" }, "name": { "type": "string" }, "of": { "type": "integer" }, "progress": { "type": "integer" }, "quiet": { "type": "boolean" }, "reason": { "type": "string" }, "ref": { "type": "string" }, "retired": { "type": "boolean" }, "season": { "type": "string" }, "seasonName": { "type": "string" }, "secret": { "type": "boolean" }, "serial": { "type": "integer" }, "step": { "type": "integer" }, "tiers": { "items": { "additionalProperties": false, "properties": { "backfill": { "type": "boolean" }, "metal": { "type": "string" }, "new": { "type": "boolean" }, "rarity": { "type": "number" }, "threshold": { "type": "integer" }, "unlockedAt": { "type": "string" } }, "required": [ "metal" ], "type": "object" }, "type": "array" } }, "required": [ "id", "category", "icon", "name", "how", "ref", "tiers" ], "type": "object" }, "type": "array" }, "onBoard": { "type": "boolean" }, "season": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "showcase": { "items": { "type": "string" }, "type": "array" }, "visibility": { "type": "string" } }, "required": [ "enabled", "visibility", "onBoard", "showcase", "hidden", "categories", "items", "counts" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Switches counting on or off, says who sees your badges, pins up to three and keeps any back.", "tags": [ "badges" ] } }, "/api/v1/catalog/{product}/features": { "get": { "operationId": "catalog.features", "parameters": [ { "in": "path", "name": "product", "required": true, "schema": { "description": "The product page", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "group": { "type": "string" }, "hidden": { "type": "boolean" }, "id": { "type": "string" }, "name": { "type": "string" }, "note": { "type": "string" }, "shipped": { "type": "boolean" }, "sort": { "type": "integer" }, "version": { "type": "string" } }, "required": [ "id", "name", "sort" ], "type": "object" }, "type": "array" }, "product": { "type": "string" } }, "required": [ "product", "items" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "What a product page says the thing does. A feature is marked as shipped only when a release actually carried it out.", "tags": [ "catalog" ] } }, "/api/v1/docs/markdown/{slug}": { "get": { "operationId": "docs.markdown", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "description": "The whole path", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "language": { "type": "string" }, "markdown": { "type": "string" }, "slug": { "type": "string" }, "summary": { "type": "string" }, "title": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "slug", "title", "language", "markdown" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "One documentation page as the markdown it is written in, in the reader's language where we have it. Same visibility as docs.page.", "tags": [ "docs" ] } }, "/api/v1/docs/outline": { "get": { "operationId": "docs.outline", "parameters": [ { "in": "query", "name": "audience", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "section", "required": false, "schema": { "description": "Only this section", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "sections": { "items": { "additionalProperties": false, "properties": { "audience": { "type": "string" }, "key": { "type": "string" }, "pages": { "items": { "additionalProperties": false, "properties": { "audience": { "type": "string" }, "draft": { "type": "boolean" }, "group": { "type": "string" }, "language": { "type": "string" }, "slug": { "type": "string" }, "sort": { "type": "integer" }, "summary": { "type": "string" }, "title": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "slug", "title", "audience", "sort" ], "type": "object" }, "type": "array" }, "sort": { "type": "integer" }, "summary": { "type": "string" }, "title": { "type": "string" } }, "required": [ "key", "title", "audience", "sort" ], "type": "object" }, "type": "array" }, "updatedAt": { "type": "string" } }, "required": [ "sections" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "The tree of the documentation, as this reader is allowed to see it.", "tags": [ "docs" ] } }, "/api/v1/docs/pages/{slug}": { "get": { "operationId": "docs.page", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "description": "The whole path", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "appliesTo": { "type": "string" }, "audience": { "type": "string" }, "body": { "type": "string" }, "draft": { "type": "boolean" }, "group": { "type": "string" }, "headings": { "items": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "level": { "type": "integer" }, "text": { "type": "string" } }, "required": [ "id", "text", "level" ], "type": "object" }, "type": "array" }, "language": { "type": "string" }, "section": { "type": "string" }, "slug": { "type": "string" }, "sort": { "type": "integer" }, "summary": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "slug", "section", "title", "body", "headings", "tags", "language", "audience", "sort" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "One documentation page, rendered, in the reader's language where we have it.", "tags": [ "docs" ] } }, "/api/v1/docs/rating": { "post": { "operationId": "docs.rate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "helpful": { "type": "boolean" }, "slug": { "type": "string" } }, "required": [ "slug", "helpful" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "helpful": { "type": "boolean" } }, "required": [ "helpful" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Did this page help? One bit, no comment box.", "tags": [ "docs" ] } }, "/api/v1/docs/search": { "get": { "operationId": "docs.search", "parameters": [ { "in": "query", "name": "audience", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "q", "required": false, "schema": { "description": "What to look for. Quotes and OR work.", "type": "string" } }, { "in": "query", "name": "section", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "hits": { "items": { "additionalProperties": false, "properties": { "audience": { "type": "string" }, "heading": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "text": { "type": "string" } }, "required": [ "id", "text" ], "type": "object" }, "language": { "type": "string" }, "score": { "type": "number" }, "section": { "type": "string" }, "slug": { "type": "string" }, "snippet": { "type": "string" }, "title": { "type": "string" } }, "required": [ "slug", "section", "title", "language", "audience", "score" ], "type": "object" }, "type": "array" } }, "required": [ "hits" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Search the documentation in both languages at once. A public search that finds nothing is counted, anonymously, so the team knows which page is missing.", "tags": [ "docs" ] } }, "/api/v1/feedback": { "get": { "operationId": "feedback.list", "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "kind", "required": false, "schema": { "description": "bug", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "mine", "required": false, "schema": { "description": "true for the asker's own items instead of the public board.", "type": "string" } }, { "in": "query", "name": "product", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "since", "required": false, "schema": { "description": "Only what was opened at or after this moment (RFC 3339", "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "description": "newest", "type": "string" } }, { "in": "query", "name": "source", "required": false, "schema": { "description": "Only what came in this way: web", "type": "string" } }, { "in": "query", "name": "state", "required": false, "schema": { "description": "new", "type": "string" } }, { "in": "query", "name": "type", "required": false, "schema": { "description": "Only what its writer said it was: feedback", "type": "string" } }, { "in": "query", "name": "until", "required": false, "schema": { "description": "Only what was opened before this moment (RFC 3339)", "type": "string" } }, { "in": "query", "name": "visibility", "required": false, "schema": { "description": "public (the default)", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "author": { "additionalProperties": false, "properties": { "avatar": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "body": { "type": "string" }, "createdAt": { "type": "string" }, "files": { "items": { "additionalProperties": false, "properties": { "bytes": { "type": "integer" }, "contentType": { "type": "string" }, "filename": { "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "filename", "contentType", "bytes", "href" ], "type": "object" }, "type": "array" }, "id": { "type": "string" }, "key": { "type": "string" }, "kind": { "type": "string" }, "merged": { "items": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "key": { "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "mergedInto": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "key": { "type": "string" } }, "required": [ "id" ], "type": "object" }, "mine": { "type": "boolean" }, "product": { "type": "string" }, "release": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "product": { "type": "string" }, "version": { "type": "string" } }, "required": [ "product", "version" ], "type": "object" }, "replies": { "items": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "body": { "type": "string" }, "by": { "additionalProperties": false, "properties": { "avatar": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "files": { "items": { "additionalProperties": false, "properties": { "bytes": { "type": "integer" }, "contentType": { "type": "string" }, "filename": { "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "filename", "contentType", "bytes", "href" ], "type": "object" }, "type": "array" }, "id": { "type": "string" }, "source": { "type": "string" }, "team": { "type": "boolean" } }, "required": [ "id", "body", "at" ], "type": "object" }, "type": "array" }, "source": { "type": "string" }, "state": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "updatedAt": { "type": "string" }, "visibility": { "type": "string" }, "voted": { "type": "boolean" }, "wanted": { "type": "integer" } }, "required": [ "id", "kind", "state", "title", "createdAt", "visibility", "wanted" ], "type": "object" }, "type": "array" }, "next": { "type": "string" } }, "required": [ "items" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "The public half of the queue: what people asked us for, in the open. The team may also ask for the private half (visibility=private|all) and filter by source, type and date.", "tags": [ "feedback" ] }, "post": { "operationId": "feedback.create", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "about": true, "anonymous": { "type": "boolean" }, "context": true, "kind": { "description": "bug or idea or question; may be left out when type says it.", "type": "string" }, "message": { "description": "What they wrote", "type": "string" }, "product": { "description": "Which of our things it is about", "type": "string" }, "source": { "description": "web", "type": "string" }, "title": { "type": "string" }, "type": { "description": "feedback or bug or feature or support.", "type": "string" }, "visibility": { "type": "string" } }, "required": [ "kind", "message" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "visibility": { "type": "string" } }, "required": [ "id", "visibility" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Files a report. Private unless the writer says otherwise.", "tags": [ "feedback" ] } }, "/api/v1/feedback/{id}": { "delete": { "operationId": "feedback.remove", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "security": [ { "stygionToken": [ "feedback.write" ] } ], "summary": "Takes an item back entirely. The writer can always do this.", "tags": [ "feedback" ] }, "get": { "operationId": "feedback.get", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "author": { "additionalProperties": false, "properties": { "avatar": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "body": { "type": "string" }, "createdAt": { "type": "string" }, "files": { "items": { "additionalProperties": false, "properties": { "bytes": { "type": "integer" }, "contentType": { "type": "string" }, "filename": { "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "filename", "contentType", "bytes", "href" ], "type": "object" }, "type": "array" }, "id": { "type": "string" }, "key": { "type": "string" }, "kind": { "type": "string" }, "merged": { "items": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "key": { "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "mergedInto": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "key": { "type": "string" } }, "required": [ "id" ], "type": "object" }, "mine": { "type": "boolean" }, "product": { "type": "string" }, "release": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "product": { "type": "string" }, "version": { "type": "string" } }, "required": [ "product", "version" ], "type": "object" }, "replies": { "items": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "body": { "type": "string" }, "by": { "additionalProperties": false, "properties": { "avatar": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "files": { "items": { "additionalProperties": false, "properties": { "bytes": { "type": "integer" }, "contentType": { "type": "string" }, "filename": { "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "filename", "contentType", "bytes", "href" ], "type": "object" }, "type": "array" }, "id": { "type": "string" }, "source": { "type": "string" }, "team": { "type": "boolean" } }, "required": [ "id", "body", "at" ], "type": "object" }, "type": "array" }, "source": { "type": "string" }, "state": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "updatedAt": { "type": "string" }, "visibility": { "type": "string" }, "voted": { "type": "boolean" }, "wanted": { "type": "integer" } }, "required": [ "id", "kind", "state", "title", "createdAt", "visibility", "wanted" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "One item with its whole conversation, if you may read it.", "tags": [ "feedback" ] }, "patch": { "operationId": "feedback.amend", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "body": { "type": "string" }, "id": { "type": "string" }, "state": { "type": "string" }, "title": { "type": "string" }, "visibility": { "type": "string" } }, "required": [ "id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "author": { "additionalProperties": false, "properties": { "avatar": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "body": { "type": "string" }, "createdAt": { "type": "string" }, "files": { "items": { "additionalProperties": false, "properties": { "bytes": { "type": "integer" }, "contentType": { "type": "string" }, "filename": { "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "filename", "contentType", "bytes", "href" ], "type": "object" }, "type": "array" }, "id": { "type": "string" }, "key": { "type": "string" }, "kind": { "type": "string" }, "merged": { "items": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "key": { "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "mergedInto": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "key": { "type": "string" } }, "required": [ "id" ], "type": "object" }, "mine": { "type": "boolean" }, "product": { "type": "string" }, "release": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "product": { "type": "string" }, "version": { "type": "string" } }, "required": [ "product", "version" ], "type": "object" }, "replies": { "items": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "body": { "type": "string" }, "by": { "additionalProperties": false, "properties": { "avatar": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "files": { "items": { "additionalProperties": false, "properties": { "bytes": { "type": "integer" }, "contentType": { "type": "string" }, "filename": { "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "filename", "contentType", "bytes", "href" ], "type": "object" }, "type": "array" }, "id": { "type": "string" }, "source": { "type": "string" }, "team": { "type": "boolean" } }, "required": [ "id", "body", "at" ], "type": "object" }, "type": "array" }, "source": { "type": "string" }, "state": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "updatedAt": { "type": "string" }, "visibility": { "type": "string" }, "voted": { "type": "boolean" }, "wanted": { "type": "integer" } }, "required": [ "id", "kind", "state", "title", "createdAt", "visibility", "wanted" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "security": [ { "stygionToken": [ "feedback.write" ] } ], "summary": "Changes what an item says or who may read it. The writer or the team.", "tags": [ "feedback" ] } }, "/api/v1/feedback/{id}/close": { "post": { "operationId": "feedback.close", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "id": { "type": "string" } }, "required": [ "id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "state": { "type": "string" } }, "required": [ "id", "state" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Closes a ticket for good: the conversation is cut into a transcript that stays with it and its Discord channel is deleted. The person who wrote it or the team.", "tags": [ "feedback" ] } }, "/api/v1/feedback/{id}/files": { "post": { "operationId": "feedback.attach", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "content": { "type": "string" }, "filename": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "content" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "bytes": { "type": "integer" }, "contentType": { "type": "string" }, "filename": { "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "filename", "contentType", "bytes", "href" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Puts a picture on a report.", "tags": [ "feedback" ] } }, "/api/v1/feedback/{id}/files/{fileId}": { "get": { "operationId": "feedback.file", "parameters": [ { "in": "path", "name": "fileId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "Body": true, "ContentType": { "type": "string" }, "Filename": { "type": "string" }, "Size": { "type": "integer" }, "URL": { "type": "string" } }, "required": [ "Body", "ContentType", "Filename", "Size", "URL" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "A file from a report, to whoever may read the report.", "tags": [ "feedback" ] } }, "/api/v1/feedback/{id}/replies": { "post": { "operationId": "feedback.reply", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "body": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "body" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "body": { "type": "string" }, "by": { "additionalProperties": false, "properties": { "avatar": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "files": { "items": { "additionalProperties": false, "properties": { "bytes": { "type": "integer" }, "contentType": { "type": "string" }, "filename": { "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "filename", "contentType", "bytes", "href" ], "type": "object" }, "type": "array" }, "id": { "type": "string" }, "source": { "type": "string" }, "team": { "type": "boolean" } }, "required": [ "id", "body", "at" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "security": [ { "stygionToken": [ "feedback.write" ] } ], "summary": "Adds a message to the conversation. Anybody signed in, not only the team.", "tags": [ "feedback" ] } }, "/api/v1/feedback/{id}/transcript": { "get": { "operationId": "feedback.transcript", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "body": { "type": "string" }, "closedBy": { "type": "string" } }, "required": [ "body", "at" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "security": [ { "stygionToken": [ "feedback.write" ] } ], "summary": "What was said in a closed ticket, as plain text. The person who wrote it or the team.", "tags": [ "feedback" ] } }, "/api/v1/feedback/{id}/vote": { "post": { "operationId": "feedback.vote", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "wanted": { "type": "boolean" } }, "required": [ "id", "wanted" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "voted": { "type": "boolean" }, "wanted": { "type": "integer" } }, "required": [ "wanted", "voted" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "security": [ { "stygionToken": [ "feedback.write" ] } ], "summary": "I want this too. One person, one voice.", "tags": [ "feedback" ] } }, "/api/v1/me": { "get": { "operationId": "identity.me", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "avatar": { "description": "Absolute URL from a linked provider", "type": "string" }, "id": { "description": "Stable identifier for this account.", "type": "string" }, "locale": { "description": "The language they chose.", "type": "string" }, "name": { "description": "What to call them. Never an email address.", "type": "string" }, "sections": { "description": "Team sections they are in. Absent unless they are on the team.", "items": { "type": "string" }, "type": "array" }, "team": { "description": "Whether they are on the STYGION team.", "type": "boolean" } }, "required": [ "id", "name", "locale", "team" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "The account making the request, or 401 for a stranger.", "tags": [ "identity" ] } }, "/api/v1/news": { "get": { "operationId": "content.news", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "description": "How many altogether. Up to 20.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "author": { "additionalProperties": false, "properties": { "avatar": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "channel": { "type": "string" }, "cover": { "additionalProperties": false, "properties": { "alt": { "type": "string" }, "src": { "type": "string" } }, "required": [ "src", "alt" ], "type": "object" }, "id": { "type": "string" }, "kind": { "description": "article or release.", "type": "string" }, "notes": { "type": "string" }, "product": { "type": "string" }, "publishedAt": { "type": "string" }, "readingMinutes": { "type": "integer" }, "slug": { "type": "string" }, "summary": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": "string" }, "version": { "type": "string" } }, "required": [ "kind", "id", "publishedAt", "tags" ], "type": "object" }, "type": "array" } }, "required": [ "items" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "The newest of everything we write and everything we release, in one list.", "tags": [ "content" ] } }, "/api/v1/notifications": { "get": { "operationId": "notify.list", "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "unread", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "createdAt": { "type": "string" }, "id": { "type": "string" }, "kind": { "type": "string" }, "link": { "type": "string" }, "read": { "type": "boolean" }, "subject": { "type": "string" }, "text": { "type": "string" } }, "required": [ "id", "kind", "text", "read", "createdAt" ], "type": "object" }, "type": "array" }, "next": { "type": "string" }, "unread": { "type": "integer" } }, "required": [ "items", "unread" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "What you have been told about, newest first.", "tags": [ "notify" ] } }, "/api/v1/notifications/read": { "post": { "operationId": "notify.read", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "id": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "unread": { "type": "integer" } }, "required": [ "unread" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Marks one as read, or all of them when no id is given.", "tags": [ "notify" ] } }, "/api/v1/notifications/settings": { "get": { "operationId": "notify.settings", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "discord": { "type": "boolean" }, "email": { "type": "boolean" }, "muted": { "items": { "type": "string" }, "type": "array" } }, "required": [ "muted", "discord", "email" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "What you want to hear about.", "tags": [ "notify" ] }, "put": { "operationId": "notify.setSettings", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "muted": { "items": { "type": "string" }, "type": "array" } }, "required": [ "muted" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "discord": { "type": "boolean" }, "email": { "type": "boolean" }, "muted": { "items": { "type": "string" }, "type": "array" } }, "required": [ "muted", "discord", "email" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Switches kinds of notification off, or back on.", "tags": [ "notify" ] } }, "/api/v1/panel/licence": { "get": { "operationId": "panel.licence", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "cancelled": { "type": "boolean" }, "panels": { "items": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "lastSeen": { "type": "string" }, "linkedAt": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "version": { "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "prices": { "items": { "additionalProperties": false, "properties": { "currency": { "type": "string" }, "minor": { "type": "integer" }, "period": { "type": "string" }, "plan": { "type": "string" } }, "required": [ "plan", "period", "minor", "currency" ], "type": "object" }, "type": "array" }, "reason": { "type": "string" }, "renews": { "type": "boolean" }, "selling": { "type": "boolean" }, "since": { "type": "string" }, "status": { "type": "string" }, "suspended": { "type": "boolean" }, "team": { "type": "boolean" }, "trial": { "type": "boolean" }, "until": { "type": "string" } }, "required": [ "selling" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "The STYGION Panel licence on your account, what one costs, and the panels you have linked to it.", "tags": [ "panel" ] } }, "/api/v1/people/{id}/avatar": { "get": { "operationId": "identity.avatar", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "Body": true, "ContentType": { "type": "string" }, "Filename": { "type": "string" }, "Size": { "type": "integer" }, "URL": { "type": "string" } }, "required": [ "Body", "ContentType", "Filename", "Size", "URL" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Somebody's picture, fetched from the provider they linked rather than by the reader's browser.", "tags": [ "identity" ] } }, "/api/v1/perf/begin": { "post": { "operationId": "perf.begin", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "kind": { "type": "string" }, "pack": { "additionalProperties": false, "properties": { "fileId": { "type": "string" }, "portal": { "type": "string" }, "projectId": { "type": "string" } }, "required": [ "portal", "projectId" ], "type": "object" }, "sender": { "type": "string" } }, "required": [ "kind" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "expiresAt": { "format": "date-time", "type": "string" }, "nonce": { "type": "string" }, "notBefore": { "format": "date-time", "type": "string" }, "sender": { "type": "string" } }, "required": [ "nonce", "notBefore", "expiresAt" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Start a benchmark: a one-time nonce for perf.submit for this kind. A client (pack version given) spends it from 90 seconds to 15 minutes after it is issued. A server (server_load, server_live; no pack) spends it within 7 days and no sooner than its run's measured seconds less 5. A server, and a launcher not signed in that sends sender \"new\", gets its own sender key here — no account needed: without one the backend issued, a new key comes back once (at most 3 new keys per address or IPv6 /64 a day and a ceiling over all addresses; none left is no error). Name the key in every later perf.begin and perf.submit; it counts publicly once it has accepted runs a day apart. Signed in or not; a nonce asked for while signed in is spent only by the same account. Limited per day.", "tags": [ "perf" ] } }, "/api/v1/perf/cpus": { "get": { "operationId": "perf.cpus", "parameters": [ { "in": "query", "name": "most", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "search", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "cpus": { "items": { "additionalProperties": false, "properties": { "cores": { "type": "integer" }, "emptyTickMs": { "type": "number" }, "family": { "type": "string" }, "name": { "type": "string" }, "runs": { "type": "integer" }, "turboGhz": { "type": "number" }, "vendor": { "type": "string" }, "year": { "type": "integer" } }, "required": [ "vendor", "name", "runs" ], "type": "object" }, "type": "array" }, "known": { "type": "integer" }, "stood": { "items": { "additionalProperties": false, "properties": { "cpu": { "additionalProperties": false, "properties": { "cores": { "type": "integer" }, "emptyTickMs": { "type": "number" }, "family": { "type": "string" }, "name": { "type": "string" }, "runs": { "type": "integer" }, "turboGhz": { "type": "number" }, "vendor": { "type": "string" }, "year": { "type": "integer" } }, "required": [ "vendor", "name", "runs" ], "type": "object" }, "emptyTickMs": { "type": "number" }, "how": { "type": "string" }, "instead": { "type": "string" }, "off": { "type": "number" }, "runs": { "type": "integer" } }, "required": [ "cpu", "how", "runs" ], "type": "object" }, "type": "array" } }, "required": [ "cpus", "known" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Processor models to pick from, with the single-thread speed we have measured for each — from the empty tick of the runs people send, never from somebody else's score table. A model nobody has run on comes back with no speed rather than a guess. An empty search answers with the models that have runs, most runs first.", "tags": [ "perf" ] } }, "/api/v1/perf/estimate": { "get": { "operationId": "perf.estimate", "parameters": [ { "in": "query", "name": "cpu", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "gpu", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "gpuPci", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "height", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "portal", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "projectId", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "ramMb", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "width", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "fpsHigh": { "type": "number" }, "fpsLow": { "type": "number" }, "hwClass": { "type": "string" }, "level": { "type": "string" }, "limits": { "type": "string" }, "live": { "additionalProperties": false, "properties": { "fps": { "type": "number" }, "lowFps": { "type": "number" }, "runs": { "type": "integer" }, "senders": { "type": "integer" } }, "required": [ "runs", "senders", "fps", "lowFps" ], "type": "object" }, "loadS": { "type": "number" }, "lowFps": { "type": "number" }, "portal": { "type": "string" }, "projectId": { "type": "string" }, "ramGb": { "type": "integer" }, "runs": { "type": "integer" }, "senders": { "type": "integer" } }, "required": [ "hwClass", "portal", "projectId", "level", "fpsLow", "fpsHigh", "lowFps", "ramGb", "loadS", "runs", "senders", "limits", "live" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "How one modpack is likely to run on a machine like yours: an average frame-rate range, 1 % low, memory and load time, with how many runs and senders it stands on and whether it was measured on similar PCs or estimated from others. Too little data is said as such, never as zero.", "tags": [ "perf" ] } }, "/api/v1/perf/estimates": { "get": { "operationId": "perf.estimates", "parameters": [ { "in": "query", "name": "cpu", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "gpu", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "gpuPci", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "height", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "packs", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "ramMb", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "width", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "estimates": { "items": { "additionalProperties": false, "properties": { "fpsHigh": { "type": "number" }, "fpsLow": { "type": "number" }, "level": { "type": "string" }, "loadS": { "type": "number" }, "lowFps": { "type": "number" }, "portal": { "type": "string" }, "projectId": { "type": "string" }, "ramGb": { "type": "integer" }, "runs": { "type": "integer" }, "senders": { "type": "integer" } }, "required": [ "portal", "projectId", "level", "fpsLow", "fpsHigh", "lowFps", "ramGb", "loadS", "runs", "senders" ], "type": "object" }, "type": "array" }, "hwClass": { "type": "string" } }, "required": [ "hwClass", "estimates" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "The same estimate for up to 50 modpacks at once (\"portal:projectId\" separated by commas), for a page of search results.", "tags": [ "perf" ] } }, "/api/v1/perf/gpus": { "get": { "operationId": "perf.gpus", "parameters": [ { "in": "query", "name": "most", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "search", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "gpus": { "items": { "additionalProperties": false, "properties": { "family": { "type": "string" }, "laptop": { "type": "boolean" }, "name": { "type": "string" }, "runs": { "type": "integer" }, "vendor": { "type": "string" }, "year": { "type": "integer" } }, "required": [ "vendor", "name" ], "type": "object" }, "type": "array" }, "known": { "type": "integer" } }, "required": [ "gpus", "known" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Graphics cards to pick from, with how many accepted client runs were measured on each. Specifications place a card (vendor, generation, year, laptop or desktop), they never score it. An empty search answers with the cards that have runs, most runs first; a card nobody has run on comes back with no count rather than a guess.", "tags": [ "perf" ] } }, "/api/v1/perf/metrics": { "get": { "operationId": "perf.metrics", "parameters": [ { "in": "query", "name": "all", "required": false, "schema": { "type": "boolean" } }, { "in": "query", "name": "side", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "metrics": { "items": { "additionalProperties": false, "properties": { "better": { "type": "string" }, "group": { "type": "string" }, "helpCs": { "type": "string" }, "helpEn": { "type": "string" }, "key": { "type": "string" }, "labelCs": { "type": "string" }, "labelEn": { "type": "string" }, "precision": { "type": "integer" }, "public": { "type": "boolean" }, "side": { "type": "string" }, "since": { "type": "integer" }, "unit": { "type": "string" } }, "required": [ "key", "unit", "better", "side", "group", "since", "precision", "public", "labelCs", "labelEn" ], "type": "object" }, "type": "array" } }, "required": [ "metrics" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "The metric registry the performance page renders by: every figure's key, unit, which way is better, side, group, Czech and English label and one sentence of what it means. A key ending in * is a family. Without all, only what a pack page shows.", "tags": [ "perf" ] } }, "/api/v1/perf/mine": { "get": { "operationId": "perf.mine", "parameters": [ { "in": "query", "name": "most", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "benchmarks": { "additionalProperties": false, "properties": { "accepted": { "type": "integer" }, "packs": { "type": "integer" }, "pioneer": { "type": "integer" } }, "required": [ "accepted", "packs", "pioneer" ], "type": "object" }, "runs": { "items": { "additionalProperties": false, "properties": { "codes": { "items": { "type": "string" }, "type": "array" }, "day": { "type": "string" }, "fps": { "type": "number" }, "hwClass": { "type": "string" }, "id": { "type": "integer" }, "kind": { "type": "string" }, "lowFps": { "type": "number" }, "pack": { "additionalProperties": false, "properties": { "fileId": { "type": "string" }, "portal": { "type": "string" }, "projectId": { "type": "string" } }, "required": [ "portal", "projectId" ], "type": "object" }, "presetId": { "type": "string" }, "state": { "type": "string" } }, "required": [ "id", "day", "kind", "pack", "state", "codes", "hwClass", "fps", "lowFps" ], "type": "object" }, "type": "array" } }, "required": [ "runs", "benchmarks" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "The benchmark runs you sent while signed in, newest first, with whether each was accepted and why not.", "tags": [ "perf" ] } }, "/api/v1/perf/mine/claim": { "post": { "operationId": "perf.claimKey", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "sender": { "type": "string" } }, "required": [ "sender" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "claimed": { "type": "integer" } }, "required": [ "claimed" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Join an instance's benchmark key (a launcher's or a server's, from perf.begin) to your account: the runs sent under it become yours (perf.mine) and every later run under the key is the account's. Only the key's holder can ask; a key another account has is not found.", "tags": [ "perf" ] } }, "/api/v1/perf/mine/forget": { "post": { "operationId": "perf.forgetMine", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "all": { "type": "boolean" }, "ids": { "items": { "type": "integer" }, "type": "array" }, "sender": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "withdrawn": { "type": "integer" } }, "required": [ "withdrawn" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Take back benchmark runs you sent: the ones named by id, or all of them with all: true (an empty list is refused, never read as all). Signed in, the account's runs; with sender (the instance's key from perf.begin), the runs sent under that key — no account needed. They leave every figure and are no longer linked to you; the measurement itself is kept, anonymously. A run that is not yours is not found, and then nothing changes.", "tags": [ "perf" ] } }, "/api/v1/perf/open": { "get": { "operationId": "perf.open", "parameters": [ { "in": "query", "name": "cpu", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "loader", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "logo", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "minecraft", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "most", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "portal", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "projectId", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "ramMb", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "storage", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "version", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "versionId", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "archived": { "items": { "additionalProperties": false, "properties": { "generation": { "type": "integer" }, "kind": { "type": "string" }, "runs": { "type": "integer" }, "scene": { "type": "integer" } }, "required": [ "kind", "generation", "scene", "runs" ], "type": "object" }, "type": "array" }, "emptyTickMs": { "additionalProperties": false, "properties": { "confidence": { "type": "string" }, "high": { "type": "number" }, "low": { "type": "number" }, "median": { "type": "number" }, "runs": { "type": "integer" } }, "required": [ "confidence", "runs" ], "type": "object" }, "figures": { "items": { "additionalProperties": false, "properties": { "key": { "type": "string" }, "kind": { "type": "string" }, "metric": { "additionalProperties": false, "properties": { "better": { "type": "string" }, "group": { "type": "string" }, "helpCs": { "type": "string" }, "helpEn": { "type": "string" }, "key": { "type": "string" }, "labelCs": { "type": "string" }, "labelEn": { "type": "string" }, "precision": { "type": "integer" }, "public": { "type": "boolean" }, "side": { "type": "string" }, "since": { "type": "integer" }, "unit": { "type": "string" } }, "required": [ "key", "unit", "better", "side", "group", "since", "precision", "public", "labelCs", "labelEn" ], "type": "object" }, "phase": { "type": "string" }, "senders": { "type": "integer" }, "summary": { "additionalProperties": false, "properties": { "confidence": { "type": "string" }, "high": { "type": "number" }, "low": { "type": "number" }, "median": { "type": "number" }, "runs": { "type": "integer" } }, "required": [ "confidence", "runs" ], "type": "object" }, "team": { "type": "boolean" } }, "required": [ "key", "kind", "metric", "summary", "senders" ], "type": "object" }, "type": "array" }, "gaveOut": { "items": { "additionalProperties": false, "properties": { "runs": { "type": "integer" }, "value": { "type": "string" } }, "required": [ "value", "runs" ], "type": "object" }, "type": "array" }, "generations": { "additionalProperties": { "type": "integer" }, "type": "object" }, "modCosts": { "items": { "additionalProperties": false, "properties": { "ci": { "items": { "type": "number" }, "type": "array" }, "inVanillaMs": { "type": "number" }, "kind": { "type": "string" }, "layer": { "type": "string" }, "metric": { "type": "string" }, "modId": { "type": "string" }, "modKey": { "type": "string" }, "phase": { "type": "string" }, "runs": { "type": "integer" }, "senders": { "type": "integer" }, "status": { "type": "string" }, "team": { "type": "boolean" }, "upper": { "type": "number" }, "value": { "type": "number" } }, "required": [ "modId", "kind", "metric", "status", "runs", "senders" ], "type": "object" }, "type": "array" }, "msPerPlayer": { "additionalProperties": false, "properties": { "confidence": { "type": "string" }, "high": { "type": "number" }, "low": { "type": "number" }, "median": { "type": "number" }, "runs": { "type": "integer" } }, "required": [ "confidence", "runs" ], "type": "object" }, "pack": { "additionalProperties": false, "properties": { "filePrint": { "type": "string" }, "loader": { "type": "string" }, "logo": { "type": "string" }, "minecraft": { "type": "string" }, "modCount": { "type": "integer" }, "modlist": { "type": "string" }, "name": { "type": "string" }, "portal": { "type": "string" }, "projectId": { "type": "string" }, "version": { "type": "string" }, "versionId": { "type": "string" } }, "required": [ "portal", "projectId", "versionId", "name", "modCount" ], "type": "object" }, "playersHeld": { "additionalProperties": false, "properties": { "confidence": { "type": "string" }, "high": { "type": "number" }, "low": { "type": "number" }, "median": { "type": "number" }, "runs": { "type": "integer" } }, "required": [ "confidence", "runs" ], "type": "object" }, "runs": { "additionalProperties": false, "properties": { "about": { "type": "integer" }, "considered": { "type": "integer" }, "likes": { "items": { "additionalProperties": false, "properties": { "about": { "type": "boolean" }, "askedMods": { "type": "integer" }, "machineNearness": { "type": "number" }, "machineSays": { "type": "string" }, "packNearness": { "type": "number" }, "run": { "additionalProperties": false, "properties": { "at": { "format": "date-time", "type": "string" }, "id": { "type": "integer" }, "kind": { "type": "string" }, "loader": { "type": "string" }, "machine": { "additionalProperties": false, "properties": { "calibration": { "type": "integer" }, "calibrationVersion": { "type": "integer" }, "cores": { "type": "integer" }, "cpu": { "type": "string" }, "flags": { "items": { "type": "string" }, "type": "array" }, "gc": { "type": "string" }, "gpu": { "type": "string" }, "gpuDriver": { "type": "string" }, "gpuPci": { "type": "string" }, "gpuVendor": { "type": "string" }, "heapMb": { "type": "integer" }, "java": { "type": "string" }, "os": { "type": "string" }, "osVersion": { "type": "string" }, "ramMb": { "type": "integer" }, "storage": { "type": "string" }, "threads": { "type": "integer" } }, "type": "object" }, "minecraft": { "type": "string" }, "modCount": { "type": "integer" }, "numbers": { "additionalProperties": false, "properties": { "allocatedMb": { "type": "integer" }, "averageTickMs": { "type": "number" }, "avgFrameMs": { "type": "number" }, "chunks": { "type": "integer" }, "cpuBusiestPct": { "type": "number" }, "emptyTickMs": { "type": "number" }, "entities": { "type": "integer" }, "frames": { "type": "integer" }, "gaveOut": { "type": "string" }, "gcPauseMaxMs": { "type": "number" }, "gcPauseMs": { "type": "integer" }, "gcPauseTotalMs": { "type": "number" }, "gcPauses": { "type": "integer" }, "gpuBusyPct": { "type": "number" }, "heapLiveP90Mb": { "type": "integer" }, "heapMaxMb": { "type": "integer" }, "heapMb": { "type": "integer" }, "heapUsedMb": { "type": "integer" }, "histogram": { "additionalProperties": false, "properties": { "counts": { "items": { "type": "integer" }, "type": "array" }, "from": { "type": "integer" }, "version": { "type": "integer" } }, "required": [ "version", "from", "counts" ], "type": "object" }, "loadPerPlayer": { "type": "integer" }, "loadS": { "type": "number" }, "loadVersion": { "type": "integer" }, "lowFrameMs": { "type": "number" }, "measureVersion": { "type": "integer" }, "medianFrameMs": { "type": "number" }, "msPerPlayer": { "type": "number" }, "msPerPlayerError": { "type": "number" }, "perSecond": { "items": { "items": { "type": "number" }, "type": "array" }, "type": "array" }, "players": { "type": "integer" }, "playersHeld": { "type": "integer" }, "seconds": { "type": "number" }, "settings": { "type": "string" }, "simulationDistance": { "type": "integer" }, "spreadRadius": { "type": "integer" }, "tickMs50": { "type": "number" }, "tickMs95": { "type": "number" }, "tickMs99": { "type": "number" }, "ticks": { "type": "integer" }, "tps": { "type": "number" }, "worldLoadS": { "type": "number" } }, "type": "object" }, "scene": { "type": "integer" }, "seconds": { "type": "integer" }, "source": { "type": "string" }, "sourceVersion": { "type": "string" } }, "required": [ "id", "source", "kind", "machine", "numbers", "seconds", "at", "modCount" ], "type": "object" }, "sharedMods": { "type": "integer" } }, "required": [ "run", "packNearness", "sharedMods", "askedMods", "about" ], "type": "object" }, "type": "array" }, "nothing": { "type": "boolean" } }, "required": [ "likes", "considered", "about", "nothing" ], "type": "object" }, "scenes": { "additionalProperties": { "type": "integer" }, "type": "object" }, "yours": { "additionalProperties": false, "properties": { "cpu": { "additionalProperties": false, "properties": { "cores": { "type": "integer" }, "emptyTickMs": { "type": "number" }, "family": { "type": "string" }, "name": { "type": "string" }, "runs": { "type": "integer" }, "turboGhz": { "type": "number" }, "vendor": { "type": "string" }, "year": { "type": "integer" } }, "required": [ "vendor", "name", "runs" ], "type": "object" }, "emptyTickMs": { "type": "number" }, "how": { "type": "string" }, "instead": { "type": "string" }, "off": { "type": "number" }, "runs": { "type": "integer" } }, "required": [ "cpu", "how", "runs" ], "type": "object" } }, "required": [ "pack", "playersHeld", "emptyTickMs", "msPerPlayer", "runs", "figures", "modCosts" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "What one modpack costs a server, on a machine like yours: how many players packs like it held, what gave out first, and the runs behind every number with how far off each one is. A locked pack answers too: the pack itself (modlist \"locked\", no mod count) and the runs ordered by machine alone, with no summary about the pack. figures[] are benchmark v2's numbers by the metric registry (server and client), modCosts[] what each mod costs with a 95 % interval. Outside senders speak without an account: a key from perf.begin or an account counts once it has accepted runs a day apart (a vouched-for account at once); a number stands on three voices with the team (two outside ones for a mod), a sender far from all the others is left out, and the team's own seed shows marked team.", "tags": [ "perf" ] } }, "/api/v1/perf/packs": { "get": { "operationId": "perf.packs", "parameters": [ { "in": "query", "name": "most", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "search", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "packs": { "items": { "additionalProperties": false, "properties": { "downloads": { "type": "integer" }, "loader": { "type": "string" }, "locked": { "type": "boolean" }, "logo": { "type": "string" }, "minecraft": { "type": "string" }, "name": { "type": "string" }, "portal": { "type": "string" }, "projectId": { "type": "string" }, "summary": { "type": "string" }, "version": { "type": "string" }, "versionId": { "type": "string" } }, "required": [ "portal", "projectId", "versionId", "name" ], "type": "object" }, "type": "array" } }, "required": [ "packs" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Search CurseForge and Modrinth for a modpack by name, to ask what it costs a server. Nothing is crawled: a pack is read at the moment somebody opens it. A pack whose author allows downloads only through CurseForge (and that is not on Modrinth) comes back with locked set: it is offered, but its mod list is not ours to read.", "tags": [ "perf" ] } }, "/api/v1/perf/packs/{fingerprint}": { "get": { "operationId": "perf.pack", "parameters": [ { "in": "path", "name": "fingerprint", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "kind", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "emptyTickMs": { "additionalProperties": false, "properties": { "confidence": { "type": "string" }, "high": { "type": "number" }, "low": { "type": "number" }, "median": { "type": "number" }, "runs": { "type": "integer" } }, "required": [ "confidence", "runs" ], "type": "object" }, "examples": { "items": { "additionalProperties": false, "properties": { "at": { "format": "date-time", "type": "string" }, "id": { "type": "integer" }, "kind": { "type": "string" }, "loader": { "type": "string" }, "machine": { "additionalProperties": false, "properties": { "calibration": { "type": "integer" }, "calibrationVersion": { "type": "integer" }, "cores": { "type": "integer" }, "cpu": { "type": "string" }, "flags": { "items": { "type": "string" }, "type": "array" }, "gc": { "type": "string" }, "gpu": { "type": "string" }, "gpuDriver": { "type": "string" }, "gpuPci": { "type": "string" }, "gpuVendor": { "type": "string" }, "heapMb": { "type": "integer" }, "java": { "type": "string" }, "os": { "type": "string" }, "osVersion": { "type": "string" }, "ramMb": { "type": "integer" }, "storage": { "type": "string" }, "threads": { "type": "integer" } }, "type": "object" }, "minecraft": { "type": "string" }, "modCount": { "type": "integer" }, "numbers": { "additionalProperties": false, "properties": { "allocatedMb": { "type": "integer" }, "averageTickMs": { "type": "number" }, "avgFrameMs": { "type": "number" }, "chunks": { "type": "integer" }, "cpuBusiestPct": { "type": "number" }, "emptyTickMs": { "type": "number" }, "entities": { "type": "integer" }, "frames": { "type": "integer" }, "gaveOut": { "type": "string" }, "gcPauseMaxMs": { "type": "number" }, "gcPauseMs": { "type": "integer" }, "gcPauseTotalMs": { "type": "number" }, "gcPauses": { "type": "integer" }, "gpuBusyPct": { "type": "number" }, "heapLiveP90Mb": { "type": "integer" }, "heapMaxMb": { "type": "integer" }, "heapMb": { "type": "integer" }, "heapUsedMb": { "type": "integer" }, "histogram": { "additionalProperties": false, "properties": { "counts": { "items": { "type": "integer" }, "type": "array" }, "from": { "type": "integer" }, "version": { "type": "integer" } }, "required": [ "version", "from", "counts" ], "type": "object" }, "loadPerPlayer": { "type": "integer" }, "loadS": { "type": "number" }, "loadVersion": { "type": "integer" }, "lowFrameMs": { "type": "number" }, "measureVersion": { "type": "integer" }, "medianFrameMs": { "type": "number" }, "msPerPlayer": { "type": "number" }, "msPerPlayerError": { "type": "number" }, "perSecond": { "items": { "items": { "type": "number" }, "type": "array" }, "type": "array" }, "players": { "type": "integer" }, "playersHeld": { "type": "integer" }, "seconds": { "type": "number" }, "settings": { "type": "string" }, "simulationDistance": { "type": "integer" }, "spreadRadius": { "type": "integer" }, "tickMs50": { "type": "number" }, "tickMs95": { "type": "number" }, "tickMs99": { "type": "number" }, "ticks": { "type": "integer" }, "tps": { "type": "number" }, "worldLoadS": { "type": "number" } }, "type": "object" }, "scene": { "type": "integer" }, "seconds": { "type": "integer" }, "source": { "type": "string" }, "sourceVersion": { "type": "string" } }, "required": [ "id", "source", "kind", "machine", "numbers", "seconds", "at", "modCount" ], "type": "object" }, "type": "array" }, "fingerprint": { "type": "string" }, "flags": { "items": { "additionalProperties": false, "properties": { "flags": { "items": { "type": "string" }, "type": "array" }, "gc": { "type": "string" }, "pauseMs": { "type": "number" }, "runs": { "type": "integer" }, "tickMs": { "type": "number" } }, "required": [ "flags", "runs" ], "type": "object" }, "type": "array" }, "gaveOut": { "items": { "additionalProperties": false, "properties": { "runs": { "type": "integer" }, "value": { "type": "string" } }, "required": [ "value", "runs" ], "type": "object" }, "type": "array" }, "live": { "additionalProperties": false, "properties": { "players": { "additionalProperties": false, "properties": { "confidence": { "type": "string" }, "high": { "type": "number" }, "low": { "type": "number" }, "median": { "type": "number" }, "runs": { "type": "integer" } }, "required": [ "confidence", "runs" ], "type": "object" }, "samples": { "type": "integer" }, "tickMs95": { "additionalProperties": false, "properties": { "confidence": { "type": "string" }, "high": { "type": "number" }, "low": { "type": "number" }, "median": { "type": "number" }, "runs": { "type": "integer" } }, "required": [ "confidence", "runs" ], "type": "object" } }, "required": [ "samples", "tickMs95", "players" ], "type": "object" }, "load": { "type": "integer" }, "loadVersion": { "type": "integer" }, "loader": { "type": "string" }, "measureVersion": { "type": "integer" }, "minecraft": { "type": "string" }, "modCosts": { "items": { "additionalProperties": false, "properties": { "ci": { "items": { "type": "number" }, "type": "array" }, "inVanillaMs": { "type": "number" }, "kind": { "type": "string" }, "layer": { "type": "string" }, "metric": { "type": "string" }, "modId": { "type": "string" }, "modKey": { "type": "string" }, "phase": { "type": "string" }, "runs": { "type": "integer" }, "senders": { "type": "integer" }, "status": { "type": "string" }, "team": { "type": "boolean" }, "upper": { "type": "number" }, "value": { "type": "number" } }, "required": [ "modId", "kind", "metric", "status", "runs", "senders" ], "type": "object" }, "type": "array" }, "modCount": { "type": "integer" }, "msPerPlayer": { "additionalProperties": false, "properties": { "confidence": { "type": "string" }, "high": { "type": "number" }, "low": { "type": "number" }, "median": { "type": "number" }, "runs": { "type": "integer" } }, "required": [ "confidence", "runs" ], "type": "object" }, "otherLoads": { "items": { "additionalProperties": false, "properties": { "runs": { "type": "integer" }, "value": { "type": "string" } }, "required": [ "value", "runs" ], "type": "object" }, "type": "array" }, "otherScenes": { "items": { "additionalProperties": false, "properties": { "runs": { "type": "integer" }, "value": { "type": "string" } }, "required": [ "value", "runs" ], "type": "object" }, "type": "array" }, "otherVersions": { "items": { "additionalProperties": false, "properties": { "runs": { "type": "integer" }, "value": { "type": "string" } }, "required": [ "value", "runs" ], "type": "object" }, "type": "array" }, "playersHeld": { "additionalProperties": false, "properties": { "confidence": { "type": "string" }, "high": { "type": "number" }, "low": { "type": "number" }, "median": { "type": "number" }, "runs": { "type": "integer" } }, "required": [ "confidence", "runs" ], "type": "object" }, "scene": { "type": "integer" }, "tickShares": { "items": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "lateShare": { "type": "number" }, "perThing": { "type": "number" }, "runs": { "type": "integer" }, "share": { "type": "number" }, "things": { "type": "integer" }, "version": { "type": "string" } }, "required": [ "id", "share", "runs" ], "type": "object" }, "type": "array" } }, "required": [ "fingerprint", "modCount", "playersHeld", "emptyTickMs", "msPerPlayer", "load", "modCosts", "live" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "What one set of mods costs a server: how many players it holds, what gives out first, and what each mod in it costs — every number with the count of runs behind it, and no number at all where there are not enough.", "tags": [ "perf" ] } }, "/api/v1/perf/recommend": { "get": { "operationId": "perf.recommend", "parameters": [ { "in": "query", "name": "cpu", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "gpu", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "gpuPci", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "height", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "portal", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "projectId", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "ramMb", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "width", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "evidence": { "additionalProperties": false, "properties": { "runs": { "type": "integer" }, "senders": { "type": "integer" } }, "required": [ "runs", "senders" ], "type": "object" }, "hwClass": { "type": "string" }, "preset": { "additionalProperties": false, "properties": { "author": { "additionalProperties": false, "properties": { "kind": { "type": "string" } }, "required": [ "kind" ], "type": "object" }, "id": { "type": "string" }, "jvm": { "additionalProperties": false, "properties": { "choice": { "type": "string" }, "heapMb": { "type": "integer" } }, "required": [ "choice" ], "type": "object" }, "name": { "additionalProperties": false, "properties": { "cs": { "type": "string" }, "en": { "type": "string" } }, "required": [ "cs", "en" ], "type": "object" }, "options": { "additionalProperties": { "type": "string" }, "type": "object" }, "pack": { "additionalProperties": false, "properties": { "madeFor": { "type": "string" }, "portal": { "type": "string" }, "projectId": { "type": "string" } }, "required": [ "portal", "projectId" ], "type": "object" }, "rev": { "type": "integer" }, "sentence": { "additionalProperties": false, "properties": { "cs": { "type": "string" }, "en": { "type": "string" } }, "required": [ "cs", "en" ], "type": "object" } }, "required": [ "id", "rev", "name", "sentence", "author", "pack" ], "type": "object" } }, "required": [ "hwClass", "preset", "evidence" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "The recommended preset for one modpack on a machine like yours, with the runs behind it — or none, when there is not enough evidence to recommend anything.", "tags": [ "perf" ] } }, "/api/v1/perf/runs": { "post": { "operationId": "perf.submit", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "bench": true, "display": { "additionalProperties": false, "properties": { "height": { "type": "integer" }, "width": { "type": "integer" } }, "required": [ "width", "height" ], "type": "object" }, "evidence": true, "files": { "items": { "type": "string" }, "type": "array" }, "hosting": { "type": "object" }, "kind": { "type": "string" }, "launcher": { "type": "string" }, "loader": { "type": "string" }, "loaderVersion": { "type": "string" }, "machine": { "additionalProperties": false, "properties": { "calibration": { "type": "integer" }, "calibrationVersion": { "type": "integer" }, "cores": { "type": "integer" }, "cpu": { "type": "string" }, "flags": { "items": { "type": "string" }, "type": "array" }, "gc": { "type": "string" }, "gpu": { "type": "string" }, "gpuDriver": { "type": "string" }, "gpuPci": { "type": "string" }, "gpuVendor": { "type": "string" }, "heapMb": { "type": "integer" }, "java": { "type": "string" }, "os": { "type": "string" }, "osVersion": { "type": "string" }, "ramMb": { "type": "integer" }, "storage": { "type": "string" }, "threads": { "type": "integer" } }, "type": "object" }, "measureVersion": { "type": "integer" }, "metrics": { "additionalProperties": { "type": "number" }, "type": "object" }, "minecraft": { "type": "string" }, "modCosts": { "items": { "additionalProperties": false, "properties": { "ci": { "items": { "type": "number" }, "type": "array" }, "inVanillaMs": { "type": "number" }, "layer": { "type": "string" }, "metric": { "type": "string" }, "modId": { "type": "string" }, "n": { "type": "integer" }, "outsideMs": { "type": "number" }, "phase": { "type": "string" }, "typedMs": { "type": "number" }, "value": { "type": "number" } }, "required": [ "modId", "metric", "layer", "value" ], "type": "object" }, "type": "array" }, "mods": { "items": { "additionalProperties": false, "properties": { "cfFingerprint": { "type": "integer" }, "file": { "type": "string" }, "id": { "type": "string" }, "lateShare": { "type": "number" }, "modId": { "type": "string" }, "sha1": { "type": "string" }, "things": { "type": "integer" }, "tickShare": { "type": "number" }, "version": { "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "nonce": { "type": "string" }, "numbers": { "additionalProperties": false, "properties": { "allocatedMb": { "type": "integer" }, "averageTickMs": { "type": "number" }, "avgFrameMs": { "type": "number" }, "chunks": { "type": "integer" }, "cpuBusiestPct": { "type": "number" }, "emptyTickMs": { "type": "number" }, "entities": { "type": "integer" }, "frames": { "type": "integer" }, "gaveOut": { "type": "string" }, "gcPauseMaxMs": { "type": "number" }, "gcPauseMs": { "type": "integer" }, "gcPauseTotalMs": { "type": "number" }, "gcPauses": { "type": "integer" }, "gpuBusyPct": { "type": "number" }, "heapLiveP90Mb": { "type": "integer" }, "heapMaxMb": { "type": "integer" }, "heapMb": { "type": "integer" }, "heapUsedMb": { "type": "integer" }, "histogram": { "additionalProperties": false, "properties": { "counts": { "items": { "type": "integer" }, "type": "array" }, "from": { "type": "integer" }, "version": { "type": "integer" } }, "required": [ "version", "from", "counts" ], "type": "object" }, "loadPerPlayer": { "type": "integer" }, "loadS": { "type": "number" }, "loadVersion": { "type": "integer" }, "lowFrameMs": { "type": "number" }, "measureVersion": { "type": "integer" }, "medianFrameMs": { "type": "number" }, "msPerPlayer": { "type": "number" }, "msPerPlayerError": { "type": "number" }, "perSecond": { "items": { "items": { "type": "number" }, "type": "array" }, "type": "array" }, "players": { "type": "integer" }, "playersHeld": { "type": "integer" }, "seconds": { "type": "number" }, "settings": { "type": "string" }, "simulationDistance": { "type": "integer" }, "spreadRadius": { "type": "integer" }, "tickMs50": { "type": "number" }, "tickMs95": { "type": "number" }, "tickMs99": { "type": "number" }, "ticks": { "type": "integer" }, "tps": { "type": "number" }, "worldLoadS": { "type": "number" } }, "type": "object" }, "overhead": { "additionalProperties": { "type": "number" }, "type": "object" }, "pack": { "additionalProperties": false, "properties": { "fileId": { "type": "string" }, "loader": { "type": "string" }, "loaderVersion": { "type": "string" }, "minecraft": { "type": "string" }, "portal": { "type": "string" }, "projectId": { "type": "string" }, "version": { "type": "string" } }, "required": [ "portal", "projectId", "fileId" ], "type": "object" }, "pass": { "type": "string" }, "passGroup": { "type": "string" }, "phases": { "items": { "additionalProperties": false, "properties": { "histogram": { "additionalProperties": false, "properties": { "counts": { "items": { "type": "integer" }, "type": "array" }, "from": { "type": "integer" }, "version": { "type": "integer" } }, "required": [ "version", "from", "counts" ], "type": "object" }, "metrics": { "additionalProperties": { "type": "number" }, "type": "object" }, "name": { "type": "string" }, "open": { "type": "boolean" }, "players": { "type": "integer" } }, "required": [ "name", "players" ], "type": "object" }, "type": "array" }, "presetId": { "type": "string" }, "profile": { "additionalProperties": false, "properties": { "instrument": { "type": "string" }, "lateTicks": { "type": "integer" }, "periodMs": { "type": "number" }, "samples": { "type": "integer" }, "stackDepth": { "type": "integer" }, "truncatedPct": { "type": "number" }, "typed": { "type": "string" }, "unattributedPct": { "type": "number" } }, "type": "object" }, "profileV2": { "additionalProperties": false, "properties": { "instrument": { "type": "string" }, "lateTicks": { "type": "integer" }, "periodMs": { "type": "number" }, "samples": { "type": "integer" }, "stackDepth": { "type": "integer" }, "truncatedPct": { "type": "number" }, "typed": { "type": "string" }, "unattributedPct": { "type": "number" } }, "type": "object" }, "runUid": { "type": "string" }, "schema": { "type": "integer" }, "seconds": { "type": "integer" }, "sender": { "type": "string" }, "settings": { "type": "object" }, "source": { "type": "string" }, "sourceVersion": { "type": "string" }, "versions": { "type": "object" } }, "required": [ "source", "kind", "minecraft", "loader", "machine", "numbers", "seconds", "mods" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "badges": { "items": { "type": "string" }, "type": "array" }, "codes": { "items": { "type": "string" }, "type": "array" }, "fingerprint": { "type": "string" }, "hwClass": { "type": "string" }, "id": { "type": "string" }, "page": { "type": "string" }, "runs": { "type": "integer" }, "state": { "type": "string" } }, "required": [ "fingerprint", "runs" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Send one measurement of a modpack — a load test from a server, a benchmark from a client. It carries what was loaded, what the machine is and what happened, and nothing that names anybody. Envelope schema 3 (benchmark v2) adds versions, figures under metric-registry keys, per-mod costs with intervals and the evidence they are recomputed from; schemas 1 and 2 are still accepted.", "tags": [ "perf" ] } }, "/api/v1/play/badge": { "get": { "operationId": "play.look", "parameters": [ { "in": "query", "name": "token", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "down": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "name", "down" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "What one Play button says, for drawing the picture of it.", "tags": [ "play" ] } }, "/api/v1/play/count": { "post": { "operationId": "play.count", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "event": { "description": "view (the button's page was opened) or click (its Play button was pressed).", "type": "string" }, "token": { "type": "string" } }, "required": [ "token", "event" ], "type": "object" } } }, "required": true }, "responses": { "204": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "A Play button's page was opened (view) or its button pressed (click). A number per day, nothing about who.", "tags": [ "play" ] } }, "/api/v1/play/links": { "get": { "operationId": "play.links", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "blocked": { "type": "boolean" }, "clicks": { "type": "integer" }, "createdAt": { "type": "string" }, "description": { "type": "string" }, "hidden": { "type": "boolean" }, "icon": { "type": "string" }, "listed": { "type": "boolean" }, "moderationNote": { "type": "string" }, "name": { "type": "string" }, "packFile": { "type": "string" }, "packId": { "type": "string" }, "packSource": { "type": "string" }, "revoked": { "type": "boolean" }, "server": { "type": "string" }, "token": { "type": "string" }, "url": { "type": "string" }, "used": { "type": "integer" }, "views": { "type": "integer" } }, "required": [ "token", "url", "server", "name", "listed", "createdAt", "used", "views", "clicks" ], "type": "object" }, "type": "array" } }, "required": [ "items" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "The Play buttons you have made, and how often each was used.", "tags": [ "play" ] }, "post": { "operationId": "play.make", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "description": { "description": "One short paragraph (200 characters) about the server. Plain words", "type": "string" }, "listed": { "description": "Show the server in the public list of servers. Nobody checks that it is yours; anybody can report it.", "type": "boolean" }, "name": { "description": "What the place is called", "type": "string" }, "packFile": { "description": "A version id to pin. Left out the newest is installed.", "type": "string" }, "packId": { "description": "The pack's id on that service (a number on CurseForge).", "type": "string" }, "packSource": { "description": "modrinth or curseforge. Empty for a server with no pack.", "type": "string" }, "server": { "description": "The address a player types into Minecraft. host or host:port.", "type": "string" } }, "required": [ "server" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "blocked": { "type": "boolean" }, "clicks": { "type": "integer" }, "createdAt": { "type": "string" }, "description": { "type": "string" }, "hidden": { "type": "boolean" }, "icon": { "type": "string" }, "listed": { "type": "boolean" }, "moderationNote": { "type": "string" }, "name": { "type": "string" }, "packFile": { "type": "string" }, "packId": { "type": "string" }, "packSource": { "type": "string" }, "revoked": { "type": "boolean" }, "server": { "type": "string" }, "token": { "type": "string" }, "url": { "type": "string" }, "used": { "type": "integer" }, "views": { "type": "integer" } }, "required": [ "token", "url", "server", "name", "listed", "createdAt", "used", "views", "clicks" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Makes a Play button for a server, to put on its own website.", "tags": [ "play" ] } }, "/api/v1/play/links/delete": { "post": { "operationId": "play.delete", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "token": { "type": "string" } }, "required": [ "token" ], "type": "object" } } }, "required": true }, "responses": { "204": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Delete one of your Play buttons and its numbers for good. Unlike taking it down, the old address then says nothing about it.", "tags": [ "play" ] } }, "/api/v1/play/links/edit": { "post": { "operationId": "play.edit", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "description": { "description": "One short paragraph (200 characters) about the server. Plain words", "type": "string" }, "listed": { "description": "Show the server in the public list of servers.", "type": "boolean" }, "name": { "description": "What the place is called", "type": "string" }, "packFile": { "description": "A version id to pin. Left out the newest is installed.", "type": "string" }, "packId": { "description": "The pack's id on that service (a number on CurseForge).", "type": "string" }, "packSource": { "description": "modrinth or curseforge. Empty for a server with no pack.", "type": "string" }, "server": { "description": "The address a player types into Minecraft. host or host:port.", "type": "string" }, "token": { "description": "Which button. From the address of the one you made.", "type": "string" } }, "required": [ "token", "server" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "blocked": { "type": "boolean" }, "clicks": { "type": "integer" }, "createdAt": { "type": "string" }, "description": { "type": "string" }, "hidden": { "type": "boolean" }, "icon": { "type": "string" }, "listed": { "type": "boolean" }, "moderationNote": { "type": "string" }, "name": { "type": "string" }, "packFile": { "type": "string" }, "packId": { "type": "string" }, "packSource": { "type": "string" }, "revoked": { "type": "boolean" }, "server": { "type": "string" }, "token": { "type": "string" }, "url": { "type": "string" }, "used": { "type": "integer" }, "views": { "type": "integer" } }, "required": [ "token", "url", "server", "name", "listed", "createdAt", "used", "views", "clicks" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Changes a Play button that is already on somebody's page — where it goes, what it is called, which pack it installs.", "tags": [ "play" ] } }, "/api/v1/play/links/revoke": { "post": { "operationId": "play.revoke", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "token": { "type": "string" } }, "required": [ "token" ], "type": "object" } } }, "required": true }, "responses": { "204": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Takes one of your Play buttons down.", "tags": [ "play" ] } }, "/api/v1/play/open": { "post": { "operationId": "play.open", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "token": { "type": "string" } }, "required": [ "token" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "icon": { "type": "string" }, "name": { "type": "string" }, "packFile": { "type": "string" }, "packId": { "type": "string" }, "packSource": { "type": "string" }, "server": { "type": "string" } }, "required": [ "server", "name" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "What a Play link means: which server, which pack. The launcher asks this when it launches one, and that is what counts as a launch.", "tags": [ "play" ] } }, "/api/v1/play/page": { "get": { "operationId": "play.page", "parameters": [ { "in": "query", "name": "token", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "checkedAt": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "listed": { "type": "boolean" }, "max": { "type": "integer" }, "name": { "type": "string" }, "online": { "type": "boolean" }, "packFile": { "type": "string" }, "packId": { "type": "string" }, "packSource": { "type": "string" }, "players": { "type": "integer" }, "server": { "type": "string" }, "token": { "type": "string" }, "version": { "type": "string" } }, "required": [ "token", "name", "server", "listed", "online", "players", "max" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "A Play button's own page: the server, the pack, and how the server is doing when it is listed. Counts nothing.", "tags": [ "play" ] } }, "/api/v1/play/report": { "post": { "operationId": "play.report", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "note": { "description": "What is wrong", "type": "string" }, "reason": { "description": "spam", "type": "string" }, "token": { "type": "string" } }, "required": [ "token", "reason" ], "type": "object" } } }, "required": true }, "responses": { "204": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Report a Play button or a listed server: spam, scam, offensive, broken or other. Signed in, once per button.", "tags": [ "play" ] } }, "/api/v1/play/servers": { "get": { "operationId": "play.servers", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "description": "How many to return", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "description": "How many to skip", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "checkedAt": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "max": { "type": "integer" }, "name": { "type": "string" }, "online": { "type": "boolean" }, "packFile": { "type": "string" }, "packId": { "type": "string" }, "packSource": { "type": "string" }, "players": { "type": "integer" }, "server": { "type": "string" }, "token": { "type": "string" }, "url": { "type": "string" }, "version": { "type": "string" } }, "required": [ "token", "url", "name", "server", "online", "players", "max" ], "type": "object" }, "type": "array" } }, "required": [ "items" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "The public list of servers: name, description, address, pack, whether it is online and how many are playing. Ranked by what is alive, never by who paid.", "tags": [ "play" ] } }, "/api/v1/play/stats": { "get": { "operationId": "play.stats", "parameters": [ { "in": "query", "name": "token", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "clicks": { "type": "integer" }, "days": { "items": { "additionalProperties": false, "properties": { "clicks": { "type": "integer" }, "day": { "type": "string" }, "launches": { "type": "integer" }, "views": { "type": "integer" } }, "required": [ "day", "views", "clicks", "launches" ], "type": "object" }, "type": "array" }, "launches": { "type": "integer" }, "name": { "type": "string" }, "token": { "type": "string" }, "views": { "type": "integer" } }, "required": [ "token", "name", "views", "clicks", "launches", "days" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "One button's views, clicks and launches: totals and the last thirty days. Its owner, or the team.", "tags": [ "play" ] } }, "/api/v1/presets/allowlist": { "get": { "operationId": "presets.allowlist", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "files": { "items": { "type": "string" }, "type": "array" }, "options": { "items": { "type": "string" }, "type": "array" }, "recommendMods": { "items": { "additionalProperties": false, "properties": { "name": { "type": "string" }, "portal": { "type": "string" }, "projectId": { "type": "string" } }, "required": [ "portal", "projectId" ], "type": "object" }, "type": "array" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "type": "integer" } }, "required": [ "version", "options", "files", "recommendMods", "updatedAt" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Which options.txt keys a preset may set, which graphics configuration files a player's preset may carry, and which performance mods the recommended preset may add.", "tags": [ "presets" ] } }, "/api/v1/presets/conflicts": { "get": { "operationId": "presets.conflicts", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "conflicts": { "items": { "additionalProperties": false, "properties": { "a": { "additionalProperties": false, "properties": { "modId": { "type": "string" }, "portal": { "type": "string" }, "projectId": { "type": "string" } }, "type": "object" }, "b": { "additionalProperties": false, "properties": { "modId": { "type": "string" }, "portal": { "type": "string" }, "projectId": { "type": "string" } }, "type": "object" }, "reason": { "additionalProperties": false, "properties": { "cs": { "type": "string" }, "en": { "type": "string" } }, "required": [ "cs", "en" ], "type": "object" } }, "required": [ "a", "b", "reason" ], "type": "object" }, "type": "array" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "type": "integer" } }, "required": [ "version", "conflicts", "updatedAt" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Mods that do not run together (Sodium and OptiFine, Embeddium and Rubidium, …), each pair by portal project or mod id, with the reason in both languages.", "tags": [ "presets" ] } }, "/api/v1/releases": { "get": { "operationId": "updates.releases", "parameters": [ { "in": "query", "name": "channel", "required": false, "schema": { "description": "alpha", "type": "string" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "product", "required": false, "schema": { "description": "Only this product", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "body": { "type": "string" }, "canceled": { "type": "boolean" }, "channel": { "type": "string" }, "current": { "type": "boolean" }, "id": { "type": "string" }, "notes": { "type": "string" }, "product": { "type": "string" }, "publications": { "items": { "additionalProperties": false, "properties": { "error": { "type": "string" }, "filename": { "type": "string" }, "status": { "type": "string" }, "target": { "type": "string" }, "url": { "type": "string" } }, "required": [ "target", "status" ], "type": "object" }, "type": "array" }, "publishedAt": { "type": "string" }, "version": { "type": "string" } }, "required": [ "id", "product", "version", "channel", "publishedAt", "notes" ], "type": "object" }, "type": "array" }, "next": { "type": "string" } }, "required": [ "items" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Every released version, newest first.", "tags": [ "updates" ] } }, "/api/v1/releases/{id}": { "get": { "operationId": "updates.release", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "body": { "type": "string" }, "canceled": { "type": "boolean" }, "channel": { "type": "string" }, "current": { "type": "boolean" }, "id": { "type": "string" }, "notes": { "type": "string" }, "product": { "type": "string" }, "publications": { "items": { "additionalProperties": false, "properties": { "error": { "type": "string" }, "filename": { "type": "string" }, "status": { "type": "string" }, "target": { "type": "string" }, "url": { "type": "string" } }, "required": [ "target", "status" ], "type": "object" }, "type": "array" }, "publishedAt": { "type": "string" }, "version": { "type": "string" } }, "required": [ "id", "product", "version", "channel", "publishedAt", "notes" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "One version, with everything that changed in it.", "tags": [ "updates" ] } }, "/api/v1/social/chat": { "get": { "operationId": "social.chat", "parameters": [ { "in": "query", "name": "with", "required": false, "schema": { "description": "The account id of the friend.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "body": { "type": "string" }, "from": { "type": "string" }, "id": { "type": "string" }, "mine": { "type": "boolean" } }, "required": [ "id", "from", "body", "at", "mine" ], "type": "object" }, "type": "array" } }, "required": [ "items" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "What you and one friend have said to each other.", "tags": [ "social" ] }, "post": { "operationId": "social.say", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "body": { "description": "What to say. Up to 500 characters.", "type": "string" }, "to": { "description": "The account id of the friend.", "type": "string" } }, "required": [ "to", "body" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "body": { "type": "string" }, "from": { "type": "string" }, "id": { "type": "string" }, "mine": { "type": "boolean" } }, "required": [ "id", "from", "body", "at", "mine" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Sends one message to a friend.", "tags": [ "social" ] } }, "/api/v1/social/friends": { "get": { "operationId": "social.friends", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "avatar": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "online": { "type": "boolean" }, "playing": { "type": "string" }, "since": { "type": "string" }, "state": { "type": "string" }, "unread": { "type": "integer" } }, "required": [ "id", "name", "state", "since" ], "type": "object" }, "type": "array" } }, "required": [ "items" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Who you know, whether they are on, and what they are playing.", "tags": [ "social" ] }, "post": { "operationId": "social.ask", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "account": { "description": "The account id of the other person.", "type": "string" } }, "required": [ "account" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "avatar": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "online": { "type": "boolean" }, "playing": { "type": "string" }, "since": { "type": "string" }, "state": { "type": "string" }, "unread": { "type": "integer" } }, "required": [ "id", "name", "state", "since" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Asks somebody to be friends, or accepts if they asked first.", "tags": [ "social" ] } }, "/api/v1/social/friends/accept": { "post": { "operationId": "social.accept", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "account": { "description": "The account id of the other person.", "type": "string" } }, "required": [ "account" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "avatar": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "online": { "type": "boolean" }, "playing": { "type": "string" }, "since": { "type": "string" }, "state": { "type": "string" }, "unread": { "type": "integer" } }, "required": [ "id", "name", "state", "since" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Accepts a request somebody sent you.", "tags": [ "social" ] } }, "/api/v1/social/friends/remove": { "post": { "operationId": "social.remove", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "account": { "description": "The account id of the other person.", "type": "string" } }, "required": [ "account" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Ends a friendship, declines a request, or takes back one you sent.", "tags": [ "social" ] } }, "/api/v1/social/people": { "get": { "operationId": "social.find", "parameters": [ { "in": "query", "name": "q", "required": false, "schema": { "description": "Part of somebody's name. At least two characters.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "avatar": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "online": { "type": "boolean" }, "playing": { "type": "string" }, "since": { "type": "string" }, "state": { "type": "string" }, "unread": { "type": "integer" } }, "required": [ "id", "name", "state", "since" ], "type": "object" }, "type": "array" } }, "required": [ "items" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Finds somebody by name so you can ask to be friends.", "tags": [ "social" ] } }, "/api/v1/social/presence": { "put": { "operationId": "social.playing", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "playing": { "description": "The name of the pack being played. Empty when they are not in a game.", "type": "string" } }, "required": [ "playing" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Tells your friends what you are playing, or that you stopped.", "tags": [ "social" ] } }, "/api/v1/status/products": { "get": { "operationId": "updates.productStatus", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "channel": { "type": "string" }, "product": { "type": "string" }, "publishedAt": { "type": "string" }, "version": { "type": "string" } }, "required": [ "product" ], "type": "object" }, "type": "array" } }, "required": [ "items" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "The highest channel each product actually has a build in.", "tags": [ "updates" ] } }, "/api/v1/status/worlds": { "get": { "operationId": "worlds.status", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "address": { "type": "string" }, "checkedAt": { "type": "string" }, "latencyMs": { "type": "integer" }, "mspt": { "type": "number" }, "online": { "type": "boolean" }, "players": { "additionalProperties": false, "properties": { "current": { "type": "integer" }, "max": { "type": "integer" }, "sample": { "items": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "type": "array" } }, "required": [ "current", "max" ], "type": "object" }, "tps": { "type": "number" }, "world": { "type": "string" } }, "required": [ "world", "online" ], "type": "object" }, "type": "array" } }, "required": [ "items" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Which of our worlds are up, and how many people are on them.", "tags": [ "worlds" ] } }, "/api/v1/support": { "get": { "operationId": "content.support", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "methods": { "items": { "additionalProperties": false, "properties": { "details": { "items": { "additionalProperties": false, "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "label", "value" ], "type": "object" }, "type": "array" }, "href": { "type": "string" }, "id": { "type": "string" }, "kind": { "description": "card", "type": "string" }, "label": { "type": "string" }, "recurring": { "type": "boolean" } }, "required": [ "id", "kind", "label" ], "type": "object" }, "type": "array" }, "monthlyCost": { "additionalProperties": false, "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "supporters": { "type": "integer" }, "targets": { "items": { "additionalProperties": false, "properties": { "current": { "type": "boolean" }, "description": { "type": "string" }, "goal": { "additionalProperties": false, "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "id": { "type": "string" }, "raised": { "additionalProperties": false, "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "type": "array" } }, "required": [ "targets", "methods" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "What supporting the project pays for, and the ways to do it.", "tags": [ "content" ] } }, "/api/v1/updates/builds": { "get": { "operationId": "updates.builds", "parameters": [ { "in": "query", "name": "app", "required": false, "schema": { "description": "Which product", "type": "string" } }, { "in": "query", "name": "channel", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "locale", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "tag", "required": false, "schema": { "description": "One released version exactly", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "app": { "type": "string" }, "channel": { "type": "string" }, "files": { "items": { "additionalProperties": false, "properties": { "arch": { "type": "string" }, "filename": { "type": "string" }, "kind": { "type": "string" }, "os": { "type": "string" }, "sha256": { "type": "string" }, "signed": { "type": "boolean" }, "size": { "type": "integer" }, "target": { "type": "string" }, "url": { "type": "string" } }, "required": [ "target", "os", "arch", "kind", "filename", "size", "url" ], "type": "object" }, "type": "array" }, "name": { "type": "string" }, "notes": { "type": "string" }, "portals": { "items": { "additionalProperties": false, "properties": { "target": { "type": "string" }, "url": { "type": "string" } }, "required": [ "target", "url" ], "type": "object" }, "type": "array" }, "publishedAt": { "type": "string" }, "tag": { "type": "string" }, "version": { "type": "string" } }, "required": [ "app", "name", "version", "channel", "tag", "publishedAt", "files" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Everything there is to download for one product, with sizes and systems in words.", "tags": [ "updates" ] } }, "/api/v1/updates/bundle/{app}": { "get": { "operationId": "updates.bundle", "parameters": [ { "in": "path", "name": "app", "required": true, "schema": { "description": "Which product", "type": "string" } }, { "in": "query", "name": "channel", "required": false, "schema": { "description": "alpha", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "app": { "type": "string" }, "channel": { "type": "string" }, "filename": { "type": "string" }, "installerUrl": { "type": "string" }, "publishedAt": { "type": "string" }, "sha256": { "type": "string" }, "signatureUrl": { "type": "string" }, "size": { "type": "integer" }, "tag": { "type": "string" }, "url": { "type": "string" }, "version": { "type": "string" } }, "required": [ "app", "version", "tag", "channel", "publishedAt", "filename", "size", "url" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "The newest version of a product that installs from a script (STYGION OS): version, sha256 and pinned addresses of the tarball, its signature and install.sh.", "tags": [ "updates" ] } }, "/api/v1/updates/bundle/{app}/{file}": { "get": { "operationId": "updates.bundleFile", "parameters": [ { "in": "path", "name": "app", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "channel", "required": false, "schema": { "type": "string" } }, { "in": "path", "name": "file", "required": true, "schema": { "description": "install.sh", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "Body": true, "ContentType": { "type": "string" }, "Filename": { "type": "string" }, "Size": { "type": "integer" }, "URL": { "type": "string" } }, "required": [ "Body", "ContentType", "Filename", "Size", "URL" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "One file of the newest version of a script-installed product, under an address that never changes: install.sh, bundle.tar.gz or bundle.tar.gz.minisig.", "tags": [ "updates" ] } }, "/api/v1/updates/changelog": { "get": { "operationId": "updates.changelog", "parameters": [ { "in": "query", "name": "app", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "from", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "locale", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "to", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "notes": { "type": "string" } }, "required": [ "notes" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "What changed between two versions, in the reader's language.", "tags": [ "updates" ] } }, "/api/v1/updates/download": { "get": { "operationId": "updates.download", "parameters": [ { "in": "query", "name": "app", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "kind", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "tag", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "target", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "Body": true, "ContentType": { "type": "string" }, "Filename": { "type": "string" }, "Size": { "type": "integer" }, "URL": { "type": "string" } }, "required": [ "Body", "ContentType", "Filename", "Size", "URL" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "The file itself. Large, but a read like any other.", "tags": [ "updates" ] } }, "/api/v1/updates/keystone-min-safe": { "get": { "operationId": "updates.keystoneMinSafe", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "version": { "description": "The oldest Keystone version the launcher offers to install for a server.", "type": "string" } }, "required": [ "version" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "The oldest Keystone the launcher will install for a server. The update check carries the same number.", "tags": [ "updates" ] } }, "/api/v1/updates/latest": { "get": { "operationId": "updates.latest", "parameters": [ { "in": "query", "name": "app", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "locale", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "channel": { "type": "string" }, "date": { "type": "string" }, "downloads": { "additionalProperties": { "type": "string" }, "type": "object" }, "notes": { "type": "string" }, "tag": { "type": "string" }, "version": { "type": "string" } }, "required": [ "channel", "tag", "version", "date", "notes", "downloads" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "The newest build worth offering a visitor, and where to get it.", "tags": [ "updates" ] } }, "/api/v1/updates/update-check": { "get": { "operationId": "updates.check", "parameters": [ { "in": "query", "name": "app", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "channel", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "current", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "hasUpdate": { "type": "boolean" }, "keystoneMinSafeVersion": { "type": "string" }, "manifest": { "additionalProperties": false, "properties": { "forced": { "type": "boolean" }, "notes": { "type": "string" }, "platforms": { "additionalProperties": { "additionalProperties": false, "properties": { "signature": { "type": "string" }, "url": { "type": "string" } }, "required": [ "signature", "url" ], "type": "object" }, "type": "object" }, "pub_date": { "type": "string" }, "version": { "type": "string" } }, "required": [ "version", "notes", "pub_date", "platforms", "forced" ], "type": "object" } }, "required": [ "hasUpdate", "manifest" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Whether a desktop client should update, and the manifest if it should.", "tags": [ "updates" ] } }, "/api/v1/updates/update-check-server": { "get": { "operationId": "updates.checkServer", "parameters": [ { "in": "query", "name": "app", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "channel", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "current", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "hasUpdate": { "type": "boolean" }, "update": { "additionalProperties": false, "properties": { "assets": { "additionalProperties": { "additionalProperties": false, "properties": { "sha256": { "type": "string" }, "url": { "type": "string" } }, "required": [ "url" ], "type": "object" }, "type": "object" }, "date": { "type": "string" }, "forced": { "type": "boolean" }, "notes": { "type": "string" }, "tag": { "type": "string" }, "version": { "type": "string" } }, "required": [ "version", "tag", "notes", "date", "assets", "forced" ], "type": "object" } }, "required": [ "hasUpdate", "update" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "The same question for a self-hosted build, which ships as a tarball.", "tags": [ "updates" ] } }, "/api/v1/wallpapers": { "get": { "operationId": "content.wallpapers", "parameters": [ { "in": "query", "name": "tag", "required": false, "schema": { "description": "Only wallpapers carrying this tag.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "credit": { "type": "string" }, "description": { "type": "string" }, "id": { "type": "string" }, "preview": { "additionalProperties": false, "properties": { "alt": { "type": "string" }, "src": { "type": "string" } }, "required": [ "src", "alt" ], "type": "object" }, "product": { "type": "string" }, "publishedAt": { "type": "string" }, "sizes": { "items": { "additionalProperties": false, "properties": { "bytes": { "type": "integer" }, "height": { "type": "integer" }, "href": { "type": "string" }, "label": { "description": "What a person recognises: Desktop 4K", "type": "string" }, "width": { "type": "integer" } }, "required": [ "label", "width", "height", "href" ], "type": "object" }, "type": "array" }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": "string" } }, "required": [ "id", "title", "preview", "sizes", "tags", "publishedAt" ], "type": "object" }, "type": "array" } }, "required": [ "items" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "Our artwork, in the sizes that were actually rendered.", "tags": [ "content" ] } }, "/api/v1/wallpapers/{id}": { "get": { "operationId": "content.wallpaper", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "credit": { "type": "string" }, "description": { "type": "string" }, "id": { "type": "string" }, "preview": { "additionalProperties": false, "properties": { "alt": { "type": "string" }, "src": { "type": "string" } }, "required": [ "src", "alt" ], "type": "object" }, "product": { "type": "string" }, "publishedAt": { "type": "string" }, "sizes": { "items": { "additionalProperties": false, "properties": { "bytes": { "type": "integer" }, "height": { "type": "integer" }, "href": { "type": "string" }, "label": { "description": "What a person recognises: Desktop 4K", "type": "string" }, "width": { "type": "integer" } }, "required": [ "label", "width", "height", "href" ], "type": "object" }, "type": "array" }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": "string" } }, "required": [ "id", "title", "preview", "sizes", "tags", "publishedAt" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "One wallpaper, so it can be linked to rather than only browsed.", "tags": [ "content" ] } }, "/api/v1/worlds/{key}/join": { "get": { "operationId": "worlds.join", "parameters": [ { "in": "path", "name": "key", "required": true, "schema": { "description": "The world's key", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "address": { "type": "string" }, "name": { "type": "string" }, "pack": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string" }, "version": { "type": "string" } }, "required": [ "source", "id", "version", "name" ], "type": "object" }, "port": { "type": "integer" }, "world": { "type": "string" } }, "required": [ "world", "name", "address", "port" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "What a launcher needs to put somebody in a world: the pack, its version and the address.", "tags": [ "worlds" ] } }, "/api/v1/worlds/{key}/leaders": { "get": { "operationId": "worlds.leaders", "parameters": [ { "in": "path", "name": "key", "required": true, "schema": { "description": "Which world.", "type": "string" } }, { "in": "query", "name": "season", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "chapters": { "items": { "additionalProperties": false, "properties": { "craft": { "type": "string" }, "done": { "type": "integer" }, "key": { "type": "string" }, "name": { "type": "string" }, "people": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "key", "done", "total", "people" ], "type": "object" }, "type": "array" }, "crowns": { "items": { "additionalProperties": false, "properties": { "craft": { "type": "string" }, "done": { "type": "integer" }, "player": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "moved": { "type": "integer" }, "name": { "type": "string" }, "playtime": { "type": "integer" }, "quests": { "type": "integer" }, "seenAt": { "type": "string" }, "since": { "type": "string" } }, "required": [ "id", "name", "quests" ], "type": "object" }, "total": { "type": "integer" } }, "required": [ "craft", "player", "done", "total" ], "type": "object" }, "type": "array" }, "loose": { "items": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "moved": { "type": "integer" }, "name": { "type": "string" }, "playtime": { "type": "integer" }, "quests": { "type": "integer" }, "seenAt": { "type": "string" }, "since": { "type": "string" } }, "required": [ "id", "name", "quests" ], "type": "object" }, "type": "array" }, "season": { "additionalProperties": false, "properties": { "endedAt": { "type": "string" }, "key": { "type": "string" }, "line": { "type": "string" }, "live": { "type": "boolean" }, "name": { "type": "string" }, "startedAt": { "type": "string" } }, "required": [ "key", "live" ], "type": "object" }, "seasons": { "items": { "additionalProperties": false, "properties": { "endedAt": { "type": "string" }, "key": { "type": "string" }, "line": { "type": "string" }, "live": { "type": "boolean" }, "name": { "type": "string" }, "startedAt": { "type": "string" } }, "required": [ "key", "live" ], "type": "object" }, "type": "array" }, "teams": { "items": { "additionalProperties": false, "properties": { "key": { "type": "string" }, "members": { "items": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "moved": { "type": "integer" }, "name": { "type": "string" }, "playtime": { "type": "integer" }, "quests": { "type": "integer" }, "seenAt": { "type": "string" }, "since": { "type": "string" } }, "required": [ "id", "name", "quests" ], "type": "object" }, "type": "array" }, "name": { "type": "string" }, "quests": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "key", "quests", "total" ], "type": "object" }, "type": "array" }, "together": { "additionalProperties": false, "properties": { "done": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "done", "total" ], "type": "object" } }, "required": [ "season", "together" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "How a world's season is going: what the whole server has finished together, who leads each craft, which chapters nobody has touched, and the teams.", "tags": [ "worlds" ] } }, "/api/v1/worlds/{key}/players/{player}": { "get": { "operationId": "worlds.player", "parameters": [ { "in": "path", "name": "key", "required": true, "schema": { "description": "Which world.", "type": "string" } }, { "in": "path", "name": "player", "required": true, "schema": { "description": "The Minecraft name.", "type": "string" } }, { "in": "query", "name": "season", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "chapters": { "items": { "additionalProperties": false, "properties": { "craft": { "type": "string" }, "done": { "type": "integer" }, "key": { "type": "string" }, "name": { "type": "string" }, "total": { "type": "integer" } }, "required": [ "key", "done", "total" ], "type": "object" }, "type": "array" }, "crafts": { "additionalProperties": { "type": "integer" }, "type": "object" }, "player": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "moved": { "type": "integer" }, "name": { "type": "string" }, "playtime": { "type": "integer" }, "quests": { "type": "integer" }, "seenAt": { "type": "string" }, "since": { "type": "string" } }, "required": [ "id", "name", "quests" ], "type": "object" }, "season": { "additionalProperties": false, "properties": { "endedAt": { "type": "string" }, "key": { "type": "string" }, "line": { "type": "string" }, "live": { "type": "boolean" }, "name": { "type": "string" }, "startedAt": { "type": "string" } }, "required": [ "key", "live" ], "type": "object" }, "team": { "type": "string" } }, "required": [ "season", "player" ], "type": "object" } } }, "description": "Success." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was not understood." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sign in and try again." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "There is nothing here, or nothing you may see." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something on our side went wrong." } }, "summary": "One player's season on one world: their progress, chapter by chapter.", "tags": [ "worlds" ] } } }, "servers": [ { "url": "https://api.stygion.eu" } ] }