Skip to main content
POST
Call videos.research_pull

Authorizations

Authorization
string
header
required

An API key minted at Settings › API & MCP. Send it as Authorization: Bearer <key>. A key carries its holder's own permissions, resolved on every call — revoking a membership closes the key's reach immediately. Keep it in an environment variable (GOOSY_API_KEY), never in a committed file.

Headers

x-request-id
string

Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from A–Z a–z 0–9 . _ : -, starting with a letter or digit; anything else is replaced by a generated id.

Maximum string length: 128

Body

application/json
scope
enum<string>
required

How wide to look — the person's own answer to the offer.

Available options:
yes,
topic_only
kind
enum<string>

What it acts on: "video" for one video, "short" for one short. Leave it out for a video.

Available options:
video,
short
brief_id
string

With kind "video": The video brief's id. If this conversation has named one, pass it — a named id always wins. If none has been named and the person is on a video's plan and means that plan ('make it two minutes', 'write it'), LEAVE IT OUT: the tool acts on the plan on screen. If none has been named and no plan is open, do not call this — ask which video they mean. Never invent an id. With kind "short": The short's brief id. If this conversation has named one, pass it — a named id always wins. If none has been named and the person is on a short's plan and means that plan ('show me the plan', 'make it'), LEAVE IT OUT: the tool acts on the plan on screen. If none has been named and no plan is open, do not call this — ask which short they mean. Never invent an id.

borrow_index
integer

Borrow ONE pick's shape, by its position in picks (0-based). Only when the person asked for it.

Required range: x >= 0
confirmation_id
string<uuid>

Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
workspace
string

Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.

Minimum string length: 1

Response

The call was admitted and dispatched. ok says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.

The tool ran and answered.

ok
boolean
required
workspace
string
required

The slug of the workspace this call ran in.

working_in
object
required

Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.

state
string
Allowed value: "confirmation_required"
confirmation_id
string<uuid>
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
expires_in_seconds
integer
request_summary
string

What will happen, in one sentence, for a person to approve before confirming.

brief_id
string

The brief this acted on — the plan on screen when no usable id was given.

picks
object
shared_shape
string
source

youtube_live — a fresh look at YouTube. your_channel — the workspace's own read, because the live lookup did not happen.

Available options:
youtube_live,
your_channel
fallback_reason
string | null