REST API Reference
HTTP endpoints for programmatic access to Metapad models and data.
/api/v1/models/{model_id}/nodes/batchPro+Batch Get Nodes
Fetch multiple nodes by ID in a single request. More efficient than multiple single-node calls. Accepts UUIDs and auto-IDs (e.g. REQ-42).
/api/v1/models/{model_id}/assets/{asset_id}/filePro+Delete Asset File
Detach the file from an asset. The asset element itself stays in the model — only the attached binary is removed from object storage and the file metadata cleared. Use this to replace a file (delete, then upload).
/api/v1/models/{model_id}/assets/{asset_id}/downloadPro+Download Asset
Download the file attached to an asset. Returns a 302 redirect to a short-lived presigned S3 URL — clients must follow redirects to fetch the binary. Returns 404 with code 'no_file' if the asset has no file attached.
/api/v1/models/{model_id}/exportPro+Export Model
Export the full model as a downloadable JSON file. Identical payload to Get Model but served with Content-Disposition: attachment for direct download.
/api/v1/models/{model_id}/assets/{asset_id}Pro+Get Asset Metadata
Fetch metadata for a single asset (label, description, filename, content type, size, tags, timestamps). Does not return the file binary — use Download Asset for that.
/api/v1/models/{model_id}/metadataPro+Get Metadata
Lightweight model metadata: name, description, language list, node/relationship counts, and last updated timestamp. Does not return model content.
/api/v1/models/{model_id}Pro+Get Model
Returns the full model data including metamodel (M2 types) and all node/relationship instances. Equivalent to a full JSON export.
/api/v1/models/{model_id}/nodes/{node_id}Pro+Get Node
Full details for a single node including all properties and optionally its incoming and outgoing relationships. Accepts UUID or auto-ID (e.g. REQ-42).
/api/v1/models/{model_id}/schemaPro+Get Schema
Returns the metamodel (M2 schema): all node types, relationship types, their properties, and allowed connection patterns. Equivalent to the MCP get_metamodel tool.
/api/v1/models/{model_id}/assetsPro+List Assets
List all assets (file attachments) in a model. Returns metadata only — file binaries are fetched separately via Download Asset. Useful for browsing what's attached to a model.
/api/v1/models/{model_id}/foldersPro+List Folders
Returns the complete folder hierarchy for the model. Folders are optional organizational containers for nodes.
/api/v1/models/{model_id}/nodesPro+List Nodes
Paginated list of node instances with filtering by type, folder, and full-text search. Returns a page of node summaries plus x-total-count header for pagination.
/api/v1/models/{model_id}/relationshipsPro+List Relationships
Paginated list of relationships with filtering by type, source, or target node. Returns x-total-count header for pagination.
/mcp/{model_id}Pro+MCP Tool Call
The MCP HTTP transport. A single JSON-RPC 2.0 endpoint that dispatches to all of Metapad's MCP tools (get_metamodel, search_nodes, create_nodes, etc.) — set 'method' to the JSON-RPC method ('tools/call', 'tools/list', 'initialize', 'ping') and put the tool name + arguments in 'params'. This is the same endpoint that Claude Desktop, Claude Code, and other MCP clients connect to — use it directly from scripts and CI when no interactive OAuth login is possible. Distinct from the REST API v1 endpoints under /api/v1/..., which expose individual resources as conventional REST.
/api/v1/models/{model_id}/assetsPro+Upload Asset
Create a new asset in a model and attach a file in a single multipart upload. Broadcasts AssetAdded + AssetFileAttached collaboration operations — browser users see the new asset in real-time. 100 MB max.