Runs
POST /api/v1/runs
Hand the Ads copilot a brief. Returns 202; poll for the result.
POST /api/v1/runsHand the Ads copilot a brief. Returns 202; poll for the result.
Asynchronous. An agent turn takes 1-5 minutes, so this returns 202 with a run id and a Retry-After; poll GET /api/v1/runs/{runId} until status leaves queued/running. A read-scoped key may start a run — it gets a restricted toolset with every write tool removed.
Requires a key with read scope or higher.
Returns 202 on success.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | no | Any unique string, at most 256 characters. A retry with the same key replays the first outcome instead of doing the work twice. Keys are scoped to the endpoint. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
brief | string | yes | What the agent should do, in plain English. |
project_id | string | yes | The account the run operates on. |
auto_apply | boolean | no | Allow the safe-apply policy to apply bounded low-risk changes without approval. Defaults to false: an API run is unattended, so everything queues unless you opt in. Default: false. |
Example
curl -X POST "https://bidandscale.com/api/v1/runs" \
-H "Authorization: Bearer $BIDANDSCALE_API_KEY" \
-H "Content-Type: application/json" \
-d '{ … }'