Extract Brand

Queue an async brand DNA extraction job from a URL, logo, or reference images.

Queue an async brand DNA extraction job. Supply any combination of a website URL, a base64-encoded logo, or base64-encoded reference images. The pipeline crawls and analyzes your inputs, then writes normalized Brand DNA to your organization’s brand record.

Endpoint: POST /api/v1/brands/extract

Request

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

At least one of url, logoBase64, or imagesBase64 is required.

Body parameters

url · string

Website URL to crawl and extract brand DNA from. The pipeline performs an extensive scrape including branding metadata, markdown, and a screenshot.

logoBase64 · string

Base64-encoded logo image (e.g. data:image/png;base64,...). Uploaded to storage before processing.

imagesBase64 · string[]

Array of base64-encoded reference images. Include your highest-signal brand visuals — logos and 1–3 references are usually sufficient.

location · object

Optional locale hints passed to the Firecrawl scrape for URL inputs.

Show location fields

location.country · string

ISO 3166-1 alpha-2 country code (e.g. "US").

location.languages · string[]

Ordered list of BCP 47 language tags (e.g. ["en-US", "en"]).

At least one of url, logoBase64, or imagesBase64 must be present. Requests that omit all three are rejected with 400.

Response

The endpoint always returns 202 Accepted for valid requests. You receive a job_id immediately — the heavy extraction work runs asynchronously.

Response fields

id · string

Unique request identifier prefixed with req_pi_.

object · string

Always "job" for this endpoint.

status · string

Always "queued" on the initial 202 response.

created_at · number

Unix timestamp (seconds) when the request was received.

data · object

Show data fields

data.job_id · string

UUID of the queued extraction job. Use this to poll for results.

Examples

curl

curl -X POST "https://api.pi.ai/api/v1/brands/extract" \
  -H "Authorization: Bearer pi_live_***" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://apple.com",
    "location": {
      "country": "US",
      "languages": ["en-US", "en"]
    }
  }'

Example response (202 Accepted):

{
  "id": "req_pi_0f4b...",
  "object": "job",
  "status": "queued",
  "created_at": 1760000000,
  "data": {
    "job_id": "a4f52db4-1234-5678-abcd-ef0123456789"
  }
}

Polling for results

After you receive the job_id, poll GET /api/v1/jobs/:job_id until status is "completed" or "failed". Jobs transition through:

queued → processing → completed | failed

To receive the full brand record in a single poll response, append ?expand=brand to the jobs request. The completed job’s data.expanded.brand will contain the full brand record including brand_dna.

See the Jobs reference for full polling details.

Send only your highest-signal inputs. A logo plus 1–3 reference images is usually enough. Avoid redundant images with near-identical style — they increase cost without improving quality.