Business Planv1

API Reference

The Deepheem API lets you run AI-powered investigations programmatically from your own applications, scripts, and workflows.

Overview

The API exposes a single endpoint — POST /api/investigate — that covers the full investigation lifecycle through a stage-based flow:

1. questions

Submit your brief. Get 4 clarifying questions back to refine the investigation scope.

2. investigate

Submit the brief + your answers. Get a full report: verdict, findings, sources, and confidence rating.

3. followup

Ask follow-up questions against the findings of a completed investigation.

API access is available exclusively on the Business Plan. Generate your API key from Settings → API Keys.

Authentication

Pass your API key in the x-api-key header on every request.

POST https://deepheem.com/api/investigate
Content-Type: application/json
x-api-key: dph_your_key_here

Keep your key secret. Never expose it in client-side code or commit it to version control. If compromised, delete it and generate a new one from your dashboard.

Base URL

https://deepheem.com/api/investigate

All requests are POST with a JSON body. The response is always JSON.

POST /api/investigate

POST/api/investigate

The investigation endpoint accepts a stage parameter that controls which part of the workflow is executed.

Common parameters

stagerequired

string

Which stage to run. One of: "questions", "investigate", "followup"

modulerequired

string

The investigation module. One of: "business", "legal"

briefrequired

string

Your investigation topic or question. Be as specific as possible.

Stage: "questions"

Submit your brief and receive 4 tailored clarifying questions. Use the answers to refine the investigation in the next stage.

Request body

stagerequired

string

"questions"

modulerequired

string

"business" | "legal"

briefrequired

string

Your investigation brief.

Example request

curl -X POST https://deepheem.com/api/investigate \
  -H "Content-Type: application/json" \
  -H "x-api-key: dph_your_key_here" \
  -d '{
    "stage": "questions",
    "module": "business",
    "brief": "Investigate the financial health of Acme Corp"
  }'

Response

{
  "questions": [
    "What specific financial metrics are most important to you (revenue, profit margins, debt)?",
    "What time period should this investigation cover?",
    "Are there specific markets or regions you want to focus on?",
    "What will you use these findings for (investment, due diligence, competitive research)?"
  ]
}

Stage: "investigate"

Submit the original brief alongside the clarifying questions and your answers. Returns a complete investigation report.

Request body

stagerequired

string

"investigate"

modulerequired

string

"business" | "legal"

briefrequired

string

The same brief from the questions stage.

questionsrequired

string[]

The array of questions returned from the questions stage.

answersrequired

string[]

Your answers to each question, in the same order.

Example request

curl -X POST https://deepheem.com/api/investigate \
  -H "Content-Type: application/json" \
  -H "x-api-key: dph_your_key_here" \
  -d '{
    "stage": "investigate",
    "module": "business",
    "brief": "Investigate the financial health of Acme Corp",
    "questions": [
      "What specific financial metrics are most important to you?",
      "What time period should this investigation cover?",
      "Are there specific markets or regions you want to focus on?",
      "What will you use these findings for?"
    ],
    "answers": [
      "Revenue growth, profit margins, and debt levels",
      "The last 3 years (2022–2025)",
      "UK and European markets",
      "Investment due diligence"
    ]
  }'

Response

{
  "verdict": "Acme Corp has shown consistent revenue growth of 12% year-on-year but carries significant debt obligations that may constrain future expansion.",
  "verdict_evidence_incomplete": false,
  "findings": [
    {
      "text": "Revenue grew from £42m to £53m between 2022 and 2024.",
      "evidence_status": "supported",
      "source": "Companies House filings"
    },
    {
      "text": "Gross profit margin declined from 38% to 31% over the same period.",
      "evidence_status": "supported",
      "source": "Annual report 2024"
    },
    {
      "text": "The company holds £18m in long-term debt, up from £9m in 2022.",
      "evidence_status": "partially_supported",
      "source": "Bloomberg Business"
    },
    {
      "text": "Rumoured acquisition talks with a US private equity firm in Q1 2025.",
      "evidence_status": "unsupported",
      "source": "Financial Times"
    }
  ],
  "sources": [
    {
      "name": "Companies House",
      "url": "https://companieshouse.gov.uk",
      "source_class": "government",
      "type": "Official website"
    },
    {
      "name": "Bloomberg Business",
      "url": "https://bloomberg.com/business",
      "source_class": "authoritative",
      "type": "News article"
    },
    {
      "name": "Financial Times",
      "url": "https://ft.com",
      "source_class": "authoritative",
      "type": "News article"
    }
  ]
}

Response fields

verdict

string

2–3 sentence headline summary grounded in retrieved evidence.

verdict_evidence_incomplete

boolean

True when retrieved sources only partially cover the brief — the verdict will note the gap explicitly.

findings

Finding[]

Array of individual findings, each assessed against retrieved source text.

findings[].text

string

