Skip to content

Actions

The work an audit recommends and the record of doing it. Beta: these shapes may change; see the changelog.

GET /audits/{auditId}/action-items/counts

How many items are still suggested, by type. counts is null until a run has finished.

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/action-items/counts" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.countsobject | nullyes
data.counts.totalintegeryes
data.counts.offPageintegeryes
data.counts.onPageintegeryes
data.counts.technicalintegeryes
{
"success": true,
"data": {
"counts": null
}
}

GET /audits/{auditId}/action-items/custom

Items the team added to the list, newest first. At most 200.

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/action-items/custom" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.itemsUserActionItem[]yes
{
"success": true,
"data": {
"items": [
{
"itemKey": "offpage:pitch-rival-com-roundup",
"title": "Pitch the widget roundup on rival.com",
"subtitle": null,
"type": "off-page",
"impact": "high"
}
]
}
}

POST /audits/{auditId}/action-items/custom

Adds an item to the list — a recommendation from the report, say — as TODO. Adding one with the key of an existing item replaces its content and keeps its status.

Terminal window
curl -X POST "https://api.beket.ai/api/v1/audits/AUDIT_ID/action-items/custom" \
-H "Authorization: Bearer $BEKET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"itemKey":"<itemKey>","title":"<title>","type":"<type>","impact":"<impact>"}'
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
itemKeystringyes
titlestringyes
subtitlestring
type“on-page” | “off-page” | “technical”yes
impact“low” | “medium” | “high”yes
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.itemUserActionItemyes
{
"success": true,
"data": {
"item": {
"itemKey": "offpage:pitch-rival-com-roundup",
"title": "Pitch the widget roundup on rival.com",
"subtitle": null,
"type": "off-page",
"impact": "high"
}
}
}

DELETE /audits/{auditId}/action-items/custom/{itemKey}

Removes an item the team added. Removing one that does not exist succeeds.

Terminal window
curl -X DELETE "https://api.beket.ai/api/v1/audits/AUDIT_ID/action-items/custom/ITEM_KEY" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
itemKeypathyesstringThe item’s key.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.itemKeystringyes
data.removedbooleanyes
{
"success": true,
"data": {
"itemKey": "offpage:pitch-rival-com-roundup",
"removed": true
}
}

GET /audits/{auditId}/action-items/links

The URLs the team attached to show work shipped, each with its newest check: whether the page is live in the crawl, cited by AI answers, or ranking. At most 500.

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/action-items/links" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.linksActionItemLink[]yes
{
"success": true,
"data": {
"links": [
{
"id": "d2a2ec00-64bb-4539-b6fe-59bbe4586a53",
"itemKey": "technical:add-faq-schema",
"url": "https://example.com/faq",
"label": "FAQ page",
"firstVerifiedAt": null,
"createdAt": "2026-10-26T19:53:04.869Z",
"outcome": null
}
]
}
}

POST /audits/{auditId}/action-items/links

Attaches an http(s) URL to an item and checks it against the newest snapshot straight away. Beket never fetches the URL; the check reads the run’s data. outcome is null when there is no snapshot yet or the check failed.

Terminal window
curl -X POST "https://api.beket.ai/api/v1/audits/AUDIT_ID/action-items/links" \
-H "Authorization: Bearer $BEKET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"itemKey":"<itemKey>","url":"<url>"}'
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
itemKeystringyes
urlstringyesAn absolute http(s) URL.
labelstring
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.linkActionItemLinkyes
{
"success": true,
"data": {
"link": {
"id": "35e17430-c4ad-4a24-90f8-aa488cb2d915",
"itemKey": "technical:add-faq-schema",
"url": "https://example.com/pricing",
"label": "Pricing page",
"firstVerifiedAt": null,
"createdAt": "2026-10-26T19:53:05.505Z",
"outcome": {
"crawlVisible": null,
"crawlDetail": "not in this crawl yet",
"crawlAgeDays": null,
"cited": false,
"domainCited": null,
"ranking": false,
"position": null,
"checkedAt": "2026-10-26T19:53:05.512Z"
}
}
}
}

DELETE /audits/{auditId}/action-items/links/{linkId}

