Create a brand

Creates a brand and starts reading its website to fill in its details. Returns 201 with the brand. A credential limited to a brand allowlist cannot create brands. A brand with the same URL or name already in the workspace answers 409 with details.existing_brand ({ brand_id, name }) for that existing brand.

POST/brands

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.

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

namestringrequired

min length 1 · max length 200

urlstring<uri>required

countrystring

min length 2 · max length 2 · default: "US"

languagestring

min length 2 · max length 10 · default: "en"

Responses

201

Created brand (public Brand shape in the success envelope)

successbooleanrequired

dataBrandObjectrequired

The public Brand shape (camelCase members, as served). organizationId identifies the owning workspace; status is the brand lifecycle vocabulary; siteContent carries the synthesis knowledge summary once the crawl completes.

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)$

organizationIdstringrequired

min length 1

namestringrequired

min length 1

urlstringrequired

min length 1

statusstringrequired

Allowed:pendingcrawlingprocessingtopics_readyconfirming_topicsgenerating_promptsreadyerror

crawlStartedAtstring<date-time> | nullrequired

Show properties

Any of:

string<date-time>

string<date-time>

null

null

competitorsDetectedAtstring<date-time> | nullrequired

Show properties

Any of:

string<date-time>

string<date-time>

null

null

descriptionstring | nullrequired

siteUrlsstring[] | nullrequired

Show properties

Any of:

string[]

Array of string

string

null

null

siteContentobject | nullrequired

Show properties

Any of:

object

whatItIsobjectrequired

Show properties

textstringrequired

sourcesstring[]required

whoItsForobjectrequired

Show properties

textstringrequired

sourcesstring[]required

verticalstringrequired

Allowed:ecommerce_dtcsaas_softwareservices_consultancymarketplace_platformmanufacturer_industrialcontent_mediaother

offeringsobjectrequired

Show properties

textstringrequired

sourcesstring[]required

buyingSituationsobjectrequired

Show properties

textstringrequired

sourcesstring[]required

howBuyersPayobjectrequired

Show properties

textstringrequired

sourcesstring[]required

whyChooseItobjectrequired

Show properties

textstringrequired

sourcesstring[]required

proofobject[]required

Show properties

Array of object

claimstringrequired

quotestringrequired

urlstringrequired

contentCoverageobjectrequired

Show properties

textstringrequired

sourcesstring[]required

null

null

crawlErrorstring | nullrequired

countrystringrequired

min length 2 · max length 2

languagestringrequired

min length 2 · max length 10

verticalstring | nullrequired

Show properties

Any of:

string

string

null

null

roleTypestring | nullrequired

companySizestring | nullrequired

onboardingStepstring | nullrequired

Show properties

Any of:

string

string

null

null

onboardingFlowstringrequired

Allowed:first_signupadd_brand

packExpandedAtstring<date-time> | nullrequired

Show properties

Any of:

string<date-time>

string<date-time>

null

null

createdAtstring<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))$

updatedAtstring<date-time>required

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

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

Request

curl -X POST 'https://api.zaraftis.com/v1/brands' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Idempotency-Key: string' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "url": "http://example.com",
  "country": "US",
  "language": "en"
}'

const response = await fetch("https://api.zaraftis.com/v1/brands", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Idempotency-Key": "string",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"name\": \"string\",\n  \"url\": \"http://example.com\",\n  \"country\": \"US\",\n  \"language\": \"en\"\n}"
});

import requests

response = requests.post(
    "https://api.zaraftis.com/v1/brands",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Idempotency-Key": "string",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"name\": \"string\",\n  \"url\": \"http://example.com\",\n  \"country\": \"US\",\n  \"language\": \"en\"\n}",
)

Response

{
  "success": true,
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "organizationId": "string",
    "name": "string",
    "url": "string",
    "status": "pending",
    "crawlStartedAt": "2019-08-24T14:15:22Z",
    "competitorsDetectedAt": "2019-08-24T14:15:22Z",
    "description": "string",
    "siteUrls": [
      "string"
    ],
    "siteContent": {
      "whatItIs": {
        "text": "string",
        "sources": [
          "string"
        ]
      },
      "whoItsFor": {
        "text": "string",
        "sources": [
          "string"
        ]
      },
      "vertical": "ecommerce_dtc",
      "offerings": {
        "text": "string",
        "sources": [
          "string"
        ]
      },
      "buyingSituations": {
        "text": "string",
        "sources": [
          "string"
        ]
      },
      "howBuyersPay": {
        "text": "string",
        "sources": [
          "string"
        ]
      },
      "whyChooseIt": {
        "text": "string",
        "sources": [
          "string"
        ]
      },
      "proof": [
        {
          "claim": "string",
          "quote": "string",
          "url": "string"
        }
      ],
      "contentCoverage": {
        "text": "string",
        "sources": [
          "string"
        ]
      }
    },
    "crawlError": "string",
    "country": "st",
    "language": "string",
    "vertical": "ecommerce_dtc",
    "roleType": "string",
    "companySize": "string",
    "onboardingStep": "brand_created",
    "onboardingFlow": "first_signup",
    "packExpandedAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "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"
}