API docs v1
POST /v1/brands/{brand_id}/shares

Create a brand-summary share

scope write:brands cost 5 RU idempotent required

Create a public share link to a curated snapshot of a brand (selected reports + SEO pages + optional analytics + optional content).

Cross-tenant safety: every report_ids/seo_page_ids entry MUST belong to this brand; mixing resources from different brands returns 400 validation_error.

If the caller already has a brand-summary share for this brand, the snapshot is rebuilt and the same token is returned (is_existing=true). Pass rotate=true to drop the existing share and mint a fresh token (use this when a previous link may have been leaked).

Defaults: 30-day expiry, no rotation, brand white-label config applied if not overridden, last 28 days of analytics/content.

Returns 400 validation_error once the caller already owns 50 active brand-summary shares for this brand.

Path parameters

Header parameters

Request body

application/json

Responses

Created a brand-summary shareapplication/json
Type:BrandShare
  • access_tokenstringrequired

    URL-safe public token. Treat as secret; rotate via POST with rotate=true.

  • brand_idstringrequired

    Owning brand id (UUID).

  • idstringrequired

    Share id (UUID).

  • share_urlstringrequired

    Pre-rendered public URL to send to recipients.

  • created_atstring (nullable)nullable

    ISO-8601 timestamp the share row was first written.

    format: `date-time`

  • expires_atstring (nullable)nullable

    ISO-8601 timestamp after which the share returns 410 Gone.

    format: `date-time`

  • is_existingboolean

    true when the response refreshed an existing share rather than creating a new row.

    default: `false`

  • objectstring

    Always brand.share.

    default: `brand.share`

  • share_typestring

    Always brand.

    default: `brand`

  • white_label_configShareWhiteLabel (nullable)nullable

    Per-share white-label overrides supplied at creation. Null when brand defaults were used.

Example response 
{
  "access_token": "Hk2L8x9PqRsTuVwXyZ-aBcDeFgHiJkLmNoPqRsTuVwXyZ_AbCdE",
  "brand_id": "3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04",
  "created_at": "2026-04-20T15:23:04.512Z",
  "expires_at": "2026-05-20T15:23:04.512Z",
  "id": "0d2c1b3a-4e5f-6789-abcd-ef0123456789",
  "is_existing": false,
  "object": "brand.share",
  "share_type": "brand",
  "share_url": "https://app.rankprompt.com/shared/Hk2L8x9PqRsTuVwXyZ-aBcDeFgHiJkLmNoPqRsTuVwXyZ_AbCdE"
}
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"
}