Removes a link. Removing one that does not exist succeeds.

Terminal window
curl -X DELETE "https://api.beket.ai/api/v1/audits/AUDIT_ID/action-items/links/LINK_ID" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
linkIdpathyesstringThe link’s id.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.linkIdstringyes
data.removedbooleanyes
{
"success": true,
"data": {
"linkId": "35e17430-c4ad-4a24-90f8-aa488cb2d915",
"removed": true
}
}

GET /audits/{auditId}/action-items/priority

The few suggested items worth doing first, ranked, with the technical quick wins and two totals. priority is null until a run has finished.

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/action-items/priority" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.priorityobject | nullyes
data.priority.itemsobject[]yesAt most 5, best first.
data.priority.items[].keystringyes
data.priority.items[].titlestringyes
data.priority.items[].domainstring | null
data.priority.items[].type“on-page” | “off-page” | “technical”yes
data.priority.items[].impact“low” | “medium” | “high”yes
data.priority.items[].promptCountinteger
data.priority.items[].promptCountCappedbooleanThe count is a floor — show it as “5+”.
data.priority.items[].rivalCitedboolean
data.priority.items[].openTerritoryboolean
data.priority.items[].scorenumberyes
data.priority.items[].relatedintegerOther suggested items folded into this one (same domain).
data.priority.items[].hookobject | nullWhy it ranks: kind is cited, roundup, open_territory or low_hanging_fruit.
data.priority.quickWinsobjectyes
data.priority.quickWins.totalintegeryes
data.priority.quickWins.itemsobject[]yesAt most 10.
data.priority.quickWins.items[].keystringyes
data.priority.quickWins.items[].titlestringyes
data.priority.highImpactintegeryesSuggested items of high impact.
data.priority.totalSuggestedintegeryes
{
"success": true,
"data": {
"priority": null
}
}

POST /audits/{auditId}/action-items/quote

Asks the Beket team to price one off-site item — an engagement or citation-gap item. This contacts the Beket team, who reply by email and in the quote’s replies. Answers 201 for a new request and 200 with the existing one when the item was already requested. Needs a user’s API key: a request is answered to a person.

Terminal window
curl -X POST "https://api.beket.ai/api/v1/audits/AUDIT_ID/action-items/quote" \
-H "Authorization: Bearer $BEKET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"itemKey":"<itemKey>"}'
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
itemKeystringyes
notestring | null
FieldTypeRequiredDescription
successbooleanyes
dataActionItemQuoteResultyes

GET /audits/{auditId}/action-items/quotes

Every quote requested on this audit, with Beket’s replies.

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/action-items/quotes" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.quotesActionItemQuote[]yes
{
"success": true,
"data": {
"quotes": [
{
"id": "ebb4822e-e3a9-4270-8ec9-df946825336d",
"itemKey": "offpage:pitch-rival-com-roundup",
"status": "QUOTED",
"itemTitle": "Get listed in the rival.com widget roundup",
"itemSummary": "rival.com is cited for 3 prompts where Example Co is absent.",
"note": null,
"replies": [
{
"sentAt": "2026-10-20T12:00:00.000Z",
"sentBy": "clrecorderuser00000000001",
"message": "We can place this within two weeks.",
"outcome": "QUOTED",
"priceCents": 45000
}
],
"createdAt": "2026-10-26T19:53:04.872Z"
}
]
}
}

GET /audits/{auditId}/action-items/status

Every item the team moved off SUGGESTED. An item not listed is SUGGESTED.

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/action-items/status" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.statusesobject[]yes
data.statuses[].itemKeystringyes
data.statuses[].status“TODO” | “DONE” | “ARCHIVED”yes
data.statuses[].doneAtstring | nullyesWhen it was marked DONE.
data.statuses[].doneTitlestring | nullyesIts title when it was marked DONE.
data.statuses[].resultobject | nullyesWhat marking it done changed. null unless DONE.
data.statuses[].result.state“untracked” | “measuring” | “no-run” | “settled”yes
data.statuses[].result.measurableFromstringOnly while measuring: the first run that can show the effect.
data.statuses[].result.outcomeobjectOnly when settled: the before-and-after reading.
{
"success": true,
"data": {
"statuses": [
{
"itemKey": "technical:add-faq-schema",
"status": "DONE",
"doneAt": "2026-10-26T19:53:05.451Z",
"doneTitle": "Add FAQ schema to the pricing page",
"result": {
"state": "measuring",
"measurableFrom": "2026-11-02T19:53:05.451Z"
}
}
]
}
}

