4.1 — API overview
On this page
4.1 — API overview
VibeMap exposes a REST API for everything you can do in the web app: create projects, read your spec, trigger regenerations, and watch tasks complete. Most users never touch it directly — the MCP server wraps it for IDE agents. But if you're building automations, dashboards, or your own integrations, this is where to look.
When to use the API directly
- Pulling spec data into another tool (Linear, Notion, your own dashboards)
- Automating project creation from an upstream source (a CRM, a sales-call transcriber, etc.)
- Custom CI workflows that need finer control than the MCP server gives
- Building a custom client UI on top of VibeMap
If you just want your IDE agent to work through a backlog, skip ahead to the MCP server — it's a much friendlier interface.
Base URL
| Environment | URL |
|---|---|
| Production | https://vibemap.ai |
Authentication
All API requests require an API key (we call them Personal Access Tokens, PATs). Generate one from the Account → API Keys screen in the web app.
Pass it in the Authorization header:
curl -H "Authorization: Bearer vm_your_token_here" \
https://vibemap.ai/api/crud/projects
Treat the key like a password. Anyone with it can read and write to all your projects.
Response format
All responses are JSON.
Success:
{
"data": [{ "id": "uuid", "name": "My Project" }]
}
Error:
{
"error": "Project not found"
}
API groups
| Group | Base Path | What it covers |
|---|---|---|
| CRUD | /api/crud/ | Read/write for every entity type (projects, features, user stories, ACs, personas, pages) |
| Projects | /api/project/ | Project-level config and bulk operations |
| Generation | /api/llm-tasks/ | Trigger AI generation tasks |
| Schema | /api/schema/ | Database schema operations |
| Billing | /api/billing/ | Subscription and usage |
| Progress | /api/progress/ | Poll for in-flight task status |
HTTP status codes
Success
| Code | Meaning |
|---|---|
200 OK | Request succeeded |
201 Created | Resource created |
204 No Content | Request succeeded with no body (e.g. delete) |
Client errors
| Code | Meaning |
|---|---|
400 Bad Request | Validation error — check the request body or query params |
401 Unauthorized | Missing or invalid API key |
403 Forbidden | Authenticated but insufficient permissions (often a tier-gated endpoint) |
404 Not Found | Resource doesn't exist or isn't accessible by your key |
429 Too Many Requests | Rate limit hit — back off and retry |
Server errors
| Code | Meaning |
|---|---|
500 Internal Server Error | Unexpected server error — open a support ticket if it persists |
Rate limiting
API requests are rate-limited per user. When you get a 429, respect the Retry-After header before retrying. Typical limits sit well above interactive use; you'll only hit them if you're polling tightly in a script.
Conventions
- All IDs are UUIDs.
- Timestamps are ISO 8601 strings in UTC.
- Request bodies use
Content-Type: application/json. - Query parameters are camelCase (
projectId,featureId). - List endpoints support filtering via query parameters — see 4.2.
Where to go next
- Read/write entities → 4.2 — CRUD endpoints
- Trigger AI generation → 4.3 — Generation endpoints