Weftd back to homepage

Weftd API & MCP server

Weftd's own AI Presence can be reached by programs as well as people: an HTTP API that answers questions about Weftd, and an MCP server for AI assistants. Both are public and need no key.

At a glance

SurfaceURLDescription
HTTP APIhttps://weftd.weftd.space/api/v1Ask a question in natural language, get JSON or plain text. weftd.com/api/v1 redirects here; /api is an alias of the current version.
OpenAPIhttps://www.weftd.com/openapi.jsonOpenAPI 3.1 description of the HTTP API.
MCP serverhttps://weftd.weftd.space/mcpStreamable HTTP endpoint for AI assistants (Claude, ChatGPT, Cursor…).

Authentication

None for Weftd's public space: call the API and connect the MCP server without a key or an account.

The same API exists for every AI Presence built on Weftd. A private space requires an API key, created in that space's Developer API settings and sent as Authorization: Bearer <key> or X-API-Key: <key>.

Endpoint: GET /api/v1

Ask Weftd a question. POST /api/v1 takes the same fields as a JSON body.

ParameterRequiredValuesDescription
queryyestextThe question, in natural language.
modenocontext (default), searchcontext: an AI-written answer with its sources. search: the knowledge entries ranked by relevance, without AI.
typenotxt (default), jsonPlain text or structured JSON.
limitno1–50, default 4Maximum number of knowledge entries used or returned.

Example requests

Ranked entries, as JSON
curl "https://weftd.weftd.space/api/v1?query=How%20much%20does%20Weftd%20cost%3F&mode=search&type=json&limit=2"
An answer written by AI, with its sources
curl -X POST https://weftd.weftd.space/api/v1 \
  -H "Content-Type: application/json" \
  -d '{"query": "What is an AI Presence?", "mode": "context", "type": "json"}'
Response (mode=search, type=json)
{
  "results": [
    { "id": "…", "title": "Weftd Plans and Pricing: Free to Enterprise", "snippet": "Weftd starts for free…", "relevance": 0.011 }
  ],
  "total": 1,
  "query": "How much does Weftd cost?"
}

Errors and rate limits

Errors are JSON, with an error field and, when useful, a code and a message: 400 for a missing query or a limit outside 1–50, 403 for a private space without a valid key, 404 for an unknown path, 429 when the rate limit is reached.

Requests are rate-limited per client IP. Every response carries the IETF RateLimit header fields: RateLimit-Policy gives the quota and its window, RateLimit the requests left and the seconds until the window resets. A 429 also carries Retry-After: wait that many seconds before retrying.

Versioning and deprecation

The version is in the path: /api/v1. Changes that keep existing requests working (a new optional parameter, a new response field) ship within v1. A breaking change ships as a new path, /api/v2, and v1 keeps answering.

A version being retired says so on every response: a Deprecation header (RFC 9745), a Sunset header (RFC 8594) with its retirement date, at least six months ahead, and a Link header with rel="successor-version" pointing at its replacement. The OpenAPI document states the same policy in x-api-lifecycle.

Connect the MCP server

Add https://weftd.weftd.space/mcp to your assistant as a custom connector. It lets the assistant search Weftd's knowledge and send a message to the team.

Claude Code
claude mcp add --transport http weftd https://weftd.weftd.space/mcp
Any MCP client (JSON configuration)
{
  "mcpServers": {
    "weftd": { "type": "http", "url": "https://weftd.weftd.space/mcp" }
  }
}

Machine-readable files