Skip to content

Configuration

What an audit measures against: competitors, languages and location, and the daily snapshot. Beta: these shapes may change; see the changelog.

GET /angles

The active angles — the categories prompts are filed under — in display order.

Terminal window
curl "https://api.beket.ai/api/v1/angles" \
-H "Authorization: Bearer $BEKET_API_KEY"
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.anglesobject[]yes
data.angles[].idstringyes
data.angles[].labelstringyes
data.angles[].groupstring
{
"success": true,
"data": {
"angles": [
{
"id": "angle-winnable-queries-int-test",
"label": "winnable int test",
"group": "AWARENESS_DISCOVERY"
},
{
"id": "RETENTION_EXPANSION",
"label": "Retention / Expansion",
"group": "EXPANSION"
}
]
}
}

GET /audits/{auditId}/changes

Who changed the audit’s profile, competitors, prompts, topics, facts, engines or targeting, and what changed, newest first. At most 200.

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/changes" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.changesobject[]yes
data.changes[].idstringyes
data.changes[].entityType“profile” | “competitor” | “query” | “connectors” | “targeting” | “topic” | “brandFact”yes
data.changes[].action“create” | “update” | “delete”yes
data.changes[].fieldstring | nullyesThe field edited; null for a whole-row create or delete.
data.changes[].oldValueobjectyesThe value before, in the field’s own JSON shape.
data.changes[].newValueobjectyesThe value after, in the field’s own JSON shape.
data.changes[].actorEmailstring | nullyes
data.changes[].actingAsOrgIdstring | nullyesSet when Beket support made the change on your behalf.
data.changes[].createdAtstringyes
{
"success": true,
"data": {
"changes": [
{
"id": "fca6152b-ff37-45b4-9b30-84f1e4ac9539",
"entityType": "brandFact",
"action": "update",
"field": "claim",
"oldValue": {
"id": "0cbd0f1b-9921-4eb3-ac83-38789de11596",
"state": "draft",
"value": "Open 24 hours"
},
"newValue": {
"id": "0cbd0f1b-9921-4eb3-ac83-38789de11596",
"state": "rejected",
"value": "Open 24 hours"
},
"actorEmail": "redacted@example.com",
"actingAsOrgId": null,
"createdAt": "2026-10-26T19:53:05.436Z"
},
{
"id": "ff168e1d-ec64-4cf7-958b-f36c9a8e6e43",
"entityType": "brandFact",
"action": "update",
"field": "claim",
"oldValue": null,
"newValue": {
"id": "c47baa43-276c-45d4-93d5-09a3e26a7580",
"state": "confirmed",
"value": "Family owned since 1998"
},
"actorEmail": "redacted@example.com",
"actingAsOrgId": null,
"createdAt": "2026-10-26T19:53:05.424Z"
}
]
}
}

GET /audits/{auditId}/competitors

The competitors this audit compares the brand against — the list a person curated. Names a run discovered on its own are not in it.

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/competitors" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
successbooleanyes
dataAuditCompetitorsyes
{
"success": true,
"data": {
"competitors": []
}
}

PATCH /audits/{auditId}/competitors

Replaces the curated list. Entries are trimmed, their domains normalized, and duplicates by name collapsed, so the response may hold fewer than you sent. Mention metrics are recomputed in the background. Market audits have no competitors to edit.

Terminal window
curl -X PATCH "https://api.beket.ai/api/v1/audits/AUDIT_ID/competitors" \
-H "Authorization: Bearer $BEKET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"competitors":[]}'
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
competitorsobject[]yes
competitors[].namestringyes
competitors[].domainstring | nullThe competitor’s site, like domain.com. Blank or null when it has none; anything else that is not a plausible host is a 400.
competitors[].sizeTier“startup” | “smb” | “mid-market” | “enterprise” | “unknown”
competitors[].classification“direct” | “indirect” | “not-competitor”
competitors[].evidencestring | null
FieldTypeRequiredDescription
successbooleanyes
dataAuditCompetitorsyes
{
"success": true,
"data": {
"competitors": [
{
"name": "Rival",
"domain": "rival.com",
"sizeTier": "unknown"
}
]
}
}

