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

Create a visibility setup

Saves the brand, prompts, platforms, and competitors that scans measure. The body needs creation_mode (manual or auto) and exactly one of brand_id or new_brand. Manual setups are free and return 201. Auto setups are not available yet and answer 501 not_implemented. With new_brand, a retry with the same Idempotency-Key reuses the brand the first request created.

POST/visibility-setups
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
creation_modestringrequired
Allowed:manualauto
brand_idstring<uuid>
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)$
new_brandobject
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
namestring
min length 1 · max length 200
countrystringrequired
min length 2 · max length 2
languagestringrequired
min length 2 · max length 10
platform_idsstring[]required
min items 1 · max items 20
topicsobject[]
max items 20
Show properties
Array of object
titlestringrequired
min length 1 · max length 200
promptsobject[]required
min items 1 · max items 200
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
Responses
201

Saved Manual setup

successbooleanrequired
dataSetupCreatedObjectrequired
Show properties
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)$
namestring | nullrequired
Show properties
Any of:
string
string
null
null
brandobjectrequired
Show properties
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)$
urlstringrequired
min length 1
countrystringrequired
min length 2 · max length 2
languagestringrequired
min length 2 · max length 10
creation_modestringrequired
Allowed:manualauto
statusstringrequired
Allowed:activearchived
setup_checksumstringrequired
min length 1
current_versionintegerrequired
min 1 · max 9007199254740991
platformsstring[]required
topicsobject[]required
Show properties
Array of object
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)$
titlestringrequired
min length 1
promptsobject[]required
Show properties
Array of object
idstring<uuid> | nullrequired
Show properties
Any of:
string<uuid>
string<uuid>
null
null
textstringrequired
min length 1
topic_idstring<uuid> | nullrequired
Show properties
Any of:
string<uuid>
string<uuid>
null
null
competitorsobject[]required
Show properties
Array of object
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)$
namestringrequired
min length 1
urlstringrequired
min length 1
request_idstringrequired
min length 1
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
404

not_found: unknown id, or an id this key cannot see

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/visibility-setups' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Idempotency-Key: string' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "creation_mode": "manual",
  "brand_id": "1bb61461-e5e3-4ebb-8cc6-5b0c37f1b7da",
  "new_brand": {
    "url": "http://example.com",
    "name": "string",
    "aliases": [
      "string"
    ],
    "country": "st",
    "language": "string"
  },
  "name": "string",
  "country": "st",
  "language": "string",
  "platform_ids": [
    "string"
  ],
  "topics": [
    {
      "title": "string"
    }
  ],
  "prompts": [
    {
      "text": "string",
      "topic_title": "string"
    }
  ],
  "competitors": [
    {
      "name": "string",
      "url": "http://example.com"
    }
  ]
}'
Response
{
  "success": true,
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "brand": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "url": "string"
    },
    "country": "st",
    "language": "string",
    "creation_mode": "manual",
    "status": "active",
    "setup_checksum": "string",
    "current_version": 1,
    "platforms": [
      "string"
    ],
    "topics": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "title": "string"
      }
    ],
    "prompts": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "text": "string",
        "topic_id": "646807af-5da6-43aa-83d3-8ac1d15ab4e5"
      }
    ],
    "competitors": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string",
        "url": "string"
      }
    ]
  },
  "request_id": "string"
}

Was this page helpful?