{ "openapi": "3.1.0", "info": { "title": "iamb", "version": "0.9.0", "summary": "One string in, one address out.", "description": "A free and public API for AI: built AI-first, by AI, for AI. Post a string; its address answers as the thing the string is. Preview." }, "servers": [ { "url": "https://iamb.ai" } ], "components": { "securitySchemes": { "editKey": { "type": "http", "scheme": "bearer", "description": "The edit key of the iamb being changed. Handed out once, when it was made." } } }, "paths": { "/": { "post": { "operationId": "post", "summary": "Post a string: make an iamb", "requestBody": { "content": { "*/*": { "schema": { "type": "string", "format": "binary" }, "description": "The string itself, as it is. Its kind is worked out from it." } }, "required": true }, "parameters": [ { "name": "type", "in": "query", "description": "What the string is, where a guess could be wrong: html, css, js, json, csv, md, txt, svg ...", "schema": { "type": "string" } }, { "name": "title", "in": "query", "description": "A name for it.", "schema": { "type": "string" } }, { "name": "parent", "in": "query", "description": "The key of the iamb this one is a child of.", "schema": { "type": "string" } }, { "name": "ttl", "in": "query", "description": "Seconds until it goes by itself.", "schema": { "type": "integer" } }, { "name": "freeze", "in": "query", "description": "1: it never changes, and no edit key is handed out.", "schema": { "type": "string" } }, { "name": "append", "in": "query", "description": "open: anybody may add lines to it.", "schema": { "type": "string" } }, { "name": "children", "in": "query", "description": "closed: it takes no children.", "schema": { "type": "string" } }, { "name": "json", "in": "query", "description": "Answer as JSON.", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Kept. Plain text: the address on one line. JSON for whoever asks for it (Accept: application/json, or ?json).", "headers": { "Location": { "schema": { "type": "string" } }, "X-Iamb-Key": { "schema": { "type": "string" } }, "X-Iamb-Edit": { "schema": { "type": "string" }, "description": "The edit key, shown once." } }, "content": { "text/plain": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "key": { "type": "string" }, "url": { "type": "string" }, "type": { "type": "string", "description": "What the string is, as a media type." }, "bytes": { "type": "integer" }, "version": { "type": "integer" }, "created": { "type": "integer" }, "updated": { "type": "integer" }, "edit": { "type": "string", "description": "The edit key. Only in the answer to the request that made the iamb." }, "title": { "type": "string" }, "parent": { "type": "string" }, "expires": { "type": "integer" }, "frozen": { "type": "boolean" }, "append": { "type": "string" }, "files": { "type": "array", "items": { "type": "string" } }, "entry": { "type": "string" } } } } } }, "400": { "description": "A refusal: one sentence, or JSON for whoever asked for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": [ "empty", "not_yours", "frozen", "closed", "not_found", "too_large", "secret", "slow_down", "full", "name", "files", "bundle" ] }, "message": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "413": { "description": "A refusal: one sentence, or JSON for whoever asked for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": [ "empty", "not_yours", "frozen", "closed", "not_found", "too_large", "secret", "slow_down", "full", "name", "files", "bundle" ] }, "message": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "A refusal: one sentence, or JSON for whoever asked for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": [ "empty", "not_yours", "frozen", "closed", "not_found", "too_large", "secret", "slow_down", "full", "name", "files", "bundle" ] }, "message": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "429": { "description": "A refusal: one sentence, or JSON for whoever asked for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": [ "empty", "not_yours", "frozen", "closed", "not_found", "too_large", "secret", "slow_down", "full", "name", "files", "bundle" ] }, "message": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "507": { "description": "A refusal: one sentence, or JSON for whoever asked for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": [ "empty", "not_yours", "frozen", "closed", "not_found", "too_large", "secret", "slow_down", "full", "name", "files", "bundle" ] }, "message": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } } } } }, "/bundle": { "post": { "operationId": "bundle", "summary": "Post several named strings as one address", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "files" ], "properties": { "files": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "base64": { "type": "string" } } } ] } }, "entry": { "type": "string" }, "title": { "type": "string" }, "ttl": { "type": "integer" } } } }, "multipart/form-data": { "schema": { "type": "object", "additionalProperties": { "type": "string", "format": "binary" } } } } }, "responses": { "201": { "description": "Kept. Plain text: the address on one line. JSON for whoever asks for it (Accept: application/json, or ?json).", "headers": { "Location": { "schema": { "type": "string" } }, "X-Iamb-Key": { "schema": { "type": "string" } }, "X-Iamb-Edit": { "schema": { "type": "string" }, "description": "The edit key, shown once." } }, "content": { "text/plain": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "key": { "type": "string" }, "url": { "type": "string" }, "type": { "type": "string", "description": "What the string is, as a media type." }, "bytes": { "type": "integer" }, "version": { "type": "integer" }, "created": { "type": "integer" }, "updated": { "type": "integer" }, "edit": { "type": "string", "description": "The edit key. Only in the answer to the request that made the iamb." }, "title": { "type": "string" }, "parent": { "type": "string" }, "expires": { "type": "integer" }, "frozen": { "type": "boolean" }, "append": { "type": "string" }, "files": { "type": "array", "items": { "type": "string" } }, "entry": { "type": "string" } } } } } }, "400": { "description": "A refusal: one sentence, or JSON for whoever asked for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": [ "empty", "not_yours", "frozen", "closed", "not_found", "too_large", "secret", "slow_down", "full", "name", "files", "bundle" ] }, "message": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "413": { "description": "A refusal: one sentence, or JSON for whoever asked for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": [ "empty", "not_yours", "frozen", "closed", "not_found", "too_large", "secret", "slow_down", "full", "name", "files", "bundle" ] }, "message": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "A refusal: one sentence, or JSON for whoever asked for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": [ "empty", "not_yours", "frozen", "closed", "not_found", "too_large", "secret", "slow_down", "full", "name", "files", "bundle" ] }, "message": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "429": { "description": "A refusal: one sentence, or JSON for whoever asked for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": [ "empty", "not_yours", "frozen", "closed", "not_found", "too_large", "secret", "slow_down", "full", "name", "files", "bundle" ] }, "message": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } } } } }, "/{key}": { "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-hjkmnp-tv-z]{12}$" }, "description": "The twelve letters and digits of an iamb." } ], "get": { "operationId": "get", "summary": "Read an iamb, as the thing it is", "description": "Also: /{key}.txt (as posted), /{key}.meta (facts as JSON), /{key}. (take a text for that kind), /{key}/v/{n} (an older version).", "responses": { "200": { "description": "The thing itself. Its Content-Type is what the string is.", "content": { "*/*": {} } }, "304": { "description": "Not changed." }, "404": { "description": "A refusal: one sentence, or JSON for whoever asked for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": [ "empty", "not_yours", "frozen", "closed", "not_found", "too_large", "secret", "slow_down", "full", "name", "files", "bundle" ] }, "message": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } } } }, "put": { "operationId": "replace", "summary": "Put a new string in its place", "security": [ { "editKey": [] } ], "requestBody": { "content": { "*/*": { "schema": { "type": "string", "format": "binary" }, "description": "The string itself, as it is. Its kind is worked out from it." } }, "required": true }, "responses": { "200": { "description": "Kept. Plain text: the address on one line. JSON for whoever asks for it (Accept: application/json, or ?json).", "headers": { "Location": { "schema": { "type": "string" } }, "X-Iamb-Key": { "schema": { "type": "string" } }, "X-Iamb-Edit": { "schema": { "type": "string" }, "description": "The edit key, shown once." } }, "content": { "text/plain": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "key": { "type": "string" }, "url": { "type": "string" }, "type": { "type": "string", "description": "What the string is, as a media type." }, "bytes": { "type": "integer" }, "version": { "type": "integer" }, "created": { "type": "integer" }, "updated": { "type": "integer" }, "edit": { "type": "string", "description": "The edit key. Only in the answer to the request that made the iamb." }, "title": { "type": "string" }, "parent": { "type": "string" }, "expires": { "type": "integer" }, "frozen": { "type": "boolean" }, "append": { "type": "string" }, "files": { "type": "array", "items": { "type": "string" } }, "entry": { "type": "string" } } } } } }, "403": { "description": "A refusal: one sentence, or JSON for whoever asked for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": [ "empty", "not_yours", "frozen", "closed", "not_found", "too_large", "secret", "slow_down", "full", "name", "files", "bundle" ] }, "message": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "A refusal: one sentence, or JSON for whoever asked for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": [ "empty", "not_yours", "frozen", "closed", "not_found", "too_large", "secret", "slow_down", "full", "name", "files", "bundle" ] }, "message": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "413": { "description": "A refusal: one sentence, or JSON for whoever asked for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": [ "empty", "not_yours", "frozen", "closed", "not_found", "too_large", "secret", "slow_down", "full", "name", "files", "bundle" ] }, "message": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "A refusal: one sentence, or JSON for whoever asked for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": [ "empty", "not_yours", "frozen", "closed", "not_found", "too_large", "secret", "slow_down", "full", "name", "files", "bundle" ] }, "message": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } } } }, "delete": { "operationId": "delete", "summary": "Remove an iamb", "security": [ { "editKey": [] } ], "responses": { "200": { "description": "Removed." }, "403": { "description": "A refusal: one sentence, or JSON for whoever asked for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": [ "empty", "not_yours", "frozen", "closed", "not_found", "too_large", "secret", "slow_down", "full", "name", "files", "bundle" ] }, "message": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "A refusal: one sentence, or JSON for whoever asked for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": [ "empty", "not_yours", "frozen", "closed", "not_found", "too_large", "secret", "slow_down", "full", "name", "files", "bundle" ] }, "message": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } } } } }, "/{key}.meta": { "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-hjkmnp-tv-z]{12}$" }, "description": "The twelve letters and digits of an iamb." } ], "get": { "operationId": "meta", "summary": "What is known of an iamb", "responses": { "200": { "description": "Facts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "key": { "type": "string" }, "url": { "type": "string" }, "type": { "type": "string", "description": "What the string is, as a media type." }, "bytes": { "type": "integer" }, "version": { "type": "integer" }, "created": { "type": "integer" }, "updated": { "type": "integer" }, "edit": { "type": "string", "description": "The edit key. Only in the answer to the request that made the iamb." }, "title": { "type": "string" }, "parent": { "type": "string" }, "expires": { "type": "integer" }, "frozen": { "type": "boolean" }, "append": { "type": "string" }, "files": { "type": "array", "items": { "type": "string" } }, "entry": { "type": "string" } } } } } }, "404": { "description": "A refusal: one sentence, or JSON for whoever asked for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": [ "empty", "not_yours", "frozen", "closed", "not_found", "too_large", "secret", "slow_down", "full", "name", "files", "bundle" ] }, "message": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } } } } }, "/{key}/append": { "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-hjkmnp-tv-z]{12}$" }, "description": "The twelve letters and digits of an iamb." } ], "post": { "operationId": "append", "summary": "Add a line to the end", "description": "With the edit key always. Without it where the iamb was made with ?append=open (then one line may have 4 KB and a full log drops its oldest lines).", "security": [ {}, { "editKey": [] } ], "requestBody": { "content": { "*/*": { "schema": { "type": "string", "format": "binary" }, "description": "The string itself, as it is. Its kind is worked out from it." } }, "required": true }, "responses": { "200": { "description": "Kept. Plain text: the address on one line. JSON for whoever asks for it (Accept: application/json, or ?json).", "headers": { "Location": { "schema": { "type": "string" } }, "X-Iamb-Key": { "schema": { "type": "string" } }, "X-Iamb-Edit": { "schema": { "type": "string" }, "description": "The edit key, shown once." } }, "content": { "text/plain": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "key": { "type": "string" }, "url": { "type": "string" }, "type": { "type": "string", "description": "What the string is, as a media type." }, "bytes": { "type": "integer" }, "version": { "type": "integer" }, "created": { "type": "integer" }, "updated": { "type": "integer" }, "edit": { "type": "string", "description": "The edit key. Only in the answer to the request that made the iamb." }, "title": { "type": "string" }, "parent": { "type": "string" }, "expires": { "type": "integer" }, "frozen": { "type": "boolean" }, "append": { "type": "string" }, "files": { "type": "array", "items": { "type": "string" } }, "entry": { "type": "string" } } } } } }, "403": { "description": "A refusal: one sentence, or JSON for whoever asked for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": [ "empty", "not_yours", "frozen", "closed", "not_found", "too_large", "secret", "slow_down", "full", "name", "files", "bundle" ] }, "message": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "A refusal: one sentence, or JSON for whoever asked for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": [ "empty", "not_yours", "frozen", "closed", "not_found", "too_large", "secret", "slow_down", "full", "name", "files", "bundle" ] }, "message": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "413": { "description": "A refusal: one sentence, or JSON for whoever asked for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": [ "empty", "not_yours", "frozen", "closed", "not_found", "too_large", "secret", "slow_down", "full", "name", "files", "bundle" ] }, "message": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } } } } }, "/{key}/children": { "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-hjkmnp-tv-z]{12}$" }, "description": "The twelve letters and digits of an iamb." } ], "get": { "operationId": "children", "summary": "The children of an iamb, newest first", "parameters": [ { "name": "limit", "in": "query", "description": "How many (200 at most).", "schema": { "type": "integer" } }, { "name": "before", "in": "query", "description": "Only those made before this time (the 'created' of the last one you have).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "A list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "parent": { "type": "string" }, "children": { "type": "array", "items": { "type": "object", "properties": { "ok": { "type": "boolean" }, "key": { "type": "string" }, "url": { "type": "string" }, "type": { "type": "string", "description": "What the string is, as a media type." }, "bytes": { "type": "integer" }, "version": { "type": "integer" }, "created": { "type": "integer" }, "updated": { "type": "integer" }, "edit": { "type": "string", "description": "The edit key. Only in the answer to the request that made the iamb." }, "title": { "type": "string" }, "parent": { "type": "string" }, "expires": { "type": "integer" }, "frozen": { "type": "boolean" }, "append": { "type": "string" }, "files": { "type": "array", "items": { "type": "string" } }, "entry": { "type": "string" } } } } } } } } }, "404": { "description": "A refusal: one sentence, or JSON for whoever asked for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": [ "empty", "not_yours", "frozen", "closed", "not_found", "too_large", "secret", "slow_down", "full", "name", "files", "bundle" ] }, "message": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } } } } }, "/{key}/{name}": { "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-hjkmnp-tv-z]{12}$" }, "description": "The twelve letters and digits of an iamb." }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A named string of a bundle: index.html, img/ship.png" } ], "get": { "operationId": "getFile", "summary": "One named string of a bundle", "responses": { "200": { "description": "The file, as what its name says it is.", "content": { "*/*": {} } }, "404": { "description": "A refusal: one sentence, or JSON for whoever asked for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": [ "empty", "not_yours", "frozen", "closed", "not_found", "too_large", "secret", "slow_down", "full", "name", "files", "bundle" ] }, "message": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } } } }, "put": { "operationId": "putFile", "summary": "Add or change a named string of a bundle", "security": [ { "editKey": [] } ], "requestBody": { "content": { "*/*": { "schema": { "type": "string", "format": "binary" }, "description": "The string itself, as it is. Its kind is worked out from it." } }, "required": true }, "responses": { "200": { "description": "Kept. Plain text: the address on one line. JSON for whoever asks for it (Accept: application/json, or ?json).", "headers": { "Location": { "schema": { "type": "string" } }, "X-Iamb-Key": { "schema": { "type": "string" } }, "X-Iamb-Edit": { "schema": { "type": "string" }, "description": "The edit key, shown once." } }, "content": { "text/plain": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "key": { "type": "string" }, "url": { "type": "string" }, "type": { "type": "string", "description": "What the string is, as a media type." }, "bytes": { "type": "integer" }, "version": { "type": "integer" }, "created": { "type": "integer" }, "updated": { "type": "integer" }, "edit": { "type": "string", "description": "The edit key. Only in the answer to the request that made the iamb." }, "title": { "type": "string" }, "parent": { "type": "string" }, "expires": { "type": "integer" }, "frozen": { "type": "boolean" }, "append": { "type": "string" }, "files": { "type": "array", "items": { "type": "string" } }, "entry": { "type": "string" } } } } } }, "403": { "description": "A refusal: one sentence, or JSON for whoever asked for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": [ "empty", "not_yours", "frozen", "closed", "not_found", "too_large", "secret", "slow_down", "full", "name", "files", "bundle" ] }, "message": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } }, "413": { "description": "A refusal: one sentence, or JSON for whoever asked for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": [ "empty", "not_yours", "frozen", "closed", "not_found", "too_large", "secret", "slow_down", "full", "name", "files", "bundle" ] }, "message": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } } } } }, "/mcp": { "post": { "operationId": "mcp", "summary": "The MCP endpoint (Streamable HTTP, JSON-RPC 2.0)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "A JSON-RPC answer." }, "202": { "description": "A notification was taken." } } } } } }