Base URL
https://rcpixel.com/api/All API requests use this base URL. Responses are returned in JSON format. All timestamps use ISO 8601 format in UTC.
Authentication
The RCPIXEL API uses JSON Web Tokens (JWT) for authentication. Obtain an access token by sending your credentials to the token endpoint, then include it in the Authorization header of subsequent requests.
Step 1: Obtain Access Token
Send a POST request with your username and password to receive an access and refresh token pair.
curl -X POST "https://rcpixel.com/api/token/" \
-H "Content-Type: application/json" \
-d '{
"username": "your_username",
"password": "your_password"
}'{
"access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}Step 2: Use the Access Token
Include the access token in the Authorization header with the Bearer prefix.
curl -X GET "https://rcpixel.com/api/tenants/" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json"Step 3: Refresh Expired Tokens
Access tokens expire after 60 minutes. Use the refresh token to obtain a new access token without re-authenticating.
curl -X POST "https://rcpixel.com/api/token/refresh/" \
-H "Content-Type: application/json" \
-d '{
"refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}'{
"access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}Security Note: Keep your tokens secure. Do not expose them in client-side code or public repositories. Access tokens expire after 60 minutes. Refresh tokens expire after 24 hours.
Tenants API
Manage multi-tenant organizations across industry verticals. Each tenant represents a client organization with its own configuration, branding, and data isolation.
| Method | Endpoint |
|---|---|
| GET | /api/tenants/ List all tenants with pagination |
| POST | /api/tenants/ Create a new tenant organization |
| GET | /api/tenants/:id/ Get tenant details by ID |
| PATCH | /api/tenants/:id/ Update tenant configuration |
| DELETE | /api/tenants/:id/ Delete a tenant and its data |
| POST | /api/tenants/:id/generate_ui/ Generate AI-powered UI for tenant |
Example Request & Response▼
curl -X GET "https://rcpixel.com/api/tenants/" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json"{
"count": 3,
"next": null,
"previous": null,
"results": [
{
"id": 1,
"name": "Acme Real Estate",
"slug": "acme-real-estate",
"industry": "real_estate",
"is_active": true,
"created_at": "2025-01-15T10:30:00Z"
}
]
}Images API
Upload, manage, label, and search images. Includes semantic search powered by embeddings and a human-in-the-loop labeling system.
| Method | Endpoint |
|---|---|
| GET | /api/images/ List images with filtering and pagination |
| POST | /api/images/ Upload a new image |
| GET | /api/images/:id/ Get image details and metadata |
| PATCH | /api/images/:id/ Update image metadata or labels |
| GET | /api/images/search/ Semantic search images by text query |
| POST | /api/images/:id/label/ Apply labels to an image |
| GET | /api/images/export_dataset/ Export labeled dataset (JSON or CSV) |
Example Request & Response▼
curl -X GET "https://rcpixel.com/api/images/search/?q=modern+kitchen" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json"{
"count": 12,
"results": [
{
"id": 42,
"filename": "kitchen-renovation-01.jpg",
"path": "/media/images/kitchen-renovation-01.jpg",
"labels": ["kitchen", "modern", "renovation"],
"similarity_score": 0.92,
"created_at": "2025-02-10T14:22:00Z"
}
]
}Projects API
Create and manage projects with full lifecycle tracking. Projects support custom actions for status transitions and workflow management.
| Method | Endpoint |
|---|---|
| GET | /api/projects/ List all projects with filtering |
| POST | /api/projects/ Create a new project |
| GET | /api/projects/:id/ Get project details |
| PATCH | /api/projects/:id/ Update project fields |
| POST | /api/projects/:id/start/ Transition project to active status |
| POST | /api/projects/:id/complete/ Mark project as completed |
Example Request & Response▼
curl -X POST "https://rcpixel.com/api/projects/" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"name": "Website Redesign",
"tenant": 1,
"description": "Complete website redesign for Q2",
"status": "planning"
}'{
"id": 15,
"name": "Website Redesign",
"tenant": 1,
"description": "Complete website redesign for Q2",
"status": "planning",
"created_at": "2025-03-01T09:00:00Z",
"updated_at": "2025-03-01T09:00:00Z"
}Tasks API
Manage tasks within projects. Supports assignment, priority levels, due dates, and integration with the BEADS task tracking system.
| Method | Endpoint |
|---|---|
| GET | /api/tasks/ List tasks with filtering by project, status, assignee |
| POST | /api/tasks/ Create a new task |
| GET | /api/tasks/:id/ Get task details |
| PATCH | /api/tasks/:id/ Update task fields |
| DELETE | /api/tasks/:id/ Delete a task |
Example Request & Response▼
curl -X GET "https://rcpixel.com/api/tasks/?project=15&status=in_progress" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json"{
"count": 5,
"results": [
{
"id": 101,
"title": "Design homepage mockup",
"project": 15,
"status": "in_progress",
"priority": "high",
"assignee": "designer@acme.com",
"due_date": "2025-03-15",
"created_at": "2025-03-02T11:00:00Z"
}
]
}Analytics API
Access cross-tenant insights, reporting data, and platform-wide analytics. Aggregate metrics across projects, tasks, and agent activities.
| Method | Endpoint |
|---|---|
| GET | /api/analytics/ Get platform-wide analytics summary |
| GET | /api/analytics/tenants/ Per-tenant usage and activity metrics |
| GET | /api/analytics/projects/ Project completion and performance stats |
| GET | /api/analytics/agents/ AI agent execution metrics |
Example Request & Response▼
curl -X GET "https://rcpixel.com/api/analytics/?period=30d" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json"{
"period": "30d",
"total_projects": 47,
"active_tenants": 12,
"tasks_completed": 234,
"agent_executions": 1089,
"avg_completion_time_hours": 18.5
}Search API
Full-text and semantic search across platform resources. Search images by visual similarity, and projects or tasks by keyword.
| Method | Endpoint |
|---|---|
| GET | /api/search/ Global search across all resource types |
| GET | /api/search/images/ Search images with semantic ranking |
| GET | /api/search/projects/ Search projects by name or description |
| GET | /api/search/tasks/ Search tasks by title or content |
Example Request & Response▼
curl -X GET "https://rcpixel.com/api/search/?q=kitchen+design&type=images" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json"{
"query": "kitchen design",
"type": "images",
"total": 8,
"results": [
{
"id": 42,
"resource_type": "image",
"title": "kitchen-renovation-01.jpg",
"relevance_score": 0.95,
"url": "/api/images/42/"
}
]
}Rate Limits
API requests are rate limited to ensure fair usage and platform stability. Rate limits are applied per API key and reset every minute.
Free Tier
100
requests / minute
Pro Tier
1,000
requests / minute
Enterprise
Custom
Contact sales
Rate limit information is included in every API response via HTTP headers:
| Header | Description |
|---|---|
| X-RateLimit-Limit | Maximum requests allowed per minute |
| X-RateLimit-Remaining | Remaining requests in current window |
| X-RateLimit-Reset | Unix timestamp when the rate limit resets |
When you exceed the rate limit, the API returns a 429 Too Many Requests response. Wait until the reset time indicated by the X-RateLimit-Reset header before retrying.
Error Handling
The API uses standard HTTP status codes and returns errors in a consistent JSON format.
Error Response Format
{
"detail": "Authentication credentials were not provided.",
"code": "not_authenticated"
}HTTP Status Codes
| Code | Description |
|---|---|
| 200 | OK - Request succeeded |
| 201 | Created - Resource created successfully |
| 204 | No Content - Successful deletion |
| 400 | Bad Request - Invalid parameters or request body |
| 401 | Unauthorized - Missing or invalid authentication token |
| 403 | Forbidden - Insufficient permissions for this resource |
| 404 | Not Found - Resource does not exist |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error - Unexpected server error |
Webhooks
RCPIXEL can send webhook notifications when events occur. Configure webhook endpoints in your dashboard settings to receive real-time updates.
Available Events
| Event | Description |
|---|---|
image.uploaded | A new image has been uploaded |
image.labeled | An image has been labeled |
project.created | A new project was created |
project.completed | A project was marked as completed |
task.assigned | A task was assigned to a user |
task.completed | A task was marked as completed |
agent.completed | An AI agent task has completed |
tenant.created | A new tenant was created |
Webhook Payload
{
"event": "image.labeled",
"timestamp": "2025-03-15T14:30:00Z",
"data": {
"id": 42,
"filename": "kitchen-renovation-01.jpg",
"labels": ["kitchen", "modern", "renovation"],
"labeled_by": "user@example.com"
}
}SDKs & Libraries
Use our official SDKs for easier integration. SDKs handle authentication, token refresh, and provide typed interfaces for all API endpoints.
Python SDK
Official Python client library with async support.
pip install rcpixelfrom rcpixel import RCPixelClient
client = RCPixelClient(
username="your_username",
password="your_password"
)
# List tenants
tenants = client.tenants.list()
# Search images
results = client.images.search("modern kitchen")Coming soon - check back for release updates.
TypeScript SDK
Official TypeScript/JavaScript client with full type safety.
npm install @rcpixel/sdkimport { RCPixelClient } from '@rcpixel/sdk';
const client = new RCPixelClient({
username: 'your_username',
password: 'your_password',
});
// List tenants
const tenants = await client.tenants.list();
// Search images
const results = await client.images.search('modern kitchen');Coming soon - check back for release updates.