Section 2: API Reference

Welcome to the VibeMap Developer API. Our API is designed to allow developers to programmatically interact with VibeMap's core project management entities, enabling custom integrations, automation, and data synchronization.

Base URL

All API requests should be made to the following base URL:

https://vibemap.ai/api

For local development, use:

http://localhost:3000/api

Authentication

VibeMap uses Personal Access Tokens for authentication. You can also use Supabase JWT tokens if you are integrating from a web client.

Personal Access Tokens (Recommended for Servers)

To authenticate using a Personal Access Token, include it in the Authorization header as a Bearer token:

Authorization: Bearer vm_your_token_here

Tokens start with the vm_ prefix. See Obtaining an API Key for details on how to generate one.

Supabase JWT (For Web Clients)

If you are building a custom frontend, you can use the standard Supabase JWT token:

Authorization: Bearer your_supabase_jwt_here

Response Formats

All responses are returned in JSON format.

Success Responses

Successful requests will typically return a 200 OK or 201 Created status code along with the requested data.

Error Responses

In case of an error, the API will return a non-200 status code and a JSON object describing the error:

{
  "error": "Error message description",
  "details": { ... }
}

Common Status Codes

Status Code	Description
200 OK	The request was successful.
201 Created	The resource was successfully created.
207 Multi-Status	Used for batch operations where some items succeeded and others failed.
400 Bad Request	The request was invalid or missing required parameters.
401 Unauthorized	Authentication failed or was not provided.
403 Forbidden	You do not have permission to access the resource.
404 Not Found	The requested resource could not be found.
500 Internal Server Error	An unexpected error occurred on our server.

Content Type

For all POST and PUT requests, ensure you set the Content-Type header to application/json:

Content-Type: application/json