Research Agent API

POST /research

Run a one-off research query with web search and scraping. Returns structured or free-text output.

Parameters (query string)

prompt	Required. The research instruction.
model	OpenRouter model ID. Default: google/gemini-2.5-flash
schema	JSON schema string for structured output.
temperature	0.0-2.0. Default: 0.1

curl -X POST "https://research-agent.net/research" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  --data-urlencode "prompt=Research Stripe Inc and find their ICP"

Response

{
  "output": "Stripe is a financial infrastructure platform...",
  "model_used": "google/gemini-2.5-flash",
  "execution_time_seconds": 8.2
}

GET /agents

List all your agents.

Response

{ "agents": [{ "id": "uuid", "name": "...", "model": "...", "input_variables": [...], "is_active": true, ... }] }

POST /agents

Create a new agent.

Request body (JSON)

{
  "name": "Company Enrichment",
  "description": "Enrich company data",
  "prompt_template": "Research {{company_name}} at {{website}} and find their ICP, tech stack, and funding.",
  "input_variables": ["company_name", "website"],
  "model": "google/gemini-2.5-flash",
  "temperature": 0.1,
  "output_schema": null
}

GET /agents/{agent_id}

Get agent details by ID.

PUT /agents/{agent_id}

Update agent configuration. Only provided fields are changed.

DELETE /agents/{agent_id}

Permanently delete an agent.

POST /agents/{agent_id}/run

Execute an agent with input variables. Costs 1 credit.

Request body (JSON)

{ "company_name": "Stripe", "website": "https://stripe.com" }

Response

{
  "agent_id": "uuid",
  "agent_name": "Company Enrichment",
  "output": { "icp": "...", "tech_stack": [...] },
  "execution_time_seconds": 12.5,
  "request_id": "A1B2C3D4"
}

GET /agents/{agent_id}/runs

List past runs for an agent.

Query parameters

limit

Max results (default 50, max 200)

GET /agents/templates

List available pre-built agent templates.

POST /agents/{agent_id}/bulk-run

Submit a bulk run job. Costs 1 credit per item (deducted upfront). Max 1000 items.

Request body (JSON)

{
  "items": [
    { "company_name": "Stripe", "website": "https://stripe.com" },
    { "company_name": "Notion", "website": "https://notion.so" },
    { "company_name": "Linear", "website": "https://linear.app" }
  ]
}

Response

{
  "job_id": "uuid",
  "total_items": 3,
  "status": "running"
}

GET /agents/{agent_id}/bulk-runs

List all bulk run jobs for an agent. Returns job_id, status, progress counts, timestamps.

GET /agents/{agent_id}/bulk-runs/{job_id}

Get bulk job status and progress.

Response

{
  "id": "uuid",
  "agent_id": "uuid",
  "status": "running",
  "total_items": 100,
  "completed_items": 45,
  "failed_items": 2,
  "created_at": "2026-03-04T12:00:00Z",
  "completed_at": null
}

GET /agents/{agent_id}/bulk-runs/{job_id}/results

Get individual item results (paginated).

Query parameters

offset	Skip N items (default 0)
limit	Max items to return (default 50, max 100)

Response

{
  "job_id": "uuid",
  "offset": 0,
  "items": [
    {
      "id": "uuid",
      "input_variables": { "company_name": "Stripe", "website": "https://stripe.com" },
      "status": "completed",
      "output": { "icp": "...", "tech_stack": [...] },
      "execution_time_seconds": 11.2
    }
  ]
}

DELETE /agents/{agent_id}/bulk-runs/{job_id}

Cancel a running bulk job. Completed items are kept.

GET /billing/credits

Get current credit balance and recent transactions.

GET /billing/plans

List available credit packs with prices.

POST /billing/checkout

Create a Stripe checkout session to purchase credits.

GET /auth/me

Get current user identity.

{ "id": "uuid", "email": "user@example.com", "display_name": "John", "created_at": "..." }

GET /auth/usage

Get usage statistics.

days	Lookback period in days (default 30)

POST /auth/rotate-key

Regenerate your API key. Old key is deactivated.