List Brands

Retrieve all brand records in your organization with optional search and pagination.

Retrieve brand records for your organization. Use the query parameter to filter by name, paginate with limit and offset, and optionally inline the latest extraction job for each brand.

This is the primary endpoint for discovering brand_id values used in downstream generation tasks.

Endpoint: GET /api/v1/brands

Request

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

Query parameters

query · string

Case-insensitive fuzzy match on brand name. Returns all brands when omitted.

limit · number

Maximum number of brands to return. Defaults to 20, maximum 100.

offset · number

Zero-based start index for pagination. Defaults to 0.

expand · string

Pass "latest_job" to inline the most recent brand extraction job for each brand row. Useful when you need status context alongside brand data.

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 "list" for this endpoint.

status · string

Always "completed" for synchronous list responses.

created_at · number

Unix timestamp (seconds) when the request was received.

data · object

Show data fields

data.data · Brand[]

Array of brand records matching your organization and query filter.

data.total_count · number

Total number of matching brands (ignores limit/offset).

data.has_more · boolean

true when additional pages are available beyond the current offset.

Each brand object in data.data contains:

id · string

Brand UUID.

org_id · string

Organization UUID that owns this brand.

domain · string

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

name · string

Human-readable brand name.

primary_hex · string | null

Primary brand color as a hex string (e.g. "#000000").

secondary_hex · string | null

Secondary brand color as a hex string.

logo_url · string | null

URL of the stored brand logo, or null if not yet extracted.

font_file_url · string | null

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

layout_rules · object

Unstructured layout metadata extracted during brand ingestion.

brand_dna · object

Normalized brand DNA object. Contains primary_background_hex, primary_accent_hex, color_palette, typography_rules, core_slogan, and imagen_style_conditioning.

created_at · string

ISO 8601 timestamp of when the brand record was created.

updated_at · string

ISO 8601 timestamp of the most recent update.

Examples

curl

curl -X GET "https://api.pi.ai/api/v1/brands?query=apple&limit=20&offset=0" \
  -H "Authorization: Bearer pi_live_***"

Example with expand and fields:

curl -X GET "https://api.pi.ai/api/v1/brands?query=apple&expand=latest_job&fields=id,name,created_at" \
  -H "Authorization: Bearer pi_live_***"

Example response:

{
  "id": "req_pi_0f4b...",
  "object": "list",
  "status": "completed",
  "created_at": 1760001200,
  "data": {
    "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": {},
        "brand_dna": {
          "primary_background_hex": "#000000",
          "primary_accent_hex": "#0071E3",
          "color_palette": ["#000000", "#F5F5F7", "#A3AAAE", "#FFFFFF"],
          "core_slogan": "Think different."
        },
        "created_at": "2026-03-24T12:10:00.000Z",
        "updated_at": "2026-03-24T12:10:40.000Z"
      }
    ],
    "total_count": 1,
    "has_more": false
  }
}

The query parameter performs a case-insensitive fuzzy match on brand name using ilike. It does not search domain or brand_dna content.

Use fields=id,name for typeahead or dropdown UIs to keep payloads small. Add domain when you need a stable identity key for client-side caching.

Avoid expand=latest_job for high-frequency or lightweight lookups such as dropdown selectors — it adds extra data you likely do not need.