{ "openapi": "3.0.0", "info": { "title": "GenHTTP Lambda API", "description": "GenHTTP Lambda hosts small C# web applications. A **lambda** is a snippet of C#\nthat returns a [GenHTTP](https://genhttp.org/) handler - a page, an API, a\nwebsite, a websocket - plus whatever other files it needs. The platform compiles\nit and serves it at an address of its own, `https://{publicKey}.{hosting domain}/`.\nThis API is everything the editor does: create a lambda, save its versions, put\none online, look at its data, its traffic and its logs.\n\n## Getting started\n\n```bash\n# 1. create a lambda - keep its privateKey,\n# which cannot be recovered\ncurl -X POST {server}/lambdas \\\n -H 'Content-Type: application/json' \\\n -d '{ \"acceptedTerms\": true }'\n\n# 2. save its code as a version, and put\n# it online in the same call\ncurl -X POST \\\n '{server}/lambdas/{privateKey}/versions?deploy=true' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"files\": [ {\n \"name\": \"lambda.cs\",\n \"code\": \"return Inline.Create().Get(() => \\\"Hi\\\");\"\n } ],\n \"change\": \"Says hi\"\n }'\n\n# 3. it answers at the address the answer\n# names (deployment.lambda.address)\n```\n\nThe terms that step 1 accepts are in `GET /system`, along with this\ninstallation's limits and the address template (`lambdaUrl`). The demos\n(`GET /demos`) are finished lambdas to read, and to start from: pass a demo's\n`id` as the `template` when creating a lambda.\n\n## Who may do what\n\nThere are no accounts. A lambda has two keys:\n\n- The **public key** names its address. It is not a secret, and its owner may\n change it.\n- The **private key** (the *editor key*) is in the path of every call that reads\n or changes the lambda: `/lambdas/{privateKey}/…`. Holding it is the\n authorization. Whoever has it may change, deploy and delete the lambda, so treat\n it like a password: do not log it or put it in a URL a third party sees. It is\n handed out once, to whoever creates the lambda, and cannot be recovered.\n\nA key that names no lambda is answered with `404`, the same way as one whose\nlambda was deleted. The demos' editor keys are public. A demo can be read like\nany other lambda, but every change is refused with `403`.\n\nThe operations under *Operating the installation* are for whoever runs the\nserver. They take the token of the installation in the `X-Admin-Token` header:\n`401` without it, `403` with a wrong one. An installation without a token does not\nhave them at all (`404`).\n\n## What a lambda is made of\n\n- A **version** is the program: its code and its resources. It never changes\n once it is saved; a change is a new version. Saving one does not put it online,\n deploying does (`?deploy=true` on a save, or `POST …/deployment/start`).\n A new lambda starts with version 1, which is the template it was made from,\n and nothing is online until a version is deployed. Only so many versions are\n kept (see the limits); the oldest go first, but never the version that is\n online or one a feature is based on.\n- The **data** is what the program keeps: its **database** (SQLite), its\n **workspace** (files it reads and writes) and its **secrets** (API keys,\n passwords). Data belongs to the lambda and is shared by every version.\n Deploying, rolling back and merging never touch it. Each kind of data is\n switched on before the lambda can use it (`PUT …/data/{kind}`). Switching a\n kind off deletes everything it held.\n- A **feature** is a change worked on beside the lambda. It starts as a copy of\n a version and of the data, is saved in place as often as needed, has a preview\n at its own address, and becomes the next version when it is merged. Only a\n feature based on the newest version can be merged.\n\n## Files\n\nA version is sent and read as a list of files:\n\n```json\n{ \"name\": \"lambda.cs\", \"code\": \"return Inline.Create()…;\" }\n{ \"name\": \"resources/web/logo.png\", \"code\": \"iVBORw0KGgo…\", \"encoding\": \"base64\" }\n```\n\n- `lambda.cs` comes first. It is the snippet that returns the handler.\n- Every other `.cs` file, in any folder, is compiled with it.\n- Files below `resources/` are the **resources**: what the lambda reads and\n serves while it runs (`Resources.App(\"web\")` serves `resources/web/`).\n- Every other file - `docs/product.md`, `tests/README.md`, the sources of a front\n end - is kept with the version and never compiled or served.\n- Text is sent as it is. Anything else is sent base64 encoded with\n `\"encoding\": \"base64\"`. C# files are always text.\n- Names are case sensitive, but two names that differ only by their case are\n refused, as are names that would not survive a clone or a zip on Windows. A\n refused save says which name it refused and why.\n\nA save that only changes some files does not have to send all of them:\n`POST …/versions/changes` and `POST …/features/{feature}/changes` add, replace and\nremove files, or replace text inside them.\n\n## Limits\n\nWhat a version may come to (its code and resources together), the room its data\nmay take (database and workspace together), and how many versions and features\nare kept are set by the operator of the installation, per tier, and may change.\nRead them instead of assuming them: `GET /system` for a new lambda, and the\n`limits` of `GET /lambdas/{privateKey}/summary` for an existing one. A save or\nan upload that does not fit is refused with `400`, and a feature or a secret\nmore than a lambda may have with `409`. The message names the limit either\nway.\n\nThe tier of a lambda (`Free`, `Premium` or `Demo`) is assigned by the operator.\nA free lambda that nobody visits or edits for a while is taken offline, and\nlater removed. `deployedUntil` and `keptUntil` say when; both move forward with\nevery visit and every edit.\n\n## Answers and errors\n\nRequests and answers are JSON unless an operation says otherwise. Field names are\ncamelCase, times are ISO 8601 in UTC, and sizes are in bytes. Where a body is\noptional, or a field is left out of a `PATCH`, what is left out stays as it is.\n\nA request that is refused is answered with a status code and a JSON body:\n\n```json\n{\n \"status\": 409,\n \"error\": \"Conflict\",\n \"message\": \"This key is already in use.\"\n}\n```\n\n- `400` **Invalid**: the request cannot be carried out as it is. The message says\n what to change.\n- `403` **Forbidden**: not for this lambda - it is a demo, or its tier does not\n include what was asked for.\n- `404` **NotFound**: the lambda, version, feature, file or table does not exist.\n- `409` **Conflict**: it collides with the state of the lambda - a key or a domain\n that is taken, a feature that is behind the newest version, a save based on a\n state that changed in the meantime. Read again, then retry.\n- `429` **TooMany**: asked for too often lately. Try again later.\n\nThe `message` is written for a person or an agent to act on. Pass it on rather\nthan replacing it. Code that does not compile is not an error of the request:\ndeploying, previewing and merging answer it with `422` and the compiler's\n`diagnostics`, and leave what was online as it was.\n\nA request that fails before the platform's own checks - a body that is not valid\nJSON, a build agent that cannot be reached - is answered with the framework's\nerror body, which has `status` and `message` but no `error`.\n\n## Other ways in\n\nThe same platform is available to AI agents as an MCP server at `/mcp`. Every\nlambda is also a git repository: clone it from the `gitPath` of the lambda, push\nto `main` to save versions, and push a branch to start a feature.\n", "version": "v1" }, "servers": [ { "url": "https://genhttp.dev/api/v1" } ], "paths": { "/lambdas": { "post": { "tags": [ "Lambdas" ], "summary": "Creates a lambda", "description": "The new lambda is in the free tier and has one version: a copy of the `template`, or a snippet that says hello if\nnone is given. Nothing is online until a version is deployed (`POST /lambdas/{privateKey}/deployment/start`, or a\nsave with `?deploy=true`). A copy of a demo that keeps records starts with an empty database of its own, switched on;\nthe demo's records are not copied.\n\nThe answer holds the editor key (`privateKey`). It is handed out this once and cannot be recovered: whoever loses it\nloses the lambda, and whoever finds it may change it.\n\nA `publicKey` that is asked for is trimmed and lower cased, and must be 3 to 40 characters of `a-z`, `0-9` and `-`,\nneither starting nor ending with a dash. It may not start with `demo-` or `xn--`, and a few names are reserved for\nthe platform (`www`, `api`, `admin`, `mail` and the like). `GET /keys/{publicKey}` says whether a key can be claimed\nbefore trying. Left out, a random key of eight characters is chosen.", "operationId": "lambdasPOST", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLambdaRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/CreateLambdaRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CreateLambdaRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/CreateLambdaRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/CreateLambdaRequest" } } } }, "responses": { "201": { "description": "The lambda was created. Keep `privateKey`: it is not handed out again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LambdaResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/LambdaResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/LambdaResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/LambdaResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/LambdaResponse" } } } }, "400": { "description": "The terms were not accepted, or the key, the template or the view cannot be used. The message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Another lambda has the public key that was asked for.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}": { "get": { "tags": [ "Lambdas" ], "summary": "Reads a lambda", "description": "Its keys and tier, its newest version and the one online, until when it stays online and is kept, and where it answers.", "operationId": "lambdasGET", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The lambda", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LambdaResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/LambdaResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/LambdaResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/LambdaResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/LambdaResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Lambdas" ], "summary": "Changes the public key or the view of a lambda", "description": "What the request leaves out stays as it is.\n\nA new `publicKey` follows the rules of `POST /lambdas` and moves the address the lambda answers at, at once: nothing\nanswers at the old address any more, and anybody may claim it. A domain of the lambda's own is not affected.\n\nThe `view` is only what the editor opens in for somebody who has not picked a view of their own.", "operationId": "lambdasPATCH", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLambdaRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/UpdateLambdaRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/UpdateLambdaRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/UpdateLambdaRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/UpdateLambdaRequest" } } } }, "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The lambda afterwards", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LambdaResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/LambdaResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/LambdaResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/LambdaResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/LambdaResponse" } } } }, "400": { "description": "The key or the view cannot be used. Nothing was changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Another lambda has the public key that was asked for.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The lambda is a demo, which anybody may read and nobody may change. Create a lambda of your own from it instead: `POST /lambdas` with the demo's id as `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Lambdas" ], "summary": "Deletes a lambda for good", "description": "Takes it offline and removes everything kept for it: every version, every feature with its preview, its database,\nworkspace and secrets, its showcase entry and published source, and what was counted of its visitors. This cannot be\nundone, and its public key is free for anybody to claim afterwards. `GET …/export` takes a copy first.", "operationId": "lambdasDELETE", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "The lambda and everything kept for it are gone." }, "403": { "description": "The lambda is a demo, which anybody may read and nobody may change. Create a lambda of your own from it instead: `POST /lambdas` with the demo's id as `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/export": { "get": { "tags": [ "Lambdas" ], "summary": "Exports the lambda as a .NET project", "description": "A zip of the **newest** version - not necessarily the one online - as a .NET 10 project on GenHTTP: a `Program.cs`\nthat hosts the snippet, stand-ins for what the platform provides in `Platform/`, and a `Dockerfile`. `dotnet run` or\n`docker build` it, and it serves what the lambda serves.\n\nThe database comes along as `database/database.db`, a copy taken while the request is answered, which the project\nopens as the lambda opened it here. The workspace does not come along, and neither do the values of the secrets: the\nproject reads them from environment variables of the same names, which `Program.cs` lists. A published source\ncarries its `LICENSE`. Exporting changes nothing about the lambda.", "operationId": "export", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "responses": { "200": { "description": "The project, as a zip archive", "headers": { "Content-Disposition": { "description": "`attachment`, named after the public key: `quiz.zip`", "schema": { "title": "String", "type": "string" } } }, "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "No lambda has this editor key, or it has no version to export.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/versions": { "get": { "tags": [ "Versions" ], "summary": "Lists the versions that are kept, newest first", "description": "Without their files. `GET …/versions/{version}` reads one with them.", "operationId": "versionsAll", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The versions, newest first", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VersionResponse" } } }, "application/yaml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VersionResponse" } } }, "application/x-www-form-urlencoded": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VersionResponse" } } }, "application/xml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VersionResponse" } } }, "text/xml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VersionResponse" } } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Versions" ], "summary": "Saves every file of the lambda as a new version", "description": "`files` is the whole lambda, `lambda.cs` first: a file the newest version has and this request does not is not in\nthe new version. To change a few files, `POST …/versions/changes` sends only those.\n\nA file name may be refused - a C# file has to be named as C# names its files, a resource needs an extension, and\nno name may hold spaces or be one Windows reserves; the message says what is wrong with which. The files together\nmay not come to more than the tier of the lambda allows a version (see the limits). Whether the code compiles is\nnot checked unless it is deployed: `POST …/code/check` compiles it without saving.", "operationId": "versionsPOST", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "deploy", "in": "query", "description": "Whether to put the new version online as well. The version is saved either way; whether it went online is in `deployment`.", "schema": { "title": "Boolean", "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/VersionRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/VersionRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/VersionRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/VersionRequest" } } } }, "responses": { "201": { "description": "The version was saved. If it was to be deployed as well, `deployment` says whether that worked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedVersionResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/SavedVersionResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SavedVersionResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/SavedVersionResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/SavedVersionResponse" } } } }, "400": { "description": "There are no files, `lambda.cs` is not the first, a name or an encoding cannot be used, or the files are larger than a version may be. Nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The lambda is a demo, which anybody may read and nobody may change. Create a lambda of your own from it instead: `POST /lambdas` with the demo's id as `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/versions/{version}": { "get": { "tags": [ "Versions" ], "summary": "Reads a version with its files", "description": "Every file, `lambda.cs` first, unless a `folder` is named: `?folder=docs/` reads the documentation of the version\nand `?folder=tests/` its tests, without every resource coming along.", "operationId": "versionsGET", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "version", "in": "path", "required": true, "description": "The number of the version, counting from 1", "schema": { "title": "Integer", "type": "integer", "format": "int32" } }, { "name": "folder", "in": "query", "description": "Only the files whose name starts with this, such as `docs/` or `resources/`", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The version with its files", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionContentResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/VersionContentResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/VersionContentResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/VersionContentResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/VersionContentResponse" } } } }, "404": { "description": "No lambda has this editor key, or it has no such version - it never existed, or it was not kept.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/versions/{version}/zip": { "get": { "tags": [ "Versions" ], "summary": "Downloads a version as a zip archive", "description": "The archive holds the files as the lambda names them, so it can be changed locally and saved again as a new version\nwith `POST …/versions/zip`. With `?layout=project` it holds them where a clone of the lambda's git repository has\nthem instead, so a .NET tool set up in a clone finds them where it looks. Unlike the export, it holds no project\naround them and no data.", "operationId": "zipGET", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "version", "in": "path", "required": true, "description": "The number of the version, counting from 1", "schema": { "title": "Integer", "type": "integer", "format": "int32" } }, { "name": "layout", "in": "query", "description": "How the files are laid out: `lambda` (the default) names them as the lambda does, `project` as a clone of its git repository has them - the snippet as `Project.cs`, the other C# files named the .NET way, the platform's own files left out", "schema": { "title": "String", "type": "string" } } ], "responses": { "200": { "description": "The files, as a zip archive", "headers": { "Content-Disposition": { "description": "`attachment`, named after the public key and the version: `quiz-v3.zip`, or `quiz-v3-project.zip`", "schema": { "title": "String", "type": "string" } } }, "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "There is no such layout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key, or it has no such version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/versions/zip": { "post": { "tags": [ "Versions" ], "summary": "Saves a zip archive as a new version", "description": "The archive replaces every file, so it has to hold all of them: a file it leaves out is not in the new version.\n\nIt is read as a commit of the files would be. A single folder around everything is removed. A git repository is\nskipped, and so is what the `.gitignore` files in the archive leave out - except files the newest version already\nhas, which are kept as git keeps what it tracks. Other dot files of the code are kept; hidden files among the\nresources are skipped. Text files are kept as text, anything that is not UTF-8 as base64. With `?layout=project`\nthe archive is read as a clone of the lambda's git repository has it, and the platform's own files are left out.\n\nThe archive is counted as it is sent, before anything is left out, against what a version may come to. Zip what a\ncommit would hold - never what a build installed (`node_modules`, for example).", "operationId": "zipPOST", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "deploy", "in": "query", "description": "Whether to put the new version online as well. The version is saved either way; whether it went online is in `deployment`.", "schema": { "title": "Boolean", "type": "boolean" } }, { "name": "specification", "in": "query", "description": "What the user wants from this version and why, in their words where possible. Kept with the version, cut past 4000 characters.", "schema": { "title": "String", "type": "string" } }, { "name": "change", "in": "query", "description": "What this version changes, in one line for the owner. Kept with the version, cut past 500 characters.", "schema": { "title": "String", "type": "string" } }, { "name": "layout", "in": "query", "description": "How the files are laid out: `lambda` (the default) names them as the lambda does, `project` as a clone of its git repository has them - the snippet as `Project.cs`, the other C# files named the .NET way, the platform's own files left out", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "description": "A zip archive of every file of the lambda", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } }, "required": true }, "responses": { "201": { "description": "The version was saved. If it was to be deployed as well, `deployment` says whether that worked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedVersionResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/SavedVersionResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SavedVersionResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/SavedVersionResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/SavedVersionResponse" } } } }, "400": { "description": "The body is not a zip archive, it is larger than a version may be, it has no `lambda.cs`, or a file in it cannot be part of a lambda. The message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The lambda is a demo, which anybody may read and nobody may change. Create a lambda of your own from it instead: `POST /lambdas` with the demo's id as `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/versions/changes": { "post": { "tags": [ "Versions" ], "summary": "Saves changes to some files as a new version", "description": "Files that are not named stay as they are, so a small change does not send every file again. The changes are\napplied in this order: `remove` takes files out, `files` adds files or replaces those of the same name, and `edits`\nreplaces text within files - each `find` has to occur exactly once in its file, or nothing is saved. What results\nhas to be a valid lambda, as for any save.", "operationId": "changes", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "deploy", "in": "query", "description": "Whether to put the new version online as well. The version is saved either way; whether it went online is in `deployment`.", "schema": { "title": "Boolean", "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionChangeRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/VersionChangeRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/VersionChangeRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/VersionChangeRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/VersionChangeRequest" } } } }, "responses": { "201": { "description": "The version was saved. If it was to be deployed as well, `deployment` says whether that worked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedVersionResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/SavedVersionResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SavedVersionResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/SavedVersionResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/SavedVersionResponse" } } } }, "400": { "description": "Nothing to change, a file to remove or edit that does not exist, a `find` that occurs never or more than once, or a result that cannot be a lambda. Nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The lambda is a demo, which anybody may read and nobody may change. Create a lambda of your own from it instead: `POST /lambdas` with the demo's id as `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/deployment": { "get": { "tags": [ "Deployment" ], "summary": "Reads what is online", "description": "Which version, since when, and until when it stays online unless it is used.", "operationId": "deployment", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "What is online", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/DeploymentResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DeploymentResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/DeploymentResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/DeploymentResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/deployment/start": { "post": { "tags": [ "Deployment" ], "summary": "Puts a version online", "description": "Compiles the version and, once it compiles, serves it from the next request on, in place of whatever was online.\nThe code that runs once as the lambda starts - outside the handler it returns, migrating its database, say - runs\nnow, and what it prints is in the lambda's log. The body is optional: without one, or without a `version`, the\nnewest version goes online.", "operationId": "start", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/DeploymentRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DeploymentRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/DeploymentRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/DeploymentRequest" } } } }, "responses": { "200": { "description": "The version is online. `diagnostics` may hold warnings of the compiler.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentOutcomeResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/DeploymentOutcomeResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DeploymentOutcomeResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/DeploymentOutcomeResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/DeploymentOutcomeResponse" } } } }, "422": { "description": "The code does not compile. `diagnostics` holds what the compiler said, with the file, line and column of each problem; nothing was put online, and whatever was online before still is.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentOutcomeResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/DeploymentOutcomeResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DeploymentOutcomeResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/DeploymentOutcomeResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/DeploymentOutcomeResponse" } } } }, "400": { "description": "The lambda has no version yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key, or it has no such version - it never existed, or it was not kept.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The lambda is a demo, which anybody may read and nobody may change. Create a lambda of your own from it instead: `POST /lambdas` with the demo's id as `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/deployment/stop": { "post": { "tags": [ "Deployment" ], "summary": "Takes the lambda offline", "description": "From the next request on, its address answers that nothing is online. Its versions and its data are kept, and\nany version can be deployed again. Nothing happens if it is offline already. The previews of its features are\nnot affected.", "operationId": "stop", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The lambda, offline", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LambdaResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/LambdaResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/LambdaResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/LambdaResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/LambdaResponse" } } } }, "403": { "description": "The lambda is a demo, which anybody may read and nobody may change. Create a lambda of your own from it instead: `POST /lambdas` with the demo's id as `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/deployment/history": { "get": { "tags": [ "Deployment" ], "summary": "Lists when the lambda was online", "description": "Which version, who put it online, how long it stayed and what ended it: the next deployment, its owner, the\nplatform because nobody used it, or the operator. The newest entry has no end while it is online. The last 200\nare kept.", "operationId": "history", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The stretches, newest first", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ActivationResponse" } } }, "application/yaml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ActivationResponse" } } }, "application/x-www-form-urlencoded": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ActivationResponse" } } }, "application/xml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ActivationResponse" } } }, "text/xml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ActivationResponse" } } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/files": { "get": { "tags": [ "Workspace" ], "summary": "Lists the files of the workspace", "operationId": "filesGET", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The files and folders of the workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceListing" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/WorkspaceListing" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/WorkspaceListing" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/WorkspaceListing" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/WorkspaceListing" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/files/{path}": { "get": { "tags": [ "Workspace" ], "summary": "Reads a file, base64 encoded", "description": "The content travels base64 encoded in JSON, so an image or an archive reads the same way as text. Up to 32 MB; a\nlarger file is refused here and read as it is from `…/{path}/content`.", "operationId": "filesGET2", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "path", "in": "path", "required": true, "description": "The path within the workspace, sent as one segment with its slashes encoded: `logs%2Ftoday.txt`", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The file, base64 encoded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/FileResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FileResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/FileResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/FileResponse" } } } }, "400": { "description": "The file is larger than 32 MB, or the path is empty or leads outside of the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key, or there is no such file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": [ "Workspace" ], "summary": "Writes a file sent base64 encoded", "description": "Replaces a file of the same path, and makes the folders it goes into. For a large file, `PUT …/{path}/content` sends it as it is.", "operationId": "filesPUT", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "path", "in": "path", "required": true, "description": "The path within the workspace, sent as one segment with its slashes encoded: `logs%2Ftoday.txt`", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/FileRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FileRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/FileRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/FileRequest" } } } }, "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The file as it was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceEntry" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/WorkspaceEntry" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/WorkspaceEntry" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/WorkspaceEntry" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/WorkspaceEntry" } } } }, "400": { "description": "The content is not base64, it does not fit into the data allowance of the lambda, or the path cannot be used. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The workspace is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The lambda is a demo, which anybody may read and nobody may change. Create a lambda of your own from it instead: `POST /lambdas` with the demo's id as `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Workspace" ], "summary": "Deletes a file, or a folder and everything in it", "description": "Nothing happens for a path where there is nothing.", "operationId": "filesDELETE", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "path", "in": "path", "required": true, "description": "The path within the workspace, sent as one segment with its slashes encoded: `logs%2Ftoday.txt`", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "Done. There is no body." }, "400": { "description": "The path is empty or leads outside of the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The lambda is a demo, which anybody may read and nobody may change. Create a lambda of your own from it instead: `POST /lambdas` with the demo's id as `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/files/{path}/content": { "get": { "tags": [ "Workspace" ], "summary": "Downloads a file as it is, however large", "description": "Always sent as bytes to save, whatever the name of the file says, so a page somebody uploaded never runs on this site.", "operationId": "contentGET", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "path", "in": "path", "required": true, "description": "The path within the workspace, sent as one segment with its slashes encoded: `logs%2Ftoday.txt`", "schema": { "title": "String", "type": "string" } } ], "responses": { "200": { "description": "The bytes of the file", "headers": { "Content-Disposition": { "description": "`attachment`, with the name of the file", "schema": { "title": "String", "type": "string" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "No lambda has this editor key, or there is no such file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": [ "Workspace" ], "summary": "Uploads a file as it is", "description": "The body is the file. It replaces a file of the same path, and the folders it goes into are made. It is written as\nit arrives and only takes the place of the old one once it is complete: an upload that is refused for want of room,\nor that ends before the `Content-Length` it announced, leaves what was there as it was. The way in for anything too\nlarge for JSON.", "operationId": "contentPUT", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "path", "in": "path", "required": true, "description": "The path within the workspace, sent as one segment with its slashes encoded: `logs%2Ftoday.txt`", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "description": "The bytes of the file", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "required": true }, "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The file as it was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceEntry" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/WorkspaceEntry" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/WorkspaceEntry" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/WorkspaceEntry" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/WorkspaceEntry" } } } }, "400": { "description": "The file does not fit into the data allowance of the lambda, the upload ended early, or the path cannot be used. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The workspace is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The lambda is a demo, which anybody may read and nobody may change. Create a lambda of your own from it instead: `POST /lambdas` with the demo's id as `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/folders/{path}": { "put": { "tags": [ "Workspace" ], "summary": "Makes a folder, with the folders it goes into", "description": "Writing a file makes its folders on its own; this is for a folder that is empty for now. Nothing happens if it is there already.", "operationId": "folders", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "path", "in": "path", "required": true, "description": "Where the folder goes within the workspace, sent as one segment with its slashes encoded", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The workspace afterwards", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceListing" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/WorkspaceListing" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/WorkspaceListing" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/WorkspaceListing" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/WorkspaceListing" } } } }, "400": { "description": "A file has that path, there is no room for another folder, or the path cannot be used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The workspace is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The lambda is a demo, which anybody may read and nobody may change. Create a lambda of your own from it instead: `POST /lambdas` with the demo's id as `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/data": { "get": { "tags": [ "Data" ], "summary": "Lists the kinds of data", "operationId": "dataAll", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "Every kind of data", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DataStoreResponse" } } }, "application/yaml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DataStoreResponse" } } }, "application/x-www-form-urlencoded": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DataStoreResponse" } } }, "application/xml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DataStoreResponse" } } }, "text/xml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DataStoreResponse" } } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/data/{kind}": { "get": { "tags": [ "Data" ], "summary": "Reads one kind of data", "operationId": "dataGET", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "kind", "in": "path", "required": true, "description": "Which kind: `database`, `workspace` or `secrets`", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The kind of data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataStoreResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/DataStoreResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DataStoreResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/DataStoreResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/DataStoreResponse" } } } }, "404": { "description": "No lambda has this editor key, or there is no such kind of data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": [ "Data" ], "summary": "Switches a kind of data on", "description": "Nothing happens if it is on already. The lambda can use it from its next request on, without being deployed again.\n\nThe database is made empty, and the lambda is started again on its next request, so what it does as it starts -\napplying its migrations - runs against it. The secrets start empty: their values are entered with\n`PUT …/secrets/{name}`.", "operationId": "dataPUT", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "kind", "in": "path", "required": true, "description": "Which kind: `database`, `workspace` or `secrets`", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The kind of data, switched on", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataStoreResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/DataStoreResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DataStoreResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/DataStoreResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/DataStoreResponse" } } } }, "404": { "description": "No lambda has this editor key, or there is no such kind of data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The lambda is a demo, which anybody may read and nobody may change. Create a lambda of your own from it instead: `POST /lambdas` with the demo's id as `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Data" ], "summary": "Switches a kind of data off and deletes it", "description": "**This cannot be undone.** Every table, file or secret of that kind is deleted, the copies of the lambda's features\nincluded. From its next request on, code that uses it fails with an exception that says it is off. `GET …/summary`\nsays whether the code of the lambda uses each kind (`usesDatabase`, `usesWorkspace`, `missingSecrets`), before\nswitching one off. Nothing happens if it is off already.", "operationId": "dataDELETE", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "kind", "in": "path", "required": true, "description": "Which kind: `database`, `workspace` or `secrets`", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The kind of data, switched off and empty", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataStoreResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/DataStoreResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DataStoreResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/DataStoreResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/DataStoreResponse" } } } }, "404": { "description": "No lambda has this editor key, or there is no such kind of data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The lambda is a demo, which anybody may read and nobody may change. Create a lambda of your own from it instead: `POST /lambdas` with the demo's id as `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/secrets": { "get": { "tags": [ "Secrets" ], "summary": "Lists the secrets by name", "description": "Never their values. The names the code reads are found in the code of the version online and of the newest one.", "operationId": "secretsGET", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The secrets by name, and the names the code reads", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretListingResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/SecretListingResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SecretListingResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/SecretListingResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/SecretListingResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/secrets/{name}": { "put": { "tags": [ "Secrets" ], "summary": "Stores a secret", "description": "The lambda reads it from its next `Secret.Read` on, without being deployed again. The value cannot be read back\nafterwards - not even by whoever stored it. Its features keep the copies they have.", "operationId": "secretsPUT", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Its name, as the code reads it: letters, digits and underscores, not starting with a digit, up to 128 characters - `STRIPE_KEY`. Case sensitive.", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/SecretRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SecretRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/SecretRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/SecretRequest" } } } }, "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The secret, without its value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/SecretResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SecretResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/SecretResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/SecretResponse" } } } }, "400": { "description": "The name is not one a secret may have, or the value is empty or larger than 32 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Secrets are switched off, or the lambda has as many secrets as it may keep.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The lambda is a demo, which anybody may read and nobody may change. Create a lambda of your own from it instead: `POST /lambdas` with the demo's id as `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Secrets" ], "summary": "Deletes a secret", "description": "From its next request on, code that reads it fails, and code that asks `Secret.Exists` is told it is not there.", "operationId": "secretsDELETE", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Its name, case sensitive", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "Done. There is no body." }, "404": { "description": "No lambda has this editor key, or it has no secret of that name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The lambda is a demo, which anybody may read and nobody may change. Create a lambda of your own from it instead: `POST /lambdas` with the demo's id as `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/features/{feature}/secrets": { "get": { "tags": [ "Secrets" ], "summary": "Lists a feature's copy of the secrets", "description": "The copy its preview reads. The names the code reads are found in the feature's files.", "operationId": "secretsGET2", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The feature's secrets by name, and the names its code reads", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretListingResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/SecretListingResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SecretListingResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/SecretListingResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/SecretListingResponse" } } } }, "404": { "description": "No lambda has this editor key, or the lambda has no feature with this key: it never existed, or it was merged or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/features/{feature}/secrets/{name}": { "put": { "tags": [ "Secrets" ], "summary": "Stores a secret in a feature's copy", "description": "For trying the feature with - a key for a sandbox, say. The lambda's own secrets are not touched, and the copy is thrown away when the feature is merged.", "operationId": "secretsPUT2", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Its name, as the code reads it: letters, digits and underscores, not starting with a digit. Case sensitive.", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/SecretRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SecretRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/SecretRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/SecretRequest" } } } }, "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The secret, without its value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/SecretResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SecretResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/SecretResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/SecretResponse" } } } }, "400": { "description": "The name is not one a secret may have, or the value is empty or larger than 32 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Secrets are switched off, or the copy has as many secrets as a lambda may keep.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key, or the lambda has no feature with this key: it never existed, or it was merged or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Secrets" ], "summary": "Deletes a secret from a feature's copy", "operationId": "secretsDELETE2", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Its name, case sensitive", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "Done. There is no body." }, "404": { "description": "No lambda has this editor key, it has no such feature, or the copy has no secret of that name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/database": { "get": { "tags": [ "Database" ], "summary": "Lists the tables of the database", "description": "And whether the lambda has a database at all, how much room it takes, and whether its code connects to it. Tables\nSQLite keeps for itself are left out; the one Evolve keeps of the migrations it applied is marked (`migrations`).\nWhile the database is switched off, the answer says so and lists nothing.", "operationId": "database", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The database and its tables", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/DatabaseResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DatabaseResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/DatabaseResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/DatabaseResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/database/tables/{table}": { "get": { "tags": [ "Database" ], "summary": "Reads rows of a table", "description": "The newest rows first, unless a column to sort by is named. Each row is a list of values in the order of the\ncolumns. A text longer than 2000 characters is cut and sent as `{ \"text\": …, \"length\": … }`, bytes as\n`{ \"blob\": length }`, and an integer beyond what JavaScript holds exactly as text.", "operationId": "tables", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "table", "in": "path", "required": true, "description": "The name of the table or view, encoded as one segment", "schema": { "title": "String", "type": "string" } }, { "name": "order", "in": "query", "description": "A column to sort by; left out, the order the rows were written in", "schema": { "title": "String", "type": "string" } }, { "name": "offset", "in": "query", "description": "How many rows to skip", "schema": { "title": "Integer", "type": "integer", "format": "int32" } }, { "name": "limit", "in": "query", "description": "How many rows to answer with, 1 to 200", "schema": { "title": "Integer", "type": "integer", "format": "int32" } }, { "name": "descending", "in": "query", "description": "Whether the order is reversed - newest, or highest, first - which it is unless this is `false`", "schema": { "title": "Boolean", "type": "boolean" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "A page of rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseRowsResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/DatabaseRowsResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DatabaseRowsResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/DatabaseRowsResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/DatabaseRowsResponse" } } } }, "404": { "description": "No lambda has this editor key, or its database has no such table.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "The table has no column of the name to sort by.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The database is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/features/{feature}/database": { "get": { "tags": [ "Database" ], "summary": "Lists the tables of a feature's database", "description": "The copy its preview reads and writes, taken when the feature was started or its data last refreshed. Its migrations may have changed its schema.", "operationId": "database2", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The feature's copy of the database and its tables", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/DatabaseResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DatabaseResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/DatabaseResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/DatabaseResponse" } } } }, "404": { "description": "No lambda has this editor key, or the lambda has no feature with this key: it never existed, or it was merged or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/features/{feature}/database/tables/{table}": { "get": { "tags": [ "Database" ], "summary": "Reads rows of a feature's database", "description": "As for the lambda's own database.", "operationId": "tables2", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } }, { "name": "table", "in": "path", "required": true, "description": "The name of the table or view, encoded as one segment", "schema": { "title": "String", "type": "string" } }, { "name": "order", "in": "query", "description": "A column to sort by; left out, the order the rows were written in", "schema": { "title": "String", "type": "string" } }, { "name": "offset", "in": "query", "description": "How many rows to skip", "schema": { "title": "Integer", "type": "integer", "format": "int32" } }, { "name": "limit", "in": "query", "description": "How many rows to answer with, 1 to 200", "schema": { "title": "Integer", "type": "integer", "format": "int32" } }, { "name": "descending", "in": "query", "description": "Whether the order is reversed, which it is unless this is `false`", "schema": { "title": "Boolean", "type": "boolean" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "A page of rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseRowsResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/DatabaseRowsResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DatabaseRowsResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/DatabaseRowsResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/DatabaseRowsResponse" } } } }, "404": { "description": "No lambda has this editor key, it has no such feature, or the copy has no such table.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "The table has no column of the name to sort by.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The lambda's database is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/features": { "get": { "tags": [ "Features" ], "summary": "Lists the features", "description": "The most recently changed first, without their files.", "operationId": "featuresAll", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The features, the most recently changed first", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FeatureResponse" } } }, "application/yaml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FeatureResponse" } } }, "application/x-www-form-urlencoded": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FeatureResponse" } } }, "application/xml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FeatureResponse" } } }, "text/xml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FeatureResponse" } } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Features" ], "summary": "Starts a feature", "description": "The feature starts from the version named as `base`, or the newest. It gets a copy of the version's files, and a\ncopy of the lambda's database, workspace and secrets as they are now - which may take a moment for a lot of data.\nIts preview is not online until it is started, or a save asks for it (`?deploy=true`). The lambda itself is not\ntouched.\n\nIt is given a `key`, which every call about it takes, and a `branch`, which is where it is in the lambda's git\nrepository. Only so many features may be open at once, as the tier of the lambda allows.", "operationId": "featuresPOST", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFeatureRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/CreateFeatureRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CreateFeatureRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/CreateFeatureRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/CreateFeatureRequest" } } } }, "responses": { "201": { "description": "The feature was started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/FeatureResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FeatureResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/FeatureResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/FeatureResponse" } } } }, "400": { "description": "The name is missing, too long (80 characters at most) or more than one line, or the lambda has no version yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The lambda has as many features open as its tier allows. Merge or delete one first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key, or it has no such version to start from.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The lambda is a demo, which anybody may read and nobody may change. Create a lambda of your own from it instead: `POST /lambdas` with the demo's id as `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/features/{feature}": { "get": { "tags": [ "Features" ], "summary": "Reads a feature with its files", "description": "Its `revision` is what a later `PUT …/files` passes to be refused, rather than replace a save made since.", "operationId": "featuresGET", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } }, { "name": "folder", "in": "query", "description": "Only the files whose name starts with this - `docs/` for its documentation, `tests/` for its tests", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The feature with its files", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureContentResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/FeatureContentResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FeatureContentResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/FeatureContentResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/FeatureContentResponse" } } } }, "404": { "description": "No lambda has this editor key, or the lambda has no feature with this key: it never existed, or it was merged or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Features" ], "summary": "Changes a feature, or moves its base", "description": "Its name, its specification or its change. What the request leaves out stays as it is; a `specification` or `change`\nsent empty is cleared. The files are not\ntouched.\n\nMove the `base` only once the changes of that version are in the feature's files. Merging replaces the lambda's\nfiles with the feature's, and nothing checks that those changes are in.", "operationId": "featuresPATCH", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFeatureRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/UpdateFeatureRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/UpdateFeatureRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/UpdateFeatureRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/UpdateFeatureRequest" } } } }, "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The feature afterwards", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/FeatureResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FeatureResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/FeatureResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/FeatureResponse" } } } }, "400": { "description": "The name is empty, too long or more than one line.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key, it has no such feature, or there is no version to move the base to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Features" ], "summary": "Deletes a feature", "description": "With its preview and its copy of the data. Its files are gone for good unless they were merged. The lambda is not touched.", "operationId": "featuresDELETE", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "Done. There is no body." }, "404": { "description": "No lambda has this editor key, or the lambda has no feature with this key: it never existed, or it was merged or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/features/{feature}/files": { "put": { "tags": [ "Features" ], "summary": "Saves every file of a feature", "description": "`files` is the whole feature, `lambda.cs` first, held to the same rules as a version - including what a version may\ncome to, since the feature becomes one. A feature keeps no history of its saves: pass the `revision` it was read\nat, and a save made in the meantime (by an agent, or in another window) is refused rather than silently replaced.", "operationId": "filesPUT2", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } }, { "name": "deploy", "in": "query", "description": "Whether to put its preview online with what was saved", "schema": { "title": "Boolean", "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureFilesRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/FeatureFilesRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FeatureFilesRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/FeatureFilesRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/FeatureFilesRequest" } } } }, "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The feature afterwards, and what came of its preview where that was asked for", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureSavedResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/FeatureSavedResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FeatureSavedResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/FeatureSavedResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/FeatureSavedResponse" } } } }, "400": { "description": "A file cannot be part of a lambda, or the files are larger than a version may be. Nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The feature was saved again since `revision`. Read it again and make the change on top of what it holds now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key, or the lambda has no feature with this key: it never existed, or it was merged or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/features/{feature}/changes": { "post": { "tags": [ "Features" ], "summary": "Changes some files of a feature", "description": "Files that are not named stay as they are. As for a version: `remove` takes files out, `files` adds or replaces\nthem, and `edits` replaces text within them, each `find` occurring exactly once. The changes are made on top of\nwhat the feature holds as the request arrives.", "operationId": "changes2", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } }, { "name": "deploy", "in": "query", "description": "Whether to put its preview online with what was saved", "schema": { "title": "Boolean", "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionChangeRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/VersionChangeRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/VersionChangeRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/VersionChangeRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/VersionChangeRequest" } } } }, "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The feature afterwards, and what came of its preview where that was asked for", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureSavedResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/FeatureSavedResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FeatureSavedResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/FeatureSavedResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/FeatureSavedResponse" } } } }, "400": { "description": "Nothing to change, a file to remove or edit that does not exist, a `find` that occurs never or more than once, or a result that cannot be a lambda. Nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The feature was saved by somebody else while this change was being made. Try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key, or the lambda has no feature with this key: it never existed, or it was merged or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/features/{feature}/zip": { "get": { "tags": [ "Features" ], "summary": "Downloads a feature as a zip archive", "description": "As for a version: the files as the lambda names them, or with `?layout=project` as a clone has them - to change them locally and put them back with `PUT …/zip`.", "operationId": "zipGET2", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } }, { "name": "layout", "in": "query", "description": "How the files are laid out: `lambda` (the default) names them as the lambda does, `project` as a clone of its git repository has them - the snippet as `Project.cs`, the other C# files named the .NET way, the platform's own files left out", "schema": { "title": "String", "type": "string" } } ], "responses": { "200": { "description": "The files, as a zip archive", "headers": { "Content-Disposition": { "description": "`attachment`, named after the start of the feature's key: `feature-3f9a1c2e.zip`", "schema": { "title": "String", "type": "string" } } }, "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "There is no such layout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key, or the lambda has no feature with this key: it never existed, or it was merged or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": [ "Features" ], "summary": "Saves a zip archive as the feature's files", "description": "The archive replaces every file of the feature, and is read exactly as one saved as a version is\n(`POST …/versions/zip`): a folder around everything removed, `.gitignore` files followed, counted as it is sent.", "operationId": "zipPUT", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } }, { "name": "deploy", "in": "query", "description": "Whether to put its preview online with what was saved", "schema": { "title": "Boolean", "type": "boolean" } }, { "name": "specification", "in": "query", "description": "What the user wants from the feature and why; left out, the one it has is kept", "schema": { "title": "String", "type": "string" } }, { "name": "change", "in": "query", "description": "What it changes, in a line; left out, the one it has is kept", "schema": { "title": "String", "type": "string" } }, { "name": "layout", "in": "query", "description": "How the files are laid out: `lambda` (the default) names them as the lambda does, `project` as a clone of its git repository has them - the snippet as `Project.cs`, the other C# files named the .NET way, the platform's own files left out", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "description": "A zip archive of every file of the feature", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } }, "required": true }, "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The feature afterwards, and what came of its preview where that was asked for", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureSavedResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/FeatureSavedResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FeatureSavedResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/FeatureSavedResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/FeatureSavedResponse" } } } }, "400": { "description": "The body is not a zip archive, it is larger than a version may be, it has no `lambda.cs`, or a file in it cannot be part of a lambda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key, or the lambda has no feature with this key: it never existed, or it was merged or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/features/{feature}/preview/start": { "post": { "tags": [ "Features" ], "summary": "Puts the preview of a feature online", "description": "Compiles the feature's files and serves them at its `previewPath`, `/features/{feature}/` on this site, against its\nown copy of the data. Nobody is sent there; it is reached by its address only. The lambda is not touched.\n\nLinks inside a lambda's pages should be relative: a feature answers below `/features/{feature}/`, where a link that\nstarts with a slash leaves it.", "operationId": "start2", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } } ], "responses": { "200": { "description": "The preview is online.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeaturePreviewResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/FeaturePreviewResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FeaturePreviewResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/FeaturePreviewResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/FeaturePreviewResponse" } } } }, "422": { "description": "The code does not compile. `diagnostics` holds what the compiler said; whatever the preview served before, it still serves.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeaturePreviewResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/FeaturePreviewResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FeaturePreviewResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/FeaturePreviewResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/FeaturePreviewResponse" } } } }, "404": { "description": "No lambda has this editor key, or the lambda has no feature with this key: it never existed, or it was merged or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/features/{feature}/preview/stop": { "post": { "tags": [ "Features" ], "summary": "Takes the preview of a feature offline", "description": "The feature, its files and its copy of the data are kept. Nothing happens if the preview is offline already.", "operationId": "stop2", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The feature afterwards", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/FeatureResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FeatureResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/FeatureResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/FeatureResponse" } } } }, "404": { "description": "No lambda has this editor key, or the lambda has no feature with this key: it never existed, or it was merged or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/features/{feature}/logs": { "get": { "tags": [ "Features" ], "summary": "Reads the log of a feature's preview", "description": "Its requests, what its code printed, and what the server said while serving it - kept apart from the lambda's own\nlog, and read the same way (`GET /lambdas/{privateKey}/logs`): oldest first, followed with `since`.", "operationId": "logs", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } }, { "name": "since", "in": "query", "description": "The `cursor` of the previous answer: only what came after it. Left out, the last 500 lines.", "schema": { "title": "Long", "type": "integer", "format": "int64" } }, { "name": "level", "in": "query", "description": "The lowest level to answer with: `debug`, `info` (the default), `warn` or `error`", "schema": { "title": "String", "type": "string" } }, { "name": "limit", "in": "query", "description": "At most this many lines, up to 2000; by default 500, or 1000 with `since`", "schema": { "title": "Integer", "type": "integer", "format": "int32" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The lines, and where to carry on from", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerLogResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/OwnerLogResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/OwnerLogResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/OwnerLogResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/OwnerLogResponse" } } } }, "404": { "description": "No lambda has this editor key, or the lambda has no feature with this key: it never existed, or it was merged or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/features/{feature}/data": { "get": { "tags": [ "Features" ], "summary": "Lists a feature's copy of the data", "description": "Which kinds are switched on is the lambda's to decide; the feature has a copy of what the lambda had when the\nfeature was started or its data was last refreshed. What is in the copies is under `…/features/{feature}/database`,\n`…/workspace` and `…/secrets`.", "operationId": "dataAll2", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "Every kind of data, as the feature's copy of it is", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DataStoreResponse" } } }, "application/yaml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DataStoreResponse" } } }, "application/x-www-form-urlencoded": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DataStoreResponse" } } }, "application/xml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DataStoreResponse" } } }, "text/xml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DataStoreResponse" } } } } }, "404": { "description": "No lambda has this editor key, or the lambda has no feature with this key: it never existed, or it was merged or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/features/{feature}/data/refresh": { "post": { "tags": [ "Features" ], "summary": "Copies the lambda's data into a feature again", "description": "The database, workspace and secrets of the feature are thrown away and copied from the lambda again, as they are\nnow. What the preview wrote into its copy is lost. The preview starts again on its next request, so it reads the\nfresh copy rather than what it held in memory.", "operationId": "refresh", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The feature afterwards", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/FeatureResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FeatureResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/FeatureResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/FeatureResponse" } } } }, "404": { "description": "No lambda has this editor key, or the lambda has no feature with this key: it never existed, or it was merged or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/features/{feature}/merge": { "post": { "tags": [ "Features" ], "summary": "Merges a feature as the next version", "description": "The feature has to be based on the newest version, and its code has to compile - a version is only ever made of\ncode that compiles. Then its files are saved as the next version, with the feature's specification and change\nunless the request says others, and the feature is deleted with its preview and its copy of the data. The lambda's\nown data is not touched, so what the preview wrote is not carried over.\n\nWith `deploy`, the new version is put online as well; `deployment` says how that went. The version is made either\nway. The body is optional.", "operationId": "merge", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeFeatureRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/MergeFeatureRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/MergeFeatureRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/MergeFeatureRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/MergeFeatureRequest" } } } }, "responses": { "201": { "description": "The feature was merged as `version`, and is gone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureMergeResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/FeatureMergeResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FeatureMergeResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/FeatureMergeResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/FeatureMergeResponse" } } } }, "422": { "description": "The code of the feature does not compile. `diagnostics` holds what the compiler said; the feature is kept as it was, to be fixed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureMergeResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/FeatureMergeResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FeatureMergeResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/FeatureMergeResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/FeatureMergeResponse" } } } }, "409": { "description": "The feature is not based on the newest version - the message says which versions to bring in - or it was saved while it was being checked. It is kept as it was.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "The feature holds exactly what the version it is based on holds, so there is nothing to merge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key, or the lambda has no feature with this key: it never existed, or it was merged or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/features/{feature}/workspace": { "get": { "tags": [ "Workspace" ], "summary": "Lists the files of a feature's workspace", "description": "What the feature's preview reads and writes. The lambda's own workspace is not touched by it.", "operationId": "workspaceGET", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The files and folders of the feature's copy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceListing" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/WorkspaceListing" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/WorkspaceListing" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/WorkspaceListing" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/WorkspaceListing" } } } }, "404": { "description": "No lambda has this editor key, or the lambda has no feature with this key: it never existed, or it was merged or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/features/{feature}/workspace/{path}": { "get": { "tags": [ "Workspace" ], "summary": "Reads a file of a feature's workspace", "description": "Up to 32 MB; a larger file is read as it is from `…/{path}/content`.", "operationId": "workspaceGET2", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } }, { "name": "path", "in": "path", "required": true, "description": "The path within the workspace, sent as one segment with its slashes encoded: `logs%2Ftoday.txt`", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The file, base64 encoded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/FileResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FileResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/FileResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/FileResponse" } } } }, "400": { "description": "The file is larger than 32 MB, or the path is empty or leads outside of the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key, or the lambda has no feature with this key: it never existed, or it was merged or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": [ "Workspace" ], "summary": "Writes a file into a feature's workspace", "operationId": "workspacePUT", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } }, { "name": "path", "in": "path", "required": true, "description": "The path within the workspace, sent as one segment with its slashes encoded: `logs%2Ftoday.txt`", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/FileRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FileRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/FileRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/FileRequest" } } } }, "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The file as it was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceEntry" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/WorkspaceEntry" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/WorkspaceEntry" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/WorkspaceEntry" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/WorkspaceEntry" } } } }, "400": { "description": "The content is not base64, it does not fit into the data allowance of the lambda, or the path cannot be used. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The lambda's workspace is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key, or the lambda has no feature with this key: it never existed, or it was merged or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Workspace" ], "summary": "Deletes from a feature's workspace", "operationId": "workspaceDELETE", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } }, { "name": "path", "in": "path", "required": true, "description": "The path within the workspace, sent as one segment with its slashes encoded: `logs%2Ftoday.txt`", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "Done. There is no body." }, "400": { "description": "The path is empty or leads outside of the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key, or the lambda has no feature with this key: it never existed, or it was merged or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/features/{feature}/workspace/{path}/content": { "get": { "tags": [ "Workspace" ], "summary": "Downloads a file of a feature's workspace", "operationId": "contentGET2", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } }, { "name": "path", "in": "path", "required": true, "description": "The path within the workspace, sent as one segment with its slashes encoded: `logs%2Ftoday.txt`", "schema": { "title": "String", "type": "string" } } ], "responses": { "200": { "description": "The bytes of the file", "headers": { "Content-Disposition": { "description": "`attachment`, with the name of the file", "schema": { "title": "String", "type": "string" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "No lambda has this editor key, or the lambda has no feature with this key: it never existed, or it was merged or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": [ "Workspace" ], "summary": "Uploads a file into a feature's workspace", "description": "As for the lambda's own workspace: of any size, replacing what is there only once the upload is complete.", "operationId": "contentPUT2", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } }, { "name": "path", "in": "path", "required": true, "description": "The path within the workspace, sent as one segment with its slashes encoded: `logs%2Ftoday.txt`", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "description": "The bytes of the file", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "required": true }, "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The file as it was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceEntry" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/WorkspaceEntry" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/WorkspaceEntry" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/WorkspaceEntry" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/WorkspaceEntry" } } } }, "400": { "description": "The file does not fit into the data allowance of the lambda, the upload ended early, or the path cannot be used. Nothing was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The lambda's workspace is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key, or the lambda has no feature with this key: it never existed, or it was merged or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/features/{feature}/folders/{path}": { "put": { "tags": [ "Workspace" ], "summary": "Makes a folder in a feature's workspace", "operationId": "folders2", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "feature", "in": "path", "required": true, "description": "The key of the feature, as `key` in the answer that started it", "schema": { "title": "String", "type": "string" } }, { "name": "path", "in": "path", "required": true, "description": "Where the folder goes within the workspace, sent as one segment with its slashes encoded", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The feature's copy of the workspace afterwards", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceListing" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/WorkspaceListing" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/WorkspaceListing" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/WorkspaceListing" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/WorkspaceListing" } } } }, "400": { "description": "A file has that path, there is no room for another folder, or the path cannot be used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The lambda's workspace is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key, or the lambda has no feature with this key: it never existed, or it was merged or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/code/check": { "post": { "tags": [ "Code analysis" ], "summary": "Compiles code without saving it", "description": "Exactly as a deployment would compile them, including the checks of what a lambda may not do, but without running\nanything. Code that does not compile is not an error of the request: it is answered with `200` and\n`success: false`. The files are held to the same rules as a save.", "operationId": "check", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/CodeRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CodeRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/CodeRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/CodeRequest" } } } }, "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "Whether it compiles, and what the compiler said", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompilationResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/CompilationResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CompilationResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/CompilationResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/CompilationResponse" } } } }, "400": { "description": "The files cannot be a lambda as they are - `lambda.cs` missing or not first, a name that cannot be used - or they are larger than a version may be.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/code/semantics": { "post": { "tags": [ "Code analysis" ], "summary": "Classifies the names in a file", "description": "For the file named by `file`, the first one if none is: where each name is, and what the compiler resolved it to.", "operationId": "semantics", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/CodeRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CodeRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/CodeRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/CodeRequest" } } } }, "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "Every name of the file, and what it means", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SemanticsResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/SemanticsResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SemanticsResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/SemanticsResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/SemanticsResponse" } } } }, "400": { "description": "There is no file of that name in the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/code/completions": { "post": { "tags": [ "Code analysis" ], "summary": "Suggests what could be written", "description": "At `line` and `column` of the file named by `file`: the members, types and keywords the compiler would accept there.", "operationId": "completions", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/CodeRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CodeRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/CodeRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/CodeRequest" } } } }, "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "What could be written there", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletionsResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/CompletionsResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CompletionsResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/CompletionsResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/CompletionsResponse" } } } }, "400": { "description": "There is no file of that name in the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/code/definition": { "post": { "tags": [ "Code analysis" ], "summary": "Finds where a name was declared", "description": "Only ever in a file of the request. A name declared elsewhere - by the framework, say - is answered with no file.", "operationId": "definition", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/CodeRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CodeRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/CodeRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/CodeRequest" } } } }, "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "Where the name was declared, or no file where that is in none of them", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefinitionResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/DefinitionResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DefinitionResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/DefinitionResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/DefinitionResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/summary": { "get": { "tags": [ "Monitoring" ], "summary": "Reads the whole of a lambda at a glance", "description": "Whether it is online and with which version, its traffic over the last hour and day, its last few problems, what\nits version and its data take, its limits, and what its documentation says. The figures about code and storage\nare about the version online, or the newest where none is.", "operationId": "summary", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The lambda at a glance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LambdaSummaryResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/LambdaSummaryResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/LambdaSummaryResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/LambdaSummaryResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/LambdaSummaryResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/traffic": { "get": { "tags": [ "Monitoring" ], "summary": "Reads the traffic of a lambda", "description": "The last hour by the minute, the last day by the quarter hour, how requests were answered, what was asked for and\nat which of its addresses. Counted in memory since the server last started, which `since` says.", "operationId": "traffic", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "Its traffic since the server came up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LambdaTraffic" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/LambdaTraffic" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/LambdaTraffic" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/LambdaTraffic" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/LambdaTraffic" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/logs": { "get": { "tags": [ "Monitoring" ], "summary": "Reads the log of a lambda", "description": "Its requests, what its code printed, and what the server said while serving it - a handler that threw, a request\nthat timed out. Oldest first. To follow it, pass the `cursor` of each answer as `since` of the next; `missed` says\nhow many lines went by unread in between. Requests are logged as warnings when they were answered with a client\nerror and as errors with a server error. The previews of its features have logs of their own.", "operationId": "logs2", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "since", "in": "query", "description": "The `cursor` of the previous answer: only what came after it. Left out, the last 500 lines.", "schema": { "title": "Long", "type": "integer", "format": "int64" } }, { "name": "level", "in": "query", "description": "The lowest level to answer with: `debug`, `info` (the default), `warn` or `error`", "schema": { "title": "String", "type": "string" } }, { "name": "limit", "in": "query", "description": "At most this many lines, up to 2000; by default 500, or 1000 with `since`", "schema": { "title": "Integer", "type": "integer", "format": "int32" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The lines, and where to carry on from", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerLogResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/OwnerLogResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/OwnerLogResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/OwnerLogResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/OwnerLogResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/showcase": { "get": { "tags": [ "Showcase" ], "summary": "Reads the showcase entry of a lambda", "operationId": "showcaseGET", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The entry, if the lambda has one, and the limits of an entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnShowcaseResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/OwnShowcaseResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/OwnShowcaseResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/OwnShowcaseResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/OwnShowcaseResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": [ "Showcase" ], "summary": "Puts a lambda into the showcase", "description": "Or changes what its entry says. A new entry needs a picture: a PNG, JPEG, GIF or WebP image, base64 encoded, no larger than the limits say. A\nchanged entry keeps its picture unless another is sent. The title (60 characters, one line) and the description\n(280 characters) are required either way, and should read plainly: what it is and what a visitor can do with it.\nThe entry is listed from now on, while the lambda is online.", "operationId": "showcasePUT", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowcaseRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/ShowcaseRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ShowcaseRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/ShowcaseRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/ShowcaseRequest" } } } }, "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The entry, as the showcase lists it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowcaseResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/ShowcaseResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ShowcaseResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/ShowcaseResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/ShowcaseResponse" } } } }, "400": { "description": "The title or the description is missing or too long, or the picture is missing, too large, not base64 or not an image of a kind that is taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The lambda is a demo, which anybody may read and nobody may change. Create a lambda of your own from it instead: `POST /lambdas` with the demo's id as `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Showcase" ], "summary": "Takes a lambda out of the showcase", "description": "Its entry and its picture are deleted. Nothing happens if it has none.", "operationId": "showcaseDELETE", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "Done. There is no body." }, "403": { "description": "The lambda is a demo, which anybody may read and nobody may change. Create a lambda of your own from it instead: `POST /lambdas` with the demo's id as `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/source": { "get": { "tags": [ "Open source" ], "summary": "Reads whether the code is published", "operationId": "sourceGET", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "What it is published under, if it ever was, and the licenses it can be published under", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnSourceResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/OwnSourceResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/OwnSourceResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/OwnSourceResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/OwnSourceResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": [ "Open source" ], "summary": "Publishes the code of a lambda", "description": "Asked again, it changes the license or the author. Every version kept is published at once, and every version saved later as well. What the request leaves out stays\nas it is; published for the first time without a license, it is MIT. The license names the `author` as the holder\nof the copyright - or, without one, \"the authors of\" the lambda. Whatever somebody downloaded keeps the license it\ncame with.", "operationId": "sourcePUT", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/SourceRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SourceRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/SourceRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/SourceRequest" } } } }, "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "What it is published under now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceSettingsResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/SourceSettingsResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SourceSettingsResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/SourceSettingsResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/SourceSettingsResponse" } } } }, "400": { "description": "The license is not one on offer, or the author is too long or more than one line.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The lambda is a demo, which anybody may read and nobody may change. Create a lambda of your own from it instead: `POST /lambdas` with the demo's id as `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Open source" ], "summary": "Takes the published code of a lambda down", "description": "From now on it is not found at `/source/{publicKey}`, and cannot be cloned. Its stars and its license are kept for\nwhen it is published again. Whatever somebody downloaded while it was published stays theirs, under the license it\ncame with. Nothing happens if it is not published.", "operationId": "sourceDELETE", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "Done. There is no body." }, "403": { "description": "The lambda is a demo, which anybody may read and nobody may change. Create a lambda of your own from it instead: `POST /lambdas` with the demo's id as `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/analytics": { "get": { "tags": [ "Analytics" ], "summary": "Reads what was counted", "description": "By day, and broken down by page, referring site, country, device, browser, system and crawler, with the same number\nof days before for comparison where the tier shows those as well. While counting is switched off, the answer says\nso and has no figures.", "operationId": "analyticsGET", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } }, { "name": "days", "in": "query", "description": "How many days, today included; left out, as many as the tier shows, which is also the most", "schema": { "title": "Integer", "type": "integer", "format": "int32" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "Whether visits are counted, and what was counted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/AnalyticsResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/AnalyticsResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/AnalyticsResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/AnalyticsResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": [ "Analytics" ], "summary": "Switches counting on", "description": "Counting starts with the next request. Nothing happens if it is on already.", "operationId": "analyticsPUT", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "Analytics, switched on", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/AnalyticsResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/AnalyticsResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/AnalyticsResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/AnalyticsResponse" } } } }, "403": { "description": "The lambda is a demo, whose visitors are not counted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Analytics" ], "summary": "Switches counting off and deletes it", "description": "**This cannot be undone**: the whole year that was kept is deleted. Switched on again, counting starts from nothing.", "operationId": "analyticsDELETE", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "Done. There is no body." }, "403": { "description": "The lambda is a demo, whose visitors are not counted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/domain": { "get": { "tags": [ "Domain" ], "summary": "Reads the domain of a lambda", "description": "The name servers are asked as the request is answered, for up to three seconds, and their answers may be cached for as long as the records say.", "operationId": "domainGET", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The domain, and what it resolves to", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/DomainResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DomainResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/DomainResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/DomainResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": [ "Domain" ], "summary": "Sets the domain a lambda answers at", "description": "Takes effect at once: the next request addressed to the domain reaches the lambda, one addressed to its previous\ndomain no longer does, and its subdomain of the hosting domain sends its visitors on to the domain from then on -\nso the domain should point here, with a certificate, first.\n\nThe domain is lower cased, an international one written as it is in the DNS, and a pasted address is forgiven its\nscheme and path. It needs an ending (`example.com`, not `example`), and may not be an IP address or a name of the\nplatform. Sending none removes it, as `DELETE` does.", "operationId": "domainPUT", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainChangeRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/DomainChangeRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DomainChangeRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/DomainChangeRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/DomainChangeRequest" } } } }, "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The domain afterwards, and what it resolves to", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/DomainResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DomainResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/DomainResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/DomainResponse" } } } }, "400": { "description": "That is not a domain that can be used. The message says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The lambda is not in the premium tier - or it is a demo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Another lambda answers at that domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Domain" ], "summary": "Removes the domain of a lambda", "description": "From the next request on it no longer answers at the domain, and its subdomain of the hosting domain answers again instead of sending visitors there. Any tier may remove a domain.", "operationId": "domainDELETE", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The lambda, without a domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/DomainResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DomainResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/DomainResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/DomainResponse" } } } }, "403": { "description": "The lambda is a demo, which anybody may read and nobody may change. Create a lambda of your own from it instead: `POST /lambdas` with the demo's id as `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/agent": { "get": { "tags": [ "Changes" ], "summary": "Reads how a change is getting on", "description": "Asked again while a change runs. The agent remembers a change for an hour after it was asked for; after that there\nis nothing to report, and what it saved is in the history of the lambda and its features.", "operationId": "agent", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "Whether there is an agent, how many changes this caller has left today, and the change under way or the last one", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentState" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/AgentState" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/AgentState" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/AgentState" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/AgentState" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The lambda is a demo, which anybody may read and nobody may change. Create a lambda of your own from it instead: `POST /lambdas` with the demo's id as `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/agent/start": { "post": { "tags": [ "Changes" ], "summary": "Asks the agent to change a lambda", "description": "The change is queued and runs in the background; `GET …/agent` follows it. The prompt is logged in full, so the\noperator knows what people ask for, and cut past 2000 characters. A request that is not about changing the\napplication is declined, and the result says why.", "operationId": "start3", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/ChangeRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ChangeRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/ChangeRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/ChangeRequest" } } } }, "responses": { "202": { "description": "The change was taken on.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentState" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/AgentState" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/AgentState" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/AgentState" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/AgentState" } } } }, "400": { "description": "The prompt says too little, or there is no such model." }, "409": { "description": "A change of this lambda is under way already. Wait for it, or stop it first." }, "404": { "description": "No lambda has this editor key, it has no such feature to go on with, or this installation takes no changes from here.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "This address asked for as many builds and changes today as one may." }, "503": { "description": "The agent is not answering. Nothing was counted." }, "403": { "description": "The lambda is a demo, which anybody may read and nobody may change. Create a lambda of your own from it instead: `POST /lambdas` with the demo's id as `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lambdas/{privateKey}/agent/stop": { "post": { "tags": [ "Changes" ], "summary": "Stops the change under way", "description": "What it saved so far stays saved - in its feature, or as a version - and whatever is online stays online. A change that is stopped is not counted back.", "operationId": "stop3", "parameters": [ { "name": "privateKey", "in": "path", "required": true, "description": "The editor key of the lambda. Holding it is what allows the call.", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The state afterwards", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentState" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/AgentState" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/AgentState" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/AgentState" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/AgentState" } } } }, "404": { "description": "No lambda has this editor key. A key that never existed and the key of a deleted lambda are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The lambda is a demo, which anybody may read and nobody may change. Create a lambda of your own from it instead: `POST /lambdas` with the demo's id as `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/keys/{publicKey}": { "get": { "tags": [ "Keys" ], "summary": "Describes a public key", "description": "Never refused: a key that cannot be claimed is answered with `valid: false` and the `reason`, as a page checking a\nkey while it is typed needs. A key that is free now may be taken by the time a lambda is created with it.", "operationId": "keys", "parameters": [ { "name": "publicKey", "in": "path", "required": true, "description": "The key to look up, in any case - it is answered the way it would be stored", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "What anybody may know about the key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/KeyResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/KeyResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/KeyResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/KeyResponse" } } } } } } }, "/demos/": { "get": { "tags": [ "Demos" ], "summary": "Lists the demos", "description": "Public. A few seconds after the server started, a demo may not be online yet (`live`).", "operationId": "demos", "responses": { "200": { "description": "Every demo", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DemoResponse" } } }, "application/yaml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DemoResponse" } } }, "application/x-www-form-urlencoded": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DemoResponse" } } }, "application/xml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DemoResponse" } } }, "text/xml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DemoResponse" } } } } } } } }, "/showcases/": { "get": { "tags": [ "Showcase" ], "summary": "Lists the showcase, a page at a time", "description": "Public. Only lambdas that are online are listed, the liveliest first: what was used over the last day, how recently\nit was visited and changed, and a few days of being seen for a new entry. The order changes as they are used, so a\npage read later may overlap the one before.", "operationId": "showcases", "parameters": [ { "name": "skip", "in": "query", "description": "How many entries to leave out, from the start", "schema": { "title": "Integer", "type": "integer", "format": "int32" } }, { "name": "take", "in": "query", "description": "How many entries to answer with, 1 to 48", "schema": { "title": "Integer", "type": "integer", "format": "int32" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "A page of entries, and where the next one starts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageOfShowcaseResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/PageOfShowcaseResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PageOfShowcaseResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/PageOfShowcaseResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/PageOfShowcaseResponse" } } } } } } }, "/showcases/{publicKey}/image": { "get": { "tags": [ "Showcase" ], "summary": "Reads the picture of a showcase entry", "description": "Public. Link it by the `imagePath` of the entry, which changes with the picture, so it may be cached for good.", "operationId": "image", "parameters": [ { "name": "publicKey", "in": "path", "required": true, "description": "The public key of the lambda", "schema": { "title": "String", "type": "string" } } ], "responses": { "200": { "description": "The picture, as it was uploaded", "headers": { "Cache-Control": { "description": "`public, max-age=31536000, immutable`", "schema": { "title": "String", "type": "string" } } }, "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "The lambda of this public key has no showcase entry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sources/": { "get": { "tags": [ "Open source" ], "summary": "Lists the published sources, a page at a time", "description": "Public. Every lambda whose owner published its code, whether or not it is online.", "operationId": "sources", "parameters": [ { "name": "search", "in": "query", "description": "Words that the key, the title or what it is about all have to contain", "schema": { "title": "String", "type": "string" } }, { "name": "order", "in": "query", "description": "`stars` (the default), the most starred first; `updated`, the most recently saved first; or `published`, the most recently published first", "schema": { "title": "String", "type": "string" } }, { "name": "skip", "in": "query", "description": "How many sources to leave out, from the start", "schema": { "title": "Integer", "type": "integer", "format": "int32" } }, { "name": "take", "in": "query", "description": "How many sources to answer with, 1 to 48", "schema": { "title": "Integer", "type": "integer", "format": "int32" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "A page of sources, and where the next one starts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageOfSourceEntryResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/PageOfSourceEntryResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PageOfSourceEntryResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/PageOfSourceEntryResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/PageOfSourceEntryResponse" } } } } } } }, "/sources/{publicKey}": { "get": { "tags": [ "Open source" ], "summary": "Reads a published source", "description": "What it is, under which license, where it runs, every version kept and what each changed - and a `starTicket` to star it with.", "operationId": "sources2", "parameters": [ { "name": "publicKey", "in": "path", "required": true, "description": "The public key of the lambda", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The source, its versions and a ticket to star it with", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceProjectResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/SourceProjectResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SourceProjectResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/SourceProjectResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/SourceProjectResponse" } } } }, "404": { "description": "There is no published source at this public key - it does not exist, or its owner has not published it, which are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sources/{publicKey}/versions/{version}": { "get": { "tags": [ "Open source" ], "summary": "Lists the files of a published version", "description": "As the project it is packed into has them - the export of that version, without its data. Packed on the first\nrequest for the version and kept, so the first answer may take a moment for a large lambda.", "operationId": "versionsGET2", "parameters": [ { "name": "publicKey", "in": "path", "required": true, "description": "The public key of the lambda", "schema": { "title": "String", "type": "string" } }, { "name": "version", "in": "path", "required": true, "description": "The number of the version, counting from 1", "schema": { "title": "Integer", "type": "integer", "format": "int32" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The files of the version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceTreeResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/SourceTreeResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SourceTreeResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/SourceTreeResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/SourceTreeResponse" } } } }, "404": { "description": "There is no published source at this public key, or it has no such version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sources/{publicKey}/versions/{version}/files/{path}": { "get": { "tags": [ "Open source" ], "summary": "Reads a file of a published version", "description": "Its text, while it is UTF-8 text no longer than a megabyte, and either way where to fetch it as it is (`rawPath`).", "operationId": "filesGET3", "parameters": [ { "name": "publicKey", "in": "path", "required": true, "description": "The public key of the lambda", "schema": { "title": "String", "type": "string" } }, { "name": "version", "in": "path", "required": true, "description": "The number of the version, counting from 1", "schema": { "title": "Integer", "type": "integer", "format": "int32" } }, { "name": "path", "in": "path", "required": true, "description": "Its path below the project's folder, encoded as one segment: `docs%2Fproduct.md`", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The file, with its text where it is text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceFileContentResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/SourceFileContentResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SourceFileContentResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/SourceFileContentResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/SourceFileContentResponse" } } } }, "404": { "description": "There is no published source at this public key, it has no such version, or the version has no such file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sources/{publicKey}/versions/{version}/raw/{path}": { "get": { "tags": [ "Open source" ], "summary": "Fetches a file of a published version as it is", "description": "A picture as a picture, anything else as plain text or as bytes - never as something a browser would run: a page\nor a script is sent as text, under a sandboxing content security policy. Bytes, and anything asked for with\n`download`, are sent to be saved.", "operationId": "raw", "parameters": [ { "name": "publicKey", "in": "path", "required": true, "description": "The public key of the lambda", "schema": { "title": "String", "type": "string" } }, { "name": "version", "in": "path", "required": true, "description": "The number of the version, counting from 1", "schema": { "title": "Integer", "type": "integer", "format": "int32" } }, { "name": "path", "in": "path", "required": true, "description": "Its path below the project's folder, encoded as one segment", "schema": { "title": "String", "type": "string" } }, { "name": "download", "in": "query", "description": "Anything but empty sends it to be saved rather than shown: `?download=1`", "schema": { "title": "String", "type": "string" } } ], "responses": { "200": { "description": "The file: a picture, `text/plain` or `application/octet-stream`", "headers": { "Content-Disposition": { "description": "`attachment`, with the name of the file - where it is bytes or `download` was asked for", "schema": { "title": "String", "type": "string" } } }, "content": { "*/*": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "There is no published source at this public key, it has no such version, or the version has no such file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sources/{publicKey}/versions/{version}/zip": { "get": { "tags": [ "Open source" ], "summary": "Downloads a published version as a project", "description": "A .NET 10 project with a `Dockerfile`, its documentation and tests, and its `LICENSE` - and none of the data the lambda keeps.", "operationId": "zipGET3", "parameters": [ { "name": "publicKey", "in": "path", "required": true, "description": "The public key of the lambda", "schema": { "title": "String", "type": "string" } }, { "name": "version", "in": "path", "required": true, "description": "The number of the version, counting from 1", "schema": { "title": "Integer", "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "The project, as a zip archive", "headers": { "Content-Disposition": { "description": "`attachment`, named after the public key and the version: `quiz-v3.zip`", "schema": { "title": "String", "type": "string" } } }, "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "There is no published source at this public key, or it has no such version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sources/{publicKey}/star": { "post": { "tags": [ "Open source" ], "summary": "Stars a published source, or takes the star back", "description": "With the `starTicket` the source was read with, which is good from a second after it was handed out for a day.\nEach address stars a source once - starring it again changes nothing, and `counted` says so - and an address may\nstar only so many sources in a while.", "operationId": "star", "parameters": [ { "name": "publicKey", "in": "path", "required": true, "description": "The public key of the lambda", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StarRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/StarRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/StarRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/StarRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/StarRequest" } } } }, "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "How it is starred now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StarResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/StarResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/StarResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/StarResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/StarResponse" } } } }, "400": { "description": "The ticket is missing, too fresh or too old. Read the source again and star it then.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "This address starred a lot in a short while. Try again in a few minutes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "There is no published source at this public key - it does not exist, or its owner has not published it, which are answered alike.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/builds/": { "post": { "tags": [ "Builds" ], "summary": "Asks the build agent to build something", "description": "The build is queued and runs in the background; `GET /builds/{id}` follows it. The prompt is logged in full, so the\noperator knows what people ask for - put nothing into it that should not be read. It is cut past 2000 characters.", "operationId": "buildsPOST", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/BuildRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/BuildRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/BuildRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/BuildRequest" } } } }, "responses": { "202": { "description": "The build was taken on. Follow it by its `id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildStarted" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/BuildStarted" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/BuildStarted" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/BuildStarted" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/BuildStarted" } } } }, "400": { "description": "The prompt says too little, or there is no such model." }, "403": { "description": "The password for the second model is not right." }, "404": { "description": "This installation builds nothing: it has no agent, or the operator switched building off." }, "429": { "description": "This address asked for as many builds today as one may." }, "503": { "description": "The agent is not answering. Nothing was counted." } } } }, "/builds/{id}": { "get": { "tags": [ "Builds" ], "summary": "Reads how a build is getting on", "description": "Asked again while it runs: its place in the queue, the steps the agent took so far, and once it is done how it\nended. The result of a build that worked holds the editor key of the new lambda, so whoever has the id of a build\ncan take the lambda it made - keep it as private as the key. The agent forgets a build some time after it ended.", "operationId": "buildsGET", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `id` of the build, as starting it returned", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "Its state, its steps, and how it ended once it has", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildProgress" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/BuildProgress" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/BuildProgress" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/BuildProgress" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/BuildProgress" } } } }, "400": { "description": "That is not the id of a build." }, "404": { "description": "The agent knows no build of this id, any more - or this installation has no agent." } } } }, "/system/": { "get": { "tags": [ "Platform" ], "summary": "Describes this installation", "description": "Its terms, which creating a lambda accepts; the limits of a free lambda; what a new lambda can start from; whether\nthe build agent is on offer; where a lambda answers (`lambdaUrl`); and what the editor suggests while code is\nwritten - the namespaces a lambda has imported and the types and snippets it may use.", "operationId": "system", "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The terms, limits, starters and vocabulary of this installation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/PlatformResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PlatformResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/PlatformResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/PlatformResponse" } } } } } } }, "/system/features": { "get": { "tags": [ "Platform" ], "summary": "Reads which pages the site links to", "description": "What the site asks on every page. Unrelated to the features of a lambda.", "operationId": "featuresGET2", "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "Which pages are linked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeaturesResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/FeaturesResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FeaturesResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/FeaturesResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/FeaturesResponse" } } } } } } }, "/admin/lambdas": { "get": { "tags": [ "Administration" ], "summary": "Lists every lambda", "description": "Newest first, twenty to a page, with what each has been doing since the server came up, which is counted in memory.", "operationId": "lambdasGET2", "parameters": [ { "name": "search", "in": "query", "description": "Only lambdas whose public key or domain contains this", "schema": { "title": "String", "type": "string" } }, { "name": "tier", "in": "query", "description": "Only lambdas of this tier: `Free`, `Premium` or `Demo`", "schema": { "title": "String", "type": "string" } }, { "name": "page", "in": "query", "description": "The page, counting from 1", "schema": { "title": "Integer", "type": "integer", "format": "int32" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "A page of lambdas", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminListingResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/AdminListingResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/AdminListingResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/AdminListingResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/AdminListingResponse" } } } }, "400": { "description": "There is no such tier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No API key has been sent with the request" }, "403": { "description": "The API key sent with the request is not valid" } }, "security": [ { "adminToken": [] } ] } }, "/admin/lambdas/{publicKey}": { "get": { "tags": [ "Administration" ], "summary": "Reads everything about one lambda", "description": "What it is - its editor key included - what it has been doing, its versions and when it was online.", "operationId": "lambdasGET3", "parameters": [ { "name": "publicKey", "in": "path", "required": true, "description": "The public key of the lambda", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "Everything about the lambda", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminLambdaDetail" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/AdminLambdaDetail" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/AdminLambdaDetail" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/AdminLambdaDetail" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/AdminLambdaDetail" } } } }, "404": { "description": "No lambda has this public key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No API key has been sent with the request" }, "403": { "description": "The API key sent with the request is not valid" } }, "security": [ { "adminToken": [] } ] }, "delete": { "tags": [ "Administration" ], "summary": "Deletes a lambda and everything kept for it", "description": "As its owner would, for good. Demos cannot be deleted: the installation keeps them.", "operationId": "lambdasDELETE2", "parameters": [ { "name": "publicKey", "in": "path", "required": true, "description": "The public key of the lambda", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "Done. There is no body." }, "404": { "description": "No lambda has this public key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No API key has been sent with the request" }, "403": { "description": "The API key sent with the request is not valid" } }, "security": [ { "adminToken": [] } ] } }, "/admin/lambdas/{publicKey}/versions/{version}": { "get": { "tags": [ "Administration" ], "summary": "Reads a version of a lambda with its files", "operationId": "versionsGET3", "parameters": [ { "name": "publicKey", "in": "path", "required": true, "description": "The public key of the lambda", "schema": { "title": "String", "type": "string" } }, { "name": "version", "in": "path", "required": true, "description": "The number of the version, counting from 1", "schema": { "title": "Integer", "type": "integer", "format": "int32" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The version with its files", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionContentResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/VersionContentResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/VersionContentResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/VersionContentResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/VersionContentResponse" } } } }, "404": { "description": "No lambda has this public key, or it has no such version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No API key has been sent with the request" }, "403": { "description": "The API key sent with the request is not valid" } }, "security": [ { "adminToken": [] } ] } }, "/admin/lambdas/{publicKey}/tier": { "put": { "tags": [ "Administration" ], "summary": "Moves a lambda to another tier", "description": "The tier decides the limits of the lambda, whether it may answer at a domain of its own, and whether it is taken\noffline and deleted when nobody uses it. Leaving the premium tier keeps the domain configured, but stops serving it;\nwhat the lambda has beyond the free limits is kept, and only what it saves next is held to them. Nothing is moved\ninto or out of the demo tier by hand.", "operationId": "tier", "parameters": [ { "name": "publicKey", "in": "path", "required": true, "description": "The public key of the lambda", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TierRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/TierRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TierRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/TierRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/TierRequest" } } } }, "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The lambda afterwards", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminLambdaDetail" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/AdminLambdaDetail" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/AdminLambdaDetail" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/AdminLambdaDetail" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/AdminLambdaDetail" } } } }, "400": { "description": "There is no such tier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The demo tier is the installation's own. Nothing is moved into or out of it by hand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this public key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No API key has been sent with the request" } }, "security": [ { "adminToken": [] } ] } }, "/admin/lambdas/{publicKey}/domain": { "put": { "tags": [ "Administration" ], "summary": "Sets the domain of a lambda", "description": "Under the same rules as `PUT /lambdas/{privateKey}/domain`: only a premium lambda may have one. Nothing, or an empty domain, removes it.", "operationId": "domainPUT2", "parameters": [ { "name": "publicKey", "in": "path", "required": true, "description": "The public key of the lambda", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainChangeRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/DomainChangeRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DomainChangeRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/DomainChangeRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/DomainChangeRequest" } } } }, "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The lambda afterwards", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminLambdaDetail" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/AdminLambdaDetail" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/AdminLambdaDetail" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/AdminLambdaDetail" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/AdminLambdaDetail" } } } }, "400": { "description": "That is not a domain that can be used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Another lambda answers at that domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lambda has this public key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No API key has been sent with the request" }, "403": { "description": "The API key sent with the request is not valid" } }, "security": [ { "adminToken": [] } ] } }, "/admin/lambdas/{publicKey}/deployment/start": { "post": { "tags": [ "Administration" ], "summary": "Puts a version of a lambda online", "description": "The newest, unless another is named - as its owner would, but for demos as well, and recorded as the operator's.", "operationId": "start4", "parameters": [ { "name": "publicKey", "in": "path", "required": true, "description": "The public key of the lambda", "schema": { "title": "String", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentRequest" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/DeploymentRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DeploymentRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/DeploymentRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/DeploymentRequest" } } } }, "responses": { "200": { "description": "The version is online.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentOutcomeResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/DeploymentOutcomeResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DeploymentOutcomeResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/DeploymentOutcomeResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/DeploymentOutcomeResponse" } } } }, "422": { "description": "The code does not compile. `diagnostics` holds what the compiler said, with the file, line and column of each problem; nothing was put online, and whatever was online before still is.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentOutcomeResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/DeploymentOutcomeResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DeploymentOutcomeResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/DeploymentOutcomeResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/DeploymentOutcomeResponse" } } } }, "404": { "description": "No lambda has this public key, or it has no such version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No API key has been sent with the request" }, "403": { "description": "The API key sent with the request is not valid" } }, "security": [ { "adminToken": [] } ] } }, "/admin/lambdas/{publicKey}/deployment/stop": { "post": { "tags": [ "Administration" ], "summary": "Takes a lambda offline without deleting it", "description": "Its history says the operator took it down. Its owner may deploy it again.", "operationId": "stop4", "parameters": [ { "name": "publicKey", "in": "path", "required": true, "description": "The public key of the lambda", "schema": { "title": "String", "type": "string" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The lambda afterwards", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LambdaOverviewResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/LambdaOverviewResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/LambdaOverviewResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/LambdaOverviewResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/LambdaOverviewResponse" } } } }, "404": { "description": "No lambda has this public key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No API key has been sent with the request" }, "403": { "description": "The API key sent with the request is not valid" } }, "security": [ { "adminToken": [] } ] } }, "/admin/settings": { "get": { "tags": [ "Administration" ], "summary": "Reads what the operator has switched on or off", "operationId": "settingsGET", "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The settings of the installation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsModel" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/SettingsModel" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SettingsModel" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/SettingsModel" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/SettingsModel" } } } }, "401": { "description": "No API key has been sent with the request" }, "403": { "description": "The API key sent with the request is not valid" } }, "security": [ { "adminToken": [] } ] }, "put": { "tags": [ "Administration" ], "summary": "Replaces the settings", "description": "All of them. They apply to the next page anybody opens.", "operationId": "settingsPUT", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsModel" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/SettingsModel" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SettingsModel" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/SettingsModel" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/SettingsModel" } } } }, "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The settings, as they were saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsModel" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/SettingsModel" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SettingsModel" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/SettingsModel" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/SettingsModel" } } } }, "401": { "description": "No API key has been sent with the request" }, "403": { "description": "The API key sent with the request is not valid" } }, "security": [ { "adminToken": [] } ] } }, "/admin/limits": { "get": { "tags": [ "Administration" ], "summary": "Reads what a lambda may have and do, per tier", "description": "Where the operator has not saved them yet, these are the defaults - the built in ones, or what the environment variables that used to set them say.", "operationId": "limitsGET", "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The limits of the installation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LimitsModel" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/LimitsModel" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/LimitsModel" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/LimitsModel" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/LimitsModel" } } } }, "401": { "description": "No API key has been sent with the request" }, "403": { "description": "The API key sent with the request is not valid" } }, "security": [ { "adminToken": [] } ] }, "put": { "tags": [ "Administration" ], "summary": "Replaces the limits, all of them", "description": "They apply to what is checked next - a save, an upload, a deploy, a connection to a database - and take nothing away\nthat a lambda already has. Every value must be greater than zero, no tier may show more days of analytics than are\nkept (a year), and the premium tier must not allow less than the free one.", "operationId": "limitsPUT", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LimitsModel" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/LimitsModel" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/LimitsModel" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/LimitsModel" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/LimitsModel" } } } }, "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The limits, as they were saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LimitsModel" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/LimitsModel" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/LimitsModel" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/LimitsModel" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/LimitsModel" } } } }, "400": { "description": "A value is zero or less, more days of analytics than are kept, or the premium tier would allow less than the free one. Nothing was changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No API key has been sent with the request" }, "403": { "description": "The API key sent with the request is not valid" } }, "security": [ { "adminToken": [] } ] } }, "/telemetry/": { "get": { "tags": [ "Telemetry" ], "summary": "Reads the telemetry of the server", "operationId": "telemetry", "parameters": [ { "name": "minutes", "in": "query", "description": "How far back the readings reach, in minutes: 1 to 1440, as far as they are kept", "schema": { "title": "Integer", "type": "integer", "format": "int32" } }, { "name": "days", "in": "query", "description": "How far back the events reach, in days: 1 to 365", "schema": { "title": "Integer", "type": "integer", "format": "int32" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "What is running, what it did, and the readings taken while it did", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelemetryResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/TelemetryResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TelemetryResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/TelemetryResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/TelemetryResponse" } } } }, "401": { "description": "No API key has been sent with the request" }, "403": { "description": "The API key sent with the request is not valid" } }, "security": [ { "adminToken": [] } ] } }, "/telemetry/lambdas": { "get": { "tags": [ "Telemetry" ], "summary": "Reads what each lambda has been doing", "description": "Only the public key identifies a lambda here - the editor key, the code and the visitors are not part of it. A lambda nobody called is not listed.", "operationId": "lambdasGET4", "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "Every lambda that was called, and the totals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/ActivityResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ActivityResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/ActivityResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/ActivityResponse" } } } }, "401": { "description": "No API key has been sent with the request" }, "403": { "description": "The API key sent with the request is not valid" } }, "security": [ { "adminToken": [] } ] } }, "/logs/": { "get": { "tags": [ "Server log" ], "summary": "Reads the log, oldest first", "description": "To follow it, pass the `cursor` of each answer as `since` of the next. Arriving without one reads only the tail, not the whole ring.", "operationId": "logs3", "parameters": [ { "name": "since", "in": "query", "description": "The `cursor` of the previous answer: only what came after it. Left out, the last 1000 lines.", "schema": { "title": "Long", "type": "integer", "format": "int64" } }, { "name": "lambda", "in": "query", "description": "Only the lines of the lambda of this public key", "schema": { "title": "String", "type": "string" } }, { "name": "level", "in": "query", "description": "The lowest level to answer with: `trace`, `debug`, `info` (the default), `warn`, `error` or `critical`", "schema": { "title": "String", "type": "string" } }, { "name": "client", "in": "query", "description": "Only the lines about the caller of this address", "schema": { "title": "String", "type": "string" } }, { "name": "limit", "in": "query", "description": "At most this many lines; by default 1000, or 2000 with `since`", "schema": { "title": "Integer", "type": "integer", "format": "int32" } } ], "responses": { "204": { "description": "A response containing no body" }, "200": { "description": "The lines, and where to carry on from", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogResponse" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/LogResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/LogResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/LogResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/LogResponse" } } } }, "401": { "description": "No API key has been sent with the request" }, "403": { "description": "The API key sent with the request is not valid" } }, "security": [ { "adminToken": [] } ] } }, "/logs/callers": { "get": { "tags": [ "Server log" ], "summary": "Lists the callers in the log", "description": "Busiest first.", "operationId": "callers", "parameters": [ { "name": "limit", "in": "query", "description": "At most this many callers", "schema": { "title": "Integer", "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "The callers", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LogCaller" } } }, "application/yaml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LogCaller" } } }, "application/x-www-form-urlencoded": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LogCaller" } } }, "application/xml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LogCaller" } } }, "text/xml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LogCaller" } } } } }, "401": { "description": "No API key has been sent with the request" }, "403": { "description": "The API key sent with the request is not valid" } }, "security": [ { "adminToken": [] } ] } } }, "components": { "schemas": { "CreateLambdaRequest": { "type": "object", "description": "Asks for a new lambda.", "additionalProperties": false, "properties": { "publicKey": { "type": "string", "description": "The public key to claim, which names the address: 3 to 40 characters of a-z, 0-9 and dashes. Left out, a random one is chosen.", "nullable": true }, "acceptedTerms": { "type": "boolean", "description": "Whether the terms of the installation (`terms` of `GET /system`) were accepted. Nothing is created unless this is true." }, "template": { "type": "string", "description": "What the lambda starts as: the `id` of a demo, as `GET /demos` and the starters of `GET /system` list them, or `empty`. Left out, empty.", "nullable": true }, "view": { "type": "string", "description": "How its editor opens: `Full` (the default) with the code, files and versions, or `Simple` - the app, how it is doing and where to ask for a change, for somebody who is not going to read the code. Case does not matter.", "nullable": true } } }, "LambdaResponse": { "type": "object", "description": "A lambda, as whoever holds its editor key sees it.", "additionalProperties": false, "properties": { "publicKey": { "type": "string", "description": "Names its address below the hosting domain. Not a secret; its owner may change it." }, "privateKey": { "type": "string", "description": "The editor key, which authorizes every call about the lambda. Treat it like a password." }, "tier": { "type": "string", "description": "`Free`, `Premium` or `Demo`, assigned by the operator. Decides its limits, whether it is kept online while nobody uses it, and whether it may answer at a domain of its own." }, "created": { "type": "string", "description": "When it was created", "format": "date-time" }, "modified": { "type": "string", "description": "When something about it last changed: a save, a deployment, a setting", "format": "date-time" }, "activeVersion": { "type": "integer", "description": "The version that is online; absent while nothing is", "format": "int32", "nullable": true }, "latestVersion": { "type": "integer", "description": "The newest version saved, which may be ahead of the one online", "format": "int32", "nullable": true }, "publicUrl": { "type": "string", "description": "Its address below the hosting domain, named after its public key: `https://quiz.genhttp.run/`. While it answers at a domain of its own, this address sends its visitors on to the domain." }, "editorPath": { "type": "string", "description": "Where its editor is on this site: `/editor/{privateKey}`. Holds the editor key." }, "deployedAt": { "type": "string", "description": "When the version online went online; absent while nothing is", "format": "date-time", "nullable": true }, "deployedUntil": { "type": "string", "description": "When it is taken offline unless it is visited or edited before then - each visit and each edit moves this on. Absent while it is offline, and for a tier that keeps it online.", "format": "date-time", "nullable": true }, "keptUntil": { "type": "string", "description": "When it is deleted unless it is visited or edited before then. Absent for a tier that keeps it.", "format": "date-time", "nullable": true }, "domain": { "type": "string", "description": "The domain of its own it is configured to answer at, whether or not its tier lets it", "nullable": true }, "domainServed": { "type": "boolean", "description": "Whether it answers at that domain: it has one, and its tier includes it" }, "address": { "type": "string", "description": "Where to link to it: its domain while that is served, `publicUrl` otherwise" }, "view": { "type": "string", "description": "How its editor opens for somebody who has not chosen a view of their own: `Full` or `Simple`" }, "gitPath": { "type": "string", "description": "Where it is cloned with git and pushed to, on this site. The versions are the commits of `main`, the features the other branches. Holds the editor key, like the editor's path." } } }, "ErrorResponse": { "type": "object", "description": "Why a request was refused.\n\nA request refused before it reached the platform's own checks - a body that is not valid JSON, a build agent that cannot be reached - carries `status` and `message` only.", "additionalProperties": false, "properties": { "status": { "type": "integer", "description": "The status code it was answered with", "format": "int32" }, "error": { "type": "string", "description": "What kind of refusal it is: `Invalid` (400), `Forbidden` (403), `NotFound` (404), `Conflict` (409) or `TooMany` (429)" }, "message": { "type": "string", "description": "What went wrong, written for a person or an agent to act on - often with what to do instead" } } }, "UpdateLambdaRequest": { "type": "object", "description": "The changes to make to a lambda. What is left out stays as it is.", "additionalProperties": false, "properties": { "publicKey": { "type": "string", "description": "The public key to move the lambda to, under the same rules as when it is created", "nullable": true }, "view": { "type": "string", "description": "How its editor opens for somebody who has not chosen a view of their own: `Full` or `Simple`", "nullable": true } } }, "VersionResponse": { "type": "object", "description": "A version, without its files.", "additionalProperties": false, "properties": { "version": { "type": "integer", "description": "Its number, counting from 1", "format": "int32" }, "created": { "type": "string", "description": "When it was saved", "format": "date-time" }, "specification": { "type": "string", "description": "What the user wanted and why, where whoever saved it said", "nullable": true }, "change": { "type": "string", "description": "What it changed, where whoever saved it said", "nullable": true }, "origin": { "type": "string", "description": "How it was saved: `template` (what the lambda started as), `api`, `agent`, `git`, `admin` or `system`", "nullable": true } } }, "VersionContentResponse": { "type": "object", "description": "A version with its files.", "additionalProperties": false, "properties": { "version": { "type": "integer", "description": "Its number", "format": "int32" }, "created": { "type": "string", "description": "When it was saved", "format": "date-time" }, "specification": { "type": "string", "description": "What the user wanted and why, where whoever saved it said", "nullable": true }, "change": { "type": "string", "description": "What it changed, where whoever saved it said", "nullable": true }, "origin": { "type": "string", "description": "How it was saved: `template`, `api`, `agent`, `git`, `admin` or `system`", "nullable": true }, "files": { "type": "array", "description": "Its files, `lambda.cs` first - all of them, or those of the folder asked for", "items": { "$ref": "#/components/schemas/LambdaFile" } } } }, "LambdaFile": { "type": "object", "description": "One file of a lambda.\n\n`lambda.cs` and the other `.cs` files are compiled, files below `resources/` are served and read while the lambda runs, and every other file is kept with the version.", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Its path, with forward slashes: `lambda.cs`, `Store.cs`, `resources/web/index.html`, `docs/product.md`. Case sensitive, and also what the compiler's messages name." }, "code": { "type": "string", "description": "Its content: the text itself, or base64 where `encoding` says so" }, "encoding": { "type": "string", "description": "`base64` for a file that is not text - a picture, a font; left out for text. C# files are always text.", "nullable": true } } }, "SavedVersionResponse": { "type": "object", "description": "A version that was just saved.", "additionalProperties": false, "properties": { "version": { "type": "integer", "description": "Its number", "format": "int32" }, "created": { "type": "string", "description": "When it was saved", "format": "date-time" }, "specification": { "type": "string", "description": "What the user wanted and why, as it was kept", "nullable": true }, "change": { "type": "string", "description": "What it changes, as it was kept", "nullable": true }, "origin": { "type": "string", "description": "How it was saved", "nullable": true }, "deployment": { "description": "What came of putting it online, where that was asked for (`?deploy=true`); absent otherwise", "nullable": true, "$ref": "#/components/schemas/DeploymentOutcomeResponse" } } }, "DeploymentOutcomeResponse": { "type": "object", "description": "What came of an attempt to put a version online.", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Whether it compiled and is online now. Where it is not, whatever was online before still is." }, "lambda": { "description": "The lambda afterwards; absent where nothing about it could be read", "nullable": true, "$ref": "#/components/schemas/LambdaResponse" }, "diagnostics": { "type": "array", "description": "What the compiler said: the errors that kept it offline, or the warnings of a version that went online", "items": { "$ref": "#/components/schemas/CompilationDiagnostic" } } } }, "CompilationDiagnostic": { "type": "object", "description": "One thing the compiler, or the platform's checks of the code, said about it.", "additionalProperties": false, "properties": { "severity": { "type": "string", "description": "`Error`, which keeps the code from going online, or `Warning`" }, "id": { "type": "string", "description": "What kind of message it is: the C# compiler's (`CS1002`), `LAMBDA0001` for something lambdas may not do, `LAMBDA0002` for a handler the platform cannot serve, or `LAMBDA` for anything else the platform refused" }, "message": { "type": "string", "description": "What is wrong, and often what to do about it" }, "line": { "type": "integer", "description": "The line in the file, counting from 1; 0 when it is about no line", "format": "int32" }, "column": { "type": "integer", "description": "The column in the line, counting from 1; 0 when it is about no line", "format": "int32" }, "file": { "type": "string", "description": "The name of the file it is in, as the lambda names it; absent when it is about none of them", "nullable": true } } }, "VersionChangeRequest": { "type": "object", "description": "Changes to make to some files, saved as the next version or into a feature.", "additionalProperties": false, "properties": { "files": { "type": "array", "description": "Files to add, or to replace where one of that name exists", "nullable": true, "items": { "$ref": "#/components/schemas/LambdaFile" } }, "remove": { "type": "array", "description": "Names of files to remove. Each has to exist.", "nullable": true, "items": { "type": "string" } }, "edits": { "type": "array", "description": "Replacements of text within files, applied after the files were added and removed", "nullable": true, "items": { "$ref": "#/components/schemas/FileEdit" } }, "specification": { "type": "string", "description": "What the user wants from this change and why. Optional, and cut past 4000 characters.", "nullable": true }, "change": { "type": "string", "description": "What this change does, in one line for the owner. Optional, and cut past 500 characters.", "nullable": true } } }, "FileEdit": { "type": "object", "description": "A replacement of text within one file.", "additionalProperties": false, "properties": { "file": { "type": "string", "description": "The name of the file to change, which has to be text" }, "find": { "type": "string", "description": "The text to replace, exactly as it is in the file. It has to occur exactly once - include more of what surrounds it where it occurs more often." }, "replace": { "type": "string", "description": "What to put in its place; empty removes it" } } }, "VersionRequest": { "type": "object", "description": "Every file of a lambda, to be saved as its next version, and why it was written.", "additionalProperties": false, "properties": { "files": { "type": "array", "description": "Every file of the lambda, `lambda.cs` first", "nullable": true, "items": { "$ref": "#/components/schemas/LambdaFile" } }, "specification": { "type": "string", "description": "What the user wants from this version and why - their requirements, in their own words where possible. Optional, and cut past 4000 characters.", "nullable": true }, "change": { "type": "string", "description": "What this version changes, in one line for the owner. Optional, and cut past 500 characters.", "nullable": true } } }, "DeploymentResponse": { "type": "object", "description": "What is online, and for how long.", "additionalProperties": false, "properties": { "deployed": { "type": "boolean", "description": "Whether a version is online" }, "version": { "type": "integer", "description": "The version that is online; absent while none is", "format": "int32", "nullable": true }, "deployedAt": { "type": "string", "description": "When it went online", "format": "date-time", "nullable": true }, "deployedUntil": { "type": "string", "description": "When it is taken offline unless it is visited or edited before then; absent for a tier that keeps it online", "format": "date-time", "nullable": true } } }, "DeploymentRequest": { "type": "object", "description": "Which version to put online.", "additionalProperties": false, "properties": { "version": { "type": "integer", "description": "The number of the version; left out, the newest", "format": "int32", "nullable": true } } }, "ActivationResponse": { "type": "object", "description": "One stretch of time a version was online.", "additionalProperties": false, "properties": { "version": { "type": "integer", "description": "The version that was online", "format": "int32" }, "started": { "type": "string", "description": "When it went online", "format": "date-time" }, "origin": { "type": "string", "description": "Who put it online: `api`, `agent`, `git`, `admin` (the operator) or `system`", "nullable": true }, "ended": { "type": "string", "description": "When it went offline; absent while it is still online", "format": "date-time", "nullable": true }, "endedBy": { "type": "string", "description": "Why it went offline: `replaced` by another deployment, `stopped` by its owner, `expired` because nobody used it, or taken down by the operator (`admin`)", "nullable": true }, "seconds": { "type": "integer", "description": "How long it was online, or has been so far, in seconds", "format": "int64" } } }, "WorkspaceListing": { "type": "object", "description": "What a workspace holds, and how much room it has left.", "additionalProperties": false, "properties": { "files": { "type": "array", "description": "Every file, in every folder", "items": { "$ref": "#/components/schemas/WorkspaceEntry" } }, "folders": { "type": "array", "description": "Every folder, by its path - listed apart, since a folder may be empty", "items": { "type": "string" } }, "usedBytes": { "type": "integer", "description": "The room the files and folders take, counted in blocks of 4 KB as the allowance is", "format": "int64" }, "quotaBytes": { "type": "integer", "description": "The room the workspace may take: the data allowance of the lambda's tier, less what its database takes", "format": "int64" }, "enabled": { "type": "boolean", "description": "Whether the workspace is switched on; while it is off, it holds nothing and nothing can be written" } } }, "WorkspaceEntry": { "type": "object", "description": "One file of a workspace.", "additionalProperties": false, "properties": { "path": { "type": "string", "description": "Its path within the workspace, with forward slashes: `logs/today.txt`" }, "size": { "type": "integer", "description": "How many bytes it holds", "format": "int64" }, "modified": { "type": "string", "description": "When it was last written", "format": "date-time" } } }, "FileResponse": { "type": "object", "description": "A file of a workspace, base64 encoded so anything can travel in JSON.", "additionalProperties": false, "properties": { "path": { "type": "string", "description": "Its path within the workspace, with forward slashes" }, "content": { "type": "string", "description": "Its bytes, base64 encoded" }, "size": { "type": "integer", "description": "How many bytes it holds", "format": "int32" } } }, "FileRequest": { "type": "object", "description": "A file to write into a workspace.", "additionalProperties": false, "properties": { "content": { "type": "string", "description": "Its bytes, base64 encoded; empty for an empty file", "nullable": true } } }, "DataStoreResponse": { "type": "object", "description": "One kind of data of a lambda, and how full it is.", "additionalProperties": false, "properties": { "kind": { "type": "string", "description": "Which kind: `database`, the SQLite database it keeps its records in; `workspace`, the files it reads and writes; or `secrets`, the API keys and passwords it reads and nobody sees" }, "enabled": { "type": "boolean", "description": "Whether the lambda has it switched on" }, "default": { "type": "boolean", "description": "Whether a lambda has it until its owner decides otherwise: the workspace does, the others do not" }, "changed": { "type": "string", "description": "When it was last switched on or off; absent while it is as it came", "format": "date-time", "nullable": true }, "items": { "type": "integer", "description": "What it holds: tables, for the database; files, for the workspace; values, for the secrets", "format": "int32" }, "usedBytes": { "type": "integer", "description": "The room that takes, as the allowance counts it; zero for the secrets, which are counted in values", "format": "int64" }, "quotaBytes": { "type": "integer", "description": "The room it may take: for the database and the workspace, the data allowance of the tier less what the other takes; zero for the secrets", "format": "int64" }, "maxItems": { "type": "integer", "description": "How many it may hold, for a kind counted in values rather than bytes - the secrets", "format": "int32", "nullable": true } } }, "SecretListingResponse": { "type": "object", "description": "The secrets of a lambda, or of a feature's copy of them, by name.", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "description": "Whether the lambda has its secrets switched on (`PUT …/data/secrets`)" }, "secrets": { "type": "array", "description": "What is stored, by name", "items": { "$ref": "#/components/schemas/SecretResponse" } }, "used": { "type": "array", "description": "Every name the code reads with `Secret.Read(\"…\")` or `Secret.Exists(\"…\")` as a literal - in the version online and the newest one, or in the feature's files", "items": { "type": "string" } }, "missing": { "type": "array", "description": "The names the code reads that have no value, and that it does not ask about with `Secret.Exists` first: what somebody still has to enter, or the code that reads them fails", "items": { "type": "string" } }, "optional": { "type": "array", "description": "The names the code asks about with `Secret.Exists` that have no value: it does without them", "items": { "type": "string" } }, "limit": { "type": "integer", "description": "How many secrets a lambda may keep", "format": "int32" } } }, "SecretResponse": { "type": "object", "description": "A secret, as anybody but the lambda gets to see it: never its value.", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "What the code reads it by: `Secret.Read(\"STRIPE_KEY\")`" }, "created": { "type": "string", "description": "When it was first stored", "format": "date-time" }, "changed": { "type": "string", "description": "When its value was last replaced", "format": "date-time" }, "used": { "type": "boolean", "description": "Whether the code reads it by that name" } } }, "SecretRequest": { "type": "object", "description": "The value to store under a name.", "additionalProperties": false, "properties": { "value": { "type": "string", "description": "The value, up to 32 KB - sent once, and never shown again" } } }, "DatabaseResponse": { "type": "object", "description": "The database of a lambda, or a feature's copy of it.", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "description": "Whether the lambda has its database switched on (`PUT …/data/database`)" }, "usedBytes": { "type": "integer", "description": "The room it takes on disk", "format": "int64" }, "quotaBytes": { "type": "integer", "description": "How large it may grow: the data allowance of the tier less what the workspace takes", "format": "int64" }, "tables": { "type": "array", "description": "Every table and view, tables first", "items": { "$ref": "#/components/schemas/DatabaseTableResponse" } }, "used": { "type": "boolean", "description": "Whether the code connects to it with `Database.GetConnection()` - in the version online and the newest one, or in the feature's files" } } }, "DatabaseTableResponse": { "type": "object", "description": "A table or view of a database.", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Its name" }, "kind": { "type": "string", "description": "`table` or `view`" }, "rows": { "type": "integer", "description": "How many rows it holds; absent where counting took too long", "format": "int64", "nullable": true }, "columns": { "type": "array", "description": "Its columns, in the order they were declared", "items": { "$ref": "#/components/schemas/DatabaseColumnResponse" } }, "migrations": { "type": "boolean", "description": "Whether it is the history Evolve keeps of the migrations it applied, rather than records of the app" } } }, "DatabaseColumnResponse": { "type": "object", "description": "A column of a table or view.", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Its name" }, "type": { "type": "string", "description": "The type it was declared with, as written: `INTEGER`, `TEXT`, or anything else SQLite accepts" }, "notNull": { "type": "boolean", "description": "Whether it was declared `NOT NULL`" }, "primaryKey": { "type": "boolean", "description": "Whether it is the primary key, or part of it" }, "default": { "type": "string", "description": "The expression it defaults to, as written", "nullable": true } } }, "DatabaseRowsResponse": { "type": "object", "description": "A page of the rows of a table or view.", "additionalProperties": false, "properties": { "table": { "type": "string", "description": "The name of the table" }, "columns": { "type": "array", "description": "Its columns, in the order of the values of each row", "items": { "$ref": "#/components/schemas/DatabaseColumnResponse" } }, "rows": { "type": "array", "description": "Each row as its values, in the order of the columns: a number, a text or null - an integer beyond what JavaScript holds exactly as text, a text of more than 2000 characters as `{ text, length }`, and bytes as `{ blob }`, their length", "items": { "type": "array", "items": { "nullable": true } } }, "total": { "type": "integer", "description": "How many rows the table holds", "format": "int64" }, "offset": { "type": "integer", "description": "How many rows were skipped", "format": "int32" }, "limit": { "type": "integer", "description": "How many rows were asked for at most", "format": "int32" }, "order": { "type": "string", "description": "The column the rows are sorted by; absent for the order they were written in", "nullable": true }, "descending": { "type": "boolean", "description": "Whether the order is reversed: newest, or highest, first" } } }, "FeatureResponse": { "type": "object", "description": "A feature: a change being worked on beside the lambda.", "additionalProperties": false, "properties": { "key": { "type": "string", "description": "What every call about it takes, and what its preview is reached by" }, "name": { "type": "string", "description": "What it is, in a few words" }, "branch": { "type": "string", "description": "The branch it is in the lambda's git repository - given when it starts, and kept when it is renamed" }, "specification": { "type": "string", "description": "What the user wants from it and why", "nullable": true }, "change": { "type": "string", "description": "What it changes, in one line", "nullable": true }, "base": { "type": "integer", "description": "The version it is based on", "format": "int32" }, "newest": { "type": "integer", "description": "The newest version of the lambda", "format": "int32", "nullable": true }, "mergeable": { "type": "boolean", "description": "Whether it can be merged: it is based on the newest version" }, "origin": { "type": "string", "description": "How it was started: `api`, `agent` or `git`", "nullable": true }, "created": { "type": "string", "description": "When it was started", "format": "date-time" }, "modified": { "type": "string", "description": "When it was last saved or changed", "format": "date-time" }, "online": { "type": "boolean", "description": "Whether its preview is online" }, "current": { "type": "boolean", "description": "Whether its preview is online and serves what the feature holds now, rather than an earlier save" }, "previewed": { "type": "string", "description": "When its preview was last put online, while it is", "format": "date-time", "nullable": true }, "previewPath": { "type": "string", "description": "Where its preview answers on this site, whether it is online or not: `/features/{key}/`" }, "revision": { "type": "integer", "description": "How many times its files were saved, counting the ones it began with. Passed back with a save, it keeps that save from replacing one made elsewhere.", "format": "int32" } } }, "CreateFeatureRequest": { "type": "object", "description": "Starts a feature: a copy of a version's files, and of the lambda's data, to work on without touching the lambda.", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "What it is, in a few words - \"Leaderboard\", \"Dark mode\". One line, 80 characters at most.", "nullable": true }, "specification": { "type": "string", "description": "What the user wants from it and why. The version it is merged into keeps it.", "nullable": true }, "base": { "type": "integer", "description": "The number of the version to start from; left out, the newest", "format": "int32", "nullable": true } } }, "FeatureContentResponse": { "type": "object", "description": "A feature with its files.", "additionalProperties": false, "properties": { "feature": { "description": "The feature", "$ref": "#/components/schemas/FeatureResponse" }, "files": { "type": "array", "description": "Its files, `lambda.cs` first - all of them, or those of the folder asked for", "items": { "$ref": "#/components/schemas/LambdaFile" } } } }, "UpdateFeatureRequest": { "type": "object", "description": "Changes a feature. What is left out stays as it is.", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "What it is, in a few words", "nullable": true }, "specification": { "type": "string", "description": "What the user wants from it and why; empty clears it", "nullable": true }, "change": { "type": "string", "description": "What it changes, in one line - what the version it is merged into will say; empty clears it", "nullable": true }, "base": { "type": "integer", "description": "The version it is based on from now on. Move it only once the changes of that version are in the feature's files: only a feature based on the newest version can be merged, and nothing checks that the changes really are in.", "format": "int32", "nullable": true } } }, "FeatureFilesRequest": { "type": "object", "description": "Every file of a feature, replacing the ones it has.", "additionalProperties": false, "properties": { "files": { "type": "array", "description": "Every file, `lambda.cs` first", "nullable": true, "items": { "$ref": "#/components/schemas/LambdaFile" } }, "specification": { "type": "string", "description": "What the user wants from it and why; left out, the one it has is kept", "nullable": true }, "change": { "type": "string", "description": "What it changes, in one line; left out, the one it has is kept", "nullable": true }, "revision": { "type": "integer", "description": "The `revision` of the feature these files were made from. Given, the save is refused with 409 if the feature was saved again since, instead of replacing that save without a trace.", "format": "int32", "nullable": true } } }, "FeatureSavedResponse": { "type": "object", "description": "A feature that was just saved.", "additionalProperties": false, "properties": { "feature": { "description": "The feature afterwards", "$ref": "#/components/schemas/FeatureResponse" }, "preview": { "description": "What came of putting its preview online, where that was asked for (`?deploy=true`); absent otherwise", "nullable": true, "$ref": "#/components/schemas/FeaturePreviewResponse" } } }, "FeaturePreviewResponse": { "type": "object", "description": "What came of putting the preview of a feature online.", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Whether it compiled and the preview is online with it" }, "feature": { "description": "The feature afterwards", "$ref": "#/components/schemas/FeatureResponse" }, "diagnostics": { "type": "array", "description": "What the compiler said: the errors that kept it offline, or the warnings of a preview that went online", "items": { "$ref": "#/components/schemas/CompilationDiagnostic" } } } }, "OwnerLogResponse": { "type": "object", "description": "A page of a lambda's log, and where to carry on from.", "additionalProperties": false, "properties": { "lines": { "type": "array", "description": "The lines, oldest first", "items": { "$ref": "#/components/schemas/OwnerLogEntry" } }, "cursor": { "type": "integer", "description": "The newest sequence held; pass it as `since` to read what comes after", "format": "int64" }, "missed": { "type": "integer", "description": "Lines that were dropped before this reader got to them, because the ring went round or more matched than were asked for", "format": "int32" }, "capturing": { "type": "boolean", "description": "Whether what lambdas print is kept at all on this installation" } } }, "OwnerLogEntry": { "type": "object", "description": "A line of a lambda's log, as its owner sees it - never with a visitor's address.", "additionalProperties": false, "properties": { "seq": { "type": "integer", "description": "Its sequence: counts up and never repeats, so a reader asks for what came after the last one it saw", "format": "int64" }, "at": { "type": "string", "description": "When it was said", "format": "date-time" }, "level": { "type": "string", "description": "`trace`, `debug`, `info`, `warn`, `error` or `critical`" }, "source": { "type": "string", "description": "Who said it: `Requests` for a request line, `stdout` or `stderr` for what the code printed, or the part of the server that spoke" }, "text": { "type": "string", "description": "What was said" }, "detail": { "type": "string", "description": "The stack trace, where there is one", "nullable": true }, "country": { "type": "string", "description": "The two letter code of the country the caller's address is registered in, where it is known", "nullable": true }, "agent": { "type": "string", "description": "What the caller said it was - its user agent", "nullable": true }, "repeats": { "type": "integer", "description": "How many identical lines in a row this one stands for; one is itself alone", "format": "int32" }, "domain": { "type": "string", "description": "The host the request was addressed to: the lambda's subdomain of the hosting domain, or its own domain", "nullable": true } } }, "MergeFeatureRequest": { "type": "object", "description": "How to merge a feature into the lambda.", "additionalProperties": false, "properties": { "deploy": { "type": "boolean", "description": "Whether to put the version it becomes online as well", "nullable": true }, "specification": { "type": "string", "description": "What the version keeps as what the user wanted; left out, the feature's", "nullable": true }, "change": { "type": "string", "description": "What the version says it changes; left out, the feature's, or that it merges the feature", "nullable": true } } }, "FeatureMergeResponse": { "type": "object", "description": "What came of merging a feature.", "additionalProperties": false, "properties": { "merged": { "type": "boolean", "description": "Whether its files became a version, and the feature is gone" }, "version": { "description": "The version it became", "nullable": true, "$ref": "#/components/schemas/VersionResponse" }, "diagnostics": { "type": "array", "description": "Why it was not merged, where its code does not compile", "items": { "$ref": "#/components/schemas/CompilationDiagnostic" } }, "deployment": { "description": "What came of putting that version online, where that was asked for", "nullable": true, "$ref": "#/components/schemas/DeploymentOutcomeResponse" } } }, "CodeRequest": { "type": "object", "description": "The files a question about code is asked of, and where in them to look.", "additionalProperties": false, "properties": { "files": { "type": "array", "description": "The files of the lambda, `lambda.cs` first, as they would be saved", "nullable": true, "items": { "$ref": "#/components/schemas/LambdaFile" } }, "file": { "type": "string", "description": "The file a question about one file is about; left out, the first", "nullable": true }, "line": { "type": "integer", "description": "The line of the position, counting from zero", "format": "int32" }, "column": { "type": "integer", "description": "The column of the position, counting from zero", "format": "int32" } } }, "CompilationResponse": { "type": "object", "description": "Whether code compiles, and what the compiler said about it.", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Whether it compiles, and would go online if it were deployed" }, "diagnostics": { "type": "array", "description": "The errors that keep it from compiling, or the warnings of code that does", "items": { "$ref": "#/components/schemas/CompilationDiagnostic" } } } }, "SemanticsResponse": { "type": "object", "description": "What every name in a file means.", "additionalProperties": false, "properties": { "tokens": { "type": "array", "description": "The names, in the order they appear", "items": { "$ref": "#/components/schemas/SemanticToken" } } } }, "SemanticToken": { "type": "object", "description": "A name in a file, and what the compiler resolved it to.", "additionalProperties": false, "properties": { "line": { "type": "integer", "description": "The line it is on, counting from zero", "format": "int32" }, "column": { "type": "integer", "description": "The column it starts at, counting from zero", "format": "int32" }, "length": { "type": "integer", "description": "How many characters it spans", "format": "int32" }, "kind": { "type": "string", "description": "What it names: `type`, `interface`, `struct`, `enum`, `enumMember`, `method`, `property`, `parameter`, `local` or `namespace`" } } }, "CompletionsResponse": { "type": "object", "description": "Everything that could be written at a position.", "additionalProperties": false, "properties": { "completions": { "type": "array", "description": "The suggestions", "items": { "$ref": "#/components/schemas/ResolvedCompletionResponse" } } } }, "ResolvedCompletionResponse": { "type": "object", "description": "Something that could be written at a position.", "additionalProperties": false, "properties": { "label": { "type": "string", "description": "What to write" }, "kind": { "type": "string", "description": "What it is: `class`, `interface`, `struct`, `enum`, `method`, `property`, `field`, `parameter`, `variable` or `text`" }, "detail": { "type": "string", "description": "Its signature, as C# writes it" }, "documentation": { "type": "string", "description": "What its documentation says about it, where it has any", "nullable": true } } }, "DefinitionResponse": { "type": "object", "description": "Where a name was declared, or nothing where that is in none of the files.", "additionalProperties": false, "properties": { "file": { "type": "string", "description": "The file it was declared in; absent where it was not declared in any file of the request", "nullable": true }, "line": { "type": "integer", "description": "The line of the declaration, counting from zero", "format": "int32" }, "column": { "type": "integer", "description": "The column the declared name starts at, counting from zero", "format": "int32" }, "length": { "type": "integer", "description": "How many characters the declared name spans", "format": "int32" } } }, "LambdaSummaryResponse": { "type": "object", "description": "Everything worth knowing about a lambda at a glance.", "additionalProperties": false, "properties": { "lambda": { "description": "The lambda", "$ref": "#/components/schemas/LambdaResponse" }, "live": { "description": "The version that is online, if one is", "nullable": true, "$ref": "#/components/schemas/VersionResponse" }, "latest": { "description": "The newest version, which may be ahead of the one online", "nullable": true, "$ref": "#/components/schemas/VersionResponse" }, "versions": { "type": "integer", "description": "How many versions are kept", "format": "int32" }, "activation": { "description": "Since when the version online has been online; absent while none is", "nullable": true, "$ref": "#/components/schemas/ActivationResponse" }, "traffic": { "description": "How much it is used, and how well it answers", "$ref": "#/components/schemas/TrafficSummary" }, "recentProblems": { "type": "array", "description": "The last few errors and warnings of its own log, newest first - not the requests that were merely refused", "items": { "$ref": "#/components/schemas/OwnerLogEntry" } }, "storage": { "description": "What it keeps, and how much of its allowances that takes", "$ref": "#/components/schemas/StorageSummary" }, "limits": { "description": "What its tier allows it", "$ref": "#/components/schemas/SummaryLimits" }, "documentation": { "description": "What the documentation of the version the storage is about says, and which of its pages it has", "$ref": "#/components/schemas/DocumentationSummary" } } }, "TrafficSummary": { "type": "object", "description": "How much a lambda is used, and how well it answers.", "additionalProperties": false, "properties": { "hourRequests": { "type": "integer", "description": "Requests in the last hour", "format": "int64" }, "hourFailed": { "type": "integer", "description": "Of those, answered with a server error", "format": "int64" }, "dayRequests": { "type": "integer", "description": "Requests in the last day", "format": "int64" }, "dayFailed": { "type": "integer", "description": "Of those, answered with a server error", "format": "int64" }, "dayRejected": { "type": "integer", "description": "Of those, answered with a client error, not found included", "format": "int64" }, "averageMillis": { "type": "number", "description": "The mean time to answer over the last day, in milliseconds", "format": "double" }, "upgrades": { "type": "integer", "description": "Connections upgraded to a websocket in the last day", "format": "int64" }, "hourly": { "type": "array", "description": "Requests per hour over the last day, oldest first", "items": { "type": "integer", "format": "int32" } }, "lastSeen": { "type": "string", "description": "When the last request arrived", "format": "date-time", "nullable": true }, "since": { "type": "string", "description": "When the counting started: when the server came up", "format": "date-time" } } }, "StorageSummary": { "type": "object", "description": "What a lambda keeps, and how much of each allowance it takes.", "additionalProperties": false, "properties": { "version": { "type": "integer", "description": "The version the figures about code are about: the one online, else the newest", "format": "int32", "nullable": true }, "codeFiles": { "type": "integer", "description": "Files of its code: the C# it is compiled from and whatever else it is kept with, never served", "format": "int32" }, "codeBytes": { "type": "integer", "description": "What those weigh, towards what a version may come to", "format": "int64" }, "resourceFiles": { "type": "integer", "description": "Its resources, which it reads and serves while it runs", "format": "int32" }, "resourceBytes": { "type": "integer", "description": "What those weigh, decoded, towards what a version may come to", "format": "int64" }, "workspaceFiles": { "type": "integer", "description": "Files in the workspace, which it writes while it runs and every version shares", "format": "int32" }, "workspaceBytes": { "type": "integer", "description": "The room those take, towards the data allowance", "format": "int64" }, "servesResources": { "type": "boolean", "description": "Whether the code of that version serves its resources" }, "servesWorkspace": { "type": "boolean", "description": "Whether it serves the workspace, which makes those files public" }, "workspaceEnabled": { "type": "boolean", "description": "Whether the workspace is switched on" }, "usesWorkspace": { "type": "boolean", "description": "Whether the code of that version uses the workspace at all, and so fails where it does once it is switched off" }, "secretsEnabled": { "type": "boolean", "description": "Whether secrets are switched on" }, "secrets": { "type": "integer", "description": "How many secrets it keeps", "format": "int32" }, "missingSecrets": { "type": "array", "description": "The secrets its code reads that have no value yet - what its owner still has to enter, because until then the code that reads them fails", "nullable": true, "items": { "type": "string" } }, "databaseEnabled": { "type": "boolean", "description": "Whether the database is switched on" }, "databaseTables": { "type": "integer", "description": "How many tables the database holds", "format": "int32" }, "databaseBytes": { "type": "integer", "description": "The room the database takes, towards the data allowance", "format": "int64" }, "usesDatabase": { "type": "boolean", "description": "Whether the code of that version connects to the database, and so fails where it does once it is switched off" } } }, "SummaryLimits": { "type": "object", "description": "What a lambda of its tier may have on this installation, as the operator set it.", "additionalProperties": false, "properties": { "buildBytes": { "type": "integer", "description": "What a version may come to, its code and its resources together, in bytes", "format": "int64" }, "dataBytes": { "type": "integer", "description": "The room its data may take, its database and its workspace together, in bytes", "format": "int64" }, "versions": { "type": "integer", "description": "How many versions are kept; the oldest beyond that go with every save, but never the one online or one a feature is based on", "format": "int32" }, "deploymentLifetimeHours": { "type": "integer", "description": "How long a free lambda may go without a visit or an edit before it is taken offline, in hours", "format": "int32" }, "retentionDays": { "type": "integer", "description": "How long a free lambda may go without a visit or an edit before it is deleted, in days", "format": "int32" }, "features": { "type": "integer", "description": "How many features it may have open at once", "format": "int32" } } }, "DocumentationSummary": { "type": "object", "description": "What a version says about itself, in `docs/` and `tests/`.", "additionalProperties": false, "properties": { "about": { "type": "string", "description": "The first paragraph of `docs/product.md`, as plain text - what the app is, in a sentence or two", "nullable": true }, "product": { "type": "boolean", "description": "Whether it has `docs/product.md`: what the app is, for whom, and why" }, "decisions": { "type": "boolean", "description": "Whether it has `docs/decisions.md`: which technical decisions were made, and why" }, "tests": { "type": "boolean", "description": "Whether it has `tests/README.md`: how it is tested" }, "files": { "type": "integer", "description": "How many files its documentation and tests come to", "format": "int32" }, "bytes": { "type": "integer", "description": "What those weigh, which counts towards what a version may come to like the rest of its code", "format": "int64" } } }, "LambdaTraffic": { "type": "object", "description": "What one lambda has been doing since the server came up.\n\nCounted in memory, so a restart of the server starts every figure again from nothing (`since`).", "additionalProperties": false, "properties": { "totals": { "description": "Everything since the server came up; absent while nobody has called it", "nullable": true, "$ref": "#/components/schemas/LambdaActivity" }, "minutes": { "type": "array", "description": "The last hour, a minute at a time, oldest first", "items": { "$ref": "#/components/schemas/TrafficPoint" } }, "quarters": { "type": "array", "description": "The last day, a quarter of an hour at a time, oldest first", "items": { "$ref": "#/components/schemas/TrafficPoint" } }, "statuses": { "description": "How the requests were answered, by the class of their status", "$ref": "#/components/schemas/StatusClasses" }, "paths": { "type": "array", "description": "What was asked for, the busiest paths first", "items": { "$ref": "#/components/schemas/PathTraffic" } }, "entrances": { "type": "array", "description": "Where it was reached - its subdomain of the hosting domain, or its own domain - the busiest first", "items": { "$ref": "#/components/schemas/EntranceTraffic" } }, "since": { "type": "string", "description": "When the counting started, which is when the server came up", "format": "date-time" } } }, "LambdaActivity": { "type": "object", "description": "What one lambda has been doing since the server came up, in totals.", "additionalProperties": false, "properties": { "publicKey": { "type": "string", "description": "The lambda, by its public key" }, "requests": { "type": "integer", "description": "Requests it answered", "format": "int64" }, "failed": { "type": "integer", "description": "Of those, answered with a server error", "format": "int64" }, "upgrades": { "type": "integer", "description": "Connections upgraded to a websocket", "format": "int64" }, "averageMillis": { "type": "number", "description": "The mean time to answer, in milliseconds", "format": "double" }, "slowestMillis": { "type": "number", "description": "The longest time to answer, in milliseconds", "format": "double" }, "bytesOut": { "type": "integer", "description": "What the responses carried, counting only those that said how much - a floor rather than a total", "format": "int64" }, "firstSeen": { "type": "string", "description": "When the first request arrived", "format": "date-time", "nullable": true }, "lastSeen": { "type": "string", "description": "When the last request arrived", "format": "date-time", "nullable": true } } }, "TrafficPoint": { "type": "object", "description": "The traffic of one interval.", "additionalProperties": false, "properties": { "at": { "type": "string", "description": "When the interval started", "format": "date-time" }, "requests": { "type": "integer", "description": "Requests answered in it", "format": "int32" }, "failed": { "type": "integer", "description": "Of those, answered with a server error (5xx)", "format": "int32" }, "rejected": { "type": "integer", "description": "Of those, answered with a client error (4xx), not found included", "format": "int32" }, "upgrades": { "type": "integer", "description": "Connections upgraded to a websocket", "format": "int32" }, "averageMillis": { "type": "number", "description": "The mean time to answer, over its requests, in milliseconds", "format": "double" }, "bytes": { "type": "integer", "description": "What the responses carried, where they said how much", "format": "int64" } } }, "StatusClasses": { "type": "object", "description": "Requests by the class of status they were answered with.", "additionalProperties": false, "properties": { "success": { "type": "integer", "description": "2xx", "format": "int64" }, "redirect": { "type": "integer", "description": "3xx", "format": "int64" }, "clientError": { "type": "integer", "description": "4xx, not found included", "format": "int64" }, "serverError": { "type": "integer", "description": "5xx", "format": "int64" } } }, "PathTraffic": { "type": "object", "description": "One path of a lambda, and how it was answered.", "additionalProperties": false, "properties": { "path": { "type": "string", "description": "The path, relative to the lambda - the same wherever it is reached" }, "requests": { "type": "integer", "description": "How often it was asked for", "format": "int64" }, "failed": { "type": "integer", "description": "Of those, answered with a server error", "format": "int64" }, "averageMillis": { "type": "number", "description": "The mean time to answer it, in milliseconds", "format": "double" } } }, "EntranceTraffic": { "type": "object", "description": "How often a lambda was reached through one of its addresses.", "additionalProperties": false, "properties": { "domain": { "type": "string", "description": "The host it was reached at - its subdomain of the hosting domain, or its own domain", "nullable": true }, "requests": { "type": "integer", "description": "Requests and websocket upgrades alike - every time somebody came in this way", "format": "int64" } } }, "OwnShowcaseResponse": { "type": "object", "description": "The showcase entry of a lambda as its owner sees it, with what may go into one.", "additionalProperties": false, "properties": { "showcase": { "description": "The entry; absent while the lambda is not in the showcase", "nullable": true, "$ref": "#/components/schemas/ShowcaseResponse" }, "limits": { "description": "What an entry may hold", "$ref": "#/components/schemas/ShowcaseLimitsResponse" } } }, "ShowcaseResponse": { "type": "object", "description": "A lambda in the showcase, as the showcase lists it.", "additionalProperties": false, "properties": { "publicKey": { "type": "string", "description": "The public key of the lambda" }, "title": { "type": "string", "description": "What its owner calls it" }, "description": { "type": "string", "description": "What its owner says it is, and what a visitor can do with it" }, "address": { "type": "string", "description": "Where it answers - its own domain while it has one, its address below the hosting domain otherwise" }, "imagePath": { "type": "string", "description": "Where its picture is on this site; it changes with the picture, so it may be cached for good" }, "imageType": { "type": "string", "description": "The media type of the picture: `image/png`, `image/jpeg`, `image/gif` or `image/webp`" }, "imageBytes": { "type": "integer", "description": "How large the picture is, in bytes", "format": "int32" }, "online": { "type": "boolean", "description": "Whether the lambda answers right now - the listing only has those" }, "created": { "type": "string", "description": "When it was put into the showcase", "format": "date-time" }, "updated": { "type": "string", "description": "When its entry last changed", "format": "date-time" } } }, "ShowcaseLimitsResponse": { "type": "object", "description": "What a showcase entry may hold.", "additionalProperties": false, "properties": { "title": { "type": "integer", "description": "How many characters the title may have", "format": "int32" }, "description": { "type": "integer", "description": "How many characters the description may have", "format": "int32" }, "imageBytes": { "type": "integer", "description": "How large the picture may be, in bytes, as the operator set it", "format": "int32" }, "imageTypes": { "type": "array", "description": "The media types a picture may have", "items": { "type": "string" } }, "tone": { "type": "string", "description": "How an entry should read" } } }, "ShowcaseRequest": { "type": "object", "description": "What a showcase entry should say.", "additionalProperties": false, "properties": { "title": { "type": "string", "description": "What it is called, on one line", "nullable": true }, "description": { "type": "string", "description": "What it is, and what a visitor can do with it", "nullable": true }, "image": { "type": "string", "description": "The picture, base64 encoded: a PNG, JPEG, GIF or WebP image. Required for a new entry; left out, the one there is kept.", "nullable": true } } }, "OwnSourceResponse": { "type": "object", "description": "Whether a lambda's source is published, as its owner sees it, and what it can be published under.", "additionalProperties": false, "properties": { "source": { "description": "What it is published under; absent when it never was", "nullable": true, "$ref": "#/components/schemas/SourceSettingsResponse" }, "licenses": { "type": "array", "description": "The licenses on offer, the default first", "items": { "$ref": "#/components/schemas/LicenseResponse" } }, "default": { "type": "string", "description": "The license a source is published under unless another is asked for: `MIT`" }, "maxAuthor": { "type": "integer", "description": "How many characters the name in the license may have", "format": "int32" } } }, "SourceSettingsResponse": { "type": "object", "description": "What a lambda's source is published under.", "additionalProperties": false, "properties": { "published": { "type": "boolean", "description": "Whether anybody may read it right now - it may have been taken down since" }, "license": { "description": "The license", "$ref": "#/components/schemas/LicenseResponse" }, "author": { "type": "string", "description": "Who holds the copyright, where the owner named somebody", "nullable": true }, "holder": { "type": "string", "description": "Who the license names: the author, or the authors of the lambda" }, "stars": { "type": "integer", "description": "How many visitors starred it - kept while it is taken down", "format": "int32" }, "publishedAt": { "type": "string", "description": "When it was published", "format": "date-time" }, "updated": { "type": "string", "description": "When what it is published under last changed", "format": "date-time" }, "path": { "type": "string", "description": "Where it is read on this site: `/source/{publicKey}`" } } }, "LicenseResponse": { "type": "object", "description": "A license a source can be published under.", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Its SPDX identifier, which is how it is asked for: `MIT`, `Apache-2.0`, `GPL-3.0-or-later` …" }, "name": { "type": "string", "description": "Its full name" }, "kind": { "type": "string", "description": "`Permissive`, `Copyleft` or `PublicDomain` - roughly what it asks of whoever reuses the code" }, "url": { "type": "string", "description": "Where it is described in full" } } }, "SourceRequest": { "type": "object", "description": "What a lambda's source is to be published under. What is left out stays as it is.", "additionalProperties": false, "properties": { "license": { "type": "string", "description": "The SPDX identifier of one of the licenses on offer; `MIT` when a source is first published without one", "nullable": true }, "author": { "type": "string", "description": "Who holds the copyright, as the license is to name them, on one line; empty names nobody", "nullable": true } } }, "AnalyticsResponse": { "type": "object", "description": "What was counted of a lambda's visitors, as its owner is shown it.\n\nWhile counting is switched off, everything from `totals` to `crawlers` is absent.", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "description": "Whether its visits are counted" }, "since": { "type": "string", "description": "When counting was switched on", "format": "date-time", "nullable": true }, "tier": { "type": "string", "description": "`Free`, `Premium` or `Demo` - which decides how many days are shown" }, "days": { "type": "integer", "description": "How many days this answer covers, today included", "format": "int32" }, "window": { "type": "integer", "description": "The most days its tier shows", "format": "int32" }, "kept": { "type": "integer", "description": "How many days are kept of every lambda, whatever its tier shows", "format": "int32" }, "from": { "type": "string", "description": "The first day of the answer, in UTC", "format": "date" }, "to": { "type": "string", "description": "The last day of the answer: today, in UTC", "format": "date" }, "earliest": { "type": "string", "description": "The first day anything was counted on - before `from` where more is kept than shown", "format": "date", "nullable": true }, "totals": { "description": "The days of the answer, summed", "nullable": true, "$ref": "#/components/schemas/AnalyticsTotalsResponse" }, "previous": { "description": "The same number of days before, summed - only where the tier shows those as well", "nullable": true, "$ref": "#/components/schemas/AnalyticsTotalsResponse" }, "daily": { "type": "array", "description": "Each day of the answer, oldest first, days without visits included", "nullable": true, "items": { "$ref": "#/components/schemas/AnalyticsDayResponse" } }, "pages": { "type": "array", "description": "The paths that were answered, the most viewed first", "nullable": true, "items": { "$ref": "#/components/schemas/AnalyticsValueResponse" } }, "referrers": { "type": "array", "description": "The sites people came from, by host", "nullable": true, "items": { "$ref": "#/components/schemas/AnalyticsValueResponse" } }, "countries": { "type": "array", "description": "The countries their addresses are registered in, by ISO code; empty where not known", "nullable": true, "items": { "$ref": "#/components/schemas/AnalyticsValueResponse" } }, "devices": { "type": "array", "description": "`desktop`, `mobile`, `tablet`, `bot` or `other`", "nullable": true, "items": { "$ref": "#/components/schemas/AnalyticsValueResponse" } }, "browsers": { "type": "array", "description": "The browsers of people - programs are not counted here", "nullable": true, "items": { "$ref": "#/components/schemas/AnalyticsValueResponse" } }, "systems": { "type": "array", "description": "The operating systems of people", "nullable": true, "items": { "$ref": "#/components/schemas/AnalyticsValueResponse" } }, "crawlers": { "type": "array", "description": "Whose programs came: search engines, AIs, chats showing a preview. The names in `confirmedCrawlers` stand for visits confirmed by their addresses, `unconfirmed` for claims to be one of them from elsewhere, and every other value for a kind of crawler.", "nullable": true, "items": { "$ref": "#/components/schemas/AnalyticsValueResponse" } }, "updated": { "type": "string", "description": "When visits were last written down; the visits since then are not in this answer yet", "format": "date-time", "nullable": true }, "intervalSeconds": { "type": "integer", "description": "How often visits are written down, in seconds", "format": "int32" }, "confirmedCrawlers": { "type": "array", "description": "The operators whose crawlers are confirmed by the addresses they publish - Google, Bing, OpenAI, Apple, Perplexity - as far as those could be fetched", "items": { "type": "string" } } } }, "AnalyticsTotalsResponse": { "type": "object", "description": "What was counted over some days, summed.", "additionalProperties": false, "properties": { "hits": { "type": "integer", "description": "Every request answered - pages, the files they load, calls of an API", "format": "int64" }, "views": { "type": "integer", "description": "The requests that were somebody opening a page - people and programs alike", "format": "int64" }, "botViews": { "type": "integer", "description": "Of the views, those of programs rather than people: crawlers, and whatever names no browser. The pages people opened are the views less these.", "format": "int64" }, "visitors": { "type": "integer", "description": "Different people who opened a page, each counted once a day - summed over days, one who came back is counted again", "format": "int64" }, "failed": { "type": "integer", "description": "Requests answered with a server error", "format": "int64" }, "rejected": { "type": "integer", "description": "Requests answered with a client error, not found included", "format": "int64" }, "bytes": { "type": "integer", "description": "What the responses carried, where that was known, in bytes", "format": "int64" }, "averageMillis": { "type": "number", "description": "The mean time to answer a request, in milliseconds", "format": "double" } } }, "AnalyticsDayResponse": { "type": "object", "description": "What was counted on one day.", "additionalProperties": false, "properties": { "date": { "type": "string", "description": "The day, in UTC", "format": "date" }, "totals": { "description": "What was counted on it", "$ref": "#/components/schemas/AnalyticsTotalsResponse" } } }, "AnalyticsValueResponse": { "type": "object", "description": "One value visits are counted by, and how often it came up.", "additionalProperties": false, "properties": { "value": { "type": "string", "description": "The path, the host, the country code or the name; `(other)` gathers what did not fit into a day's list" }, "hits": { "type": "integer", "description": "Requests it was part of", "format": "int64" }, "views": { "type": "integer", "description": "Pages opened it was part of", "format": "int64" }, "botViews": { "type": "integer", "description": "Of those, the pages programs opened rather than people", "format": "int64" } } }, "DomainResponse": { "type": "object", "description": "The domain of a lambda, and whether it answers at it.", "additionalProperties": false, "properties": { "domain": { "type": "string", "description": "The domain it is configured to answer at; absent without one", "nullable": true }, "tier": { "type": "string", "description": "The tier of the lambda, which decides whether it may have one" }, "allowed": { "type": "boolean", "description": "Whether the tier includes a domain of its own: only the premium tier does" }, "served": { "type": "boolean", "description": "Whether requests to the domain reach the lambda right now - it has one, and its tier includes it. A domain kept from a premium tier is not served." }, "dns": { "description": "What the domain resolves to, as the server sees it; absent without a domain", "nullable": true, "$ref": "#/components/schemas/DnsResponse" } } }, "DnsResponse": { "type": "object", "description": "What a domain resolves to, looked up by the server as the request was answered.\n\nOnly the addresses - not whether they are this installation's, which is for whoever knows where it runs to compare.", "additionalProperties": false, "properties": { "addresses": { "type": "array", "description": "Every address the domain resolved to, IPv4 and IPv6 alike", "items": { "type": "string" } }, "problem": { "type": "string", "description": "Why nothing could be resolved, where nothing could: it does not resolve yet, or the name servers could not be asked", "nullable": true } } }, "DomainChangeRequest": { "type": "object", "description": "The domain a lambda is to answer at.", "additionalProperties": false, "properties": { "domain": { "type": "string", "description": "The domain, as it should answer: `shop.example.com`, or `www.example.com` to answer there. Nothing, or an empty one, removes it.", "nullable": true } } }, "AgentState": { "type": "object", "description": "Whether a change can be asked for, and the change under way or the last one.", "additionalProperties": false, "properties": { "available": { "type": "boolean", "description": "Whether changes can be asked for: there is an agent, and the operator has not switched the box off" }, "perDay": { "type": "integer", "description": "How many builds and changes one address may ask for in a day", "format": "int32" }, "left": { "type": "integer", "description": "How many of those this caller has left today", "format": "int32" }, "secondModel": { "type": "boolean", "description": "Whether a second model is on offer, behind a password" }, "job": { "description": "The change under way, or the last one, while the agent still remembers it", "nullable": true, "$ref": "#/components/schemas/ChangeProgress" } } }, "ChangeProgress": { "type": "object", "description": "A change the agent was asked for, and how it is getting on.", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "What the agent knows it by" }, "state": { "type": "string", "description": "`queued`, `running`, `done`, `failed` or `cancelled`" }, "prompt": { "type": "string", "description": "What was asked for" }, "deploy": { "type": "boolean", "description": "Whether it was asked to merge the change and put it online" }, "model": { "type": "string", "description": "Which of the offered models is making it" }, "before": { "type": "integer", "description": "The version that was online when it was asked for", "format": "int32", "nullable": true }, "steps": { "type": "array", "description": "What it has done so far", "items": { "$ref": "#/components/schemas/AgentStep" } }, "result": { "description": "How it ended, once it has", "nullable": true, "$ref": "#/components/schemas/ChangeResult" }, "waiting": { "type": "integer", "description": "Its place in the queue; zero once it runs", "format": "int32" }, "seconds": { "type": "integer", "description": "How long it has been running, in seconds", "format": "int32" }, "limit": { "type": "integer", "description": "How long it may run, in seconds; absent when there is no clock on it", "format": "int32", "nullable": true }, "feature": { "type": "string", "description": "The key of the feature it was asked to go on with; absent when it starts one of its own", "nullable": true } } }, "AgentStep": { "type": "object", "description": "One thing the agent did while building or changing a lambda.\n\nA fact rather than a sentence, so a page can say it in its own language. The only prose is what the agent itself said between steps (`say`).", "additionalProperties": false, "properties": { "at": { "type": "integer", "description": "Seconds into the run", "format": "int32" }, "kind": { "type": "string", "description": "What it did: `say`, `guide`, `demos`, `read`, `logs`, `create`, `write`, `check`, `deploy`, `upload`, `delete`, `list`, `feature` (started one), `update` (changed a feature's notes or base), `merge`, `discard` (deleted a feature), `data` (switched a kind of data on), `records` (read the database), `secrets` (listed the secrets) or `other`" }, "text": { "type": "string", "description": "What the agent said, for a step of kind `say`", "nullable": true }, "tool": { "type": "string", "description": "The tool, for a step of kind `other`", "nullable": true }, "files": { "type": "array", "description": "The files written or read", "nullable": true, "items": { "type": "string" } }, "removed": { "type": "array", "description": "The files a write removed", "nullable": true, "items": { "type": "string" } }, "whole": { "type": "boolean", "description": "Whether a write replaced every file rather than some", "nullable": true }, "path": { "type": "string", "description": "The workspace path of an upload or a removal", "nullable": true }, "done": { "type": "boolean", "description": "Whether the tool has answered", "nullable": true }, "version": { "type": "integer", "description": "The version read, saved, merged into, put online, or made a feature's base", "format": "int32", "nullable": true }, "online": { "type": "boolean", "description": "Whether a write or a deployment went online - at the preview address, for a feature", "nullable": true }, "errors": { "type": "integer", "description": "How many errors the compiler found", "format": "int32", "nullable": true }, "problems": { "type": "integer", "description": "How many errors the log holds", "format": "int32", "nullable": true }, "problem": { "type": "string", "description": "Why the platform refused the step, in its words", "nullable": true }, "feature": { "type": "string", "description": "The name of the feature the step was about", "nullable": true }, "preview": { "type": "boolean", "description": "Whether the step was about a feature rather than the lambda itself", "nullable": true }, "data": { "type": "string", "description": "The kind of data a step of kind `data` switched on: `database`, `secrets` or `workspace`", "nullable": true } } }, "ChangeResult": { "type": "object", "description": "How a change ended, from what the tools answered rather than from what the model said about them.", "additionalProperties": false, "properties": { "ok": { "type": "boolean", "description": "Whether it saved anything - into a feature, or as a version" }, "version": { "type": "integer", "description": "The newest version it saved, merging included", "format": "int32", "nullable": true }, "online": { "type": "integer", "description": "The version it put online, if it put one there", "format": "int32", "nullable": true }, "deployed": { "type": "boolean", "description": "Whether it put a version online", "nullable": true }, "compiles": { "type": "boolean", "description": "Whether the last code it compiled compiles, where it is known", "nullable": true }, "before": { "type": "integer", "description": "The version that was online when it started - to put back, if the change is not wanted", "format": "int32", "nullable": true }, "unchanged": { "type": "boolean", "description": "Whether it saved nothing", "nullable": true }, "cancelled": { "type": "boolean", "description": "Whether somebody stopped it", "nullable": true }, "reason": { "type": "string", "description": "What cut it short: `timeout`, `turns` (it used up its steps) or `unauthorised`; `declined` where the agent would not make the change at all", "nullable": true }, "summary": { "type": "string", "description": "What the agent said at the end, for the owner - or, where it declined, why", "nullable": true }, "error": { "type": "string", "description": "What went wrong, in English", "nullable": true }, "detail": { "type": "string", "description": "What went wrong, in the words of whatever it went wrong in", "nullable": true }, "feature": { "type": "string", "description": "The key of the feature the change was left in, where it was not merged", "nullable": true }, "featureName": { "type": "string", "description": "What that feature is called", "nullable": true }, "preview": { "type": "boolean", "description": "Whether that feature's preview is online, to be tried", "nullable": true }, "declined": { "type": "boolean", "description": "Whether the agent would not make the change; `summary` says why", "nullable": true } } }, "ChangeRequest": { "type": "object", "description": "What should be different about a lambda.", "additionalProperties": false, "properties": { "prompt": { "type": "string", "description": "What to change, in the words of whoever wants it, in any language - at least three characters, cut past 2000", "nullable": true }, "deploy": { "type": "boolean", "description": "Whether to merge the change and put it online once it works (the default), rather than leave it in its feature for the owner to try first" }, "model": { "type": "string", "description": "Which of the offered models makes it: left out or `opus` for the default one, `fable` for the second, where one is offered", "nullable": true }, "password": { "type": "string", "description": "The password for the second model", "nullable": true }, "language": { "type": "string", "description": "The language of whoever asks, as a code like `de` or `pt-pt`, for the agent to answer in where the prompt does not tell", "nullable": true }, "feature": { "type": "string", "description": "The key of a feature to go on with; left out, the agent starts a new one", "nullable": true } } }, "KeyResponse": { "type": "object", "description": "Everything anybody may know about a public key.", "additionalProperties": false, "properties": { "publicKey": { "type": "string", "description": "The key as it would be stored: trimmed and lower cased" }, "valid": { "type": "boolean", "description": "Whether it is spelled as a key may be: 3 to 40 characters of a-z, 0-9 and dashes, not starting or ending with a dash" }, "available": { "type": "boolean", "description": "Whether a new lambda could be created with it right now" }, "exists": { "type": "boolean", "description": "Whether a lambda has it" }, "deployed": { "type": "boolean", "description": "Whether that lambda is online" }, "reason": { "type": "string", "description": "Why it cannot be claimed, where it cannot - spelling, a reserved name, a key kept for the demos", "nullable": true } } }, "DemoResponse": { "type": "object", "description": "A demo the installation keeps online, and how to read it.", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "What it is started from: the `template` of `POST /lambdas`" }, "name": { "type": "string", "description": "What it is called" }, "description": { "type": "string", "description": "What it is" }, "shows": { "type": "string", "description": "What reading its code teaches" }, "readWhen": { "type": "string", "description": "The kinds of request it is the right starting point for" }, "publicKey": { "type": "string", "description": "Where it answers: its public key" }, "privateKey": { "type": "string", "description": "Its editor key: public, and read only - every change is refused" }, "address": { "type": "string", "description": "Where it answers, below the hosting domain" }, "files": { "type": "array", "description": "The files it is made of, the snippet first", "items": { "type": "string" } }, "live": { "type": "boolean", "description": "Whether it answers right now - the demos are prepared after the server started" } } }, "PageOfShowcaseResponse": { "type": "object", "description": "A page of a listing that is read a page at a time, with `skip` and `take`.", "additionalProperties": false, "properties": { "entries": { "type": "array", "description": "The entries of this page", "items": { "$ref": "#/components/schemas/ShowcaseResponse" } }, "total": { "type": "integer", "description": "How many entries there are altogether", "format": "int32" }, "next": { "type": "integer", "description": "The `skip` of the next page; absent when this was the last", "format": "int32", "nullable": true } } }, "PageOfSourceEntryResponse": { "type": "object", "description": "A page of a listing that is read a page at a time, with `skip` and `take`.", "additionalProperties": false, "properties": { "entries": { "type": "array", "description": "The entries of this page", "items": { "$ref": "#/components/schemas/SourceEntryResponse" } }, "total": { "type": "integer", "description": "How many entries there are altogether", "format": "int32" }, "next": { "type": "integer", "description": "The `skip` of the next page; absent when this was the last", "format": "int32", "nullable": true } } }, "SourceEntryResponse": { "type": "object", "description": "A published source, as the listing shows it.", "additionalProperties": false, "properties": { "publicKey": { "type": "string", "description": "The public key of the lambda" }, "title": { "type": "string", "description": "What its owner calls it in the showcase, where it is in the showcase", "nullable": true }, "about": { "type": "string", "description": "What its newest version says it is: the first paragraph of its `docs/product.md`", "nullable": true }, "description": { "type": "string", "description": "What its owner says about it in the showcase, where it is there", "nullable": true }, "license": { "description": "The license it is published under", "$ref": "#/components/schemas/LicenseResponse" }, "stars": { "type": "integer", "description": "How many visitors starred it", "format": "int32" }, "online": { "type": "boolean", "description": "Whether the app answers right now" }, "address": { "type": "string", "description": "Where the app answers - its own domain while it has one, its address below the hosting domain otherwise" }, "path": { "type": "string", "description": "Where its source is read on this site: `/source/{publicKey}`" }, "imagePath": { "type": "string", "description": "Its picture in the showcase, where it has one", "nullable": true }, "latestVersion": { "type": "integer", "description": "Its newest version", "format": "int32", "nullable": true }, "updated": { "type": "string", "description": "When its newest version was saved", "format": "date-time", "nullable": true }, "publishedAt": { "type": "string", "description": "When its source was published", "format": "date-time" } } }, "SourceProjectResponse": { "type": "object", "description": "A published source with its history.", "additionalProperties": false, "properties": { "source": { "description": "The source, as the listing shows it", "$ref": "#/components/schemas/SourceEntryResponse" }, "author": { "type": "string", "description": "Who holds the copyright, where the owner named somebody", "nullable": true }, "holder": { "type": "string", "description": "Who the license names as holding it: the author, or the authors of the lambda" }, "activeVersion": { "type": "integer", "description": "The version online, if one is", "format": "int32", "nullable": true }, "created": { "type": "string", "description": "When the lambda was created", "format": "date-time" }, "versions": { "type": "array", "description": "Every version kept, newest first: what each changed, never what was asked for", "items": { "$ref": "#/components/schemas/SourceVersionResponse" } }, "starTicket": { "type": "string", "description": "What starring it is sent with (`POST …/star`): good from a second after it was handed out, for a day" }, "gitPath": { "type": "string", "description": "Where it is cloned with git on this site - every version, read only" } } }, "SourceVersionResponse": { "type": "object", "description": "A version of a published source.", "additionalProperties": false, "properties": { "version": { "type": "integer", "description": "Its number", "format": "int32" }, "created": { "type": "string", "description": "When it was saved", "format": "date-time" }, "change": { "type": "string", "description": "What it changed, in a line", "nullable": true }, "origin": { "type": "string", "description": "How it was saved: `template`, `api`, `agent` or `git`", "nullable": true }, "online": { "type": "boolean", "description": "Whether it is the version online" }, "zipPath": { "type": "string", "description": "Where it is downloaded as a project" } } }, "SourceTreeResponse": { "type": "object", "description": "The files of a published version, as the project it is packed into has them.", "additionalProperties": false, "properties": { "publicKey": { "type": "string", "description": "The public key of the lambda" }, "version": { "type": "integer", "description": "The number of the version", "format": "int32" }, "root": { "type": "string", "description": "The folder the project is in, inside the zip" }, "bytes": { "type": "integer", "description": "How large the zip is, in bytes", "format": "int64" }, "files": { "type": "array", "description": "Every file, by its path below the project's folder", "items": { "$ref": "#/components/schemas/SourceFileResponse" } }, "zipPath": { "type": "string", "description": "Where the zip is downloaded" } } }, "SourceFileResponse": { "type": "object", "description": "A file of a published version.", "additionalProperties": false, "properties": { "path": { "type": "string", "description": "Its path below the project's folder" }, "size": { "type": "integer", "description": "How large it is, in bytes", "format": "int64" }, "kind": { "type": "string", "description": "What it is: `code`, `resource`, `docs`, `tests`, `platform` (what stands in for the platform) or `project` (what makes it a project)" } } }, "SourceFileContentResponse": { "type": "object", "description": "A file of a published version, with its text.", "additionalProperties": false, "properties": { "path": { "type": "string", "description": "Its path below the project's folder" }, "size": { "type": "integer", "description": "How large it is, in bytes", "format": "int64" }, "kind": { "type": "string", "description": "What it is: `code`, `resource`, `docs`, `tests`, `platform` or `project`" }, "text": { "type": "boolean", "description": "Whether it is text - which is then in `content`, unless it is longer than a megabyte" }, "content": { "type": "string", "description": "Its text, while it is text no longer than a megabyte", "nullable": true }, "rawPath": { "type": "string", "description": "Where it is fetched as it is" } } }, "StarRequest": { "type": "object", "description": "A star given, or taken back.", "additionalProperties": false, "properties": { "ticket": { "type": "string", "description": "The `starTicket` the source was read with", "nullable": true }, "starred": { "type": "boolean", "description": "`true`, or left out, to star it; `false` to take the star back", "nullable": true } } }, "StarResponse": { "type": "object", "description": "How a source is starred now.", "additionalProperties": false, "properties": { "stars": { "type": "integer", "description": "How many stars it has now", "format": "int32" }, "starred": { "type": "boolean", "description": "Whether this address stars it now" }, "counted": { "type": "boolean", "description": "Whether this request changed the count - it does not where the same was done from here before" } } }, "BuildRequest": { "type": "object", "description": "What should be built.", "additionalProperties": false, "properties": { "prompt": { "type": "string", "description": "What to build, in the words of whoever wants it, in any language - at least three characters, cut past 2000", "nullable": true }, "model": { "type": "string", "description": "Which of the offered models builds it: left out or `opus` for the default one, `fable` for the second, where one is offered", "nullable": true }, "password": { "type": "string", "description": "The password for the second model", "nullable": true } } }, "BuildStarted": { "type": "object", "description": "A build the agent has taken on.", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "What to follow it by: `GET /builds/{id}`" }, "queued": { "type": "integer", "description": "How many builds are waiting ahead of it", "format": "int32" } } }, "BuildProgress": { "type": "object", "description": "How a build is getting on.", "additionalProperties": false, "properties": { "state": { "type": "string", "description": "`queued`, `running`, `done` or `failed`" }, "steps": { "type": "array", "description": "What it has done so far, as facts a page can say in the visitor's language - the same steps the editor shows of a change", "items": { "$ref": "#/components/schemas/AgentStep" } }, "result": { "description": "How it ended, once it has", "nullable": true, "$ref": "#/components/schemas/BuildResult" }, "waiting": { "type": "integer", "description": "Its place in the queue; zero once it runs", "format": "int32" }, "seconds": { "type": "integer", "description": "How long it has been running, in seconds, counted by the agent", "format": "int32" }, "limit": { "type": "integer", "description": "How long it may run, in seconds; absent when there is no clock on it", "format": "int32", "nullable": true } } }, "BuildResult": { "type": "object", "description": "How a build ended.", "additionalProperties": false, "properties": { "ok": { "type": "boolean", "description": "Whether a lambda was made" }, "deployed": { "type": "boolean", "description": "Whether it is online", "nullable": true }, "publicKey": { "type": "string", "description": "The public key of the lambda that was made", "nullable": true }, "privateKey": { "type": "string", "description": "Its editor key - handed out here, to whoever asked for the build, and nowhere else", "nullable": true }, "url": { "type": "string", "description": "Where it answers", "nullable": true }, "editorUrl": { "type": "string", "description": "Where its editor is", "nullable": true }, "summary": { "type": "string", "description": "What the agent said it made", "nullable": true }, "keep": { "type": "string", "description": "What the person needs to be told about keeping the editor key", "nullable": true }, "error": { "type": "string", "description": "What went wrong, or - where it was declined - why, in the language of the request", "nullable": true }, "detail": { "type": "string", "description": "What went wrong, in the words of whatever it went wrong in", "nullable": true }, "declined": { "type": "boolean", "description": "Whether the agent would not build what was asked for, because it is not an application or not one this platform is for; `error` says why", "nullable": true } } }, "PlatformResponse": { "type": "object", "description": "What this installation is like.", "additionalProperties": false, "properties": { "terms": { "type": "string", "description": "The terms of service, which creating a lambda accepts (`acceptedTerms`)" }, "starters": { "type": "array", "description": "What a new lambda can start from, in the words of somebody who wants to build something", "items": { "$ref": "#/components/schemas/StarterResponse" } }, "buildBytes": { "type": "integer", "description": "What a version of a free lambda may come to, its code and its resources together, in bytes", "format": "int64" }, "deploymentLifetimeHours": { "type": "integer", "description": "How long a free lambda may go without a visit or an edit before it is taken offline, in hours", "format": "int32" }, "retentionDays": { "type": "integer", "description": "How long a free lambda may go without a visit or an edit before it is deleted, in days", "format": "int32" }, "imports": { "type": "array", "description": "The namespaces a lambda has imported without saying so", "items": { "type": "string" } }, "completions": { "type": "array", "description": "The types, attributes and snippets the editor suggests while code is written", "items": { "$ref": "#/components/schemas/CompletionItem" } }, "build": { "description": "Whether the build agent is on offer, and how often", "$ref": "#/components/schemas/BuildAvailability" }, "lambdaUrl": { "type": "string", "description": "Where a lambda answers, with `{key}` where its public key goes: `https://{key}.genhttp.run/`" } } }, "StarterResponse": { "type": "object", "description": "Something a new lambda can be started from.", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "What to pass as `template` when creating the lambda" }, "title": { "type": "string", "description": "What somebody would want to build, in their words" }, "description": { "type": "string", "description": "What they would get" }, "demo": { "type": "string", "description": "Where the demo it copies answers, to look at first; absent for the empty lambda", "nullable": true } } }, "CompletionItem": { "type": "object", "description": "A name or a snippet the editor may suggest, whatever the code around it.", "additionalProperties": false, "properties": { "label": { "type": "string", "description": "What is suggested: a type a lambda may use, an attribute, or the name of a snippet" }, "kind": { "type": "string", "description": "What it is: `class`, `struct`, `interface`, `enum`, `attribute` or `snippet`" }, "detail": { "type": "string", "description": "Where it comes from - the namespace of a type - or what a snippet does" }, "insert": { "type": "string", "description": "For a snippet, the code to insert; absent where it is the label itself", "nullable": true } } }, "BuildAvailability": { "type": "object", "description": "Whether this installation builds things, and how often it lets one caller.", "additionalProperties": false, "properties": { "available": { "type": "boolean", "description": "Whether builds can be asked for: there is an agent, and the operator has not switched building off" }, "perDay": { "type": "integer", "description": "How many builds and changes one address may ask for in a day", "format": "int32" }, "secondModel": { "type": "boolean", "description": "Whether a second model is on offer, behind a password" } } }, "FeaturesResponse": { "type": "object", "description": "Which pages the site links to.", "additionalProperties": false, "properties": { "enterprise": { "type": "boolean", "description": "Whether the header links to the enterprise page, which can be reached either way" } } }, "AdminListingResponse": { "type": "object", "description": "A page of every lambda on the installation.", "additionalProperties": false, "properties": { "lambdas": { "type": "array", "description": "The lambdas of this page", "items": { "$ref": "#/components/schemas/AdminLambda" } }, "total": { "type": "integer", "description": "How many lambdas there are", "format": "int32" }, "deployed": { "type": "integer", "description": "How many of them are online", "format": "int32" }, "matched": { "type": "integer", "description": "How many the search matched, which is what the pages count from", "format": "int32" }, "page": { "type": "integer", "description": "The page this is, counting from 1", "format": "int32" }, "pages": { "type": "integer", "description": "How many pages there are", "format": "int32" } } }, "AdminLambda": { "type": "object", "description": "A lambda as the operator sees it: what is kept about it, and what it has been doing since the server came up.", "additionalProperties": false, "properties": { "publicKey": { "type": "string", "description": "Its public key" }, "privateKey": { "type": "string", "description": "Its editor key" }, "tier": { "type": "string", "description": "`Free`, `Premium` or `Demo`" }, "created": { "type": "string", "description": "When it was created", "format": "date-time" }, "modified": { "type": "string", "description": "When something about it last changed", "format": "date-time" }, "activeVersion": { "type": "integer", "description": "The version online; absent while none is", "format": "int32", "nullable": true }, "latestVersion": { "type": "integer", "description": "Its newest version", "format": "int32", "nullable": true }, "versions": { "type": "integer", "description": "How many versions are kept", "format": "int32" }, "deployedUntil": { "type": "string", "description": "When it is taken offline unless it is used before then", "format": "date-time", "nullable": true }, "keptUntil": { "type": "string", "description": "When it is deleted unless it is used before then", "format": "date-time", "nullable": true }, "requests": { "type": "integer", "description": "Requests since the server came up", "format": "int64" }, "failed": { "type": "integer", "description": "Of those, answered with a server error", "format": "int64" }, "lastSeen": { "type": "string", "description": "When the last request arrived, since the server came up", "format": "date-time", "nullable": true }, "domain": { "type": "string", "description": "The domain of its own, if it has one", "nullable": true }, "domainServed": { "type": "boolean", "description": "Whether it answers at that domain" } } }, "AdminLambdaDetail": { "type": "object", "description": "Everything about one lambda, for the operator.", "additionalProperties": false, "properties": { "lambda": { "description": "The lambda, as its owner sees it - its editor key included", "$ref": "#/components/schemas/LambdaResponse" }, "traffic": { "description": "What it has been doing since the server came up", "$ref": "#/components/schemas/LambdaTraffic" }, "versions": { "type": "array", "description": "Its versions, newest first", "items": { "$ref": "#/components/schemas/VersionResponse" } }, "activations": { "type": "array", "description": "Every stretch of time it was online, newest first", "items": { "$ref": "#/components/schemas/ActivationResponse" } }, "tiers": { "type": "array", "description": "The tiers it may be moved to", "items": { "type": "string" } } } }, "TierRequest": { "type": "object", "description": "The tier to move a lambda to.", "additionalProperties": false, "properties": { "tier": { "type": "string", "description": "`Free` or `Premium`, in any case" } } }, "LambdaOverviewResponse": { "type": "object", "description": "What is left of a lambda after the operator acted on it.", "additionalProperties": false, "properties": { "publicKey": { "type": "string", "description": "Its public key" }, "activeVersion": { "type": "integer", "description": "The version online; absent while none is", "format": "int32", "nullable": true }, "deployedUntil": { "type": "string", "description": "When it is taken offline unless it is used before then", "format": "date-time", "nullable": true } } }, "SettingsModel": { "type": "object", "description": "What the operator can switch on or off for the whole installation.", "additionalProperties": false, "properties": { "enterprisePage": { "type": "boolean", "description": "Whether the header of the site links to the enterprise page" }, "buildBox": { "type": "boolean", "description": "Whether `/build` offers its text box, where there is an agent" }, "changeBox": { "type": "boolean", "description": "Whether the Change section of the editor offers its text box, where there is an agent" } } }, "LimitsModel": { "type": "object", "description": "What a lambda may have and do, as the operator set it.", "additionalProperties": false, "properties": { "free": { "description": "What a free lambda, or a demo, may have", "$ref": "#/components/schemas/TierLimitsModel" }, "premium": { "description": "What a premium lambda may have; never less than a free one", "$ref": "#/components/schemas/TierLimitsModel" }, "offlineAfterHours": { "type": "integer", "description": "How long a free lambda may go without a visit or an edit before it is taken offline, in hours", "format": "int32" }, "removedAfterHours": { "type": "integer", "description": "How long a free lambda may go without a visit or an edit before it is deleted, in hours", "format": "int32" }, "showcaseImageBytes": { "type": "integer", "description": "How large the picture of a showcase entry may be, in bytes", "format": "int32" }, "requestsPerSecond": { "type": "integer", "description": "How many requests one client may send to the lambdas in a second", "format": "int32" }, "buildsPerDay": { "type": "integer", "description": "How many builds and changes one address may ask the build agent for in a day", "format": "int32" } } }, "TierLimitsModel": { "type": "object", "description": "What a lambda of one tier may have.", "additionalProperties": false, "properties": { "buildBytes": { "type": "integer", "description": "What a version may come to, its code and its resources together, in bytes", "format": "int64" }, "dataBytes": { "type": "integer", "description": "The room its data may take, its database and its workspace together, in bytes", "format": "int64" }, "versions": { "type": "integer", "description": "How many of its versions are kept", "format": "int32" }, "features": { "type": "integer", "description": "How many features it may have open at once", "format": "int32" }, "analyticsDays": { "type": "integer", "description": "How many days of its analytics its owner is shown, of the year that is kept", "format": "int32" } } }, "TelemetryResponse": { "type": "object", "description": "The state of the server, and the readings taken while it ran.", "additionalProperties": false, "properties": { "server": { "description": "What is running, and on what", "$ref": "#/components/schemas/ServerDescription" }, "traffic": { "description": "What it answered since it came up", "$ref": "#/components/schemas/TrafficDescription" }, "platform": { "description": "What the platform holds", "$ref": "#/components/schemas/PlatformDescription" }, "latest": { "description": "The newest reading", "$ref": "#/components/schemas/TelemetrySample" }, "intervalSeconds": { "type": "integer", "description": "How often a reading is taken, in seconds", "format": "int32" }, "samples": { "type": "array", "description": "The readings of the window asked for, oldest first", "items": { "$ref": "#/components/schemas/TelemetrySample" } }, "events": { "description": "What happened on the platform per day", "$ref": "#/components/schemas/EventHistory" } } }, "ServerDescription": { "type": "object", "description": "What is running, and on what.", "additionalProperties": false, "properties": { "engine": { "type": "string", "description": "The engine serving the requests: `ioxide` or `kestrel`" }, "version": { "type": "string", "description": "The version of GenHTTP" }, "runtime": { "type": "string", "description": "The .NET runtime" }, "platform": { "type": "string", "description": "The platform the runtime runs on: `linux-x64`, say" }, "serverGarbageCollection": { "type": "boolean", "description": "Whether the server garbage collector is used" }, "processors": { "type": "integer", "description": "How many processors the process may use", "format": "int32" }, "started": { "type": "string", "description": "When the server came up", "format": "date-time" }, "uptimeSeconds": { "type": "integer", "description": "How long it has been up, in seconds", "format": "int64" } } }, "TrafficDescription": { "type": "object", "description": "What the server has answered since it came up.", "additionalProperties": false, "properties": { "requests": { "type": "integer", "description": "Requests answered", "format": "int64" }, "failed": { "type": "integer", "description": "Of those, answered with a server error", "format": "int64" }, "upgrades": { "type": "integer", "description": "Websocket upgrades", "format": "int64" }, "openSockets": { "type": "integer", "description": "Connections open right now", "format": "int32" } } }, "PlatformDescription": { "type": "object", "description": "What the platform holds.", "additionalProperties": false, "properties": { "lambdas": { "type": "integer", "description": "Lambdas there are", "format": "int32" }, "deployed": { "type": "integer", "description": "Of those, online", "format": "int32" }, "versions": { "type": "integer", "description": "Versions kept, of all lambdas", "format": "int32" } } }, "TelemetrySample": { "type": "object", "description": "One reading of the server process.\n\nThe breakdown of the resident memory and the descriptors are read from `/proc` on Linux, and are zero elsewhere.", "additionalProperties": false, "properties": { "taken": { "type": "string", "description": "When it was taken", "format": "date-time" }, "managedBytes": { "type": "integer", "description": "What the managed heap holds", "format": "int64" }, "heapCommittedBytes": { "type": "integer", "description": "What the managed heap has committed", "format": "int64" }, "heapFragmentedBytes": { "type": "integer", "description": "Of that, what lies free between objects", "format": "int64" }, "workingSetBytes": { "type": "integer", "description": "The working set of the process", "format": "int64" }, "privateBytes": { "type": "integer", "description": "The private memory of the process", "format": "int64" }, "residentBytes": { "type": "integer", "description": "Everything the process has in physical memory", "format": "int64" }, "anonymousBytes": { "type": "integer", "description": "Of that, anonymous memory: heaps and stacks", "format": "int64" }, "jitBytes": { "type": "integer", "description": "Of that, code the JIT compiled", "format": "int64" }, "assemblyBytes": { "type": "integer", "description": "Of that, assemblies mapped from disk", "format": "int64" }, "otherFileBytes": { "type": "integer", "description": "Of that, other files mapped from disk", "format": "int64" }, "swapBytes": { "type": "integer", "description": "What was swapped out", "format": "int64" }, "gen0Collections": { "type": "integer", "description": "Generation 0 collections since the start", "format": "int32" }, "gen1Collections": { "type": "integer", "description": "Generation 1 collections since the start", "format": "int32" }, "gen2Collections": { "type": "integer", "description": "Generation 2 collections since the start", "format": "int32" }, "allocatedBytes": { "type": "integer", "description": "Everything allocated since the start", "format": "int64" }, "pausePercentage": { "type": "number", "description": "The share of time spent paused for collections, in percent", "format": "double" }, "cpuPercentage": { "type": "number", "description": "The share of every core the process used since the previous reading, in percent", "format": "double" }, "threads": { "type": "integer", "description": "Threads of the process", "format": "int32" }, "requests": { "type": "integer", "description": "Requests answered since the previous reading", "format": "int64" }, "failed": { "type": "integer", "description": "Of those, answered with a server error", "format": "int64" }, "upgrades": { "type": "integer", "description": "Websocket upgrades since the previous reading", "format": "int64" }, "inFlight": { "type": "integer", "description": "Requests being answered as it was taken", "format": "int32" }, "openSockets": { "type": "integer", "description": "Open connections as it was taken", "format": "int32" }, "averageMillis": { "type": "number", "description": "The mean time to answer since the previous reading, in milliseconds", "format": "double" }, "openConnections": { "type": "integer", "description": "Connections established as it was taken", "format": "int32" }, "acceptedConnections": { "type": "integer", "description": "Connections accepted since the start", "format": "int64" }, "connections": { "type": "integer", "description": "Connections accepted since the previous reading", "format": "int64" }, "fileDescriptors": { "type": "integer", "description": "File descriptors the process holds", "format": "int32" }, "socketDescriptors": { "type": "integer", "description": "Of those, sockets", "format": "int32" }, "ringDescriptors": { "type": "integer", "description": "Of those, io_uring rings", "format": "int32" } } }, "EventHistory": { "type": "object", "description": "What happened on the platform per day, one series per kind of event.", "additionalProperties": false, "properties": { "days": { "type": "array", "description": "The days covered, as `yyyy-MM-dd` in UTC, oldest first", "items": { "type": "string" } }, "series": { "type": "array", "description": "One series per kind of event, its counts in the order of `days`", "items": { "$ref": "#/components/schemas/EventSeries" } } } }, "EventSeries": { "type": "object", "description": "How often one kind of event happened, day by day.", "additionalProperties": false, "properties": { "kind": { "type": "string", "description": "`created`, `saved`, `deployed`, `undeployed` or `deleted` - of lambdas" }, "counts": { "type": "array", "description": "How many happened on each day of the window", "items": { "type": "integer", "format": "int32" } }, "total": { "type": "integer", "description": "How many have ever happened, beyond the window too", "format": "int32" } } }, "ActivityResponse": { "type": "object", "description": "What every lambda has been doing since the server came up.", "additionalProperties": false, "properties": { "lambdas": { "type": "array", "description": "Every lambda that was called", "items": { "$ref": "#/components/schemas/LambdaActivity" } }, "requests": { "type": "integer", "description": "Their requests, together", "format": "int64" }, "upgrades": { "type": "integer", "description": "Their websocket upgrades, together", "format": "int64" } } }, "LogResponse": { "type": "object", "description": "A page of the server's log, and where to carry on from.", "additionalProperties": false, "properties": { "lines": { "type": "array", "description": "The lines, oldest first", "items": { "$ref": "#/components/schemas/LogEntry" } }, "cursor": { "type": "integer", "description": "The newest sequence held; pass it as `since` to read what comes after", "format": "int64" }, "missed": { "type": "integer", "description": "Lines that were dropped before the reader got to them, because the ring went round or more matched than were asked for", "format": "int32" }, "capacity": { "type": "integer", "description": "How many lines the ring holds in all", "format": "int32" }, "written": { "type": "integer", "description": "How many lines were written since the server came up", "format": "int64" }, "capturing": { "type": "boolean", "description": "Whether what lambdas print is kept" }, "addresses": { "type": "boolean", "description": "Whether the address a request came from is recorded" }, "previous": { "description": "How the run before this one ended, where it did not end cleanly; absent on a first start and after a clean stop", "nullable": true, "$ref": "#/components/schemas/PreviousRun" } } }, "LogEntry": { "type": "object", "description": "A line of the server's log, as the operator sees it.", "additionalProperties": false, "properties": { "seq": { "type": "integer", "description": "Its sequence: counts up and never repeats, so a reader asks for what came after the last one it saw", "format": "int64" }, "at": { "type": "string", "description": "When it was said", "format": "date-time" }, "level": { "type": "string", "description": "`trace`, `debug`, `info`, `warn`, `error` or `critical`" }, "source": { "type": "string", "description": "Who said it: `Requests` for a request line, `stdout` or `stderr` for what a lambda printed, or the part of the server that spoke" }, "lambda": { "type": "string", "description": "The public key of the lambda it belongs to; absent for the platform itself", "nullable": true }, "text": { "type": "string", "description": "What was said" }, "detail": { "type": "string", "description": "The stack trace, where there is one", "nullable": true }, "client": { "type": "string", "description": "The address of the caller, where addresses are recorded - with the address a proxy claimed for it, where one did", "nullable": true }, "agent": { "type": "string", "description": "What the caller said it was - its user agent", "nullable": true }, "country": { "type": "string", "description": "The two letter code of the country the caller's address is registered in, where it is known", "nullable": true }, "place": { "type": "string", "description": "The place the caller's address is registered at, where places are looked up", "nullable": true }, "repeats": { "type": "integer", "description": "How many identical lines in a row this one stands for", "format": "int32" }, "domain": { "type": "string", "description": "The lambda's own host the request was addressed to; absent for the platform", "nullable": true } } }, "PreviousRun": { "type": "object", "description": "The end of the run of the server before this one, where it was not a clean one.", "additionalProperties": false, "properties": { "started": { "type": "string", "description": "When it started", "format": "date-time" }, "lastSeen": { "type": "string", "description": "When it was last seen alive", "format": "date-time" }, "minutes": { "type": "number", "description": "How long it ran, in minutes", "format": "double" }, "signalled": { "type": "boolean", "description": "Whether anything asked it to stop. Nothing having asked points at the machine rather than at an operator or a deployment." }, "fault": { "type": "string", "description": "The exception that ended it, where one did", "nullable": true }, "workingSet": { "type": "integer", "description": "Its working set when it was last seen, in bytes", "format": "int64" }, "requests": { "type": "integer", "description": "How many requests it had answered", "format": "int64" }, "sockets": { "type": "integer", "description": "How many connections were open when it was last seen", "format": "int32" } } }, "LogCaller": { "type": "object", "description": "A caller the log still holds something about.", "additionalProperties": false, "properties": { "client": { "type": "string", "description": "Its address" }, "place": { "type": "string", "description": "The place its address is registered at, where known", "nullable": true }, "country": { "type": "string", "description": "The two letter code of the country its address is registered in, where known", "nullable": true }, "agent": { "type": "string", "description": "What it said it was, last", "nullable": true }, "lines": { "type": "integer", "description": "How many lines of the log are about it", "format": "int64" }, "failed": { "type": "integer", "description": "How many of its requests were answered with an error", "format": "int64" }, "first": { "type": "string", "description": "When it was first seen in what the log holds", "format": "date-time" }, "last": { "type": "string", "description": "When it was last seen", "format": "date-time" } } } }, "securitySchemes": { "adminToken": { "type": "apiKey", "description": "The administration token of the installation (`LAMBDA_ADMIN_TOKEN`).", "name": "X-Admin-Token", "in": "header" } } }, "tags": [ { "name": "Platform", "description": "What this installation is like: its terms, its limits, what a lambda can start from, and where lambdas answer.\n\nPublic. Read it first: the limits and the address of lambdas differ between installations, and may change." }, { "name": "Keys", "description": "Public keys, and what anybody may know about one: whether it is free, and whether something answers there.\n\nPublic. A key names the address of a lambda, so what can be learned here is what anybody could learn by visiting it." }, { "name": "Demos", "description": "Finished lambdas the installation keeps online, to be read and started from.\n\nEach demo shows how something is done the GenHTTP way - a REST API with a database, sign-up and log-in, a multiplayer\ngame over websockets, uploads, live updates - with its documentation and tests. Its editor key is public, so it is\nread with the same calls as any lambda (`GET /lambdas/{privateKey}/versions/1`, its logs, its database), and every\nchange is refused with `403`. A lambda of your own starts as a copy of one with `POST /lambdas` and its `id` as\n`template`." }, { "name": "Lambdas", "description": "The lambdas themselves: created, read, moved to another key, exported and deleted.\n\nA lambda is addressed by its **editor key** (`privateKey`), which is also what authorizes every call below\n`/lambdas/{privateKey}`. Its versions, deployment, data and everything else about it are below the same path.\n\nWhere a lambda answers: `publicUrl` is its address below the hosting domain, named after its public key.\n`address` is where to link to it - its own domain while it answers at one (premium only), `publicUrl` otherwise." }, { "name": "Versions", "description": "The saved versions of a lambda: its program, which never changes once it is saved.\n\nA version is the program: its code and its resources, and what is written about it (`docs/`, `tests/`). It is\nnumbered from 1 and never changes; a change to the lambda is a new version. Saving one does not put it online -\npass `?deploy=true`, or deploy it afterwards. Data (database, workspace, secrets) is not part of a version.\n\nEvery save may say what the user wanted (`specification`) and what it changes (`change`), which the history shows.\nOnly so many versions are kept, as the tier of the lambda allows; with every save the oldest beyond that go, but\nnever the version online or one a feature is based on.\n\nA lambda that exists is best changed in a feature (see *Features*) rather than by saving versions directly: the\nfeature can be tried at its own address first." }, { "name": "Deployment", "description": "Whether a lambda is online, putting a version online, and taking it offline.\n\nAt most one version of a lambda is online at a time, and it serves every request to the lambda's address.\nDeploying compiles the version and switches over to it once it compiles; until then, and if it does not, whatever\nwas online stays online. Deploying an older version is how a lambda is rolled back. Neither deploying nor rolling\nback touches the data.\n\nA free lambda that nobody visits or edits for a while is taken offline by the platform (`deployedUntil` says when),\nand can be deployed again at any time." }, { "name": "Features", "description": "Changes worked on beside a lambda, tried at an address of their own, and merged into it once they work.\n\nA feature starts as a copy of a version - the newest, unless another is named - and of the lambda's data: its\ndatabase, workspace and secrets as they are at that moment. It is saved in place as often as needed; unlike a\nversion, it keeps no history of its saves. Its **preview** answers at `previewPath` on this site, against its own\ncopy of the data, while the lambda goes on serving its visitors as before.\n\n**Merging** makes the feature's files the next version of the lambda and deletes the feature, its preview and its\ncopy of the data. What the preview wrote into its copy - records, files - is not carried over: the lambda's own data\nis never touched by a feature.\n\nOnly a feature based on the newest version can be merged, so a merge cannot undo a version saved after the feature\nstarted. Where one was, its changes are brought into the feature's files first, then the feature's `base` is moved\nto it (`PATCH`), and then it merges. The platform does not merge files itself.\n\nA free lambda's preview goes offline, like the lambda, when nobody changes the feature for a while." }, { "name": "Code analysis", "description": "Questions for the compiler about code that has not been saved: does it compile, and what does a name mean.\n\nEach takes the files with it, as a save would, and stores nothing. They are behind the editor key of a lambda because\nthey run the compiler, against the references and the rules a lambda is compiled with - so code that passes the\ncheck compiles when it is deployed. Positions count lines and columns from zero." }, { "name": "Data", "description": "What a lambda keeps: which kinds of data it has, and switching them on and off.\n\nA version is the program and is replaced by the next one. Data is what the program keeps, shared by every version\nand left alone by deploying, rolling back and merging. There are three kinds:\n\n- `database`: a SQLite database, which the code reaches with `Database.GetConnection()`. Off until it is switched\n on. Its tables are under `…/database`.\n- `workspace`: files the code reads and writes. On unless its owner switched it off. They are under `…/files`.\n- `secrets`: API keys and passwords the code reads with `Secret.Read(\"NAME\")`, which nobody else can read. Off\n until they are switched on. Their names are under `…/secrets`.\n\nA kind is switched on before the lambda can use it, and the lambda can use it from its next request on, without\nbeing deployed again. **Switching a kind off deletes everything it held**, the copies of the lambda's features\nincluded, and cannot be undone. Code that uses a kind while it is off fails with an exception that says so.\n\nThe database and the workspace share one allowance, the data allowance of the lambda's tier." }, { "name": "Database", "description": "The database of a lambda, read as its owner reads it: its tables, and the records in them.\n\nEvery lambda may have a SQLite database, which its code reaches with `Database.GetConnection()`. Its schema is made\nby migrations the lambda ships in `resources/migrations/`, applied as it starts; its records are written by the\nlambda. This API only reads it - there is no way to change a record from outside the lambda.\n\nIt is data: every version reads the same database, deploying and rolling back leave it alone, and a feature works on\na copy of it, read below `…/features/{feature}/database`. It is off until it is switched on\n(`PUT /lambdas/{privateKey}/data/database`), which makes it empty. Switching it off deletes it." }, { "name": "Workspace", "description": "The files a lambda keeps: its workspace, which its code reads and writes while it runs.\n\nThe workspace is data, not part of a version: every version reads and writes the same files, and deploying or rolling\nback leaves them alone. It is where uploads, generated files and large files that are no part of the program - a\nmodel, a dataset, media - go. It is switched on unless its owner switched it off (`DELETE …/data/workspace`, which\ndeletes every file); while it is off, nothing can be written.\n\nA file is addressed by its path within the workspace, sent as **one** segment with its slashes encoded:\n`GET /lambdas/{privateKey}/files/logs%2Ftoday.txt`. Files are written as they are with `PUT …/content`, of any size, or\nbase64 encoded in JSON. Either way, the room it takes counts towards the data allowance of the lambda - workspace and\ndatabase together - in blocks of 4 KB, a folder taking one block.\n\nA feature has a copy of the workspace, reached the same way below `/lambdas/{privateKey}/features/{feature}/`." }, { "name": "Secrets", "description": "The secrets of a lambda - API keys, passwords, tokens - which its code reads and nobody else does.\n\nThe code reads a secret with `Secret.Read(\"NAME\")`, or asks whether it is there with `Secret.Exists(\"NAME\")`. A value\nis **written and never read back**: no operation of this API answers with one, and neither does the editor. What can\nbe seen is the name, when it was set, whether the code reads it - and which names the code reads that have no value\nyet (`missing`), which is what somebody still has to enter.\n\nSecrets are data: every version reads the same, deploying and rolling back leave them alone, and a feature works on a\ncopy of them. They are off until they are switched on (`PUT /lambdas/{privateKey}/data/secrets`), and switching them\noff deletes them. A lambda may keep 100.\n\nThe values are kept encrypted at rest, and a lambda reads a changed value from its next `Secret.Read` on.\nAn exported project reads them from environment variables of the same names." }, { "name": "Monitoring", "description": "How a lambda is doing: the whole of it at a glance, its traffic, and its log.\n\n`GET …/summary` answers the question *is this all right?* in one call: whether it is online, how it is used,\nwhether it is failing, what it keeps, and how much of its allowances that takes - what an agent asks after deploying\nto see whether it works.\n\nTraffic and logs are kept in memory: a restart of the server starts the counting again, and the log is a ring shared\nwith every other lambda, so a busy neighbour shortens how far back it reaches. They are for watching, not keeping;\nwhat is counted of visitors over time is under *Analytics*. Neither ever holds a visitor's address." }, { "name": "Analytics", "description": "Who visits a lambda, counted by day: visitors, page views and requests, and where they came from.\n\nCounting is the owner's choice and never starts on its own. Once switched on, the visits of a lambda are counted by\nday in UTC: visitors, page views and requests, and the pages, referring sites, countries, devices, browsers, systems\nand crawlers behind them. They are written down every few minutes, so the last minutes are not in an answer yet.\nA year is kept of every lambda; the tier decides how much of it is shown - a free lambda the last seven days, a\npremium one all of it, as the operator set it.\n\nA **visitor** is a person who opened a page, counted once a day. A **page view** is a page opened, by people or by\nprograms - `botViews` are the programs'. Requests count everything. Crawlers are told from people by a maintained\nlist, and the big operators' (Google, Bing, OpenAI, Apple, Perplexity) are confirmed by the addresses they publish.\n\nNothing that names a visitor is kept: counts only, the referrer as its host, and visitors told apart for a day by a\nhash that is never written down. No cookie, and nothing added to the lambda. The previews of features and the demos\nare not counted." }, { "name": "Domain", "description": "A domain of a lambda's own, which it answers at instead of its subdomain of the hosting domain.\n\nPart of the premium tier, which only the operator assigns. While a lambda answers at its domain, its subdomain of the\nhosting domain sends its visitors on to the domain with a permanent redirect, and `address` names the domain.\n\nThe domain is entered as it should answer. `www.` in front of a domain is sent on to the domain itself, unless the\ndomain was entered with `www.` - then that is where it answers, and the name without is not sent there. The domain has\nto point to this installation (in the DNS) and needs a certificate, which the operator of the installation takes\ncare of; the answer says what the domain resolves to, as the server sees it, to check the first." }, { "name": "Showcase", "description": "The showcase: lambdas their owners chose to show, for anybody to browse - and putting one there.\n\nShowcasing is the owner's choice and never happens on its own. An entry has a title, a description and a picture,\nand is listed (`GET /showcases`) only while its lambda is online. The listing is public and names lambdas by their\npublic key and address only - never an editor key." }, { "name": "Open source", "description": "Publishing the code of a lambda, for anybody to read, clone, download and star.\n\nPublishing is the owner's choice and never happens on its own. What is published is the program: every version kept,\nas the export packs it - its code, resources, documentation and tests - with a `LICENSE`. **Never the data**: no\ndatabase, workspace or secret, and nothing only the owner may know - not the specification of a version, the editor\nkey, traffic, logs or visitors. A version is described by its change line only.\n\nA published source is read at `/source/{publicKey}` on this site, through `GET /sources/…`, and cloned with git from\n`/source/{publicKey}.git`, read only. A source that is not published is not found, like a key nobody has." }, { "name": "Builds", "description": "The build agent of the installation: a sentence in, a new lambda out - for anybody, without a key.\n\nWhat `/build` on this site does. Somebody says what they would like; the agent of the installation creates a lambda\nfor it, writes it, and puts it online, and the build's result names the address and the editor key. It only builds\napplications: a request that is not one, or is about the platform rather than an app on it, or is meant to do harm,\nis declined with a sentence saying why.\n\nWhether this installation builds anything at all is in `GET /system` (`build`), with how many builds one address\nmay ask for a day. Each build is counted against that allowance, which starts again at midnight UTC and is shared\nwith the changes asked for in the editor. An agent may also be reached directly through MCP at `/mcp`.\n\nErrors here carry `status` and `message` only." }, { "name": "Changes", "description": "The build agent of the installation, changing a lambda for whoever holds its editor key.\n\nWhat the Change section of the editor does: the owner says what should be different, and the agent changes the lambda\nin a feature - a new one, or one named - and tries it at its preview. With `deploy` (the default) it merges the feature\nand puts the new version online once it works; without, it leaves the feature for the owner to try and merge. What is\nonline stays online until then.\n\nOne change of a lambda runs at a time. Changes count against the same daily allowance as builds, per address, which\nstarts again at midnight UTC. Demos cannot be changed. Errors that come from the agent carry `status` and `message`\nonly." }, { "name": "Administration", "description": "Every lambda on the installation, its settings and its limits - for whoever runs it.\n\nLambdas are addressed by their **public** key here, and every action is the one the owner would take, recorded as the\noperator's. The answers carry editor keys. The settings and the limits apply to the whole installation, from the next\nrequest on." }, { "name": "Telemetry", "description": "What the server process looks like from the inside, so a long run can be watched rather than guessed at.\n\nReadings of memory, the collector, the threads and the connections, taken on an interval and kept in memory, and what\nhappened on the platform per day. Only the public key identifies a lambda here." }, { "name": "Server log", "description": "What the server and the lambdas on it have been saying.\n\nOne ring of lines, held in memory and shared by everything on the installation: the requests, what lambdas printed,\nand what the server said. Behind the token, since it holds whatever a stranger's code decided to print - and, where\nthe operator records them, the addresses of callers." } ], "x-tagGroups": [ { "name": "Getting started", "tags": [ "Platform", "Keys", "Demos", "Lambdas" ] }, { "name": "The program", "tags": [ "Versions", "Deployment", "Features", "Code analysis" ] }, { "name": "What it keeps", "tags": [ "Data", "Database", "Workspace", "Secrets" ] }, { "name": "How it is doing", "tags": [ "Monitoring", "Analytics" ] }, { "name": "Sharing it", "tags": [ "Domain", "Showcase", "Open source" ] }, { "name": "The build agent", "tags": [ "Builds", "Changes" ] }, { "name": "Operating the installation", "tags": [ "Administration", "Telemetry", "Server log" ] } ] }