PATCH /v1/brands/{brand_id}/white-label

Update white-label settings

scope write:white-label cost 1 RU idempotent required

Partial update of the brand's white-label config (PATCH semantics):

Only fields included in the body are touched.
Sending an explicit null for any nullable scalar clears that column.
For nested section configs (report_sections_config, brand_sections_config), only the toggles you send are merged with the persisted blob. Sending null clears the blob entirely.
An empty body is a valid no-op.

Path parameters

brand_idstring required
Brand UUID.

Header parameters

Idempotency-Keystring optional

Request body

application/json required

Type:WhiteLabelUpdate

brand_sections_configWhiteLabelBrandSectionsPatch (nullable)nullable
Per-section toggles for brand exports. Only the keys you send are merged with the persisted blob; send null to clear the blob entirely.
company_namestring (nullable)nullable
cover_subtitlestring (nullable)nullable
cover_titlestring (nullable)nullable
footer_emailstring (nullable)nullable
Contact email rendered in the footer; send null to clear.
footer_phonestring (nullable)nullable
footer_websitestring (nullable)nullable
logo_urlstring (nullable)nullable
primary_colorstring (nullable)nullable
#RRGGBB hex color; send null to clear.
report_sections_configWhiteLabelReportSectionsPatch (nullable)nullable
Per-section toggles for report exports. Only the keys you send are merged with the persisted blob; send null to clear the blob entirely.
secondary_colorstring (nullable)nullable

Example payload

{
  "logo_url": "https://cdn.acmecoffee.example.com/brand/logo-2026.png",
  "primary_color": "#C0392B",
  "report_sections_config": {
    "show_citation_table": false,
    "show_competitor_ranking": false
  }
}

Responses

Updated white-label settingsapplication/json

Type:WhiteLabel

brand_idstringrequired
Owning brand id (UUID).
brand_sections_configWhiteLabelBrandSections (nullable)nullable
Per-section toggles for brand exports.
company_namestring (nullable)nullable
Display name shown next to the logo / in the footer.
cover_subtitlestring (nullable)nullable
Subtitle rendered on the report cover page.
cover_titlestring (nullable)nullable
Title rendered on the report cover page.
created_atstring (nullable)nullable
ISO-8601 timestamp the row was first written.

format: `date-time`
footer_emailstring (nullable)nullable
Contact email rendered in the footer.
footer_phonestring (nullable)nullable
Contact phone rendered in the footer.
footer_websitestring (nullable)nullable
Contact website rendered in the footer.
logo_urlstring (nullable)nullable
Public URL of the logo rendered in headers and the cover page.
objectstring
Always white_label.

default: `white_label`
primary_colorstring (nullable)nullable
Primary brand color in #RRGGBB.
report_sections_configWhiteLabelReportSections
Per-section toggles for report exports.
Show fields
Type:WhiteLabelReportSections
- show_category_performanceboolean
  default: `true`
- show_citation_leaderboardboolean
  default: `true`
- show_citation_tableboolean
  default: `true`
- show_competitor_rankingboolean
  default: `true`
- show_cover_pageboolean
  default: `true`
- show_footerboolean
  default: `true`
- show_header_logoboolean
  default: `true`
- show_missed_promptsboolean
  default: `true`
- show_platform_matrixboolean
  default: `true`
- show_platform_performanceboolean
  default: `true`
- show_prompt_ranksboolean
  default: `true`
- show_prompt_trendsboolean
  default: `true`
- show_ranked_promptsboolean
  default: `true`
- show_region_breakdownboolean
  default: `true`
- show_run_history_tableboolean
  default: `true`
- show_stats_cardsboolean
  default: `true`
- show_trend_chartboolean
  default: `true`
- show_visibility_scoreboolean
  default: `true`
secondary_colorstring (nullable)nullable
Secondary brand color in #RRGGBB.
updated_atstring (nullable)nullable
ISO-8601 timestamp of the last write.

format: `date-time`

Example response

{
  "brand_id": "3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04",
  "company_name": "Acme Coffee Roasters",
  "cover_subtitle": "Monthly AI search performance for our wholesale catalog.",
  "cover_title": "Acme Coffee Visibility Report",
  "created_at": "2026-01-12T15:23:04.512Z",
  "footer_email": "hello@acmecoffee.example.com",
  "footer_phone": "+1-415-555-0117",
  "footer_website": "https://acmecoffee.example.com",
  "logo_url": "https://cdn.acmecoffee.example.com/brand/logo.png",
  "object": "white_label",
  "primary_color": "#C0392B",
  "report_sections_config": {
    "show_category_performance": true,
    "show_citation_leaderboard": true,
    "show_citation_table": true,
    "show_competitor_ranking": true,
    "show_cover_page": true,
    "show_footer": true,
    "show_header_logo": true,
    "show_missed_prompts": true,
    "show_platform_matrix": true,
    "show_platform_performance": true,
    "show_prompt_ranks": true,
    "show_prompt_trends": true,
    "show_ranked_prompts": true,
    "show_region_breakdown": true,
    "show_run_history_table": true,
    "show_stats_cards": true,
    "show_trend_chart": true,
    "show_visibility_score": true
  },
  "secondary_color": "#2C3E50",
  "updated_at": "2026-04-01T09:00:11.412Z"
}

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 not foundapplication/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": "not_found",
    "message": "Resource not found"
  },
  "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 PATCH \
  --url https://api.rankprompt.com/v1/brands/your_brand_id_here/white-label \
  --header 'Authorization: Bearer rp_live_<YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <UNIQUE_KEY>' \
  --data '{
  "logo_url": "https://cdn.acmecoffee.example.com/brand/logo-2026.png",
  "primary_color": "#C0392B",
  "report_sections_config": {
    "show_citation_table": false,
    "show_competitor_ranking": false
  }
}'

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

const url = 'https://api.rankprompt.com/v1/brands/your_brand_id_here/white-label';
const options = {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer rp_live_<YOUR_API_KEY>',
    'Idempotency-Key': '<UNIQUE_KEY>',
    'Content-Type': 'application/json'
  },
  body: '{"logo_url":"https://cdn.acmecoffee.example.com/brand/logo-2026.png","primary_color":"#C0392B","report_sections_config":{"show_citation_table":false,"show_competitor_ranking":false}}'
};

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/your_brand_id_here/white-label"

payload = {
    "logo_url": "https://cdn.acmecoffee.example.com/brand/logo-2026.png",
    "primary_color": "#C0392B",
    "report_sections_config": {
        "show_citation_table": False,
        "show_competitor_ranking": False
    }
}
headers = {
    "Authorization": "Bearer rp_live_<YOUR_API_KEY>",
    "Idempotency-Key": "<UNIQUE_KEY>",
    "Content-Type": "application/json"
}

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

print(response.json())