POST /audits/{auditId}/entities/import

Applies many edits from a CSV with the header name,type,merge_into, at most 500 rows and 200,000 characters. All or none: if any row is refused, nothing is applied and the 422 lists the refused rows in error.details.rows.

Terminal window
curl -X POST "https://api.beket.ai/api/v1/audits/AUDIT_ID/entities/import" \
-H "Authorization: Bearer $BEKET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"csv":"<csv>"}'
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
csvstringyes
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.rowsobject[]yes
data.rows[].lineintegeryes
data.rows[].namestringyes
data.rows[].status“applied” | “unchanged”yes
{
"success": true,
"data": {
"rows": [
{
"line": 2,
"name": "Gadgetly",
"status": "applied"
}
]
}
}

PUT /audits/{auditId}/entities/merge

Records the name as another spelling of the competitor into, so its mentions count for that competitor. into: null unmerges it.

Terminal window
curl -X PUT "https://api.beket.ai/api/v1/audits/AUDIT_ID/entities/merge" \
-H "Authorization: Bearer $BEKET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"<name>","into":"<into>"}'
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
namestringyes
intostring | nullyes
FieldTypeRequiredDescription
successbooleanyes
dataEntityEditResultyes
{
"success": true,
"data": {
"nameKey": "n:acmelabs",
"outcome": "applied"
}
}

GET /audits/{auditId}/entities/review

The names AI answers mention that are neither the brand nor a curated competitor, most mentioned first, at most 100 per page. Each carries the competitors it may be another spelling of.

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/entities/review?q=Q&status=STATUS" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
qquerynostringOnly names containing this text.
statusqueryno“pending” | “overridden” | “all”pending (the default): names not yet given a type; overridden: names given one; all: both.
offsetquerynointegerNames to skip. Default 0.
limitquerynointegerNames per page, 1–100. Default 100.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.entitiesobject[]yes
data.entities[].nameKeystringyes
data.entities[].namestringyesThe most common spelling.
data.entities[].mentionsintegeryes
data.entities[].answersintegeryes
data.entities[].kind“brand” | “competitor” | “place” | “ai_platform” | “person” | “publisher” | “generic”yes
data.entities[].override“place” | “ai_platform” | “person” | “publisher” | “generic” | nullyes
data.entities[].suggestionsobject[]yes
data.entities[].suggestions[].namestringyes
data.entities[].suggestions[].reason“same_name” | “contains_name”yes
data.totalintegeryes
data.offsetintegeryes
data.limitintegeryes
{
"success": true,
"data": {
"entities": [
{
"kind": "generic",
"name": "Acme Labs",
"answers": 1,
"nameKey": "n:acmelabs",
"mentions": 2,
"override": null,
"suggestions": []
},
{
"kind": "generic",
"name": "WidgetHub",
"answers": 1,
"nameKey": "n:widgethub",
"mentions": 2,
"override": null,
"suggestions": []
}
],
"total": 2,
"offset": 0,
"limit": 100
}
}

PUT /audits/{auditId}/entities/type

Marks a name as something other than a competitor, so the report stops counting it as one. kind: null clears the override.

Terminal window
curl -X PUT "https://api.beket.ai/api/v1/audits/AUDIT_ID/entities/type" \
-H "Authorization: Bearer $BEKET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"<name>","kind":"<kind>"}'
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
namestringyes
kind“place” | “ai_platform” | “person” | “publisher” | “generic” | nullyes
FieldTypeRequiredDescription
successbooleanyes
dataEntityEditResultyes
{
"success": true,
"data": {
"nameKey": "n:widgethub",
"outcome": "applied"
}
}

