{ "openapi": "3.1.1", "info": { "title": "Reference Tag Organizer API", "version": "1.0.0", "summary": "Clean up and apply tags across a reference board.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://pageboardtagorganizer.usefulweb.app" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Clean up and apply tags across a reference board.", "description": "Normalize tags on a Pageboard project, then optionally add or remove a tag on every reference. Download the updated editable board.\n\nMethodology:\n- Trims and collapses whitespace in existing tags and removes empty tags. Tags that differ only in letter case are merged: the first spelling on the board (in reference order) is used everywhere, and duplicates on one reference are removed.\n- Add and remove apply to every reference after normalization. Adding a duplicate has no effect; removing compares without case. The entire operation is rejected if adding would exceed eight tags on any reference.\n- All other reference fields, links, notes, favorites and screenshots are preserved. No source pages are loaded.\n- The project download is the editable result; the editor link carries the same data and is omitted when it would exceed one million encoded characters.", "tags": [ "apps" ], "x-mcp-tool": "pageboard_tag_organizer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageboardTagOrganizerInput" }, "examples": { "example1": { "summary": "Clean up messy tags", "value": { "project": "{\"format\":\"pageboard-project\",\"version\":1,\"name\":\"Imported bookmarks\",\"entries\":[{\"id\":\"pricing\",\"title\":\"Pricing with three plans\",\"url\":\"\",\"type\":\"Pricing\",\"platform\":\"Desktop\",\"tags\":[\" Pricing \",\"pricing\",\"Conversion table\"],\"notes\":\"\",\"favorite\":false,\"accent\":\"#c9bca8\",\"screenshot\":\"\"},{\"id\":\"footer\",\"title\":\"Footer with a sitemap\",\"url\":\"\",\"type\":\"Footer\",\"platform\":\"Desktop\",\"tags\":[\"Navigation\",\"navigation \",\"Typography\"],\"notes\":\"\",\"favorite\":false,\"accent\":\"#c9bca8\",\"screenshot\":\"\"},{\"id\":\"signup\",\"title\":\"Signup in one step\",\"url\":\"\",\"type\":\"Form\",\"platform\":\"Mobile\",\"tags\":[\"Forms\",\"typography\",\"Forms\"],\"notes\":\"\",\"favorite\":false,\"accent\":\"#c9bca8\",\"screenshot\":\"\"}],\"moodboard\":{\"items\":[]}}" } }, "example2": { "summary": "Add a research tag to every reference", "value": { "action": "add", "tag": "research" } }, "example3": { "summary": "Remove a tag in any letter case", "value": { "project": "{\"format\":\"pageboard-project\",\"version\":1,\"name\":\"Imported bookmarks\",\"entries\":[{\"id\":\"pricing\",\"title\":\"Pricing with three plans\",\"url\":\"\",\"type\":\"Pricing\",\"platform\":\"Desktop\",\"tags\":[\" Pricing \",\"pricing\",\"Conversion table\"],\"notes\":\"\",\"favorite\":false,\"accent\":\"#c9bca8\",\"screenshot\":\"\"},{\"id\":\"footer\",\"title\":\"Footer with a sitemap\",\"url\":\"\",\"type\":\"Footer\",\"platform\":\"Desktop\",\"tags\":[\"Navigation\",\"navigation \",\"Typography\"],\"notes\":\"\",\"favorite\":false,\"accent\":\"#c9bca8\",\"screenshot\":\"\"},{\"id\":\"signup\",\"title\":\"Signup in one step\",\"url\":\"\",\"type\":\"Form\",\"platform\":\"Mobile\",\"tags\":[\"Forms\",\"typography\",\"Forms\"],\"notes\":\"\",\"favorite\":false,\"accent\":\"#c9bca8\",\"screenshot\":\"\"}],\"moodboard\":{\"items\":[]}}", "action": "remove", "tag": "TYPOGRAPHY" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageboardTagOrganizerResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "PageboardTagOrganizerInput": { "type": "object", "additionalProperties": false, "properties": { "project": { "title": "Pageboard project JSON", "type": "string", "maxLength": 4000000, "default": "{\n \"format\": \"pageboard-project\",\n \"version\": 1,\n \"name\": \"A small collection\",\n \"entries\": [\n {\n \"id\": \"studio\",\n \"title\": \"A quiet studio\",\n \"url\": \"\",\n \"type\": \"Portfolio\",\n \"platform\": \"Desktop\",\n \"tags\": [\n \"Editorial\",\n \"Typography\"\n ],\n \"notes\": \"Try a generous margin and a single strong headline.\",\n \"favorite\": true,\n \"accent\": \"#d9b99f\",\n \"screenshot\": \"\"\n },\n {\n \"id\": \"garden\",\n \"title\": \"The garden journal\",\n \"url\": \"\",\n \"type\": \"Editorial\",\n \"platform\": \"Mobile\",\n \"tags\": [\n \"Nature\",\n \"Photography\"\n ],\n \"notes\": \"Look for a calm rhythm between image and text.\",\n \"favorite\": false,\n \"accent\": \"#a9b99d\",\n \"screenshot\": \"\"\n },\n {\n \"id\": \"objects\",\n \"title\": \"Objects for everyday\",\n \"url\": \"\",\n \"type\": \"Shop\",\n \"platform\": \"Desktop\",\n \"tags\": [\n \"Minimal\",\n \"Product\"\n ],\n \"notes\": \"A restrained palette lets the objects stand out.\",\n \"favorite\": false,\n \"accent\": \"#bfc3d2\",\n \"screenshot\": \"\"\n },\n {\n \"id\": \"festival\",\n \"title\": \"An independent festival\",\n \"url\": \"\",\n \"type\": \"Event\",\n \"platform\": \"Mobile\",\n \"tags\": [\n \"Color\",\n \"Typography\"\n ],\n \"notes\": \"Explore expressive type and a clear schedule.\",\n \"favorite\": false,\n \"accent\": \"#e2b878\",\n \"screenshot\": \"\"\n }\n ],\n \"moodboard\": {\n \"items\": [\n {\n \"id\": \"m-studio\",\n \"kind\": \"reference\",\n \"x\": 60,\n \"y\": 60,\n \"w\": 260,\n \"h\": 220,\n \"text\": \"\",\n \"color\": \"#d9b99f\",\n \"ref\": \"studio\",\n \"image\": \"\"\n },\n {\n \"id\": \"m-garden\",\n \"kind\": \"reference\",\n \"x\": 360,\n \"y\": 60,\n \"w\": 220,\n \"h\": 220,\n \"text\": \"\",\n \"color\": \"#a9b99d\",\n \"ref\": \"garden\",\n \"image\": \"\"\n },\n {\n \"id\": \"m-note\",\n \"kind\": \"note\",\n \"x\": 620,\n \"y\": 60,\n \"w\": 240,\n \"h\": 150,\n \"text\": \"Calm, editorial, lots of white space.\",\n \"color\": \"#fff6d8\",\n \"ref\": \"\",\n \"image\": \"\"\n },\n {\n \"id\": \"m-sand\",\n \"kind\": \"swatch\",\n \"x\": 620,\n \"y\": 240,\n \"w\": 120,\n \"h\": 110,\n \"text\": \"Sand\",\n \"color\": \"#d9b99f\",\n \"ref\": \"\",\n \"image\": \"\"\n },\n {\n \"id\": \"m-moss\",\n \"kind\": \"swatch\",\n \"x\": 760,\n \"y\": 240,\n \"w\": 120,\n \"h\": 110,\n \"text\": \"Moss\",\n \"color\": \"#6f7f5f\",\n \"ref\": \"\",\n \"image\": \"\"\n }\n ]\n }\n}" }, "action": { "title": "Tag action", "type": "string", "enum": [ "normalize", "add", "remove" ], "default": "normalize" }, "tag": { "title": "Tag to add or remove", "type": "string", "maxLength": 40, "default": "" } }, "required": [] }, "PageboardTagOrganizerResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "project", "report", "changedEntries", "projectFile", "openInApp" ], "properties": { "project": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Pageboard project", "type": "object", "required": [ "format", "version", "name", "entries" ], "properties": { "format": { "const": "pageboard-project" }, "version": { "const": 1 }, "name": { "type": "string", "maxLength": 120 }, "entries": { "type": "array", "maxItems": 100, "items": { "type": "object", "required": [ "id", "title", "url", "type", "platform", "tags", "notes", "favorite", "accent", "screenshot" ], "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$" }, "title": { "type": "string", "maxLength": 120 }, "url": { "type": "string", "maxLength": 2048 }, "type": { "type": "string", "maxLength": 80 }, "platform": { "type": "string", "maxLength": 80 }, "tags": { "type": "array", "maxItems": 8, "items": { "type": "string", "maxLength": 40 } }, "notes": { "type": "string", "maxLength": 4000 }, "favorite": { "type": "boolean" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "screenshot": { "type": "string", "maxLength": 400040, "pattern": "^(|data:image/(png|jpeg|webp);base64,[A-Za-z0-9+/]+=*)$" } } } }, "moodboard": { "type": "object", "description": "Optional spatial moodboard on a 1600 × 1000 canvas; array order is the stacking order.", "required": [ "items" ], "properties": { "items": { "type": "array", "maxItems": 80, "items": { "type": "object", "required": [ "id", "kind", "x", "y" ], "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$" }, "kind": { "enum": [ "reference", "note", "swatch", "image" ] }, "x": { "type": "integer", "minimum": 0, "maximum": 1600 }, "y": { "type": "integer", "minimum": 0, "maximum": 1000 }, "w": { "type": "integer", "minimum": 120, "maximum": 480 }, "h": { "type": "integer", "minimum": 90, "maximum": 400 }, "text": { "type": "string", "maxLength": 300 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "ref": { "type": "string", "description": "Entry id of a reference card." }, "image": { "type": "string", "description": "Embedded PNG/JPEG/WebP data URI of an image card (under 300 KB)." } } } } } } } }, "report": { "type": "object", "additionalProperties": false, "required": [ "name", "entries", "favorites", "withScreenshots", "withUrls", "types", "platforms", "tags", "moodboardCards", "bytes" ], "properties": { "name": { "type": "string" }, "entries": { "type": "integer" }, "favorites": { "type": "integer" }, "withScreenshots": { "type": "integer" }, "withUrls": { "type": "integer" }, "types": { "type": "object", "additionalProperties": { "type": "integer" } }, "platforms": { "type": "object", "additionalProperties": { "type": "integer" } }, "tags": { "type": "object", "additionalProperties": { "type": "integer" } }, "moodboardCards": { "type": "integer" }, "bytes": { "type": "integer" } } }, "changedEntries": { "type": "integer" }, "projectFile": { "type": "object", "additionalProperties": false, "required": [ "artifactId", "filename", "mime", "bytes", "sha256", "path" ], "properties": { "artifactId": { "type": "string" }, "filename": { "type": "string" }, "mime": { "type": "string" }, "bytes": { "type": "integer" }, "sha256": { "type": "string" }, "path": { "type": "string", "description": "Download path on the same site (valid for about 2 hours)." } } }, "openInApp": { "type": [ "string", "null" ] } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }