Skip to content
Zaraftis API
Esc
↑↓navigate↵open⌘Jpreview

Start a scan

Starts a paid scan of the chosen prompts on the chosen platforms and returns 202 right away. The response carries the scan id, a status_url and task reference to poll, the requested query counts, and the billing object with the reserved credits. Credits come only from the workspace wallet.

POST/scans
Authorization
AuthorizationBearer token · headerrequired

API key sent as Authorization: Bearer <key>. A key belongs to one workspace, has scopes, and can be limited to some brands.

or
AuthorizationOAuth2 access token · headerrequired

OAuth 2.1 sign-in (authorization code with PKCE) used by AI assistants that connect through the Zaraftis MCP server. Discovery URLs are at https://api.zaraftis.com/api/auth.

Header parameters
Idempotency-Keystringrequired

A new value, such as a UUID, for each new request. Send the same value to retry a request safely; see https://docs.zaraftis.com/conventions#safe-retries-with-idempotency-key.

min length 1 · max length 64
Request body
requiredapplication/json
Any of:
object
setup_idstring<uuid>required
matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
prompt_selectionobject
Show properties
Any of:
object
modestringrequired
object
modestringrequired
prompt_idsstring<uuid>[]required
min items 1 · max items 150
platform_selectionobject
Show properties
Any of:
object
modestringrequired
object
modestringrequired
platform_idsstring[]required
min items 1 · max items 20
response_detailstring
Allowed:compactdetailed
object
brand_idstring<uuid>required
matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
countrystringrequired
min length 2 · max length 2
languagestringrequired
min length 2 · max length 10
platform_idsstring[]required
min items 1 · max items 12
promptsobject[]required
min items 1 · max items 150
Show properties
Array of object
textstringrequired
min length 1 · max length 500
topic_titlestring | null
Show properties
Any of:
string
string
null
null
competitorsobject[]
max items 20
Show properties
Array of object
namestringrequired
min length 1 · max length 200
urlstring<uri>required
response_detailstring
Allowed:compactdetailed
object
new_brandobjectrequired
Show properties
urlstring<uri>required
namestring | null
Show properties
Any of:
string
string
null
null
aliasesstring[]
max items 50
countrystring
min length 2 · max length 2
languagestring
min length 2 · max length 10
countrystringrequired
min length 2 · max length 2
languagestringrequired
min length 2 · max length 10
platform_idsstring[]required
min items 1 · max items 12
promptsobject[]required
min items 1 · max items 150
Show properties
Array of object
textstringrequired
min length 1 · max length 500
topic_titlestring | null
Show properties
Any of:
string
string
null
null
competitorsobject[]
max items 20
Show properties
Array of object
namestringrequired
min length 1 · max length 200
urlstring<uri>required
response_detailstring
Allowed:compactdetailed
Responses
202

Accepted scan (reserved billing; poll status_url to terminal)

successbooleanrequired
dataobjectrequired

The response data

request_idRequestIdrequired
400

bad_request or validation_failed

successbooleanrequired
errorobjectrequired
Show properties
codestringrequired
messagestringrequired
retryablebooleanrequired
detailsobject
field_errorsobject[]
Show properties
Array of object
fieldstringrequired
codestringrequired
Allowed:requiredformattoo_smalltoo_largeunrecognized_keyinvalid
messagestringrequired
request_idRequestIdrequired
402

wallet_not_activated, insufficient_credits, or payment_action_required

successbooleanrequired
errorobjectrequired
Show properties
codestringrequired
messagestringrequired
retryablebooleanrequired
detailsobject
field_errorsobject[]
Show properties
Array of object
fieldstringrequired
codestringrequired
Allowed:requiredformattoo_smalltoo_largeunrecognized_keyinvalid
messagestringrequired
request_idRequestIdrequired
409

conflict, duplicate_url, or idempotency_conflict

successbooleanrequired
errorobjectrequired
Show properties
codestringrequired
messagestringrequired
retryablebooleanrequired
detailsobject
field_errorsobject[]
Show properties
Array of object
fieldstringrequired
codestringrequired
Allowed:requiredformattoo_smalltoo_largeunrecognized_keyinvalid
messagestringrequired
request_idRequestIdrequired
429

rate_limited: wait the Retry-After seconds

successbooleanrequired
errorobjectrequired
Show properties
codestringrequired
messagestringrequired
retryablebooleanrequired
detailsobject
field_errorsobject[]
Show properties
Array of object
fieldstringrequired
codestringrequired
Allowed:requiredformattoo_smalltoo_largeunrecognized_keyinvalid
messagestringrequired
request_idRequestIdrequired
Request
curl -X POST 'https://api.zaraftis.com/v1/scans' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Idempotency-Key: string' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "setup_id": "223e7533-659b-4438-b6f4-f841a5d7dfa9",
  "prompt_selection": {
    "mode": "all"
  },
  "platform_selection": {
    "mode": "all"
  },
  "response_detail": "compact"
}'
Response
{
  "success": true,
  "data": {},
  "request_id": "string"
}

Was this page helpful?