Create a scan

curl https://www.thesapientcompany.com/api/v1/scans \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "input": { "type": "video", "video_url": "https://yourcdn.com/ad.mp4" },
    "model": "qualia",
    "lenses": ["attention", "purchase_intent", "manipulation"],
    "granularity": "second",
    "options": {
      "include_reasons": true,
      "include_benchmark": true,
      "include_raw": true,
      "include_fmri": false
    },
    "webhook_url": "https://yourapp.com/hooks/sapient"
  }'

const res = await fetch("https://www.thesapientcompany.com/api/v1/scans", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input: { type: "video", video_url: "https://yourcdn.com/ad.mp4" },
    model: "qualia",
    lenses: ["attention", "purchase_intent", "manipulation"],
    options: { include_raw: true },
    webhook_url: "https://yourapp.com/hooks/sapient",
  }),
});

const { scan_id } = await res.json();

import requests

res = requests.post(
    "https://www.thesapientcompany.com/api/v1/scans",
    headers={
        "Authorization": "Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
    },
    json={
        "input": {"type": "video", "video_url": "https://yourcdn.com/ad.mp4"},
        "model": "qualia",
        "lenses": ["attention", "purchase_intent", "manipulation"],
        "options": {"include_raw": True},
        "webhook_url": "https://yourapp.com/hooks/sapient",
    },
)

scan_id = res.json()["scan_id"]

{
  "scan_id": "mary_run_mq7c8f31_jad6o8tl",
  "status": "queued",
  "lenses": ["attention", "purchase_intent", "manipulation"]
}

POST

scans

curl https://www.thesapientcompany.com/api/v1/scans \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "input": { "type": "video", "video_url": "https://yourcdn.com/ad.mp4" },
    "model": "qualia",
    "lenses": ["attention", "purchase_intent", "manipulation"],
    "granularity": "second",
    "options": {
      "include_reasons": true,
      "include_benchmark": true,
      "include_raw": true,
      "include_fmri": false
    },
    "webhook_url": "https://yourapp.com/hooks/sapient"
  }'

const res = await fetch("https://www.thesapientcompany.com/api/v1/scans", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input: { type: "video", video_url: "https://yourcdn.com/ad.mp4" },
    model: "qualia",
    lenses: ["attention", "purchase_intent", "manipulation"],
    options: { include_raw: true },
    webhook_url: "https://yourapp.com/hooks/sapient",
  }),
});

const { scan_id } = await res.json();

import requests

res = requests.post(
    "https://www.thesapientcompany.com/api/v1/scans",
    headers={
        "Authorization": "Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
    },
    json={
        "input": {"type": "video", "video_url": "https://yourcdn.com/ad.mp4"},
        "model": "qualia",
        "lenses": ["attention", "purchase_intent", "manipulation"],
        "options": {"include_raw": True},
        "webhook_url": "https://yourapp.com/hooks/sapient",
    },
)

scan_id = res.json()["scan_id"]

{
  "scan_id": "mary_run_mq7c8f31_jad6o8tl",
  "status": "queued",
  "lenses": ["attention", "purchase_intent", "manipulation"]
}

Submit a piece of content (a video, audio track, or page URL) and Sapient runs it through the brain model, returning a queued scan you poll (or receive on a webhook_url). The completed scan is a per-second timeline: every lens you ask for, scored second by second, with optional per-second raw brain-network values, benchmarks, reasons, and detected moments.

Mary is temporarily unavailable — all scans run on Qualia, the default model.

Videos are capped at 3 minutes. A longer clip is rejected up front (no GPU spend, no charge); trim or split it before submitting.

Pick the lenses you care about; the model runs on Qualia by default. Completed Qualia scans cost $2.50 each (see pricing).

Body Parameters

object

required

The content to analyze.

Show input

string

required

video, audio, or url — you provide an asset URL. Qualia does not take text input.

string

A public asset URL, used when type is url (also accepted as a fallback for video / audio).

string

The public video URL, used when type is video.

string

The public audio URL, used when type is audio.

string

Text input is not supported — Qualia takes a video or audio URL.

string

Optional hint when type is url: video (default), audio, or image.

string

default:"qualia"

Mary is temporarily unavailable — all scans run on Qualia, the default model ($2.50/scan). It requires a video (or audio) URL input. See Models.

string[]

Which lenses to score. Any subset of the four: attention, memory, purchase_intent, manipulation. Defaults to the top three. Unknown values are ignored.

string

default:"second"

The timeline resolution. Per-second is the default and the only resolution today.

object

Toggles for what the completed scan includes.

Show options

boolean

default:"true"

Plain-language “why this number” for each lens at each second, plus detected moments and a summary.

boolean

default:"true"

A { percentile, label } for each lens at each second, scored against Sapient’s corpus.

boolean

default:"false"

The underlying per-second values for all seven brain networks (Visual, Somatomotor, Dorsal Attention, Ventral Attention, Limbic, Frontoparietal, Default Mode). See Raw brain networks.

boolean

default:"false"

A signed URL to the rendered fMRI artifact, when available.

string

If set, Sapient POSTs the completed scan to this URL once it finishes. Best-effort; polling is always available as a fallback.

Response

string

The scan identifier, e.g. mary_run_mq7c8f31_jad6o8tl. Use it to poll for the result.

string

queued on submit. Later transitions to processing, then complete (or error).

string[]

The normalized lens list this scan will score. It echoes your request, deduped and defaulted.

curl https://www.thesapientcompany.com/api/v1/scans \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "input": { "type": "video", "video_url": "https://yourcdn.com/ad.mp4" },
    "model": "qualia",
    "lenses": ["attention", "purchase_intent", "manipulation"],
    "granularity": "second",
    "options": {
      "include_reasons": true,
      "include_benchmark": true,
      "include_raw": true,
      "include_fmri": false
    },
    "webhook_url": "https://yourapp.com/hooks/sapient"
  }'

const res = await fetch("https://www.thesapientcompany.com/api/v1/scans", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input: { type: "video", video_url: "https://yourcdn.com/ad.mp4" },
    model: "qualia",
    lenses: ["attention", "purchase_intent", "manipulation"],
    options: { include_raw: true },
    webhook_url: "https://yourapp.com/hooks/sapient",
  }),
});

const { scan_id } = await res.json();

import requests

res = requests.post(
    "https://www.thesapientcompany.com/api/v1/scans",
    headers={
        "Authorization": "Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
    },
    json={
        "input": {"type": "video", "video_url": "https://yourcdn.com/ad.mp4"},
        "model": "qualia",
        "lenses": ["attention", "purchase_intent", "manipulation"],
        "options": {"include_raw": True},
        "webhook_url": "https://yourapp.com/hooks/sapient",
    },
)

scan_id = res.json()["scan_id"]

{
  "scan_id": "mary_run_mq7c8f31_jad6o8tl",
  "status": "queued",
  "lenses": ["attention", "purchase_intent", "manipulation"]
}

Get a scan

Scans

Concepts

Reference

Body Parameters

Response

​Body Parameters

​Response

Body Parameters

Response