Endpoints

Conventions

All paths are relative to https://teddit.io/api. Send the key as described under Authentication.

• Access is the lowest key role that may call the endpoint: viewer (a Read key), member (Read + edit) or admin (Read + scan). A higher role may always call it too.
• :orgId is the workspace id from GET /whoami. :id is a site id from GET /orgs/:orgId/projects.
• Period parameters. The report endpoints take period (day, week, month or quarter; default week) and start (any date inside the period you want, YYYY-MM-DD; default the latest period). Their responses repeat period and start and list every period that has data in periods.
• In responses, “named” is mentioned, “linked” is ownCited, your place is brandRank, visibility is the visibility score, and an assistant is a provider with the key openai, anthropic, perplexity, gemini, google_aio or google_ai_mode.

The MCP tools return the same data, so a tool’s description also describes the matching endpoint.

Workspace

Add a site takes name and url (both required), and optionally industry, brandTerms (other names, up to 50), competitors (objects with name and domain, up to 50), language (default English) and location (default United States).

Invite takes email and role (viewer, member or admin; default member). Change a role takes role. What an admin may and may not do to other members is on the Roles page.

Not available to keys: everything under /auth and /account, creating, deleting and leaving workspaces, renaming a workspace (PATCH /orgs/:orgId, Owner only), topping up and invoices (Owner only) and managing keys (/orgs/:orgId/tokens).

Sites

Change settings takes any of these fields:

• name, brandTerms: the brand name and its other names. Changing either re-reads all stored answers; the response then carries a reanalysis summary.
• industry, language, location (the country).
• scanFrequencyDays (1 to 365): the gap between scheduled scans.
• monthlyCapUsd: the site’s monthly cap in US dollars. null or 0 removes it.
• scanSettings: the saved scan settings, replaced as a whole. An object with providers (assistant keys; left out means all connected), models (assistant key to model), category, budgetUsd (the most one scan may cost; 0 means twice its estimate) and skipAtCap (false lets scans start even when the monthly cap is spent).

Schedule takes enabled (true or false) and optionally batch (batch pricing for scans with the saved settings; on unless you switch it off). With it on, ChatGPT, Claude and Gemini answer for a lower price within hours; the other assistants answer at once. Switching the schedule on sets the first scan for the next night (UTC).

Deleting a site, with its prompts, scans and answers, is for a signed-in Owner and is not available to keys.

Reports

All of these are GET, need viewer, and take the period parameters.

curl "https://teddit.io/api/projects/12/report?period=month&start=2026-09-15" \
  -H "Authorization: Bearer tdt_…"

How the numbers in these responses are computed: Metrics and statuses.

Prompts and categories

The list and the export take the same query parameters: q (text search), category, status (draft, active, paused), intent, verdict (named, lost, cited, missing, failed), competitor (a tracked competitor’s name), stability (held, volatile, lost) and scanned (yes, never). The list also takes sort (created, text, category, rank, scanned), dir (asc, desc), page, perPage (5 to 200, default 20) and the period parameters, which set what one history square stands for.

Add takes text (3 to 500 characters, required), category or categories (a list of up to 8), intent (default informational), funnel (default awareness) and status (default active). A text that is already tracked answers 409. Edit takes the same fields, all optional; categories replaces the whole list.

Bulk takes ids (1 to 5000) and status, category or delete: true. Deleting a prompt deletes its answers.

Import takes contents (the text of the file, up to 2,000,000 characters), status (default draft) and dryRun. It returns rows, created, updated, skipped and categories. The file format is on the Importing prompts page.

One answer takes engine (an assistant key; default the first assistant that answered) or r (the id of a past answer, taken from the prompt’s results).

Merge categories takes names (the categories to fold) and into (the name they become). One name is a rename, several are a merge, and an empty into removes the categories from their prompts.

Competitors and pages

Track takes name (required), domain, aliases (other names, up to 30), color and logo. Change takes the same fields, all optional: only what you send changes, aliases replaces the whole list, and domain: null removes the domain. All three competitor endpoints re-read the stored answers when the names change and return the result as reanalysis.

Pages takes q, section (the first part of the path), shown (yes or no), page and perPage (5 to 200, default 50).

Scans

Estimate and start take the same body. Every field is optional:

• providers: assistant keys. Empty means every connected assistant.
• promptIds: a chosen set of prompts. Empty means every active prompt. Prompts that are not active are skipped.
• category: scan one category.
• sample: scan this many prompts, drawn at random.
• models: assistant key to model, from the options in scan-options. chatgpt-app and gemini-app (fast: answered at once) and chatgpt-app-queue and gemini-app-queue (slow and cheaper: a few minutes) take the answer as the app shows it.
• batch: batch pricing. ChatGPT, Claude and Gemini answer for a lower price within hours; the other assistants answer at once.
• saved: true takes the assistants, models and category from the site’s saved scan settings instead of from this request. On start it takes the saved limit per scan too.
• Start only: budgetUsd (stop once the scan has cost this much; left out, twice its estimate) and label.

Estimate returns prompts, answers, cost and formatted. Start returns the scan and answers 400 with the reason when the scan cannot start. The reasons, and how cost is counted, are on the Balance and spending limits page.

One scan takes tab (all, notNamed, competitorsOnly, errors), engine (an assistant key) and page. Scan statuses are queued, running, cancelling, cancelled, done and failed.

A complete example

Find the site, add a prompt, price a scan of one category, run it and read the result. Starting the scan needs a Read + scan key.

KEY="tdt_…"
API="https://teddit.io/api"

# 1. Which workspace is this key for?
curl "$API/whoami" -H "Authorization: Bearer $KEY"
#    → "org": { "id": 3, … }

# 2. The sites of the workspace
curl "$API/orgs/3/projects" -H "Authorization: Bearer $KEY"
#    → "projects": [{ "id": 12, "domain": "brightloop.example", … }]

# 3. Add a prompt
curl -X POST "$API/projects/12/prompts" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"text": "What does email automation cost for 10,000 contacts?", "category": "pricing", "intent": "commercial"}'

# 4. What would a scan of that category cost?
curl -X POST "$API/projects/12/scans/estimate" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"category": "pricing"}'
#    → { "prompts": …, "answers": …, "cost": …, "formatted": "$…" }

# 5. Run it, and stop at 2 dollars
curl -X POST "$API/projects/12/scans" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"category": "pricing", "budgetUsd": 2}'

# 6. Follow it until "run" is null
curl "$API/projects/12/scans/live" -H "Authorization: Bearer $KEY"

# 7. Read this week's report
curl "$API/projects/12/report" -H "Authorization: Bearer $KEY"