PATCH /audits/{auditId}/action-items/status

Moves one item to TODO, DONE or ARCHIVED, or back to SUGGESTED, which clears it. title is kept only on the move to DONE, so the item still lists after the report rewords it.

Terminal window
curl -X PATCH "https://api.beket.ai/api/v1/audits/AUDIT_ID/action-items/status" \
-H "Authorization: Bearer $BEKET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"itemKey":"<itemKey>","status":"<status>"}'
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
itemKeystringyes
status“SUGGESTED” | “TODO” | “DONE” | “ARCHIVED”yes
titlestring
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.itemKeystringyes
data.status“SUGGESTED” | “TODO” | “DONE” | “ARCHIVED”yes
{
"success": true,
"data": {
"itemKey": "technical:add-faq-schema",
"status": "DONE"
}
}

GET /audits/{auditId}/indexnow

The key the site hosts so search engines accept its IndexNow pings, and whether Beket has found it live.

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/indexnow" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.keystring | nullyesnull until a key is issued.
data.keyLocationstring | nullyesThe URL the key file must answer at.
data.hoststring | nullyesnull until the site is crawled.
data.verifiedAtstring | nullyes
data.filestring | nullyesThe path to host the key file at.
{
"success": true,
"data": {
"key": null,
"keyLocation": null,
"host": "example.com",
"verifiedAt": null,
"file": null
}
}

POST /audits/{auditId}/indexnow/verify

Issues a key if there is none, then fetches the key file from the site and records verifiedAt when it matches. verified: false means the file is not live yet — host contents at file.

Terminal window
curl -X POST "https://api.beket.ai/api/v1/audits/AUDIT_ID/indexnow/verify" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.verifiedbooleanyes
data.keystringyes
data.keyLocationstringyesThe URL the key file must answer at.
data.hoststringyes
data.verifiedAtstring | nullyesSet by this check when it matched, or by an earlier one.
data.filestringyesThe path to host the key file at.
data.contentsstringyesThe exact contents the file must hold.
FieldTypeRequiredDescription
idstringyes
itemKeystringyes
urlstringyes
labelstring | nullyes
firstVerifiedAtstring | nullyesThe first time a run found the link live or cited.
createdAtstringyes
outcomeobject | nullyesThe newest check against the latest snapshot; null until one ran.
outcome.crawlVisibleboolean | nullyesOn the audited site: present in the crawl and answering 2xx/3xx. null off-site.
outcome.crawlDetailstring | null
outcome.crawlAgeDaysinteger | nullAge of the crawl this was measured against.
outcome.citedboolean | nullyesAI answers cited this exact URL.
outcome.domainCitedboolean | nullAI answers cited its domain. Off-site links only.
outcome.rankingboolean | nullThe page ranks in search. On-site links only.
outcome.positioninteger | null
outcome.checkedAtstringyes
FieldTypeRequiredDescription
idstringyes
itemKeystringyes
status“REQUESTED” | “QUOTED” | “NEEDS_CALL” | “DECLINED”yes
itemTitlestringyesThe item as it read when the quote was requested.
itemSummarystring | null
notestring | null
repliesobject[]yesBeket’s answers, oldest first.
replies[].outcome“QUOTED” | “NEEDS_CALL” | “DECLINED”yes
replies[].priceCentsinteger | nullyesSet only on a QUOTED reply.
replies[].messagestringyes
replies[].sentBystring
replies[].sentAtstringyes
createdAtstringyes
FieldTypeRequiredDescription
quoteActionItemQuoteyes
FieldTypeRequiredDescription
itemKeystringyes
titlestringyes
subtitlestring | nullyes
type“on-page” | “off-page” | “technical”yes
impact“low” | “medium” | “high”yes