# Cook API

> The Cook API runs a Cook workspace from code: leads and clients, routines, sites, forms, booking pages, ads, approvals, the Library and more. The Cook MCP server calls this same API.

This file is for AI agents and other programs. It tells how to call the API and lists every operation in one line. https://trycook.ai/docs/api-reference/llms-full.txt gives each operation its arguments and a real-world example. People read the same reference at https://trycook.ai/docs/api-reference.

## Call the API

- Send `POST https://api.trycook.ai/v1` with the JSON body `{"op": "<operation>", "args": {...}}`.
- A call that works returns `{"ok": true, "result": ...}`. A call that fails returns `{"ok": false, "error": "..."}` with an HTTP error status.
- `GET https://api.trycook.ai/v1/ops` lists every operation, with no key.

## Keys

- **Every call** sends `Authorization: Bearer <your Cook API key>` and `Content-Type: application/json`.
- **Get a key** in Cook: Settings → Developer → API keys (https://app.trycook.ai/settings?tab=apikeys). Only owners and admins of the workspace can make keys. Cook shows the key one time.
- **A key works in the workspace it was made in.** A key made in Settings cannot reach another workspace: sending `X-Cook-Workspace-Id` with another workspace's id returns `403` "This key is limited to its original Cook workspace."
- **Choosing a workspace:** only a key that Cook's sign-in page makes for a connected app, such as the Cook MCP server, can send `X-Cook-Workspace-Id` to work in another workspace where its person is an owner or admin. `auth.workspaces` lists the ids it can send.
- **Account keys:** "Bind this key to my account", on by default, binds the key to you. 66 operations, marked **Account key**, refuse any other key with `403`. An account key stops working (`401`) when its person is no longer an owner or admin of the workspace.
- **Deciding cards:** `approvals.decide` works only with the key that Cook's sign-in page makes for a connected app.
- **Paid plan only.** Without one, every operation except `auth.context` and `auth.workspaces` returns `402`.

## First call

Dana made a key in Settings for her Harbor Dental workspace and wants to check it before her script runs.

```bash
curl https://api.trycook.ai/v1 \
  --request POST \
  --header "Authorization: Bearer $COOK_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "op": "auth.context",
    "args": {}
  }'
```

Response:

```json
{
  "ok": true,
  "result": {
    "keyId": "k57d2b3m8x1n9v0c4q6r7s5t2w8y1z3a",
    "orgId": "harbor-dental",
    "userId": "u4r8w2q6e1t9y3a7",
    "scopeKind": "user",
    "scopes": [
      "org:*"
    ],
    "workspaceAccess": "workspace",
    "defaultWorkspaceId": "harbor-dental",
    "role": "owner"
  }
}
```

## Errors

- 400: The body is not JSON, `op` is missing or unknown, `args` do not match the operation, or `X-Cook-Workspace-Id` is sent empty. Cook checks the key and the plan first, so an unknown op on an unpaid workspace returns 402.
- 400: "This isn't included in this workspace's plan." The workspace's plan does not include this operation. Your request is fine.
- 400 `BAD_REQUEST`: The operation refused the values in `args`. `error` says why.
- 401: The Authorization header is missing, the key is invalid or revoked, or the key's person is no longer an owner or admin of the workspace.
- 402 `PAYMENT_REQUIRED`: The workspace is not on a paid plan. The body includes `planUrl`.
- 403 `FORBIDDEN`: The key cannot do this: `X-Cook-Workspace-Id` names a workspace the key cannot reach ("This key is limited to its original Cook workspace."), the operation needs an account key, the key reaches only the task board, or the key cannot decide approval cards.
- 403: `auth.context` or `auth.workspaces` was called with a key that is not bound to a person.
- 403 `ACCESS_DENIED`: The key's person does not have the permission this operation needs.
- 403 `WORKSPACE_SUSPENDED`: The workspace is suspended.
- 404 `NOT_FOUND`: The record the arguments name does not exist in this workspace.
- 413: The body is larger than 400 KB.
- 429: The key is over a rate limit. `retryAfter` gives the seconds to wait.
- 500: The operation failed on the server.

## Rate limits

- Each key can make 300 calls per minute, with bursts up to 600.
- These operations also count toward 60 calls per hour for each key: `hires.ask`, `import.start`, `mail.reply`, `mail.send`, `media.render`, `research.adLibrary`, `runs.start`, `sandbox.run`.
- A call over a limit returns 429 with `retryAfter`: the number of seconds to wait.

## Operations

Arguments and a real-world example for every operation: https://trycook.ai/docs/api-reference/llms-full.txt
The same catalog as JSON, with a JSON Schema for every argument: https://trycook.ai/docs/api-reference.json

### Your key (`auth.*`)

- `auth.context`: The key's own workspace, person, scopes and workspace access. Account key only. Arguments: none.
- `auth.workspaces`: The workspaces this key can choose with X-Cook-Workspace-Id. Account key only. Arguments: none.

### Workspace (`org.*`)

- `org.department`: One department's head + members. Arguments: `department` (string, required).
- `org.overview`: Org bootstrap. Arguments: none.

### CRM (`crm.*`)

- `crm.approval`: Submit a draft reply for human approval. Arguments: `subjectType` (one of `conversation`, `lead`, required); `subjectId` (string, required); `leadId` (string); `draftText` (string, required).
- `crm.clientArchive`: Archive a client. Arguments: `clientId` (string, required); `reason` (string).
- `crm.clientCreate`: Create a client. Arguments: `name` (string, required); `website` (string).
- `crm.clientFieldLog`: Custom-field changes on the workspace's clients in time order, with who made each. Arguments: `since` (number); `limit` (number).
- `crm.clientFields`: The current values of named custom fields on every client. Arguments: `keys` (string[], required); `includeArchived` (boolean).
- `crm.clientFile`: Write a markdown or JSON file into a client's drive folder clients/<slug>/<name>. Arguments: `clientId` (string, required); `name` (string, required); `content` (string, required).
- `crm.clientFileGet`: Read a markdown or JSON file back out of a client's drive folder clients/<slug>/<name>. Arguments: `clientId` (string, required); `name` (string, required).
- `crm.clientNotes`: Team notes on a client, or on every client, in time order. Arguments: `clientId` (string); `since` (number); `limit` (number).
- `crm.clientOffer`: Overwrite a client's OFFER.md on the drive and flip offerStatus → draft for review. Arguments: `clientId` (string, required); `content` (string, required).
- `crm.clientRestore`: Restore an archived client and the channels/tasks archived with it. Arguments: `clientId` (string, required).
- `crm.clientRoadmapSeed`: Replace a client's roadmap with the given items. Arguments: `clientId` (string, required); `items` (object[], required); `mode` ("replace").
- `crm.clients`: List the org's ACTIVE clients. Arguments: `includeArchived` (boolean).
- `crm.clientUpdate`: Update a client's name/website/logo/email/customFields. Arguments: `clientId` (string, required); `name` (string); `website` (string); `logo` (string); `research` (boolean).
- `crm.conversationMessage`: Append a CRM conversation message. Arguments: `conversationId` (string, required); `role` (one of `them`, `agent`, required); `text` (string, required).
- `crm.conversationMessages`: Messages in one conversation. Arguments: `conversationId` (string, required).
- `crm.conversations`: CRM conversations, newest first. Arguments: `limit` (number).
- `crm.emailLead`: Email one lead on its own card. Arguments: `leadId` (string, required); `subject` (string, required); `body` (string, required).
- `crm.engagement`: Record an agent outreach touch. Arguments: `leadId` (string, required); `persona` (string, required); `text` (string, required).
- `crm.lead`: One lead + activity + conversations + meetings. Arguments: `leadId` (string, required).
- `crm.leadActivity`: Log activity on a lead. Arguments: `leadId` (string, required); `kind` (one of `ai`, `them`, `sys`, required); `title` (string, required); `detail` (string); `at` (string).
- `crm.leadDoing`: Update a lead's live 'doing' line. Arguments: `leadId` (string, required); `doing` (string, required); `lastActivity` (string).
- `crm.leadNotes`: Overwrite a lead's notes. Arguments: `leadId` (string, required); `notes` (string, required).
- `crm.leads`: Leads, newest first, with their tags and named pipelineStageId. Arguments: `clientId` (string); `stage` (string); `limit` (number); `since` (string); `answers` (boolean).
- `crm.leadSetter`: Who texts one lead. Arguments: `leadId` (string, required); `setter` (one of `me`, `ai_setter`, required).
- `crm.leadStage`: Move a lead's pipeline stage. Arguments: `leadId` (string, required); `stage` (one of `new`, `working`, `qualified`, `meeting`, `won`, `lost`, required); `score` (number).
- `crm.leadsWaiting`: The leads a setter owes a message now, longest waiting first. Arguments: `clientId` (string); `limit` (number); `newWithinDays` (number).
- `crm.leadThread`: One lead's whole conversation as the timeline Cook's AI reads before it texts. Arguments: `leadId` (string, required); `limit` (number).
- `crm.leadUpdate`: Correct a lead's name/company/email/phone. Arguments: `leadId` (string, required); `name` (string); `company` (string); `email` (string); `phone` (string).
- `crm.meetingBook`: Book a lead at an open time the lead agreed to, the way the AI setter's book_meeting does. Arguments: `leadId` (string, required); `startAt` (number, required).
- `crm.meetingCancel`: Cancel a lead's meeting. Arguments: `leadId` (string, required); `meetingId` (string); `reason` (string).
- `crm.meetingMarkNoShow`: Mark a meeting a no-show. Arguments: `meetingId` (string, required).
- `crm.meetingReschedule`: Move a lead's meeting. Arguments: `leadId` (string, required); `startAt` (number, required); `meetingId` (string).
- `crm.meetings`: Meetings (org-wide or one lead's), each with rebookUrl. Arguments: `leadId` (string).
- `crm.meetingSlots`: Every open time on the calendar a lead is booked on. Arguments: `leadId` (string, required); `from` (string); `days` (number).
- `crm.meetingUnmarkNoShow`: Take back a meeting's no-show. Arguments: `meetingId` (string, required).
- `crm.outreachEvent`: Ingest a browser-observed outreach event. Arguments: `clientId` (string · id); `campaign` (string, required); `platform` (one of `instagram`, `linkedin`, `facebook`, required); `eventId` (string, required); `senderAccount` (string, required); `profileUrl` (string, required); `senderHandle` (string); `attemptId` (string); `externalMessageId` (string); `kind` (one of `attempted`, `sent`, `received`, `failed`, `uncertain`, `connection_requested`, `connection_accepted`, required); `text` (string); `occurredAt` (number, required); `evidence` (object); `runId` (string); `recipientName` (string); `recipientAvatarUrl` (string).
- `crm.outreachMetrics`: Confirmed social outreach metrics by client and campaign. Arguments: `clientId` (string · id); `campaign` (string).
- `crm.pipeline`: Pipeline stages + per-stage lead counts, the named pipelines with their ids and their stages. Arguments: none.
- `crm.pipelineCreate`: Create a named pipeline with its stages, as Settings → Pipelines does. Arguments: `name` (string, required); `stages` (object[], required).
- `crm.prospectImport`: Save Instagram or LinkedIn profiles as campaign leads. Arguments: `clientId` (string · id); `campaign` (string, required); `platform` (one of `instagram`, `linkedin`, `facebook`, required); `sourceUrl` (string); `rows` (object[], required).
- `crm.setOpportunity`: Create or move a lead's opportunity. Arguments: `leadId` (string, required); `pipeline` (string, required); `stage` (string); `value` (number); `status` (one of `open`, `won`, `lost`, `abandoned`); `name` (string).
- `crm.setterRoutine`: The routine of the AI app on this key that Cook wakes when a lead needs a setter. Account key only. Arguments: none.
- `crm.setterRoutineSet`: Set the routine of the AI app on this key that Cook wakes when a lead needs a setter. Account key only. Arguments: `enabled` (boolean, required); `fireUrl` (string); `token` (string); `events` (string[]); `newLeads` (one of `app`, `ai_setter`).
- `crm.textLead`: Text one lead the way Cook's AI does. Arguments: `leadId` (string, required); `text` (string, required); `afterMessageId` (string).

### Routines (`workflows.*`)

- `workflows.create`: Create a routine the way Cook's AI does. Arguments: `name` (string, required); `trigger` (any, required); `nodes` (any, required); `edges` (any, required); `clientId` (string · id).
- `workflows.edit`: Replace the config of the named steps, as Cook's AI changes a routine. Arguments: `id` (string, required); `steps` (object[], required).
- `workflows.get`: One routine: its trigger, steps. Arguments: `id` (string · id, required).
- `workflows.list`: Canonical workflow definitions, graphs, triggers, and schedules. Arguments: none.
- `workflows.pause`: Turn a routine off, as Cook's AI does. Arguments: `id` (string · id, required).
- `workflows.propose`: File the approval card Cook's AI files to turn a routine on. Arguments: `id` (string, required); `action` (one of `enable`, `promote`, `rollback`, required); `version` (number).
- `workflows.runNow`: Run a routine that is on, now, as Cook's AI does. Arguments: `id` (string · id, required).
- `workflows.runs`: A routine's runs, newest first, as its Enrollment list shows them. Arguments: `id` (string, required); `limit` (number).
- `workflows.status`: A routine's test verdicts as Cook's AI reads them. Arguments: `id` (string · id, required).
- `workflows.test`: Queue the test battery Cook's AI runs, on the draft when there is one. Arguments: `id` (string, required).
- `workflows.trace`: One routine run's steps in order. Arguments: `workflowRunId` (string, required).

### Forms and quizzes (`forms.*`)

- `forms.create`: Create a form or quiz the way Cook's AI does. Arguments: `name` (string, required); `description` (string); `fields` (object[]); `submitLabel` (string); `successMessage` (string); `successRedirectUrl` (string); `live` (boolean); `clientId` (string · id); `display` (string).
- `forms.delete`: Propose deleting a form or quiz. Arguments: `id` (string, required).
- `forms.dropoff`: One form's drop-off as its Forms tab shows it. Arguments: `formId` (string, required); `window` (one of `7d`, `30d`, `all`).
- `forms.get`: One form in full, as Cook's AI reads it before changing it. Arguments: `formId` (string, required).
- `forms.list`: The workspace's forms, newest first. Arguments: none.
- `forms.update`: Change a form the way Cook's AI does. Arguments: `id` (string · id, required); `name` (string); `description` (string); `fields` (object[]); `submitLabel` (string); `successMessage` (string); `successRedirectUrl` (string); `live` (boolean); `steps` (object[]); `outcomes` (object[]); `rules` (object[]); `display` (string).

### Booking pages (`booking.*`)

- `booking.calendars`: The workspace's connected booking calendar. Arguments: none.
- `booking.create`: Create a booking page the way Cook's AI does. Arguments: `name` (string, required); `clientId` (string · id); `durationMinutes` (number); `description` (string); `conferencing` (string); `timezone` (string); `successRedirectUrl` (string); `questions` (object[]); `requireBusinessEmail` (boolean); `hostEmails` (string[]); `calendarId` (string).
- `booking.list`: The workspace's booking pages as Cook's AI reads them. Arguments: none.
- `booking.publish`: Publish (live true) or unpublish a booking page, as Cook's AI does. Arguments: `id` (string · id, required); `live` (boolean, required).
- `booking.update`: Propose a booking page change. Arguments: `id` (string, required); `name` (string); `description` (string); `durationMinutes` (number); `location` (string); `timezone` (string); `bookingWindowDays` (number); `minNoticeMinutes` (number); `openHours` (object[]); `questions` (object[]); `addQuestions` (object[]); `requireBusinessEmail` (boolean); `disqualifyMessage` (string); `disqualifyRedirectUrl` (string); `successMessage` (string); `successRedirectUrl` (string); `hostEmails` (string[]); `calendarId` (string).

### Sites (`funnels.*`)

- `funnels.clone`: A git clone address for one site's files, good for an hour. Account key only. Arguments: `funnelId` (string, required).
- `funnels.createSite`: Make a site from the caller's files. Arguments: `name` (string, required); `files` (object[], required).
- `funnels.delete`: Propose taking a site offline. Arguments: `funnelId` (string, required).
- `funnels.get`: One funnel's detail. Arguments: `funnelId` (string, required).
- `funnels.list`: The org's funnels. Arguments: none.
- `funnels.publish`: File one site's publish card for this key's person. Account key only. Arguments: `funnelId` (string, required).
- `funnels.publishSite`: File the publish card for a site on Cook's build machine. Account key only. Arguments: `site` (string, required); `clientId` (string · id); `title` (string).
- `funnels.readSite`: Read a site's files from Cook's build machine, to change a site the caller did not just write. Arguments: `funnelId` (string); `site` (string); `paths` (string[]).

### Ads (`ads.*`)

- `ads.adSet`: One ad set in detail — budget, bidding, schedule, targeting. Arguments: `clientId` (string, required); `adSetId` (string, required).
- `ads.backend`: Which platform runs one client's ads. Arguments: `clientId` (string).
- `ads.createAd`: Propose a new ad. Arguments: `clientId` (string, required); `name` (string, required); `goal` (string); `headline` (string); `body` (string); `description` (string); `callToAction` (string); `linkUrl` (string); `imageUrl` (string); `video` (string); `leadGenFormId` (string); `existingCampaignId` (string); `adSetId` (string); `budgetAmount` (number); `budgetType` (string); `startDate` (string); `endDate` (string); `countries` (string[]); `ageMin` (number); `ageMax` (number); `interests` (string[]); `specialAdCategories` (string[]); `status` (string); `validateOnly` (boolean).
- `ads.createCampaign`: Propose a new ad campaign. Arguments: `clientId` (string, required); `name` (string, required); `goal` (string, required); `budgetAmount` (number); `budgetType` (string); `status` (string); `specialAdCategories` (string[]).
- `ads.creatives`: The ad creatives running for one client, optionally filtered by campaign or status. Arguments: `clientId` (string, required); `campaignId` (string); `status` (string); `fromDate` (string); `toDate` (string); `limit` (number).
- `ads.duplicateAd`: Propose copying an ad on a client's Zernio ad account, into its own ad set or adSetId. Arguments: `clientId` (string, required); `adId` (string, required); `adSetId` (string).
- `ads.duplicateCampaign`: Propose copying a campaign on a client's Zernio ad account with its ad sets, ads and creatives. Arguments: `clientId` (string, required); `campaignId` (string, required).
- `ads.insights`: Ad performance for one client's ad account. Arguments: `clientId` (string, required); `objectId` (string); `level` (string); `fields` (string); `breakdowns` (string); `datePreset` (string); `fromDate` (string); `toDate` (string); `limit` (number); `timeIncrement` (number); `attribution` ("adset"); `accountOnly` (boolean); `includeCampaigns` (boolean).
- `ads.leadForms`: The lead forms attached to one client's ad account. Arguments: `clientId` (string, required).
- `ads.setAdStatus`: Propose pausing or resuming ads. Files an approval card. Arguments: `clientId` (string, required); `adIds` (string[], required); `status` (string, required).
- `ads.updateAdSet`: Propose a change to an ad set's budget, name, or bidding. Arguments: `clientId` (string, required); `adSetId` (string, required); `budgetAmount` (number); `budgetType` (string); `name` (string); `bidStrategy` (string); `bidAmount` (number); `roasAverageFloor` (number).

### Meta ads (`meta.*`)

- `meta.adAccounts`: Ad accounts on a client's Meta connection. Arguments: `clientId` (string).
- `meta.ads`: Ads on a client's direct-Meta ad account. Arguments: `clientId` (string, required).
- `meta.campaigns`: Campaigns on a client's direct-Meta ad account. Arguments: `clientId` (string, required).
- `meta.duplicateAd`: Propose copying an ad on a client's direct-Meta ad account into its own ad set or adSetId. Arguments: `clientId` (string, required); `adId` (string, required); `adSetId` (string); `url` (string).
- `meta.duplicateCampaign`: Propose copying a campaign on a client's direct-Meta ad account with its ad sets and ads. Arguments: `clientId` (string, required); `campaignId` (string, required); `url` (string).
- `meta.formLeads`: The leads collected by one Meta lead form. Arguments: `clientId` (string, required); `formId` (string, required).
- `meta.insights`: Read-only direct Meta reporting. Arguments: `clientId` (string, required); `datePreset` (string).
- `meta.leadForms`: Lead forms on one Facebook page for a direct-Meta client. Arguments: `clientId` (string, required); `pageId` (string, required).
- `meta.pixels`: The pixels on a direct-Meta client's ad account and when each last fired. Arguments: `clientId` (string, required).
- `meta.setStatus`: Propose pausing or resuming a campaign, ad set or ad on a client's direct-Meta ad account. Arguments: `clientId` (string, required); `nodeId` (string, required); `status` (one of `ACTIVE`, `PAUSED`, required).
- `meta.updateBudget`: Propose a new daily budget on a direct-Meta campaign or ad set. Arguments: `clientId` (string, required); `nodeId` (string, required); `dailyBudgetCents` (number); `dailyBudgetAmount` (number).
- `meta.updateDestination`: Propose sending one ad, or every ad in an ad set or campaign, on a client's direct-Meta ad account to a new landing page. Arguments: `clientId` (string, required); `level` (one of `campaign`, `adset`, `ad`, required); `id` (string, required); `url` (string, required).

### Whop ads (`whopads.*`)

- `whopads.createAd`: Propose a Whop draft ad in a new or existing ad group. Arguments: `clientId` (string); `adGroupId` (string); `title` (string, required); `campaignTitle` (string); `adGroupTitle` (string); `objective` (string); `primaryTexts` (string[], required); `headlines` (string[], required); `descriptions` (string[]); `callToAction` (string); `url` (string, required); `creativeFileIds` (string[]); `socialAccountId` (string); `budgetAmount` (number); `budgetType` (one of `daily`, `lifetime`); `countries` (string[]); `optimizationGoal` (string); `conversionEvent` (string).
- `whopads.duplicateAd`: Propose copying a Whop ad into its own ad group or adGroupId. Arguments: `clientId` (string); `adId` (string, required); `adGroupId` (string); `url` (string).
- `whopads.duplicateCampaign`: Propose copying a Whop campaign with its ad groups and ads. Arguments: `clientId` (string); `campaignId` (string, required); `url` (string).
- `whopads.launch`: Propose launching a draft Whop campaign. Arguments: `clientId` (string); `campaignId` (string, required).
- `whopads.setStatus`: Propose pausing or resuming a Whop campaign, ad group or ad. Arguments: `clientId` (string); `level` (one of `campaign`, `ad_group`, `ad`, required); `id` (string, required); `paused` (boolean, required).
- `whopads.status`: One client's Whop ads. Arguments: `clientId` (string); `statsFrom` (string); `statsTo` (string); `attributionModel` (one of `last_touch`, `first_touch`); `timeZone` (string); `limit` (number); `campaignId` (string); `includeCreatives` (boolean).
- `whopads.updateBudget`: Propose a new budget for a Whop campaign or ad group, in whole units of the ad account's currency. Arguments: `clientId` (string); `level` (one of `campaign`, `ad_group`, required); `id` (string, required); `budgetAmount` (number, required); `budgetType` (one of `daily`, `lifetime`).
- `whopads.updateDestination`: Propose sending one Whop ad, or every ad in an ad group or campaign, to a new landing page. Arguments: `clientId` (string); `level` (one of `campaign`, `ad_group`, `ad`, required); `id` (string, required); `url` (string, required).
- `whopads.uploadCreative`: Upload a picture or video to Whop as an ad creative. Account key only. Arguments: `path` (string); `url` (string); `assetId` (string); `clientId` (string).
- `whopads.validatePixel`: Whether the Whop pixel is installed on a page, and which events it has sent and when. Arguments: `clientId` (string); `url` (string).

### Media generation (`media.*`)

- `media.editImage`: Edit or recombine images from a prompt plus up to 8 reference images. Arguments: `prompt` (string, required); `imageUrl` (string); `imageUrls` (string[]); `assetId` (string); `assetIds` (string[]); `aspect` (string); `callId` (string).
- `media.generateImage`: Generate an image from a prompt. Arguments: `prompt` (string, required); `aspect` (string); `transparent` (boolean); `callId` (string).
- `media.generateVideo`: Generate a video from a prompt, optionally starting from a still. Arguments: `prompt` (string, required); `aspect` (string); `durationSec` (number); `resolution` (one of `480p`, `720p`); `imageUrl` (string); `assetId` (string); `model` (string); `input` (any); `callId` (string).
- `media.generateVoice`: A voiceover (generate_voice). Account key only. Arguments: `text` (string, required); `voice` (string); `strictVoice` (boolean); `speed` (number); `voiceModify` (object).
- `media.render`: Render one of Cook's template videos. Account key only. Arguments: `title` (string, required); `composition` (string, required); `props` (object (map)); `type` (string); `summary` (string); `delivery` (object).
- `media.renderStatus`: Where a media.render job got to. Arguments: `jobId` (string, required).
- `media.status`: Where one media generation got to, by callId. Arguments: `callId` (string, required).
- `media.transcribe`: A transcript with word-level timestamps. Account key only. Arguments: `mediaUrl` (string); `assetId` (string); `language` (string); `diarize` (boolean); `timestampGranularity` (one of `word`, `character`, `none`).
- `media.viewImage`: Pictures handed back as bytes. Account key only. Arguments: `url` (string); `urls` (string[]); `assetId` (string); `assetIds` (string[]).
- `media.voices`: The voices generate_voice speaks with. Account key only. Arguments: none.

### Library (`assets.*`)

- `assets.comment`: Add an agent comment to an asset. Arguments: `assetId` (string, required); `text` (string, required).
- `assets.fromRun`: Ship a run's output into the Library. Arguments: `runId` (string, required); `sourceKind` (one of `loop`, `channel`, required); `title` (string, required); `type` (one of `offers`, `ads`, `emails`, `content`, `research`, `funnels`, `leads`, `copy`, `wiki`, `reports`, required); `client` (string, required); `media` (string, required); `kind` (one of `doc`, `vid`, `img`, `art`, required); `desc` (string, required); `long` (string); `tags` (string[], required); `agent` (string).
- `assets.get`: Asset metadata + drive-backed content + canonical revisions. Arguments: `assetId` (string, required).
- `assets.list`: Library assets (compact). Arguments: `type` (string); `q` (string); `limit` (number).
- `assets.review`: Set an asset's review status. Arguments: `assetId` (string, required); `status` (one of `pending`, `approved`, `revised`, required).
- `assets.revision`: Add a content revision to an asset. Arguments: `assetId` (string, required); `long` (string, required); `desc` (string); `label` (string, required).
- `assets.search`: Semantic Library search over current asset metadata, body files, and attachments. Arguments: `query` (string, required); `type` (string); `clientId` (string · id); `review` (string); `limit` (number).

### Deliverables (`deliverables.*`)

- `deliverables.create`: Create a finished deliverable in the Library, as Cook's agent does. Account key only. Arguments: `title` (string, required); `client` (string); `summary` (string); `type` (one of `research`, `content`, `copy`, `ads`, `offers`, `emails`, `leads`, `funnels`); `html` (string); `drivePath` (string); `mediaUrl` (string); `mediaKind` (one of `doc`, `vid`, `img`, `art`, `aud`); `productionProject` (string); `attachments` (object[]).
- `deliverables.list`: Recent deliverables in the Library, newest first, or one client's, as Cook's agent reads them. Account key only. Arguments: `limit` (number); `client` (string).
- `deliverables.share`: A link to one deliverable. Account key only. Arguments: `deliverableId` (string, required); `audience` (one of `anyone`, `workspace`).
- `deliverables.update`: Revise a deliverable as a new version, keeping the old ones. Account key only. Arguments: `deliverableId` (string, required); `title` (string); `summary` (string); `client` (string); `html` (string); `drivePath` (string); `mediaUrl` (string); `mediaKind` (one of `doc`, `vid`, `img`, `art`, `aud`); `productionProject` (string); `attachments` (object[]); `note` (string); `resurface` (boolean).

### Knowledge (`knowledge.*`)

- `knowledge.get`: One knowledge doc with body. Arguments: `docId` (string, required).
- `knowledge.lint`: Log a wiki lint/activity note. Arguments: `docId` (string); `clientId` (string); `actor` (string); `summary` (string, required).
- `knowledge.list`: Knowledge docs metadata. Arguments: `clientId` (string); `all` (boolean).
- `knowledge.pinned`: Pinned knowledge for an agent surface. Arguments: `surface` (one of `customer`, `internal`, required); `department` (string); `clientId` (string · id); `leadId` (string · id).
- `knowledge.remove`: Permanently delete a knowledge doc + its index chunks. Arguments: `docId` (string, required).
- `knowledge.search`: Hybrid RAG search over the org knowledge base. Arguments: `surface` (one of `customer`, `internal`, required); `query` (string, required); `department` (string); `clientId` (string · id); `leadId` (string · id); `limit` (number).
- `knowledge.setEnabled`: Enable/disable a knowledge doc. Arguments: `docId` (string, required); `enabled` (boolean, required).
- `knowledge.upsert`: Create/update a knowledge doc (snapshots a revision). Arguments: `clientId` (string); `title` (string, required); `body` (string, required); `category` (string); `audience` (one of `customer`, `internal`, required); `departments` (string[]); `actor` (string); `summary` (string).

### Drive (`drive.*`)

- `drive.downloadUrl`: A link that downloads one drive file, good for 15 minutes, with its name, content type and size. Arguments: `path` (string, required).
- `drive.ls`: List the files and folders at a path on a drive. Arguments: `resource` (string); `path` (string).
- `drive.read`: Read one file from a drive. Arguments: `resource` (string); `path` (string, required).
- `drive.resources`: List the drives this workspace has. Arguments: none.
- `drive.stage`: A public, seekable streaming URL for a media file on the workspace drive. Account key only. Arguments: `drivePath` (string, required); `delivery` (object).
- `drive.uploadFinish`: Finish an upload from drive.uploadStart. Arguments: `path` (string, required); `size` (number, required); `library` (object).
- `drive.uploadLink`: A Cook link where a signed-in member of the workspace adds files from their computer. Arguments: none.
- `drive.uploadStart`: Start uploading one file. Arguments: `name` (string, required); `contentType` (string, required); `size` (number, required); `folder` (string).
- `drive.write`: Create or overwrite a file on a drive (200KB cap). Arguments: `resource` (string); `path` (string, required); `content` (string, required).

### Channels (`channels.*`)

- `channels.append`: Append a chunk to a streaming message. Arguments: `messageId` (string, required); `chunk` (string, required).
- `channels.fail`: Mark a streaming placeholder failed. Arguments: `messageId` (string, required); `text` (string, required).
- `channels.finalize`: Finalize a streaming message. Arguments: `messageId` (string, required).
- `channels.list`: All channels in the org. Arguments: none.
- `channels.messages`: Channel messages. Arguments: `channel` (string, required); `limit` (number); `parentId` (string).
- `channels.post`: Post a channel message. Arguments: `channel` (string, required); `text` (string); `kind` (one of `agent`, `system`, `user`); `persona` (string); `parentId` (string); `runId` (string); `streaming` (boolean); `attachment` (object); `grades` (object[]).

### Email (`mail.*`)

- `mail.drafts`: The key's person's drafts in Emails → Drafts, newest first. Account key only. Arguments: none.
- `mail.forward`: Propose forwarding an email in a connected Gmail or Outlook inbox, attachments included. Account key only. Arguments: `to` (string[], required); `messageId` (string); `threadId` (string); `mailbox` (string); `note` (string).
- `mail.mailboxes`: What the workspace can send email as, as Cook's agent reads it. Account key only. Arguments: none.
- `mail.reply`: Reply in an org-mail thread (expensive; hourly-capped). Arguments: `text` (string); `html` (string); `labels` (string[]); `agentKey` (string); `parentMessageId` (string, required); `threadId` (string); `isAutoReply` (boolean).
- `mail.saveDrafts`: Save emails as drafts in the key's person's Emails → Drafts. Account key only. Arguments: `drafts` (object[], required).
- `mail.send`: Send org mail (expensive; hourly-capped). Arguments: `text` (string); `html` (string); `labels` (string[]); `agentKey` (string); `to` (string | string[], required); `subject` (string, required); `cc` (string | string[]); `bcc` (string | string[]); `replyTo` (string).
- `mail.status`: Delivery status of an email the workspace sent. Account key only. Arguments: `outboundId` (string, required).
- `mail.thread`: One email conversation, every message in order, as Cook's agent reads it. Account key only. Arguments: `threadId` (string, required); `mailbox` (string).
- `mail.threads`: Recent email conversations, newest first, as Cook's agent reads them. Account key only. Arguments: `unreadOnly` (boolean); `labels` (string[]); `limit` (number); `mailbox` (string).

### Texting (`sms.*`)

- `sms.log`: The texts Cook sent and received, newest first, or those to and from one lead. Arguments: `leadId` (string); `limit` (number).
- `sms.registration`: The texting (US A2P 10DLC) registrations of the workspace, its own and its clients', or of one client, as Cook's AI reads them. Arguments: `clientId` (string).
- `sms.registrationDraft`: Save business and campaign details into the draft texting registration of the workspace or of one client, by the rules of Cook's own draft save. Arguments: `clientId` (string); `businessName` (string); `entityType` (one of `sole_prop`, `private`, `public`, `nonprofit`); `ein` (string); `website` (string); `messagingBrandName` (string); `privacyPolicyUrl` (string); `termsUrl` (string); `contactEmail` (string); `contactPhone` (string); `street` (string); `city` (string); `region` (string); `postalCode` (string); `areaCode` (string); `useCase` (string); `description` (string); `optInDescription` (string); `sampleMessages` (string[]); `repFirstName` (string); `repLastName` (string); `repTitle` (string).
- `sms.registrationSubmit`: Propose filing the saved draft texting registration with the carriers. Arguments: `clientId` (string).
- `sms.status`: The numbers the workspace. Arguments: `clientId` (string); `country` (string).

### AI sales rep (`sdr.*`)

- `sdr.report`: AI SDR activity report for one client over the last N days. Arguments: `clientId` (string, required); `days` (number).
- `sdr.status`: One client's AI SDR. Arguments: `clientId` (string, required).
- `sdr.summary`: One client's AI SDR configuration in full. Arguments: `clientId` (string, required).

### Approvals (`approvals.*`)

- `approvals.decide`: Approve or reject a waiting card as this key's person. Account key only. Arguments: `submissionId` (string, required); `decision` (one of `approve`, `reject`, required); `feedback` (string); `acknowledgedFees` (boolean).
- `approvals.get`: One approval card this key's person may read. Account key only. Arguments: `submissionId` (string, required).
- `approvals.list`: The approval cards waiting for this key's person to decide. Account key only. Arguments: `limit` (number).
- `approvals.rules`: The workspace's approval rules for this key's person. Account key only. Arguments: none.
- `approvals.setRule`: File a card that sets one approval rule. Account key only. Arguments: `family` (string, required); `minRoleToRun` (one of `owner`, `admin`, `member`, `nobody`, required); `approverFloor` (one of `owner`, `admin`).
- `approvals.setYolo`: File a card that turns YOLO mode on or off. Account key only. Arguments: `on` (boolean, required).

### Review requests (`submissions.*`)

- `submissions.create`: File work for human review. Arguments: `agentKey` (string, required); `kind` (one of `crm_reply`, `asset_review`, `general`); `title` (string, required); `body` (string, required); `link` (string); `refType` (string); `refId` (string); `leadId` (string); `runId` (string); `assetId` (string); `conversationId` (string).
- `submissions.list`: Approval-queue submissions. Arguments: `status` (string); `kind` (string); `limit` (number).
- `submissions.recommend`: Record an approve/reject recommendation on a submission. Arguments: `submissionId` (string, required); `recommendation` (one of `approve`, `reject`, required); `note` (string).

### Team (`team.*`)

- `team.cancelInvite`: Revoke a waiting invitation by its email. Account key only. Arguments: `email` (string, required).
- `team.invite`: Invite one person to the team by email, as an admin or a member. Account key only. Arguments: `email` (string, required); `role` (one of `admin`, `member`, required).
- `team.list`: The workspace's team for this key's person. Account key only. Arguments: none.
- `team.remove`: Remove a teammate from the workspace. Account key only. Arguments: `member` (string, required).
- `team.setRole`: File a card that makes a teammate an admin or a member. Account key only. Arguments: `member` (string, required); `role` (one of `admin`, `member`, required).

### Hires (`hires.*`)

- `hires.ask`: Give a hire a job in the person's own words, as the job page's box does. Account key only. Arguments: `hire` (string, required); `text` (string, required); `jobId` (string).
- `hires.cancel`: Let a hire go. Account key only. Arguments: `hire` (string, required).
- `hires.get`: One hire's page. Account key only. Arguments: `hire` (string, required).
- `hires.hire`: Hire a role (owner or admin, account keys only). Account key only. Arguments: `role` (string, required); `name` (string); `timezone` (string).
- `hires.list`: The roles this key's person can hire and the team's hires. Account key only. Arguments: none.
- `hires.update`: Change a hire's model. Account key only. Arguments: `hire` (string, required); `model` (null | string); `monthlyBudgetUsd` (null | number); `paused` (boolean).

### Task board (`board.*`)

- `board.comment`: Comment on a board task, optionally with files. Arguments: `taskId` (string, required); `body` (string, required); `attachmentKeys` (string[]).
- `board.create`: Create a task on the HQ board. Arguments: `title` (string, required); `notes` (string); `status` (one of `todo`, `progress`, `review`, `blocked`, `done`); `priority` (one of `high`, `med`, `low`); `clientId` (string); `assigneeUserId` (string); `assigneeAgentKey` (string); `project` (string); `dueDate` (string); `parentId` (string); `labels` (string[]); `alsoAssignedUserIds` (string[]).
- `board.get`: One board task with its description, comments and history. Arguments: `taskId` (string, required).
- `board.link`: Link a GitHub pull request, branch or commit to a board task. Arguments: `taskId` (string, required); `url` (string, required).
- `board.list`: Tasks on the HQ board, newest change first. Arguments: `clientId` (string); `status` (string); `q` (string); `number` (number); `limit` (number); `label` (string).
- `board.people`: Who a board task can be assigned to. Arguments: none.
- `board.unlink`: Remove a GitHub link from a board task. Arguments: `taskId` (string, required); `url` (string, required).
- `board.update`: Change a board task. Arguments: `taskId` (string, required); `title` (string); `notes` (string); `status` (one of `todo`, `progress`, `review`, `blocked`, `done`); `priority` (one of `high`, `med`, `low`); `assigneeUserId` (string); `assigneeAgentKey` (string); `project` (string); `dueDate` (string); `labels` (string[]); `alsoAssignedUserIds` (string[]).
- `board.uploadStart`: Start a file upload to a board task. Arguments: `taskId` (string, required); `name` (string, required); `contentType` (string, required); `size` (number, required).

### Agent tasks (`tasks.*`)

- `tasks.finish`: Terminal task transition. Arguments: `taskId` (string, required); `status` (one of `todo`, `running`, `blocked`, `done`, `failed`, required); `summary` (string).
- `tasks.get`: One task + lanes. Arguments: `taskId` (string, required).
- `tasks.lane`: Update a task lane (status/output, append mode). Arguments: `laneId` (string, required); `status` (one of `pending`, `active`, `done`, `error`); `output` (string); `append` (boolean).
- `tasks.list`: Team tasks. Arguments: `status` (string); `limit` (number).

### Runs (`runs.*`)

- `runs.cancel`: Request worker cancellation, including after a failed row. Account key only. Arguments: `runId` (string, required); `clientId` (string).
- `runs.complete`: Terminal run transition. Arguments: `runId` (string, required); `status` (one of `passed`, `failed`, `shipped`, required); `note` (string).
- `runs.get`: One run + its steps. Arguments: `runId` (string, required).
- `runs.grade`: Store the QA grade on a run. Arguments: `runId` (string, required); `gradeChecks` (object[], required); `verdict` (string, required); `note` (string, required).
- `runs.list`: Agent runs, newest first. Arguments: `status` (string); `limit` (number).
- `runs.start`: Start an agent run as the account key user. Account key only. Arguments: `clientId` (string); `type` (one of `offers`, `ads`, `emails`, `content`, `research`, `funnels`, `leads`, `copy`, `wiki`, `reports`, required); `goal` (string, required); `auto` (boolean).
- `runs.stepOutput`: Set (output) or append (chunk) a step's output. Arguments: `runId` (string, required); `key` (one of `research`, `build`, `grade`, `ship`, required); `output` (string); `chunk` (string).
- `runs.stepStatus`: Set a run step's status. Arguments: `runId` (string, required); `key` (one of `research`, `build`, `grade`, `ship`, required); `status` (one of `pending`, `active`, `done`, `error`, required).

### Payments (`payments.*`)

- `payments.list`: Who bought: payments newest first, each with the buyer's name and email, amount, product, date and status, and where the buyer came from. Arguments: `clientId` (string); `limit` (number); `email` (string); `status` (string).

### Integrations (`integrations.*`)

- `integrations.connect`: A Cook link where the person connects Whop. Arguments: `clientId` (string).

### Search (`search.*`)

- `search.embed`: Embed the caller's own short texts. Arguments: `texts` (string[], required); `kind` (one of `document`, `query`).

### Chat replies (agent host) (`chat.*`)

- `chat.append`: Append a chunk to a streaming direct-chat assistant reply. Arguments: `messageId` (string, required); `chunk` (string, required).
- `chat.finalize`: Finalize a direct-chat assistant reply. Arguments: `messageId` (string, required); `text` (string); `status` (one of `done`, `error`).

### Goal loop (agent host) (`goal.*`)

- `goal.advance`: Drive the /goal loop after a goal turn. Arguments: `threadId` (string, required); `verdict` (one of `DONE`, `CONTINUE`, required); `reason` (string).

### Usage (agent host) (`usage.*`)

- `usage.costReport`: The real billed cost of the workspace's media generations. Account key only. Arguments: `sinceMinutes` (number); `includeUrls` (boolean).
- `usage.record`: Self-report usage for metering. Arguments: `kind` (one of `inference`, `sandbox`, required); `model` (string); `provider` (string); `inputTokens` (number); `outputTokens` (number); `totalTokens` (number); `costUsd` (number); `byo` (boolean); `runId` (string); `source` (string).

### Agent host (`host.*`)

- `host.config`: Hosted-ingress boot config (webhook secret once provisioned). Arguments: none.

### AiVisibility (`aiVisibility.*`)

- `aiVisibility.results`: AI visibility panels. Arguments: `panelId` (string); `clientId` (string); `runs` (number).

### Billing (`billing.*`)

- `billing.paymentMethods.add`: Start adding a card. Account key only. Arguments: none.
- `billing.paymentMethods.list`: The payment methods the workspace pays with. Account key only. Arguments: none.
- `billing.paymentMethods.remove`: Remove a payment method. Account key only. Arguments: `paymentMethod` (string, required).
- `billing.paymentMethods.setDefault`: Make a payment method the default. Account key only. Arguments: `paymentMethod` (string, required).

### Calls (`calls.*`)

- `calls.list`: Every call the workspace has in a window, from every source. Account key only. Arguments: `client` (string); `link` (string); `sinceDaysAgo` (number); `sinceHoursAgo` (number); `untilDaysAgo` (number); `untilHoursAhead` (number); `limit` (number).
- `calls.transcript`: The full transcript of one call by its calls.list id, fenced as untrusted. Account key only. Arguments: `meetingId` (string, required).

### Cloudflare (`cloudflare.*`)

- `cloudflare.workerDeploy`: Propose deploying a Worker to the workspace's own Cloudflare account. Arguments: `script` (string, required); `mainModule` (string, required); `modules` (object[], required); `compatibilityDate` (string); `compatibilityFlags` (string[]); `d1` (object[]); `vars` (object[]).
- `cloudflare.workers`: The workspace's own Cloudflare account as Cook reads it through the API token connected in Integrations. Arguments: none.
- `cloudflare.workerSecretRequest`: Ask for a secret on one of the workspace's Cloudflare Workers. Arguments: `script` (string, required); `name` (string, required); `why` (string).

### Ghl (`ghl.*`)

- `ghl.addTags`: Add tags to one GoHighLevel contact. Account key only. Arguments: `client` (string); `contactId` (string, required); `tags` (string[], required).
- `ghl.appointments`: Appointments synced from the workspace's GoHighLevel calendars in a window, with the exact count. Account key only. Arguments: `basis` (one of `booked`, `scheduled`); `range` (one of `today`, `tomorrow`, `yesterday`, `next_7_days`, `last_7_days`, `next_30_days`, `last_30_days`); `from` (string); `to` (string); `timezone` (string); `status` (string); `includeCancelled` (boolean); `limit` (number).
- `ghl.contacts`: GoHighLevel contacts by name/email/phone. Account key only. Arguments: `client` (string); `query` (string); `tags` (string[]); `limit` (number); `startAfterId` (string); `startAfter` (number).
- `ghl.conversations`: GoHighLevel conversations, newest first, with each thread's last message. Account key only. Arguments: `client` (string); `contactId` (string); `limit` (number); `startAfterDate` (number).
- `ghl.messages`: The messages of one GoHighLevel conversation. Account key only. Arguments: `client` (string); `conversationId` (string, required); `limit` (number).
- `ghl.opportunities`: GoHighLevel opportunities. Account key only. Arguments: `client` (string); `status` (string); `limit` (number).
- `ghl.pipelines`: GoHighLevel sales pipelines and their stages, as Cook's agent reads them. Account key only. Arguments: `client` (string).
- `ghl.sendMessage`: Propose an SMS or WhatsApp to one GoHighLevel contact. Account key only. Arguments: `client` (string); `contactId` (string, required); `message` (string, required); `channel` (one of `SMS`, `WhatsApp`).
- `ghl.sync`: Pull the workspace's GoHighLevel pipelines, opportunities. Account key only. Arguments: `clientId` (string).

### Import (`import.*`)

- `import.start`: Move a tool's account into Cook. Arguments: `tool` (one of `ghl`, `calendly`, `typeform`, `higgsfield`, required); `clientId` (string · id); `since` (number); `requestIds` (string[]); `credentials` (object (map)).
- `import.status`: An import job's report. Arguments: `jobId` (string); `tool` (one of `ghl`, `calendly`, `typeform`, `higgsfield`).

### Products (`products.*`)

- `products.createWhop`: Propose a product people buy on Whop. Account key only. Arguments: `name` (string, required); `price` (string | number, required); `files` (string[], required); `currency` (string); `description` (string); `mode` (one of `test`, `live`); `clientId` (string).
- `products.list`: What the workspace sells. Arguments: `client` (string); `productId` (string).
- `products.trackedLink`: A buy link for a Whop product that names where it is placed. Arguments: `clientId` (string); `product` (string, required); `placement` (string, required).

### Research (`research.*`)

- `research.adLibrary`: Search other advertisers' running ads. Arguments: `query` (string, required); `platform` (one of `meta`, `tiktok`, `youtube`, `all`); `minDaysRunning` (number); `country` (string); `limit` (number).
- `research.swipes`: Search the workspace's own swipe library. Account key only. Arguments: `query` (string, required); `type` (string); `limit` (number).

### Sandbox (`sandbox.*`)

- `sandbox.check`: The state of a background sandbox.run job, collecting it when it has finished. Account key only. Arguments: `jobId` (string, required).
- `sandbox.run`: Run a bash script in a fresh Linux sandbox, the one Cook's chat agent uses. Account key only. Arguments: `script` (string, required); `outputs` (string[], required); `inputs` (string[]); `saveDir` (string); `timeoutSeconds` (number); `background` (boolean); `memoryMb` (number); `label` (string).

### Skills (`skills.*`)

- `skills.list`: The skills Cook's chat agent works from. Account key only. Arguments: none.
- `skills.read`: One of Cook's skills. Account key only. Arguments: `name` (string, required); `path` (string).

### Webhooks (`webhooks.*`)

- `webhooks.create`: Subscribe an HTTPS URL to events. Arguments: `name` (string, required); `url` (string, required); `events` (string[], required).
- `webhooks.delete`: Delete a webhook subscription. Arguments: `id` (string, required).
- `webhooks.deliveries`: A subscription's recent delivery attempts. Arguments: `id` (string, required).
- `webhooks.events`: The events a webhook can subscribe to. Arguments: none.
- `webhooks.list`: The workspace's outbound webhook subscriptions. Arguments: none.
- `webhooks.test`: Send one signed webhook.test event to a subscription. Arguments: `id` (string, required).