Quickstart

This guide gets a new workspace from empty to its first scored candidate. Use the browser workflow when you are setting up a brand for the first time. Use the API workflow when the brand already has a ready signature and you want to automate scoring.

Browser workflow

1. Open Brands from the app sidebar.
2. Choose Create brand.
3. Enter a brand name, confirm the slug, and add brand context. Good context includes the audience, offer, category, creative constraints, and anything the model should know when explaining results.
4. Open the brand and go to References.
5. Upload historical ads as winners and losers. Winners should be ads you would want future candidates to resemble. Losers should be ads that underperformed, failed to convert, or are known off-brand examples.
6. Wait for references to finish processing. References that are still pending or uploaded but not verified cannot be used in a signature.
7. Review the library. Set the right winner/loser label, exclude references that should not influence scoring, or set a lower weight for ambiguous examples.
8. Build a signature after you have at least 3 eligible winners and 3 eligible losers.
9. Open Score, upload a candidate video, and choose Score after the upload is ready.
10. Open the result page and review final score, brand winner-likeness, general attention, confidence, recommendations, playback, element scores, network scores, and heatmap availability.

The first score is usually directional if the reference bank is small. Scores become more reliable as the brand bank becomes larger, more balanced, and better reviewed.

API workflow

The API workflow mirrors what the browser does. A candidate video must be uploaded and verified before you can create a scoring run.

export CORTEX_TOKEN="ctx_live_..."
export BRAND_ID="brand_..."
export VIDEO_FILE="./candidate.mp4"
export IDEMPOTENCY_KEY="$(uuidgen)"

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

The response includes a video_id and an uploadUrl. Upload the file directly to that URL with the same content type:

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary "@$VIDEO_FILE"

Then complete the upload:

curl -X POST https://app.cortex.ad/api/uploads/complete \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{"video_id":"'"$VIDEO_ID"'"}'

Finally create the scoring:

curl -X POST https://app.cortex.ad/api/scorings/create \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"video_id":"'"$VIDEO_ID"'"}'

A new scoring usually returns 202 Accepted with a scoring_id and job_id. Reusing the same idempotency key for the same request may return the existing scoring instead of starting a duplicate.

Before you score

Make sure the brand has a ready signature. If the API returns no_ready_signature, open the brand in the app, review the reference library, and build a signature.

Make sure the workspace can write. Trial-expired, inactive, read-only, or quota-exceeded workspaces cannot start new scorings until billing or usage is resolved.