Projects
Create, read, update, and delete monitoring projects.
Projects API
Manage your monitoring projects. Each project represents a brand or product you want to track across AI platforms.
Base URL
All requests to the Projects API use this base URL:
https://aibeam.io/api/v1
Authentication
Include your API key in the Authorization header for all requests:
Authorization: Bearer YOUR_API_KEY
Replace YOUR_API_KEY with your actual API key from the AIBeam dashboard.
Project Object
A project represents a monitoring workspace for tracking a brand across AI platforms.
Fields
| Field | Type | Description |
|---|---|---|
id | uuid | Unique project identifier |
account_id | uuid | Account that owns this project |
name | string | Display name for the project |
brand_name | string | Brand or product name being monitored |
website_url | string | Official website URL |
favicon_url | string | Brand favicon URL (optional) |
description | string | Project description |
target_country | string | Target country (e.g., "US", "GB") |
main_topic | string | Primary topic or category |
settings | object | Configuration object |
settings.platforms | array | Enabled platforms: "chatgpt", "perplexity", "claude", "gemini" |
settings.monitoring_frequency | string | "daily" or "weekly" |
settings.auto_discover_competitors | boolean | Enable automatic competitor discovery |
is_active | boolean | Whether the project is active |
is_paused | boolean | Whether monitoring is paused |
created_at | timestamp | Creation timestamp |
updated_at | timestamp | Last update timestamp |
Example Project Object
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"account_id": "550e8400-e29b-41d4-a716-446655440001",
"name": "Acme Marketing Campaign Q1 2026",
"brand_name": "Acme Corp",
"website_url": "https://acme.com",
"favicon_url": "https://acme.com/favicon.ico",
"description": "Monitor Acme Corp visibility across AI platforms",
"target_country": "US",
"main_topic": "B2B Software",
"settings": {
"platforms": ["chatgpt", "perplexity", "claude"],
"monitoring_frequency": "weekly",
"auto_discover_competitors": true
},
"is_active": true,
"is_paused": false,
"created_at": "2026-03-01T10:30:00Z",
"updated_at": "2026-03-10T14:22:30Z"
}
Endpoints
List Projects
Get all projects in your account.
GET /api/v1/projects
Request
No query parameters or request body required.
Response
Status Code: 200 OK
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"account_id": "550e8400-e29b-41d4-a716-446655440001",
"name": "Acme Marketing Campaign Q1 2026",
"brand_name": "Acme Corp",
"website_url": "https://acme.com",
"favicon_url": "https://acme.com/favicon.ico",
"description": "Monitor Acme Corp visibility across AI platforms",
"target_country": "US",
"main_topic": "B2B Software",
"settings": {
"platforms": ["chatgpt", "perplexity", "claude"],
"monitoring_frequency": "weekly",
"auto_discover_competitors": true
},
"is_active": true,
"is_paused": false,
"created_at": "2026-03-01T10:30:00Z",
"updated_at": "2026-03-10T14:22:30Z"
},
{
"id": "660e8400-e29b-41d4-a716-446655440002",
"account_id": "550e8400-e29b-41d4-a716-446655440001",
"name": "Acme Product Launch",
"brand_name": "Acme Pro",
"website_url": "https://acme.com/pro",
"favicon_url": null,
"description": "Launch campaign for Acme Pro",
"target_country": "US",
"main_topic": "SaaS",
"settings": {
"platforms": ["chatgpt", "perplexity", "claude", "gemini"],
"monitoring_frequency": "weekly",
"auto_discover_competitors": false
},
"is_active": true,
"is_paused": false,
"created_at": "2026-02-15T08:00:00Z",
"updated_at": "2026-03-10T09:15:00Z"
}
]
}
Example Request
curl -X GET "https://aibeam.io/api/v1/projects" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json"
Create Project
Create a new monitoring project.
POST /api/v1/projects
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
brand_name | string | Yes | Brand or product name |
website_url | string | Yes | Official website URL |
description | string | No | Project description |
target_country | string | No | Target country (default: "US") |
main_topic | string | No | Primary topic or category |
Response
Status Code: 201 Created
{
"data": {
"id": "770e8400-e29b-41d4-a716-446655440003",
"account_id": "550e8400-e29b-41d4-a716-446655440001",
"name": "Acme Corp",
"brand_name": "Acme Corp",
"website_url": "https://acme.com",
"favicon_url": null,
"description": "Monitor Acme Corp visibility across AI platforms",
"target_country": "US",
"main_topic": "B2B Software",
"settings": {
"platforms": ["chatgpt", "perplexity"],
"monitoring_frequency": "weekly",
"auto_discover_competitors": false
},
"is_active": true,
"is_paused": false,
"created_at": "2026-03-10T15:00:00Z",
"updated_at": "2026-03-10T15:00:00Z"
}
}
Example Request
curl -X POST "https://aibeam.io/api/v1/projects" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"brand_name": "Acme Corp",
"website_url": "https://acme.com",
"description": "Monitor Acme Corp visibility across AI platforms",
"target_country": "US",
"main_topic": "B2B Software"
}'
Error Responses
Status Code: 422 Unprocessable Entity
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "website_url must be a valid URL"
}
}
Status Code: 500 Internal Server Error
{
"success": false,
"error": {
"code": "INTERNAL_ERROR",
"message": "Failed to create project"
}
}
Get Project
Retrieve a specific project by ID.
GET /api/v1/projects/:projectId
Path Parameters
| Parameter | Type | Description |
|---|---|---|
projectId | uuid | The project ID |
Response
Status Code: 200 OK
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"account_id": "550e8400-e29b-41d4-a716-446655440001",
"name": "Acme Marketing Campaign Q1 2026",
"brand_name": "Acme Corp",
"website_url": "https://acme.com",
"favicon_url": "https://acme.com/favicon.ico",
"description": "Monitor Acme Corp visibility across AI platforms",
"target_country": "US",
"main_topic": "B2B Software",
"settings": {
"platforms": ["chatgpt", "perplexity", "claude"],
"monitoring_frequency": "weekly",
"auto_discover_competitors": true
},
"is_active": true,
"is_paused": false,
"created_at": "2026-03-01T10:30:00Z",
"updated_at": "2026-03-10T14:22:30Z"
}
}
Example Request
curl -X GET "https://aibeam.io/api/v1/projects/550e8400-e29b-41d4-a716-446655440000" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json"
Error Response
Status Code: 404 Not Found
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "Project not found"
}
}
Update Project
Update an existing project.
PATCH /api/v1/projects/:projectId
Path Parameters
| Parameter | Type | Description |
|---|---|---|
projectId | uuid | The project ID |
Request Body
All fields are optional. Include only the fields you want to update.
| Field | Type | Description |
|---|---|---|
brand_name | string | Brand or product name |
website_url | string | Official website URL |
description | string | Project description |
target_country | string | Target country |
main_topic | string | Primary topic |
settings | object | Project settings |
Response
Status Code: 200 OK
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"account_id": "550e8400-e29b-41d4-a716-446655440001",
"name": "Acme Corp",
"brand_name": "Acme Corp",
"website_url": "https://acme.com",
"favicon_url": "https://acme.com/favicon.ico",
"description": "Global monitoring for Acme Corp",
"target_country": "US",
"main_topic": "B2B SaaS",
"settings": {
"platforms": ["chatgpt", "perplexity", "claude"],
"monitoring_frequency": "weekly",
"auto_discover_competitors": true
},
"is_active": true,
"is_paused": false,
"created_at": "2026-03-01T10:30:00Z",
"updated_at": "2026-03-10T16:45:30Z"
}
}
Example Request
curl -X PATCH "https://aibeam.io/api/v1/projects/550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "Global monitoring for Acme Corp",
"main_topic": "B2B SaaS"
}'
Error Response
Status Code: 422 Unprocessable Entity
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "website_url must be a valid URL"
}
}
Delete Project
Archive a project so new monitoring stops. Retained response history remains available for reporting and audit evidence.
DELETE /api/v1/projects/:projectId
Path Parameters
| Parameter | Type | Description |
|---|---|---|
projectId | uuid | The project ID |
Response
Status Code: 200 OK
{
"data": {
"deleted": true
}
}
Example Request
curl -X DELETE "https://aibeam.io/api/v1/projects/550e8400-e29b-41d4-a716-446655440000" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json"
Error Response
Status Code: 404 Not Found
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "Project not found"
}
}
Error Codes
| Code | HTTP Status | Description |
|---|---|---|
VALIDATION_ERROR | 422 | Invalid request parameters or body |
UNAUTHORIZED | 401 | Missing or invalid API key |
FORBIDDEN | 403 | You do not have access to this resource |
NOT_FOUND | 404 | Project does not exist |
RATE_LIMIT_EXCEEDED | 429 | Too many requests; please try again later |
AIBEAM_KILL_SWITCH_ACTIVE | 503 | Project writes are temporarily read-only |
INTERNAL_ERROR | 500 | Internal server error |
Rate Limiting
All API requests are rate limited to prevent abuse:
| Tier | Requests/minute | Requests/day |
|---|---|---|
| Professional | 60 | 500 |
| Agency | 200 | 5,000 |
Rate limit information is included in response headers:
X-RateLimit-Limit: 60 X-RateLimit-Remaining: 42 X-RateLimit-Reset: 1678531200
When rate limited, the API returns a 429 status code. Retry after the time specified in Retry-After header.