Quickstart: curl

Every tool is one POST to /api/v1/tools/ and its name, with the tool's input as JSON and an API key as a Bearer token. This page calls a few from the shell.

Set upCopy Anchor Link

Create a key in Settings → Connections (see Authentication) and keep it, with the API's address, in your environment:

export PROBABLY_API_URL="https://studio.probably.co"
export PROBABLY_API_KEY="prb_..."

While you build, tick Sandbox for a prb_test_ key: every call below works the same in your organization's sandbox, answered from recordings and charged nothing (see Sandbox keys).

List your SpacesCopy Anchor Link

#!/usr/bin/env bash
# List the Spaces your API key reaches.
set -euo pipefail

curl --silent --show-error --fail-with-body \
  --request POST "$PROBABLY_API_URL/api/v1/tools/list_spaces" \
  --header "Authorization: Bearer $PROBABLY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{}'

The answer is the tool's output as JSON, here spaces with each Space's id, name and whether it is archived. A refusal answers with a status and a body naming its outcome, such as invalid with the fields to fix; Errors lists them all.

Read eventsCopy Anchor Link

#!/usr/bin/env bash
# Read your organization's events from the start, ten at a time. Pass the
# page's "cursor" as "after" to read the next page.
set -euo pipefail

curl --silent --show-error --fail-with-body \
  "$PROBABLY_API_URL/api/v1/events?after=0&limit=10" \
  --header "Authorization: Bearer $PROBABLY_API_KEY"

Each page carries a cursor. Pass it as after to read on from there; Events and webhooks explains the types and the payload.

Talk to the MCP serverCopy Anchor Link

The same key works on the MCP endpoint, for clients you set up with a header:

#!/usr/bin/env bash
# Ask the MCP server which tools your API key is offered, as an MCP client
# set up with an Authorization header does.
set -euo pipefail

curl --silent --show-error --fail-with-body \
  --request POST "$PROBABLY_API_URL/api/mcp" \
  --header "Authorization: Bearer $PROBABLY_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json, text/event-stream" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Start paid workCopy Anchor Link

Paid work takes two calls: a tool that prepares it answers with a preview and a confirmationId, and confirm_spend with that ID starts it, once the person paying has agreed. The tools that prepare paid work are prepare_audience_research (prepare audience research), prepare_campaign_batch (prepare a campaign batch), prepare_campaign_openings (prepare a segment's openings), prepare_video (prepare a new video), prepare_regenerate (prepare a new version), prepare_variants (prepare variants), prepare_apply_change (prepare to apply a change), research (prepare research), brainstorm (prepare a brainstorm), write_script (prepare a script), review (prepare a review), generate_clip (prepare a clip), voice (prepare recordings), or storyboard (prepare a storyboard). Spend confirmations explains the flow, and the TypeScript quickstart runs it end to end.