Suggest the brand’s Google Business Profile

Section titled “Suggest the brand’s Google Business Profile”

GET /audits/{auditId}/profile/gbp-suggestion

A best guess at the brand’s own Google Business Profile, looked up on Google Maps from its name and city, for you to confirm. null when nothing matched, when the profile already names one, or when the audit has no brand profile — never an error.

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/profile/gbp-suggestion" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.suggestionobject | nullyes
data.suggestion.placeIdstringyes
data.suggestion.namestringyes
data.suggestion.formattedAddressstring | null
data.suggestion.phonestring | null
{
"success": true,
"data": {
"suggestion": null
}
}

PATCH /audits/{auditId}/schedule

Toggles the daily snapshot and sets the time zone whose night it runs in. The zone applies whether or not a schedule exists yet; the toggle needs one, which an audit gets after its first full run. The schedule fields are absent until then.

Terminal window
curl -X PATCH "https://api.beket.ai/api/v1/audits/AUDIT_ID/schedule" \
-H "Authorization: Bearer $BEKET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"snapshotEnabled":true}'
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
snapshotEnabledboolean
snapshotTimeZonestring | nullThe time zone whose night the daily snapshot runs in, as an IANA name (Europe/Berlin). null removes the override, so the organization’s zone applies.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.auditIdstring
data.intervalHoursinteger
data.snapshotLabelPrefixstring | null
data.optionsobjectThe run options each scheduled run uses.
data.createdAtstring
data.nextRunAtstring
data.runCountinteger
data.lastErrorstring | null
data.snapshotEnabledbooleanWhether the daily snapshot runs.
data.snapshotTimeZonestring | nullyesThis audit’s own zone override; null when it has none.
data.resolvedSnapshotTimeZonestringyesThe zone that actually applies — the override, or the organization’s.
{
"success": true,
"data": {
"snapshotTimeZone": "America/New_York",
"resolvedSnapshotTimeZone": "America/New_York"
}
}

GET /audits/{auditId}/targeting

The languages prompts are written in and the location answers are requested from.

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/targeting" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
successbooleanyes
dataAuditTargetingyes
{
"success": true,
"data": {
"languages": [],
"locations": [],
"languageSuggestions": [
"EN"
],
"locationSuggestions": []
}
}

PATCH /audits/{auditId}/targeting

Replaces the languages and location. Languages may be sent as names (English) or codes; they are stored and returned as ISO 639-1 codes. Applies to prompts generated and runs started after the change.

Terminal window
curl -X PATCH "https://api.beket.ai/api/v1/audits/AUDIT_ID/targeting" \
-H "Authorization: Bearer $BEKET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"languages":[]}'
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
languagesstring[]
locationsstring[]
FieldTypeRequiredDescription
successbooleanyes
dataAuditTargetingyes
{
"success": true,
"data": {
"languages": [
"EN"
],
"locations": [
"United States"
],
"languageSuggestions": [
"EN"
],
"locationSuggestions": []
}
}
FieldTypeRequiredDescription
competitorsobject[]yes
competitors[].namestringyes
competitors[].domainstring | nullyes
competitors[].sizeTier“startup” | “smb” | “mid-market” | “enterprise” | “unknown”
competitors[].classification“direct” | “indirect” | “not-competitor”not-competitor is a person’s verdict; a run never overrides it.
competitors[].evidencestring | nullWhy this is a competitor. Absent until a run surfaces evidence.
FieldTypeRequiredDescription
languagesstring[]yesISO 639-1 codes the prompts are written in.
locationsstring[]yesThe location answers are requested from. At most one.
languageSuggestionsstring[]yesLanguages that fit this audit, for a picker.
locationSuggestionsstring[]yesLocations that fit this audit, for a picker.
FieldTypeRequiredDescription
nameKeystring | nullyesThe key the name files under.
outcome“applied” | “unchanged”yesunchanged when the name already read that way; nothing was written.