{ "openapi": "3.1.0", "info": { "title": "hellodb API", "version": "1.0.0", "description": "The API behind hellodb, a visual canvas for designing database schemas. Every endpoint is a POST that takes and returns JSON. The same entries are exposed as MCP tools at https://api.hellodb.io/bridge/mcp, so an agent can call them natively rather than through this spec.", "contact": { "name": "hellodb", "url": "https://hellodb.io" } }, "servers": [{ "url": "https://api.hellodb.io/bridge", "description": "Production" }], "security": [{ "authToken": [] }], "components": { "securitySchemes": { "authToken": { "type": "apiKey", "in": "header", "name": "x-auth-token", "description": "Session token from auth.googleSignIn. Sign in at https://hellodb.io/sign-in to obtain one. When it expires, send the refresh token as x-refresh-token and the renewed session comes back in the x-new-auth-token response header." } }, "schemas": { "Error": { "type": "object", "description": "Every failure returns this shape, whatever the status code.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code, e.g. NOT_FOUND or FORBIDDEN" }, "message": { "type": "string", "description": "Human-readable explanation" }, "hint": { "type": "string", "description": "How to resolve it, when there is a known remedy" } }, "required": ["code", "message"] } }, "required": ["error"] } } }, "tags": [ { "name": "health" }, { "name": "auth" }, { "name": "user" }, { "name": "schema" }, { "name": "canvas" }, { "name": "version" }, { "name": "share" }, { "name": "public" }, { "name": "issue" }, { "name": "token" } ], "paths": { "/health.check": { "post": { "operationId": "healthCheck", "summary": "Liveness probe: reports whether the API and its database are reachable", "description": "Liveness probe: reports whether the API and its database are reachable", "tags": ["health"], "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "True when the process is serving" }, "database": { "type": "string", "description": "Mongoose connection state: 'connected', 'connecting', or 'disconnected'" } }, "required": ["ok", "database"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth.googleSignIn": { "post": { "operationId": "authGoogleSignIn", "summary": "Exchange a Google authorization code for a hellodb session", "description": "Exchange a Google authorization code for a hellodb session", "tags": ["auth"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "description": "The single-use authorization code returned by Google" } }, "required": ["code"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "authToken": { "type": "string", "description": "Short-lived JWT, sent as x-auth-token" }, "refreshToken": { "type": "string", "description": "Opaque long-lived token, sent as x-refresh-token" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "avatarUrl": { "anyOf": [{ "type": "string" }, { "type": "null" }] } }, "required": ["id", "email", "name", "avatarUrl"], "additionalProperties": false } }, "required": ["authToken", "refreshToken", "user"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth.signOut": { "post": { "operationId": "authSignOut", "summary": "Revoke the refresh token, ending this session only", "description": "Revoke the refresh token, ending this session only", "tags": ["auth"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refreshToken": { "type": "string", "description": "The refresh token to revoke" } }, "required": ["refreshToken"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": ["ok"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user.me": { "post": { "operationId": "userMe", "summary": "The account this session or agent token belongs to", "description": "The account this session or agent token belongs to", "tags": ["user"], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "avatarUrl": { "anyOf": [{ "type": "string" }, { "type": "null" }] } }, "required": ["id", "email", "name", "avatarUrl"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/schema.list": { "post": { "operationId": "schemaList", "summary": "List schemas the signed-in user can open — their own and any shared with them, newest first. Metadata only; no canvas content. Pass `query` to find one by name rather than reading the whole list. Names are not unique: when more than one row comes back for the name you were given, tell them apart by access, description, model count and updatedAt rather than picking one.", "description": "List schemas the signed-in user can open — their own and any shared with them, newest first. Metadata only; no canvas content. Pass `query` to find one by name rather than reading the whole list. Names are not unique: when more than one row comes back for the name you were given, tell them apart by access, description, model count and updatedAt rather than picking one.", "tags": ["schema"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filter": { "description": "Which schemas to return. Defaults to 'all' — owned plus shared, excluding archived. 'archived' returns only the archived ones.", "type": "string", "enum": ["all", "mine", "shared", "archived"] }, "query": { "description": "Narrows to schemas whose NAME contains this text, case-insensitively. Matches name only — not description, not engine. This is the cheap way to find one schema; prefer it over reading the whole list.", "type": "string", "maxLength": 120 }, "sort": { "description": "Defaults to 'recent' — most recently updated first. 'name' is A–Z, case-insensitive.", "type": "string", "enum": ["recent", "name"] }, "limit": { "description": "Rows per page. Defaults to 12; anything above 200 is clamped to it.", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "offset": { "description": "Rows to skip. Defaults to 0. Ordering by recency shifts as schemas are edited, so a row can repeat across two pages — deduplicate by `id` when walking more than one.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Schema id — pass to schema.get, or open at /app/{id}. The only stable identity a schema has" }, "name": { "type": "string", "description": "Not unique — two schemas can share a name. Never resolve one by name alone" }, "description": { "type": "string" }, "engine": { "type": "string", "description": "Database dialect the schema is authored against" }, "modelCount": { "type": "number" }, "relationCount": { "type": "number" }, "defaultDensity": { "type": "string", "enum": ["models", "relations", "fields"], "description": "How much of each model the schema is drawn with by default — names only, foreign keys, or every field. The designer opens on it and the dashboard thumbnail is rendered at it." }, "access": { "type": "string", "enum": ["owner", "write", "read"], "description": "The caller's standing on this schema" }, "isArchived": { "type": "boolean", "description": "Archived schemas are hidden from the default list" }, "isPublic": { "type": "boolean" }, "isImported": { "type": "boolean", "description": "True when the schema arrived as a file rather than being drawn here. Its layout came in with it, so no one has arranged this canvas by hand." }, "updatedAt": { "type": "string", "description": "ISO timestamp of the last change" }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "description", "engine", "modelCount", "relationCount", "defaultDensity", "access", "isArchived", "isPublic", "isImported", "updatedAt", "createdAt" ], "additionalProperties": false } }, "total": { "type": "number", "description": "How many schemas match `filter` and `query` in total, before paging — not how many came back" }, "hasMore": { "type": "boolean", "description": "True when rows remain past this page. Advance `offset` by `limit` to read them." } }, "required": ["rows", "total", "hasMore"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/schema.thumbnails": { "post": { "operationId": "schemaThumbnails", "summary": "The dashboard thumbnails for a page of schemas — each one an SVG of the canvas, rendered by the same code the designer draws and exports with, and cached against the canvas revision.", "description": "The dashboard thumbnails for a page of schemas — each one an SVG of the canvas, rendered by the same code the designer draws and exports with, and cached against the canvas revision.", "tags": ["schema"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "string" }, "description": "Schema ids, normally the page `schema.list` just returned" }, "theme": { "type": "string", "enum": ["dark", "light"], "description": "The palette is baked into the bytes, so the caller asks for the one it is drawing into" } }, "required": ["ids", "theme"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "svg": { "type": "string" } }, "required": ["id", "svg"], "additionalProperties": false } } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/schema.get": { "post": { "operationId": "schemaGet", "summary": "One schema by id, with the caller’s access level", "description": "One schema by id, with the caller’s access level", "tags": ["schema"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Schema id" } }, "required": ["id"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Schema id — pass to schema.get, or open at /app/{id}. The only stable identity a schema has" }, "name": { "type": "string", "description": "Not unique — two schemas can share a name. Never resolve one by name alone" }, "description": { "type": "string" }, "engine": { "type": "string", "description": "Database dialect the schema is authored against" }, "modelCount": { "type": "number" }, "relationCount": { "type": "number" }, "defaultDensity": { "type": "string", "enum": ["models", "relations", "fields"], "description": "How much of each model the schema is drawn with by default — names only, foreign keys, or every field. The designer opens on it and the dashboard thumbnail is rendered at it." }, "access": { "type": "string", "enum": ["owner", "write", "read"], "description": "The caller's standing on this schema" }, "isArchived": { "type": "boolean", "description": "Archived schemas are hidden from the default list" }, "isPublic": { "type": "boolean" }, "isImported": { "type": "boolean", "description": "True when the schema arrived as a file rather than being drawn here. Its layout came in with it, so no one has arranged this canvas by hand." }, "updatedAt": { "type": "string", "description": "ISO timestamp of the last change" }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "description", "engine", "modelCount", "relationCount", "defaultDensity", "access", "isArchived", "isPublic", "isImported", "updatedAt", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/schema.create": { "post": { "operationId": "schemaCreate", "summary": "Create an empty schema and its canvas", "description": "Create an empty schema and its canvas", "tags": ["schema"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Schema name, e.g. acme_store" }, "description": { "type": "string", "maxLength": 512 }, "engine": { "description": "Database dialect. Left unset when not given.", "type": "string", "maxLength": 60 }, "defaultDensity": { "description": "How much of each model the schema opens with. Defaults to 'models' — names only.", "type": "string", "enum": ["models", "relations", "fields"] }, "isImported": { "description": "Set when this schema is being created to receive a file — an import — rather than to be drawn from scratch. Marks the canvas as one whose layout arrived with it. Defaults to false.", "type": "boolean" } }, "required": ["name"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Schema id — pass to schema.get, or open at /app/{id}. The only stable identity a schema has" }, "name": { "type": "string", "description": "Not unique — two schemas can share a name. Never resolve one by name alone" }, "description": { "type": "string" }, "engine": { "type": "string", "description": "Database dialect the schema is authored against" }, "modelCount": { "type": "number" }, "relationCount": { "type": "number" }, "defaultDensity": { "type": "string", "enum": ["models", "relations", "fields"], "description": "How much of each model the schema is drawn with by default — names only, foreign keys, or every field. The designer opens on it and the dashboard thumbnail is rendered at it." }, "access": { "type": "string", "enum": ["owner", "write", "read"], "description": "The caller's standing on this schema" }, "isArchived": { "type": "boolean", "description": "Archived schemas are hidden from the default list" }, "isPublic": { "type": "boolean" }, "isImported": { "type": "boolean", "description": "True when the schema arrived as a file rather than being drawn here. Its layout came in with it, so no one has arranged this canvas by hand." }, "updatedAt": { "type": "string", "description": "ISO timestamp of the last change" }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "description", "engine", "modelCount", "relationCount", "defaultDensity", "access", "isArchived", "isPublic", "isImported", "updatedAt", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/schema.patch": { "post": { "operationId": "schemaPatch", "summary": "Rename a schema, or change its description, engine or default view", "description": "Rename a schema, or change its description, engine or default view", "tags": ["schema"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 512 }, "engine": { "type": "string", "maxLength": 60 }, "defaultDensity": { "description": "How much of each model the schema opens with, and is drawn with in its thumbnail", "type": "string", "enum": ["models", "relations", "fields"] } }, "required": ["id"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Schema id — pass to schema.get, or open at /app/{id}. The only stable identity a schema has" }, "name": { "type": "string", "description": "Not unique — two schemas can share a name. Never resolve one by name alone" }, "description": { "type": "string" }, "engine": { "type": "string", "description": "Database dialect the schema is authored against" }, "modelCount": { "type": "number" }, "relationCount": { "type": "number" }, "defaultDensity": { "type": "string", "enum": ["models", "relations", "fields"], "description": "How much of each model the schema is drawn with by default — names only, foreign keys, or every field. The designer opens on it and the dashboard thumbnail is rendered at it." }, "access": { "type": "string", "enum": ["owner", "write", "read"], "description": "The caller's standing on this schema" }, "isArchived": { "type": "boolean", "description": "Archived schemas are hidden from the default list" }, "isPublic": { "type": "boolean" }, "isImported": { "type": "boolean", "description": "True when the schema arrived as a file rather than being drawn here. Its layout came in with it, so no one has arranged this canvas by hand." }, "updatedAt": { "type": "string", "description": "ISO timestamp of the last change" }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "description", "engine", "modelCount", "relationCount", "defaultDensity", "access", "isArchived", "isPublic", "isImported", "updatedAt", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/schema.setArchived": { "post": { "operationId": "schemaSetArchived", "summary": "Archive a schema or bring it back. Archiving hides it from the list without deleting anything.", "description": "Archive a schema or bring it back. Archiving hides it from the list without deleting anything.", "tags": ["schema"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "isArchived": { "type": "boolean", "description": "True to archive, false to restore" } }, "required": ["id", "isArchived"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Schema id — pass to schema.get, or open at /app/{id}. The only stable identity a schema has" }, "name": { "type": "string", "description": "Not unique — two schemas can share a name. Never resolve one by name alone" }, "description": { "type": "string" }, "engine": { "type": "string", "description": "Database dialect the schema is authored against" }, "modelCount": { "type": "number" }, "relationCount": { "type": "number" }, "defaultDensity": { "type": "string", "enum": ["models", "relations", "fields"], "description": "How much of each model the schema is drawn with by default — names only, foreign keys, or every field. The designer opens on it and the dashboard thumbnail is rendered at it." }, "access": { "type": "string", "enum": ["owner", "write", "read"], "description": "The caller's standing on this schema" }, "isArchived": { "type": "boolean", "description": "Archived schemas are hidden from the default list" }, "isPublic": { "type": "boolean" }, "isImported": { "type": "boolean", "description": "True when the schema arrived as a file rather than being drawn here. Its layout came in with it, so no one has arranged this canvas by hand." }, "updatedAt": { "type": "string", "description": "ISO timestamp of the last change" }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "description", "engine", "modelCount", "relationCount", "defaultDensity", "access", "isArchived", "isPublic", "isImported", "updatedAt", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/schema.delete": { "post": { "operationId": "schemaDelete", "summary": "Delete a schema and everything belonging to it — canvases, versions, ops, shares and renders", "description": "Delete a schema and everything belonging to it — canvases, versions, ops, shares and renders", "tags": ["schema"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": ["id"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": ["ok"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/schema.describe": { "post": { "operationId": "schemaDescribe", "summary": "A compact description of one schema: model names, their fields and types, and the relations between them. Use this to reason about a schema; it omits layout and prose so it stays small.", "description": "A compact description of one schema: model names, their fields and types, and the relations between them. Use this to reason about a schema; it omits layout and prose so it stays small.", "tags": ["schema"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Schema id from schema.list" } }, "required": ["id"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "engine": { "type": "string" }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The id every op addresses this model by" }, "name": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" }, "description": "Each field as \"name: type (id)\", with `PK` or `FK` where it is one. An OBJECT field ends \"-> document \" and its own fields follow, indented two spaces per level — that document id is what a field op means by `entityId` when adding inside it." } }, "required": ["id", "name", "fields"], "additionalProperties": false } }, "relations": { "type": "array", "items": { "type": "string" }, "description": "Each relation as \"parent.field -> child.field\", named rather than by id, and one-to-one marked. An endpoint inside an embedded document reads as its full path, e.g. \"user.address.geo\"." } }, "required": ["name", "engine", "models", "relations"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/canvas.get": { "post": { "operationId": "canvasGet", "summary": "The current canvas of a schema — every model, field and relation, as drawn.", "description": "The current canvas of a schema — every model, field and relation, as drawn.", "tags": ["canvas"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaId": { "type": "string", "description": "Schema id" } }, "required": ["schemaId"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaId": { "type": "string" }, "seq": { "type": "number", "description": "Ordering counter — pass back to resume after a disconnect" }, "content": { "type": "object", "properties": { "models": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "relations": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["models", "relations"], "additionalProperties": false } }, "required": ["schemaId", "seq", "content"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/canvas.applyOps": { "post": { "operationId": "canvasApplyOps", "summary": "Apply a batch of canvas operations — add or move models, edit fields, draw relations. Everyone with the schema open sees the result immediately. `model.patch` accepts `hideRelations`, which stops one model’s edges being drawn so a hub does not bury the rest of the schema; it deletes nothing and the edges return on hover, but always tell the person which models you set it on.", "description": "Apply a batch of canvas operations — add or move models, edit fields, draw relations. Everyone with the schema open sees the result immediately. `model.patch` accepts `hideRelations`, which stops one model’s edges being drawn so a hub does not bury the rest of the schema; it deletes nothing and the edges return on hover, but always tell the person which models you set it on.", "tags": ["canvas"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaId": { "type": "string" }, "ops": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "model.add", "model.move", "model.patch", "model.remove", "field.add", "field.patch", "field.remove", "field.reorder", "relation.add", "relation.patch", "relation.remove", "index.add", "index.patch", "index.remove" ], "description": "Which operation this is" } }, "required": ["kind"], "additionalProperties": {} }, "description": "Canvas operations, applied in order. Every op is an object with a `kind` and the fields that kind needs — e.g. { kind: \"model.add\", model: {...} }, { kind: \"model.move\", id, x, y }, { kind: \"field.add\", entityId, field: {...}, index }, { kind: \"index.add\", modelId, index: {...} }. The full shape of each is in the hellodb agent skill." } }, "required": ["schemaId", "ops"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "seq": { "type": "number" }, "applied": { "type": "number", "description": "How many of the submitted operations took effect" }, "rejected": { "type": "array", "items": { "type": "object", "properties": { "reason": { "type": "string" } }, "required": ["reason"], "additionalProperties": false } } }, "required": ["seq", "applied", "rejected"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/canvas.replace": { "post": { "operationId": "canvasReplace", "summary": "Replace the whole canvas at once. For generating or importing a schema — dozens of models arriving together land as one change rather than as a stream that makes the canvas thrash.", "description": "Replace the whole canvas at once. For generating or importing a schema — dozens of models arriving together land as one change rather than as a stream that makes the canvas thrash.", "tags": ["canvas"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaId": { "type": "string" }, "content": { "type": "object", "properties": { "models": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "hue": { "anyOf": [{ "type": "number" }, { "type": "null" }] }, "x": { "type": "number" }, "y": { "type": "number" }, "fields": { "type": "array", "items": { "$ref": "#/$defs/__schema0" } }, "indexes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "fields": { "type": "array", "items": { "type": "object", "properties": { "fieldId": { "type": "string", "minLength": 1 }, "direction": { "type": "string", "enum": ["asc", "desc"] } }, "required": ["fieldId"], "additionalProperties": false } }, "isUnique": { "type": "boolean" }, "kind": { "type": "string" }, "description": { "type": "string" }, "at": { "type": "number" } }, "required": ["id", "fields"], "additionalProperties": false } }, "description": { "type": "string" }, "hideRelations": { "type": "boolean" }, "at": { "type": "number" } }, "required": ["id", "name", "x", "y", "fields"], "additionalProperties": false } }, "relations": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "parentModelId": { "type": "string", "minLength": 1 }, "parentFieldId": { "type": "string", "minLength": 1 }, "childModelId": { "type": "string", "minLength": 1 }, "childFieldId": { "type": "string", "minLength": 1 }, "cardinality": { "type": "string", "enum": ["one-to-many", "one-to-one"] }, "description": { "type": "string" }, "at": { "type": "number" } }, "required": [ "id", "parentModelId", "parentFieldId", "childModelId", "childFieldId" ], "additionalProperties": false } } }, "required": ["models", "relations"], "additionalProperties": false } }, "required": ["schemaId", "content"], "additionalProperties": false, "$defs": { "__schema0": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "BIGINT", "BLOB", "BOOLEAN", "DATE", "DECIMAL", "ENUM", "INT", "JSONB", "OBJECT", "OBJECTID", "TEXT", "TIMESTAMP", "UUID", "VARCHAR", "VECTOR" ] }, "isPrimaryKey": { "type": "boolean" }, "isForeignKey": { "type": "boolean" }, "isNullable": { "type": "boolean" }, "isArray": { "type": "boolean" }, "enumValues": { "type": "array", "items": { "type": "string" } }, "vectorLength": { "type": "number" }, "description": { "type": "string" }, "at": { "type": "number" }, "nested": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "fields": { "type": "array", "items": { "$ref": "#/$defs/__schema0" } } }, "required": ["id", "fields"], "additionalProperties": false } }, "required": ["id", "name", "type"], "additionalProperties": false } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "seq": { "type": "number" } }, "required": ["seq"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/canvas.tidy": { "post": { "operationId": "canvasTidy", "summary": "Re-arrange every model into left-to-right columns by relation depth — the same layout as the Tidy button. This REPLACES the current arrangement: use it on a new or unarranged schema, or when the person asks to reset the layout. Never use it to tidy a canvas someone arranged by hand; place new models individually instead.", "description": "Re-arrange every model into left-to-right columns by relation depth — the same layout as the Tidy button. This REPLACES the current arrangement: use it on a new or unarranged schema, or when the person asks to reset the layout. Never use it to tidy a canvas someone arranged by hand; place new models individually instead.", "tags": ["canvas"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaId": { "type": "string" } }, "required": ["schemaId"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "seq": { "type": "number" }, "moved": { "type": "number", "description": "How many models actually changed position" } }, "required": ["seq", "moved"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/version.list": { "post": { "operationId": "versionList", "summary": "The version history of a schema, newest first, one page at a time. Metadata only — no canvas content. Two numbers from here form a comparison the person can open at /app/{schemaId}/compare/v{from}/v{to}.", "description": "The version history of a schema, newest first, one page at a time. Metadata only — no canvas content. Two numbers from here form a comparison the person can open at /app/{schemaId}/compare/v{from}/v{to}.", "tags": ["version"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaId": { "type": "string" }, "archived": { "description": "Defaults to 'exclude'. Archived versions are ones somebody filed out of the list, usually because they were cut by mistake — they still restore and compare, they are just not part of the history anyone is reading.", "type": "string", "enum": ["exclude", "include"] }, "limit": { "description": "Rows per page. Defaults to 12; anything above 200 is clamped to it.", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "offset": { "description": "Rows to skip. Defaults to 0.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["schemaId"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "versions": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "number" }, "description": { "type": "string" }, "createdAt": { "type": "string" }, "createdBy": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "restoredFrom": { "anyOf": [{ "type": "number" }, { "type": "null" }], "description": "The version this one was restored from, when it was" }, "atSeq": { "type": "number", "description": "The room counter at the cut — what \"changes since\" is measured against" }, "isArchived": { "type": "boolean", "description": "Filed away out of the history list. Display only — it still restores and compares" } }, "required": [ "number", "description", "createdAt", "createdBy", "restoredFrom", "atSeq", "isArchived" ], "additionalProperties": false } }, "seq": { "type": "number" }, "currentNumber": { "type": "number", "description": "The highest version number this schema has, archived or not — where the canvas is. 0 if none" }, "hasChangesSinceLastVersion": { "type": "boolean" }, "total": { "type": "number", "description": "How many versions match `archived` in total, before paging" }, "hasMore": { "type": "boolean", "description": "True when rows remain past this page. Advance `offset` by `limit` to read them." } }, "required": [ "versions", "seq", "currentNumber", "hasChangesSinceLastVersion", "total", "hasMore" ], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/version.get": { "post": { "operationId": "versionGet", "summary": "One version’s canvas, as it was when that version was cut.", "description": "One version’s canvas, as it was when that version was cut.", "tags": ["version"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaId": { "type": "string" }, "number": { "type": "number" } }, "required": ["schemaId", "number"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "number" }, "description": { "type": "string" }, "atSeq": { "type": "number" }, "content": { "type": "object", "properties": { "models": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "relations": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["models", "relations"], "additionalProperties": false } }, "required": ["number", "description", "atSeq", "content"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/version.create": { "post": { "operationId": "versionCreate", "summary": "Name the current state of a schema as a version. Cut one before and after any substantial change: the two numbers form a comparison the person can open at /app/{schemaId}/compare/v{from}/v{to}, which draws the difference on the canvas itself.", "description": "Name the current state of a schema as a version. Cut one before and after any substantial change: the two numbers form a comparison the person can open at /app/{schemaId}/compare/v{from}/v{to}, which draws the difference on the canvas itself.", "tags": ["version"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaId": { "type": "string" }, "description": { "type": "string", "minLength": 1, "maxLength": 200, "description": "What changed — required, so every row says something" } }, "required": ["schemaId", "description"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "number" }, "atSeq": { "type": "number" } }, "required": ["number", "atSeq"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/version.restore": { "post": { "operationId": "versionRestore", "summary": "Put a past version back as the current canvas. History is never rewritten — this appends a new version recording where it came from.", "description": "Put a past version back as the current canvas. History is never rewritten — this appends a new version recording where it came from.", "tags": ["version"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaId": { "type": "string" }, "number": { "type": "number" } }, "required": ["schemaId", "number"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "seq": { "type": "number" }, "restoredTo": { "type": "number" } }, "required": ["seq", "restoredTo"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/version.setArchived": { "post": { "operationId": "versionSetArchived", "summary": "File a version out of the history list, or put it back. Display only — an archived version keeps its number and still restores and compares. Use it for a version cut by mistake, not to clean up history somebody may still be reading.", "description": "File a version out of the history list, or put it back. Display only — an archived version keeps its number and still restores and compares. Use it for a version cut by mistake, not to clean up history somebody may still be reading.", "tags": ["version"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaId": { "type": "string" }, "number": { "type": "number" }, "isArchived": { "type": "boolean" } }, "required": ["schemaId", "number", "isArchived"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "number" }, "isArchived": { "type": "boolean" } }, "required": ["number", "isArchived"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/version.diff": { "post": { "operationId": "versionDiff", "summary": "What changed between two versions of a schema, as Markdown. Pass version numbers, or \"current\" for the live canvas. Prefer giving a person the drawing at /app/{schemaId}/compare/v{from}/v{to}; use this when you need to read the changes yourself.", "description": "What changed between two versions of a schema, as Markdown. Pass version numbers, or \"current\" for the live canvas. Prefer giving a person the drawing at /app/{schemaId}/compare/v{from}/v{to}; use this when you need to read the changes yourself.", "tags": ["version"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaId": { "type": "string" }, "from": { "anyOf": [{ "type": "number" }, { "type": "string", "const": "current" }], "description": "Version number, or \"current\"" }, "to": { "anyOf": [{ "type": "number" }, { "type": "string", "const": "current" }], "description": "Version number, or \"current\"" } }, "required": ["schemaId", "from", "to"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "added": { "type": "number" }, "removed": { "type": "number" }, "modified": { "type": "number" }, "markdown": { "type": "string", "description": "The changes grouped by model, ready to read or paste" } }, "required": ["from", "to", "added", "removed", "modified", "markdown"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/share.list": { "post": { "operationId": "shareList", "summary": "Who a schema is shared with, and at what level.", "description": "Who a schema is shared with, and at what level.", "tags": ["share"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaId": { "type": "string" } }, "required": ["schemaId"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "avatarUrl": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "access": { "type": "string", "enum": ["owner", "write", "read"] }, "hasAccount": { "type": "boolean" } }, "required": ["email", "name", "avatarUrl", "access", "hasAccount"], "additionalProperties": false }, "collaborators": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "avatarUrl": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "access": { "type": "string", "enum": ["owner", "write", "read"] }, "hasAccount": { "type": "boolean" } }, "required": ["email", "name", "avatarUrl", "access", "hasAccount"], "additionalProperties": false } }, "myAccess": { "type": "string", "enum": ["owner", "write", "read"] }, "isPublic": { "type": "boolean" }, "publicToken": { "anyOf": [{ "type": "string" }, { "type": "null" }] } }, "required": ["owner", "collaborators", "myAccess", "isPublic", "publicToken"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/share.invite": { "post": { "operationId": "shareInvite", "summary": "Share a schema with someone by email, or change the access of someone it is already shared with.", "description": "Share a schema with someone by email, or change the access of someone it is already shared with.", "tags": ["share"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaId": { "type": "string" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "access": { "type": "string", "enum": ["write", "read"], "description": "Ownership is not transferable through this" } }, "required": ["schemaId", "email", "access"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "hasAccount": { "type": "boolean" } }, "required": ["ok", "hasAccount"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/share.revoke": { "post": { "operationId": "shareRevoke", "summary": "Stop sharing a schema with someone.", "description": "Stop sharing a schema with someone.", "tags": ["share"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaId": { "type": "string" }, "email": { "type": "string" } }, "required": ["schemaId", "email"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": ["ok"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/share.leave": { "post": { "operationId": "shareLeave", "summary": "Remove yourself from a schema someone shared with you.", "description": "Remove yourself from a schema someone shared with you.", "tags": ["share"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaId": { "type": "string" } }, "required": ["schemaId"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": ["ok"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/share.setPublic": { "post": { "operationId": "shareSetPublic", "summary": "Turn the public read-only link on or off for a schema.", "description": "Turn the public read-only link on or off for a schema.", "tags": ["share"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaId": { "type": "string" }, "isPublic": { "type": "boolean" } }, "required": ["schemaId", "isPublic"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "isPublic": { "type": "boolean" }, "token": { "anyOf": [{ "type": "string" }, { "type": "null" }] } }, "required": ["isPublic", "token"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/share.rotateLink": { "post": { "operationId": "shareRotateLink", "summary": "Replace the public link with a new one, which invalidates every address already handed out.", "description": "Replace the public link with a new one, which invalidates every address already handed out.", "tags": ["share"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaId": { "type": "string" } }, "required": ["schemaId"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": ["token"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/public.get": { "post": { "operationId": "publicGet", "summary": "Open a schema through its public link. No account needed; read-only.", "description": "Open a schema through its public link. No account needed; read-only.", "tags": ["public"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 8, "description": "The token from a /s/ address" } }, "required": ["token"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "engine": { "type": "string" }, "content": { "type": "object", "properties": { "models": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "relations": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["models", "relations"], "additionalProperties": false } }, "required": ["name", "description", "engine", "content"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/issue.report": { "post": { "operationId": "issueReport", "summary": "Report a bug, idea or note about hellodb itself — the product, not the schema being edited. File a bug the moment a tool behaves wrongly and you can say concretely what you expected and what happened. File an idea only for a concrete gap the work in front of you exposed, and only once the person has agreed to it. Not a place to log notes for the user.", "description": "Report a bug, idea or note about hellodb itself — the product, not the schema being edited. File a bug the moment a tool behaves wrongly and you can say concretely what you expected and what happened. File an idea only for a concrete gap the work in front of you exposed, and only once the person has agreed to it. Not a place to log notes for the user.", "tags": ["issue"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "default": "bug", "description": "What kind of report this is", "type": "string", "enum": ["bug", "idea", "other"] }, "body": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "What happened, in the reporter’s own words" }, "context": { "description": "Where the reporter was. Filled in by the client, not the user.", "type": "object", "properties": { "schemaId": { "type": "string" }, "path": { "type": "string", "maxLength": 400 }, "version": { "type": "string", "maxLength": 40 }, "userAgent": { "type": "string", "maxLength": 400 }, "viewport": { "type": "string", "maxLength": 40 }, "appVersion": { "type": "string", "maxLength": 40 } }, "additionalProperties": false } }, "required": ["kind", "body"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "reference": { "type": "string", "description": "Short reference shown to the reporter" } }, "required": ["id", "reference"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/token.list": { "post": { "operationId": "tokenList", "summary": "Every agent token on this account, newest first.", "description": "Every agent token on this account, newest first.", "tags": ["token"], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "prefix": { "type": "string" }, "lastUsedAt": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "createdAt": { "type": "string" } }, "required": ["id", "name", "description", "prefix", "lastUsedAt", "createdAt"], "additionalProperties": false } } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/token.create": { "post": { "operationId": "tokenCreate", "summary": "Create an agent token. The token itself is returned once and cannot be read again.", "description": "Create an agent token. The token itself is returned once and cannot be read again.", "tags": ["token"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "description": { "type": "string", "maxLength": 200 } }, "required": ["name"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "record": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "prefix": { "type": "string" }, "lastUsedAt": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "description", "prefix", "lastUsedAt", "createdAt" ], "additionalProperties": false }, "token": { "type": "string" } }, "required": ["record", "token"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/token.revoke": { "post": { "operationId": "tokenRevoke", "summary": "Revoke an agent token. Whatever is holding it stops working on its next call.", "description": "Revoke an agent token. Whatever is holding it stops working on its next call.", "tags": ["token"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": ["id"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": ["ok"], "additionalProperties": false } } } }, "400": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }