Probably
Start free
Docs

Prepare research

research, in Changes: A connection or key that may make changes. None spends credits; prepare_* and stage tools (research, brainstorm, write_script, review, generate_clip, voice, storyboard) prepare paid work for confirm_spend.

POST
/api/v1/tools/research

Prepare grounded research for a brief: product facts, audience language and current formats, each finding with its sources, and gaps; links in the brief are inspected. It runs on a video of the Space (videoId, using that video's brief) or on a new draft made from brief, never both. Metered at cost, at most 100 credits (the preview's capCredits); nothing is spent until it is confirmed. Read the result with get_stage. Show the person the preview. If the connection may spend, call confirm_spend with the confirmationId once they agree; otherwise send them the confirmUrl to confirm it in the studio. It expires in 15 minutes. Pass a new requestKey; repeating one returns the same confirmation.

Authorization

apiKey
headerAuthorizationBearer <token>

An API key (prb_…) from Settings → Connections.

Request Body

application/json
  1. body
spaceId*string
Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
videoId?string

A video of the Space to run on, with its current brief. Don't pass brief, name or attachments with it

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
brief?string

The brief for a new draft video, when no videoId is given

Length10 <= length <= 20000
name?string
Length1 <= length <= 120
attachments?array<||>
Itemsitems <= 45
requestKey*string
Match^[\w.:-]+$
Length8 <= length <= 64

Response Body

The tool's answer.

application/json
  1. response
videoId*string
Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
confirmationId*string
Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
expiresAt*string
preview*||||||
confirmUrl*|null
curl -X POST 'https://studio.probably.co/api/v1/tools/research' \  -H "Authorization: Bearer $PROBABLY_API_KEY" \  -H 'Content-Type: application/json' \  -d '{  "spaceId": "5b0e7c1a-3f52-4d8e-9a61-2c4f8e9d7b30",  "brief": "A 30-second TikTok for TrailGuard, a reef-safe SPF 50 for trail runners: sweat-proof, no white cast",  "attachments": [],  "requestKey": "research-trailguard-1"}'
{  "videoId": "9c3d5e2f-8a14-4b67-b0d9-6e1f2a3c4d5e",  "confirmationId": "e7a1b2c3-d4e5-4f60-8172-93a4b5c6d7e8",  "expiresAt": "2026-10-25T09:15:00.000Z",  "preview": {    "kind": "stage",    "stage": "research",    "capCredits": 100,    "availableCredits": 1840,    "fits": true,    "clip": null,    "voice": null,    "raw": false,    "storyboard": null,    "sandbox": false  },  "confirmUrl": null}