cortex
Docs nav

Brands

Brands are the organizing unit for API automation. A brand owns references, signatures, candidate uploads, and scorings.

Current API model

The customer-facing API is workflow-oriented. It supports the upload, signature, scoring, and artifact flows needed to automate Cortex. It is not a generic brand CRUD API.

Create and review brands in the app when setting up a workspace. Use the API when you need to upload videos, trigger builds, and start scorings from another system.

Brand identifiers

Most API calls use brand_id, not the visible slug. Store the brand ID in your integration once you have it from Cortex.

The browser URL uses the slug:

/app/brands/acme

API workflow requests use the ID:

{
  "brand_id": "brand_123"
}

Brand context

Brand context is edited in the app. It gives Cortex narrative context: audience, offer, category, constraints, and creative strategy. API scoring uses the brand associated with the candidate video, so keep brand context current before running large scoring batches.

References through the API

A reference video starts the same way as a candidate upload, except purpose defaults to reference.

curl -X POST https://app.cortex.ad/api/uploads/create \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $UPLOAD_KEY" \
  -d '{
    "brand_id": "brand_123",
    "original_filename": "winner-01.mp4",
    "mime_type_hint": "video/mp4",
    "size_bytes_hint": 12800000
  }'

After upload completion, reference videos are processed before they become eligible. Use the app to assign winner/loser roles, review status, weights, and KPI metadata. This protects the brand bank from accidental automation mistakes.

Build a signature

Start a signature build for a brand:

curl -X POST https://app.cortex.ad/api/signatures/build \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"brand_id":"brand_123"}'

The brand must have at least 3 eligible winners and 3 eligible losers, and eligible references must be ready. A successful build request returns a signature_id and job_id.

Automate repeated operations:

  • Upload reference files.
  • Upload candidate files.
  • Complete uploads.
  • Build signatures after review.
  • Start candidate scorings.
  • Retrieve heatmap artifacts when available.

Keep human review in the app:

  • Choosing winner vs. loser labels.
  • Excluding questionable references.
  • Adjusting reference weights.
  • Reviewing diagnostics before a rebuild.