Scorings

The scorings API starts a candidate scoring against the candidate's brand. The candidate must already be uploaded and verified.

Flow

1. Create a candidate upload with /api/uploads/create.
2. Upload bytes to the returned uploadUrl.
3. Complete the upload with /api/uploads/complete.
4. Create the scoring with /api/scorings/create.
5. Open the result in the app or poll your own workflow using the returned identifiers.

Create upload

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": "candidate.mp4",
    "mime_type_hint": "video/mp4",
    "size_bytes_hint": 12800000,
    "purpose": "candidate"
  }'

Response:

{
  "video_id": "video_123",
  "uploadUrl": "https://..."
}

Upload the file directly to uploadUrl with the same MIME type.

Complete upload

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

Candidate uploads return after server verification. Reference uploads may start processing jobs, but candidates are ready to score after upload verification.

Create 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_123"}'

video_id is required. The brand is resolved from the candidate video.

Responses

202 Accepted means a new scoring was created:

{
  "scoring_id": "scoring_123",
  "job_id": "job_123"
}

200 OK can mean the same idempotent request already committed and the existing scoring is returned:

{
  "scoring_id": "scoring_123"
}

409 Conflict with idempotency_key_in_flight means the same key is already running. Retry after the Retry-After header.

Product-state errors

Use Idempotency-Key for all create operations. Do not reuse a key for a different candidate or request body.