Catalyst API Reference

Base URL

Production: https://api.catalyst.surf/api/v1
Development: http://localhost:8000/api/v1

Authentication

All API endpoints require authentication via JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Response Format

Success Response

{
  "status_code": 200,
  "message": "Success",
  "data": {
    // Response data
  }
}

Error Response

{
  "status_code": 400,
  "message": "Error description",
  "detail": "Additional error details"
}

Authentication Endpoints

POST /auth/login

Request Body:

{
  "email": "[email protected]",
  "password": "password123"
}

Response:

{
  "status_code": 200,
  "message": "Login successful",
  "data": {
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "token_type": "bearer",
    "expires_in": 2628000,
    "user": {
      "id": "uuid",
      "email": "[email protected]",
      "name": "John Doe",
      "role": "admin"
    }
  }
}

Register

POST /auth/register

Request Body:

{
  "email": "[email protected]",
  "password": "password123",
  "name": "John Doe"
}

Get Current User

GET /users/me

Response:

{
  "status_code": 200,
  "data": {
    "id": "uuid",
    "email": "[email protected]",
    "name": "John Doe",
    "role": "admin",
    "is_active": true,
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Client Management

List Clients

GET /clients

Query Parameters:

page (optional): Page number (default: 1)
limit (optional): Items per page (default: 10)

Response:

{
  "status_code": 200,
  "data": {
    "clients": [
      {
        "id": "uuid",
        "name": "Acme Corp",
        "logo": "https://example.com/logo.png",
        "is_active": true,
        "role": "admin",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ],
    "total_pages": 1,
    "current_page": 1
  }
}

Create Client

POST /clients

Request Body:

{
  "name": "New Client",
  "logo": "https://example.com/logo.png"
}

Get Client Role

GET /clients/{client_id}/role

Response:

{
  "status_code": 200,
  "data": {
    "role": "admin"
  }
}

Task Management

List Tasks

GET /tasks

Query Parameters:

client_id (optional): Filter by client
status (optional): Filter by status (pending, in_progress, completed, cancelled)
task_type (optional): Filter by type (review_creative, review_report, other)
priority (optional): Filter by priority (Backlog, Low, Medium, High)
by_me (optional): Filter tasks assigned to current user (true/false)
other_people (optional): Filter tasks assigned to others (true/false)
assignee_id (optional): Filter by specific assignee
page (optional): Page number (default: 1)
limit (optional): Items per page (default: 10)

Response:

{
  "status_code": 200,
  "data": {
    "tasks": [
      {
        "id": "uuid",
        "name": "Review Facebook Ad Creative",
        "task_type": "review_creative",
        "status": "pending",
        "priority": "High",
        "client_id": "uuid",
        "created_by": "uuid",
        "assignees": ["uuid1", "uuid2"],
        "due_date": "2024-01-15T00:00:00Z",
        "description": "Review the new Facebook ad creative",
        "related_object_id": "uuid",
        "related_object_type": "creative_submission",
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ],
    "total_pages": 1,
    "current_page": 1
  }
}

Create Task

POST /tasks

Request Body:

{
  "name": "Review Facebook Ad Creative",
  "task_type": "review_creative",
  "priority": "High",
  "assignees": ["uuid1", "uuid2"],
  "due_date": "2024-01-15",
  "description": "Review the new Facebook ad creative",
  "related_object_id": "uuid",
  "related_object_type": "creative_submission"
}

Update Task

PATCH /tasks/{task_id}

Request Body:

{
  "name": "Updated Task Name",
  "priority": "Medium",
  "assignees": ["uuid1", "uuid3"],
  "description": "Updated description"
}

Complete Task

POST /tasks/{task_id}/complete

Request Body:

{
  "completed_by": "uuid"
}

Cancel Task

POST /tasks/{task_id}/cancel

Request Body:

{
  "completed_by": "uuid"
}

Delete Task

DELETE /tasks/{task_id}

Task Comments

Get Task Comments

GET /tasks/{task_id}/comments

Response:

{
  "status_code": 200,
  "data": {
    "comments": [
      {
        "id": "uuid",
        "comment": "This looks good, approved!",
        "user_id": "uuid",
        "user_name": "John Doe",
        "user_email": "[email protected]",
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

Add Comment

POST /tasks/{task_id}/comments

Request Body:

{
  "comment": "This looks good, approved!"
}

Update Comment

PATCH /tasks/comments/{comment_id}

Request Body:

{
  "comment": "Updated comment text"
}

Delete Comment

DELETE /tasks/comments/{comment_id}

Alert System

List Alerts

GET /alerts

Query Parameters:

client_id (optional): Filter by client

Response:

{
  "status_code": 200,
  "data": {
    "settings": [
      {
        "alert_id": "uuid",
        "name": "High CPLPV Alert",
        "description": "Alert when CPLPV exceeds threshold",
        "alert_type": "cplpv",
        "is_enabled": true,
        "is_default": false,
        "data_level": "ad",
        "custom_config": {
          "frequency": {
            "type": "daily",
            "time": "05:00",
            "timezone": "America/Los_Angeles"
          },
          "thresholds": {
            "cplpv": 50
          }
        },
        "created_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

Create Alert

POST /alerts?client_id={client_id}

Request Body:

{
  "name": "High CPLPV Alert",
  "description": "Alert when CPLPV exceeds threshold",
  "alert_type": "cplpv",
  "condition_config": {
    "field": "cplpv",
    "operator": "greater_than",
    "value": 50
  },
  "action_config": {
    "create_task": true,
    "assignees": ["uuid1", "uuid2"],
    "task_type": "review_report"
  },
  "data_source": "dm_alert.alert_cplpv",
  "frequency": {
    "type": "daily",
    "time": "05:00",
    "timezone": "America/Los_Angeles"
  }
}

Update Alert

PUT /alerts/{alert_id}?client_id={client_id}

Request Body:

{
  "name": "Updated Alert Name",
  "is_enabled": false
}

Delete Alert

DELETE /alerts/{alert_id}?client_id={client_id}

Trigger Alert

POST /alerts/{alert_id}/trigger?client_id={client_id}

Response:

{
  "status_code": 200,
  "data": {
    "alert_name": "High CPLPV Alert",
    "instances_created": 5,
    "message": "Alert triggered successfully"
  }
}

Alert Instances (Notifications)

List Alert Instances

GET /alerts/instances

Query Parameters:

client_id (optional): Filter by client
alert_id (optional): Filter by alert
status (optional): Filter by status (triggered, resolved, dismissed)
limit (optional): Items per page (default: 50)
offset (optional): Offset for pagination (default: 0)

Response:

{
  "status_code": 200,
  "data": {
    "instances": [
      {
        "id": "uuid",
        "alert_id": "uuid",
        "alert_name": "High CPLPV Alert",
        "client_id": "uuid",
        "triggered_at": "2024-01-01T00:00:00Z",
        "alert_data": {
          "ad_id": "123456789",
          "ad_name": "Summer Sale Ad",
          "cplpv": 75.50,
          "account_average": 45.20
        },
        "status": "triggered",
        "task_id": "uuid",
        "resolved_at": null,
        "resolved_by": null
      }
    ]
  }
}

Resolve Alert Instance

PUT /alerts/instances/{instance_id}/resolve

Request Body:

{
  "resolution_notes": "Issue has been addressed"
}

Dismiss Alert Instance

PUT /alerts/instances/{instance_id}/dismiss

Lead Scoring

Get Lead Scoring Results

GET /leadscoring/results

Query Parameters:

client_id (optional): Filter by client
min_score (optional): Minimum score threshold
max_score (optional): Maximum score threshold
limit (optional): Items per page (default: 100)
offset (optional): Offset for pagination (default: 0)

Response:

{
  "status_code": 200,
  "data": {
    "results": [
      {
        "id": "uuid",
        "email": "[email protected]",
        "score": 0.85,
        "value": {
          "engagement_score": 0.8,
          "demographic_score": 0.9,
          "behavioral_score": 0.85
        },
        "raw_data": {
          "page_views": 15,
          "time_on_site": 300,
          "form_submissions": 2
        },
        "source": "website",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

Score Lead

POST /leadscoring/score

Request Body:

{
  "email": "[email protected]",
  "raw_data": {
    "page_views": 10,
    "time_on_site": 200,
    "form_submissions": 1
  },
  "client_id": "uuid"
}

Creative Submissions

List Creative Submissions

GET /creative-submissions

Query Parameters:

client_id (optional): Filter by client
status (optional): Filter by status (pending, approved, rejected)
page (optional): Page number (default: 1)
limit (optional): Items per page (default: 10)

Response:

{
  "status_code": 200,
  "data": {
    "submissions": [
      {
        "id": "uuid",
        "name": "Summer Sale Banner",
        "ad_type": "image",
        "media_url": "https://example.com/banner.jpg",
        "media_filename": "summer_sale_banner.jpg",
        "media_size": 1024000,
        "media_content_type": "image/jpeg",
        "ad_script": "Summer Sale - 50% Off!",
        "headline": "Summer Sale",
        "primary_text": "Get 50% off on all items",
        "status": "pending",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

Create Creative Submission

POST /creative-submissions

Request Body:

{
  "name": "Summer Sale Banner",
  "ad_type": "image",
  "media_url": "https://example.com/banner.jpg",
  "ad_script": "Summer Sale - 50% Off!",
  "headline": "Summer Sale",
  "primary_text": "Get 50% off on all items"
}

Approve Creative

POST /creative-submissions/{id}/approve

Reject Creative

POST /creative-submissions/{id}/reject

Request Body:

{
  "reason": "Does not meet brand guidelines"
}

Reports & Analytics

Growth Report

GET /reports/growth

Query Parameters:

client_id (required): Client ID
start_date (optional): Start date (YYYY-MM-DD)
end_date (optional): End date (YYYY-MM-DD)
period (optional): Period (daily, weekly, monthly)

Performance Report

GET /reports/performance

Query Parameters:

client_id (required): Client ID
platform (optional): Platform filter
campaign_id (optional): Campaign filter
start_date (optional): Start date
end_date (optional): End date

Error Codes

Code	Description
400	Bad Request - Invalid input data
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions
404	Not Found - Resource not found
422	Unprocessable Entity - Validation error
500	Internal Server Error - Server error

Rate Limiting

Rate Limit: 1000 requests per hour per user
Headers: Rate limit information included in response headers
- X-RateLimit-Limit: Request limit per hour
- X-RateLimit-Remaining: Remaining requests
- X-RateLimit-Reset: Reset time (Unix timestamp)

Pagination

Most list endpoints support pagination:

page: Page number (1-based, default: 1)
limit: Items per page (default: 10, max: 100)

Response includes:

total_pages: Total number of pages
current_page: Current page number
total_items: Total number of items

Filtering & Sorting

Many endpoints support filtering and sorting:

Common Filters:

status: Filter by status
created_at: Date range filtering
client_id: Filter by client

Common Sort Options:

created_at: Sort by creation date
updated_at: Sort by update date
name: Sort alphabetically

Example:

GET /tasks?status=pending&sort=created_at&order=desc&page=1&limit=20

This API reference covers the main endpoints. For complete documentation with examples, visit the interactive API docs at /docs (development) or contact the development team.

Catalyst API Reference

Base URL​

Authentication​

Response Format​

Success Response​

Error Response​

Authentication Endpoints​

Login​

Register​

Get Current User​

Client Management​

List Clients​

Create Client​

Get Client Role​

Task Management​

List Tasks​

Create Task​

Update Task​

Complete Task​

Cancel Task​

Delete Task​

Task Comments​

Get Task Comments​

Add Comment​

Update Comment​

Delete Comment​

Alert System​

List Alerts​

Create Alert​

Update Alert​

Delete Alert​

Trigger Alert​

Alert Instances (Notifications)​

List Alert Instances​

Resolve Alert Instance​

Dismiss Alert Instance​

Lead Scoring​

Get Lead Scoring Results​

Score Lead​

Creative Submissions​

List Creative Submissions​

Create Creative Submission​

Approve Creative​

Reject Creative​

Reports & Analytics​

Growth Report​

Performance Report​

Error Codes​

Rate Limiting​

Pagination​

Filtering & Sorting​

Base URL

Authentication

Response Format

Success Response

Error Response

Authentication Endpoints

Login

Register

Get Current User

Client Management

List Clients

Create Client

Get Client Role

Task Management

List Tasks

Create Task

Update Task

Complete Task

Cancel Task

Delete Task

Task Comments

Get Task Comments

Add Comment

Update Comment

Delete Comment

Alert System

List Alerts

Create Alert

Update Alert

Delete Alert

Trigger Alert

Alert Instances (Notifications)

List Alert Instances

Resolve Alert Instance

Dismiss Alert Instance

Lead Scoring

Get Lead Scoring Results

Score Lead

Creative Submissions

List Creative Submissions

Create Creative Submission

Approve Creative

Reject Creative

Reports & Analytics

Growth Report

Performance Report

Error Codes

Rate Limiting

Pagination

Filtering & Sorting