External API Reference

Use the Chatobserver External API to pull prompt metadata, run history, and brand-visibility trends into your reporting stack. The API is read-only and available to any workspace with an active subscription.

Base URL & versioning

https://app.chatobserver.com/api/external/v1

All endpoints described below use GET requests and return JSON.

Authentication

1. Go to Settings → API and create a key.
2. Copy the value once displayed; keys are shown only on creation.
3. Store the key securely. Anyone with the key can read your workspace data.
4. Revoke keys the moment they are no longer needed—select the key in Settings → API and choose Revoke.

Include the key as a Bearer token:

GET /api/external/v1/prompts
Authorization: Bearer YOUR_API_KEY

If a request returns 401 Unauthorized, verify that the key is active and tied to the correct workspace.

Pagination

Responses include a pageInfo block:

{
  "data": [...],
  "pageInfo": {
    "limit": 50,
    "hasMore": true,
    "nextCursor": "eyJpZCI6..."
  }
}

• Use limit to control page size (defaults differ per endpoint).
• When hasMore is true, request the next page by passing cursor=nextCursor.

Endpoints

List prompts

GET /prompts

Retrieve active prompts (archived prompts are excluded unless you filter by status).

Query parameter	Description
limit (1‑100, default 50)	Page size
cursor	Continue from a previous response
status	active, inactive, or archived
search	Case-insensitive match on title, description, or prompt text
updatedAfter, updatedBefore	ISO-8601 timestamps
personaId, groupId	Filter by associated persona or group

Sample response (trimmed):

{
  "data": [
    {
      "id": 42,
      "title": "Enterprise positioning audit",
      "description": "Weekly check on messaging against key rivals",
      "promptText": "Act as a CMO evaluating...",
      "visibility": "team",
      "status": "active",
      "resultSyncStatus": "complete",
      "targetPlatforms": ["chatgpt", "perplexity"],
      "schedule": {
        "frequency": "weekly",
        "hour": 14,
        "minute": 0,
        "timezone": "America/New_York",
        "intervalMinutes": null,
        "daysOfWeek": [2]
      },
      "nextRunAt": "2024-05-06T18:00:00.000Z",
      "lastRunAt": "2024-04-29T18:02:15.000Z",
      "createdAt": "2023-11-09T15:22:11.000Z",
      "updatedAt": "2024-04-29T18:02:15.000Z",
      "personaCount": 2,
      "groupCount": 1
    }
  ],
  "pageInfo": {
    "limit": 50,
    "hasMore": false,
    "nextCursor": null
  }
}

List prompt runs

GET /prompt-runs

Review recent executions and their statuses.

Query parameter	Description
limit (1‑100, default 50)	Page size
cursor	Continue from a previous response
status	queued, running, succeeded, failed
analysisStatus	pending, complete, failed
trigger	schedule or manual
promptId	Filter runs for a single prompt
from, to	ISO-8601 timestamps for creation time
rootDomain	Return runs that cite a specific domain

Each run includes timestamps, the prompt title (when available), and any captured error message.

Brand visibility rollups

GET /brand-visibility

Pull daily mention counts by domain for the selected window. Use this to mirror the Brand Visibility chart in external dashboards.

Query parameter	Description
limit (1‑500, default 200)	Page size
cursor	Continue from a previous response
promptId	Focus on a single prompt
rootDomain	Filter to a specific domain
windowDays (1‑365, default 30)	Number of days to include (ignored when from/to provided)
from, to	ISO-8601 timestamps defining the reporting window

Response fields:

• bucketDay – UTC date representing the rollup day
• rootDomain – Domain cited in runs
• promptId – Prompt responsible for the mention (when available)
• mentionCount – Number of mentions recorded for that combination

Error handling

• 400 Bad Request – Check query parameters (invalid cursor or malformed date).
• 401 Unauthorized – Missing or revoked API key.
• 429 Too Many Requests – Slow down and retry with backoff.
• 500 range – Temporary outage; retry or contact support if it persists.

Support

Email support@chatobserver.com with the request ID from the x-request-id response header when reporting API issues.