Agents

Research agents for automated content research

List research agents

get

List all research agents for the team. Requires Power plan or higher.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Query parameters

site_idstring · uuidOptional

Filter by site ID

Responses

200

List of agents

application/json

idstring · uuidOptional

namestringOptional

descriptionstring · nullableOptional

agent_typestring · enumOptionalPossible values:

site_idstring · uuidOptional

statusstring · enumOptionalPossible values:

schedulestring · enumOptionalPossible values:

run_countintegerOptional

last_run_atstring · date-time · nullableOptional

next_run_atstring · date-time · nullableOptional

created_atstring · date-timeOptional

get

/v1/agents

HTTPcURLJavaScriptPython

GET /v1/agents HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

List of agents

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "description": "text",
    "agent_type": "local_news",
    "site_id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "active",
    "schedule": "weekly",
    "run_count": 1,
    "last_run_at": "2026-04-02T01:04:08.552Z",
    "next_run_at": "2026-04-02T01:04:08.552Z",
    "created_at": "2026-04-02T01:04:08.552Z"
  }
]

Get an agent

get

Get agent details including latest snapshot and research brief.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstring · uuidRequired

Agent ID

Responses

200

Agent detail with latest results

application/json

idstring · uuidOptional

namestringOptional

descriptionstring · nullableOptional

agent_typestring · enumOptionalPossible values:

site_idstring · uuidOptional

statusstring · enumOptionalPossible values:

schedulestring · enumOptionalPossible values:

run_countintegerOptional

last_run_atstring · date-time · nullableOptional

next_run_atstring · date-time · nullableOptional

created_atstring · date-timeOptional

configobjectOptional

Agent-type-specific configuration

sourcesobject[]Optional

Data sources configuration

latest_snapshotobject · nullableOptional

Most recent agent run snapshot with crawl stats and extracted data

latest_briefobject · nullableOptional

Most recent research brief with content ideas and keywords

get

/v1/agents/{id}

HTTPcURLJavaScriptPython

GET /v1/agents/{id} HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

Agent detail with latest results

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "agent_type": "local_news",
  "site_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "active",
  "schedule": "weekly",
  "run_count": 1,
  "last_run_at": "2026-04-02T01:04:08.552Z",
  "next_run_at": "2026-04-02T01:04:08.552Z",
  "created_at": "2026-04-02T01:04:08.552Z",
  "config": {},
  "sources": [
    {}
  ],
  "latest_snapshot": {},
  "latest_brief": {}
}

Trigger an agent run

post

Manually trigger an agent to run immediately. Returns 409 if already running.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstring · uuidRequired

Responses

200

Agent run triggered

application/json

messagestringOptional

409

Agent is already running

post

/v1/agents/{id}/run

HTTPcURLJavaScriptPython

POST /v1/agents/{id}/run HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

{
  "message": "text"
}