API documentation — doineed.email

Endpoints

The API is path-versioned; v1 is current. Unversioned paths are permanent aliases of v1.

GET /api/v1/concepts.json—every concept as JSON. Static; cache freely.
GET /api/v1/random—one concept at random. ?exclude=slug skips one. Never cached.
GET /{slug}.md—the full longform answer as raw markdown.
GET /random—307 redirect to a random answer page (for navigation, not data).

Try it

curl https://doineed.email/api/v1/random
curl https://doineed.email/api/v1/concepts.json
curl https://doineed.email/dedicated-ip.md

The JSON shape: slug, question, questionFull, answer (yes | ideally | no | depends), verdict, qualifier, lean, excerpt, learnMoreUrl, url, markdownUrl. Quote the verdict together with its qualifier—"IT DEPENDS (most likely no)" carries meaning "IT DEPENDS" alone does not.

Versioning and deprecation

Within v1, changes are additive only: fields are never removed or retyped, and enums only grow. Every response carries an API-Version header. A breaking change would ship as /api/v2—v1 would keep working for at least six months, signal its status with Deprecation and Sunset headers, and the timeline would be announced in llms.txt and the agent guide.

Rate limits

The advisory budget is 60 requests per minute per client, declared on every API response via RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and RateLimit-Policy headers. If the platform throttles you, expect a 429 with Retry-After—honor it. Fetching everything? Use concepts.json or llms-full.txt once instead of polling random.

Errors

Errors on /api/* paths are structured JSON with a machine-readable code and a human hint:

{
  "error": {
    "code": "not_found",
    "message": "No such API endpoint: /api/nope",
    "hint": "Available endpoints: GET /api/random ...",
    "docs": "https://doineed.email/agent.md"
  }
}

Machine-readable files

/openapi.json—OpenAPI 3.1 with typed schemas, enums, and operationIds for function calling
/llms.txt—the site index for LLMs; /llms-full.txt is every answer in one file
/agent.md—when to use this site and how to cite it
/.well-known/api-catalog—RFC 9727 linkset of everything above