GPTR LogoGPT Researcher

/api-reference

API reference

The self-hosted GPT Researcher FastAPI server exposes a small, agent-friendly REST API. The full machine-readable specification is available as OpenAPI 3.1 at /openapi.json (also linked from this page's Link response header).

Authentication: none on the gptr.dev marketing site. Self-hosted servers read your LLM and retriever provider keys from environment variables (OPENAI_API_KEY, TAVILY_API_KEY, etc.).

Rate limits: self-hosted defaults to no rate limit; in production deployments responses include X-RateLimit-Limit, X-RateLimit-Remaining, and Retry-After headers. Errors come back as a consistent JSON envelope.

Streaming: long-running operations support SSE and chunked transfer encoding. Set Accept: text/event-stream on GET /research/stream.

Webhooks: see /webhooks for event-driven notifications.

POST /research

Run a deep-research task

Plans subtopics, fetches and validates 10-30 sources, accumulates a research context, and (optionally) writes a long-form report. Typical latency 30 - 60s.

Request body

{
  "query": "string (required)",
  "report_type": "research_report | outline_report | resource_report | detailed_report",
  "retriever": "tavily | bing | google | duckduckgo | searx | ..."
}

Response

{ report: string (markdown), sources: Source[], duration_ms: number }

GET /research/stream

Stream a deep-research task via SSE

Same as POST /research but returns Server-Sent Events: planning, source-found, source-validated, report-chunk, complete.

Request body

Use ?query= and optional ?report_type= query params. Set Accept: text/event-stream.

Response

text/event-stream of progress events

POST /search

Quick web search

Low-latency snippet search across the configured retriever (Tavily, Bing, Google, DuckDuckGo, SearXNG).

Request body

{
  "query": "string (required)",
  "retriever": "string",
  "max_results": "1-20 (default 5)"
}

Response

{ results: { url, title, content }[] }

POST /report

Write a report from existing context

Generates a long-form Markdown report from a previously accumulated research context.

Request body

{
  "query": "string",
  "context": "string (optional)",
  "report_type": "string"
}

Response

{ report: string (markdown) }

GET /sources

List sources from the most recent research run

Returns the URL+title+snippet of every source gathered during the last /research call.

Response

Source[]

GET /health

Liveness check

Response

{ status: 'ok' | 'degraded', version, uptime_seconds }

Error envelope

Every error returns a JSON object with stable codes so agents can branch on the failure mode without parsing prose.

{
  "error": {
    "code": "rate_limited | invalid_request | provider_error | not_found",
    "message": "Human-readable explanation.",
    "retry_after_seconds": "(optional, on 429)",
    "details": {}
  }
}

Function-calling compatibility

Operation IDs are unique, parameters are typed, and response schemas are declared, so the spec is consumable by ChatGPT, Claude, and Gemini function calling out of the box. Pass https://gptr.dev/openapi.json directly as a tool source.