Get Brand

Retrieve a single brand record by its UUID.

Retrieve a single brand record for your organization by its UUID. This is the direct resolver for the result_url returned by a completed brand extraction job.

Endpoint: GET /api/v1/brands/:id

Request

GET /api/v1/brands/:id
Authorization: Bearer <your_api_key>

Path parameters

id · string · required

Brand UUID to retrieve. You receive this from the completed extraction job’s result_url or from the List Brands endpoint.

Query parameters

expand · string

Pass "latest_job" to include the most recent extraction job as data.expanded.latest_job.

include · string

Alias for expand=latest_job.

fields · string

Comma-separated list of brand fields to return (e.g. id,name,brand_dna). Omit to return the full brand object.

Response

Response fields

id · string

Unique request identifier prefixed with req_pi_.

object · string

Always "brand" for this endpoint.

status · string

Always "completed" for synchronous brand retrieval.

created_at · number

Unix timestamp (seconds) when the request was received.

data · object

The brand record.

Show brand fields

data.id · string

Brand UUID.

data.org_id · string

Organization UUID that owns this brand.

data.domain · string

Canonical domain used as the brand identity key (e.g. "apple.com").

data.name · string

Human-readable brand name.

data.primary_hex · string | null

Primary brand color as a hex string.

data.secondary_hex · string | null

Secondary brand color as a hex string.

data.logo_url · string | null

URL of the stored brand logo.

data.font_file_url · string | null

URL of the stored brand font file, or null if not available.

data.layout_rules · object

Unstructured layout metadata extracted during brand ingestion.

data.brand_dna · object

Normalized brand DNA. Key fields:

• primary_background_hex — dominant surface/background color
• primary_accent_hex — dominant CTA/interaction accent color
• color_palette — array of exactly 4 unique #RRGGBB hex values
• typography_rules — concise typographic guidance
• core_slogan — single best brand slogan
• imagen_style_conditioning — exactly 2 sentences for image generation style

data.created_at · string

ISO 8601 timestamp of when the brand record was created.

data.updated_at · string

ISO 8601 timestamp of the most recent update.

Examples

curl

curl -X GET "https://api.pi.ai/api/v1/brands/1c26bcfa-e50e-4800-a7df-5b97db5fd50c" \
  -H "Authorization: Bearer pi_live_***"

Example with expand and fields:

curl -X GET "https://api.pi.ai/api/v1/brands/1c26bcfa-e50e-4800-a7df-5b97db5fd50c?include=latest_job&fields=id,name,brand_dna" \
  -H "Authorization: Bearer pi_live_***"

Example response:

{
  "id": "req_pi_9dc4...",
  "object": "brand",
  "status": "completed",
  "created_at": 1760002100,
  "data": {
    "id": "1c26bcfa-e50e-4800-a7df-5b97db5fd50c",
    "org_id": "30c0342f-4f28-4a13-9d63-5f5a10f57cc6",
    "domain": "apple.com",
    "name": "apple.com",
    "primary_hex": "#000000",
    "secondary_hex": "#F5F5F7",
    "logo_url": "https://cdn.example.com/brands/org/brand/logo.png",
    "font_file_url": null,
    "layout_rules": {
      "core_slogan": "Think different."
    },
    "brand_dna": {
      "primary_background_hex": "#000000",
      "primary_accent_hex": "#0071E3",
      "color_palette": ["#000000", "#F5F5F7", "#A3AAAE", "#FFFFFF"],
      "typography_rules": "Use bold minimalist sans-serif hierarchy.",
      "core_slogan": "Think different.",
      "imagen_style_conditioning": "Clean premium product photography. Soft studio lighting and high contrast details."
    },
    "created_at": "2026-03-24T12:10:00.000Z",
    "updated_at": "2026-03-24T12:10:40.000Z"
  }
}

You receive a brand_id from the extraction job’s result_url field once the job reaches "completed" status. Poll GET /api/v1/jobs/:job_id to get this value, or use ?expand=brand on the job request to receive the full brand record inline.

This endpoint returns 404 when the brand does not exist or when it belongs to a different organization. Both cases return the same status code to avoid leaking resource existence across organizations.