Projects API Overview
Complete guide to the Projects API for managing projects with CRUD operations
Projects API
The Projects API provides full CRUD functionality for managing projects within your organization. Create, read, update, and delete projects programmatically.
Base URL
/api/projectsAuthentication
All projects endpoints require authentication. Include your session token in the request headers:
Authorization: Bearer <session_token>Endpoints Overview
| Endpoint | Method | Description |
|---|---|---|
/ | GET | List all projects for the authenticated user |
/ | POST | Create a new project |
/:id | GET | Retrieve a specific project by ID |
/:id | PUT | Update a project by ID |
/:id | DELETE | Delete a project by ID |
/check-slug | GET | Check if a project slug is available |
Response Format
All responses follow a consistent JSON structure:
{
"success": true,
"data": { ... },
"message": "Operation completed successfully"
}Error responses:
{
"success": false,
"data": null,
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication required"
}
}List Projects
Retrieve all projects for the authenticated user.
GET /api/projectsQuery Parameters
| Parameter | Type | Description |
|---|---|---|
limit | number | Maximum number of results (default: 20, max: 100) |
offset | number | Number of results to skip (default: 0) |
status | string | Filter by status: active, archived, draft |
Response
{
"success": true,
"data": {
"projects": [
{
"id": "proj_123456789",
"name": "My Awesome Project",
"slug": "my-awesome-project",
"description": "A description of the project",
"status": "active",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z",
"ownerId": "user_987654321",
"organizationId": "org_123456789"
}
],
"pagination": {
"total": 42,
"limit": 20,
"offset": 0,
"hasMore": true
}
},
"message": "Projects retrieved successfully"
}Create Project
Create a new project.
POST /api/projectsRequest Body
{
"name": "My New Project",
"slug": "my-new-project",
"description": "Optional project description",
"status": "active"
}Parameters
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Project name (1-100 characters) |
slug | string | Yes | URL-friendly identifier (unique per organization) |
description | string | No | Project description (max 500 characters) |
status | string | No | Project status: active, archived, draft (default: active) |
Response
{
"success": true,
"data": {
"id": "proj_987654321",
"name": "My New Project",
"slug": "my-new-project",
"description": "Optional project description",
"status": "active",
"createdAt": "2024-02-04T12:00:00Z",
"updatedAt": "2024-02-04T12:00:00Z",
"ownerId": "user_987654321",
"organizationId": "org_123456789"
},
"message": "Project created successfully"
}Get Project
Retrieve a specific project by ID.
GET /api/projects/:idPath Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | Project ID |
Response
{
"success": true,
"data": {
"id": "proj_123456789",
"name": "My Awesome Project",
"slug": "my-awesome-project",
"description": "A description of the project",
"status": "active",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z",
"ownerId": "user_987654321",
"organizationId": "org_123456789"
},
"message": "Project retrieved successfully"
}Update Project
Update an existing project.
PUT /api/projects/:idPath Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | Project ID |
Request Body
{
"name": "Updated Project Name",
"description": "Updated description",
"status": "archived"
}Parameters
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | Project name (1-100 characters) |
slug | string | No | URL-friendly identifier (unique per organization) |
description | string | No | Project description (max 500 characters) |
status | string | No | Project status: active, archived, draft |
Response
{
"success": true,
"data": {
"id": "proj_123456789",
"name": "Updated Project Name",
"slug": "my-awesome-project",
"description": "Updated description",
"status": "archived",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-02-04T12:30:00Z",
"ownerId": "user_987654321",
"organizationId": "org_123456789"
},
"message": "Project updated successfully"
}Delete Project
Delete a project permanently.
DELETE /api/projects/:idPath Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | Project ID |
Response
{
"success": true,
"data": {
"deleted": true,
"id": "proj_123456789"
},
"message": "Project deleted successfully"
}Error Codes
| Code | HTTP Status | Description |
|---|---|---|
UNAUTHORIZED | 401 | Missing or invalid authentication |
FORBIDDEN | 403 | Insufficient permissions to access project |
NOT_FOUND | 404 | Project not found |
BAD_REQUEST | 400 | Invalid request parameters |
CONFLICT | 409 | Slug already exists |
INTERNAL_ERROR | 500 | Server error |
Rate Limits
- 100 requests per minute per user
- 1000 requests per hour per organization
SDK Example
import { createProjectsClient } from '@/lib/projects/client';
const projects = createProjectsClient();
// List all projects
const { projects: allProjects } = await projects.list({ limit: 10 });
// Create a new project
const newProject = await projects.create({
name: 'My New Project',
slug: 'my-new-project',
description: 'Project description'
});
// Update a project
const updated = await projects.update('proj_123456789', {
status: 'archived'
});
// Delete a project
await projects.delete('proj_123456789');