Project Brand

Project stored brand DNA into a compact, use-case-specific payload.

Convert a stored brand DNA record into a compact JSON payload shaped for a specific use case. Use this endpoint after extraction completes when you need concise brand context for frontend agents, design token generators, or copy workflows — without passing the full raw DNA.

Endpoint: POST /api/v1/brands/:id/project

Request

POST /api/v1/brands/:id/project
Authorization: Bearer <your_api_key>
Content-Type: application/json

Path parameters

id · string · required

Brand UUID to project. Obtain this from the completed extraction job or from the List Brands endpoint.

Body parameters

use_case · string · required

A plain-English description of how the brand context will be used. The model shapes the output payload around this description.

Examples:

• "Generate shadcn design tokens for a SaaS dashboard"
• "Create campaign copy for a social media ad"
• "Build a Next.js landing page token contract"
• "Create lovable.dev-ready UI variables and button style guide"

Response

The endpoint returns 200 synchronously. When the model path succeeds, you receive a model-generated compact payload. If Gemini cannot produce valid structured output, the server falls back to a deterministic projection derived from stored DNA — you still receive 200 with a valid payload.

Response fields

id · string

Unique request identifier prefixed with req_pi_.

object · string

Always "brand.projection" for this endpoint.

status · string

Always "completed" when a payload is produced.

created_at · number

Unix timestamp (seconds) when the request was received.

data · object

Show data fields

data.use_case · string

The use_case string echoed back from your request.

data.is_wildcard · boolean

true when a dynamic model-based projection was attempted (as opposed to a fixed, pre-defined use case).

data.payload · object

The compact brand context payload shaped for your use case.

Show payload fields

data.payload.use_case · string

Echo of the requested use case.

data.payload.brand_projection · object

Compact brand DNA fields relevant to the use case. Typically includes primary_background_hex, primary_accent_hex, color_palette, typography_rules, core_slogan, imagen_style_conditioning, and logo_url.

data.payload.meta · object

Metadata about how the projection was generated.

• meta.source — "deterministic_projection" when the model path failed and a fallback was used; absent or different when the model path succeeded.
• meta.reason — short explanation of why the fallback was triggered (e.g. "model_unavailable_or_invalid_json").

Examples

curl

curl -X POST "https://api.pi.ai/api/v1/brands/12cecf5a-42e9-48b4-85bb-6743126ff2e8/project" \
  -H "Authorization: Bearer pi_live_***" \
  -H "Content-Type: application/json" \
  -d '{"use_case": "Generate shadcn design tokens for a SaaS dashboard"}'

Example response:

{
  "id": "req_pi_2f2b3de6-aaaa-bbbb-cccc-ddddeeeeffff",
  "object": "brand.projection",
  "status": "completed",
  "created_at": 1762540000,
  "data": {
    "use_case": "Generate shadcn design tokens for a SaaS dashboard",
    "is_wildcard": true,
    "payload": {
      "use_case": "Generate shadcn design tokens for a SaaS dashboard",
      "brand_projection": {
        "primary_background_hex": "#FFFFFF",
        "primary_accent_hex": "#0071E3",
        "color_palette": ["#FFFFFF", "#0071E3", "#1D1D1F"],
        "typography_rules": "Bold minimalist sans-serif hierarchy with generous whitespace.",
        "core_slogan": "Think different.",
        "imagen_style_conditioning": "Clean premium product photography. Soft studio lighting and high contrast details.",
        "logo_url": null
      },
      "meta": {
        "source": "deterministic_projection",
        "reason": "model_unavailable_or_invalid_json"
      }
    }
  }
}

Inspect data.payload.meta to determine whether the response was produced by the model or by the deterministic fallback. When the model path succeeds, meta may be absent or may not contain source: "deterministic_projection". Either way, the payload is safe to consume.

Error codes

Code	HTTP	Description
invalid_brand_id	400	Path id is not a valid UUID.
invalid_request_body	400	use_case is missing or invalid.
invalid_json_body	400	Request body is not valid JSON.
projection_request_too_large	400	Request body exceeds the projection body-size limit.
brand_not_found	404	Brand does not exist or belongs to a different organization.
projection_abuse_threshold_exceeded	429	Repeated oversized requests exceeded the abuse window limit.
brand_lookup_failed	500	Database error while loading the brand.
projection_generation_failed	502	Projection could not be built — no fallback was available.

Do not call this endpoint before the extraction job has completed. If the brand record exists but brand_dna is empty or partial, projection output quality will be significantly degraded.

Write use_case strings that describe the developer artifact you are building, not the brand itself. Tool-oriented descriptions like "Generate shadcn design tokens for a dashboard" produce tighter, more actionable payloads than generic descriptions like "our brand colors".