Skip to main content
POST
Call ads.plan

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
run_id
string<uuid>

The brief's run id; leave it out for the brief this conversation started.

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})$
concept_count
integer

How many ads to plan, only when the person names a number ('make it five ads'). Leave it out for Goosy's default. A number past the most one board draws is held to it; the answer's concept_count is what was planned.

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
ready
boolean
required

False when a question is still open — then nothing is planned.

campaign_name
string | null
required
readback
string | null
required
concept_count
integer
required
Required range: x >= 0
daily_budget_cents
integer
required
Required range: x >= 0
audience_lines
string[]
required
open_questions
string[]
required
budget_question
object | null
required

Present once the goal, where it runs, who sees it and where clicks go are recorded and the budget is still open: ask it at once with ask_user, its question and options exactly as given, every label and description word for word, since each figure in them is read from the platform's minimum or the workspace's own campaigns. Say audience_size, Meta's own estimate, once before you ask, word for word; leave it out when it is null. With no options, ask the question in words. Null otherwise: never ask the budget before it is present.

accept_question
object | null
required

The read-back put to the member with its press, Make the campaign: Goosy asks it as soon as the plan is ready, so never ask it again. Their answer comes back on this call as member_answered; a press or a yes is accepted with ads.accept_plan, anything else is a change to record first. Null while a part is open.

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.