API docs

Updated May 4, 2026

The API is small on purpose. It accepts a bearer token, creates research jobs, and exposes pack views for sources, artifacts, media, and agent context.

Public base URL: https://researcher.now.

Auth

Send Authorization: Bearer $AUTO_RESEARCH_TOKEN on every /v1/* request. Health stays public.

Routes

GET /health: Service liveness.
POST /v1/research-packs: Creates a job and returns jobId and packId.
GET /v1/research-packs/:id: Pack plus job status.
GET /v1/research-packs/:id/sources: Normalized source rows.
GET /v1/research-packs/:id/media: Media rows.
GET /v1/research-packs/:id/artifacts: Structured artifacts.
GET /v1/research-packs/:id/agent-context: Agent-ready bundle.
GET /v1/library: Archived completed packs.
GET /v1/library/:id: Single library entry by pack ID.
GET /v1/playbooks: Registered playbook catalog.
GET /v1/playbooks/:id: Single playbook by ID.
POST /v1/research-packs/:id/cancel: Cancels a queued or running job.
POST /v1/research-packs/:id/evaluate: Stores an evaluation record.
POST /v1/evals: Direct eval insert helper.

Create pack

export AUTO_RESEARCH_BASE_URL="https://researcher.now"

curl "$AUTO_RESEARCH_BASE_URL/v1/playbooks" \
  -H "Authorization: Bearer $AUTO_RESEARCH_TOKEN"

curl -X POST "$AUTO_RESEARCH_BASE_URL/v1/research-packs" \
  -H "Authorization: Bearer $AUTO_RESEARCH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "00000000-0000-0000-0000-000000000000",
    "requestedBy": "research-auto",
    "topic": "popular chocolate chip cookie recipes",
    "mode": "collection",
    "playbook": "cookie_recipe_corpus",
    "depth": "wide",
    "outputSchemas": ["recipe_v1", "source_coverage_v1"],
    "limits": { "maxQueries": 8, "maxSources": 50, "maxCostUsd": 10 }
  }'

Agent context

{
  "packId": "uuid",
  "status": "succeeded",
  "agentContext": {
    "brief": "Collected 50 sources...",
    "topFindings": [],
    "sourceMap": [],
    "structuredData": {},
    "media": [],
    "openQuestions": [],
    "recommendedActions": [],
    "citations": []
  }
}

Library

curl "$AUTO_RESEARCH_BASE_URL/v1/library?limit=20" \
  -H "Authorization: Bearer $AUTO_RESEARCH_TOKEN"

Playbooks

curl "$AUTO_RESEARCH_BASE_URL/v1/playbooks" \
  -H "Authorization: Bearer $AUTO_RESEARCH_TOKEN"