Quickstart

This guide walks through the minimum integration: create an API key, launch a campaign, and read the synthesized report.

1. Create an API key

API keys are workspace-scoped. From the Ontora dashboard:

Open Settings → API keys.
Click Create API key.
Pick the scopes you need. For this quickstart, select interviews and exports.
Copy the key (it starts with ont_). You will not be able to see it again.

Treat API keys like passwords. Store them in a secret manager — never commit them to source control.

2. Authenticate

Every request takes an X-API-Key header.

export ONTORA_API_KEY="ont_..."

curl https://api.ontora.com/v1/interviews \
  -H "X-API-Key: $ONTORA_API_KEY"

import os, httpx

client = httpx.Client(
    base_url="https://api.ontora.com",
    headers={"X-API-Key": os.environ["ONTORA_API_KEY"]},
)

campaigns = client.get("/v1/interviews").json()

const res = await fetch("https://api.ontora.com/v1/interviews", {
  headers: { "X-API-Key": process.env.ONTORA_API_KEY! },
});
const campaigns = await res.json();

3. Launch a campaign

Create a campaign, add contacts, then start it.

# 1. Create
curl -X POST https://api.ontora.com/v1/interviews \
  -H "X-API-Key: $ONTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q2 facility-ops interviews",
    "goal": "Map current scheduling workflows and pain points",
    "channel": "in_app_chat",
    "topics": [
      {"name": "Daily scheduling", "goal": "Understand how shifts are assigned"}
    ]
  }'

# 2. Add contacts (returns interview_id from step 1)
curl -X POST https://api.ontora.com/v1/interviews/$ID/contacts/bulk \
  -H "X-API-Key: $ONTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contacts": [{"name": "Sam", "email": "sam@example.com"}]}'

# 3. Start the campaign
curl -X POST https://api.ontora.com/v1/interviews/$ID/start \
  -H "X-API-Key: $ONTORA_API_KEY"

4. Pull the synthesis report

Once the campaign has completed conversations, fetch the rendered report as Markdown:

curl https://api.ontora.com/v1/interviews/$ID/export/report \
  -H "X-API-Key: $ONTORA_API_KEY" \
  -o report.md

Or get individual transcripts as a ZIP:

curl https://api.ontora.com/v1/interviews/$ID/export/transcripts \
  -H "X-API-Key: $ONTORA_API_KEY" \
  -o transcripts.zip

5. Ask a question across the campaign

Use the GraphRAG query endpoint to run grounded questions over every transcript:

curl -X POST https://api.ontora.com/v1/interviews/$ID/graph/query \
  -H "X-API-Key: $ONTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What are the most painful manual steps in the scheduling workflow?"}'

The response includes the answer, common patterns, and dissenting opinions across respondents.

Get started

Core concepts

Guides

MCP server

CLI

Webhooks

1. Create an API key

2. Authenticate

3. Launch a campaign

4. Pull the synthesis report

5. Ask a question across the campaign

What’s next

Subscribe to webhooks

Connect Claude or Cursor

​1. Create an API key

​2. Authenticate

​3. Launch a campaign

​4. Pull the synthesis report

​5. Ask a question across the campaign

​What’s next

Subscribe to webhooks

Connect Claude or Cursor

1. Create an API key

2. Authenticate

3. Launch a campaign

4. Pull the synthesis report

5. Ask a question across the campaign

What’s next