REST API

The REST surface is read-only and backed by the same D1/R2 fact store as MCP.

Base URLs

https://mcp.aiworkflowmcp.com
https://api.aiworkflowmcp.com

Both hostnames route to the MCP/API Worker. Use mcp.aiworkflowmcp.com for MCP clients and direct REST examples.

Authentication

Public read calls work without a key. Authenticated calls should send:

Authorization: Bearer ${AIWORKFLOWMCP_API_KEY}

x-api-key is accepted for compatibility, but bearer auth is preferred.

Search

GET /v1/search?q=...&type=DOC&fresh_only=true&include_markdown=false&limit=10

Parameters:

• q: required search query.
• type: DOC, MCP_SERVER, MODEL, SKILL, TOOL, or TUTORIAL.
• fresh_only: optional boolean. Reject stale facts when true.
• include_markdown: optional boolean. Loads full Markdown from R2 for document results.
• limit: optional integer. Default 10, maximum 50.

Example:

curl -fsS \
  "https://mcp.aiworkflowmcp.com/v1/search?type=DOC&q=claude%20code&limit=1"

Catalog Lists

GET /v1/models/list?limit=500&offset=0
GET /v1/tools/list?limit=200&offset=0
GET /v1/skills/list?limit=500&offset=0
GET /v1/tutorials/list?limit=200&offset=0
GET /v1/mcp-servers/list?limit=200&offset=0

List responses include limit, offset, total, and a typed collection key such as models, tools, or skills.

curl -fsS "https://mcp.aiworkflowmcp.com/v1/models/list?limit=3"
curl -fsS "https://mcp.aiworkflowmcp.com/v1/tools/list?limit=3"

Catalog Details

GET /v1/models/:id
GET /v1/tools/:id
GET /v1/skills/:id
GET /v1/mcp-servers/:id

Detail responses include the typed item, evidence, and related empty arrays reserved for richer joins.

curl -fsS "https://mcp.aiworkflowmcp.com/v1/models/gpt-5"
curl -fsS "https://mcp.aiworkflowmcp.com/v1/tools/claude-code"

Frameworks

GET /v1/frameworks/search?q=...&domain=...&include_candidates=false&include_prompt=false&limit=8
GET /v1/frameworks/route?q=...&domain=...&include_candidates=false
GET /v1/frameworks/list?limit=25&offset=0&include_candidates=false
GET /v1/frameworks/:id?include_prompt=false

Examples:

curl -fsS "https://api.aiworkflowmcp.com/v1/sources/status"
curl -fsS "https://api.aiworkflowmcp.com/v1/frameworks/search?q=riskiest%20assumption%20test&limit=3"
curl -fsS "https://api.aiworkflowmcp.com/v1/frameworks/route?q=preflight%20risky%20launch%20decision"

Health And Sources

GET /health
GET /v1/sources/status

/health is the high-level readiness signal. /v1/sources/status is the source-level operations view.

curl -fsS https://mcp.aiworkflowmcp.com/health
curl -fsS https://api.aiworkflowmcp.com/v1/sources/status

Response Fields

Catalog rows expose:

• id
• display_name or title
• vendor
• status
• trust_tier
• source_url
• evidence_key
• last_synced_at
• last_verified_at
• stale
• type-specific fields such as model prices, context length, capabilities, or supported models

Evidence objects expose:

• source_url
• key
• content_hash
• last_synced_at
• stale

Error Statuses

• 400: invalid query, invalid type, missing q, invalid JSON-RPC payload.
• 401: invalid, revoked, malformed, or expired API key.
• 404: unknown detail id or JSON-RPC method.
• 429: per-minute rate limit exceeded.
• 500: unexpected source, D1, R2, or Worker failure.

See Errors for concrete response bodies.