API reference

Deep research

Run a cited, multi-step research report on a public topic, company, or vehicle, reconciled across the web pages it reads.

POST/api/v1/research

Scope: chat
Formats: JSON · SSE
Sandbox: Free fixtures

curl https://deepsearch.app/api/v1/research \
  -H "Authorization: Bearer $DEEPSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "query": "Compare the public product strategy of Stripe and Adyen in 2026",
        "subjectType": "company",
        "format": "json"
      }'

curl https://deepsearch.app/api/v1/research \
  -H "Authorization: Bearer $DEEPSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "query": "Compare the public product strategy of Stripe and Adyen in 2026",
        "subjectType": "company",
        "format": "json"
      }'

const res = await fetch("https://deepsearch.app/api/v1/research", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DEEPSEARCH_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "query": "Compare the public product strategy of Stripe and Adyen in 2026",
    "subjectType": "company",
    "format": "json"
  }),
});

const result = await res.json();
console.log(result);

const res = await fetch("https://deepsearch.app/api/v1/research", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DEEPSEARCH_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "query": "Compare the public product strategy of Stripe and Adyen in 2026",
    "subjectType": "company",
    "format": "json"
  }),
});

const result = await res.json();
console.log(result);

import os
import json
import requests

res = requests.post(
    "https://deepsearch.app/api/v1/research",
    headers={
        "Authorization": f"Bearer {os.environ['DEEPSEARCH_API_KEY']}",
        "Content-Type": "application/json",
    },
    json=json.loads("{\"query\":\"Compare the public product strategy of Stripe and Adyen in 2026\",\"subjectType\":\"company\",\"format\":\"json\"}"),
)

print(res.json())

import os
import json
import requests

res = requests.post(
    "https://deepsearch.app/api/v1/research",
    headers={
        "Authorization": f"Bearer {os.environ['DEEPSEARCH_API_KEY']}",
        "Content-Type": "application/json",
    },
    json=json.loads("{\"query\":\"Compare the public product strategy of Stripe and Adyen in 2026\",\"subjectType\":\"company\",\"format\":\"json\"}"),
)

print(res.json())

Example request

Authorization

Authorizationheaderrequired

Send Bearer $DEEPSEARCH_API_KEY with the chat scope. The free sandbox uses the published test key.

Authentication guide

Body parameters

querystringrequired

The public topic, company, or VIN to research, 1 to 1,000 characters.

subjectTypeenum

A hint that selects the most relevant public-data tools.

generalcompanyvin

Default: general

depthenum

The current API version always runs a multi-step deep research pass.

deep

Default: deep

formatenum

sse to stream progress and the report, or json for the collected response.

ssejson

Default: sse

sandboxboolean

Return deterministic, unmetered fixtures for CI, demos, and parser development.

Default: false

Response

JSON responses preserve the operation result and include request metadata, usage, and collected events. SSE delivers progress and result events as they arrive.

Streaming & formats

{
  "object": "research_result",
  "request_id": "req_01HZY8U6RESEARCH9F4X9J7Z1H",
  "metadata": {
    "api_version": "v1",
    "operation": "research",
    "request_id": "req_01HZY8U6RESEARCH9F4X9J7Z1H",
    "generated_at": "2026-10-24T12:00:00.000Z"
  },
  "usage": {
    "metered": true,
    "percentageCharged": 5,
    "remainingPercent": 68,
    "resetAt": "2026-11-01T00:00:00.000Z",
    "source": "included",
    "credits": 5,
    "allowanceSource": "weekly"
  },
  "query": "Compare the public product strategy of Stripe and Adyen in 2026",
  "subject_type": "company",
  "report": "**In short:** Both sell unified commerce, from different starting points ([stripe.com](https://stripe.com/)).",
  "sources": [
    {
      "id": "src-1",
      "position": 1,
      "url": "https://stripe.com/",
      "title": "Stripe",
      "domain": "stripe.com"
    }
  ],
  "related_questions": [
    "How do their pricing models differ?"
  ],
  "events": []
}

{
  "object": "research_result",
  "request_id": "req_01HZY8U6RESEARCH9F4X9J7Z1H",
  "metadata": {
    "api_version": "v1",
    "operation": "research",
    "request_id": "req_01HZY8U6RESEARCH9F4X9J7Z1H",
    "generated_at": "2026-10-24T12:00:00.000Z"
  },
  "usage": {
    "metered": true,
    "percentageCharged": 5,
    "remainingPercent": 68,
    "resetAt": "2026-11-01T00:00:00.000Z",
    "source": "included",
    "credits": 5,
    "allowanceSource": "weekly"
  },
  "query": "Compare the public product strategy of Stripe and Adyen in 2026",
  "subject_type": "company",
  "report": "**In short:** Both sell unified commerce, from different starting points ([stripe.com](https://stripe.com/)).",
  "sources": [
    {
      "id": "src-1",
      "position": 1,
      "url": "https://stripe.com/",
      "title": "Stripe",
      "domain": "stripe.com"
    }
  ],
  "related_questions": [
    "How do their pricing models differ?"
  ],
  "events": []
}

{
  "object": "research_result",
  "request_id": "req_01HZY8U6RESEARCH9F4X9J7Z1H",
  "metadata": {
    "api_version": "v1",
    "operation": "research",
    "request_id": "req_01HZY8U6RESEARCH9F4X9J7Z1H",
    "generated_at": "2026-10-24T12:00:00.000Z"
  },
  "usage": {
    "metered": true,
    "percentageCharged": 5,
    "remainingPercent": 68,
    "resetAt": "2026-11-01T00:00:00.000Z",
    "source": "included",
    "credits": 5,
    "allowanceSource": "weekly"
  },
  "query": "Compare the public product strategy of Stripe and Adyen in 2026",
  "subject_type": "company",
  "report": "**In short:** Both sell unified commerce, from different starting points ([stripe.com](https://stripe.com/)).",
  "sources": [
    {
      "id": "src-1",
      "position": 1,
      "url": "https://stripe.com/",
      "title": "Stripe",
      "domain": "stripe.com"
    }
  ],
  "related_questions": [
    "How do their pricing models differ?"
  ],
  "events": []
}

{
  "error": {
    "code": "invalid_json",
    "message": "The request body was not valid JSON."
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "No Authorization: Bearer <key> header was sent. Body carries an onboarding url."
  }
}

{
  "error": {
    "code": "not_subscribed",
    "message": "The account has no active subscription. Body carries a url to subscribe."
  }
}

{
  "error": {
    "code": "missing_scope",
    "message": "The key is valid but lacks the scope this endpoint needs."
  }
}

{
  "error": {
    "code": "idempotency_conflict",
    "message": "The Idempotency-Key was reused with a different request body."
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests from this API key or IP. Retry after the reset time."
  }
}

{
  "error": {
    "code": "spend_cap_reached",
    "message": "A temporary service-wide spend cap was hit. Retry later."
  }
}

Example responseapplication/json

Sources & coverage

Run DeepSearch's research agent on a public topic, company, or vehicle. It plans, searches the web, reads the pages themselves, corroborates claims across sources, and returns one cited Markdown report with its source list and follow-up questions. People research is not part of this endpoint; use search, dossier and chat for a person. The request has the same shape as the MPP gateway's /v1/research, so an agent that pays per call and one that uses an account send identical bodies. A run takes minutes; create a job when the client cannot hold a long request.

Usage & caching

Deep research is Very High usage and covers every search and page read in the run.

Usage & rate limits

Examples illustrate the contract. Test request runs the selected deployment; sandbox fixtures are unmetered.