Agent
Chats with the in-app Agent, its approvals, models, skills and guidance.
Get the Agent's approval settings
When the Agent may act without asking.
The workspace's rules for the in-app Agent's approvals: whether members may choose Run everything (owners and admins always may) and the budget guardrail, the largest budget or bid increase, or new spend, the Agent makes without asking (above it, it always asks, even with Run everything). canRunEverything says whether the caller may choose Run everything now, with reason when not. A person's own choice is their agentApprovals preference (PUT /preferences/agentApprovals). Also in MCP as get_agent_approval_settings.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
budgetGuardrailbudgetGuardrail.amount- Also the largest raise per change (per day for daily budgets), as a decimal string in
currency; only for ad accounts in that currency. Null: the percent alone. budgetGuardrail.currency- ISO 4217, a currency Meta supports; given exactly when
amountis. budgetGuardrail.percent- The largest raise of a budget or bid, and of new spend next to what the ad account spends a day, as a decimal string percent from 0 to 1000 (default "50").
canEdit- The caller is an owner or admin.
canRunEverything- The caller may choose Run everything now: a person signed in to Pluto, where the workspace lets them.
membersCanTurnOffApprovals- Members may choose Run everything; owners and admins always may.
reason- Why not, when
canRunEverythingis false. updatedAt- Last saved; null before the first save.
version- Saves so far; send it as
expectedVersion.
curl "$PLUTO_API/agent/approval-settings" \
-H "Authorization: Bearer $PLUTO_KEY"Set the Agent's approval settings
Set when the Agent may act without asking.
Owners and admins. Each setting is optional; what you leave out stays. When members may not turn approvals off, their Agent asks for risky actions again. expectedVersion is version; a newer save answers 409 with current. Also in MCP as set_agent_approval_settings.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
budgetGuardrailbudgetGuardrail.amount- Also the largest raise per change (per day for daily budgets), as a decimal string in
currency; only for ad accounts in that currency. Null: the percent alone. budgetGuardrail.currency- ISO 4217, a currency Meta supports; given exactly when
amountis. budgetGuardrail.percent- The largest raise of a budget or bid, and of new spend next to what the ad account spends a day, as a decimal string percent from 0 to 1000 (default "50").
expectedVersionversionthe change is based on (0 before the first save).membersCanTurnOffApprovals- Whether members may choose Run everything.
Response
budgetGuardrailbudgetGuardrail.amount- Also the largest raise per change (per day for daily budgets), as a decimal string in
currency; only for ad accounts in that currency. Null: the percent alone. budgetGuardrail.currency- ISO 4217, a currency Meta supports; given exactly when
amountis. budgetGuardrail.percent- The largest raise of a budget or bid, and of new spend next to what the ad account spends a day, as a decimal string percent from 0 to 1000 (default "50").
canEdit- The caller is an owner or admin.
canRunEverything- The caller may choose Run everything now: a person signed in to Pluto, where the workspace lets them.
membersCanTurnOffApprovals- Members may choose Run everything; owners and admins always may.
reason- Why not, when
canRunEverythingis false. updatedAt- Last saved; null before the first save.
version- Saves so far; send it as
expectedVersion.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PUT "$PLUTO_API/agent/approval-settings" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: f129c590-9b30-4df7-8e57-d1c56c6b33da" \
-H "Content-Type: application/json" \
-d '{
"budgetGuardrail": {
"amount": "150.00",
"currency": "USD",
"percent": "20"
},
"expectedVersion": 3,
"membersCanTurnOffApprovals": true
}'Resolve proposed actions
Approves or declines waiting approvals of one answer as one decision (the app's grouped item, "Turn off 86 Pages"): each is decided as its own approve or reject would (approve runs it as the signed-in person, once, and needs its permission), in the order given, and the answer continues once, after the last. Who may decide and the permissions are checked for all of them first (403 or 422, nothing decided). Retried with the same Idempotency-Key, what was decided is replayed. Answers with the stream: an approval event per decision, the continued answer, done; a decision that fails on the way ends it with error, and what was decided stays.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
approvalIds- 1 to 200 waiting approvals of one answer, decided in this order.
decision- Approve all of them, or decline all of them.One of
approve,reject reason- Why you declined, up to 1000 characters; the Agent reads it.
Response
approvalapproval.canApprove- The viewer can approve it: the same as
canDecide. approval.canDecide- The viewer may approve or decline it: they hold
capability, and it's theirs to decide (the person the Agent proposed it for, or an organization owner or admin). approval.capability- What approving or declining it needs, as a capability ID (
ads:publish): the capability of the tool it runs, or of what its call asked for beyond it (a copy made at the platform). Someone without it never decides it, the person who asked included. approval.chatId- Chat.
approval.createdAt- Proposed.
approval.decidedAt- Decided.
approval.effectapproval.effect.done- The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approval.effect.entities- What it changes.
approval.effect.entities[].id- ID.
approval.effect.entities[].kind- Kind.One of
launch,adSet,ad approval.effect.entities[].launchId- Its launch.
approval.effect.entities[].name- Name.
approval.effect.lines- Human details, never field names or IDs.
approval.effect.lines[].label- A human label, e.g. Trigger.
approval.effect.lines[].value- Its value, e.g. New comment.
approval.effect.money- Amounts it spends or sets.
approval.effect.money[].amount- A decimal amount; never a float.
approval.effect.money[].currency- ISO 4217; null when the account's currency isn't known.
approval.effect.money[].label- Label.
approval.effect.subject- What it acts on, one quiet line to show under the title without expanding; absent for most actions. A comment action names the comment: v.i.u.m: “Does this work for small teams?” on App review test.
approval.effect.summary- What it does, in a sentence; empty when that would only repeat
title. approval.effect.title- The action as one sentence with real names, never IDs: Delete loop “Facebook comment moderator”. A tool without its own sentence reads as its title.
approval.effect.warnings- Things to know before approving.
approval.error- Why it failed, or the reason it was declined.
approval.error.code- Stable code.
approval.error.message- For the person.
approval.error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. approval.id- Approval.
approval.messageId- The answer that proposed it.
approval.permission- The coarse permission the call asked with: the action's own (
read,revieworwriteonly when the person chose Ask every time). What deciding needs iscapability.One ofread,review,write,publish,admin,organization approval.result- After approving.
approval.result.jobId- The job it started.
approval.result.summary- What happened.
approval.status- State.One of
pending,approved,rejected,failed,superseded approval.title- What it does, as one sentence with real names and never IDs, e.g. Delete loop “Facebook comment moderator”. The same as
effect.title. approval.tool- The MCP tool it runs.
chatchat.createdAt- Started.
chat.effort- The reasoning effort picked for the chat; null: the model's default.
chat.id- Chat.
chat.lastMessageAt- Last message.
chat.loopId- The loop it is the history of (it made the loop, or was started in its builder).
chat.model- The chat's model:
pluto,autoor a model ID fromGET /agent/models. chat.ownerId- The chat's person: only they rename, delete or share it.
chat.shared- Shared with everyone who can see its loop; false: private to its person.
chat.source- Where it started.One of
page,panel,home,loop chat.status- What it's doing.One of
idle,running,awaiting_approval chat.title- Title; null until the first answer names it.
chat.unread- An answer arrived after the person last read it.
chat.updatedAt- Last change.
codeerror: spend_limit, payment_required, model_unavailable, rate_limited, refusal, max_tokens, step_limit or internal.delta- Text to append.
messagemessage.approvalIds- Approvals raised in this answer.
message.attachments- Files the person attached.
message.attachments[].contentType- A chat file's type.
message.attachments[].fileId- A chat file, uploaded for the message.
message.attachments[].kind- Kind (a media library item is an
imageor avideo).One ofimage,video,pdf,document,spreadsheet,presentation,text,code,audio,archive message.attachments[].mediaId- A media library item.
message.attachments[].name- File name.
message.attachments[].pageCount- Pages of a PDF, Word document or presentation.
message.attachments[].previewUrl- A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
message.attachments[].sizeBytes- A chat file's size.
message.chatId- Chat.
message.completedAt- Finished.
message.createdAt- Written.
message.error- Why the answer failed.
message.error.code- Stable code.
message.error.message- For the person.
message.error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. message.id- Message.
message.model- The model that produced the answer; null for the person's messages.
message.parts- The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
message.parts[].answerquestion: the answer once given (a choice's label, or the words of your reply).message.parts[].choiceIdquestion: the choice it was answered with.message.parts[].choicesquestion: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).message.parts[].columnstable: its columns.message.parts[].data- Every kind but
comboandtable: the series. message.parts[].description- One line under the title: the period, the unit.
message.parts[].groupscombo: its groups.message.parts[].id- The part; the same ID again replaces it.
message.parts[].itemsads: the ads, in the order shown.message.parts[].kind- How it's drawn;
tableis a table.One ofline,bar,horizontal-bar,stacked-bar,stacked-area,donut,funnel,combo,simple-bar,simple-normalized,spark-line,spark-bar,table message.parts[].optionsselection: the options (POST /agent/chats/{id}/parts/{part_id}/select).message.parts[].periodads: the days of itsmetrics:since,untilandpreset(last_30_days, …, or null).message.parts[].proposedselection: the options the Agent recommends, checked at first.message.parts[].rowstable: its rows.message.parts[].selectedselection: the options you confirmed.message.parts[].showLegend- Whether a legend shows; absent: for two or more series.
message.parts[].sizesimple-normalizedonly.One ofsmall,medium,largemessage.parts[].textquestion: the question.text: the words (Markdown).message.parts[].title- What it shows.
message.parts[].type- A chart or a table, a question the Agent asks, options it proposes, ads it shows as cards, or the answer's words written before the card that follows them.One of
chart,question,selection,ads,text message.parts[].valueFormat- How values read:
style(decimal,percentwith values as percentages,currencywithcurrency),notation,minimumFractionDigits,maximumFractionDigits,unit. message.parts[].xAxislabel,hide.message.parts[].yAxislabel,integersOnly.message.role- Who wrote it.One of
user,assistant message.sentBy- Who sent a person's message (only they edit it); null for answers and for older messages, which are the chat's person's.
message.sources- The web pages the answer used: cited pages in the order first cited, then pages it read without citing; each URL once. Empty when it didn't use the web.
message.sources[].site- The hostname without
www.. message.sources[].title- Its title (its site when it named none).
message.sources[].url- The page.
message.status- State:
waitingfor credits;awaiting_userwhen the answer asked a question or proposed a selection (parts) and waits for your reply.One ofcomplete,streaming,stopped,failed,awaiting_approval,waiting,awaiting_user message.steps- What the Agent did, in order.
message.steps[].category- What kind of call it is, for a summary like "Created 2 launches, ran a search": from what the tool does (adds, changes, reads, lists, searches),
mcpfor another Pluto product (server). Absent for narration and thinking, and on older steps.One ofwrite,edit,read,list,search,mcp,other message.steps[].detail- Error, reasoning or narration text; a search's query; a read page's URL.
message.steps[].entities- What it touched.
message.steps[].entities[].id- ID.
message.steps[].entities[].kind- Kind.One of
launch,adSet,ad message.steps[].entities[].launchId- Its launch.
message.steps[].entities[].name- Name.
message.steps[].finishedAt- Finished.
message.steps[].id- Step.
message.steps[].kind- A tool call, narration before tools, summarized reasoning, a web search (
detailis the query) or a web page read (detailis its URL).One oftool,note,thinking,search,fetch message.steps[].label- Present tense while running, past tense when done.
message.steps[].server- The Pluto product an
mcpstep used, e.g.Pluto Profit. message.steps[].startedAt- Started.
message.steps[].status- State.One of
running,done,failed,awaiting_approval,rejected,stopped message.steps[].tool- The MCP tool; null for every kind but
tool. message.text- The question, or the answer (markdown;
pluto:links name launches, ad sets and ads). message.version- Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
message.versions- How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
message.workedMs- Active time, excluding waits for approval.
messageId- The Agent message a delta belongs to.
partpart.answerquestion: the answer once given (a choice's label, or the words of your reply).part.choiceIdquestion: the choice it was answered with.part.choicesquestion: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).part.columnstable: its columns.part.data- Every kind but
comboandtable: the series. part.description- One line under the title: the period, the unit.
part.groupscombo: its groups.part.id- The part; the same ID again replaces it.
part.itemsads: the ads, in the order shown.part.kind- How it's drawn;
tableis a table.One ofline,bar,horizontal-bar,stacked-bar,stacked-area,donut,funnel,combo,simple-bar,simple-normalized,spark-line,spark-bar,table part.optionsselection: the options (POST /agent/chats/{id}/parts/{part_id}/select).part.periodads: the days of itsmetrics:since,untilandpreset(last_30_days, …, or null).part.proposedselection: the options the Agent recommends, checked at first.part.rowstable: its rows.part.selectedselection: the options you confirmed.part.showLegend- Whether a legend shows; absent: for two or more series.
part.sizesimple-normalizedonly.One ofsmall,medium,largepart.textquestion: the question.text: the words (Markdown).part.title- What it shows.
part.type- A chart or a table, a question the Agent asks, options it proposes, ads it shows as cards, or the answer's words written before the card that follows them.One of
chart,question,selection,ads,text part.valueFormat- How values read:
style(decimal,percentwith values as percentages,currencywithcurrency),notation,minimumFractionDigits,maximumFractionDigits,unit. part.xAxislabel,hide.part.yAxislabel,integersOnly.reasonerrorwith spend_limit: which limit stopped it (member_limit, workspace_limit or trial_cap); with payment_required: why there's no access.retryableerror: whether retrying can help.sourcessourcesevents: the answer's web pages so far.sources[].site- The hostname without
www.. sources[].title- Its title (its site when it named none).
sources[].url- The page.
stallstall: why the answer seems stuck, decided from the stream:no_first_byte(the model sent nothing for 10 s),silent_stream(an open stream sent no event for 15 s) orsilent_tool(a tool reported nothing for 45 s), andsince, when the silence began (epoch milliseconds);nullonce it moves again.stall.kind- What went quiet.One of
no_first_byte,silent_stream,silent_tool stall.since- When the silence began, epoch milliseconds.
stepstep.category- What kind of call it is, for a summary like "Created 2 launches, ran a search": from what the tool does (adds, changes, reads, lists, searches),
mcpfor another Pluto product (server). Absent for narration and thinking, and on older steps.One ofwrite,edit,read,list,search,mcp,other step.detail- Error, reasoning or narration text; a search's query; a read page's URL.
step.entities- What it touched.
step.entities[].id- ID.
step.entities[].kind- Kind.One of
launch,adSet,ad step.entities[].launchId- Its launch.
step.entities[].name- Name.
step.finishedAt- Finished.
step.id- Step.
step.kind- A tool call, narration before tools, summarized reasoning, a web search (
detailis the query) or a web page read (detailis its URL).One oftool,note,thinking,search,fetch step.label- Present tense while running, past tense when done.
step.server- The Pluto product an
mcpstep used, e.g.Pluto Profit. step.startedAt- Started.
step.status- State.One of
running,done,failed,awaiting_approval,rejected,stopped step.tool- The MCP tool; null for every kind but
tool. stepId- The thinking step a delta belongs to.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/agent/approvals/decide" \
-b "plutoads_session=$PLUTO_SESSION" \
-H "Idempotency-Key: 5b2f7964-f836-4cef-991a-86bd2f67a938" \
-H "Content-Type: application/json" \
-d '{
"approvalIds": [
"1fa0aef8-e184-47c2-9e38-d15e5b1cb1c3"
],
"decision": "approve",
"reason": "Spend is pacing ahead of plan; hold the budget until Friday."
}'Read a proposed action sent to you
The card of an Agent proposal sent to your Inbox (an approval item; its approval.id). A member's Agent may propose an action their role leaves out; proposed in their own chat, which nobody else opens, it is sent to the workspace's members who hold what deciding it needs, never to the person who asked. The card is what the chat's card shows of it (effect), who asked (proposedBy), how it stands and who decided it, and nothing of the chat: no chat, no message, no chat title. canDecide while you hold capability and may use the Agent, checked again when you decide and when the action runs. 404 for anyone it wasn't sent to, the person who asked included (they read it in their chat).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The approval's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
canApprove- You can approve it: the same as
canDecide. canDecide- You may approve or reject it now: you hold
capabilityand may use the Agent. Checked again when you decide and when it runs. capability- What approving or rejecting it needs, as a capability ID (
ads:publish). The person who asked doesn't hold it. createdAt- Proposed.
decidedAt- Decided.
decidedBy- Who approved or rejected it; null while it waits, or once it was taken back.
decidedBy.id- Person.
decidedBy.name- Their name now; null once their account is gone.
effecteffect.done- The same once it ran.
effect.entities- What it changes.
effect.entities[].id- ID.
effect.entities[].kind- Kind.One of
launch,adSet,ad effect.entities[].launchId- Its launch.
effect.entities[].name- Name.
effect.lines- Human details, never field names or IDs.
effect.lines[].label- A human label.
effect.lines[].value- Its value.
effect.money- Amounts it spends or sets.
effect.money[].amount- A decimal amount; never a float.
effect.money[].currency- ISO 4217; null when the account's currency isn't known.
effect.money[].label- Label.
effect.subject- What it acts on, one quiet line under the title; absent for most actions.
effect.summary- What it does, in a sentence; empty when that would only repeat
title. effect.title- The action as one sentence with real names, never IDs.
effect.warnings- Things to know before approving.
error- Why it failed, or the reason it was rejected.
error.code- Stable code.
error.message- For the person.
error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. expiresAt- Until when approving it runs it (a day after it was proposed); rejecting still clears it after.
id- Approval.
permission- The coarse permission the call asked with. What deciding needs is
capability.One ofread,review,write,publish,admin,organization proposedBy- Who asked: the person the Agent proposed it for.
proposedBy.id- Person.
proposedBy.name- Their name now; null once their account is gone.
result- After approving.
result.jobId- The job it started.
result.summary- What happened.
status- State.
superseded: the person who asked took it back.One ofpending,approved,rejected,failed,superseded title- What it does, as one sentence with real names and never IDs. The same as
effect.title. tool- The MCP tool it runs.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/agent/approvals/1fa0aef8-e184-47c2-9e38-d15e5b1cb1c3" \
-H "Authorization: Bearer $PLUTO_KEY"Approve a proposed action
Runs the action exactly as the approval card shows it, as the signed-in person and once (the command ID is the approval's), then continues the answer. Only a person can approve, and approving needs the action's own permission (publish or admin). In a loop's shared chat only the person the Agent proposed it for, or an organization owner or admin, decides it (403 otherwise). A launch changed since the proposal fails the approval instead of publishing something else. Answers with the stream: approval, the continued answer, done.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The approval's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
object
Response
approvalapproval.canApprove- The viewer can approve it: the same as
canDecide. approval.canDecide- The viewer may approve or decline it: they hold
capability, and it's theirs to decide (the person the Agent proposed it for, or an organization owner or admin). approval.capability- What approving or declining it needs, as a capability ID (
ads:publish): the capability of the tool it runs, or of what its call asked for beyond it (a copy made at the platform). Someone without it never decides it, the person who asked included. approval.chatId- Chat.
approval.createdAt- Proposed.
approval.decidedAt- Decided.
approval.effectapproval.effect.done- The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approval.effect.entities- What it changes.
approval.effect.entities[].id- ID.
approval.effect.entities[].kind- Kind.One of
launch,adSet,ad approval.effect.entities[].launchId- Its launch.
approval.effect.entities[].name- Name.
approval.effect.lines- Human details, never field names or IDs.
approval.effect.lines[].label- A human label, e.g. Trigger.
approval.effect.lines[].value- Its value, e.g. New comment.
approval.effect.money- Amounts it spends or sets.
approval.effect.money[].amount- A decimal amount; never a float.
approval.effect.money[].currency- ISO 4217; null when the account's currency isn't known.
approval.effect.money[].label- Label.
approval.effect.subject- What it acts on, one quiet line to show under the title without expanding; absent for most actions. A comment action names the comment: v.i.u.m: “Does this work for small teams?” on App review test.
approval.effect.summary- What it does, in a sentence; empty when that would only repeat
title. approval.effect.title- The action as one sentence with real names, never IDs: Delete loop “Facebook comment moderator”. A tool without its own sentence reads as its title.
approval.effect.warnings- Things to know before approving.
approval.error- Why it failed, or the reason it was declined.
approval.error.code- Stable code.
approval.error.message- For the person.
approval.error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. approval.id- Approval.
approval.messageId- The answer that proposed it.
approval.permission- The coarse permission the call asked with: the action's own (
read,revieworwriteonly when the person chose Ask every time). What deciding needs iscapability.One ofread,review,write,publish,admin,organization approval.result- After approving.
approval.result.jobId- The job it started.
approval.result.summary- What happened.
approval.status- State.One of
pending,approved,rejected,failed,superseded approval.title- What it does, as one sentence with real names and never IDs, e.g. Delete loop “Facebook comment moderator”. The same as
effect.title. approval.tool- The MCP tool it runs.
chatchat.createdAt- Started.
chat.effort- The reasoning effort picked for the chat; null: the model's default.
chat.id- Chat.
chat.lastMessageAt- Last message.
chat.loopId- The loop it is the history of (it made the loop, or was started in its builder).
chat.model- The chat's model:
pluto,autoor a model ID fromGET /agent/models. chat.ownerId- The chat's person: only they rename, delete or share it.
chat.shared- Shared with everyone who can see its loop; false: private to its person.
chat.source- Where it started.One of
page,panel,home,loop chat.status- What it's doing.One of
idle,running,awaiting_approval chat.title- Title; null until the first answer names it.
chat.unread- An answer arrived after the person last read it.
chat.updatedAt- Last change.
codeerror: spend_limit, payment_required, model_unavailable, rate_limited, refusal, max_tokens, step_limit or internal.delta- Text to append.
messagemessage.approvalIds- Approvals raised in this answer.
message.attachments- Files the person attached.
message.attachments[].contentType- A chat file's type.
message.attachments[].fileId- A chat file, uploaded for the message.
message.attachments[].kind- Kind (a media library item is an
imageor avideo).One ofimage,video,pdf,document,spreadsheet,presentation,text,code,audio,archive message.attachments[].mediaId- A media library item.
message.attachments[].name- File name.
message.attachments[].pageCount- Pages of a PDF, Word document or presentation.
message.attachments[].previewUrl- A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
message.attachments[].sizeBytes- A chat file's size.
message.chatId- Chat.
message.completedAt- Finished.
message.createdAt- Written.
message.error- Why the answer failed.
message.error.code- Stable code.
message.error.message- For the person.
message.error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. message.id- Message.
message.model- The model that produced the answer; null for the person's messages.
message.parts- The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
message.parts[].answerquestion: the answer once given (a choice's label, or the words of your reply).message.parts[].choiceIdquestion: the choice it was answered with.message.parts[].choicesquestion: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).message.parts[].columnstable: its columns.message.parts[].data- Every kind but
comboandtable: the series. message.parts[].description- One line under the title: the period, the unit.
message.parts[].groupscombo: its groups.message.parts[].id- The part; the same ID again replaces it.
message.parts[].itemsads: the ads, in the order shown.message.parts[].kind- How it's drawn;
tableis a table.One ofline,bar,horizontal-bar,stacked-bar,stacked-area,donut,funnel,combo,simple-bar,simple-normalized,spark-line,spark-bar,table message.parts[].optionsselection: the options (POST /agent/chats/{id}/parts/{part_id}/select).message.parts[].periodads: the days of itsmetrics:since,untilandpreset(last_30_days, …, or null).message.parts[].proposedselection: the options the Agent recommends, checked at first.message.parts[].rowstable: its rows.message.parts[].selectedselection: the options you confirmed.message.parts[].showLegend- Whether a legend shows; absent: for two or more series.
message.parts[].sizesimple-normalizedonly.One ofsmall,medium,largemessage.parts[].textquestion: the question.text: the words (Markdown).message.parts[].title- What it shows.
message.parts[].type- A chart or a table, a question the Agent asks, options it proposes, ads it shows as cards, or the answer's words written before the card that follows them.One of
chart,question,selection,ads,text message.parts[].valueFormat- How values read:
style(decimal,percentwith values as percentages,currencywithcurrency),notation,minimumFractionDigits,maximumFractionDigits,unit. message.parts[].xAxislabel,hide.message.parts[].yAxislabel,integersOnly.message.role- Who wrote it.One of
user,assistant message.sentBy- Who sent a person's message (only they edit it); null for answers and for older messages, which are the chat's person's.
message.sources- The web pages the answer used: cited pages in the order first cited, then pages it read without citing; each URL once. Empty when it didn't use the web.
message.sources[].site- The hostname without
www.. message.sources[].title- Its title (its site when it named none).
message.sources[].url- The page.
message.status- State:
waitingfor credits;awaiting_userwhen the answer asked a question or proposed a selection (parts) and waits for your reply.One ofcomplete,streaming,stopped,failed,awaiting_approval,waiting,awaiting_user message.steps- What the Agent did, in order.
message.steps[].category- What kind of call it is, for a summary like "Created 2 launches, ran a search": from what the tool does (adds, changes, reads, lists, searches),
mcpfor another Pluto product (server). Absent for narration and thinking, and on older steps.One ofwrite,edit,read,list,search,mcp,other message.steps[].detail- Error, reasoning or narration text; a search's query; a read page's URL.
message.steps[].entities- What it touched.
message.steps[].entities[].id- ID.
message.steps[].entities[].kind- Kind.One of
launch,adSet,ad message.steps[].entities[].launchId- Its launch.
message.steps[].entities[].name- Name.
message.steps[].finishedAt- Finished.
message.steps[].id- Step.
message.steps[].kind- A tool call, narration before tools, summarized reasoning, a web search (
detailis the query) or a web page read (detailis its URL).One oftool,note,thinking,search,fetch message.steps[].label- Present tense while running, past tense when done.
message.steps[].server- The Pluto product an
mcpstep used, e.g.Pluto Profit. message.steps[].startedAt- Started.
message.steps[].status- State.One of
running,done,failed,awaiting_approval,rejected,stopped message.steps[].tool- The MCP tool; null for every kind but
tool. message.text- The question, or the answer (markdown;
pluto:links name launches, ad sets and ads). message.version- Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
message.versions- How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
message.workedMs- Active time, excluding waits for approval.
messageId- The Agent message a delta belongs to.
partpart.answerquestion: the answer once given (a choice's label, or the words of your reply).part.choiceIdquestion: the choice it was answered with.part.choicesquestion: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).part.columnstable: its columns.part.data- Every kind but
comboandtable: the series. part.description- One line under the title: the period, the unit.
part.groupscombo: its groups.part.id- The part; the same ID again replaces it.
part.itemsads: the ads, in the order shown.part.kind- How it's drawn;
tableis a table.One ofline,bar,horizontal-bar,stacked-bar,stacked-area,donut,funnel,combo,simple-bar,simple-normalized,spark-line,spark-bar,table part.optionsselection: the options (POST /agent/chats/{id}/parts/{part_id}/select).part.periodads: the days of itsmetrics:since,untilandpreset(last_30_days, …, or null).part.proposedselection: the options the Agent recommends, checked at first.part.rowstable: its rows.part.selectedselection: the options you confirmed.part.showLegend- Whether a legend shows; absent: for two or more series.
part.sizesimple-normalizedonly.One ofsmall,medium,largepart.textquestion: the question.text: the words (Markdown).part.title- What it shows.
part.type- A chart or a table, a question the Agent asks, options it proposes, ads it shows as cards, or the answer's words written before the card that follows them.One of
chart,question,selection,ads,text part.valueFormat- How values read:
style(decimal,percentwith values as percentages,currencywithcurrency),notation,minimumFractionDigits,maximumFractionDigits,unit. part.xAxislabel,hide.part.yAxislabel,integersOnly.reasonerrorwith spend_limit: which limit stopped it (member_limit, workspace_limit or trial_cap); with payment_required: why there's no access.retryableerror: whether retrying can help.sourcessourcesevents: the answer's web pages so far.sources[].site- The hostname without
www.. sources[].title- Its title (its site when it named none).
sources[].url- The page.
stallstall: why the answer seems stuck, decided from the stream:no_first_byte(the model sent nothing for 10 s),silent_stream(an open stream sent no event for 15 s) orsilent_tool(a tool reported nothing for 45 s), andsince, when the silence began (epoch milliseconds);nullonce it moves again.stall.kind- What went quiet.One of
no_first_byte,silent_stream,silent_tool stall.since- When the silence began, epoch milliseconds.
stepstep.category- What kind of call it is, for a summary like "Created 2 launches, ran a search": from what the tool does (adds, changes, reads, lists, searches),
mcpfor another Pluto product (server). Absent for narration and thinking, and on older steps.One ofwrite,edit,read,list,search,mcp,other step.detail- Error, reasoning or narration text; a search's query; a read page's URL.
step.entities- What it touched.
step.entities[].id- ID.
step.entities[].kind- Kind.One of
launch,adSet,ad step.entities[].launchId- Its launch.
step.entities[].name- Name.
step.finishedAt- Finished.
step.id- Step.
step.kind- A tool call, narration before tools, summarized reasoning, a web search (
detailis the query) or a web page read (detailis its URL).One oftool,note,thinking,search,fetch step.label- Present tense while running, past tense when done.
step.server- The Pluto product an
mcpstep used, e.g.Pluto Profit. step.startedAt- Started.
step.status- State.One of
running,done,failed,awaiting_approval,rejected,stopped step.tool- The MCP tool; null for every kind but
tool. stepId- The thinking step a delta belongs to.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/agent/approvals/1fa0aef8-e184-47c2-9e38-d15e5b1cb1c3/approve" \
-b "plutoads_session=$PLUTO_SESSION" \
-H "Idempotency-Key: 16093ffc-c065-499a-abfa-ef7160e79921" \
-H "Content-Type: application/json" \
-d '{}'Resolve a proposal sent to you
Approves or rejects a proposal sent to your Inbox, from its card, without its chat. approve runs the action exactly as the card shows it, as you and once (the command ID is the approval's); reject clears it, and the Agent reads your reason. Only a person who holds its capability decides it (403 naming it otherwise), checked again as the action runs; approving a day after it was proposed answers 409 and runs nothing. The person who asked sees the outcome in their chat, and their answer continues. Retried with the same Idempotency-Key, the decision is replayed. Answers with the card as it stands.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The approval's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
decision- Approve it, or reject it.One of
approve,reject reason- Why you rejected it, up to 1000 characters; the Agent reads it.
Response
canApprove- You can approve it: the same as
canDecide. canDecide- You may approve or reject it now: you hold
capabilityand may use the Agent. Checked again when you decide and when it runs. capability- What approving or rejecting it needs, as a capability ID (
ads:publish). The person who asked doesn't hold it. createdAt- Proposed.
decidedAt- Decided.
decidedBy- Who approved or rejected it; null while it waits, or once it was taken back.
decidedBy.id- Person.
decidedBy.name- Their name now; null once their account is gone.
effecteffect.done- The same once it ran.
effect.entities- What it changes.
effect.entities[].id- ID.
effect.entities[].kind- Kind.One of
launch,adSet,ad effect.entities[].launchId- Its launch.
effect.entities[].name- Name.
effect.lines- Human details, never field names or IDs.
effect.lines[].label- A human label.
effect.lines[].value- Its value.
effect.money- Amounts it spends or sets.
effect.money[].amount- A decimal amount; never a float.
effect.money[].currency- ISO 4217; null when the account's currency isn't known.
effect.money[].label- Label.
effect.subject- What it acts on, one quiet line under the title; absent for most actions.
effect.summary- What it does, in a sentence; empty when that would only repeat
title. effect.title- The action as one sentence with real names, never IDs.
effect.warnings- Things to know before approving.
error- Why it failed, or the reason it was rejected.
error.code- Stable code.
error.message- For the person.
error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. expiresAt- Until when approving it runs it (a day after it was proposed); rejecting still clears it after.
id- Approval.
permission- The coarse permission the call asked with. What deciding needs is
capability.One ofread,review,write,publish,admin,organization proposedBy- Who asked: the person the Agent proposed it for.
proposedBy.id- Person.
proposedBy.name- Their name now; null once their account is gone.
result- After approving.
result.jobId- The job it started.
result.summary- What happened.
status- State.
superseded: the person who asked took it back.One ofpending,approved,rejected,failed,superseded title- What it does, as one sentence with real names and never IDs. The same as
effect.title. tool- The MCP tool it runs.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/agent/approvals/1fa0aef8-e184-47c2-9e38-d15e5b1cb1c3/decision" \
-b "plutoads_session=$PLUTO_SESSION" \
-H "Idempotency-Key: b6923828-8894-45b2-82a0-5ed552c00ded" \
-H "Content-Type: application/json" \
-d '{
"decision": "approve",
"reason": "Spend is pacing ahead of plan; hold the budget until Friday."
}'Decline a proposed action
The Agent is told you declined (with your reason) and continues. Only a person can decline (API keys and agents get 403): the person the Agent proposed it for, or an organization owner or admin, declines it (403 otherwise). Answers with the stream.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The approval's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
reason- Up to 1000 characters; the Agent reads it.
Response
approvalapproval.canApprove- The viewer can approve it: the same as
canDecide. approval.canDecide- The viewer may approve or decline it: they hold
capability, and it's theirs to decide (the person the Agent proposed it for, or an organization owner or admin). approval.capability- What approving or declining it needs, as a capability ID (
ads:publish): the capability of the tool it runs, or of what its call asked for beyond it (a copy made at the platform). Someone without it never decides it, the person who asked included. approval.chatId- Chat.
approval.createdAt- Proposed.
approval.decidedAt- Decided.
approval.effectapproval.effect.done- The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approval.effect.entities- What it changes.
approval.effect.entities[].id- ID.
approval.effect.entities[].kind- Kind.One of
launch,adSet,ad approval.effect.entities[].launchId- Its launch.
approval.effect.entities[].name- Name.
approval.effect.lines- Human details, never field names or IDs.
approval.effect.lines[].label- A human label, e.g. Trigger.
approval.effect.lines[].value- Its value, e.g. New comment.
approval.effect.money- Amounts it spends or sets.
approval.effect.money[].amount- A decimal amount; never a float.
approval.effect.money[].currency- ISO 4217; null when the account's currency isn't known.
approval.effect.money[].label- Label.
approval.effect.subject- What it acts on, one quiet line to show under the title without expanding; absent for most actions. A comment action names the comment: v.i.u.m: “Does this work for small teams?” on App review test.
approval.effect.summary- What it does, in a sentence; empty when that would only repeat
title. approval.effect.title- The action as one sentence with real names, never IDs: Delete loop “Facebook comment moderator”. A tool without its own sentence reads as its title.
approval.effect.warnings- Things to know before approving.
approval.error- Why it failed, or the reason it was declined.
approval.error.code- Stable code.
approval.error.message- For the person.
approval.error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. approval.id- Approval.
approval.messageId- The answer that proposed it.
approval.permission- The coarse permission the call asked with: the action's own (
read,revieworwriteonly when the person chose Ask every time). What deciding needs iscapability.One ofread,review,write,publish,admin,organization approval.result- After approving.
approval.result.jobId- The job it started.
approval.result.summary- What happened.
approval.status- State.One of
pending,approved,rejected,failed,superseded approval.title- What it does, as one sentence with real names and never IDs, e.g. Delete loop “Facebook comment moderator”. The same as
effect.title. approval.tool- The MCP tool it runs.
chatchat.createdAt- Started.
chat.effort- The reasoning effort picked for the chat; null: the model's default.
chat.id- Chat.
chat.lastMessageAt- Last message.
chat.loopId- The loop it is the history of (it made the loop, or was started in its builder).
chat.model- The chat's model:
pluto,autoor a model ID fromGET /agent/models. chat.ownerId- The chat's person: only they rename, delete or share it.
chat.shared- Shared with everyone who can see its loop; false: private to its person.
chat.source- Where it started.One of
page,panel,home,loop chat.status- What it's doing.One of
idle,running,awaiting_approval chat.title- Title; null until the first answer names it.
chat.unread- An answer arrived after the person last read it.
chat.updatedAt- Last change.
codeerror: spend_limit, payment_required, model_unavailable, rate_limited, refusal, max_tokens, step_limit or internal.delta- Text to append.
messagemessage.approvalIds- Approvals raised in this answer.
message.attachments- Files the person attached.
message.attachments[].contentType- A chat file's type.
message.attachments[].fileId- A chat file, uploaded for the message.
message.attachments[].kind- Kind (a media library item is an
imageor avideo).One ofimage,video,pdf,document,spreadsheet,presentation,text,code,audio,archive message.attachments[].mediaId- A media library item.
message.attachments[].name- File name.
message.attachments[].pageCount- Pages of a PDF, Word document or presentation.
message.attachments[].previewUrl- A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
message.attachments[].sizeBytes- A chat file's size.
message.chatId- Chat.
message.completedAt- Finished.
message.createdAt- Written.
message.error- Why the answer failed.
message.error.code- Stable code.
message.error.message- For the person.
message.error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. message.id- Message.
message.model- The model that produced the answer; null for the person's messages.
message.parts- The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
message.parts[].answerquestion: the answer once given (a choice's label, or the words of your reply).message.parts[].choiceIdquestion: the choice it was answered with.message.parts[].choicesquestion: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).message.parts[].columnstable: its columns.message.parts[].data- Every kind but
comboandtable: the series. message.parts[].description- One line under the title: the period, the unit.
message.parts[].groupscombo: its groups.message.parts[].id- The part; the same ID again replaces it.
message.parts[].itemsads: the ads, in the order shown.message.parts[].kind- How it's drawn;
tableis a table.One ofline,bar,horizontal-bar,stacked-bar,stacked-area,donut,funnel,combo,simple-bar,simple-normalized,spark-line,spark-bar,table message.parts[].optionsselection: the options (POST /agent/chats/{id}/parts/{part_id}/select).message.parts[].periodads: the days of itsmetrics:since,untilandpreset(last_30_days, …, or null).message.parts[].proposedselection: the options the Agent recommends, checked at first.message.parts[].rowstable: its rows.message.parts[].selectedselection: the options you confirmed.message.parts[].showLegend- Whether a legend shows; absent: for two or more series.
message.parts[].sizesimple-normalizedonly.One ofsmall,medium,largemessage.parts[].textquestion: the question.text: the words (Markdown).message.parts[].title- What it shows.
message.parts[].type- A chart or a table, a question the Agent asks, options it proposes, ads it shows as cards, or the answer's words written before the card that follows them.One of
chart,question,selection,ads,text message.parts[].valueFormat- How values read:
style(decimal,percentwith values as percentages,currencywithcurrency),notation,minimumFractionDigits,maximumFractionDigits,unit. message.parts[].xAxislabel,hide.message.parts[].yAxislabel,integersOnly.message.role- Who wrote it.One of
user,assistant message.sentBy- Who sent a person's message (only they edit it); null for answers and for older messages, which are the chat's person's.
message.sources- The web pages the answer used: cited pages in the order first cited, then pages it read without citing; each URL once. Empty when it didn't use the web.
message.sources[].site- The hostname without
www.. message.sources[].title- Its title (its site when it named none).
message.sources[].url- The page.
message.status- State:
waitingfor credits;awaiting_userwhen the answer asked a question or proposed a selection (parts) and waits for your reply.One ofcomplete,streaming,stopped,failed,awaiting_approval,waiting,awaiting_user message.steps- What the Agent did, in order.
message.steps[].category- What kind of call it is, for a summary like "Created 2 launches, ran a search": from what the tool does (adds, changes, reads, lists, searches),
mcpfor another Pluto product (server). Absent for narration and thinking, and on older steps.One ofwrite,edit,read,list,search,mcp,other message.steps[].detail- Error, reasoning or narration text; a search's query; a read page's URL.
message.steps[].entities- What it touched.
message.steps[].entities[].id- ID.
message.steps[].entities[].kind- Kind.One of
launch,adSet,ad message.steps[].entities[].launchId- Its launch.
message.steps[].entities[].name- Name.
message.steps[].finishedAt- Finished.
message.steps[].id- Step.
message.steps[].kind- A tool call, narration before tools, summarized reasoning, a web search (
detailis the query) or a web page read (detailis its URL).One oftool,note,thinking,search,fetch message.steps[].label- Present tense while running, past tense when done.
message.steps[].server- The Pluto product an
mcpstep used, e.g.Pluto Profit. message.steps[].startedAt- Started.
message.steps[].status- State.One of
running,done,failed,awaiting_approval,rejected,stopped message.steps[].tool- The MCP tool; null for every kind but
tool. message.text- The question, or the answer (markdown;
pluto:links name launches, ad sets and ads). message.version- Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
message.versions- How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
message.workedMs- Active time, excluding waits for approval.
messageId- The Agent message a delta belongs to.
partpart.answerquestion: the answer once given (a choice's label, or the words of your reply).part.choiceIdquestion: the choice it was answered with.part.choicesquestion: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).part.columnstable: its columns.part.data- Every kind but
comboandtable: the series. part.description- One line under the title: the period, the unit.
part.groupscombo: its groups.part.id- The part; the same ID again replaces it.
part.itemsads: the ads, in the order shown.part.kind- How it's drawn;
tableis a table.One ofline,bar,horizontal-bar,stacked-bar,stacked-area,donut,funnel,combo,simple-bar,simple-normalized,spark-line,spark-bar,table part.optionsselection: the options (POST /agent/chats/{id}/parts/{part_id}/select).part.periodads: the days of itsmetrics:since,untilandpreset(last_30_days, …, or null).part.proposedselection: the options the Agent recommends, checked at first.part.rowstable: its rows.part.selectedselection: the options you confirmed.part.showLegend- Whether a legend shows; absent: for two or more series.
part.sizesimple-normalizedonly.One ofsmall,medium,largepart.textquestion: the question.text: the words (Markdown).part.title- What it shows.
part.type- A chart or a table, a question the Agent asks, options it proposes, ads it shows as cards, or the answer's words written before the card that follows them.One of
chart,question,selection,ads,text part.valueFormat- How values read:
style(decimal,percentwith values as percentages,currencywithcurrency),notation,minimumFractionDigits,maximumFractionDigits,unit. part.xAxislabel,hide.part.yAxislabel,integersOnly.reasonerrorwith spend_limit: which limit stopped it (member_limit, workspace_limit or trial_cap); with payment_required: why there's no access.retryableerror: whether retrying can help.sourcessourcesevents: the answer's web pages so far.sources[].site- The hostname without
www.. sources[].title- Its title (its site when it named none).
sources[].url- The page.
stallstall: why the answer seems stuck, decided from the stream:no_first_byte(the model sent nothing for 10 s),silent_stream(an open stream sent no event for 15 s) orsilent_tool(a tool reported nothing for 45 s), andsince, when the silence began (epoch milliseconds);nullonce it moves again.stall.kind- What went quiet.One of
no_first_byte,silent_stream,silent_tool stall.since- When the silence began, epoch milliseconds.
stepstep.category- What kind of call it is, for a summary like "Created 2 launches, ran a search": from what the tool does (adds, changes, reads, lists, searches),
mcpfor another Pluto product (server). Absent for narration and thinking, and on older steps.One ofwrite,edit,read,list,search,mcp,other step.detail- Error, reasoning or narration text; a search's query; a read page's URL.
step.entities- What it touched.
step.entities[].id- ID.
step.entities[].kind- Kind.One of
launch,adSet,ad step.entities[].launchId- Its launch.
step.entities[].name- Name.
step.finishedAt- Finished.
step.id- Step.
step.kind- A tool call, narration before tools, summarized reasoning, a web search (
detailis the query) or a web page read (detailis its URL).One oftool,note,thinking,search,fetch step.label- Present tense while running, past tense when done.
step.server- The Pluto product an
mcpstep used, e.g.Pluto Profit. step.startedAt- Started.
step.status- State.One of
running,done,failed,awaiting_approval,rejected,stopped step.tool- The MCP tool; null for every kind but
tool. stepId- The thinking step a delta belongs to.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/agent/approvals/1fa0aef8-e184-47c2-9e38-d15e5b1cb1c3/reject" \
-b "plutoads_session=$PLUTO_SESSION" \
-H "Idempotency-Key: be44b2f9-beb7-4d43-a777-890b487cef43" \
-H "Content-Type: application/json" \
-d '{
"reason": "Spend is pacing ahead of plan; hold the budget until Friday."
}'List shared chats
The signed-in person's shared chats in this workspace, the latest shared or updated first, each with its title.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- The person's shared chats.
items[].chatId- The chat.
items[].createdAt- First shared.
items[].id- The link.
items[].messages- Messages in the snapshot.
items[].newer- The chat has messages the link doesn't show yet.
items[].path- The app path it opens in the workspace (
/share/<token>). items[].title- The chat's title; null until the first answer names it.
items[].token- The link's own ID, separate from the chat's: the last part of its address.
items[].updatedAt- Shared or last updated: the snapshot holds the messages up to then.
items[].url- The link people open; null while the workspace has no address.
curl "$PLUTO_API/agent/chat-links" \
-H "Authorization: Bearer $PLUTO_KEY"List chats
Chats with at least one message, most recently updated first.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
after | string | Optional | Cursor: nextAfter of the previous page. |
limit | string | Optional | Page size (1-500). |
q | string | Optional | Filters titles (case-insensitive). |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- This page.
items[].createdAt- Started.
items[].effort- The reasoning effort picked for the chat; null: the model's default.
items[].id- Chat.
items[].lastMessageAt- Last message.
items[].loopId- The loop it is the history of (it made the loop, or was started in its builder).
items[].model- The chat's model:
pluto,autoor a model ID fromGET /agent/models. items[].ownerId- The chat's person: only they rename, delete or share it.
items[].shared- Shared with everyone who can see its loop; false: private to its person.
items[].source- Where it started.One of
page,panel,home,loop items[].status- What it's doing.One of
idle,running,awaiting_approval items[].title- Title; null until the first answer names it.
items[].unread- An answer arrived after the person last read it.
items[].updatedAt- Last change.
nextAfter- Cursor for the next page; null at the end.
curl "$PLUTO_API/agent/chats" \
-H "Authorization: Bearer $PLUTO_KEY"Start a chat
Private to the signed-in person, unless it's a loop's chat its person shared (then everyone who can see the loop reads it); API keys get 403 (a chat needs a person).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
effort- A reasoning effort the model accepts (
effortsinGET /agent/models); 422 oneffortotherwise.One oflow,medium,high,xhigh,max modelpluto,autoor a model ID fromGET /agent/models; when absent, the caller's last choice, else the first model in their picker. Refused (422 onmodel) when it can't run here or the workspace doesn't allow it.source- Where the chat started (
loop: a loop's builder; usePOST /loops/{id}/chatto attach it).One ofpage,panel,home,loop
Response
approvals- The approvals these messages carry.
approvals[].canApprove- The viewer can approve it: the same as
canDecide. approvals[].canDecide- The viewer may approve or decline it: they hold
capability, and it's theirs to decide (the person the Agent proposed it for, or an organization owner or admin). approvals[].capability- What approving or declining it needs, as a capability ID (
ads:publish): the capability of the tool it runs, or of what its call asked for beyond it (a copy made at the platform). Someone without it never decides it, the person who asked included. approvals[].chatId- Chat.
approvals[].createdAt- Proposed.
approvals[].decidedAt- Decided.
approvals[].effectapprovals[].effect.done- The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approvals[].effect.entities- What it changes.
approvals[].effect.entities[].id- ID.
approvals[].effect.entities[].kind- Kind.One of
launch,adSet,ad approvals[].effect.entities[].launchId- Its launch.
approvals[].effect.entities[].name- Name.
approvals[].effect.lines- Human details, never field names or IDs.
approvals[].effect.lines[].label- A human label, e.g. Trigger.
approvals[].effect.lines[].value- Its value, e.g. New comment.
approvals[].effect.money- Amounts it spends or sets.
approvals[].effect.money[].amount- A decimal amount; never a float.
approvals[].effect.money[].currency- ISO 4217; null when the account's currency isn't known.
approvals[].effect.money[].label- Label.
approvals[].effect.subject- What it acts on, one quiet line to show under the title without expanding; absent for most actions. A comment action names the comment: v.i.u.m: “Does this work for small teams?” on App review test.
approvals[].effect.summary- What it does, in a sentence; empty when that would only repeat
title. approvals[].effect.title- The action as one sentence with real names, never IDs: Delete loop “Facebook comment moderator”. A tool without its own sentence reads as its title.
approvals[].effect.warnings- Things to know before approving.
approvals[].error- Why it failed, or the reason it was declined.
approvals[].error.code- Stable code.
approvals[].error.message- For the person.
approvals[].error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. approvals[].id- Approval.
approvals[].messageId- The answer that proposed it.
approvals[].permission- The coarse permission the call asked with: the action's own (
read,revieworwriteonly when the person chose Ask every time). What deciding needs iscapability.One ofread,review,write,publish,admin,organization approvals[].result- After approving.
approvals[].result.jobId- The job it started.
approvals[].result.summary- What happened.
approvals[].status- State.One of
pending,approved,rejected,failed,superseded approvals[].title- What it does, as one sentence with real names and never IDs, e.g. Delete loop “Facebook comment moderator”. The same as
effect.title. approvals[].tool- The MCP tool it runs.
createdAt- Started.
effort- The reasoning effort picked for the chat; null: the model's default.
hasEarlier- Older messages exist:
?before=<first message id>. id- Chat.
lastMessageAt- Last message.
loopId- The loop it is the history of (it made the loop, or was started in its builder).
messages- The newest page (100 by default), oldest first.
messages[].approvalIds- Approvals raised in this answer.
messages[].attachments- Files the person attached.
messages[].attachments[].contentType- A chat file's type.
messages[].attachments[].fileId- A chat file, uploaded for the message.
messages[].attachments[].kind- Kind (a media library item is an
imageor avideo).One ofimage,video,pdf,document,spreadsheet,presentation,text,code,audio,archive messages[].attachments[].mediaId- A media library item.
messages[].attachments[].name- File name.
messages[].attachments[].pageCount- Pages of a PDF, Word document or presentation.
messages[].attachments[].previewUrl- A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
messages[].attachments[].sizeBytes- A chat file's size.
messages[].chatId- Chat.
messages[].completedAt- Finished.
messages[].createdAt- Written.
messages[].error- Why the answer failed.
messages[].error.code- Stable code.
messages[].error.message- For the person.
messages[].error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. messages[].id- Message.
messages[].model- The model that produced the answer; null for the person's messages.
messages[].parts- The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
messages[].parts[].answerquestion: the answer once given (a choice's label, or the words of your reply).messages[].parts[].choiceIdquestion: the choice it was answered with.messages[].parts[].choicesquestion: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).messages[].parts[].columnstable: its columns.messages[].parts[].data- Every kind but
comboandtable: the series. messages[].parts[].description- One line under the title: the period, the unit.
messages[].parts[].groupscombo: its groups.messages[].parts[].id- The part; the same ID again replaces it.
messages[].parts[].itemsads: the ads, in the order shown.messages[].parts[].kind- How it's drawn;
tableis a table.One ofline,bar,horizontal-bar,stacked-bar,stacked-area,donut,funnel,combo,simple-bar,simple-normalized,spark-line,spark-bar,table messages[].parts[].optionsselection: the options (POST /agent/chats/{id}/parts/{part_id}/select).messages[].parts[].periodads: the days of itsmetrics:since,untilandpreset(last_30_days, …, or null).messages[].parts[].proposedselection: the options the Agent recommends, checked at first.messages[].parts[].rowstable: its rows.messages[].parts[].selectedselection: the options you confirmed.messages[].parts[].showLegend- Whether a legend shows; absent: for two or more series.
messages[].parts[].sizesimple-normalizedonly.One ofsmall,medium,largemessages[].parts[].textquestion: the question.text: the words (Markdown).messages[].parts[].title- What it shows.
messages[].parts[].type- A chart or a table, a question the Agent asks, options it proposes, ads it shows as cards, or the answer's words written before the card that follows them.One of
chart,question,selection,ads,text messages[].parts[].valueFormat- How values read:
style(decimal,percentwith values as percentages,currencywithcurrency),notation,minimumFractionDigits,maximumFractionDigits,unit. messages[].parts[].xAxislabel,hide.messages[].parts[].yAxislabel,integersOnly.messages[].role- Who wrote it.One of
user,assistant messages[].sentBy- Who sent a person's message (only they edit it); null for answers and for older messages, which are the chat's person's.
messages[].sources- The web pages the answer used: cited pages in the order first cited, then pages it read without citing; each URL once. Empty when it didn't use the web.
messages[].sources[].site- The hostname without
www.. messages[].sources[].title- Its title (its site when it named none).
messages[].sources[].url- The page.
messages[].status- State:
waitingfor credits;awaiting_userwhen the answer asked a question or proposed a selection (parts) and waits for your reply.One ofcomplete,streaming,stopped,failed,awaiting_approval,waiting,awaiting_user messages[].steps- What the Agent did, in order.
messages[].steps[].category- What kind of call it is, for a summary like "Created 2 launches, ran a search": from what the tool does (adds, changes, reads, lists, searches),
mcpfor another Pluto product (server). Absent for narration and thinking, and on older steps.One ofwrite,edit,read,list,search,mcp,other messages[].steps[].detail- Error, reasoning or narration text; a search's query; a read page's URL.
messages[].steps[].entities- What it touched.
messages[].steps[].entities[].id- ID.
messages[].steps[].entities[].kind- Kind.One of
launch,adSet,ad messages[].steps[].entities[].launchId- Its launch.
messages[].steps[].entities[].name- Name.
messages[].steps[].finishedAt- Finished.
messages[].steps[].id- Step.
messages[].steps[].kind- A tool call, narration before tools, summarized reasoning, a web search (
detailis the query) or a web page read (detailis its URL).One oftool,note,thinking,search,fetch messages[].steps[].label- Present tense while running, past tense when done.
messages[].steps[].server- The Pluto product an
mcpstep used, e.g.Pluto Profit. messages[].steps[].startedAt- Started.
messages[].steps[].status- State.One of
running,done,failed,awaiting_approval,rejected,stopped messages[].steps[].tool- The MCP tool; null for every kind but
tool. messages[].text- The question, or the answer (markdown;
pluto:links name launches, ad sets and ads). messages[].version- Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
messages[].versions- How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
messages[].workedMs- Active time, excluding waits for approval.
model- The chat's model:
pluto,autoor a model ID fromGET /agent/models. ownerId- The chat's person: only they rename, delete or share it.
shared- Shared with everyone who can see its loop; false: private to its person.
source- Where it started.One of
page,panel,home,loop status- What it's doing.One of
idle,running,awaiting_approval title- Title; null until the first answer names it.
unread- An answer arrived after the person last read it.
updatedAt- Last change.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/agent/chats" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 540f8b6d-459e-4b80-aaa4-3b60ac703e85" \
-H "Content-Type: application/json" \
-d '{
"effort": "low",
"model": "pluto",
"source": "page"
}'Get a chat
A chat with its messages and approvals.
The newest messages (100 by default) with the approvals they carry, oldest first. hasEarlier says older messages exist: pass the first message's id as before for the page before it.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The chat's ID. |
before | string | Optional | A message ID: the messages before it. |
limit | string | Optional | 1-200; 100 by default. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
approvals- The approvals these messages carry.
approvals[].canApprove- The viewer can approve it: the same as
canDecide. approvals[].canDecide- The viewer may approve or decline it: they hold
capability, and it's theirs to decide (the person the Agent proposed it for, or an organization owner or admin). approvals[].capability- What approving or declining it needs, as a capability ID (
ads:publish): the capability of the tool it runs, or of what its call asked for beyond it (a copy made at the platform). Someone without it never decides it, the person who asked included. approvals[].chatId- Chat.
approvals[].createdAt- Proposed.
approvals[].decidedAt- Decided.
approvals[].effectapprovals[].effect.done- The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approvals[].effect.entities- What it changes.
approvals[].effect.entities[].id- ID.
approvals[].effect.entities[].kind- Kind.One of
launch,adSet,ad approvals[].effect.entities[].launchId- Its launch.
approvals[].effect.entities[].name- Name.
approvals[].effect.lines- Human details, never field names or IDs.
approvals[].effect.lines[].label- A human label, e.g. Trigger.
approvals[].effect.lines[].value- Its value, e.g. New comment.
approvals[].effect.money- Amounts it spends or sets.
approvals[].effect.money[].amount- A decimal amount; never a float.
approvals[].effect.money[].currency- ISO 4217; null when the account's currency isn't known.
approvals[].effect.money[].label- Label.
approvals[].effect.subject- What it acts on, one quiet line to show under the title without expanding; absent for most actions. A comment action names the comment: v.i.u.m: “Does this work for small teams?” on App review test.
approvals[].effect.summary- What it does, in a sentence; empty when that would only repeat
title. approvals[].effect.title- The action as one sentence with real names, never IDs: Delete loop “Facebook comment moderator”. A tool without its own sentence reads as its title.
approvals[].effect.warnings- Things to know before approving.
approvals[].error- Why it failed, or the reason it was declined.
approvals[].error.code- Stable code.
approvals[].error.message- For the person.
approvals[].error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. approvals[].id- Approval.
approvals[].messageId- The answer that proposed it.
approvals[].permission- The coarse permission the call asked with: the action's own (
read,revieworwriteonly when the person chose Ask every time). What deciding needs iscapability.One ofread,review,write,publish,admin,organization approvals[].result- After approving.
approvals[].result.jobId- The job it started.
approvals[].result.summary- What happened.
approvals[].status- State.One of
pending,approved,rejected,failed,superseded approvals[].title- What it does, as one sentence with real names and never IDs, e.g. Delete loop “Facebook comment moderator”. The same as
effect.title. approvals[].tool- The MCP tool it runs.
createdAt- Started.
effort- The reasoning effort picked for the chat; null: the model's default.
hasEarlier- Older messages exist:
?before=<first message id>. id- Chat.
lastMessageAt- Last message.
loopId- The loop it is the history of (it made the loop, or was started in its builder).
messages- The newest page (100 by default), oldest first.
messages[].approvalIds- Approvals raised in this answer.
messages[].attachments- Files the person attached.
messages[].attachments[].contentType- A chat file's type.
messages[].attachments[].fileId- A chat file, uploaded for the message.
messages[].attachments[].kind- Kind (a media library item is an
imageor avideo).One ofimage,video,pdf,document,spreadsheet,presentation,text,code,audio,archive messages[].attachments[].mediaId- A media library item.
messages[].attachments[].name- File name.
messages[].attachments[].pageCount- Pages of a PDF, Word document or presentation.
messages[].attachments[].previewUrl- A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
messages[].attachments[].sizeBytes- A chat file's size.
messages[].chatId- Chat.
messages[].completedAt- Finished.
messages[].createdAt- Written.
messages[].error- Why the answer failed.
messages[].error.code- Stable code.
messages[].error.message- For the person.
messages[].error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. messages[].id- Message.
messages[].model- The model that produced the answer; null for the person's messages.
messages[].parts- The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
messages[].parts[].answerquestion: the answer once given (a choice's label, or the words of your reply).messages[].parts[].choiceIdquestion: the choice it was answered with.messages[].parts[].choicesquestion: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).messages[].parts[].columnstable: its columns.messages[].parts[].data- Every kind but
comboandtable: the series. messages[].parts[].description- One line under the title: the period, the unit.
messages[].parts[].groupscombo: its groups.messages[].parts[].id- The part; the same ID again replaces it.
messages[].parts[].itemsads: the ads, in the order shown.messages[].parts[].kind- How it's drawn;
tableis a table.One ofline,bar,horizontal-bar,stacked-bar,stacked-area,donut,funnel,combo,simple-bar,simple-normalized,spark-line,spark-bar,table messages[].parts[].optionsselection: the options (POST /agent/chats/{id}/parts/{part_id}/select).messages[].parts[].periodads: the days of itsmetrics:since,untilandpreset(last_30_days, …, or null).messages[].parts[].proposedselection: the options the Agent recommends, checked at first.messages[].parts[].rowstable: its rows.messages[].parts[].selectedselection: the options you confirmed.messages[].parts[].showLegend- Whether a legend shows; absent: for two or more series.
messages[].parts[].sizesimple-normalizedonly.One ofsmall,medium,largemessages[].parts[].textquestion: the question.text: the words (Markdown).messages[].parts[].title- What it shows.
messages[].parts[].type- A chart or a table, a question the Agent asks, options it proposes, ads it shows as cards, or the answer's words written before the card that follows them.One of
chart,question,selection,ads,text messages[].parts[].valueFormat- How values read:
style(decimal,percentwith values as percentages,currencywithcurrency),notation,minimumFractionDigits,maximumFractionDigits,unit. messages[].parts[].xAxislabel,hide.messages[].parts[].yAxislabel,integersOnly.messages[].role- Who wrote it.One of
user,assistant messages[].sentBy- Who sent a person's message (only they edit it); null for answers and for older messages, which are the chat's person's.
messages[].sources- The web pages the answer used: cited pages in the order first cited, then pages it read without citing; each URL once. Empty when it didn't use the web.
messages[].sources[].site- The hostname without
www.. messages[].sources[].title- Its title (its site when it named none).
messages[].sources[].url- The page.
messages[].status- State:
waitingfor credits;awaiting_userwhen the answer asked a question or proposed a selection (parts) and waits for your reply.One ofcomplete,streaming,stopped,failed,awaiting_approval,waiting,awaiting_user messages[].steps- What the Agent did, in order.
messages[].steps[].category- What kind of call it is, for a summary like "Created 2 launches, ran a search": from what the tool does (adds, changes, reads, lists, searches),
mcpfor another Pluto product (server). Absent for narration and thinking, and on older steps.One ofwrite,edit,read,list,search,mcp,other messages[].steps[].detail- Error, reasoning or narration text; a search's query; a read page's URL.
messages[].steps[].entities- What it touched.
messages[].steps[].entities[].id- ID.
messages[].steps[].entities[].kind- Kind.One of
launch,adSet,ad messages[].steps[].entities[].launchId- Its launch.
messages[].steps[].entities[].name- Name.
messages[].steps[].finishedAt- Finished.
messages[].steps[].id- Step.
messages[].steps[].kind- A tool call, narration before tools, summarized reasoning, a web search (
detailis the query) or a web page read (detailis its URL).One oftool,note,thinking,search,fetch messages[].steps[].label- Present tense while running, past tense when done.
messages[].steps[].server- The Pluto product an
mcpstep used, e.g.Pluto Profit. messages[].steps[].startedAt- Started.
messages[].steps[].status- State.One of
running,done,failed,awaiting_approval,rejected,stopped messages[].steps[].tool- The MCP tool; null for every kind but
tool. messages[].text- The question, or the answer (markdown;
pluto:links name launches, ad sets and ads). messages[].version- Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
messages[].versions- How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
messages[].workedMs- Active time, excluding waits for approval.
model- The chat's model:
pluto,autoor a model ID fromGET /agent/models. ownerId- The chat's person: only they rename, delete or share it.
shared- Shared with everyone who can see its loop; false: private to its person.
source- Where it started.One of
page,panel,home,loop status- What it's doing.One of
idle,running,awaiting_approval title- Title; null until the first answer names it.
unread- An answer arrived after the person last read it.
updatedAt- Last change.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/agent/chats/26926918-2839-4fc9-87f3-3707d4b8e0d7" \
-H "Authorization: Bearer $PLUTO_KEY"Rename or share a chat
Only the chat's person; anyone else gets 404. Give title, shared or both. shared is only for a chat linked to a loop (loopId), else 422: true shares it with everyone who can see the loop, false keeps it to its person again.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The chat's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
shared- Share a loop's chat with the people who can see the loop (true) or stop sharing it (false).
title- 1-120 characters.
Response
createdAt- Started.
effort- The reasoning effort picked for the chat; null: the model's default.
id- Chat.
lastMessageAt- Last message.
loopId- The loop it is the history of (it made the loop, or was started in its builder).
model- The chat's model:
pluto,autoor a model ID fromGET /agent/models. ownerId- The chat's person: only they rename, delete or share it.
shared- Shared with everyone who can see its loop; false: private to its person.
source- Where it started.One of
page,panel,home,loop status- What it's doing.One of
idle,running,awaiting_approval title- Title; null until the first answer names it.
unread- An answer arrived after the person last read it.
updatedAt- Last change.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/agent/chats/26926918-2839-4fc9-87f3-3707d4b8e0d7" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 5feec0ee-dc7a-44f8-9c19-b799f85bb3b9" \
-H "Content-Type: application/json" \
-d '{
"shared": true,
"title": "Vitamin C Serum, UGC 9x16"
}'Delete a chat
Stops a running answer first; the chat's messages and approvals are deleted.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The chat's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
Done; no content.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/agent/chats/26926918-2839-4fc9-87f3-3707d4b8e0d7" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: d62f2efa-7e9d-469b-8544-40e912421b89"List your ratings in a chat
Your thumbs up and down on the Agent's answers in this chat (your own chat, or a loop's shared chat you can read). Not for guests.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The chat's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
itemsitems[].comment- Kept only while the organization has "Help improve Pluto's AI" on; null otherwise.
items[].messageId- The rated answer.
items[].rating- Thumbs up or down.One of
up,down items[].reason- Why it was rated down; null for a thumbs up or without a reason.One of
wrong_answer,ignored_request,wrong_changes,too_slow,other items[].updatedAt- When it was last rated.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/agent/chats/26926918-2839-4fc9-87f3-3707d4b8e0d7/feedback" \
-H "Authorization: Bearer $PLUTO_KEY"Get a chat's link
Share chat: the chat's link (link), or null while it isn't shared. Only the chat's person; anyone else gets 404. newer says the chat has messages the link doesn't show yet.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The chat's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
link- The link, or null.
link.chatId- The chat.
link.createdAt- First shared.
link.id- The link.
link.messages- Messages in the snapshot.
link.newer- The chat has messages the link doesn't show yet.
link.path- The app path it opens in the workspace (
/share/<token>). link.token- The link's own ID, separate from the chat's: the last part of its address.
link.updatedAt- Shared or last updated: the snapshot holds the messages up to then.
link.url- The link people open; null while the workspace has no address.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/agent/chats/26926918-2839-4fc9-87f3-3707d4b8e0d7/link" \
-H "Authorization: Bearer $PLUTO_KEY"Share a chat
Shares the chat with the members of this workspace through a link, or updates its link to the chat as it reads now (the token stays). The link shows a snapshot, the messages up to now, read only; later messages stay private until it's updated. Only signed-in members of the workspace who use the Agent can open it; it is never public. Only the chat's person (404 otherwise); 422 for a chat with no message yet.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The chat's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
chatId- The chat.
createdAt- First shared.
id- The link.
messages- Messages in the snapshot.
newer- The chat has messages the link doesn't show yet.
path- The app path it opens in the workspace (
/share/<token>). token- The link's own ID, separate from the chat's: the last part of its address.
updatedAt- Shared or last updated: the snapshot holds the messages up to then.
url- The link people open; null while the workspace has no address.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PUT "$PLUTO_API/agent/chats/26926918-2839-4fc9-87f3-3707d4b8e0d7/link" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 5b4ce93f-3478-4318-a774-2915f866c012"Turn off a chat's link
Turns the chat's link off: it stops working for everyone at once (sharing again makes a new link). Only the chat's person; a chat that isn't shared answers 204 too.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The chat's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
Done; no content.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/agent/chats/26926918-2839-4fc9-87f3-3707d4b8e0d7/link" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: bccc5476-35ad-4e18-86fb-11ceca8059bf"Ask the Agent
Answers with server-sent events: chat, message, text (answer delta), answerReset, thinking, step, sources (the web pages the answer used so far: the whole list, replacing the last one), part (a chart, table, question or selection the answer shows: messageId and the part; the same id replaces it), approval, stall (the answer seems stuck: messageId and stall, { kind, since } or null once it moves again; never stored), error and a final done; each event's data is JSON. Closing the stream doesn't stop the answer (use /stop). Before each model call the organization's, workspace's and member's usage limits and paid access are checked: over a limit the answer is a 402 spend_limit whose reason names it (member_limit, workspace_limit or trial_cap); without access a 402 payment_required. A limit reached mid-answer ends it with an error event of that code and reason. Used credits (credits_used) are never a refusal: the answer waits (message status waiting, its error.reason credits_used) and starts by itself once credits arrive.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The chat's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
contextcontext.adId- The open ad.
context.fileIds- Chat files attached to the question (
POST /workspaces/{id}/chat-files), eachready:409while one is still being prepared,422for one that failed or isn't yours. Up to 20 files in all, withmediaIds. context.launchId- The open launch.
context.loopId- The loop open in the builder: the Agent reads its current definition.
context.mediaIds- Media library items attached to the question.
context.path- The app page the person is on.
context.selectedStepIds- Steps selected on the builder's canvas (up to 50): what "this step" means.
effort- A reasoning effort the model accepts (
effortsinGET /agent/models); 422 oneffortotherwise.One oflow,medium,high,xhigh,max modelpluto,autoor a model ID fromGET /agent/models: the chat runs on it from here on. Refused (422 onmodel) when it can't run here or the workspace doesn't allow it.text- 1-16000 characters.
Response
approvalapproval.canApprove- The viewer can approve it: the same as
canDecide. approval.canDecide- The viewer may approve or decline it: they hold
capability, and it's theirs to decide (the person the Agent proposed it for, or an organization owner or admin). approval.capability- What approving or declining it needs, as a capability ID (
ads:publish): the capability of the tool it runs, or of what its call asked for beyond it (a copy made at the platform). Someone without it never decides it, the person who asked included. approval.chatId- Chat.
approval.createdAt- Proposed.
approval.decidedAt- Decided.
approval.effectapproval.effect.done- The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approval.effect.entities- What it changes.
approval.effect.entities[].id- ID.
approval.effect.entities[].kind- Kind.One of
launch,adSet,ad approval.effect.entities[].launchId- Its launch.
approval.effect.entities[].name- Name.
approval.effect.lines- Human details, never field names or IDs.
approval.effect.lines[].label- A human label, e.g. Trigger.
approval.effect.lines[].value- Its value, e.g. New comment.
approval.effect.money- Amounts it spends or sets.
approval.effect.money[].amount- A decimal amount; never a float.
approval.effect.money[].currency- ISO 4217; null when the account's currency isn't known.
approval.effect.money[].label- Label.
approval.effect.subject- What it acts on, one quiet line to show under the title without expanding; absent for most actions. A comment action names the comment: v.i.u.m: “Does this work for small teams?” on App review test.
approval.effect.summary- What it does, in a sentence; empty when that would only repeat
title. approval.effect.title- The action as one sentence with real names, never IDs: Delete loop “Facebook comment moderator”. A tool without its own sentence reads as its title.
approval.effect.warnings- Things to know before approving.
approval.error- Why it failed, or the reason it was declined.
approval.error.code- Stable code.
approval.error.message- For the person.
approval.error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. approval.id- Approval.
approval.messageId- The answer that proposed it.
approval.permission- The coarse permission the call asked with: the action's own (
read,revieworwriteonly when the person chose Ask every time). What deciding needs iscapability.One ofread,review,write,publish,admin,organization approval.result- After approving.
approval.result.jobId- The job it started.
approval.result.summary- What happened.
approval.status- State.One of
pending,approved,rejected,failed,superseded approval.title- What it does, as one sentence with real names and never IDs, e.g. Delete loop “Facebook comment moderator”. The same as
effect.title. approval.tool- The MCP tool it runs.
chatchat.createdAt- Started.
chat.effort- The reasoning effort picked for the chat; null: the model's default.
chat.id- Chat.
chat.lastMessageAt- Last message.
chat.loopId- The loop it is the history of (it made the loop, or was started in its builder).
chat.model- The chat's model:
pluto,autoor a model ID fromGET /agent/models. chat.ownerId- The chat's person: only they rename, delete or share it.
chat.shared- Shared with everyone who can see its loop; false: private to its person.
chat.source- Where it started.One of
page,panel,home,loop chat.status- What it's doing.One of
idle,running,awaiting_approval chat.title- Title; null until the first answer names it.
chat.unread- An answer arrived after the person last read it.
chat.updatedAt- Last change.
codeerror: spend_limit, payment_required, model_unavailable, rate_limited, refusal, max_tokens, step_limit or internal.delta- Text to append.
messagemessage.approvalIds- Approvals raised in this answer.
message.attachments- Files the person attached.
message.attachments[].contentType- A chat file's type.
message.attachments[].fileId- A chat file, uploaded for the message.
message.attachments[].kind- Kind (a media library item is an
imageor avideo).One ofimage,video,pdf,document,spreadsheet,presentation,text,code,audio,archive message.attachments[].mediaId- A media library item.
message.attachments[].name- File name.
message.attachments[].pageCount- Pages of a PDF, Word document or presentation.
message.attachments[].previewUrl- A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
message.attachments[].sizeBytes- A chat file's size.
message.chatId- Chat.
message.completedAt- Finished.
message.createdAt- Written.
message.error- Why the answer failed.
message.error.code- Stable code.
message.error.message- For the person.
message.error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. message.id- Message.
message.model- The model that produced the answer; null for the person's messages.
message.parts- The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
message.parts[].answerquestion: the answer once given (a choice's label, or the words of your reply).message.parts[].choiceIdquestion: the choice it was answered with.message.parts[].choicesquestion: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).message.parts[].columnstable: its columns.message.parts[].data- Every kind but
comboandtable: the series. message.parts[].description- One line under the title: the period, the unit.
message.parts[].groupscombo: its groups.message.parts[].id- The part; the same ID again replaces it.
message.parts[].itemsads: the ads, in the order shown.message.parts[].kind- How it's drawn;
tableis a table.One ofline,bar,horizontal-bar,stacked-bar,stacked-area,donut,funnel,combo,simple-bar,simple-normalized,spark-line,spark-bar,table message.parts[].optionsselection: the options (POST /agent/chats/{id}/parts/{part_id}/select).message.parts[].periodads: the days of itsmetrics:since,untilandpreset(last_30_days, …, or null).message.parts[].proposedselection: the options the Agent recommends, checked at first.message.parts[].rowstable: its rows.message.parts[].selectedselection: the options you confirmed.message.parts[].showLegend- Whether a legend shows; absent: for two or more series.
message.parts[].sizesimple-normalizedonly.One ofsmall,medium,largemessage.parts[].textquestion: the question.text: the words (Markdown).message.parts[].title- What it shows.
message.parts[].type- A chart or a table, a question the Agent asks, options it proposes, ads it shows as cards, or the answer's words written before the card that follows them.One of
chart,question,selection,ads,text message.parts[].valueFormat- How values read:
style(decimal,percentwith values as percentages,currencywithcurrency),notation,minimumFractionDigits,maximumFractionDigits,unit. message.parts[].xAxislabel,hide.message.parts[].yAxislabel,integersOnly.message.role- Who wrote it.One of
user,assistant message.sentBy- Who sent a person's message (only they edit it); null for answers and for older messages, which are the chat's person's.
message.sources- The web pages the answer used: cited pages in the order first cited, then pages it read without citing; each URL once. Empty when it didn't use the web.
message.sources[].site- The hostname without
www.. message.sources[].title- Its title (its site when it named none).
message.sources[].url- The page.
message.status- State:
waitingfor credits;awaiting_userwhen the answer asked a question or proposed a selection (parts) and waits for your reply.One ofcomplete,streaming,stopped,failed,awaiting_approval,waiting,awaiting_user message.steps- What the Agent did, in order.
message.steps[].category- What kind of call it is, for a summary like "Created 2 launches, ran a search": from what the tool does (adds, changes, reads, lists, searches),
mcpfor another Pluto product (server). Absent for narration and thinking, and on older steps.One ofwrite,edit,read,list,search,mcp,other message.steps[].detail- Error, reasoning or narration text; a search's query; a read page's URL.
message.steps[].entities- What it touched.
message.steps[].entities[].id- ID.
message.steps[].entities[].kind- Kind.One of
launch,adSet,ad message.steps[].entities[].launchId- Its launch.
message.steps[].entities[].name- Name.
message.steps[].finishedAt- Finished.
message.steps[].id- Step.
message.steps[].kind- A tool call, narration before tools, summarized reasoning, a web search (
detailis the query) or a web page read (detailis its URL).One oftool,note,thinking,search,fetch message.steps[].label- Present tense while running, past tense when done.
message.steps[].server- The Pluto product an
mcpstep used, e.g.Pluto Profit. message.steps[].startedAt- Started.
message.steps[].status- State.One of
running,done,failed,awaiting_approval,rejected,stopped message.steps[].tool- The MCP tool; null for every kind but
tool. message.text- The question, or the answer (markdown;
pluto:links name launches, ad sets and ads). message.version- Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
message.versions- How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
message.workedMs- Active time, excluding waits for approval.
messageId- The Agent message a delta belongs to.
partpart.answerquestion: the answer once given (a choice's label, or the words of your reply).part.choiceIdquestion: the choice it was answered with.part.choicesquestion: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).part.columnstable: its columns.part.data- Every kind but
comboandtable: the series. part.description- One line under the title: the period, the unit.
part.groupscombo: its groups.part.id- The part; the same ID again replaces it.
part.itemsads: the ads, in the order shown.part.kind- How it's drawn;
tableis a table.One ofline,bar,horizontal-bar,stacked-bar,stacked-area,donut,funnel,combo,simple-bar,simple-normalized,spark-line,spark-bar,table part.optionsselection: the options (POST /agent/chats/{id}/parts/{part_id}/select).part.periodads: the days of itsmetrics:since,untilandpreset(last_30_days, …, or null).part.proposedselection: the options the Agent recommends, checked at first.part.rowstable: its rows.part.selectedselection: the options you confirmed.part.showLegend- Whether a legend shows; absent: for two or more series.
part.sizesimple-normalizedonly.One ofsmall,medium,largepart.textquestion: the question.text: the words (Markdown).part.title- What it shows.
part.type- A chart or a table, a question the Agent asks, options it proposes, ads it shows as cards, or the answer's words written before the card that follows them.One of
chart,question,selection,ads,text part.valueFormat- How values read:
style(decimal,percentwith values as percentages,currencywithcurrency),notation,minimumFractionDigits,maximumFractionDigits,unit. part.xAxislabel,hide.part.yAxislabel,integersOnly.reasonerrorwith spend_limit: which limit stopped it (member_limit, workspace_limit or trial_cap); with payment_required: why there's no access.retryableerror: whether retrying can help.sourcessourcesevents: the answer's web pages so far.sources[].site- The hostname without
www.. sources[].title- Its title (its site when it named none).
sources[].url- The page.
stallstall: why the answer seems stuck, decided from the stream:no_first_byte(the model sent nothing for 10 s),silent_stream(an open stream sent no event for 15 s) orsilent_tool(a tool reported nothing for 45 s), andsince, when the silence began (epoch milliseconds);nullonce it moves again.stall.kind- What went quiet.One of
no_first_byte,silent_stream,silent_tool stall.since- When the silence began, epoch milliseconds.
stepstep.category- What kind of call it is, for a summary like "Created 2 launches, ran a search": from what the tool does (adds, changes, reads, lists, searches),
mcpfor another Pluto product (server). Absent for narration and thinking, and on older steps.One ofwrite,edit,read,list,search,mcp,other step.detail- Error, reasoning or narration text; a search's query; a read page's URL.
step.entities- What it touched.
step.entities[].id- ID.
step.entities[].kind- Kind.One of
launch,adSet,ad step.entities[].launchId- Its launch.
step.entities[].name- Name.
step.finishedAt- Finished.
step.id- Step.
step.kind- A tool call, narration before tools, summarized reasoning, a web search (
detailis the query) or a web page read (detailis its URL).One oftool,note,thinking,search,fetch step.label- Present tense while running, past tense when done.
step.server- The Pluto product an
mcpstep used, e.g.Pluto Profit. step.startedAt- Started.
step.status- State.One of
running,done,failed,awaiting_approval,rejected,stopped step.tool- The MCP tool; null for every kind but
tool. stepId- The thinking step a delta belongs to.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them. - 503The Agent isn't set up.
curl -X POST "$PLUTO_API/agent/chats/26926918-2839-4fc9-87f3-3707d4b8e0d7/messages" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 33697be0-65d9-4711-88f9-738259bb7797" \
-H "Content-Type: application/json" \
-d '{
"context": {
"adId": "a96d7456-dc02-4734-998b-3e439361abe3",
"fileIds": [
"1407e6a7-8e94-4479-98ab-d5432626c5a5"
],
"launchId": "2046ac37-4775-4757-9ef2-3d948cbfc560",
"loopId": "94956d8d-acdf-4e32-b384-25d0b605c2a9",
"mediaIds": [
"04acd56b-ded4-4670-9f9b-1c0c550c1701"
],
"path": "fall-2026/vitamin-c-serum-ugc-9x16.mp4",
"selectedStepIds": [
"202f56bb-33ee-4280-a52e-487822738349"
]
},
"effort": "low",
"model": "pluto",
"text": "Can we try the 4x5 cut for Instagram feed before we publish?"
}'Edit a message
Edits one of your own messages (any of them, not only the last) and continues the chat from it, like editing in ChatGPT or Claude. A running answer stops first, as with POST /agent/chats/{id}/stop (what it did stays done and billed). The new text becomes the message's next version (version, versions); everything after the message leaves the conversation and stays with the earlier version, never deleted (GET .../versions, POST .../version switch back). The Agent answers with the history up to the edited message, billed like any answer; earlier answers' usage is never refunded or charged again. The body is the same as sending a message; attachments in context replace the message's. Only the person who sent the message (403 otherwise); 409 when the answer couldn't be stopped in time, or for a message no longer in the conversation. Answers with server-sent events like sending a message, starting with the new version.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The chat's ID. |
message_id | string | Required | The message's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
contextcontext.adId- The open ad.
context.fileIds- Chat files attached, each
ready. context.launchId- The open launch.
context.loopId- The loop open in the builder.
context.mediaIds- Media library items attached.
context.path- The app page the person is on.
context.selectedStepIds- Steps selected on the builder's canvas (up to 50).
effort- A reasoning effort the model accepts.One of
low,medium,high,xhigh,max modelpluto,autoor a model ID fromGET /agent/models: the chat runs on it from here on.text- 1-16000 characters.
Response
approvalapproval.canApprove- The viewer can approve it: the same as
canDecide. approval.canDecide- The viewer may approve or decline it: they hold
capability, and it's theirs to decide (the person the Agent proposed it for, or an organization owner or admin). approval.capability- What approving or declining it needs, as a capability ID (
ads:publish): the capability of the tool it runs, or of what its call asked for beyond it (a copy made at the platform). Someone without it never decides it, the person who asked included. approval.chatId- Chat.
approval.createdAt- Proposed.
approval.decidedAt- Decided.
approval.effectapproval.effect.done- The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approval.effect.entities- What it changes.
approval.effect.entities[].id- ID.
approval.effect.entities[].kind- Kind.One of
launch,adSet,ad approval.effect.entities[].launchId- Its launch.
approval.effect.entities[].name- Name.
approval.effect.lines- Human details, never field names or IDs.
approval.effect.lines[].label- A human label, e.g. Trigger.
approval.effect.lines[].value- Its value, e.g. New comment.
approval.effect.money- Amounts it spends or sets.
approval.effect.money[].amount- A decimal amount; never a float.
approval.effect.money[].currency- ISO 4217; null when the account's currency isn't known.
approval.effect.money[].label- Label.
approval.effect.subject- What it acts on, one quiet line to show under the title without expanding; absent for most actions. A comment action names the comment: v.i.u.m: “Does this work for small teams?” on App review test.
approval.effect.summary- What it does, in a sentence; empty when that would only repeat
title. approval.effect.title- The action as one sentence with real names, never IDs: Delete loop “Facebook comment moderator”. A tool without its own sentence reads as its title.
approval.effect.warnings- Things to know before approving.
approval.error- Why it failed, or the reason it was declined.
approval.error.code- Stable code.
approval.error.message- For the person.
approval.error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. approval.id- Approval.
approval.messageId- The answer that proposed it.
approval.permission- The coarse permission the call asked with: the action's own (
read,revieworwriteonly when the person chose Ask every time). What deciding needs iscapability.One ofread,review,write,publish,admin,organization approval.result- After approving.
approval.result.jobId- The job it started.
approval.result.summary- What happened.
approval.status- State.One of
pending,approved,rejected,failed,superseded approval.title- What it does, as one sentence with real names and never IDs, e.g. Delete loop “Facebook comment moderator”. The same as
effect.title. approval.tool- The MCP tool it runs.
chatchat.createdAt- Started.
chat.effort- The reasoning effort picked for the chat; null: the model's default.
chat.id- Chat.
chat.lastMessageAt- Last message.
chat.loopId- The loop it is the history of (it made the loop, or was started in its builder).
chat.model- The chat's model:
pluto,autoor a model ID fromGET /agent/models. chat.ownerId- The chat's person: only they rename, delete or share it.
chat.shared- Shared with everyone who can see its loop; false: private to its person.
chat.source- Where it started.One of
page,panel,home,loop chat.status- What it's doing.One of
idle,running,awaiting_approval chat.title- Title; null until the first answer names it.
chat.unread- An answer arrived after the person last read it.
chat.updatedAt- Last change.
codeerror: spend_limit, payment_required, model_unavailable, rate_limited, refusal, max_tokens, step_limit or internal.delta- Text to append.
messagemessage.approvalIds- Approvals raised in this answer.
message.attachments- Files the person attached.
message.attachments[].contentType- A chat file's type.
message.attachments[].fileId- A chat file, uploaded for the message.
message.attachments[].kind- Kind (a media library item is an
imageor avideo).One ofimage,video,pdf,document,spreadsheet,presentation,text,code,audio,archive message.attachments[].mediaId- A media library item.
message.attachments[].name- File name.
message.attachments[].pageCount- Pages of a PDF, Word document or presentation.
message.attachments[].previewUrl- A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
message.attachments[].sizeBytes- A chat file's size.
message.chatId- Chat.
message.completedAt- Finished.
message.createdAt- Written.
message.error- Why the answer failed.
message.error.code- Stable code.
message.error.message- For the person.
message.error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. message.id- Message.
message.model- The model that produced the answer; null for the person's messages.
message.parts- The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
message.parts[].answerquestion: the answer once given (a choice's label, or the words of your reply).message.parts[].choiceIdquestion: the choice it was answered with.message.parts[].choicesquestion: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).message.parts[].columnstable: its columns.message.parts[].data- Every kind but
comboandtable: the series. message.parts[].description- One line under the title: the period, the unit.
message.parts[].groupscombo: its groups.message.parts[].id- The part; the same ID again replaces it.
message.parts[].itemsads: the ads, in the order shown.message.parts[].kind- How it's drawn;
tableis a table.One ofline,bar,horizontal-bar,stacked-bar,stacked-area,donut,funnel,combo,simple-bar,simple-normalized,spark-line,spark-bar,table message.parts[].optionsselection: the options (POST /agent/chats/{id}/parts/{part_id}/select).message.parts[].periodads: the days of itsmetrics:since,untilandpreset(last_30_days, …, or null).message.parts[].proposedselection: the options the Agent recommends, checked at first.message.parts[].rowstable: its rows.message.parts[].selectedselection: the options you confirmed.message.parts[].showLegend- Whether a legend shows; absent: for two or more series.
message.parts[].sizesimple-normalizedonly.One ofsmall,medium,largemessage.parts[].textquestion: the question.text: the words (Markdown).message.parts[].title- What it shows.
message.parts[].type- A chart or a table, a question the Agent asks, options it proposes, ads it shows as cards, or the answer's words written before the card that follows them.One of
chart,question,selection,ads,text message.parts[].valueFormat- How values read:
style(decimal,percentwith values as percentages,currencywithcurrency),notation,minimumFractionDigits,maximumFractionDigits,unit. message.parts[].xAxislabel,hide.message.parts[].yAxislabel,integersOnly.message.role- Who wrote it.One of
user,assistant message.sentBy- Who sent a person's message (only they edit it); null for answers and for older messages, which are the chat's person's.
message.sources- The web pages the answer used: cited pages in the order first cited, then pages it read without citing; each URL once. Empty when it didn't use the web.
message.sources[].site- The hostname without
www.. message.sources[].title- Its title (its site when it named none).
message.sources[].url- The page.
message.status- State:
waitingfor credits;awaiting_userwhen the answer asked a question or proposed a selection (parts) and waits for your reply.One ofcomplete,streaming,stopped,failed,awaiting_approval,waiting,awaiting_user message.steps- What the Agent did, in order.
message.steps[].category- What kind of call it is, for a summary like "Created 2 launches, ran a search": from what the tool does (adds, changes, reads, lists, searches),
mcpfor another Pluto product (server). Absent for narration and thinking, and on older steps.One ofwrite,edit,read,list,search,mcp,other message.steps[].detail- Error, reasoning or narration text; a search's query; a read page's URL.
message.steps[].entities- What it touched.
message.steps[].entities[].id- ID.
message.steps[].entities[].kind- Kind.One of
launch,adSet,ad message.steps[].entities[].launchId- Its launch.
message.steps[].entities[].name- Name.
message.steps[].finishedAt- Finished.
message.steps[].id- Step.
message.steps[].kind- A tool call, narration before tools, summarized reasoning, a web search (
detailis the query) or a web page read (detailis its URL).One oftool,note,thinking,search,fetch message.steps[].label- Present tense while running, past tense when done.
message.steps[].server- The Pluto product an
mcpstep used, e.g.Pluto Profit. message.steps[].startedAt- Started.
message.steps[].status- State.One of
running,done,failed,awaiting_approval,rejected,stopped message.steps[].tool- The MCP tool; null for every kind but
tool. message.text- The question, or the answer (markdown;
pluto:links name launches, ad sets and ads). message.version- Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
message.versions- How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
message.workedMs- Active time, excluding waits for approval.
messageId- The Agent message a delta belongs to.
partpart.answerquestion: the answer once given (a choice's label, or the words of your reply).part.choiceIdquestion: the choice it was answered with.part.choicesquestion: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).part.columnstable: its columns.part.data- Every kind but
comboandtable: the series. part.description- One line under the title: the period, the unit.
part.groupscombo: its groups.part.id- The part; the same ID again replaces it.
part.itemsads: the ads, in the order shown.part.kind- How it's drawn;
tableis a table.One ofline,bar,horizontal-bar,stacked-bar,stacked-area,donut,funnel,combo,simple-bar,simple-normalized,spark-line,spark-bar,table part.optionsselection: the options (POST /agent/chats/{id}/parts/{part_id}/select).part.periodads: the days of itsmetrics:since,untilandpreset(last_30_days, …, or null).part.proposedselection: the options the Agent recommends, checked at first.part.rowstable: its rows.part.selectedselection: the options you confirmed.part.showLegend- Whether a legend shows; absent: for two or more series.
part.sizesimple-normalizedonly.One ofsmall,medium,largepart.textquestion: the question.text: the words (Markdown).part.title- What it shows.
part.type- A chart or a table, a question the Agent asks, options it proposes, ads it shows as cards, or the answer's words written before the card that follows them.One of
chart,question,selection,ads,text part.valueFormat- How values read:
style(decimal,percentwith values as percentages,currencywithcurrency),notation,minimumFractionDigits,maximumFractionDigits,unit. part.xAxislabel,hide.part.yAxislabel,integersOnly.reasonerrorwith spend_limit: which limit stopped it (member_limit, workspace_limit or trial_cap); with payment_required: why there's no access.retryableerror: whether retrying can help.sourcessourcesevents: the answer's web pages so far.sources[].site- The hostname without
www.. sources[].title- Its title (its site when it named none).
sources[].url- The page.
stallstall: why the answer seems stuck, decided from the stream:no_first_byte(the model sent nothing for 10 s),silent_stream(an open stream sent no event for 15 s) orsilent_tool(a tool reported nothing for 45 s), andsince, when the silence began (epoch milliseconds);nullonce it moves again.stall.kind- What went quiet.One of
no_first_byte,silent_stream,silent_tool stall.since- When the silence began, epoch milliseconds.
stepstep.category- What kind of call it is, for a summary like "Created 2 launches, ran a search": from what the tool does (adds, changes, reads, lists, searches),
mcpfor another Pluto product (server). Absent for narration and thinking, and on older steps.One ofwrite,edit,read,list,search,mcp,other step.detail- Error, reasoning or narration text; a search's query; a read page's URL.
step.entities- What it touched.
step.entities[].id- ID.
step.entities[].kind- Kind.One of
launch,adSet,ad step.entities[].launchId- Its launch.
step.entities[].name- Name.
step.finishedAt- Finished.
step.id- Step.
step.kind- A tool call, narration before tools, summarized reasoning, a web search (
detailis the query) or a web page read (detailis its URL).One oftool,note,thinking,search,fetch step.label- Present tense while running, past tense when done.
step.server- The Pluto product an
mcpstep used, e.g.Pluto Profit. step.startedAt- Started.
step.status- State.One of
running,done,failed,awaiting_approval,rejected,stopped step.tool- The MCP tool; null for every kind but
tool. stepId- The thinking step a delta belongs to.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them. - 503The Agent isn't set up.
curl -X POST "$PLUTO_API/agent/chats/26926918-2839-4fc9-87f3-3707d4b8e0d7/messages/ed2edbe6-7226-4cfb-b34a-c7b9965ec61b/edit" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 37a5cc78-2116-4bf4-9d39-fca3714050c0" \
-H "Content-Type: application/json" \
-d '{
"context": {
"adId": "a96d7456-dc02-4734-998b-3e439361abe3",
"fileIds": [
"1407e6a7-8e94-4479-98ab-d5432626c5a5"
],
"launchId": "2046ac37-4775-4757-9ef2-3d948cbfc560",
"loopId": "94956d8d-acdf-4e32-b384-25d0b605c2a9",
"mediaIds": [
"04acd56b-ded4-4670-9f9b-1c0c550c1701"
],
"path": "fall-2026/vitamin-c-serum-ugc-9x16.mp4",
"selectedStepIds": [
"202f56bb-33ee-4280-a52e-487822738349"
]
},
"effort": "low",
"model": "pluto",
"text": "Can we try the 4x5 cut for Instagram feed before we publish?"
}'Rate an answer
Thumbs up or down on one of the Agent's answers, with an optional reason chip when down. One rating per answer and person; rating again replaces it. comment (up to 500 characters) is kept only while the organization has "Help improve Pluto's AI" on, and never used to train models. Rating a question (not an answer) is a 422; another person's chat is a 404. Not for guests.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The chat's ID. |
message_id | string | Required | The message's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
comment- Optional; kept only with "Help improve Pluto's AI" on.
rating- Thumbs up or down.One of
up,down reason- Why it was rated down (ignored for a thumbs up).One of
wrong_answer,ignored_request,wrong_changes,too_slow,other
Response
comment- Kept only while the organization has "Help improve Pluto's AI" on; null otherwise.
messageId- The rated answer.
rating- Thumbs up or down.One of
up,down reason- Why it was rated down; null for a thumbs up or without a reason.One of
wrong_answer,ignored_request,wrong_changes,too_slow,other updatedAt- When it was last rated.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PUT "$PLUTO_API/agent/chats/26926918-2839-4fc9-87f3-3707d4b8e0d7/messages/ed2edbe6-7226-4cfb-b34a-c7b9965ec61b/feedback" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: e79e8367-ff79-4254-ac01-573ae6b0afe1" \
-H "Content-Type: application/json" \
-d '{
"comment": "Can we try the 4x5 cut for Instagram feed before we publish?",
"rating": "up",
"reason": "wrong_answer"
}'Clear your rating
Removes your rating of the answer. Clearing one that isn't there succeeds too.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The chat's ID. |
message_id | string | Required | The message's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
Done; no content.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/agent/chats/26926918-2839-4fc9-87f3-3707d4b8e0d7/messages/ed2edbe6-7226-4cfb-b34a-c7b9965ec61b/feedback" \
-H "Authorization: Bearer $PLUTO_KEY"Retry an answer as a new version
Runs one of the conversation's answers (message_id, any of them, not only the last) again as its next version, like Retry in Claude: the answer and everything after it leave the conversation and stay with the earlier version, never deleted (GET .../versions and POST .../version on the answer switch back). The Agent answers the question before it again, with what it attached, as the person who asked it and with their access now; earlier versions keep their usage, the new one is billed like any answer. Send { "model": ..., "effort": ... } to run it on another model (the chat keeps it from then on), or no body for the chat's own. 422 for a question's ID (edit a question instead); 409 while an answer runs, or for an answer no longer in the conversation. Answers with server-sent events like sending a message, starting with the new version.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The chat's ID. |
message_id | string | Required | The message's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
approvalapproval.canApprove- The viewer can approve it: the same as
canDecide. approval.canDecide- The viewer may approve or decline it: they hold
capability, and it's theirs to decide (the person the Agent proposed it for, or an organization owner or admin). approval.capability- What approving or declining it needs, as a capability ID (
ads:publish): the capability of the tool it runs, or of what its call asked for beyond it (a copy made at the platform). Someone without it never decides it, the person who asked included. approval.chatId- Chat.
approval.createdAt- Proposed.
approval.decidedAt- Decided.
approval.effectapproval.effect.done- The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approval.effect.entities- What it changes.
approval.effect.entities[].id- ID.
approval.effect.entities[].kind- Kind.One of
launch,adSet,ad approval.effect.entities[].launchId- Its launch.
approval.effect.entities[].name- Name.
approval.effect.lines- Human details, never field names or IDs.
approval.effect.lines[].label- A human label, e.g. Trigger.
approval.effect.lines[].value- Its value, e.g. New comment.
approval.effect.money- Amounts it spends or sets.
approval.effect.money[].amount- A decimal amount; never a float.
approval.effect.money[].currency- ISO 4217; null when the account's currency isn't known.
approval.effect.money[].label- Label.
approval.effect.subject- What it acts on, one quiet line to show under the title without expanding; absent for most actions. A comment action names the comment: v.i.u.m: “Does this work for small teams?” on App review test.
approval.effect.summary- What it does, in a sentence; empty when that would only repeat
title. approval.effect.title- The action as one sentence with real names, never IDs: Delete loop “Facebook comment moderator”. A tool without its own sentence reads as its title.
approval.effect.warnings- Things to know before approving.
approval.error- Why it failed, or the reason it was declined.
approval.error.code- Stable code.
approval.error.message- For the person.
approval.error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. approval.id- Approval.
approval.messageId- The answer that proposed it.
approval.permission- The coarse permission the call asked with: the action's own (
read,revieworwriteonly when the person chose Ask every time). What deciding needs iscapability.One ofread,review,write,publish,admin,organization approval.result- After approving.
approval.result.jobId- The job it started.
approval.result.summary- What happened.
approval.status- State.One of
pending,approved,rejected,failed,superseded approval.title- What it does, as one sentence with real names and never IDs, e.g. Delete loop “Facebook comment moderator”. The same as
effect.title. approval.tool- The MCP tool it runs.
chatchat.createdAt- Started.
chat.effort- The reasoning effort picked for the chat; null: the model's default.
chat.id- Chat.
chat.lastMessageAt- Last message.
chat.loopId- The loop it is the history of (it made the loop, or was started in its builder).
chat.model- The chat's model:
pluto,autoor a model ID fromGET /agent/models. chat.ownerId- The chat's person: only they rename, delete or share it.
chat.shared- Shared with everyone who can see its loop; false: private to its person.
chat.source- Where it started.One of
page,panel,home,loop chat.status- What it's doing.One of
idle,running,awaiting_approval chat.title- Title; null until the first answer names it.
chat.unread- An answer arrived after the person last read it.
chat.updatedAt- Last change.
codeerror: spend_limit, payment_required, model_unavailable, rate_limited, refusal, max_tokens, step_limit or internal.delta- Text to append.
messagemessage.approvalIds- Approvals raised in this answer.
message.attachments- Files the person attached.
message.attachments[].contentType- A chat file's type.
message.attachments[].fileId- A chat file, uploaded for the message.
message.attachments[].kind- Kind (a media library item is an
imageor avideo).One ofimage,video,pdf,document,spreadsheet,presentation,text,code,audio,archive message.attachments[].mediaId- A media library item.
message.attachments[].name- File name.
message.attachments[].pageCount- Pages of a PDF, Word document or presentation.
message.attachments[].previewUrl- A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
message.attachments[].sizeBytes- A chat file's size.
message.chatId- Chat.
message.completedAt- Finished.
message.createdAt- Written.
message.error- Why the answer failed.
message.error.code- Stable code.
message.error.message- For the person.
message.error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. message.id- Message.
message.model- The model that produced the answer; null for the person's messages.
message.parts- The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
message.parts[].answerquestion: the answer once given (a choice's label, or the words of your reply).message.parts[].choiceIdquestion: the choice it was answered with.message.parts[].choicesquestion: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).message.parts[].columnstable: its columns.message.parts[].data- Every kind but
comboandtable: the series. message.parts[].description- One line under the title: the period, the unit.
message.parts[].groupscombo: its groups.message.parts[].id- The part; the same ID again replaces it.
message.parts[].itemsads: the ads, in the order shown.message.parts[].kind- How it's drawn;
tableis a table.One ofline,bar,horizontal-bar,stacked-bar,stacked-area,donut,funnel,combo,simple-bar,simple-normalized,spark-line,spark-bar,table message.parts[].optionsselection: the options (POST /agent/chats/{id}/parts/{part_id}/select).message.parts[].periodads: the days of itsmetrics:since,untilandpreset(last_30_days, …, or null).message.parts[].proposedselection: the options the Agent recommends, checked at first.message.parts[].rowstable: its rows.message.parts[].selectedselection: the options you confirmed.message.parts[].showLegend- Whether a legend shows; absent: for two or more series.
message.parts[].sizesimple-normalizedonly.One ofsmall,medium,largemessage.parts[].textquestion: the question.text: the words (Markdown).message.parts[].title- What it shows.
message.parts[].type- A chart or a table, a question the Agent asks, options it proposes, ads it shows as cards, or the answer's words written before the card that follows them.One of
chart,question,selection,ads,text message.parts[].valueFormat- How values read:
style(decimal,percentwith values as percentages,currencywithcurrency),notation,minimumFractionDigits,maximumFractionDigits,unit. message.parts[].xAxislabel,hide.message.parts[].yAxislabel,integersOnly.message.role- Who wrote it.One of
user,assistant message.sentBy- Who sent a person's message (only they edit it); null for answers and for older messages, which are the chat's person's.
message.sources- The web pages the answer used: cited pages in the order first cited, then pages it read without citing; each URL once. Empty when it didn't use the web.
message.sources[].site- The hostname without
www.. message.sources[].title- Its title (its site when it named none).
message.sources[].url- The page.
message.status- State:
waitingfor credits;awaiting_userwhen the answer asked a question or proposed a selection (parts) and waits for your reply.One ofcomplete,streaming,stopped,failed,awaiting_approval,waiting,awaiting_user message.steps- What the Agent did, in order.
message.steps[].category- What kind of call it is, for a summary like "Created 2 launches, ran a search": from what the tool does (adds, changes, reads, lists, searches),
mcpfor another Pluto product (server). Absent for narration and thinking, and on older steps.One ofwrite,edit,read,list,search,mcp,other message.steps[].detail- Error, reasoning or narration text; a search's query; a read page's URL.
message.steps[].entities- What it touched.
message.steps[].entities[].id- ID.
message.steps[].entities[].kind- Kind.One of
launch,adSet,ad message.steps[].entities[].launchId- Its launch.
message.steps[].entities[].name- Name.
message.steps[].finishedAt- Finished.
message.steps[].id- Step.
message.steps[].kind- A tool call, narration before tools, summarized reasoning, a web search (
detailis the query) or a web page read (detailis its URL).One oftool,note,thinking,search,fetch message.steps[].label- Present tense while running, past tense when done.
message.steps[].server- The Pluto product an
mcpstep used, e.g.Pluto Profit. message.steps[].startedAt- Started.
message.steps[].status- State.One of
running,done,failed,awaiting_approval,rejected,stopped message.steps[].tool- The MCP tool; null for every kind but
tool. message.text- The question, or the answer (markdown;
pluto:links name launches, ad sets and ads). message.version- Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
message.versions- How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
message.workedMs- Active time, excluding waits for approval.
messageId- The Agent message a delta belongs to.
partpart.answerquestion: the answer once given (a choice's label, or the words of your reply).part.choiceIdquestion: the choice it was answered with.part.choicesquestion: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).part.columnstable: its columns.part.data- Every kind but
comboandtable: the series. part.description- One line under the title: the period, the unit.
part.groupscombo: its groups.part.id- The part; the same ID again replaces it.
part.itemsads: the ads, in the order shown.part.kind- How it's drawn;
tableis a table.One ofline,bar,horizontal-bar,stacked-bar,stacked-area,donut,funnel,combo,simple-bar,simple-normalized,spark-line,spark-bar,table part.optionsselection: the options (POST /agent/chats/{id}/parts/{part_id}/select).part.periodads: the days of itsmetrics:since,untilandpreset(last_30_days, …, or null).part.proposedselection: the options the Agent recommends, checked at first.part.rowstable: its rows.part.selectedselection: the options you confirmed.part.showLegend- Whether a legend shows; absent: for two or more series.
part.sizesimple-normalizedonly.One ofsmall,medium,largepart.textquestion: the question.text: the words (Markdown).part.title- What it shows.
part.type- A chart or a table, a question the Agent asks, options it proposes, ads it shows as cards, or the answer's words written before the card that follows them.One of
chart,question,selection,ads,text part.valueFormat- How values read:
style(decimal,percentwith values as percentages,currencywithcurrency),notation,minimumFractionDigits,maximumFractionDigits,unit. part.xAxislabel,hide.part.yAxislabel,integersOnly.reasonerrorwith spend_limit: which limit stopped it (member_limit, workspace_limit or trial_cap); with payment_required: why there's no access.retryableerror: whether retrying can help.sourcessourcesevents: the answer's web pages so far.sources[].site- The hostname without
www.. sources[].title- Its title (its site when it named none).
sources[].url- The page.
stallstall: why the answer seems stuck, decided from the stream:no_first_byte(the model sent nothing for 10 s),silent_stream(an open stream sent no event for 15 s) orsilent_tool(a tool reported nothing for 45 s), andsince, when the silence began (epoch milliseconds);nullonce it moves again.stall.kind- What went quiet.One of
no_first_byte,silent_stream,silent_tool stall.since- When the silence began, epoch milliseconds.
stepstep.category- What kind of call it is, for a summary like "Created 2 launches, ran a search": from what the tool does (adds, changes, reads, lists, searches),
mcpfor another Pluto product (server). Absent for narration and thinking, and on older steps.One ofwrite,edit,read,list,search,mcp,other step.detail- Error, reasoning or narration text; a search's query; a read page's URL.
step.entities- What it touched.
step.entities[].id- ID.
step.entities[].kind- Kind.One of
launch,adSet,ad step.entities[].launchId- Its launch.
step.entities[].name- Name.
step.finishedAt- Finished.
step.id- Step.
step.kind- A tool call, narration before tools, summarized reasoning, a web search (
detailis the query) or a web page read (detailis its URL).One oftool,note,thinking,search,fetch step.label- Present tense while running, past tense when done.
step.server- The Pluto product an
mcpstep used, e.g.Pluto Profit. step.startedAt- Started.
step.status- State.One of
running,done,failed,awaiting_approval,rejected,stopped step.tool- The MCP tool; null for every kind but
tool. stepId- The thinking step a delta belongs to.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them. - 503The Agent isn't set up.
curl -X POST "$PLUTO_API/agent/chats/26926918-2839-4fc9-87f3-3707d4b8e0d7/messages/ed2edbe6-7226-4cfb-b34a-c7b9965ec61b/retry" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 5687ee90-1e1e-4f93-814a-32a32af48218"Switch a message version
Shows version version of the message (message_id: any of its versions, a question or an answer) with the messages that followed it, as left; nothing is deleted. 409 while an answer runs, or when an earlier message's version hides this one. Answers with the chat, as GET /agent/chats/{id}.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The chat's ID. |
message_id | string | Required | The message's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
version- 1-based, as
versionon the message.
Response
approvals- The approvals these messages carry.
approvals[].canApprove- The viewer can approve it: the same as
canDecide. approvals[].canDecide- The viewer may approve or decline it: they hold
capability, and it's theirs to decide (the person the Agent proposed it for, or an organization owner or admin). approvals[].capability- What approving or declining it needs, as a capability ID (
ads:publish): the capability of the tool it runs, or of what its call asked for beyond it (a copy made at the platform). Someone without it never decides it, the person who asked included. approvals[].chatId- Chat.
approvals[].createdAt- Proposed.
approvals[].decidedAt- Decided.
approvals[].effectapprovals[].effect.done- The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approvals[].effect.entities- What it changes.
approvals[].effect.entities[].id- ID.
approvals[].effect.entities[].kind- Kind.One of
launch,adSet,ad approvals[].effect.entities[].launchId- Its launch.
approvals[].effect.entities[].name- Name.
approvals[].effect.lines- Human details, never field names or IDs.
approvals[].effect.lines[].label- A human label, e.g. Trigger.
approvals[].effect.lines[].value- Its value, e.g. New comment.
approvals[].effect.money- Amounts it spends or sets.
approvals[].effect.money[].amount- A decimal amount; never a float.
approvals[].effect.money[].currency- ISO 4217; null when the account's currency isn't known.
approvals[].effect.money[].label- Label.
approvals[].effect.subject- What it acts on, one quiet line to show under the title without expanding; absent for most actions. A comment action names the comment: v.i.u.m: “Does this work for small teams?” on App review test.
approvals[].effect.summary- What it does, in a sentence; empty when that would only repeat
title. approvals[].effect.title- The action as one sentence with real names, never IDs: Delete loop “Facebook comment moderator”. A tool without its own sentence reads as its title.
approvals[].effect.warnings- Things to know before approving.
approvals[].error- Why it failed, or the reason it was declined.
approvals[].error.code- Stable code.
approvals[].error.message- For the person.
approvals[].error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. approvals[].id- Approval.
approvals[].messageId- The answer that proposed it.
approvals[].permission- The coarse permission the call asked with: the action's own (
read,revieworwriteonly when the person chose Ask every time). What deciding needs iscapability.One ofread,review,write,publish,admin,organization approvals[].result- After approving.
approvals[].result.jobId- The job it started.
approvals[].result.summary- What happened.
approvals[].status- State.One of
pending,approved,rejected,failed,superseded approvals[].title- What it does, as one sentence with real names and never IDs, e.g. Delete loop “Facebook comment moderator”. The same as
effect.title. approvals[].tool- The MCP tool it runs.
createdAt- Started.
effort- The reasoning effort picked for the chat; null: the model's default.
hasEarlier- Older messages exist:
?before=<first message id>. id- Chat.
lastMessageAt- Last message.
loopId- The loop it is the history of (it made the loop, or was started in its builder).
messages- The newest page (100 by default), oldest first.
messages[].approvalIds- Approvals raised in this answer.
messages[].attachments- Files the person attached.
messages[].attachments[].contentType- A chat file's type.
messages[].attachments[].fileId- A chat file, uploaded for the message.
messages[].attachments[].kind- Kind (a media library item is an
imageor avideo).One ofimage,video,pdf,document,spreadsheet,presentation,text,code,audio,archive messages[].attachments[].mediaId- A media library item.
messages[].attachments[].name- File name.
messages[].attachments[].pageCount- Pages of a PDF, Word document or presentation.
messages[].attachments[].previewUrl- A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
messages[].attachments[].sizeBytes- A chat file's size.
messages[].chatId- Chat.
messages[].completedAt- Finished.
messages[].createdAt- Written.
messages[].error- Why the answer failed.
messages[].error.code- Stable code.
messages[].error.message- For the person.
messages[].error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. messages[].id- Message.
messages[].model- The model that produced the answer; null for the person's messages.
messages[].parts- The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
messages[].parts[].answerquestion: the answer once given (a choice's label, or the words of your reply).messages[].parts[].choiceIdquestion: the choice it was answered with.messages[].parts[].choicesquestion: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).messages[].parts[].columnstable: its columns.messages[].parts[].data- Every kind but
comboandtable: the series. messages[].parts[].description- One line under the title: the period, the unit.
messages[].parts[].groupscombo: its groups.messages[].parts[].id- The part; the same ID again replaces it.
messages[].parts[].itemsads: the ads, in the order shown.messages[].parts[].kind- How it's drawn;
tableis a table.One ofline,bar,horizontal-bar,stacked-bar,stacked-area,donut,funnel,combo,simple-bar,simple-normalized,spark-line,spark-bar,table messages[].parts[].optionsselection: the options (POST /agent/chats/{id}/parts/{part_id}/select).messages[].parts[].periodads: the days of itsmetrics:since,untilandpreset(last_30_days, …, or null).messages[].parts[].proposedselection: the options the Agent recommends, checked at first.messages[].parts[].rowstable: its rows.messages[].parts[].selectedselection: the options you confirmed.messages[].parts[].showLegend- Whether a legend shows; absent: for two or more series.
messages[].parts[].sizesimple-normalizedonly.One ofsmall,medium,largemessages[].parts[].textquestion: the question.text: the words (Markdown).messages[].parts[].title- What it shows.
messages[].parts[].type- A chart or a table, a question the Agent asks, options it proposes, ads it shows as cards, or the answer's words written before the card that follows them.One of
chart,question,selection,ads,text messages[].parts[].valueFormat- How values read:
style(decimal,percentwith values as percentages,currencywithcurrency),notation,minimumFractionDigits,maximumFractionDigits,unit. messages[].parts[].xAxislabel,hide.messages[].parts[].yAxislabel,integersOnly.messages[].role- Who wrote it.One of
user,assistant messages[].sentBy- Who sent a person's message (only they edit it); null for answers and for older messages, which are the chat's person's.
messages[].sources- The web pages the answer used: cited pages in the order first cited, then pages it read without citing; each URL once. Empty when it didn't use the web.
messages[].sources[].site- The hostname without
www.. messages[].sources[].title- Its title (its site when it named none).
messages[].sources[].url- The page.
messages[].status- State:
waitingfor credits;awaiting_userwhen the answer asked a question or proposed a selection (parts) and waits for your reply.One ofcomplete,streaming,stopped,failed,awaiting_approval,waiting,awaiting_user messages[].steps- What the Agent did, in order.
messages[].steps[].category- What kind of call it is, for a summary like "Created 2 launches, ran a search": from what the tool does (adds, changes, reads, lists, searches),
mcpfor another Pluto product (server). Absent for narration and thinking, and on older steps.One ofwrite,edit,read,list,search,mcp,other messages[].steps[].detail- Error, reasoning or narration text; a search's query; a read page's URL.
messages[].steps[].entities- What it touched.
messages[].steps[].entities[].id- ID.
messages[].steps[].entities[].kind- Kind.One of
launch,adSet,ad messages[].steps[].entities[].launchId- Its launch.
messages[].steps[].entities[].name- Name.
messages[].steps[].finishedAt- Finished.
messages[].steps[].id- Step.
messages[].steps[].kind- A tool call, narration before tools, summarized reasoning, a web search (
detailis the query) or a web page read (detailis its URL).One oftool,note,thinking,search,fetch messages[].steps[].label- Present tense while running, past tense when done.
messages[].steps[].server- The Pluto product an
mcpstep used, e.g.Pluto Profit. messages[].steps[].startedAt- Started.
messages[].steps[].status- State.One of
running,done,failed,awaiting_approval,rejected,stopped messages[].steps[].tool- The MCP tool; null for every kind but
tool. messages[].text- The question, or the answer (markdown;
pluto:links name launches, ad sets and ads). messages[].version- Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
messages[].versions- How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
messages[].workedMs- Active time, excluding waits for approval.
model- The chat's model:
pluto,autoor a model ID fromGET /agent/models. ownerId- The chat's person: only they rename, delete or share it.
shared- Shared with everyone who can see its loop; false: private to its person.
source- Where it started.One of
page,panel,home,loop status- What it's doing.One of
idle,running,awaiting_approval title- Title; null until the first answer names it.
unread- An answer arrived after the person last read it.
updatedAt- Last change.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/agent/chats/26926918-2839-4fc9-87f3-3707d4b8e0d7/messages/ed2edbe6-7226-4cfb-b34a-c7b9965ec61b/version" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 953471b5-65f4-4050-8be6-65aa8b5e02cf" \
-H "Content-Type: application/json" \
-d '{
"version": 3
}'List message versions
The versions of one of the chat's messages (message_id: any of them), oldest first; current marks the one in the conversation now. Editing a question adds a version of it, retrying an answer (POST .../retry) a version of the answer, and each version keeps the messages that followed it.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The chat's ID. |
message_id | string | Required | The message's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- Oldest first.
items[].attachments- Its files.
items[].attachments[].contentType- A chat file's type.
items[].attachments[].fileId- A chat file, uploaded for the message.
items[].attachments[].kind- Kind (a media library item is an
imageor avideo).One ofimage,video,pdf,document,spreadsheet,presentation,text,code,audio,archive items[].attachments[].mediaId- A media library item.
items[].attachments[].name- File name.
items[].attachments[].pageCount- Pages of a PDF, Word document or presentation.
items[].attachments[].previewUrl- A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
items[].attachments[].sizeBytes- A chat file's size.
items[].createdAt- Sent.
items[].current- In the conversation now.
items[].id- This version's message.
items[].text- Its text.
items[].version- 1-based, oldest first.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/agent/chats/26926918-2839-4fc9-87f3-3707d4b8e0d7/messages/ed2edbe6-7226-4cfb-b34a-c7b9965ec61b/versions" \
-H "Authorization: Bearer $PLUTO_KEY"Answer the Agent's question
Answers the question the chat's last answer asked (a question part, part_id its id, while the answer is awaiting_user) with one of its choices. The choice's words become your next message, the part records them (answer, choiceId), and the Agent continues; replying in your own words with POST /agent/chats/{id}/messages answers it too. 409 when the question isn't open any more; 422 for a choice it doesn't have. Answers with server-sent events like sending a message.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The chat's ID. |
part_id | string | Required | The part's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
choiceId- One of the question's
choices[].id.
Response
approvalapproval.canApprove- The viewer can approve it: the same as
canDecide. approval.canDecide- The viewer may approve or decline it: they hold
capability, and it's theirs to decide (the person the Agent proposed it for, or an organization owner or admin). approval.capability- What approving or declining it needs, as a capability ID (
ads:publish): the capability of the tool it runs, or of what its call asked for beyond it (a copy made at the platform). Someone without it never decides it, the person who asked included. approval.chatId- Chat.
approval.createdAt- Proposed.
approval.decidedAt- Decided.
approval.effectapproval.effect.done- The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approval.effect.entities- What it changes.
approval.effect.entities[].id- ID.
approval.effect.entities[].kind- Kind.One of
launch,adSet,ad approval.effect.entities[].launchId- Its launch.
approval.effect.entities[].name- Name.
approval.effect.lines- Human details, never field names or IDs.
approval.effect.lines[].label- A human label, e.g. Trigger.
approval.effect.lines[].value- Its value, e.g. New comment.
approval.effect.money- Amounts it spends or sets.
approval.effect.money[].amount- A decimal amount; never a float.
approval.effect.money[].currency- ISO 4217; null when the account's currency isn't known.
approval.effect.money[].label- Label.
approval.effect.subject- What it acts on, one quiet line to show under the title without expanding; absent for most actions. A comment action names the comment: v.i.u.m: “Does this work for small teams?” on App review test.
approval.effect.summary- What it does, in a sentence; empty when that would only repeat
title. approval.effect.title- The action as one sentence with real names, never IDs: Delete loop “Facebook comment moderator”. A tool without its own sentence reads as its title.
approval.effect.warnings- Things to know before approving.
approval.error- Why it failed, or the reason it was declined.
approval.error.code- Stable code.
approval.error.message- For the person.
approval.error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. approval.id- Approval.
approval.messageId- The answer that proposed it.
approval.permission- The coarse permission the call asked with: the action's own (
read,revieworwriteonly when the person chose Ask every time). What deciding needs iscapability.One ofread,review,write,publish,admin,organization approval.result- After approving.
approval.result.jobId- The job it started.
approval.result.summary- What happened.
approval.status- State.One of
pending,approved,rejected,failed,superseded approval.title- What it does, as one sentence with real names and never IDs, e.g. Delete loop “Facebook comment moderator”. The same as
effect.title. approval.tool- The MCP tool it runs.
chatchat.createdAt- Started.
chat.effort- The reasoning effort picked for the chat; null: the model's default.
chat.id- Chat.
chat.lastMessageAt- Last message.
chat.loopId- The loop it is the history of (it made the loop, or was started in its builder).
chat.model- The chat's model:
pluto,autoor a model ID fromGET /agent/models. chat.ownerId- The chat's person: only they rename, delete or share it.
chat.shared- Shared with everyone who can see its loop; false: private to its person.
chat.source- Where it started.One of
page,panel,home,loop chat.status- What it's doing.One of
idle,running,awaiting_approval chat.title- Title; null until the first answer names it.
chat.unread- An answer arrived after the person last read it.
chat.updatedAt- Last change.
codeerror: spend_limit, payment_required, model_unavailable, rate_limited, refusal, max_tokens, step_limit or internal.delta- Text to append.
messagemessage.approvalIds- Approvals raised in this answer.
message.attachments- Files the person attached.
message.attachments[].contentType- A chat file's type.
message.attachments[].fileId- A chat file, uploaded for the message.
message.attachments[].kind- Kind (a media library item is an
imageor avideo).One ofimage,video,pdf,document,spreadsheet,presentation,text,code,audio,archive message.attachments[].mediaId- A media library item.
message.attachments[].name- File name.
message.attachments[].pageCount- Pages of a PDF, Word document or presentation.
message.attachments[].previewUrl- A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
message.attachments[].sizeBytes- A chat file's size.
message.chatId- Chat.
message.completedAt- Finished.
message.createdAt- Written.
message.error- Why the answer failed.
message.error.code- Stable code.
message.error.message- For the person.
message.error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. message.id- Message.
message.model- The model that produced the answer; null for the person's messages.
message.parts- The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
message.parts[].answerquestion: the answer once given (a choice's label, or the words of your reply).message.parts[].choiceIdquestion: the choice it was answered with.message.parts[].choicesquestion: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).message.parts[].columnstable: its columns.message.parts[].data- Every kind but
comboandtable: the series. message.parts[].description- One line under the title: the period, the unit.
message.parts[].groupscombo: its groups.message.parts[].id- The part; the same ID again replaces it.
message.parts[].itemsads: the ads, in the order shown.message.parts[].kind- How it's drawn;
tableis a table.One ofline,bar,horizontal-bar,stacked-bar,stacked-area,donut,funnel,combo,simple-bar,simple-normalized,spark-line,spark-bar,table message.parts[].optionsselection: the options (POST /agent/chats/{id}/parts/{part_id}/select).message.parts[].periodads: the days of itsmetrics:since,untilandpreset(last_30_days, …, or null).message.parts[].proposedselection: the options the Agent recommends, checked at first.message.parts[].rowstable: its rows.message.parts[].selectedselection: the options you confirmed.message.parts[].showLegend- Whether a legend shows; absent: for two or more series.
message.parts[].sizesimple-normalizedonly.One ofsmall,medium,largemessage.parts[].textquestion: the question.text: the words (Markdown).message.parts[].title- What it shows.
message.parts[].type- A chart or a table, a question the Agent asks, options it proposes, ads it shows as cards, or the answer's words written before the card that follows them.One of
chart,question,selection,ads,text message.parts[].valueFormat- How values read:
style(decimal,percentwith values as percentages,currencywithcurrency),notation,minimumFractionDigits,maximumFractionDigits,unit. message.parts[].xAxislabel,hide.message.parts[].yAxislabel,integersOnly.message.role- Who wrote it.One of
user,assistant message.sentBy- Who sent a person's message (only they edit it); null for answers and for older messages, which are the chat's person's.
message.sources- The web pages the answer used: cited pages in the order first cited, then pages it read without citing; each URL once. Empty when it didn't use the web.
message.sources[].site- The hostname without
www.. message.sources[].title- Its title (its site when it named none).
message.sources[].url- The page.
message.status- State:
waitingfor credits;awaiting_userwhen the answer asked a question or proposed a selection (parts) and waits for your reply.One ofcomplete,streaming,stopped,failed,awaiting_approval,waiting,awaiting_user message.steps- What the Agent did, in order.
message.steps[].category- What kind of call it is, for a summary like "Created 2 launches, ran a search": from what the tool does (adds, changes, reads, lists, searches),
mcpfor another Pluto product (server). Absent for narration and thinking, and on older steps.One ofwrite,edit,read,list,search,mcp,other message.steps[].detail- Error, reasoning or narration text; a search's query; a read page's URL.
message.steps[].entities- What it touched.
message.steps[].entities[].id- ID.
message.steps[].entities[].kind- Kind.One of
launch,adSet,ad message.steps[].entities[].launchId- Its launch.
message.steps[].entities[].name- Name.
message.steps[].finishedAt- Finished.
message.steps[].id- Step.
message.steps[].kind- A tool call, narration before tools, summarized reasoning, a web search (
detailis the query) or a web page read (detailis its URL).One oftool,note,thinking,search,fetch message.steps[].label- Present tense while running, past tense when done.
message.steps[].server- The Pluto product an
mcpstep used, e.g.Pluto Profit. message.steps[].startedAt- Started.
message.steps[].status- State.One of
running,done,failed,awaiting_approval,rejected,stopped message.steps[].tool- The MCP tool; null for every kind but
tool. message.text- The question, or the answer (markdown;
pluto:links name launches, ad sets and ads). message.version- Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
message.versions- How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
message.workedMs- Active time, excluding waits for approval.
messageId- The Agent message a delta belongs to.
partpart.answerquestion: the answer once given (a choice's label, or the words of your reply).part.choiceIdquestion: the choice it was answered with.part.choicesquestion: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).part.columnstable: its columns.part.data- Every kind but
comboandtable: the series. part.description- One line under the title: the period, the unit.
part.groupscombo: its groups.part.id- The part; the same ID again replaces it.
part.itemsads: the ads, in the order shown.part.kind- How it's drawn;
tableis a table.One ofline,bar,horizontal-bar,stacked-bar,stacked-area,donut,funnel,combo,simple-bar,simple-normalized,spark-line,spark-bar,table part.optionsselection: the options (POST /agent/chats/{id}/parts/{part_id}/select).part.periodads: the days of itsmetrics:since,untilandpreset(last_30_days, …, or null).part.proposedselection: the options the Agent recommends, checked at first.part.rowstable: its rows.part.selectedselection: the options you confirmed.part.showLegend- Whether a legend shows; absent: for two or more series.
part.sizesimple-normalizedonly.One ofsmall,medium,largepart.textquestion: the question.text: the words (Markdown).part.title- What it shows.
part.type- A chart or a table, a question the Agent asks, options it proposes, ads it shows as cards, or the answer's words written before the card that follows them.One of
chart,question,selection,ads,text part.valueFormat- How values read:
style(decimal,percentwith values as percentages,currencywithcurrency),notation,minimumFractionDigits,maximumFractionDigits,unit. part.xAxislabel,hide.part.yAxislabel,integersOnly.reasonerrorwith spend_limit: which limit stopped it (member_limit, workspace_limit or trial_cap); with payment_required: why there's no access.retryableerror: whether retrying can help.sourcessourcesevents: the answer's web pages so far.sources[].site- The hostname without
www.. sources[].title- Its title (its site when it named none).
sources[].url- The page.
stallstall: why the answer seems stuck, decided from the stream:no_first_byte(the model sent nothing for 10 s),silent_stream(an open stream sent no event for 15 s) orsilent_tool(a tool reported nothing for 45 s), andsince, when the silence began (epoch milliseconds);nullonce it moves again.stall.kind- What went quiet.One of
no_first_byte,silent_stream,silent_tool stall.since- When the silence began, epoch milliseconds.
stepstep.category- What kind of call it is, for a summary like "Created 2 launches, ran a search": from what the tool does (adds, changes, reads, lists, searches),
mcpfor another Pluto product (server). Absent for narration and thinking, and on older steps.One ofwrite,edit,read,list,search,mcp,other step.detail- Error, reasoning or narration text; a search's query; a read page's URL.
step.entities- What it touched.
step.entities[].id- ID.
step.entities[].kind- Kind.One of
launch,adSet,ad step.entities[].launchId- Its launch.
step.entities[].name- Name.
step.finishedAt- Finished.
step.id- Step.
step.kind- A tool call, narration before tools, summarized reasoning, a web search (
detailis the query) or a web page read (detailis its URL).One oftool,note,thinking,search,fetch step.label- Present tense while running, past tense when done.
step.server- The Pluto product an
mcpstep used, e.g.Pluto Profit. step.startedAt- Started.
step.status- State.One of
running,done,failed,awaiting_approval,rejected,stopped step.tool- The MCP tool; null for every kind but
tool. stepId- The thinking step a delta belongs to.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them. - 503The Agent isn't set up.
curl -X POST "$PLUTO_API/agent/chats/26926918-2839-4fc9-87f3-3707d4b8e0d7/parts/18a92ec9-6a9d-4373-9553-b4a8d78414ef/answer" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 96fb4366-3e5f-432e-bb00-79c15434caf7" \
-H "Content-Type: application/json" \
-d '{
"choiceId": "8fd5d64b-8716-4538-a03f-7e80286efa98"
}'Confirm the Agent's selection
Confirms exactly these options of the selection the chat's last answer proposed (a selection part, part_id its id, while the answer is awaiting_user); none is a choice too. Their names become your next message (the Agent reads their IDs), the part records them (selected), and the Agent continues; it acts on them only through its usual tools and approvals. 409 when the selection isn't open any more; 422 for an option it doesn't have. Answers with server-sent events like sending a message.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The chat's ID. |
part_id | string | Required | The part's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
optionIds- The
options[].idyou keep, up to 100.
Response
approvalapproval.canApprove- The viewer can approve it: the same as
canDecide. approval.canDecide- The viewer may approve or decline it: they hold
capability, and it's theirs to decide (the person the Agent proposed it for, or an organization owner or admin). approval.capability- What approving or declining it needs, as a capability ID (
ads:publish): the capability of the tool it runs, or of what its call asked for beyond it (a copy made at the platform). Someone without it never decides it, the person who asked included. approval.chatId- Chat.
approval.createdAt- Proposed.
approval.decidedAt- Decided.
approval.effectapproval.effect.done- The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approval.effect.entities- What it changes.
approval.effect.entities[].id- ID.
approval.effect.entities[].kind- Kind.One of
launch,adSet,ad approval.effect.entities[].launchId- Its launch.
approval.effect.entities[].name- Name.
approval.effect.lines- Human details, never field names or IDs.
approval.effect.lines[].label- A human label, e.g. Trigger.
approval.effect.lines[].value- Its value, e.g. New comment.
approval.effect.money- Amounts it spends or sets.
approval.effect.money[].amount- A decimal amount; never a float.
approval.effect.money[].currency- ISO 4217; null when the account's currency isn't known.
approval.effect.money[].label- Label.
approval.effect.subject- What it acts on, one quiet line to show under the title without expanding; absent for most actions. A comment action names the comment: v.i.u.m: “Does this work for small teams?” on App review test.
approval.effect.summary- What it does, in a sentence; empty when that would only repeat
title. approval.effect.title- The action as one sentence with real names, never IDs: Delete loop “Facebook comment moderator”. A tool without its own sentence reads as its title.
approval.effect.warnings- Things to know before approving.
approval.error- Why it failed, or the reason it was declined.
approval.error.code- Stable code.
approval.error.message- For the person.
approval.error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. approval.id- Approval.
approval.messageId- The answer that proposed it.
approval.permission- The coarse permission the call asked with: the action's own (
read,revieworwriteonly when the person chose Ask every time). What deciding needs iscapability.One ofread,review,write,publish,admin,organization approval.result- After approving.
approval.result.jobId- The job it started.
approval.result.summary- What happened.
approval.status- State.One of
pending,approved,rejected,failed,superseded approval.title- What it does, as one sentence with real names and never IDs, e.g. Delete loop “Facebook comment moderator”. The same as
effect.title. approval.tool- The MCP tool it runs.
chatchat.createdAt- Started.
chat.effort- The reasoning effort picked for the chat; null: the model's default.
chat.id- Chat.
chat.lastMessageAt- Last message.
chat.loopId- The loop it is the history of (it made the loop, or was started in its builder).
chat.model- The chat's model:
pluto,autoor a model ID fromGET /agent/models. chat.ownerId- The chat's person: only they rename, delete or share it.
chat.shared- Shared with everyone who can see its loop; false: private to its person.
chat.source- Where it started.One of
page,panel,home,loop chat.status- What it's doing.One of
idle,running,awaiting_approval chat.title- Title; null until the first answer names it.
chat.unread- An answer arrived after the person last read it.
chat.updatedAt- Last change.
codeerror: spend_limit, payment_required, model_unavailable, rate_limited, refusal, max_tokens, step_limit or internal.delta- Text to append.
messagemessage.approvalIds- Approvals raised in this answer.
message.attachments- Files the person attached.
message.attachments[].contentType- A chat file's type.
message.attachments[].fileId- A chat file, uploaded for the message.
message.attachments[].kind- Kind (a media library item is an
imageor avideo).One ofimage,video,pdf,document,spreadsheet,presentation,text,code,audio,archive message.attachments[].mediaId- A media library item.
message.attachments[].name- File name.
message.attachments[].pageCount- Pages of a PDF, Word document or presentation.
message.attachments[].previewUrl- A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
message.attachments[].sizeBytes- A chat file's size.
message.chatId- Chat.
message.completedAt- Finished.
message.createdAt- Written.
message.error- Why the answer failed.
message.error.code- Stable code.
message.error.message- For the person.
message.error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. message.id- Message.
message.model- The model that produced the answer; null for the person's messages.
message.parts- The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
message.parts[].answerquestion: the answer once given (a choice's label, or the words of your reply).message.parts[].choiceIdquestion: the choice it was answered with.message.parts[].choicesquestion: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).message.parts[].columnstable: its columns.message.parts[].data- Every kind but
comboandtable: the series. message.parts[].description- One line under the title: the period, the unit.
message.parts[].groupscombo: its groups.message.parts[].id- The part; the same ID again replaces it.
message.parts[].itemsads: the ads, in the order shown.message.parts[].kind- How it's drawn;
tableis a table.One ofline,bar,horizontal-bar,stacked-bar,stacked-area,donut,funnel,combo,simple-bar,simple-normalized,spark-line,spark-bar,table message.parts[].optionsselection: the options (POST /agent/chats/{id}/parts/{part_id}/select).message.parts[].periodads: the days of itsmetrics:since,untilandpreset(last_30_days, …, or null).message.parts[].proposedselection: the options the Agent recommends, checked at first.message.parts[].rowstable: its rows.message.parts[].selectedselection: the options you confirmed.message.parts[].showLegend- Whether a legend shows; absent: for two or more series.
message.parts[].sizesimple-normalizedonly.One ofsmall,medium,largemessage.parts[].textquestion: the question.text: the words (Markdown).message.parts[].title- What it shows.
message.parts[].type- A chart or a table, a question the Agent asks, options it proposes, ads it shows as cards, or the answer's words written before the card that follows them.One of
chart,question,selection,ads,text message.parts[].valueFormat- How values read:
style(decimal,percentwith values as percentages,currencywithcurrency),notation,minimumFractionDigits,maximumFractionDigits,unit. message.parts[].xAxislabel,hide.message.parts[].yAxislabel,integersOnly.message.role- Who wrote it.One of
user,assistant message.sentBy- Who sent a person's message (only they edit it); null for answers and for older messages, which are the chat's person's.
message.sources- The web pages the answer used: cited pages in the order first cited, then pages it read without citing; each URL once. Empty when it didn't use the web.
message.sources[].site- The hostname without
www.. message.sources[].title- Its title (its site when it named none).
message.sources[].url- The page.
message.status- State:
waitingfor credits;awaiting_userwhen the answer asked a question or proposed a selection (parts) and waits for your reply.One ofcomplete,streaming,stopped,failed,awaiting_approval,waiting,awaiting_user message.steps- What the Agent did, in order.
message.steps[].category- What kind of call it is, for a summary like "Created 2 launches, ran a search": from what the tool does (adds, changes, reads, lists, searches),
mcpfor another Pluto product (server). Absent for narration and thinking, and on older steps.One ofwrite,edit,read,list,search,mcp,other message.steps[].detail- Error, reasoning or narration text; a search's query; a read page's URL.
message.steps[].entities- What it touched.
message.steps[].entities[].id- ID.
message.steps[].entities[].kind- Kind.One of
launch,adSet,ad message.steps[].entities[].launchId- Its launch.
message.steps[].entities[].name- Name.
message.steps[].finishedAt- Finished.
message.steps[].id- Step.
message.steps[].kind- A tool call, narration before tools, summarized reasoning, a web search (
detailis the query) or a web page read (detailis its URL).One oftool,note,thinking,search,fetch message.steps[].label- Present tense while running, past tense when done.
message.steps[].server- The Pluto product an
mcpstep used, e.g.Pluto Profit. message.steps[].startedAt- Started.
message.steps[].status- State.One of
running,done,failed,awaiting_approval,rejected,stopped message.steps[].tool- The MCP tool; null for every kind but
tool. message.text- The question, or the answer (markdown;
pluto:links name launches, ad sets and ads). message.version- Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
message.versions- How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
message.workedMs- Active time, excluding waits for approval.
messageId- The Agent message a delta belongs to.
partpart.answerquestion: the answer once given (a choice's label, or the words of your reply).part.choiceIdquestion: the choice it was answered with.part.choicesquestion: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).part.columnstable: its columns.part.data- Every kind but
comboandtable: the series. part.description- One line under the title: the period, the unit.
part.groupscombo: its groups.part.id- The part; the same ID again replaces it.
part.itemsads: the ads, in the order shown.part.kind- How it's drawn;
tableis a table.One ofline,bar,horizontal-bar,stacked-bar,stacked-area,donut,funnel,combo,simple-bar,simple-normalized,spark-line,spark-bar,table part.optionsselection: the options (POST /agent/chats/{id}/parts/{part_id}/select).part.periodads: the days of itsmetrics:since,untilandpreset(last_30_days, …, or null).part.proposedselection: the options the Agent recommends, checked at first.part.rowstable: its rows.part.selectedselection: the options you confirmed.part.showLegend- Whether a legend shows; absent: for two or more series.
part.sizesimple-normalizedonly.One ofsmall,medium,largepart.textquestion: the question.text: the words (Markdown).part.title- What it shows.
part.type- A chart or a table, a question the Agent asks, options it proposes, ads it shows as cards, or the answer's words written before the card that follows them.One of
chart,question,selection,ads,text part.valueFormat- How values read:
style(decimal,percentwith values as percentages,currencywithcurrency),notation,minimumFractionDigits,maximumFractionDigits,unit. part.xAxislabel,hide.part.yAxislabel,integersOnly.reasonerrorwith spend_limit: which limit stopped it (member_limit, workspace_limit or trial_cap); with payment_required: why there's no access.retryableerror: whether retrying can help.sourcessourcesevents: the answer's web pages so far.sources[].site- The hostname without
www.. sources[].title- Its title (its site when it named none).
sources[].url- The page.
stallstall: why the answer seems stuck, decided from the stream:no_first_byte(the model sent nothing for 10 s),silent_stream(an open stream sent no event for 15 s) orsilent_tool(a tool reported nothing for 45 s), andsince, when the silence began (epoch milliseconds);nullonce it moves again.stall.kind- What went quiet.One of
no_first_byte,silent_stream,silent_tool stall.since- When the silence began, epoch milliseconds.
stepstep.category- What kind of call it is, for a summary like "Created 2 launches, ran a search": from what the tool does (adds, changes, reads, lists, searches),
mcpfor another Pluto product (server). Absent for narration and thinking, and on older steps.One ofwrite,edit,read,list,search,mcp,other step.detail- Error, reasoning or narration text; a search's query; a read page's URL.
step.entities- What it touched.
step.entities[].id- ID.
step.entities[].kind- Kind.One of
launch,adSet,ad step.entities[].launchId- Its launch.
step.entities[].name- Name.
step.finishedAt- Finished.
step.id- Step.
step.kind- A tool call, narration before tools, summarized reasoning, a web search (
detailis the query) or a web page read (detailis its URL).One oftool,note,thinking,search,fetch step.label- Present tense while running, past tense when done.
step.server- The Pluto product an
mcpstep used, e.g.Pluto Profit. step.startedAt- Started.
step.status- State.One of
running,done,failed,awaiting_approval,rejected,stopped step.tool- The MCP tool; null for every kind but
tool. stepId- The thinking step a delta belongs to.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them. - 503The Agent isn't set up.
curl -X POST "$PLUTO_API/agent/chats/26926918-2839-4fc9-87f3-3707d4b8e0d7/parts/18a92ec9-6a9d-4373-9553-b4a8d78414ef/select" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 7c9c496e-d579-449a-90a0-f57cab601ed5" \
-H "Content-Type: application/json" \
-d '{
"optionIds": [
"fa4dc520-f9a2-4434-9cbc-29811f2c5175"
]
}'Mark a chat read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The chat's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
Done; no content.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/agent/chats/26926918-2839-4fc9-87f3-3707d4b8e0d7/read" \
-H "Authorization: Bearer $PLUTO_KEY"Retry a failed or stopped answer
Runs the last failed or stopped answer again. Send { "model": ..., "effort": ... } to run it on another model (the chat keeps it from then on), or no body for the chat's own. Answers with server-sent events like sending a message (chat, message, text, step, approval, error, done).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The chat's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
approvalapproval.canApprove- The viewer can approve it: the same as
canDecide. approval.canDecide- The viewer may approve or decline it: they hold
capability, and it's theirs to decide (the person the Agent proposed it for, or an organization owner or admin). approval.capability- What approving or declining it needs, as a capability ID (
ads:publish): the capability of the tool it runs, or of what its call asked for beyond it (a copy made at the platform). Someone without it never decides it, the person who asked included. approval.chatId- Chat.
approval.createdAt- Proposed.
approval.decidedAt- Decided.
approval.effectapproval.effect.done- The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approval.effect.entities- What it changes.
approval.effect.entities[].id- ID.
approval.effect.entities[].kind- Kind.One of
launch,adSet,ad approval.effect.entities[].launchId- Its launch.
approval.effect.entities[].name- Name.
approval.effect.lines- Human details, never field names or IDs.
approval.effect.lines[].label- A human label, e.g. Trigger.
approval.effect.lines[].value- Its value, e.g. New comment.
approval.effect.money- Amounts it spends or sets.
approval.effect.money[].amount- A decimal amount; never a float.
approval.effect.money[].currency- ISO 4217; null when the account's currency isn't known.
approval.effect.money[].label- Label.
approval.effect.subject- What it acts on, one quiet line to show under the title without expanding; absent for most actions. A comment action names the comment: v.i.u.m: “Does this work for small teams?” on App review test.
approval.effect.summary- What it does, in a sentence; empty when that would only repeat
title. approval.effect.title- The action as one sentence with real names, never IDs: Delete loop “Facebook comment moderator”. A tool without its own sentence reads as its title.
approval.effect.warnings- Things to know before approving.
approval.error- Why it failed, or the reason it was declined.
approval.error.code- Stable code.
approval.error.message- For the person.
approval.error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. approval.id- Approval.
approval.messageId- The answer that proposed it.
approval.permission- The coarse permission the call asked with: the action's own (
read,revieworwriteonly when the person chose Ask every time). What deciding needs iscapability.One ofread,review,write,publish,admin,organization approval.result- After approving.
approval.result.jobId- The job it started.
approval.result.summary- What happened.
approval.status- State.One of
pending,approved,rejected,failed,superseded approval.title- What it does, as one sentence with real names and never IDs, e.g. Delete loop “Facebook comment moderator”. The same as
effect.title. approval.tool- The MCP tool it runs.
chatchat.createdAt- Started.
chat.effort- The reasoning effort picked for the chat; null: the model's default.
chat.id- Chat.
chat.lastMessageAt- Last message.
chat.loopId- The loop it is the history of (it made the loop, or was started in its builder).
chat.model- The chat's model:
pluto,autoor a model ID fromGET /agent/models. chat.ownerId- The chat's person: only they rename, delete or share it.
chat.shared- Shared with everyone who can see its loop; false: private to its person.
chat.source- Where it started.One of
page,panel,home,loop chat.status- What it's doing.One of
idle,running,awaiting_approval chat.title- Title; null until the first answer names it.
chat.unread- An answer arrived after the person last read it.
chat.updatedAt- Last change.
codeerror: spend_limit, payment_required, model_unavailable, rate_limited, refusal, max_tokens, step_limit or internal.delta- Text to append.
messagemessage.approvalIds- Approvals raised in this answer.
message.attachments- Files the person attached.
message.attachments[].contentType- A chat file's type.
message.attachments[].fileId- A chat file, uploaded for the message.
message.attachments[].kind- Kind (a media library item is an
imageor avideo).One ofimage,video,pdf,document,spreadsheet,presentation,text,code,audio,archive message.attachments[].mediaId- A media library item.
message.attachments[].name- File name.
message.attachments[].pageCount- Pages of a PDF, Word document or presentation.
message.attachments[].previewUrl- A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
message.attachments[].sizeBytes- A chat file's size.
message.chatId- Chat.
message.completedAt- Finished.
message.createdAt- Written.
message.error- Why the answer failed.
message.error.code- Stable code.
message.error.message- For the person.
message.error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. message.id- Message.
message.model- The model that produced the answer; null for the person's messages.
message.parts- The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
message.parts[].answerquestion: the answer once given (a choice's label, or the words of your reply).message.parts[].choiceIdquestion: the choice it was answered with.message.parts[].choicesquestion: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).message.parts[].columnstable: its columns.message.parts[].data- Every kind but
comboandtable: the series. message.parts[].description- One line under the title: the period, the unit.
message.parts[].groupscombo: its groups.message.parts[].id- The part; the same ID again replaces it.
message.parts[].itemsads: the ads, in the order shown.message.parts[].kind- How it's drawn;
tableis a table.One ofline,bar,horizontal-bar,stacked-bar,stacked-area,donut,funnel,combo,simple-bar,simple-normalized,spark-line,spark-bar,table message.parts[].optionsselection: the options (POST /agent/chats/{id}/parts/{part_id}/select).message.parts[].periodads: the days of itsmetrics:since,untilandpreset(last_30_days, …, or null).message.parts[].proposedselection: the options the Agent recommends, checked at first.message.parts[].rowstable: its rows.message.parts[].selectedselection: the options you confirmed.message.parts[].showLegend- Whether a legend shows; absent: for two or more series.
message.parts[].sizesimple-normalizedonly.One ofsmall,medium,largemessage.parts[].textquestion: the question.text: the words (Markdown).message.parts[].title- What it shows.
message.parts[].type- A chart or a table, a question the Agent asks, options it proposes, ads it shows as cards, or the answer's words written before the card that follows them.One of
chart,question,selection,ads,text message.parts[].valueFormat- How values read:
style(decimal,percentwith values as percentages,currencywithcurrency),notation,minimumFractionDigits,maximumFractionDigits,unit. message.parts[].xAxislabel,hide.message.parts[].yAxislabel,integersOnly.message.role- Who wrote it.One of
user,assistant message.sentBy- Who sent a person's message (only they edit it); null for answers and for older messages, which are the chat's person's.
message.sources- The web pages the answer used: cited pages in the order first cited, then pages it read without citing; each URL once. Empty when it didn't use the web.
message.sources[].site- The hostname without
www.. message.sources[].title- Its title (its site when it named none).
message.sources[].url- The page.
message.status- State:
waitingfor credits;awaiting_userwhen the answer asked a question or proposed a selection (parts) and waits for your reply.One ofcomplete,streaming,stopped,failed,awaiting_approval,waiting,awaiting_user message.steps- What the Agent did, in order.
message.steps[].category- What kind of call it is, for a summary like "Created 2 launches, ran a search": from what the tool does (adds, changes, reads, lists, searches),
mcpfor another Pluto product (server). Absent for narration and thinking, and on older steps.One ofwrite,edit,read,list,search,mcp,other message.steps[].detail- Error, reasoning or narration text; a search's query; a read page's URL.
message.steps[].entities- What it touched.
message.steps[].entities[].id- ID.
message.steps[].entities[].kind- Kind.One of
launch,adSet,ad message.steps[].entities[].launchId- Its launch.
message.steps[].entities[].name- Name.
message.steps[].finishedAt- Finished.
message.steps[].id- Step.
message.steps[].kind- A tool call, narration before tools, summarized reasoning, a web search (
detailis the query) or a web page read (detailis its URL).One oftool,note,thinking,search,fetch message.steps[].label- Present tense while running, past tense when done.
message.steps[].server- The Pluto product an
mcpstep used, e.g.Pluto Profit. message.steps[].startedAt- Started.
message.steps[].status- State.One of
running,done,failed,awaiting_approval,rejected,stopped message.steps[].tool- The MCP tool; null for every kind but
tool. message.text- The question, or the answer (markdown;
pluto:links name launches, ad sets and ads). message.version- Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
message.versions- How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
message.workedMs- Active time, excluding waits for approval.
messageId- The Agent message a delta belongs to.
partpart.answerquestion: the answer once given (a choice's label, or the words of your reply).part.choiceIdquestion: the choice it was answered with.part.choicesquestion: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).part.columnstable: its columns.part.data- Every kind but
comboandtable: the series. part.description- One line under the title: the period, the unit.
part.groupscombo: its groups.part.id- The part; the same ID again replaces it.
part.itemsads: the ads, in the order shown.part.kind- How it's drawn;
tableis a table.One ofline,bar,horizontal-bar,stacked-bar,stacked-area,donut,funnel,combo,simple-bar,simple-normalized,spark-line,spark-bar,table part.optionsselection: the options (POST /agent/chats/{id}/parts/{part_id}/select).part.periodads: the days of itsmetrics:since,untilandpreset(last_30_days, …, or null).part.proposedselection: the options the Agent recommends, checked at first.part.rowstable: its rows.part.selectedselection: the options you confirmed.part.showLegend- Whether a legend shows; absent: for two or more series.
part.sizesimple-normalizedonly.One ofsmall,medium,largepart.textquestion: the question.text: the words (Markdown).part.title- What it shows.
part.type- A chart or a table, a question the Agent asks, options it proposes, ads it shows as cards, or the answer's words written before the card that follows them.One of
chart,question,selection,ads,text part.valueFormat- How values read:
style(decimal,percentwith values as percentages,currencywithcurrency),notation,minimumFractionDigits,maximumFractionDigits,unit. part.xAxislabel,hide.part.yAxislabel,integersOnly.reasonerrorwith spend_limit: which limit stopped it (member_limit, workspace_limit or trial_cap); with payment_required: why there's no access.retryableerror: whether retrying can help.sourcessourcesevents: the answer's web pages so far.sources[].site- The hostname without
www.. sources[].title- Its title (its site when it named none).
sources[].url- The page.
stallstall: why the answer seems stuck, decided from the stream:no_first_byte(the model sent nothing for 10 s),silent_stream(an open stream sent no event for 15 s) orsilent_tool(a tool reported nothing for 45 s), andsince, when the silence began (epoch milliseconds);nullonce it moves again.stall.kind- What went quiet.One of
no_first_byte,silent_stream,silent_tool stall.since- When the silence began, epoch milliseconds.
stepstep.category- What kind of call it is, for a summary like "Created 2 launches, ran a search": from what the tool does (adds, changes, reads, lists, searches),
mcpfor another Pluto product (server). Absent for narration and thinking, and on older steps.One ofwrite,edit,read,list,search,mcp,other step.detail- Error, reasoning or narration text; a search's query; a read page's URL.
step.entities- What it touched.
step.entities[].id- ID.
step.entities[].kind- Kind.One of
launch,adSet,ad step.entities[].launchId- Its launch.
step.entities[].name- Name.
step.finishedAt- Finished.
step.id- Step.
step.kind- A tool call, narration before tools, summarized reasoning, a web search (
detailis the query) or a web page read (detailis its URL).One oftool,note,thinking,search,fetch step.label- Present tense while running, past tense when done.
step.server- The Pluto product an
mcpstep used, e.g.Pluto Profit. step.startedAt- Started.
step.status- State.One of
running,done,failed,awaiting_approval,rejected,stopped step.tool- The MCP tool; null for every kind but
tool. stepId- The thinking step a delta belongs to.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them. - 503The Agent isn't set up.
curl -X POST "$PLUTO_API/agent/chats/26926918-2839-4fc9-87f3-3707d4b8e0d7/retry" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: e95c702c-0cb5-4f48-bafb-2b17c006c779"Stop a running answer
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The chat's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
createdAt- Started.
effort- The reasoning effort picked for the chat; null: the model's default.
id- Chat.
lastMessageAt- Last message.
loopId- The loop it is the history of (it made the loop, or was started in its builder).
model- The chat's model:
pluto,autoor a model ID fromGET /agent/models. ownerId- The chat's person: only they rename, delete or share it.
shared- Shared with everyone who can see its loop; false: private to its person.
source- Where it started.One of
page,panel,home,loop status- What it's doing.One of
idle,running,awaiting_approval title- Title; null until the first answer names it.
unread- An answer arrived after the person last read it.
updatedAt- Last change.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/agent/chats/26926918-2839-4fc9-87f3-3707d4b8e0d7/stop" \
-H "Authorization: Bearer $PLUTO_KEY"Get your Agent guidance
Personal instructions and context the Agent follows when it answers you, in chats you start in this workspace. version 0 and empty text before the first save. Also in MCP as get_agent_guidance. Yours only: the signed-in person's, or the person a connected agent or agent client acts for, in this workspace. API keys and M2M clients without a person get 403; another person's skill is 404. Not for guests.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
text- The guidance; empty when there's none. Up to 4,000 characters.
updatedAt- Last saved; null before the first save.
version- Send it back as
expectedVersion; 0 before the first save.
curl "$PLUTO_API/agent/guidance" \
-H "Authorization: Bearer $PLUTO_KEY"Set your Agent guidance
Replaces your guidance (up to 4,000 characters; empty clears it). It goes into chats you start from now on, below the Agent's own rules: it never grants permissions or skips an approval. Loops and a loop's shared chat never read it. With expectedVersion, a newer save is a 409 with current; without, it replaces what's saved. Also in MCP as set_agent_guidance. Yours only: the signed-in person's, or the person a connected agent or agent client acts for, in this workspace. API keys and M2M clients without a person get 403; another person's skill is 404. Not for guests.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
text- The whole guidance; empty clears it.
Response
text- The guidance; empty when there's none. Up to 4,000 characters.
updatedAt- Last saved; null before the first save.
version- Send it back as
expectedVersion; 0 before the first save.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PUT "$PLUTO_API/agent/guidance" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 5f0500b5-6df3-4f90-afd3-3e90ca0600af" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3,
"text": "Can we try the 4x5 cut for Instagram feed before we publish?"
}'List Agent memory
What the in-app Agent remembers for you and for the whole workspace: typed entries (preference, rule, fact, reference), rules first, then newest first. Every chat's prompt lists their titles and descriptions; the Agent reads a body when the entry matters. A rule's limits are enforced by Pluto. query searches titles, descriptions and bodies (every word must match). A credential without a person (an API key) sees the workspace's entries only. Also in MCP as list_agent_memories.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
query | string | Optional | Words to search for. |
type | string | Optional | Only preference, rule, fact or reference entries. |
scope | string | Optional | Only personal (yours) or workspace entries. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- Entries, rules first, then newest first.
items[].body- Details and why (up to 4,000 characters); the Agent reads it when the entry matters.
items[].canEdit- The caller may change or delete it.
items[].createdAt- Saved.
items[].createdBy- Who saved it.
items[].description- The one line the Agent recalls it by, in every chat's prompt (up to 200 characters).
items[].id- The entry.
items[].limits- A rule's limits, enforced by Pluto.
budgetIncrease: the largest budget or bid raise the Agent makes without asking (percent, and/oramountper change, per day for daily budgets, with itscurrency; decimal strings).askBefore: actions that always ask first. items[].limits.askBeforeitems[].limits.budgetIncreaseitems[].limits.budgetIncrease.amountitems[].limits.budgetIncrease.currencyitems[].limits.budgetIncrease.percentitems[].scope- The person's own, or the workspace's (every member's chats).One of
personal,workspace items[].source- Where it came from:
kindischat(saved from an Agent chat, withchatIdandmessageId),settings,apiormcp. items[].source.chatIditems[].source.kind- One of
chat,settings,api,mcp items[].source.messageIditems[].title- A few words (up to 80 characters).
items[].type- preference, rule, fact or reference.One of
preference,rule,fact,reference items[].updatedAt- Last changed.
items[].version- Send it back as
expectedVersion.
curl "$PLUTO_API/agent/memories" \
-H "Authorization: Bearer $PLUTO_KEY"Create a memory entry
One thing for the Agent to remember in later chats: a short title, the one-line description it's recalled by, details in body. scope: workspace is for everyone (owners and admins; 403 otherwise); otherwise it's yours. A title already remembered in that scope is a 422 on title: update that entry instead. A rule's limits are enforced: budgetIncrease makes a larger budget or bid raise ask first, even with Run everything (and in loops, for workspace rules); askBefore makes those actions always ask. Up to 200 entries each. Also in MCP as create_agent_memory.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
body- Details and why.
description- The one line the Agent recalls it by, without tags.
limits- A rule's limits, enforced by Pluto.
budgetIncrease: the largest budget or bid raise the Agent makes without asking (percent, and/oramountper change, per day for daily budgets, with itscurrency; decimal strings).askBefore: actions that always ask first. limits.askBeforelimits.budgetIncreaselimits.budgetIncrease.amountlimits.budgetIncrease.currencylimits.budgetIncrease.percentscopepersonal(the default) orworkspace.One ofpersonal,workspacetitle- A few words; unique in its scope.
type- preference, rule, fact or reference.One of
preference,rule,fact,reference
Response
body- Details and why (up to 4,000 characters); the Agent reads it when the entry matters.
canEdit- The caller may change or delete it.
createdAt- Saved.
createdBy- Who saved it.
description- The one line the Agent recalls it by, in every chat's prompt (up to 200 characters).
id- The entry.
limits- A rule's limits, enforced by Pluto.
budgetIncrease: the largest budget or bid raise the Agent makes without asking (percent, and/oramountper change, per day for daily budgets, with itscurrency; decimal strings).askBefore: actions that always ask first. limits.askBeforelimits.budgetIncreaselimits.budgetIncrease.amountlimits.budgetIncrease.currencylimits.budgetIncrease.percentscope- The person's own, or the workspace's (every member's chats).One of
personal,workspace source- Where it came from:
kindischat(saved from an Agent chat, withchatIdandmessageId),settings,apiormcp. source.chatIdsource.kind- One of
chat,settings,api,mcp source.messageIdtitle- A few words (up to 80 characters).
type- preference, rule, fact or reference.One of
preference,rule,fact,reference updatedAt- Last changed.
version- Send it back as
expectedVersion.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/agent/memories" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: d30fed13-857e-42f3-98dc-96daa363438e" \
-H "Content-Type: application/json" \
-d '{
"body": "Can we try the 4x5 cut for Instagram feed before we publish?",
"description": "Two drops every morning for brighter, even skin.",
"limits": {
"askBefore": [
"publishing"
],
"budgetIncrease": {
"amount": "150.00",
"currency": "USD",
"percent": "20"
}
},
"scope": "personal",
"title": "Vitamin C Serum, UGC 9x16",
"type": "preference"
}'Get a memory entry
Yours or the workspace's; another person's entry is 404. Also in MCP as get_agent_memory.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The memory's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
body- Details and why (up to 4,000 characters); the Agent reads it when the entry matters.
canEdit- The caller may change or delete it.
createdAt- Saved.
createdBy- Who saved it.
description- The one line the Agent recalls it by, in every chat's prompt (up to 200 characters).
id- The entry.
limits- A rule's limits, enforced by Pluto.
budgetIncrease: the largest budget or bid raise the Agent makes without asking (percent, and/oramountper change, per day for daily budgets, with itscurrency; decimal strings).askBefore: actions that always ask first. limits.askBeforelimits.budgetIncreaselimits.budgetIncrease.amountlimits.budgetIncrease.currencylimits.budgetIncrease.percentscope- The person's own, or the workspace's (every member's chats).One of
personal,workspace source- Where it came from:
kindischat(saved from an Agent chat, withchatIdandmessageId),settings,apiormcp. source.chatIdsource.kind- One of
chat,settings,api,mcp source.messageIdtitle- A few words (up to 80 characters).
type- preference, rule, fact or reference.One of
preference,rule,fact,reference updatedAt- Last changed.
version- Send it back as
expectedVersion.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/agent/memories/209308fc-b21f-4892-97a7-9ee2933a518b" \
-H "Authorization: Bearer $PLUTO_KEY"Change a memory entry
Any of type, title, description, body and limits (null makes a rule guidance only). Yours to change; the workspace's for owners and admins. A stale expectedVersion is a 409 with current. Also in MCP as update_agent_memory.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The memory's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
body- Details and why.
description- The one line the Agent recalls it by, without tags.
expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
limits- A rule's limits, enforced by Pluto.
budgetIncrease: the largest budget or bid raise the Agent makes without asking (percent, and/oramountper change, per day for daily budgets, with itscurrency; decimal strings).askBefore: actions that always ask first. limits.askBeforelimits.budgetIncreaselimits.budgetIncrease.amountlimits.budgetIncrease.currencylimits.budgetIncrease.percenttitle- A few words; unique in its scope.
type- preference, rule, fact or reference.One of
preference,rule,fact,reference
Response
body- Details and why (up to 4,000 characters); the Agent reads it when the entry matters.
canEdit- The caller may change or delete it.
createdAt- Saved.
createdBy- Who saved it.
description- The one line the Agent recalls it by, in every chat's prompt (up to 200 characters).
id- The entry.
limits- A rule's limits, enforced by Pluto.
budgetIncrease: the largest budget or bid raise the Agent makes without asking (percent, and/oramountper change, per day for daily budgets, with itscurrency; decimal strings).askBefore: actions that always ask first. limits.askBeforelimits.budgetIncreaselimits.budgetIncrease.amountlimits.budgetIncrease.currencylimits.budgetIncrease.percentscope- The person's own, or the workspace's (every member's chats).One of
personal,workspace source- Where it came from:
kindischat(saved from an Agent chat, withchatIdandmessageId),settings,apiormcp. source.chatIdsource.kind- One of
chat,settings,api,mcp source.messageIdtitle- A few words (up to 80 characters).
type- preference, rule, fact or reference.One of
preference,rule,fact,reference updatedAt- Last changed.
version- Send it back as
expectedVersion.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/agent/memories/209308fc-b21f-4892-97a7-9ee2933a518b" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: ffb6aae1-a7f0-407f-b9b6-7c7cf981a4dc" \
-H "Content-Type: application/json" \
-d '{
"body": "Can we try the 4x5 cut for Instagram feed before we publish?",
"description": "Two drops every morning for brighter, even skin.",
"expectedVersion": 3,
"limits": {
"askBefore": [
"publishing"
],
"budgetIncrease": {
"amount": "150.00",
"currency": "USD",
"percent": "20"
}
},
"title": "Vitamin C Serum, UGC 9x16",
"type": "preference"
}'Delete a memory entry
For good. Yours to delete; the workspace's for owners and admins. Also in MCP as delete_agent_memory.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The memory's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
Done; no content.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/agent/memories/209308fc-b21f-4892-97a7-9ee2933a518b" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: bdf565cf-7745-4697-b268-45dd735f8088"List the Agent's models
Models the Agent can run on.
The models the Agent can run on in this workspace, Pluto first, each saying whether it can run now, whether members may pick it and whether it's in the caller's own model picker, with the model a chat without one runs on, the workspace's settings and the caller's picker choices. Pass an id as model when starting or messaging a chat. Also in MCP as list_models.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
defaultModel- What a chat without a model runs on: the caller's last choice, else the first model in their picker; null when no model can run.
models- Every model offered, Pluto first, then
auto, then grouped by provider. models[].aliases- Family words search matches (
pluto,sonnet,gpt, ...). models[].allowed- Members may pick it (Settings, Agent).
models[].available- It can run now; false while its provider isn't set up yet.
models[].contextWindow- Tokens of context; null for Pluto and
auto. models[].defaultEffort- The effort used when none is picked.
models[].efforts- Reasoning effort levels it accepts; empty: none to pick.
models[].hint- One line: what it's good at.
models[].idpluto,autoor a model ID, e.g.pluto.models[].name- Display name.
models[].older- A previous generation, still served.
models[].preview- Preview at the provider.
models[].provider- Null for Pluto and
auto.One ofanthropic,openai,xai models[].providerName- Anthropic, OpenAI or xAI; null for Pluto and
auto. models[].recommended- In the recommended set people see until they choose otherwise.
models[].retention- How long the provider keeps requests when longer than usual (e.g.
30d); null for Pluto. models[].streaming- Streams its answer.
models[].tools- Uses tools.
models[].usOnly- How requests stay in the US.
models[].visible- In the caller's own model picker.
recent- The viewer's last models (up to 3, newest first), only ones they may pick.
settingssettings.allowedModels- Null: every model that can run.
settings.canEdit- The viewer is an owner or admin.
settings.updatedAt- Last saved.
settings.version- 0 until first saved.
visibilityvisibility.hidden- Recommended models turned off.
visibility.shown- Turned on beyond the recommended set.
curl "$PLUTO_API/agent/models" \
-H "Authorization: Bearer $PLUTO_KEY"Set the workspace's models
Owners and admins: the models members may pick. expectedVersion is settings.version; a newer save answers 409 with current. Also in MCP as update_model_settings.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
allowedModels- Model IDs (and
auto) members may pick; null allows every model that can run. expectedVersionsettings.versionthe change is based on (0 before the first save).
Response
defaultModel- What a chat without a model runs on: the caller's last choice, else the first model in their picker; null when no model can run.
models- Every model offered, Pluto first, then
auto, then grouped by provider. models[].aliases- Family words search matches (
pluto,sonnet,gpt, ...). models[].allowed- Members may pick it (Settings, Agent).
models[].available- It can run now; false while its provider isn't set up yet.
models[].contextWindow- Tokens of context; null for Pluto and
auto. models[].defaultEffort- The effort used when none is picked.
models[].efforts- Reasoning effort levels it accepts; empty: none to pick.
models[].hint- One line: what it's good at.
models[].idpluto,autoor a model ID, e.g.pluto.models[].name- Display name.
models[].older- A previous generation, still served.
models[].preview- Preview at the provider.
models[].provider- Null for Pluto and
auto.One ofanthropic,openai,xai models[].providerName- Anthropic, OpenAI or xAI; null for Pluto and
auto. models[].recommended- In the recommended set people see until they choose otherwise.
models[].retention- How long the provider keeps requests when longer than usual (e.g.
30d); null for Pluto. models[].streaming- Streams its answer.
models[].tools- Uses tools.
models[].usOnly- How requests stay in the US.
models[].visible- In the caller's own model picker.
recent- The viewer's last models (up to 3, newest first), only ones they may pick.
settingssettings.allowedModels- Null: every model that can run.
settings.canEdit- The viewer is an owner or admin.
settings.updatedAt- Last saved.
settings.version- 0 until first saved.
visibilityvisibility.hidden- Recommended models turned off.
visibility.shown- Turned on beyond the recommended set.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PUT "$PLUTO_API/agent/models/settings" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: c4e3ef49-b308-48c9-bc77-0348c089443c" \
-H "Content-Type: application/json" \
-d '{
"allowedModels": [
"pluto"
],
"expectedVersion": 3
}'Choose the models in your picker
The caller's own model picker (Settings, Models): shown lists models turned on beyond the recommended set, hidden the recommended ones turned off; both replace what was saved, and empty lists go back to the recommended set. At least one model the caller may pick stays on (422 otherwise). People only (an API key without a person gets 422). The workspace's allowed models still decide what may be picked. Also in MCP as update_model_visibility.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
hidden- Recommended models to hide.
shown- Models to show although not recommended.
Response
defaultModel- What a chat without a model runs on: the caller's last choice, else the first model in their picker; null when no model can run.
models- Every model offered, Pluto first, then
auto, then grouped by provider. models[].aliases- Family words search matches (
pluto,sonnet,gpt, ...). models[].allowed- Members may pick it (Settings, Agent).
models[].available- It can run now; false while its provider isn't set up yet.
models[].contextWindow- Tokens of context; null for Pluto and
auto. models[].defaultEffort- The effort used when none is picked.
models[].efforts- Reasoning effort levels it accepts; empty: none to pick.
models[].hint- One line: what it's good at.
models[].idpluto,autoor a model ID, e.g.pluto.models[].name- Display name.
models[].older- A previous generation, still served.
models[].preview- Preview at the provider.
models[].provider- Null for Pluto and
auto.One ofanthropic,openai,xai models[].providerName- Anthropic, OpenAI or xAI; null for Pluto and
auto. models[].recommended- In the recommended set people see until they choose otherwise.
models[].retention- How long the provider keeps requests when longer than usual (e.g.
30d); null for Pluto. models[].streaming- Streams its answer.
models[].tools- Uses tools.
models[].usOnly- How requests stay in the US.
models[].visible- In the caller's own model picker.
recent- The viewer's last models (up to 3, newest first), only ones they may pick.
settingssettings.allowedModels- Null: every model that can run.
settings.canEdit- The viewer is an owner or admin.
settings.updatedAt- Last saved.
settings.version- 0 until first saved.
visibilityvisibility.hidden- Recommended models turned off.
visibility.shown- Turned on beyond the recommended set.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PUT "$PLUTO_API/agent/models/visibility" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 72551d0a-fc53-4b7e-b289-677f79b7c229" \
-H "Content-Type: application/json" \
-d '{
"hidden": [
"Brevanne"
],
"shown": [
"Brevanne"
]
}'List saved scripts
The workspace's saved scripts (Python the Agent wrote in its code sandbox and keeps to reuse), without code, open ones only; with loopId, that loop's and the workspace's. Also in MCP as list_scripts; MCP clients save with save_script.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
loopId | string | Optional | A loop: its scripts and the workspace's. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- The scripts, a loop's first.
items[].createdAt- Created.
items[].createdByKind- person, agent, api_key or system.
items[].id- The script.
items[].inputs- What its
main(inputs)takes and what it returns, prints or writes. items[].languagepython.items[].lastUsedAt- Last loaded to run.
items[].loopId- Its loop; null: the whole workspace's.
items[].name- Its name, unique in its loop (or the workspace).
items[].purpose- What it does and when to use it.
items[].updatedAt- Last saved.
items[].usedCount- Times it was loaded to run.
items[].version- The latest version.
curl "$PLUTO_API/agent/scripts" \
-H "Authorization: Bearer $PLUTO_KEY"Get a saved script
The script with the code of its latest version, or of version, and its versions newest first. Also in MCP as get_script.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The script's ID. |
version | string | Optional | An older version's code. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
code- The code of
shownVersion. createdAt- Created.
createdByKind- person, agent, api_key or system.
id- The script.
inputs- What its
main(inputs)takes and what it returns, prints or writes. languagepython.lastUsedAt- Last loaded to run.
loopId- Its loop; null: the whole workspace's.
name- Its name, unique in its loop (or the workspace).
purpose- What it does and when to use it.
shownVersion- The version
codeis. updatedAt- Last saved.
usedCount- Times it was loaded to run.
version- The latest version.
versions- Every version, newest first.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/agent/scripts/6a496718-0f2e-43d7-a8ea-bd47c1daca6a" \
-H "Authorization: Bearer $PLUTO_KEY"Open a shared chat
What a teammate's link shows: the chat's title, who shared it and when, and its snapshot's messages (100 by default, oldest first; hasEarlier and before page back) with their approvals as they read, decided by nobody here. For a signed-in member of the link's workspace who uses the Agent, while the person who shared it is still a member; anyone else, an unknown or turned-off link included, gets 404.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
token | string | Required | |
before | string | Optional | A message ID: the messages before it. |
limit | string | Optional | 1-200; 100 by default. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
approvals- The approvals these messages carry, as they read.
approvals[].canApprove- The viewer can approve it: the same as
canDecide. approvals[].canDecide- The viewer may approve or decline it: they hold
capability, and it's theirs to decide (the person the Agent proposed it for, or an organization owner or admin). approvals[].capability- What approving or declining it needs, as a capability ID (
ads:publish): the capability of the tool it runs, or of what its call asked for beyond it (a copy made at the platform). Someone without it never decides it, the person who asked included. approvals[].chatId- Chat.
approvals[].createdAt- Proposed.
approvals[].decidedAt- Decided.
approvals[].effectapprovals[].effect.done- The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approvals[].effect.entities- What it changes.
approvals[].effect.entities[].id- ID.
approvals[].effect.entities[].kind- Kind.One of
launch,adSet,ad approvals[].effect.entities[].launchId- Its launch.
approvals[].effect.entities[].name- Name.
approvals[].effect.lines- Human details, never field names or IDs.
approvals[].effect.lines[].label- A human label, e.g. Trigger.
approvals[].effect.lines[].value- Its value, e.g. New comment.
approvals[].effect.money- Amounts it spends or sets.
approvals[].effect.money[].amount- A decimal amount; never a float.
approvals[].effect.money[].currency- ISO 4217; null when the account's currency isn't known.
approvals[].effect.money[].label- Label.
approvals[].effect.subject- What it acts on, one quiet line to show under the title without expanding; absent for most actions. A comment action names the comment: v.i.u.m: “Does this work for small teams?” on App review test.
approvals[].effect.summary- What it does, in a sentence; empty when that would only repeat
title. approvals[].effect.title- The action as one sentence with real names, never IDs: Delete loop “Facebook comment moderator”. A tool without its own sentence reads as its title.
approvals[].effect.warnings- Things to know before approving.
approvals[].error- Why it failed, or the reason it was declined.
approvals[].error.code- Stable code.
approvals[].error.message- For the person.
approvals[].error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. approvals[].id- Approval.
approvals[].messageId- The answer that proposed it.
approvals[].permission- The coarse permission the call asked with: the action's own (
read,revieworwriteonly when the person chose Ask every time). What deciding needs iscapability.One ofread,review,write,publish,admin,organization approvals[].result- After approving.
approvals[].result.jobId- The job it started.
approvals[].result.summary- What happened.
approvals[].status- State.One of
pending,approved,rejected,failed,superseded approvals[].title- What it does, as one sentence with real names and never IDs, e.g. Delete loop “Facebook comment moderator”. The same as
effect.title. approvals[].tool- The MCP tool it runs.
hasEarlier- Earlier messages exist:
?before=<first message id>. linkId- The link.
messages- This page of the snapshot, oldest first.
messages[].approvalIds- Approvals raised in this answer.
messages[].attachments- Files the person attached.
messages[].attachments[].contentType- A chat file's type.
messages[].attachments[].fileId- A chat file, uploaded for the message.
messages[].attachments[].kind- Kind (a media library item is an
imageor avideo).One ofimage,video,pdf,document,spreadsheet,presentation,text,code,audio,archive messages[].attachments[].mediaId- A media library item.
messages[].attachments[].name- File name.
messages[].attachments[].pageCount- Pages of a PDF, Word document or presentation.
messages[].attachments[].previewUrl- A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
messages[].attachments[].sizeBytes- A chat file's size.
messages[].chatId- Chat.
messages[].completedAt- Finished.
messages[].createdAt- Written.
messages[].error- Why the answer failed.
messages[].error.code- Stable code.
messages[].error.message- For the person.
messages[].error.reason- For
spend_limit, the limit that stopped the Agent; forpayment_required, why there's no access. messages[].id- Message.
messages[].model- The model that produced the answer; null for the person's messages.
messages[].parts- The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
messages[].parts[].answerquestion: the answer once given (a choice's label, or the words of your reply).messages[].parts[].choiceIdquestion: the choice it was answered with.messages[].parts[].choicesquestion: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).messages[].parts[].columnstable: its columns.messages[].parts[].data- Every kind but
comboandtable: the series. messages[].parts[].description- One line under the title: the period, the unit.
messages[].parts[].groupscombo: its groups.messages[].parts[].id- The part; the same ID again replaces it.
messages[].parts[].itemsads: the ads, in the order shown.messages[].parts[].kind- How it's drawn;
tableis a table.One ofline,bar,horizontal-bar,stacked-bar,stacked-area,donut,funnel,combo,simple-bar,simple-normalized,spark-line,spark-bar,table messages[].parts[].optionsselection: the options (POST /agent/chats/{id}/parts/{part_id}/select).messages[].parts[].periodads: the days of itsmetrics:since,untilandpreset(last_30_days, …, or null).messages[].parts[].proposedselection: the options the Agent recommends, checked at first.messages[].parts[].rowstable: its rows.messages[].parts[].selectedselection: the options you confirmed.messages[].parts[].showLegend- Whether a legend shows; absent: for two or more series.
messages[].parts[].sizesimple-normalizedonly.One ofsmall,medium,largemessages[].parts[].textquestion: the question.text: the words (Markdown).messages[].parts[].title- What it shows.
messages[].parts[].type- A chart or a table, a question the Agent asks, options it proposes, ads it shows as cards, or the answer's words written before the card that follows them.One of
chart,question,selection,ads,text messages[].parts[].valueFormat- How values read:
style(decimal,percentwith values as percentages,currencywithcurrency),notation,minimumFractionDigits,maximumFractionDigits,unit. messages[].parts[].xAxislabel,hide.messages[].parts[].yAxislabel,integersOnly.messages[].role- Who wrote it.One of
user,assistant messages[].sentBy- Who sent a person's message (only they edit it); null for answers and for older messages, which are the chat's person's.
messages[].sources- The web pages the answer used: cited pages in the order first cited, then pages it read without citing; each URL once. Empty when it didn't use the web.
messages[].sources[].site- The hostname without
www.. messages[].sources[].title- Its title (its site when it named none).
messages[].sources[].url- The page.
messages[].status- State:
waitingfor credits;awaiting_userwhen the answer asked a question or proposed a selection (parts) and waits for your reply.One ofcomplete,streaming,stopped,failed,awaiting_approval,waiting,awaiting_user messages[].steps- What the Agent did, in order.
messages[].steps[].category- What kind of call it is, for a summary like "Created 2 launches, ran a search": from what the tool does (adds, changes, reads, lists, searches),
mcpfor another Pluto product (server). Absent for narration and thinking, and on older steps.One ofwrite,edit,read,list,search,mcp,other messages[].steps[].detail- Error, reasoning or narration text; a search's query; a read page's URL.
messages[].steps[].entities- What it touched.
messages[].steps[].entities[].id- ID.
messages[].steps[].entities[].kind- Kind.One of
launch,adSet,ad messages[].steps[].entities[].launchId- Its launch.
messages[].steps[].entities[].name- Name.
messages[].steps[].finishedAt- Finished.
messages[].steps[].id- Step.
messages[].steps[].kind- A tool call, narration before tools, summarized reasoning, a web search (
detailis the query) or a web page read (detailis its URL).One oftool,note,thinking,search,fetch messages[].steps[].label- Present tense while running, past tense when done.
messages[].steps[].server- The Pluto product an
mcpstep used, e.g.Pluto Profit. messages[].steps[].startedAt- Started.
messages[].steps[].status- State.One of
running,done,failed,awaiting_approval,rejected,stopped messages[].steps[].tool- The MCP tool; null for every kind but
tool. messages[].text- The question, or the answer (markdown;
pluto:links name launches, ad sets and ads). messages[].version- Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
messages[].versions- How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
messages[].workedMs- Active time, excluding waits for approval.
sharedAt- Shared or last updated.
sharedBysharedBy.id- The person.
sharedBy.name- Their name.
title- The chat's title.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/agent/shared/443c4665-1524-4ed3-bc71-1c19ee9d92c7" \
-H "Authorization: Bearer $PLUTO_KEY"Download a shared file
Redirects (302) to a short-lived URL of a file the shared chat shows; 404 for a file outside the snapshot.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
token | string | Required | |
fileId | string | Required | The file's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/agent/shared/443c4665-1524-4ed3-bc71-1c19ee9d92c7/files/1407e6a7-8e94-4479-98ab-d5432626c5a5/content" \
-H "Authorization: Bearer $PLUTO_KEY"Preview a shared file
The preview of a file the shared chat shows, as GET /workspaces/{id}/chat-files/{fileId}/preview answers its person; 404 for a file outside the snapshot.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
token | string | Required | |
fileId | string | Required | The file's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404The file has no preview, or the link doesn't show it.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/agent/shared/443c4665-1524-4ed3-bc71-1c19ee9d92c7/files/1407e6a7-8e94-4479-98ab-d5432626c5a5/preview" \
-H "Authorization: Bearer $PLUTO_KEY"List your Agent skills
Your skills in this workspace, and the ones shared with the whole workspace (shared), by name, without their prompts. The Agent sees every name and description in the chats you start and loads a skill's prompt when a request fits or you name it; you run one with /name at the start of a message (POST /agent/chats/{id}/messages). Also in MCP as list_agent_skills; run_agent_skill hands an outside agent a skill's instructions. Yours only: the signed-in person's, or the person a connected agent or agent client acts for, in this workspace. API keys and M2M clients without a person get 403; another person's skill is 404. Not for guests.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- Every skill, by name, without its body.
items[].canEdit- The caller may change or delete it.
items[].createdAt- Created.
items[].description- What it does and when to use it (up to 1,024 characters): the Agent picks skills by it.
items[].id- The skill.
items[].name- Lowercase letters, numbers and hyphens (up to 64); run it in the Agent as
/name. items[].shared- Shared with everyone in the workspace (owners and admins change it); otherwise the author's own.
items[].source- Where it came from:
kindischat(saved from an Agent chat, withchatIdandmessageId),settings,apiormcp. items[].source.chatIditems[].source.kind- One of
chat,settings,api,mcp items[].source.messageIditems[].updatedAt- Last changed.
items[].version- Send it back as
expectedVersion.
curl "$PLUTO_API/agent/skills" \
-H "Authorization: Bearer $PLUTO_KEY"Create a skill
Up to 50 skills each, and 50 shared; a name already used is a 422 on name. shared: true shares it with the workspace (owners and admins; 403 otherwise). Something that should run on its own is a loop instead. Also in MCP as create_agent_skill. Yours only: the signed-in person's, or the person a connected agent or agent client acts for, in this workspace. API keys and M2M clients without a person get 403; another person's skill is 404. Not for guests.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
body- The prompt the skill runs.
description- What the skill does and when to use it, without tags: the Agent picks skills by it.
name- Lowercase letters, numbers and single hyphens, up to 64; unique among your skills (and among shared ones). Run it as
/name. shared- Shared with everyone in the workspace (owners and admins share and change it).
Response
body- The prompt the skill runs (up to 20,000 characters).
canEdit- The caller may change or delete it.
createdAt- Created.
description- What it does and when to use it (up to 1,024 characters): the Agent picks skills by it.
id- The skill.
name- Lowercase letters, numbers and hyphens (up to 64); run it in the Agent as
/name. shared- Shared with everyone in the workspace (owners and admins change it); otherwise the author's own.
source- Where it came from:
kindischat(saved from an Agent chat, withchatIdandmessageId),settings,apiormcp. source.chatIdsource.kind- One of
chat,settings,api,mcp source.messageIdupdatedAt- Last changed.
version- Send it back as
expectedVersion.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/agent/skills" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 6bfa0987-f373-47ba-a30a-40228ee83006" \
-H "Content-Type: application/json" \
-d '{
"body": "Can we try the 4x5 cut for Instagram feed before we publish?",
"description": "Two drops every morning for brighter, even skin.",
"name": "Vitamin C Serum, UGC 9x16",
"shared": true
}'Get a skill
Also in MCP as get_agent_skill, which takes the name too. Yours only: the signed-in person's, or the person a connected agent or agent client acts for, in this workspace. API keys and M2M clients without a person get 403; another person's skill is 404. Not for guests.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The skill's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
body- The prompt the skill runs (up to 20,000 characters).
canEdit- The caller may change or delete it.
createdAt- Created.
description- What it does and when to use it (up to 1,024 characters): the Agent picks skills by it.
id- The skill.
name- Lowercase letters, numbers and hyphens (up to 64); run it in the Agent as
/name. shared- Shared with everyone in the workspace (owners and admins change it); otherwise the author's own.
source- Where it came from:
kindischat(saved from an Agent chat, withchatIdandmessageId),settings,apiormcp. source.chatIdsource.kind- One of
chat,settings,api,mcp source.messageIdupdatedAt- Last changed.
version- Send it back as
expectedVersion.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/agent/skills/7efc822f-6223-4103-95d7-24a49a7240b8" \
-H "Authorization: Bearer $PLUTO_KEY"Change a skill
Any of name, description, body and shared; the rest stay. Your own skills are yours to change; shared ones, and sharing, are for owners and admins (403). A stale expectedVersion is a 409 with current. Also in MCP as update_agent_skill. Yours only: the signed-in person's, or the person a connected agent or agent client acts for, in this workspace. API keys and M2M clients without a person get 403; another person's skill is 404. Not for guests.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The skill's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
body- The prompt the skill runs.
description- What the skill does and when to use it, without tags: the Agent picks skills by it.
expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
name- Lowercase letters, numbers and single hyphens, up to 64; unique among your skills (and among shared ones). Run it as
/name. shared- Shared with everyone in the workspace (owners and admins share and change it).
Response
body- The prompt the skill runs (up to 20,000 characters).
canEdit- The caller may change or delete it.
createdAt- Created.
description- What it does and when to use it (up to 1,024 characters): the Agent picks skills by it.
id- The skill.
name- Lowercase letters, numbers and hyphens (up to 64); run it in the Agent as
/name. shared- Shared with everyone in the workspace (owners and admins change it); otherwise the author's own.
source- Where it came from:
kindischat(saved from an Agent chat, withchatIdandmessageId),settings,apiormcp. source.chatIdsource.kind- One of
chat,settings,api,mcp source.messageIdupdatedAt- Last changed.
version- Send it back as
expectedVersion.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/agent/skills/7efc822f-6223-4103-95d7-24a49a7240b8" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: e086dcbe-10b0-437b-873f-35619db0ddb0" \
-H "Content-Type: application/json" \
-d '{
"body": "Can we try the 4x5 cut for Instagram feed before we publish?",
"description": "Two drops every morning for brighter, even skin.",
"expectedVersion": 3,
"name": "Vitamin C Serum, UGC 9x16",
"shared": true
}'Delete a skill
For good: /name stops running it and new chats no longer list it. Shared skills are deleted by owners and admins. Also in MCP as delete_agent_skill. Yours only: the signed-in person's, or the person a connected agent or agent client acts for, in this workspace. API keys and M2M clients without a person get 403; another person's skill is 404. Not for guests.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The skill's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
Done; no content.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/agent/skills/7efc822f-6223-4103-95d7-24a49a7240b8" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: c09bb833-0734-4112-930b-d9f3e3deb2e5"List suggestions
The memory entries and skills the Agent suggested saving in one of your chats (chatId), each under the answer it came with: pending until you save or dismiss it, saved (auto when Save automatically saved it), or dismissed. Only in the app: an agent never saves what an agent suggested. Yours only: the signed-in person's, or the person a connected agent or agent client acts for, in this workspace. API keys and M2M clients without a person get 403; another person's skill is 404. Not for guests.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
chatId | string | Optional | The chat. Required: without it the answer is 400. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- Oldest first.
items[].action- What it would do.One of
create,update,delete items[].auto- Saved without asking (Save automatically).
items[].chatId- The chat.
items[].createdAt- Suggested.
items[].current- For an update or delete, what's saved now; null when it's gone.
items[].decidedAt- Saved or dismissed.
items[].id- The suggestion.
items[].kind- A memory entry or a skill.One of
memory,skill items[].messageId- The answer it came with.
items[].proposal- The fields to save (for an update, only what changes).
items[].savedId- The entry or skill it saved.
items[].status- Where it stands.One of
pending,saved,dismissed items[].targetId- The entry or skill an update or delete is about.
curl "$PLUTO_API/agent/suggestions" \
-H "Authorization: Bearer $PLUTO_KEY"Dismiss a suggestion
Nothing is saved; the suggestion stays dismissed. Yours only: the signed-in person's, or the person a connected agent or agent client acts for, in this workspace. API keys and M2M clients without a person get 403; another person's skill is 404. Not for guests.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The suggestion's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
action- What it would do.One of
create,update,delete auto- Saved without asking (Save automatically).
chatId- The chat.
createdAt- Suggested.
current- For an update or delete, what's saved now; null when it's gone.
decidedAt- Saved or dismissed.
id- The suggestion.
kind- A memory entry or a skill.One of
memory,skill messageId- The answer it came with.
proposal- The fields to save (for an update, only what changes).
savedId- The entry or skill it saved.
status- Where it stands.One of
pending,saved,dismissed targetId- The entry or skill an update or delete is about.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/agent/suggestions/8cdb4d20-0092-4ac0-854c-7c3c7cdd677e/dismiss" \
-H "Authorization: Bearer $PLUTO_KEY"Save a suggestion
Saves what the Agent suggested, as suggested or with your edits (fields, the same shape as proposal), as you: the entry or skill comes from that chat. A suggestion already decided comes back as it is. Yours only: the signed-in person's, or the person a connected agent or agent client acts for, in this workspace. API keys and M2M clients without a person get 403; another person's skill is 404. Not for guests.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The suggestion's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
fields- The fields to save instead of the suggested ones.
Response
action- What it would do.One of
create,update,delete auto- Saved without asking (Save automatically).
chatId- The chat.
createdAt- Suggested.
current- For an update or delete, what's saved now; null when it's gone.
decidedAt- Saved or dismissed.
id- The suggestion.
kind- A memory entry or a skill.One of
memory,skill messageId- The answer it came with.
proposal- The fields to save (for an update, only what changes).
savedId- The entry or skill it saved.
status- Where it stands.One of
pending,saved,dismissed targetId- The entry or skill an update or delete is about.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/agent/suggestions/8cdb4d20-0092-4ac0-854c-7c3c7cdd677e/save" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: da0d89f9-7cd7-4311-8e6b-d1f559145d44" \
-H "Content-Type: application/json" \
-d '{
"fields": {}
}'