Skip to content

Quickstart

This walks the entire loop: name a target, review its prompts, run a measurement, and read the result. Everything here uses one API key and no SDK.

You need a bkt_ key from Settings → Developer & AI → API keys, on a paid plan (a free plan reaches only the Zapier endpoints). See Authentication if you do not have one yet.

Terminal window
export BEKET_API_KEY="bkt_..."
1 POST /audits name the target → auditId, status PENDING
2 POST /audits/:id/prepare explore + profile → 202; poll to AWAITING_CONFIG
3 POST /audits/:id/prompts/generate generate prompts → costs money, once per audit
4 GET /audits/:id/config-options what your plan allows
5 POST /audits/:id/start begin measuring → 202 + estimate
6 GET /audits/:id/run poll → respect retryAfterMs
7 GET /audits/:id/snapshots a run finished → cheap, poll this over time
8 POST /graphql read the report → one section at a time

Steps 1–5 are setup and happen once. Steps 7–8 are the part a long-running integration repeats.

  1. The fastest path is a bare domain. To map a market instead of a brand, send topic in place of domain.

    Terminal window
    curl -X POST "https://api.beket.ai/api/v1/audits" \
    -H "Authorization: Bearer $BEKET_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"domain": "example.com"}'

    The audit is created PENDING. Nothing is measured and nothing is billed yet.

  2. Preparing explores the target, infers the brand profile, and selects the angles. Everything after this depends on it.

    Terminal window
    curl -X POST "https://api.beket.ai/api/v1/audits/AUDIT_ID/prepare" \
    -H "Authorization: Bearer $BEKET_API_KEY"
    # 202 Accepted. Now poll until the status reaches AWAITING_CONFIG:
    curl "https://api.beket.ai/api/v1/audits/AUDIT_ID" \
    -H "Authorization: Bearer $BEKET_API_KEY"

    This one also costs money — it crawls the target and runs an LLM. Prepare an audit once; do not re-prepare one that is past PENDING, because that redoes the work and clobbers configuration you have already set.

  3. Prompts are the questions the audit asks the AI surfaces. They are generated from the brand profile, once per audit.

    Terminal window
    curl -X POST "https://api.beket.ai/api/v1/audits/AUDIT_ID/prompts/generate" \
    -H "Authorization: Bearer $BEKET_API_KEY"

    The audit is now awaiting prompt review. Read the set back with GET /audits/{auditId}/prompts — maxQueries there is your plan’s ceiling on how many may be selected, and selecting more is rejected when the run starts, not when you select them.

  4. Connector availability and the connector ceiling are plan-dependent. Reading this first is cheaper than having a selection silently clamped.

    Terminal window
    curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/config-options" \
    -H "Authorization: Bearer $BEKET_API_KEY"
  5. Terminal window
    curl -X POST "https://api.beket.ai/api/v1/audits/AUDIT_ID/start" \
    -H "Authorization: Bearer $BEKET_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"connectorTypes": ["OPENAI"]}'

    This answers 202, not 200 — the run is enqueued, not finished. The response carries an estimate of the run’s size and, importantly, effectiveConnectors and droppedConnectors: your selection is clamped to the plan’s ceiling rather than rejected, so read back what was actually kept instead of assuming you got what you asked for.

  6. Use the server’s own guidance on when to poll again. retryAfterMs varies with the phase the run is in, and polling faster does not make a run finish sooner.

    Terminal window
    curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/run" \
    -H "Authorization: Bearer $BEKET_API_KEY"
  7. A completed run produces a snapshot. Snapshots are the cheap thing to watch: each carries summary metrics and reportAvailable, and the list is cursor-paginated newest-first.

    Terminal window
    curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/snapshots?limit=1" \
    -H "Authorization: Bearer $BEKET_API_KEY"

    The report’s written analysis lands shortly after the run. GET /audits/{auditId}/synthesis answers llm: true once it has.

  8. The report is read through GraphQL, one section at a time — note the path is /graphql at the API’s origin, not under /api/v1:

    Terminal window
    curl -X POST "https://api.beket.ai/graphql" \
    -H "Authorization: Bearer $BEKET_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "query ($auditId: String!) { reportOverview(auditId: $auditId) { brandName executiveSummary headline { visibility shareOfVoice } } }", "variables": {"auditId": "AUDIT_ID"}}'

    Reading the report lists every section — winnable prompts, the content roadmap, the market leaderboard — and how each one refuses.

Once the first run is done, the recurring shape of an integration is small:

poll GET /audits/:id/snapshots ← cheap, summary metrics per snapshot
↓ a new snapshot appeared
diff GET /audits/:id/snapshots/compare ← what moved since the one before
read POST /graphql ← the report sections you show

The report changes only when a run completes, so reading it on a timer is wasted transfer on both sides. Poll the snapshot list, notice a new entry, and read then.

For “what moved since last time”, GET /audits/{auditId}/snapshots/compare?b=SNAPSHOT_ID compares a snapshot with the baseline it was taken against: prompts, metrics, competitors, cited sources and recommendations. Send its ETag back as If-None-Match and an unchanged comparison costs a 304.

For the raw material — every answer, one row each — page through GET /audits/{auditId}/answers/export with a date range, or fetch the same as CSV from answers/export.csv.