REST API v1 — Live

Build on Color Idea

The official developer API for Color Idea's visual documentation platform. Programmatically access projects, media archives, reports, and team data.

Explore Endpoints View Examples
api.coloridea.co
$ curl -X GET https://api.coloridea.co/api/v1/projects \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json"

# Response
{
  "success": true,
  "data": [ /* project objects */ ],
  "total": 47
}
2.7M+
Archived Images
50+
Active Projects
600+
Visual Reports
8+
Years of Data
Base URL
https://api.coloridea.co/api/v1
// endpoints

API Reference

All endpoints follow RESTful conventions and return JSON responses.

POST /auth/login
Authenticate a user and receive a signed JWT access token.
Auth
POST /auth/logout
Invalidate the current session and clear the access token.
Auth
GET /auth/me
Returns the authenticated user's profile and permissions.
Auth
GET /projects
List all projects with pagination, filtering, and sorting support.
Projects
GET /projects/:id
Retrieve a single project by ID including all metadata and stats.
Projects
POST /projects
Create a new documentation project with category, location, and timeline.
Projects
PUT /projects/:id
Update project details, status, or configuration settings.
Projects
DELETE /projects/:id
Soft-delete a project. Archived media is retained for 30 days.
Projects
GET /projects/:id/media
Paginated list of all archived images and videos for a project.
Media
POST /projects/:id/media
Upload new media files. Supports multipart/form-data with auto-compression.
Media
DELETE /media/:mediaId
Permanently remove a media asset from the cloud archive.
Media
GET /reports
Retrieve all visual progress reports with date-range filtering.
Reports
POST /reports
Generate a new periodic visual report for a specific project.
Reports
GET /team
List all team members with roles and assigned projects
Team
POST /team
Invite a new team member and assign permissions and project access.
Team
PUT /team/:memberId
Update a team member's role, permissions, or project assignments.
Team
// authentication

How Auth Works

Color Idea API uses JWT Bearer tokens. Obtain a token via login, then include it in every request header.

🔑

Bearer Token

After logging in, you receive a signed JWT. Pass it in the Authorization header for all protected routes.

Authorization: Bearer eyJhbGci...
🔐

Login Request

Send your credentials to the login endpoint to receive an access token and user profile.

POST /api/v1/auth/login
{
  "email": "you@example.com",
  "password": "••••••••"
}
// examples

Request & Response

A full example of fetching a project's media archive with authentication.

GET /projects/64fa.../media Request
Headers:
 Authorization: Bearer eyJhbGci...
 Accept: application/json

Query params:
 page=1
 limit=20
 type=image
Response 200 OK
{
 "success": true,
 "data": [
  {
   "_id": "64fb...",
   "url": "https://cdn...",
   "type": "image",
   "capturedAt": "2025-03-01"
  }
 ],
 "page": 1,
 "total": 2700000
}
// built for scale

Platform Features

⚡

High Performance

Node.js + Express backend optimized for large media payloads with streaming support and Redis caching.

☁️

Cloud Archive

All media is stored in a secure, geographically redundant cloud archive with CDN delivery globally.

📊

Real-time Reports

Visual progress reports generated on-demand or on schedule, ready for stakeholder presentation.

🔒

Secure by Default

JWT authentication, HTTPS-only, rate limiting, and role-based access control on every endpoint.

📦

Pagination & Filtering

All list endpoints support cursor or offset pagination, date-range queries, and field-level filtering.

🌐

Bilingual Support

API responses support both Arabic and English field localization via the Accept-Language header.