Update a visibility setup

Records an edit as a NEW immutable setup version and returns the setup in the same shape as GET. Content edits (country, language, platform_ids, prompts, together with optional topics and competitors) always replace the complete measurement configuration; a partial content body is rejected. A name-only body renames the setup without a new version. Historical scans keep the version they used.

PATCH/visibility-setups/{setup_id}

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.

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.

Path parameters

setup_idstring<uuid>required

Request body

requiredapplication/json

namestring

min length 1 · max length 200

countrystring

min length 2 · max length 2

languagestring

min length 2 · max length 10

platform_idsstring[]

min items 1 · max items 20

topicsobject[]

max items 20

Show properties

Array of object

titlestringrequired

min length 1 · max length 200

promptsobject[]

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

200

The saved setup after the edit

successbooleanrequired

dataSetupObjectrequired

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

created_atstring<date-time>required

matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

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

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 PATCH 'https://api.zaraftis.com/v1/visibility-setups/497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "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"
    }
  ]
}'

const response = await fetch("https://api.zaraftis.com/v1/visibility-setups/497f6eca-6276-4993-bfeb-53cbbbba6f08", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"name\": \"string\",\n  \"country\": \"st\",\n  \"language\": \"string\",\n  \"platform_ids\": [\n    \"string\"\n  ],\n  \"topics\": [\n    {\n      \"title\": \"string\"\n    }\n  ],\n  \"prompts\": [\n    {\n      \"text\": \"string\",\n      \"topic_title\": \"string\"\n    }\n  ],\n  \"competitors\": [\n    {\n      \"name\": \"string\",\n      \"url\": \"http://example.com\"\n    }\n  ]\n}"
});

import requests

response = requests.patch(
    "https://api.zaraftis.com/v1/visibility-setups/497f6eca-6276-4993-bfeb-53cbbbba6f08",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"name\": \"string\",\n  \"country\": \"st\",\n  \"language\": \"string\",\n  \"platform_ids\": [\n    \"string\"\n  ],\n  \"topics\": [\n    {\n      \"title\": \"string\"\n    }\n  ],\n  \"prompts\": [\n    {\n      \"text\": \"string\",\n      \"topic_title\": \"string\"\n    }\n  ],\n  \"competitors\": [\n    {\n      \"name\": \"string\",\n      \"url\": \"http://example.com\"\n    }\n  ]\n}",
)

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"
      }
    ],
    "created_at": "2019-08-24T14:15:22Z"
  },
  "request_id": "string"
}

{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true,
    "details": {},
    "field_errors": [
      {
        "field": "string",
        "code": "required",
        "message": "string"
      }
    ]
  },
  "request_id": "string"
}

{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true,
    "details": {},
    "field_errors": [
      {
        "field": "string",
        "code": "required",
        "message": "string"
      }
    ]
  },
  "request_id": "string"
}

{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true,
    "details": {},
    "field_errors": [
      {
        "field": "string",
        "code": "required",
        "message": "string"
      }
    ]
  },
  "request_id": "string"
}