Base URL: https://api.yourdomain.com (production) or http://localhost:3000 (dev)
All authenticated endpoints require JWT in Authorization header:
Authorization: Bearer <jwt_token>
{
"data": { ... },
"message": "Success message (optional)"
}{
"error": "Error message",
"code": "ERROR_CODE",
"details": {}
}Register a new user.
Request:
{
"email": "user@example.com",
"password": "securepassword123"
}Response (201):
{
"user": {
"id": "uuid",
"email": "user@example.com"
},
"token": "jwt_token_here",
"refreshToken": "refresh_token_here"
}Errors:
- 400: Validation error (invalid email, weak password)
- 409: User already exists
Login existing user.
Request:
{
"email": "user@example.com",
"password": "securepassword123"
}Response (200):
{
"user": {
"id": "uuid",
"email": "user@example.com"
},
"token": "jwt_token_here",
"refreshToken": "refresh_token_here"
}Errors:
- 401: Invalid credentials
Get current user info.
Headers: Authorization: Bearer <token>
Response (200):
{
"user": {
"id": "uuid",
"email": "user@example.com",
"createdAt": "2024-01-01T00:00:00Z"
}
}Errors:
- 401: Invalid or expired token
Refresh access token using refresh token.
Request:
{
"refreshToken": "refresh_token_here"
}Response (200):
{
"token": "new_jwt_token",
"refreshToken": "new_refresh_token"
}Errors:
- 401: Invalid or expired refresh token
Get all folders for authenticated user.
Headers: Authorization: Bearer <token>
Response (200):
{
"folders": [
{
"id": "uuid",
"userId": "uuid",
"name": "Work",
"parentId": null,
"isPinned": false,
"position": 0,
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z"
},
{
"id": "uuid",
"userId": "uuid",
"name": "Projects",
"parentId": "uuid",
"isPinned": false,
"position": 0,
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z"
}
]
}Create a new folder.
Headers: Authorization: Bearer <token>
Request:
{
"name": "New Folder",
"parentId": null,
"isPinned": false
}Response (201):
{
"folder": {
"id": "uuid",
"userId": "uuid",
"name": "New Folder",
"parentId": null,
"isPinned": false,
"position": 0,
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z"
}
}Errors:
- 400: Validation error (missing name, invalid parentId)
Get specific folder.
Headers: Authorization: Bearer <token>
Response (200):
{
"folder": {
"id": "uuid",
"userId": "uuid",
"name": "Folder Name",
"parentId": null,
"isPinned": false,
"position": 0,
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z"
}
}Errors:
- 404: Folder not found or doesn't belong to user
Update folder.
Headers: Authorization: Bearer <token>
Request:
{
"name": "Updated Name",
"isPinned": true,
"parentId": "uuid"
}Response (200):
{
"folder": {
"id": "uuid",
"userId": "uuid",
"name": "Updated Name",
"parentId": "uuid",
"isPinned": true,
"position": 0,
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T01:00:00Z"
}
}Errors:
- 404: Folder not found
- 400: Invalid data (circular parent reference)
Delete folder (and optionally its contents).
Headers: Authorization: Bearer <token>
Query Params:
cascade=true- Delete all subfolders and conversations (default: false)
Response (204): No content
Errors:
- 404: Folder not found
- 409: Folder has children (if cascade=false)
Get all prompts for authenticated user.
Headers: Authorization: Bearer <token>
Query Params:
category- Filter by categoryfavorite- Filter favorites only (true/false)search- Search in title/content
Response (200):
{
"prompts": [
{
"id": "uuid",
"userId": "uuid",
"title": "Explain Like I'm 5",
"content": "Explain the following in simple terms: {{TEXT}}",
"category": "Education",
"isFavorite": false,
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z"
}
]
}Create new prompt.
Headers: Authorization: Bearer <token>
Request:
{
"title": "Code Reviewer",
"content": "Review this code and suggest improvements: {{CODE}}",
"category": "Programming",
"isFavorite": false
}Response (201):
{
"prompt": {
"id": "uuid",
"userId": "uuid",
"title": "Code Reviewer",
"content": "Review this code and suggest improvements: {{CODE}}",
"category": "Programming",
"isFavorite": false,
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z"
}
}Errors:
- 400: Validation error (missing title/content)
Get specific prompt.
Headers: Authorization: Bearer <token>
Response (200):
{
"prompt": {
"id": "uuid",
"userId": "uuid",
"title": "Code Reviewer",
"content": "Review this code: {{CODE}}",
"category": "Programming",
"isFavorite": false,
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z"
}
}Errors:
- 404: Prompt not found
Update prompt.
Headers: Authorization: Bearer <token>
Request:
{
"title": "Updated Title",
"content": "Updated content",
"isFavorite": true
}Response (200):
{
"prompt": {
"id": "uuid",
"userId": "uuid",
"title": "Updated Title",
"content": "Updated content",
"category": "Programming",
"isFavorite": true,
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T01:00:00Z"
}
}Delete prompt.
Headers: Authorization: Bearer <token>
Response (204): No content
Errors:
- 404: Prompt not found
Get all chains for authenticated user.
Headers: Authorization: Bearer <token>
Response (200):
{
"chains": [
{
"id": "uuid",
"userId": "uuid",
"name": "Blog Post Generator",
"description": "Generates a complete blog post from a topic",
"steps": [
{
"id": "uuid",
"chainId": "uuid",
"promptId": "uuid",
"promptText": "Generate 5 blog post titles about: {{TOPIC}}",
"position": 0,
"outputVariable": "TITLES"
},
{
"id": "uuid",
"chainId": "uuid",
"promptId": null,
"promptText": "Write an outline for: {{TITLES[0]}}",
"position": 1,
"outputVariable": "OUTLINE"
}
],
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z"
}
]
}Create new chain.
Headers: Authorization: Bearer <token>
Request:
{
"name": "Research Assistant",
"description": "Helps research a topic",
"steps": [
{
"promptText": "What are the key aspects of {{TOPIC}}?",
"position": 0,
"outputVariable": "ASPECTS"
},
{
"promptText": "Explain {{ASPECTS}} in detail",
"position": 1
}
]
}Response (201):
{
"chain": {
"id": "uuid",
"userId": "uuid",
"name": "Research Assistant",
"description": "Helps research a topic",
"steps": [...],
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z"
}
}Get specific chain.
Headers: Authorization: Bearer <token>
Response (200):
{
"chain": {
"id": "uuid",
"name": "Chain Name",
"description": "Description",
"steps": [...],
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z"
}
}Errors:
- 404: Chain not found
Update chain.
Headers: Authorization: Bearer <token>
Request:
{
"name": "Updated Name",
"description": "Updated description",
"steps": [...]
}Response (200):
{
"chain": {
"id": "uuid",
"name": "Updated Name",
"steps": [...],
"updatedAt": "2024-01-01T01:00:00Z"
}
}Delete chain.
Headers: Authorization: Bearer <token>
Response (204): No content
Pull all user data (full sync).
Headers: Authorization: Bearer <token>
Query Params:
since- ISO timestamp, only return items updated since this time
Response (200):
{
"data": {
"folders": [...],
"prompts": [...],
"chains": [...],
"conversations": [...],
"bookmarks": [...]
},
"timestamp": "2024-01-01T00:00:00Z"
}Push local changes to server.
Headers: Authorization: Bearer <token>
Request:
{
"folders": [...],
"prompts": [...],
"chains": [...],
"lastSyncTimestamp": "2024-01-01T00:00:00Z"
}Response (200):
{
"success": true,
"conflicts": [],
"timestamp": "2024-01-01T01:00:00Z"
}- 200 OK - Request succeeded
- 201 Created - Resource created successfully
- 204 No Content - Request succeeded with no response body
- 400 Bad Request - Invalid request data
- 401 Unauthorized - Missing or invalid authentication
- 403 Forbidden - Insufficient permissions
- 404 Not Found - Resource not found
- 409 Conflict - Resource conflict (e.g., duplicate)
- 500 Internal Server Error - Server error
- Limit: 100 requests per minute per user
- Headers:
X-RateLimit-Limit: Maximum requests allowedX-RateLimit-Remaining: Remaining requestsX-RateLimit-Reset: Time when limit resets (Unix timestamp)
API version is included in the base URL: /v1/
Example: https://api.yourdomain.com/v1/folders