The finding text.

findings[].evidence_status

"supported" | "partially_supported" | "unsupported" | "contradicted"

How well the retrieved source text supports this specific finding.

findings[].source

string

The source this finding was drawn from.

sources

Source[]

Array of sources retrieved and used during the investigation.

sources[].name

string

Source name.

sources[].url

string

Source URL.

sources[].source_class

Authority classification for this source.

sources[].type

string

e.g. "News article", "Official website", "Regulatory filing", "Case law".

Stage: "followup"

Ask a follow-up question based on the findings of a completed investigation. Does not consume an additional investigation from your allowance.

Request body

stagerequired

string

"followup"

briefrequired

string

The original investigation brief.

verdictrequired

string

The verdict from the completed investigation.

findingsrequired

Finding[]

The findings array from the completed investigation.

followUpQuestionrequired

string

The question you want answered.

Example request

curl -X POST https://deepheem.com/api/investigate \
  -H "Content-Type: application/json" \
  -H "x-api-key: dph_your_key_here" \
  -d '{
    "stage": "followup",
    "brief": "Investigate the financial health of Acme Corp",
    "verdict": "Acme Corp has shown consistent revenue growth...",
    "findings": [
      { "text": "Revenue grew from £42m to £53m...", "confidence": "confirmed", "source": "Companies House" }
    ],
    "followUpQuestion": "How does their debt level compare to industry average?"
  }'

Response

{
  "answer": "Acme Corp's debt-to-revenue ratio of 34% is above the UK mid-market average of approximately 22%, suggesting the company is more leveraged than its peers. This may limit its ability to raise further capital without equity dilution."
}

Error codes

Status	Code	Meaning
401	Unauthorized	Missing or invalid API key.
403	No active subscription	Your subscription is not active. Check your billing.
403	Investigation limit reached	You have reached your monthly investigation limit. Business plan has unlimited investigations.
400	Invalid stage	The stage parameter is missing or not one of: questions, investigate, followup.
500	API error	An internal error occurred. Retry the request. If it persists, contact support.

All error responses follow this shape:

{ "error": "Description of what went wrong" }

Full examples

JavaScript / Node.js

const API_KEY = 'dph_your_key_here'
const BASE = 'https://deepheem.com/api/investigate'

async function runInvestigation(brief, module = 'business') {
  // Step 1 — get clarifying questions
  const q = await fetch(BASE, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': API_KEY },
    body: JSON.stringify({ stage: 'questions', module, brief })
  }).then(r => r.json())

  const questions = q.questions
  // In your app, present these questions to the user.
  // For this example we provide placeholder answers:
  const answers = questions.map(() => 'Not specified')

  // Step 2 — run the investigation
  const result = await fetch(BASE, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': API_KEY },
    body: JSON.stringify({ stage: 'investigate', module, brief, questions, answers })
  }).then(r => r.json())

  console.log('Verdict:', result.verdict)
  console.log('Confidence:', result.confidence)
  console.log('Findings:', result.findings)
  console.log('Sources:', result.sources)

  return result
}

runInvestigation('Investigate the financial health of Acme Corp')

Python

import requests

API_KEY = 'dph_your_key_here'
BASE = 'https://deepheem.com/api/investigate'
HEADERS = {'Content-Type': 'application/json', 'x-api-key': API_KEY}

brief = 'Investigate the financial health of Acme Corp'
module = 'business'

# Step 1 — questions
q = requests.post(BASE, json={'stage': 'questions', 'module': module, 'brief': brief}, headers=HEADERS)
questions = q.json()['questions']

# Provide answers (in your app, collect these from the user)
answers = ['Not specified'] * len(questions)

# Step 2 — investigate
result = requests.post(BASE, json={
    'stage': 'investigate',
    'module': module,
    'brief': brief,
    'questions': questions,
    'answers': answers
}, headers=HEADERS).json()

print('Verdict:', result['verdict'])
print('Confidence:', result['confidence'])
for f in result['findings']:
    print(f"- [{f['confidence']}] {f['text']} ({f['source']})")

cURL — full flow

# Step 1: Get questions
curl -X POST https://deepheem.com/api/investigate \
  -H "Content-Type: application/json" \
  -H "x-api-key: dph_your_key_here" \
  -d '{"stage":"questions","module":"business","brief":"Investigate Acme Corp finances"}'

# Step 2: Run investigation (using the questions from step 1)
curl -X POST https://deepheem.com/api/investigate \
  -H "Content-Type: application/json" \
  -H "x-api-key: dph_your_key_here" \
  -d '{
    "stage": "investigate",
    "module": "business",
    "brief": "Investigate Acme Corp finances",
    "questions": ["Question 1?","Question 2?","Question 3?","Question 4?"],
    "answers": ["Answer 1","Answer 2","Answer 3","Answer 4"]
  }'

Questions about the API?

support@deepheem.com