Prompts API

Prompts are the questions AIBeam runs across ChatGPT, Perplexity, Claude, and Gemini. Prompt capacity is account-wide across all projects.

Prompt Capacity

Scheduled monitoring consumes monthly credits. Daily prompts are also limited by the daily priority slots in your plan.

Prompt Object

{
  "id": "880e8400-e29b-41d4-a716-446655440004",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "prompt_text": "best project management software",
  "platforms": ["chatgpt", "perplexity", "claude"],
  "monitoring_frequency": "weekly",
  "category": null,
  "tags": ["comparison"],
  "is_active": true,
  "created_at": "2026-03-05T09:20:00Z",
  "updated_at": "2026-03-10T14:22:30Z"
}

List Prompts

GET /api/v1/projects/:projectId/prompts

Response

{
  "data": [
    {
      "id": "880e8400-e29b-41d4-a716-446655440004",
      "project_id": "550e8400-e29b-41d4-a716-446655440000",
      "prompt_text": "best project management software",
      "platforms": ["chatgpt", "perplexity", "claude"],
      "monitoring_frequency": "weekly",
      "category": null,
      "tags": ["comparison"],
      "is_active": true,
      "created_at": "2026-03-05T09:20:00Z",
      "updated_at": "2026-03-10T14:22:30Z"
    }
  ]
}

Create Prompt

POST /api/v1/projects/:projectId/prompts

Request Body

Example Request

curl -X POST "https://aibeam.io/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/prompts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_text": "best project management software",
    "platforms": ["chatgpt", "perplexity", "claude"],
    "monitoring_frequency": "weekly",
    "tags": ["comparison"]
  }'

Response

{
  "data": {
    "id": "910e8400-e29b-41d4-a716-446655440007",
    "project_id": "550e8400-e29b-41d4-a716-446655440000",
    "prompt_text": "best project management software",
    "platforms": ["chatgpt", "perplexity", "claude"],
    "monitoring_frequency": "weekly",
    "category": null,
    "tags": ["comparison"],
    "is_active": true,
    "created_at": "2026-03-10T16:30:00Z",
    "updated_at": "2026-03-10T16:30:00Z"
  }
}

Get Prompt

GET /api/v1/prompts/:promptId

Response

{
  "data": {
    "id": "880e8400-e29b-41d4-a716-446655440004",
    "project_id": "550e8400-e29b-41d4-a716-446655440000",
    "prompt_text": "best project management software",
    "platforms": ["chatgpt", "perplexity", "claude"],
    "monitoring_frequency": "weekly",
    "category": null,
    "tags": ["comparison"],
    "is_active": true,
    "created_at": "2026-03-05T09:20:00Z",
    "updated_at": "2026-03-10T14:22:30Z"
  }
}

Update Prompt

PATCH /api/v1/prompts/:promptId

PATCH accepts prompt_text, monitoring_frequency, tags, and is_active. Platform coverage is fixed by subscription tier and is not updated through this route.

Example Request

curl -X PATCH "https://aibeam.io/api/v1/prompts/880e8400-e29b-41d4-a716-446655440004" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_text": "enterprise SaaS solutions for teams",
    "monitoring_frequency": "weekly",
    "tags": ["comparison", "saas"]
  }'

Delete Prompt

DELETE /api/v1/prompts/:promptId

Deleting a prompt archives it and returns:

{
  "data": {
    "deleted": true
  }
}

Error Responses

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Prompt capacity reached for your subscription tier"
  }
}

Common error codes are VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, RATE_LIMIT_EXCEEDED, AIBEAM_KILL_SWITCH_ACTIVE, and INTERNAL_ERROR.

Rate Limiting

Rate limit information is included in response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1678531200

Next Steps

• Projects API - Manage monitoring projects
• Competitors API - Track competitors
• Data Endpoints - Read visibility, mentions, citations, and sentiment