POST /v1/brands

Create a brand

scope write:brands cost 1 RU idempotent required

Create a brand owned by the principal. The new brand starts without researched facts. Call POST /v1/brands/{brand_id}/facts to enqueue the research job.

API keys restricted to a single brand cannot create new brands and are rejected with brand_not_authorized.

Header parameters

Idempotency-Keystring optional

Request body

application/json required

Type:CreateBrandRequest

namestringrequired
Display name (1-80 chars).

min length: 1 · max length: 80
websitestringrequired
Primary brand website URL. Required. Must be a fully-qualified http(s):// URL.

max length: 500
brand_aliasesarray of string (nullable)nullable
Up to 50 alternate names used for citation matching.
categoriesarray of string (nullable)nullable
Free-form industry/topic tags (e.g. specialty coffee, saas). Up to 30 entries, each up to 100 characters. Defaults to [] on create.
countrystring (nullable)nullable
Primary country (e.g. United States, Argentina).
languagestring (nullable)nullable
Primary language. Accepts English name (English, Spanish) or ISO 639-1 code (en, es); normalised to the English name on write.

Example payload

{
  "brand_aliases": [
    "Acme",
    "Acme Coffee"
  ],
  "categories": [
    "specialty coffee",
    "wholesale"
  ],
  "country": "United States",
  "language": "English",
  "name": "Acme Coffee Roasters",
  "website": "https://acmecoffee.example.com"
}

Responses

Created a brandapplication/json

Type:Brand

created_atstringrequired
ISO-8601 timestamp when the brand was created.

format: `date-time`
idstringrequired
Stable brand identifier (UUID).
namestringrequired
Display name of the brand.
updated_atstringrequired
ISO-8601 timestamp of the last update.

format: `date-time`
websitestringrequired
Primary brand website URL. Always present; website is required at create time.
brand_aliasesarray of string
Alternate names used for citation matching.
brand_info_summarystring (nullable)nullable
Short description derived from the latest brand audit. Null when no audit has run.
categoriesarray of string
Free-form industry/topic category tags assigned to the brand (e.g. specialty coffee, saas, fintech). Used to seed prompt generation.
countrystring (nullable)nullable
Primary country (e.g. United States, Argentina).
languagestring (nullable)nullable
Primary language (English name like English, Spanish).
objectstring
Always brand.

default: `brand`

Example response

{
  "brand_aliases": [
    "Acme",
    "ACR",
    "Acme Coffee"
  ],
  "brand_info_summary": "Specialty coffee roaster founded in 2014, serving wholesale cafes across the US.",
  "categories": [
    "specialty coffee",
    "wholesale",
    "roastery"
  ],
  "country": "United States",
  "created_at": "2024-08-12T15:23:04.512Z",
  "id": "3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04",
  "language": "English",
  "name": "Acme Coffee Roasters",
  "object": "brand",
  "updated_at": "2024-09-01T11:08:42.117Z",
  "website": "https://acmecoffee.example.com"
}

Request validation failedapplication/json

Type:ApiError

errorobjectrequired
Show fields
- codestringrequired
  Stable machine-readable error code from the catalog.
- messagestringrequired
  Human-readable description suitable for logging.
- detailsobject
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  Empty object (no properties).
request_idstring
Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Missing or invalid credentialsapplication/json

Type:ApiError

errorobjectrequired
Show fields
- codestringrequired
  Stable machine-readable error code from the catalog.
- messagestringrequired
  Human-readable description suitable for logging.
- detailsobject
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  Empty object (no properties).
request_idstring
Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid credentials"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

You do not have permission to access this resourceapplication/json

Type:ApiError

errorobjectrequired
Show fields
- codestringrequired
  Stable machine-readable error code from the catalog.
- messagestringrequired
  Human-readable description suitable for logging.
- detailsobject
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  Empty object (no properties).
request_idstring
Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "forbidden",
    "message": "You do not have permission to access this resource"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Resource conflictapplication/json

Type:ApiError

errorobjectrequired
Show fields
- codestringrequired
  Stable machine-readable error code from the catalog.
- messagestringrequired
  Human-readable description suitable for logging.
- detailsobject
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  Empty object (no properties).
request_idstring
Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "conflict",
    "message": "Resource conflict"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Request body did not match the expected schemaapplication/json

Type:ApiError

errorobjectrequired
Show fields
- codestringrequired
  Stable machine-readable error code from the catalog.
- messagestringrequired
  Human-readable description suitable for logging.
- detailsobject
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  Empty object (no properties).
request_idstring
Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "body_validation_error",
    "message": "Request body did not match the expected schema"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Per-minute rate limit exceededapplication/json

Type:ApiError

errorobjectrequired
Show fields
- codestringrequired
  Stable machine-readable error code from the catalog.
- messagestringrequired
  Human-readable description suitable for logging.
- detailsobject
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  Empty object (no properties).
request_idstring
Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Per-minute rate limit exceeded"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

An unexpected error occurredapplication/json

Type:ApiError

errorobjectrequired
Show fields
- codestringrequired
  Stable machine-readable error code from the catalog.
- messagestringrequired
  Human-readable description suitable for logging.
- detailsobject
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  Empty object (no properties).
request_idstring
Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Service temporarily unavailable, please retryapplication/json

Type:ApiError

errorobjectrequired
Show fields
- codestringrequired
  Stable machine-readable error code from the catalog.
- messagestringrequired
  Human-readable description suitable for logging.
- detailsobject
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  Empty object (no properties).
request_idstring
Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "service_unavailable",
    "message": "Service temporarily unavailable, please retry"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Request example

curl --request POST \
  --url https://api.rankprompt.com/v1/brands \
  --header 'Authorization: Bearer rp_live_<YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <UNIQUE_KEY>' \
  --data '{
  "brand_aliases": [
    "Acme",
    "Acme Coffee"
  ],
  "categories": [
    "specialty coffee",
    "wholesale"
  ],
  "country": "United States",
  "language": "English",
  "name": "Acme Coffee Roasters",
  "website": "https://acmecoffee.example.com"
}'

const fetch = require('node-fetch');

const url = 'https://api.rankprompt.com/v1/brands';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer rp_live_<YOUR_API_KEY>',
    'Idempotency-Key': '<UNIQUE_KEY>',
    'Content-Type': 'application/json'
  },
  body: '{"brand_aliases":["Acme","Acme Coffee"],"categories":["specialty coffee","wholesale"],"country":"United States","language":"English","name":"Acme Coffee Roasters","website":"https://acmecoffee.example.com"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

import requests

url = "https://api.rankprompt.com/v1/brands"

payload = {
    "brand_aliases": ["Acme", "Acme Coffee"],
    "categories": ["specialty coffee", "wholesale"],
    "country": "United States",
    "language": "English",
    "name": "Acme Coffee Roasters",
    "website": "https://acmecoffee.example.com"
}
headers = {
    "Authorization": "Bearer rp_live_<YOUR_API_KEY>",
    "Idempotency-Key": "<UNIQUE_KEY>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())