API reference

Agent

Chats with the in-app Agent, its approvals, models, skills and guidance.

GET/agent/approval-settings

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.

Permission: read

Parameters

NameTypeRequiredDescription
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

budgetGuardrailobjectRequired
budgetGuardrail.amountstring or nullRequired
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.currencystring or nullRequired
ISO 4217, a currency Meta supports; given exactly when amount is.
budgetGuardrail.percentstringRequired
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").
canEditbooleanRequired
The caller is an owner or admin.
canRunEverythingbooleanRequired
The caller may choose Run everything now: a person signed in to Pluto, where the workspace lets them.
membersCanTurnOffApprovalsbooleanRequired
Members may choose Run everything; owners and admins always may.
reasonstring or nullRequired
Why not, when canRunEverything is false.
updatedAtstring (date-time) or nullRequired
Last saved; null before the first save.
versionintegerRequired
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.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/agent/approval-settings" \
  -H "Authorization: Bearer $PLUTO_KEY"
PUT/agent/approval-settings

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.

Permission: adminCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

budgetGuardrailobject
budgetGuardrail.amountstring or nullRequired
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.currencystring or nullRequired
ISO 4217, a currency Meta supports; given exactly when amount is.
budgetGuardrail.percentstringRequired
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").
expectedVersionintegerRequired
version the change is based on (0 before the first save).
membersCanTurnOffApprovalsboolean
Whether members may choose Run everything.

Response200 OK

budgetGuardrailobjectRequired
budgetGuardrail.amountstring or nullRequired
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.currencystring or nullRequired
ISO 4217, a currency Meta supports; given exactly when amount is.
budgetGuardrail.percentstringRequired
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").
canEditbooleanRequired
The caller is an owner or admin.
canRunEverythingbooleanRequired
The caller may choose Run everything now: a person signed in to Pluto, where the workspace lets them.
membersCanTurnOffApprovalsbooleanRequired
Members may choose Run everything; owners and admins always may.
reasonstring or nullRequired
Why not, when canRunEverything is false.
updatedAtstring (date-time) or nullRequired
Last saved; null before the first save.
versionintegerRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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
  }'
POST/agent/approvals/decide

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.

Permission: writeApp session onlyCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

approvalIdsarray of strings (uuid)Required
1 to 200 waiting approvals of one answer, decided in this order.
decisionstringRequired
Approve all of them, or decline all of them.One of approve, reject
reasonstring
Why you declined, up to 1000 characters; the Agent reads it.

Response200 OK

approvalobject
approval.canApprovebooleanRequired
The viewer can approve it: the same as canDecide.
approval.canDecidebooleanRequired
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.capabilitystringRequired
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.chatIdstring (uuid)Required
Chat.
approval.createdAtstring (date-time)Required
Proposed.
approval.decidedAtstring (date-time) or nullRequired
Decided.
approval.effectobjectRequired
approval.effect.donestringRequired
The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approval.effect.entitiesarray of objectsRequired
What it changes.
approval.effect.entities[].idstring (uuid)Required
ID.
approval.effect.entities[].kindstringRequired
Kind.One of launch, adSet, ad
approval.effect.entities[].launchIdstring (uuid)Required
Its launch.
approval.effect.entities[].namestring or nullRequired
Name.
approval.effect.linesarray of objectsRequired
Human details, never field names or IDs.
approval.effect.lines[].labelstringRequired
A human label, e.g. Trigger.
approval.effect.lines[].valuestringRequired
Its value, e.g. New comment.
approval.effect.moneyarray of objectsRequired
Amounts it spends or sets.
approval.effect.money[].amountstringRequired
A decimal amount; never a float.
approval.effect.money[].currencystring or nullRequired
ISO 4217; null when the account's currency isn't known.
approval.effect.money[].labelstringRequired
Label.
approval.effect.subjectstring
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.summarystringRequired
What it does, in a sentence; empty when that would only repeat title.
approval.effect.titlestringRequired
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.warningsarray of stringsRequired
Things to know before approving.
approval.errorobject or nullRequired
Why it failed, or the reason it was declined.
approval.error.codestringRequired
Stable code.
approval.error.messagestringRequired
For the person.
approval.error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
approval.idstring (uuid)Required
Approval.
approval.messageIdstring (uuid)Required
The answer that proposed it.
approval.permissionstringRequired
The coarse permission the call asked with: the action's own (read, review or write only when the person chose Ask every time). What deciding needs is capability.One of read, review, write, publish, admin, organization
approval.resultobject or nullRequired
After approving.
approval.result.jobIdstring (uuid) or nullRequired
The job it started.
approval.result.summarystringRequired
What happened.
approval.statusstringRequired
State.One of pending, approved, rejected, failed, superseded
approval.titlestringRequired
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.toolstringRequired
The MCP tool it runs.
chatobject
chat.createdAtstring (date-time)Required
Started.
chat.effortstring or nullRequired
The reasoning effort picked for the chat; null: the model's default.
chat.idstring (uuid)Required
Chat.
chat.lastMessageAtstring (date-time) or nullRequired
Last message.
chat.loopIdstring (uuid) or nullRequired
The loop it is the history of (it made the loop, or was started in its builder).
chat.modelstringRequired
The chat's model: pluto, auto or a model ID from GET /agent/models.
chat.ownerIdstring (uuid)Required
The chat's person: only they rename, delete or share it.
chat.sharedbooleanRequired
Shared with everyone who can see its loop; false: private to its person.
chat.sourcestringRequired
Where it started.One of page, panel, home, loop
chat.statusstringRequired
What it's doing.One of idle, running, awaiting_approval
chat.titlestring or nullRequired
Title; null until the first answer names it.
chat.unreadbooleanRequired
An answer arrived after the person last read it.
chat.updatedAtstring (date-time)Required
Last change.
codestring
error: spend_limit, payment_required, model_unavailable, rate_limited, refusal, max_tokens, step_limit or internal.
deltastring
Text to append.
messageobject
message.approvalIdsarray of strings (uuid)Required
Approvals raised in this answer.
message.attachmentsarray of objectsRequired
Files the person attached.
message.attachments[].contentTypestring
A chat file's type.
message.attachments[].fileIdstring (uuid)
A chat file, uploaded for the message.
message.attachments[].kindstringRequired
Kind (a media library item is an image or a video).One of image, video, pdf, document, spreadsheet, presentation, text, code, audio, archive
message.attachments[].mediaIdstring (uuid)
A media library item.
message.attachments[].namestringRequired
File name.
message.attachments[].pageCountinteger
Pages of a PDF, Word document or presentation.
message.attachments[].previewUrlstring
A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
message.attachments[].sizeBytesinteger
A chat file's size.
message.chatIdstring (uuid)Required
Chat.
message.completedAtstring (date-time) or nullRequired
Finished.
message.createdAtstring (date-time)Required
Written.
message.errorobject or nullRequired
Why the answer failed.
message.error.codestringRequired
Stable code.
message.error.messagestringRequired
For the person.
message.error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
message.idstring (uuid)Required
Message.
message.modelstring or nullRequired
The model that produced the answer; null for the person's messages.
message.partsarray of objectsRequired
The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
message.parts[].answerstring
question: the answer once given (a choice's label, or the words of your reply).
message.parts[].choiceIdstring
question: the choice it was answered with.
message.parts[].choicesarray of objects
question: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).
message.parts[].columnsarray of objects
table: its columns.
message.parts[].dataarray of objects
Every kind but combo and table: the series.
message.parts[].descriptionstring
One line under the title: the period, the unit.
message.parts[].groupsarray of objects
combo: its groups.
message.parts[].idstringRequired
The part; the same ID again replaces it.
message.parts[].itemsarray of objects
ads: the ads, in the order shown.
message.parts[].kindstring
How it's drawn; table is a table.One of line, bar, horizontal-bar, stacked-bar, stacked-area, donut, funnel, combo, simple-bar, simple-normalized, spark-line, spark-bar, table
message.parts[].optionsarray of objects
selection: the options (POST /agent/chats/{id}/parts/{part_id}/select).
message.parts[].periodobject
ads: the days of its metrics: since, until and preset (last_30_days, …, or null).
message.parts[].proposedarray of strings
selection: the options the Agent recommends, checked at first.
message.parts[].rowsarray of objects
table: its rows.
message.parts[].selectedarray of strings
selection: the options you confirmed.
message.parts[].showLegendboolean
Whether a legend shows; absent: for two or more series.
message.parts[].sizestring
simple-normalized only.One of small, medium, large
message.parts[].textstring
question: the question. text: the words (Markdown).
message.parts[].titlestring
What it shows.
message.parts[].typestringRequired
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[].valueFormatobject
How values read: style (decimal, percent with values as percentages, currency with currency), notation, minimumFractionDigits, maximumFractionDigits, unit.
message.parts[].xAxisobject
label, hide.
message.parts[].yAxisobject
label, integersOnly.
message.rolestringRequired
Who wrote it.One of user, assistant
message.sentBystring (uuid) or nullRequired
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.sourcesarray of objectsRequired
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[].sitestringRequired
The hostname without www..
message.sources[].titlestringRequired
Its title (its site when it named none).
message.sources[].urlstringRequired
The page.
message.statusstringRequired
State: waiting for credits; awaiting_user when the answer asked a question or proposed a selection (parts) and waits for your reply.One of complete, streaming, stopped, failed, awaiting_approval, waiting, awaiting_user
message.stepsarray of objectsRequired
What the Agent did, in order.
message.steps[].categorystring
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), mcp for another Pluto product (server). Absent for narration and thinking, and on older steps.One of write, edit, read, list, search, mcp, other
message.steps[].detailstring or nullRequired
Error, reasoning or narration text; a search's query; a read page's URL.
message.steps[].entitiesarray of objectsRequired
What it touched.
message.steps[].entities[].idstring (uuid)Required
ID.
message.steps[].entities[].kindstringRequired
Kind.One of launch, adSet, ad
message.steps[].entities[].launchIdstring (uuid)Required
Its launch.
message.steps[].entities[].namestring or nullRequired
Name.
message.steps[].finishedAtstring (date-time) or nullRequired
Finished.
message.steps[].idstringRequired
Step.
message.steps[].kindstringRequired
A tool call, narration before tools, summarized reasoning, a web search (detail is the query) or a web page read (detail is its URL).One of tool, note, thinking, search, fetch
message.steps[].labelstringRequired
Present tense while running, past tense when done.
message.steps[].serverstring
The Pluto product an mcp step used, e.g. Pluto Profit.
message.steps[].startedAtstring (date-time)Required
Started.
message.steps[].statusstringRequired
State.One of running, done, failed, awaiting_approval, rejected, stopped
message.steps[].toolstring or nullRequired
The MCP tool; null for every kind but tool.
message.textstringRequired
The question, or the answer (markdown; pluto: links name launches, ad sets and ads).
message.versionintegerRequired
Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
message.versionsintegerRequired
How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
message.workedMsinteger or nullRequired
Active time, excluding waits for approval.
messageIdstring (uuid)
The Agent message a delta belongs to.
partobject
part.answerstring
question: the answer once given (a choice's label, or the words of your reply).
part.choiceIdstring
question: the choice it was answered with.
part.choicesarray of objects
question: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).
part.columnsarray of objects
table: its columns.
part.dataarray of objects
Every kind but combo and table: the series.
part.descriptionstring
One line under the title: the period, the unit.
part.groupsarray of objects
combo: its groups.
part.idstringRequired
The part; the same ID again replaces it.
part.itemsarray of objects
ads: the ads, in the order shown.
part.kindstring
How it's drawn; table is a table.One of line, bar, horizontal-bar, stacked-bar, stacked-area, donut, funnel, combo, simple-bar, simple-normalized, spark-line, spark-bar, table
part.optionsarray of objects
selection: the options (POST /agent/chats/{id}/parts/{part_id}/select).
part.periodobject
ads: the days of its metrics: since, until and preset (last_30_days, …, or null).
part.proposedarray of strings
selection: the options the Agent recommends, checked at first.
part.rowsarray of objects
table: its rows.
part.selectedarray of strings
selection: the options you confirmed.
part.showLegendboolean
Whether a legend shows; absent: for two or more series.
part.sizestring
simple-normalized only.One of small, medium, large
part.textstring
question: the question. text: the words (Markdown).
part.titlestring
What it shows.
part.typestringRequired
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.valueFormatobject
How values read: style (decimal, percent with values as percentages, currency with currency), notation, minimumFractionDigits, maximumFractionDigits, unit.
part.xAxisobject
label, hide.
part.yAxisobject
label, integersOnly.
reasonstring or null
error with spend_limit: which limit stopped it (member_limit, workspace_limit or trial_cap); with payment_required: why there's no access.
retryableboolean
error: whether retrying can help.
sourcesarray of objects
sources events: the answer's web pages so far.
sources[].sitestringRequired
The hostname without www..
sources[].titlestringRequired
Its title (its site when it named none).
sources[].urlstringRequired
The page.
stallobject or null
stall: 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) or silent_tool (a tool reported nothing for 45 s), and since, when the silence began (epoch milliseconds); null once it moves again.
stall.kindstringRequired
What went quiet.One of no_first_byte, silent_stream, silent_tool
stall.sinceintegerRequired
When the silence began, epoch milliseconds.
stepobject
step.categorystring
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), mcp for another Pluto product (server). Absent for narration and thinking, and on older steps.One of write, edit, read, list, search, mcp, other
step.detailstring or nullRequired
Error, reasoning or narration text; a search's query; a read page's URL.
step.entitiesarray of objectsRequired
What it touched.
step.entities[].idstring (uuid)Required
ID.
step.entities[].kindstringRequired
Kind.One of launch, adSet, ad
step.entities[].launchIdstring (uuid)Required
Its launch.
step.entities[].namestring or nullRequired
Name.
step.finishedAtstring (date-time) or nullRequired
Finished.
step.idstringRequired
Step.
step.kindstringRequired
A tool call, narration before tools, summarized reasoning, a web search (detail is the query) or a web page read (detail is its URL).One of tool, note, thinking, search, fetch
step.labelstringRequired
Present tense while running, past tense when done.
step.serverstring
The Pluto product an mcp step used, e.g. Pluto Profit.
step.startedAtstring (date-time)Required
Started.
step.statusstringRequired
State.One of running, done, failed, awaiting_approval, rejected, stopped
step.toolstring or nullRequired
The MCP tool; null for every kind but tool.
stepIdstring
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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."
  }'
GET/agent/approvals/{id}

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).

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe approval's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

canApprovebooleanRequired
You can approve it: the same as canDecide.
canDecidebooleanRequired
You may approve or reject it now: you hold capability and may use the Agent. Checked again when you decide and when it runs.
capabilitystringRequired
What approving or rejecting it needs, as a capability ID (ads:publish). The person who asked doesn't hold it.
createdAtstring (date-time)Required
Proposed.
decidedAtstring (date-time) or nullRequired
Decided.
decidedByobject or nullRequired
Who approved or rejected it; null while it waits, or once it was taken back.
decidedBy.idstring (uuid)Required
Person.
decidedBy.namestring or nullRequired
Their name now; null once their account is gone.
effectobjectRequired
effect.donestringRequired
The same once it ran.
effect.entitiesarray of objectsRequired
What it changes.
effect.entities[].idstring (uuid)Required
ID.
effect.entities[].kindstringRequired
Kind.One of launch, adSet, ad
effect.entities[].launchIdstring (uuid)Required
Its launch.
effect.entities[].namestring or nullRequired
Name.
effect.linesarray of objectsRequired
Human details, never field names or IDs.
effect.lines[].labelstringRequired
A human label.
effect.lines[].valuestringRequired
Its value.
effect.moneyarray of objectsRequired
Amounts it spends or sets.
effect.money[].amountstringRequired
A decimal amount; never a float.
effect.money[].currencystring or nullRequired
ISO 4217; null when the account's currency isn't known.
effect.money[].labelstringRequired
Label.
effect.subjectstring
What it acts on, one quiet line under the title; absent for most actions.
effect.summarystringRequired
What it does, in a sentence; empty when that would only repeat title.
effect.titlestringRequired
The action as one sentence with real names, never IDs.
effect.warningsarray of stringsRequired
Things to know before approving.
errorobject or nullRequired
Why it failed, or the reason it was rejected.
error.codestringRequired
Stable code.
error.messagestringRequired
For the person.
error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
expiresAtstring (date-time)Required
Until when approving it runs it (a day after it was proposed); rejecting still clears it after.
idstring (uuid)Required
Approval.
permissionstringRequired
The coarse permission the call asked with. What deciding needs is capability.One of read, review, write, publish, admin, organization
proposedByobject or nullRequired
Who asked: the person the Agent proposed it for.
proposedBy.idstring (uuid)Required
Person.
proposedBy.namestring or nullRequired
Their name now; null once their account is gone.
resultobject or nullRequired
After approving.
result.jobIdstring (uuid) or nullRequired
The job it started.
result.summarystringRequired
What happened.
statusstringRequired
State. superseded: the person who asked took it back.One of pending, approved, rejected, failed, superseded
titlestringRequired
What it does, as one sentence with real names and never IDs. The same as effect.title.
toolstringRequired
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-After seconds. 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"
POST/agent/approvals/{id}/approve

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.

Permission: writeApp session onlyCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe approval's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

Response200 OK

approvalobject
approval.canApprovebooleanRequired
The viewer can approve it: the same as canDecide.
approval.canDecidebooleanRequired
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.capabilitystringRequired
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.chatIdstring (uuid)Required
Chat.
approval.createdAtstring (date-time)Required
Proposed.
approval.decidedAtstring (date-time) or nullRequired
Decided.
approval.effectobjectRequired
approval.effect.donestringRequired
The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approval.effect.entitiesarray of objectsRequired
What it changes.
approval.effect.entities[].idstring (uuid)Required
ID.
approval.effect.entities[].kindstringRequired
Kind.One of launch, adSet, ad
approval.effect.entities[].launchIdstring (uuid)Required
Its launch.
approval.effect.entities[].namestring or nullRequired
Name.
approval.effect.linesarray of objectsRequired
Human details, never field names or IDs.
approval.effect.lines[].labelstringRequired
A human label, e.g. Trigger.
approval.effect.lines[].valuestringRequired
Its value, e.g. New comment.
approval.effect.moneyarray of objectsRequired
Amounts it spends or sets.
approval.effect.money[].amountstringRequired
A decimal amount; never a float.
approval.effect.money[].currencystring or nullRequired
ISO 4217; null when the account's currency isn't known.
approval.effect.money[].labelstringRequired
Label.
approval.effect.subjectstring
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.summarystringRequired
What it does, in a sentence; empty when that would only repeat title.
approval.effect.titlestringRequired
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.warningsarray of stringsRequired
Things to know before approving.
approval.errorobject or nullRequired
Why it failed, or the reason it was declined.
approval.error.codestringRequired
Stable code.
approval.error.messagestringRequired
For the person.
approval.error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
approval.idstring (uuid)Required
Approval.
approval.messageIdstring (uuid)Required
The answer that proposed it.
approval.permissionstringRequired
The coarse permission the call asked with: the action's own (read, review or write only when the person chose Ask every time). What deciding needs is capability.One of read, review, write, publish, admin, organization
approval.resultobject or nullRequired
After approving.
approval.result.jobIdstring (uuid) or nullRequired
The job it started.
approval.result.summarystringRequired
What happened.
approval.statusstringRequired
State.One of pending, approved, rejected, failed, superseded
approval.titlestringRequired
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.toolstringRequired
The MCP tool it runs.
chatobject
chat.createdAtstring (date-time)Required
Started.
chat.effortstring or nullRequired
The reasoning effort picked for the chat; null: the model's default.
chat.idstring (uuid)Required
Chat.
chat.lastMessageAtstring (date-time) or nullRequired
Last message.
chat.loopIdstring (uuid) or nullRequired
The loop it is the history of (it made the loop, or was started in its builder).
chat.modelstringRequired
The chat's model: pluto, auto or a model ID from GET /agent/models.
chat.ownerIdstring (uuid)Required
The chat's person: only they rename, delete or share it.
chat.sharedbooleanRequired
Shared with everyone who can see its loop; false: private to its person.
chat.sourcestringRequired
Where it started.One of page, panel, home, loop
chat.statusstringRequired
What it's doing.One of idle, running, awaiting_approval
chat.titlestring or nullRequired
Title; null until the first answer names it.
chat.unreadbooleanRequired
An answer arrived after the person last read it.
chat.updatedAtstring (date-time)Required
Last change.
codestring
error: spend_limit, payment_required, model_unavailable, rate_limited, refusal, max_tokens, step_limit or internal.
deltastring
Text to append.
messageobject
message.approvalIdsarray of strings (uuid)Required
Approvals raised in this answer.
message.attachmentsarray of objectsRequired
Files the person attached.
message.attachments[].contentTypestring
A chat file's type.
message.attachments[].fileIdstring (uuid)
A chat file, uploaded for the message.
message.attachments[].kindstringRequired
Kind (a media library item is an image or a video).One of image, video, pdf, document, spreadsheet, presentation, text, code, audio, archive
message.attachments[].mediaIdstring (uuid)
A media library item.
message.attachments[].namestringRequired
File name.
message.attachments[].pageCountinteger
Pages of a PDF, Word document or presentation.
message.attachments[].previewUrlstring
A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
message.attachments[].sizeBytesinteger
A chat file's size.
message.chatIdstring (uuid)Required
Chat.
message.completedAtstring (date-time) or nullRequired
Finished.
message.createdAtstring (date-time)Required
Written.
message.errorobject or nullRequired
Why the answer failed.
message.error.codestringRequired
Stable code.
message.error.messagestringRequired
For the person.
message.error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
message.idstring (uuid)Required
Message.
message.modelstring or nullRequired
The model that produced the answer; null for the person's messages.
message.partsarray of objectsRequired
The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
message.parts[].answerstring
question: the answer once given (a choice's label, or the words of your reply).
message.parts[].choiceIdstring
question: the choice it was answered with.
message.parts[].choicesarray of objects
question: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).
message.parts[].columnsarray of objects
table: its columns.
message.parts[].dataarray of objects
Every kind but combo and table: the series.
message.parts[].descriptionstring
One line under the title: the period, the unit.
message.parts[].groupsarray of objects
combo: its groups.
message.parts[].idstringRequired
The part; the same ID again replaces it.
message.parts[].itemsarray of objects
ads: the ads, in the order shown.
message.parts[].kindstring
How it's drawn; table is a table.One of line, bar, horizontal-bar, stacked-bar, stacked-area, donut, funnel, combo, simple-bar, simple-normalized, spark-line, spark-bar, table
message.parts[].optionsarray of objects
selection: the options (POST /agent/chats/{id}/parts/{part_id}/select).
message.parts[].periodobject
ads: the days of its metrics: since, until and preset (last_30_days, …, or null).
message.parts[].proposedarray of strings
selection: the options the Agent recommends, checked at first.
message.parts[].rowsarray of objects
table: its rows.
message.parts[].selectedarray of strings
selection: the options you confirmed.
message.parts[].showLegendboolean
Whether a legend shows; absent: for two or more series.
message.parts[].sizestring
simple-normalized only.One of small, medium, large
message.parts[].textstring
question: the question. text: the words (Markdown).
message.parts[].titlestring
What it shows.
message.parts[].typestringRequired
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[].valueFormatobject
How values read: style (decimal, percent with values as percentages, currency with currency), notation, minimumFractionDigits, maximumFractionDigits, unit.
message.parts[].xAxisobject
label, hide.
message.parts[].yAxisobject
label, integersOnly.
message.rolestringRequired
Who wrote it.One of user, assistant
message.sentBystring (uuid) or nullRequired
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.sourcesarray of objectsRequired
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[].sitestringRequired
The hostname without www..
message.sources[].titlestringRequired
Its title (its site when it named none).
message.sources[].urlstringRequired
The page.
message.statusstringRequired
State: waiting for credits; awaiting_user when the answer asked a question or proposed a selection (parts) and waits for your reply.One of complete, streaming, stopped, failed, awaiting_approval, waiting, awaiting_user
message.stepsarray of objectsRequired
What the Agent did, in order.
message.steps[].categorystring
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), mcp for another Pluto product (server). Absent for narration and thinking, and on older steps.One of write, edit, read, list, search, mcp, other
message.steps[].detailstring or nullRequired
Error, reasoning or narration text; a search's query; a read page's URL.
message.steps[].entitiesarray of objectsRequired
What it touched.
message.steps[].entities[].idstring (uuid)Required
ID.
message.steps[].entities[].kindstringRequired
Kind.One of launch, adSet, ad
message.steps[].entities[].launchIdstring (uuid)Required
Its launch.
message.steps[].entities[].namestring or nullRequired
Name.
message.steps[].finishedAtstring (date-time) or nullRequired
Finished.
message.steps[].idstringRequired
Step.
message.steps[].kindstringRequired
A tool call, narration before tools, summarized reasoning, a web search (detail is the query) or a web page read (detail is its URL).One of tool, note, thinking, search, fetch
message.steps[].labelstringRequired
Present tense while running, past tense when done.
message.steps[].serverstring
The Pluto product an mcp step used, e.g. Pluto Profit.
message.steps[].startedAtstring (date-time)Required
Started.
message.steps[].statusstringRequired
State.One of running, done, failed, awaiting_approval, rejected, stopped
message.steps[].toolstring or nullRequired
The MCP tool; null for every kind but tool.
message.textstringRequired
The question, or the answer (markdown; pluto: links name launches, ad sets and ads).
message.versionintegerRequired
Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
message.versionsintegerRequired
How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
message.workedMsinteger or nullRequired
Active time, excluding waits for approval.
messageIdstring (uuid)
The Agent message a delta belongs to.
partobject
part.answerstring
question: the answer once given (a choice's label, or the words of your reply).
part.choiceIdstring
question: the choice it was answered with.
part.choicesarray of objects
question: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).
part.columnsarray of objects
table: its columns.
part.dataarray of objects
Every kind but combo and table: the series.
part.descriptionstring
One line under the title: the period, the unit.
part.groupsarray of objects
combo: its groups.
part.idstringRequired
The part; the same ID again replaces it.
part.itemsarray of objects
ads: the ads, in the order shown.
part.kindstring
How it's drawn; table is a table.One of line, bar, horizontal-bar, stacked-bar, stacked-area, donut, funnel, combo, simple-bar, simple-normalized, spark-line, spark-bar, table
part.optionsarray of objects
selection: the options (POST /agent/chats/{id}/parts/{part_id}/select).
part.periodobject
ads: the days of its metrics: since, until and preset (last_30_days, …, or null).
part.proposedarray of strings
selection: the options the Agent recommends, checked at first.
part.rowsarray of objects
table: its rows.
part.selectedarray of strings
selection: the options you confirmed.
part.showLegendboolean
Whether a legend shows; absent: for two or more series.
part.sizestring
simple-normalized only.One of small, medium, large
part.textstring
question: the question. text: the words (Markdown).
part.titlestring
What it shows.
part.typestringRequired
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.valueFormatobject
How values read: style (decimal, percent with values as percentages, currency with currency), notation, minimumFractionDigits, maximumFractionDigits, unit.
part.xAxisobject
label, hide.
part.yAxisobject
label, integersOnly.
reasonstring or null
error with spend_limit: which limit stopped it (member_limit, workspace_limit or trial_cap); with payment_required: why there's no access.
retryableboolean
error: whether retrying can help.
sourcesarray of objects
sources events: the answer's web pages so far.
sources[].sitestringRequired
The hostname without www..
sources[].titlestringRequired
Its title (its site when it named none).
sources[].urlstringRequired
The page.
stallobject or null
stall: 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) or silent_tool (a tool reported nothing for 45 s), and since, when the silence began (epoch milliseconds); null once it moves again.
stall.kindstringRequired
What went quiet.One of no_first_byte, silent_stream, silent_tool
stall.sinceintegerRequired
When the silence began, epoch milliseconds.
stepobject
step.categorystring
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), mcp for another Pluto product (server). Absent for narration and thinking, and on older steps.One of write, edit, read, list, search, mcp, other
step.detailstring or nullRequired
Error, reasoning or narration text; a search's query; a read page's URL.
step.entitiesarray of objectsRequired
What it touched.
step.entities[].idstring (uuid)Required
ID.
step.entities[].kindstringRequired
Kind.One of launch, adSet, ad
step.entities[].launchIdstring (uuid)Required
Its launch.
step.entities[].namestring or nullRequired
Name.
step.finishedAtstring (date-time) or nullRequired
Finished.
step.idstringRequired
Step.
step.kindstringRequired
A tool call, narration before tools, summarized reasoning, a web search (detail is the query) or a web page read (detail is its URL).One of tool, note, thinking, search, fetch
step.labelstringRequired
Present tense while running, past tense when done.
step.serverstring
The Pluto product an mcp step used, e.g. Pluto Profit.
step.startedAtstring (date-time)Required
Started.
step.statusstringRequired
State.One of running, done, failed, awaiting_approval, rejected, stopped
step.toolstring or nullRequired
The MCP tool; null for every kind but tool.
stepIdstring
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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 '{}'
POST/agent/approvals/{id}/decision

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.

Permission: writeApp session onlyCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe approval's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

decisionstringRequired
Approve it, or reject it.One of approve, reject
reasonstring
Why you rejected it, up to 1000 characters; the Agent reads it.

Response200 OK

canApprovebooleanRequired
You can approve it: the same as canDecide.
canDecidebooleanRequired
You may approve or reject it now: you hold capability and may use the Agent. Checked again when you decide and when it runs.
capabilitystringRequired
What approving or rejecting it needs, as a capability ID (ads:publish). The person who asked doesn't hold it.
createdAtstring (date-time)Required
Proposed.
decidedAtstring (date-time) or nullRequired
Decided.
decidedByobject or nullRequired
Who approved or rejected it; null while it waits, or once it was taken back.
decidedBy.idstring (uuid)Required
Person.
decidedBy.namestring or nullRequired
Their name now; null once their account is gone.
effectobjectRequired
effect.donestringRequired
The same once it ran.
effect.entitiesarray of objectsRequired
What it changes.
effect.entities[].idstring (uuid)Required
ID.
effect.entities[].kindstringRequired
Kind.One of launch, adSet, ad
effect.entities[].launchIdstring (uuid)Required
Its launch.
effect.entities[].namestring or nullRequired
Name.
effect.linesarray of objectsRequired
Human details, never field names or IDs.
effect.lines[].labelstringRequired
A human label.
effect.lines[].valuestringRequired
Its value.
effect.moneyarray of objectsRequired
Amounts it spends or sets.
effect.money[].amountstringRequired
A decimal amount; never a float.
effect.money[].currencystring or nullRequired
ISO 4217; null when the account's currency isn't known.
effect.money[].labelstringRequired
Label.
effect.subjectstring
What it acts on, one quiet line under the title; absent for most actions.
effect.summarystringRequired
What it does, in a sentence; empty when that would only repeat title.
effect.titlestringRequired
The action as one sentence with real names, never IDs.
effect.warningsarray of stringsRequired
Things to know before approving.
errorobject or nullRequired
Why it failed, or the reason it was rejected.
error.codestringRequired
Stable code.
error.messagestringRequired
For the person.
error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
expiresAtstring (date-time)Required
Until when approving it runs it (a day after it was proposed); rejecting still clears it after.
idstring (uuid)Required
Approval.
permissionstringRequired
The coarse permission the call asked with. What deciding needs is capability.One of read, review, write, publish, admin, organization
proposedByobject or nullRequired
Who asked: the person the Agent proposed it for.
proposedBy.idstring (uuid)Required
Person.
proposedBy.namestring or nullRequired
Their name now; null once their account is gone.
resultobject or nullRequired
After approving.
result.jobIdstring (uuid) or nullRequired
The job it started.
result.summarystringRequired
What happened.
statusstringRequired
State. superseded: the person who asked took it back.One of pending, approved, rejected, failed, superseded
titlestringRequired
What it does, as one sentence with real names and never IDs. The same as effect.title.
toolstringRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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."
  }'
POST/agent/approvals/{id}/reject

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.

Permission: writeApp session onlyCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe approval's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

reasonstring
Up to 1000 characters; the Agent reads it.

Response200 OK

approvalobject
approval.canApprovebooleanRequired
The viewer can approve it: the same as canDecide.
approval.canDecidebooleanRequired
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.capabilitystringRequired
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.chatIdstring (uuid)Required
Chat.
approval.createdAtstring (date-time)Required
Proposed.
approval.decidedAtstring (date-time) or nullRequired
Decided.
approval.effectobjectRequired
approval.effect.donestringRequired
The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approval.effect.entitiesarray of objectsRequired
What it changes.
approval.effect.entities[].idstring (uuid)Required
ID.
approval.effect.entities[].kindstringRequired
Kind.One of launch, adSet, ad
approval.effect.entities[].launchIdstring (uuid)Required
Its launch.
approval.effect.entities[].namestring or nullRequired
Name.
approval.effect.linesarray of objectsRequired
Human details, never field names or IDs.
approval.effect.lines[].labelstringRequired
A human label, e.g. Trigger.
approval.effect.lines[].valuestringRequired
Its value, e.g. New comment.
approval.effect.moneyarray of objectsRequired
Amounts it spends or sets.
approval.effect.money[].amountstringRequired
A decimal amount; never a float.
approval.effect.money[].currencystring or nullRequired
ISO 4217; null when the account's currency isn't known.
approval.effect.money[].labelstringRequired
Label.
approval.effect.subjectstring
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.summarystringRequired
What it does, in a sentence; empty when that would only repeat title.
approval.effect.titlestringRequired
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.warningsarray of stringsRequired
Things to know before approving.
approval.errorobject or nullRequired
Why it failed, or the reason it was declined.
approval.error.codestringRequired
Stable code.
approval.error.messagestringRequired
For the person.
approval.error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
approval.idstring (uuid)Required
Approval.
approval.messageIdstring (uuid)Required
The answer that proposed it.
approval.permissionstringRequired
The coarse permission the call asked with: the action's own (read, review or write only when the person chose Ask every time). What deciding needs is capability.One of read, review, write, publish, admin, organization
approval.resultobject or nullRequired
After approving.
approval.result.jobIdstring (uuid) or nullRequired
The job it started.
approval.result.summarystringRequired
What happened.
approval.statusstringRequired
State.One of pending, approved, rejected, failed, superseded
approval.titlestringRequired
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.toolstringRequired
The MCP tool it runs.
chatobject
chat.createdAtstring (date-time)Required
Started.
chat.effortstring or nullRequired
The reasoning effort picked for the chat; null: the model's default.
chat.idstring (uuid)Required
Chat.
chat.lastMessageAtstring (date-time) or nullRequired
Last message.
chat.loopIdstring (uuid) or nullRequired
The loop it is the history of (it made the loop, or was started in its builder).
chat.modelstringRequired
The chat's model: pluto, auto or a model ID from GET /agent/models.
chat.ownerIdstring (uuid)Required
The chat's person: only they rename, delete or share it.
chat.sharedbooleanRequired
Shared with everyone who can see its loop; false: private to its person.
chat.sourcestringRequired
Where it started.One of page, panel, home, loop
chat.statusstringRequired
What it's doing.One of idle, running, awaiting_approval
chat.titlestring or nullRequired
Title; null until the first answer names it.
chat.unreadbooleanRequired
An answer arrived after the person last read it.
chat.updatedAtstring (date-time)Required
Last change.
codestring
error: spend_limit, payment_required, model_unavailable, rate_limited, refusal, max_tokens, step_limit or internal.
deltastring
Text to append.
messageobject
message.approvalIdsarray of strings (uuid)Required
Approvals raised in this answer.
message.attachmentsarray of objectsRequired
Files the person attached.
message.attachments[].contentTypestring
A chat file's type.
message.attachments[].fileIdstring (uuid)
A chat file, uploaded for the message.
message.attachments[].kindstringRequired
Kind (a media library item is an image or a video).One of image, video, pdf, document, spreadsheet, presentation, text, code, audio, archive
message.attachments[].mediaIdstring (uuid)
A media library item.
message.attachments[].namestringRequired
File name.
message.attachments[].pageCountinteger
Pages of a PDF, Word document or presentation.
message.attachments[].previewUrlstring
A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
message.attachments[].sizeBytesinteger
A chat file's size.
message.chatIdstring (uuid)Required
Chat.
message.completedAtstring (date-time) or nullRequired
Finished.
message.createdAtstring (date-time)Required
Written.
message.errorobject or nullRequired
Why the answer failed.
message.error.codestringRequired
Stable code.
message.error.messagestringRequired
For the person.
message.error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
message.idstring (uuid)Required
Message.
message.modelstring or nullRequired
The model that produced the answer; null for the person's messages.
message.partsarray of objectsRequired
The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
message.parts[].answerstring
question: the answer once given (a choice's label, or the words of your reply).
message.parts[].choiceIdstring
question: the choice it was answered with.
message.parts[].choicesarray of objects
question: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).
message.parts[].columnsarray of objects
table: its columns.
message.parts[].dataarray of objects
Every kind but combo and table: the series.
message.parts[].descriptionstring
One line under the title: the period, the unit.
message.parts[].groupsarray of objects
combo: its groups.
message.parts[].idstringRequired
The part; the same ID again replaces it.
message.parts[].itemsarray of objects
ads: the ads, in the order shown.
message.parts[].kindstring
How it's drawn; table is a table.One of line, bar, horizontal-bar, stacked-bar, stacked-area, donut, funnel, combo, simple-bar, simple-normalized, spark-line, spark-bar, table
message.parts[].optionsarray of objects
selection: the options (POST /agent/chats/{id}/parts/{part_id}/select).
message.parts[].periodobject
ads: the days of its metrics: since, until and preset (last_30_days, …, or null).
message.parts[].proposedarray of strings
selection: the options the Agent recommends, checked at first.
message.parts[].rowsarray of objects
table: its rows.
message.parts[].selectedarray of strings
selection: the options you confirmed.
message.parts[].showLegendboolean
Whether a legend shows; absent: for two or more series.
message.parts[].sizestring
simple-normalized only.One of small, medium, large
message.parts[].textstring
question: the question. text: the words (Markdown).
message.parts[].titlestring
What it shows.
message.parts[].typestringRequired
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[].valueFormatobject
How values read: style (decimal, percent with values as percentages, currency with currency), notation, minimumFractionDigits, maximumFractionDigits, unit.
message.parts[].xAxisobject
label, hide.
message.parts[].yAxisobject
label, integersOnly.
message.rolestringRequired
Who wrote it.One of user, assistant
message.sentBystring (uuid) or nullRequired
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.sourcesarray of objectsRequired
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[].sitestringRequired
The hostname without www..
message.sources[].titlestringRequired
Its title (its site when it named none).
message.sources[].urlstringRequired
The page.
message.statusstringRequired
State: waiting for credits; awaiting_user when the answer asked a question or proposed a selection (parts) and waits for your reply.One of complete, streaming, stopped, failed, awaiting_approval, waiting, awaiting_user
message.stepsarray of objectsRequired
What the Agent did, in order.
message.steps[].categorystring
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), mcp for another Pluto product (server). Absent for narration and thinking, and on older steps.One of write, edit, read, list, search, mcp, other
message.steps[].detailstring or nullRequired
Error, reasoning or narration text; a search's query; a read page's URL.
message.steps[].entitiesarray of objectsRequired
What it touched.
message.steps[].entities[].idstring (uuid)Required
ID.
message.steps[].entities[].kindstringRequired
Kind.One of launch, adSet, ad
message.steps[].entities[].launchIdstring (uuid)Required
Its launch.
message.steps[].entities[].namestring or nullRequired
Name.
message.steps[].finishedAtstring (date-time) or nullRequired
Finished.
message.steps[].idstringRequired
Step.
message.steps[].kindstringRequired
A tool call, narration before tools, summarized reasoning, a web search (detail is the query) or a web page read (detail is its URL).One of tool, note, thinking, search, fetch
message.steps[].labelstringRequired
Present tense while running, past tense when done.
message.steps[].serverstring
The Pluto product an mcp step used, e.g. Pluto Profit.
message.steps[].startedAtstring (date-time)Required
Started.
message.steps[].statusstringRequired
State.One of running, done, failed, awaiting_approval, rejected, stopped
message.steps[].toolstring or nullRequired
The MCP tool; null for every kind but tool.
message.textstringRequired
The question, or the answer (markdown; pluto: links name launches, ad sets and ads).
message.versionintegerRequired
Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
message.versionsintegerRequired
How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
message.workedMsinteger or nullRequired
Active time, excluding waits for approval.
messageIdstring (uuid)
The Agent message a delta belongs to.
partobject
part.answerstring
question: the answer once given (a choice's label, or the words of your reply).
part.choiceIdstring
question: the choice it was answered with.
part.choicesarray of objects
question: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).
part.columnsarray of objects
table: its columns.
part.dataarray of objects
Every kind but combo and table: the series.
part.descriptionstring
One line under the title: the period, the unit.
part.groupsarray of objects
combo: its groups.
part.idstringRequired
The part; the same ID again replaces it.
part.itemsarray of objects
ads: the ads, in the order shown.
part.kindstring
How it's drawn; table is a table.One of line, bar, horizontal-bar, stacked-bar, stacked-area, donut, funnel, combo, simple-bar, simple-normalized, spark-line, spark-bar, table
part.optionsarray of objects
selection: the options (POST /agent/chats/{id}/parts/{part_id}/select).
part.periodobject
ads: the days of its metrics: since, until and preset (last_30_days, …, or null).
part.proposedarray of strings
selection: the options the Agent recommends, checked at first.
part.rowsarray of objects
table: its rows.
part.selectedarray of strings
selection: the options you confirmed.
part.showLegendboolean
Whether a legend shows; absent: for two or more series.
part.sizestring
simple-normalized only.One of small, medium, large
part.textstring
question: the question. text: the words (Markdown).
part.titlestring
What it shows.
part.typestringRequired
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.valueFormatobject
How values read: style (decimal, percent with values as percentages, currency with currency), notation, minimumFractionDigits, maximumFractionDigits, unit.
part.xAxisobject
label, hide.
part.yAxisobject
label, integersOnly.
reasonstring or null
error with spend_limit: which limit stopped it (member_limit, workspace_limit or trial_cap); with payment_required: why there's no access.
retryableboolean
error: whether retrying can help.
sourcesarray of objects
sources events: the answer's web pages so far.
sources[].sitestringRequired
The hostname without www..
sources[].titlestringRequired
Its title (its site when it named none).
sources[].urlstringRequired
The page.
stallobject or null
stall: 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) or silent_tool (a tool reported nothing for 45 s), and since, when the silence began (epoch milliseconds); null once it moves again.
stall.kindstringRequired
What went quiet.One of no_first_byte, silent_stream, silent_tool
stall.sinceintegerRequired
When the silence began, epoch milliseconds.
stepobject
step.categorystring
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), mcp for another Pluto product (server). Absent for narration and thinking, and on older steps.One of write, edit, read, list, search, mcp, other
step.detailstring or nullRequired
Error, reasoning or narration text; a search's query; a read page's URL.
step.entitiesarray of objectsRequired
What it touched.
step.entities[].idstring (uuid)Required
ID.
step.entities[].kindstringRequired
Kind.One of launch, adSet, ad
step.entities[].launchIdstring (uuid)Required
Its launch.
step.entities[].namestring or nullRequired
Name.
step.finishedAtstring (date-time) or nullRequired
Finished.
step.idstringRequired
Step.
step.kindstringRequired
A tool call, narration before tools, summarized reasoning, a web search (detail is the query) or a web page read (detail is its URL).One of tool, note, thinking, search, fetch
step.labelstringRequired
Present tense while running, past tense when done.
step.serverstring
The Pluto product an mcp step used, e.g. Pluto Profit.
step.startedAtstring (date-time)Required
Started.
step.statusstringRequired
State.One of running, done, failed, awaiting_approval, rejected, stopped
step.toolstring or nullRequired
The MCP tool; null for every kind but tool.
stepIdstring
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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."
  }'
GET/agent/chat-links

The signed-in person's shared chats in this workspace, the latest shared or updated first, each with its title.

Permission: write

Parameters

NameTypeRequiredDescription
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
The person's shared chats.
items[].chatIdstring (uuid)Required
The chat.
items[].createdAtstring (date-time)Required
First shared.
items[].idstring (uuid)Required
The link.
items[].messagesintegerRequired
Messages in the snapshot.
items[].newerbooleanRequired
The chat has messages the link doesn't show yet.
items[].pathstringRequired
The app path it opens in the workspace (/share/<token>).
items[].titlestring or nullRequired
The chat's title; null until the first answer names it.
items[].tokenstringRequired
The link's own ID, separate from the chat's: the last part of its address.
items[].updatedAtstring (date-time)Required
Shared or last updated: the snapshot holds the messages up to then.
items[].urlstring or nullRequired
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.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/agent/chat-links" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/agent/chats

List chats

Chats with at least one message, most recently updated first.

Permission: read

Parameters

NameTypeRequiredDescription
afterquerystringOptionalCursor: nextAfter of the previous page.
limitquerystringOptionalPage size (1-500).
qquerystringOptionalFilters titles (case-insensitive).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
This page.
items[].createdAtstring (date-time)Required
Started.
items[].effortstring or nullRequired
The reasoning effort picked for the chat; null: the model's default.
items[].idstring (uuid)Required
Chat.
items[].lastMessageAtstring (date-time) or nullRequired
Last message.
items[].loopIdstring (uuid) or nullRequired
The loop it is the history of (it made the loop, or was started in its builder).
items[].modelstringRequired
The chat's model: pluto, auto or a model ID from GET /agent/models.
items[].ownerIdstring (uuid)Required
The chat's person: only they rename, delete or share it.
items[].sharedbooleanRequired
Shared with everyone who can see its loop; false: private to its person.
items[].sourcestringRequired
Where it started.One of page, panel, home, loop
items[].statusstringRequired
What it's doing.One of idle, running, awaiting_approval
items[].titlestring or nullRequired
Title; null until the first answer names it.
items[].unreadbooleanRequired
An answer arrived after the person last read it.
items[].updatedAtstring (date-time)Required
Last change.
nextAfterstring or integer or null
Cursor for the next page; null at the end.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/agent/chats" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/agent/chats

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).

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

effortstring
A reasoning effort the model accepts (efforts in GET /agent/models); 422 on effort otherwise.One of low, medium, high, xhigh, max
modelstring
pluto, auto or a model ID from GET /agent/models; when absent, the caller's last choice, else the first model in their picker. Refused (422 on model) when it can't run here or the workspace doesn't allow it.
sourcestring
Where the chat started (loop: a loop's builder; use POST /loops/{id}/chat to attach it).One of page, panel, home, loop

Response201 Created

approvalsarray of objectsRequired
The approvals these messages carry.
approvals[].canApprovebooleanRequired
The viewer can approve it: the same as canDecide.
approvals[].canDecidebooleanRequired
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[].capabilitystringRequired
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[].chatIdstring (uuid)Required
Chat.
approvals[].createdAtstring (date-time)Required
Proposed.
approvals[].decidedAtstring (date-time) or nullRequired
Decided.
approvals[].effectobjectRequired
approvals[].effect.donestringRequired
The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approvals[].effect.entitiesarray of objectsRequired
What it changes.
approvals[].effect.entities[].idstring (uuid)Required
ID.
approvals[].effect.entities[].kindstringRequired
Kind.One of launch, adSet, ad
approvals[].effect.entities[].launchIdstring (uuid)Required
Its launch.
approvals[].effect.entities[].namestring or nullRequired
Name.
approvals[].effect.linesarray of objectsRequired
Human details, never field names or IDs.
approvals[].effect.lines[].labelstringRequired
A human label, e.g. Trigger.
approvals[].effect.lines[].valuestringRequired
Its value, e.g. New comment.
approvals[].effect.moneyarray of objectsRequired
Amounts it spends or sets.
approvals[].effect.money[].amountstringRequired
A decimal amount; never a float.
approvals[].effect.money[].currencystring or nullRequired
ISO 4217; null when the account's currency isn't known.
approvals[].effect.money[].labelstringRequired
Label.
approvals[].effect.subjectstring
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.summarystringRequired
What it does, in a sentence; empty when that would only repeat title.
approvals[].effect.titlestringRequired
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.warningsarray of stringsRequired
Things to know before approving.
approvals[].errorobject or nullRequired
Why it failed, or the reason it was declined.
approvals[].error.codestringRequired
Stable code.
approvals[].error.messagestringRequired
For the person.
approvals[].error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
approvals[].idstring (uuid)Required
Approval.
approvals[].messageIdstring (uuid)Required
The answer that proposed it.
approvals[].permissionstringRequired
The coarse permission the call asked with: the action's own (read, review or write only when the person chose Ask every time). What deciding needs is capability.One of read, review, write, publish, admin, organization
approvals[].resultobject or nullRequired
After approving.
approvals[].result.jobIdstring (uuid) or nullRequired
The job it started.
approvals[].result.summarystringRequired
What happened.
approvals[].statusstringRequired
State.One of pending, approved, rejected, failed, superseded
approvals[].titlestringRequired
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[].toolstringRequired
The MCP tool it runs.
createdAtstring (date-time)Required
Started.
effortstring or nullRequired
The reasoning effort picked for the chat; null: the model's default.
hasEarlierbooleanRequired
Older messages exist: ?before=<first message id>.
idstring (uuid)Required
Chat.
lastMessageAtstring (date-time) or nullRequired
Last message.
loopIdstring (uuid) or nullRequired
The loop it is the history of (it made the loop, or was started in its builder).
messagesarray of objectsRequired
The newest page (100 by default), oldest first.
messages[].approvalIdsarray of strings (uuid)Required
Approvals raised in this answer.
messages[].attachmentsarray of objectsRequired
Files the person attached.
messages[].attachments[].contentTypestring
A chat file's type.
messages[].attachments[].fileIdstring (uuid)
A chat file, uploaded for the message.
messages[].attachments[].kindstringRequired
Kind (a media library item is an image or a video).One of image, video, pdf, document, spreadsheet, presentation, text, code, audio, archive
messages[].attachments[].mediaIdstring (uuid)
A media library item.
messages[].attachments[].namestringRequired
File name.
messages[].attachments[].pageCountinteger
Pages of a PDF, Word document or presentation.
messages[].attachments[].previewUrlstring
A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
messages[].attachments[].sizeBytesinteger
A chat file's size.
messages[].chatIdstring (uuid)Required
Chat.
messages[].completedAtstring (date-time) or nullRequired
Finished.
messages[].createdAtstring (date-time)Required
Written.
messages[].errorobject or nullRequired
Why the answer failed.
messages[].error.codestringRequired
Stable code.
messages[].error.messagestringRequired
For the person.
messages[].error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
messages[].idstring (uuid)Required
Message.
messages[].modelstring or nullRequired
The model that produced the answer; null for the person's messages.
messages[].partsarray of objectsRequired
The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
messages[].parts[].answerstring
question: the answer once given (a choice's label, or the words of your reply).
messages[].parts[].choiceIdstring
question: the choice it was answered with.
messages[].parts[].choicesarray of objects
question: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).
messages[].parts[].columnsarray of objects
table: its columns.
messages[].parts[].dataarray of objects
Every kind but combo and table: the series.
messages[].parts[].descriptionstring
One line under the title: the period, the unit.
messages[].parts[].groupsarray of objects
combo: its groups.
messages[].parts[].idstringRequired
The part; the same ID again replaces it.
messages[].parts[].itemsarray of objects
ads: the ads, in the order shown.
messages[].parts[].kindstring
How it's drawn; table is a table.One of line, bar, horizontal-bar, stacked-bar, stacked-area, donut, funnel, combo, simple-bar, simple-normalized, spark-line, spark-bar, table
messages[].parts[].optionsarray of objects
selection: the options (POST /agent/chats/{id}/parts/{part_id}/select).
messages[].parts[].periodobject
ads: the days of its metrics: since, until and preset (last_30_days, …, or null).
messages[].parts[].proposedarray of strings
selection: the options the Agent recommends, checked at first.
messages[].parts[].rowsarray of objects
table: its rows.
messages[].parts[].selectedarray of strings
selection: the options you confirmed.
messages[].parts[].showLegendboolean
Whether a legend shows; absent: for two or more series.
messages[].parts[].sizestring
simple-normalized only.One of small, medium, large
messages[].parts[].textstring
question: the question. text: the words (Markdown).
messages[].parts[].titlestring
What it shows.
messages[].parts[].typestringRequired
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[].valueFormatobject
How values read: style (decimal, percent with values as percentages, currency with currency), notation, minimumFractionDigits, maximumFractionDigits, unit.
messages[].parts[].xAxisobject
label, hide.
messages[].parts[].yAxisobject
label, integersOnly.
messages[].rolestringRequired
Who wrote it.One of user, assistant
messages[].sentBystring (uuid) or nullRequired
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[].sourcesarray of objectsRequired
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[].sitestringRequired
The hostname without www..
messages[].sources[].titlestringRequired
Its title (its site when it named none).
messages[].sources[].urlstringRequired
The page.
messages[].statusstringRequired
State: waiting for credits; awaiting_user when the answer asked a question or proposed a selection (parts) and waits for your reply.One of complete, streaming, stopped, failed, awaiting_approval, waiting, awaiting_user
messages[].stepsarray of objectsRequired
What the Agent did, in order.
messages[].steps[].categorystring
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), mcp for another Pluto product (server). Absent for narration and thinking, and on older steps.One of write, edit, read, list, search, mcp, other
messages[].steps[].detailstring or nullRequired
Error, reasoning or narration text; a search's query; a read page's URL.
messages[].steps[].entitiesarray of objectsRequired
What it touched.
messages[].steps[].entities[].idstring (uuid)Required
ID.
messages[].steps[].entities[].kindstringRequired
Kind.One of launch, adSet, ad
messages[].steps[].entities[].launchIdstring (uuid)Required
Its launch.
messages[].steps[].entities[].namestring or nullRequired
Name.
messages[].steps[].finishedAtstring (date-time) or nullRequired
Finished.
messages[].steps[].idstringRequired
Step.
messages[].steps[].kindstringRequired
A tool call, narration before tools, summarized reasoning, a web search (detail is the query) or a web page read (detail is its URL).One of tool, note, thinking, search, fetch
messages[].steps[].labelstringRequired
Present tense while running, past tense when done.
messages[].steps[].serverstring
The Pluto product an mcp step used, e.g. Pluto Profit.
messages[].steps[].startedAtstring (date-time)Required
Started.
messages[].steps[].statusstringRequired
State.One of running, done, failed, awaiting_approval, rejected, stopped
messages[].steps[].toolstring or nullRequired
The MCP tool; null for every kind but tool.
messages[].textstringRequired
The question, or the answer (markdown; pluto: links name launches, ad sets and ads).
messages[].versionintegerRequired
Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
messages[].versionsintegerRequired
How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
messages[].workedMsinteger or nullRequired
Active time, excluding waits for approval.
modelstringRequired
The chat's model: pluto, auto or a model ID from GET /agent/models.
ownerIdstring (uuid)Required
The chat's person: only they rename, delete or share it.
sharedbooleanRequired
Shared with everyone who can see its loop; false: private to its person.
sourcestringRequired
Where it started.One of page, panel, home, loop
statusstringRequired
What it's doing.One of idle, running, awaiting_approval
titlestring or nullRequired
Title; null until the first answer names it.
unreadbooleanRequired
An answer arrived after the person last read it.
updatedAtstring (date-time)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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/agent/chats/{id}

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.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe chat's ID.
beforequerystringOptionalA message ID: the messages before it.
limitquerystringOptional1-200; 100 by default.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

approvalsarray of objectsRequired
The approvals these messages carry.
approvals[].canApprovebooleanRequired
The viewer can approve it: the same as canDecide.
approvals[].canDecidebooleanRequired
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[].capabilitystringRequired
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[].chatIdstring (uuid)Required
Chat.
approvals[].createdAtstring (date-time)Required
Proposed.
approvals[].decidedAtstring (date-time) or nullRequired
Decided.
approvals[].effectobjectRequired
approvals[].effect.donestringRequired
The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approvals[].effect.entitiesarray of objectsRequired
What it changes.
approvals[].effect.entities[].idstring (uuid)Required
ID.
approvals[].effect.entities[].kindstringRequired
Kind.One of launch, adSet, ad
approvals[].effect.entities[].launchIdstring (uuid)Required
Its launch.
approvals[].effect.entities[].namestring or nullRequired
Name.
approvals[].effect.linesarray of objectsRequired
Human details, never field names or IDs.
approvals[].effect.lines[].labelstringRequired
A human label, e.g. Trigger.
approvals[].effect.lines[].valuestringRequired
Its value, e.g. New comment.
approvals[].effect.moneyarray of objectsRequired
Amounts it spends or sets.
approvals[].effect.money[].amountstringRequired
A decimal amount; never a float.
approvals[].effect.money[].currencystring or nullRequired
ISO 4217; null when the account's currency isn't known.
approvals[].effect.money[].labelstringRequired
Label.
approvals[].effect.subjectstring
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.summarystringRequired
What it does, in a sentence; empty when that would only repeat title.
approvals[].effect.titlestringRequired
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.warningsarray of stringsRequired
Things to know before approving.
approvals[].errorobject or nullRequired
Why it failed, or the reason it was declined.
approvals[].error.codestringRequired
Stable code.
approvals[].error.messagestringRequired
For the person.
approvals[].error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
approvals[].idstring (uuid)Required
Approval.
approvals[].messageIdstring (uuid)Required
The answer that proposed it.
approvals[].permissionstringRequired
The coarse permission the call asked with: the action's own (read, review or write only when the person chose Ask every time). What deciding needs is capability.One of read, review, write, publish, admin, organization
approvals[].resultobject or nullRequired
After approving.
approvals[].result.jobIdstring (uuid) or nullRequired
The job it started.
approvals[].result.summarystringRequired
What happened.
approvals[].statusstringRequired
State.One of pending, approved, rejected, failed, superseded
approvals[].titlestringRequired
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[].toolstringRequired
The MCP tool it runs.
createdAtstring (date-time)Required
Started.
effortstring or nullRequired
The reasoning effort picked for the chat; null: the model's default.
hasEarlierbooleanRequired
Older messages exist: ?before=<first message id>.
idstring (uuid)Required
Chat.
lastMessageAtstring (date-time) or nullRequired
Last message.
loopIdstring (uuid) or nullRequired
The loop it is the history of (it made the loop, or was started in its builder).
messagesarray of objectsRequired
The newest page (100 by default), oldest first.
messages[].approvalIdsarray of strings (uuid)Required
Approvals raised in this answer.
messages[].attachmentsarray of objectsRequired
Files the person attached.
messages[].attachments[].contentTypestring
A chat file's type.
messages[].attachments[].fileIdstring (uuid)
A chat file, uploaded for the message.
messages[].attachments[].kindstringRequired
Kind (a media library item is an image or a video).One of image, video, pdf, document, spreadsheet, presentation, text, code, audio, archive
messages[].attachments[].mediaIdstring (uuid)
A media library item.
messages[].attachments[].namestringRequired
File name.
messages[].attachments[].pageCountinteger
Pages of a PDF, Word document or presentation.
messages[].attachments[].previewUrlstring
A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
messages[].attachments[].sizeBytesinteger
A chat file's size.
messages[].chatIdstring (uuid)Required
Chat.
messages[].completedAtstring (date-time) or nullRequired
Finished.
messages[].createdAtstring (date-time)Required
Written.
messages[].errorobject or nullRequired
Why the answer failed.
messages[].error.codestringRequired
Stable code.
messages[].error.messagestringRequired
For the person.
messages[].error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
messages[].idstring (uuid)Required
Message.
messages[].modelstring or nullRequired
The model that produced the answer; null for the person's messages.
messages[].partsarray of objectsRequired
The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
messages[].parts[].answerstring
question: the answer once given (a choice's label, or the words of your reply).
messages[].parts[].choiceIdstring
question: the choice it was answered with.
messages[].parts[].choicesarray of objects
question: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).
messages[].parts[].columnsarray of objects
table: its columns.
messages[].parts[].dataarray of objects
Every kind but combo and table: the series.
messages[].parts[].descriptionstring
One line under the title: the period, the unit.
messages[].parts[].groupsarray of objects
combo: its groups.
messages[].parts[].idstringRequired
The part; the same ID again replaces it.
messages[].parts[].itemsarray of objects
ads: the ads, in the order shown.
messages[].parts[].kindstring
How it's drawn; table is a table.One of line, bar, horizontal-bar, stacked-bar, stacked-area, donut, funnel, combo, simple-bar, simple-normalized, spark-line, spark-bar, table
messages[].parts[].optionsarray of objects
selection: the options (POST /agent/chats/{id}/parts/{part_id}/select).
messages[].parts[].periodobject
ads: the days of its metrics: since, until and preset (last_30_days, …, or null).
messages[].parts[].proposedarray of strings
selection: the options the Agent recommends, checked at first.
messages[].parts[].rowsarray of objects
table: its rows.
messages[].parts[].selectedarray of strings
selection: the options you confirmed.
messages[].parts[].showLegendboolean
Whether a legend shows; absent: for two or more series.
messages[].parts[].sizestring
simple-normalized only.One of small, medium, large
messages[].parts[].textstring
question: the question. text: the words (Markdown).
messages[].parts[].titlestring
What it shows.
messages[].parts[].typestringRequired
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[].valueFormatobject
How values read: style (decimal, percent with values as percentages, currency with currency), notation, minimumFractionDigits, maximumFractionDigits, unit.
messages[].parts[].xAxisobject
label, hide.
messages[].parts[].yAxisobject
label, integersOnly.
messages[].rolestringRequired
Who wrote it.One of user, assistant
messages[].sentBystring (uuid) or nullRequired
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[].sourcesarray of objectsRequired
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[].sitestringRequired
The hostname without www..
messages[].sources[].titlestringRequired
Its title (its site when it named none).
messages[].sources[].urlstringRequired
The page.
messages[].statusstringRequired
State: waiting for credits; awaiting_user when the answer asked a question or proposed a selection (parts) and waits for your reply.One of complete, streaming, stopped, failed, awaiting_approval, waiting, awaiting_user
messages[].stepsarray of objectsRequired
What the Agent did, in order.
messages[].steps[].categorystring
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), mcp for another Pluto product (server). Absent for narration and thinking, and on older steps.One of write, edit, read, list, search, mcp, other
messages[].steps[].detailstring or nullRequired
Error, reasoning or narration text; a search's query; a read page's URL.
messages[].steps[].entitiesarray of objectsRequired
What it touched.
messages[].steps[].entities[].idstring (uuid)Required
ID.
messages[].steps[].entities[].kindstringRequired
Kind.One of launch, adSet, ad
messages[].steps[].entities[].launchIdstring (uuid)Required
Its launch.
messages[].steps[].entities[].namestring or nullRequired
Name.
messages[].steps[].finishedAtstring (date-time) or nullRequired
Finished.
messages[].steps[].idstringRequired
Step.
messages[].steps[].kindstringRequired
A tool call, narration before tools, summarized reasoning, a web search (detail is the query) or a web page read (detail is its URL).One of tool, note, thinking, search, fetch
messages[].steps[].labelstringRequired
Present tense while running, past tense when done.
messages[].steps[].serverstring
The Pluto product an mcp step used, e.g. Pluto Profit.
messages[].steps[].startedAtstring (date-time)Required
Started.
messages[].steps[].statusstringRequired
State.One of running, done, failed, awaiting_approval, rejected, stopped
messages[].steps[].toolstring or nullRequired
The MCP tool; null for every kind but tool.
messages[].textstringRequired
The question, or the answer (markdown; pluto: links name launches, ad sets and ads).
messages[].versionintegerRequired
Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
messages[].versionsintegerRequired
How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
messages[].workedMsinteger or nullRequired
Active time, excluding waits for approval.
modelstringRequired
The chat's model: pluto, auto or a model ID from GET /agent/models.
ownerIdstring (uuid)Required
The chat's person: only they rename, delete or share it.
sharedbooleanRequired
Shared with everyone who can see its loop; false: private to its person.
sourcestringRequired
Where it started.One of page, panel, home, loop
statusstringRequired
What it's doing.One of idle, running, awaiting_approval
titlestring or nullRequired
Title; null until the first answer names it.
unreadbooleanRequired
An answer arrived after the person last read it.
updatedAtstring (date-time)Required
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-After seconds. 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"
PATCH/agent/chats/{id}

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.

Permission: readCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe chat's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

sharedboolean
Share a loop's chat with the people who can see the loop (true) or stop sharing it (false).
titlestring
1-120 characters.

Response200 OK

createdAtstring (date-time)Required
Started.
effortstring or nullRequired
The reasoning effort picked for the chat; null: the model's default.
idstring (uuid)Required
Chat.
lastMessageAtstring (date-time) or nullRequired
Last message.
loopIdstring (uuid) or nullRequired
The loop it is the history of (it made the loop, or was started in its builder).
modelstringRequired
The chat's model: pluto, auto or a model ID from GET /agent/models.
ownerIdstring (uuid)Required
The chat's person: only they rename, delete or share it.
sharedbooleanRequired
Shared with everyone who can see its loop; false: private to its person.
sourcestringRequired
Where it started.One of page, panel, home, loop
statusstringRequired
What it's doing.One of idle, running, awaiting_approval
titlestring or nullRequired
Title; null until the first answer names it.
unreadbooleanRequired
An answer arrived after the person last read it.
updatedAtstring (date-time)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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/agent/chats/{id}

Delete a chat

Stops a running answer first; the chat's messages and approvals are deleted.

Permission: readCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe chat's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response204 No Content

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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
GET/agent/chats/{id}/feedback

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.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe chat's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
items[].commentstring or nullRequired
Kept only while the organization has "Help improve Pluto's AI" on; null otherwise.
items[].messageIdstring (uuid)Required
The rated answer.
items[].ratingstringRequired
Thumbs up or down.One of up, down
items[].reasonstring or nullRequired
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[].updatedAtstring (date-time)Required
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-After seconds. 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/agent/chats/{id}/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.

Permission: write

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe chat's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

linkobject or nullRequired
The link, or null.
link.chatIdstring (uuid)Required
The chat.
link.createdAtstring (date-time)Required
First shared.
link.idstring (uuid)Required
The link.
link.messagesintegerRequired
Messages in the snapshot.
link.newerbooleanRequired
The chat has messages the link doesn't show yet.
link.pathstringRequired
The app path it opens in the workspace (/share/<token>).
link.tokenstringRequired
The link's own ID, separate from the chat's: the last part of its address.
link.updatedAtstring (date-time)Required
Shared or last updated: the snapshot holds the messages up to then.
link.urlstring or nullRequired
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-After seconds. 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"
PUT/agent/chats/{id}/link

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe chat's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

chatIdstring (uuid)Required
The chat.
createdAtstring (date-time)Required
First shared.
idstring (uuid)Required
The link.
messagesintegerRequired
Messages in the snapshot.
newerbooleanRequired
The chat has messages the link doesn't show yet.
pathstringRequired
The app path it opens in the workspace (/share/<token>).
tokenstringRequired
The link's own ID, separate from the chat's: the last part of its address.
updatedAtstring (date-time)Required
Shared or last updated: the snapshot holds the messages up to then.
urlstring or nullRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
DELETE/agent/chats/{id}/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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe chat's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response204 No Content

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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
POST/agent/chats/{id}/messages

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe chat's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

contextobject
context.adIdstring (uuid)
The open ad.
context.fileIdsarray of strings (uuid)
Chat files attached to the question (POST /workspaces/{id}/chat-files), each ready: 409 while one is still being prepared, 422 for one that failed or isn't yours. Up to 20 files in all, with mediaIds.
context.launchIdstring (uuid)
The open launch.
context.loopIdstring (uuid)
The loop open in the builder: the Agent reads its current definition.
context.mediaIdsarray of strings (uuid)
Media library items attached to the question.
context.pathstring
The app page the person is on.
context.selectedStepIdsarray of strings
Steps selected on the builder's canvas (up to 50): what "this step" means.
effortstring
A reasoning effort the model accepts (efforts in GET /agent/models); 422 on effort otherwise.One of low, medium, high, xhigh, max
modelstring
pluto, auto or a model ID from GET /agent/models: the chat runs on it from here on. Refused (422 on model) when it can't run here or the workspace doesn't allow it.
textstringRequired
1-16000 characters.

Response200 OK

approvalobject
approval.canApprovebooleanRequired
The viewer can approve it: the same as canDecide.
approval.canDecidebooleanRequired
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.capabilitystringRequired
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.chatIdstring (uuid)Required
Chat.
approval.createdAtstring (date-time)Required
Proposed.
approval.decidedAtstring (date-time) or nullRequired
Decided.
approval.effectobjectRequired
approval.effect.donestringRequired
The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approval.effect.entitiesarray of objectsRequired
What it changes.
approval.effect.entities[].idstring (uuid)Required
ID.
approval.effect.entities[].kindstringRequired
Kind.One of launch, adSet, ad
approval.effect.entities[].launchIdstring (uuid)Required
Its launch.
approval.effect.entities[].namestring or nullRequired
Name.
approval.effect.linesarray of objectsRequired
Human details, never field names or IDs.
approval.effect.lines[].labelstringRequired
A human label, e.g. Trigger.
approval.effect.lines[].valuestringRequired
Its value, e.g. New comment.
approval.effect.moneyarray of objectsRequired
Amounts it spends or sets.
approval.effect.money[].amountstringRequired
A decimal amount; never a float.
approval.effect.money[].currencystring or nullRequired
ISO 4217; null when the account's currency isn't known.
approval.effect.money[].labelstringRequired
Label.
approval.effect.subjectstring
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.summarystringRequired
What it does, in a sentence; empty when that would only repeat title.
approval.effect.titlestringRequired
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.warningsarray of stringsRequired
Things to know before approving.
approval.errorobject or nullRequired
Why it failed, or the reason it was declined.
approval.error.codestringRequired
Stable code.
approval.error.messagestringRequired
For the person.
approval.error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
approval.idstring (uuid)Required
Approval.
approval.messageIdstring (uuid)Required
The answer that proposed it.
approval.permissionstringRequired
The coarse permission the call asked with: the action's own (read, review or write only when the person chose Ask every time). What deciding needs is capability.One of read, review, write, publish, admin, organization
approval.resultobject or nullRequired
After approving.
approval.result.jobIdstring (uuid) or nullRequired
The job it started.
approval.result.summarystringRequired
What happened.
approval.statusstringRequired
State.One of pending, approved, rejected, failed, superseded
approval.titlestringRequired
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.toolstringRequired
The MCP tool it runs.
chatobject
chat.createdAtstring (date-time)Required
Started.
chat.effortstring or nullRequired
The reasoning effort picked for the chat; null: the model's default.
chat.idstring (uuid)Required
Chat.
chat.lastMessageAtstring (date-time) or nullRequired
Last message.
chat.loopIdstring (uuid) or nullRequired
The loop it is the history of (it made the loop, or was started in its builder).
chat.modelstringRequired
The chat's model: pluto, auto or a model ID from GET /agent/models.
chat.ownerIdstring (uuid)Required
The chat's person: only they rename, delete or share it.
chat.sharedbooleanRequired
Shared with everyone who can see its loop; false: private to its person.
chat.sourcestringRequired
Where it started.One of page, panel, home, loop
chat.statusstringRequired
What it's doing.One of idle, running, awaiting_approval
chat.titlestring or nullRequired
Title; null until the first answer names it.
chat.unreadbooleanRequired
An answer arrived after the person last read it.
chat.updatedAtstring (date-time)Required
Last change.
codestring
error: spend_limit, payment_required, model_unavailable, rate_limited, refusal, max_tokens, step_limit or internal.
deltastring
Text to append.
messageobject
message.approvalIdsarray of strings (uuid)Required
Approvals raised in this answer.
message.attachmentsarray of objectsRequired
Files the person attached.
message.attachments[].contentTypestring
A chat file's type.
message.attachments[].fileIdstring (uuid)
A chat file, uploaded for the message.
message.attachments[].kindstringRequired
Kind (a media library item is an image or a video).One of image, video, pdf, document, spreadsheet, presentation, text, code, audio, archive
message.attachments[].mediaIdstring (uuid)
A media library item.
message.attachments[].namestringRequired
File name.
message.attachments[].pageCountinteger
Pages of a PDF, Word document or presentation.
message.attachments[].previewUrlstring
A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
message.attachments[].sizeBytesinteger
A chat file's size.
message.chatIdstring (uuid)Required
Chat.
message.completedAtstring (date-time) or nullRequired
Finished.
message.createdAtstring (date-time)Required
Written.
message.errorobject or nullRequired
Why the answer failed.
message.error.codestringRequired
Stable code.
message.error.messagestringRequired
For the person.
message.error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
message.idstring (uuid)Required
Message.
message.modelstring or nullRequired
The model that produced the answer; null for the person's messages.
message.partsarray of objectsRequired
The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
message.parts[].answerstring
question: the answer once given (a choice's label, or the words of your reply).
message.parts[].choiceIdstring
question: the choice it was answered with.
message.parts[].choicesarray of objects
question: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).
message.parts[].columnsarray of objects
table: its columns.
message.parts[].dataarray of objects
Every kind but combo and table: the series.
message.parts[].descriptionstring
One line under the title: the period, the unit.
message.parts[].groupsarray of objects
combo: its groups.
message.parts[].idstringRequired
The part; the same ID again replaces it.
message.parts[].itemsarray of objects
ads: the ads, in the order shown.
message.parts[].kindstring
How it's drawn; table is a table.One of line, bar, horizontal-bar, stacked-bar, stacked-area, donut, funnel, combo, simple-bar, simple-normalized, spark-line, spark-bar, table
message.parts[].optionsarray of objects
selection: the options (POST /agent/chats/{id}/parts/{part_id}/select).
message.parts[].periodobject
ads: the days of its metrics: since, until and preset (last_30_days, …, or null).
message.parts[].proposedarray of strings
selection: the options the Agent recommends, checked at first.
message.parts[].rowsarray of objects
table: its rows.
message.parts[].selectedarray of strings
selection: the options you confirmed.
message.parts[].showLegendboolean
Whether a legend shows; absent: for two or more series.
message.parts[].sizestring
simple-normalized only.One of small, medium, large
message.parts[].textstring
question: the question. text: the words (Markdown).
message.parts[].titlestring
What it shows.
message.parts[].typestringRequired
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[].valueFormatobject
How values read: style (decimal, percent with values as percentages, currency with currency), notation, minimumFractionDigits, maximumFractionDigits, unit.
message.parts[].xAxisobject
label, hide.
message.parts[].yAxisobject
label, integersOnly.
message.rolestringRequired
Who wrote it.One of user, assistant
message.sentBystring (uuid) or nullRequired
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.sourcesarray of objectsRequired
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[].sitestringRequired
The hostname without www..
message.sources[].titlestringRequired
Its title (its site when it named none).
message.sources[].urlstringRequired
The page.
message.statusstringRequired
State: waiting for credits; awaiting_user when the answer asked a question or proposed a selection (parts) and waits for your reply.One of complete, streaming, stopped, failed, awaiting_approval, waiting, awaiting_user
message.stepsarray of objectsRequired
What the Agent did, in order.
message.steps[].categorystring
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), mcp for another Pluto product (server). Absent for narration and thinking, and on older steps.One of write, edit, read, list, search, mcp, other
message.steps[].detailstring or nullRequired
Error, reasoning or narration text; a search's query; a read page's URL.
message.steps[].entitiesarray of objectsRequired
What it touched.
message.steps[].entities[].idstring (uuid)Required
ID.
message.steps[].entities[].kindstringRequired
Kind.One of launch, adSet, ad
message.steps[].entities[].launchIdstring (uuid)Required
Its launch.
message.steps[].entities[].namestring or nullRequired
Name.
message.steps[].finishedAtstring (date-time) or nullRequired
Finished.
message.steps[].idstringRequired
Step.
message.steps[].kindstringRequired
A tool call, narration before tools, summarized reasoning, a web search (detail is the query) or a web page read (detail is its URL).One of tool, note, thinking, search, fetch
message.steps[].labelstringRequired
Present tense while running, past tense when done.
message.steps[].serverstring
The Pluto product an mcp step used, e.g. Pluto Profit.
message.steps[].startedAtstring (date-time)Required
Started.
message.steps[].statusstringRequired
State.One of running, done, failed, awaiting_approval, rejected, stopped
message.steps[].toolstring or nullRequired
The MCP tool; null for every kind but tool.
message.textstringRequired
The question, or the answer (markdown; pluto: links name launches, ad sets and ads).
message.versionintegerRequired
Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
message.versionsintegerRequired
How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
message.workedMsinteger or nullRequired
Active time, excluding waits for approval.
messageIdstring (uuid)
The Agent message a delta belongs to.
partobject
part.answerstring
question: the answer once given (a choice's label, or the words of your reply).
part.choiceIdstring
question: the choice it was answered with.
part.choicesarray of objects
question: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).
part.columnsarray of objects
table: its columns.
part.dataarray of objects
Every kind but combo and table: the series.
part.descriptionstring
One line under the title: the period, the unit.
part.groupsarray of objects
combo: its groups.
part.idstringRequired
The part; the same ID again replaces it.
part.itemsarray of objects
ads: the ads, in the order shown.
part.kindstring
How it's drawn; table is a table.One of line, bar, horizontal-bar, stacked-bar, stacked-area, donut, funnel, combo, simple-bar, simple-normalized, spark-line, spark-bar, table
part.optionsarray of objects
selection: the options (POST /agent/chats/{id}/parts/{part_id}/select).
part.periodobject
ads: the days of its metrics: since, until and preset (last_30_days, …, or null).
part.proposedarray of strings
selection: the options the Agent recommends, checked at first.
part.rowsarray of objects
table: its rows.
part.selectedarray of strings
selection: the options you confirmed.
part.showLegendboolean
Whether a legend shows; absent: for two or more series.
part.sizestring
simple-normalized only.One of small, medium, large
part.textstring
question: the question. text: the words (Markdown).
part.titlestring
What it shows.
part.typestringRequired
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.valueFormatobject
How values read: style (decimal, percent with values as percentages, currency with currency), notation, minimumFractionDigits, maximumFractionDigits, unit.
part.xAxisobject
label, hide.
part.yAxisobject
label, integersOnly.
reasonstring or null
error with spend_limit: which limit stopped it (member_limit, workspace_limit or trial_cap); with payment_required: why there's no access.
retryableboolean
error: whether retrying can help.
sourcesarray of objects
sources events: the answer's web pages so far.
sources[].sitestringRequired
The hostname without www..
sources[].titlestringRequired
Its title (its site when it named none).
sources[].urlstringRequired
The page.
stallobject or null
stall: 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) or silent_tool (a tool reported nothing for 45 s), and since, when the silence began (epoch milliseconds); null once it moves again.
stall.kindstringRequired
What went quiet.One of no_first_byte, silent_stream, silent_tool
stall.sinceintegerRequired
When the silence began, epoch milliseconds.
stepobject
step.categorystring
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), mcp for another Pluto product (server). Absent for narration and thinking, and on older steps.One of write, edit, read, list, search, mcp, other
step.detailstring or nullRequired
Error, reasoning or narration text; a search's query; a read page's URL.
step.entitiesarray of objectsRequired
What it touched.
step.entities[].idstring (uuid)Required
ID.
step.entities[].kindstringRequired
Kind.One of launch, adSet, ad
step.entities[].launchIdstring (uuid)Required
Its launch.
step.entities[].namestring or nullRequired
Name.
step.finishedAtstring (date-time) or nullRequired
Finished.
step.idstringRequired
Step.
step.kindstringRequired
A tool call, narration before tools, summarized reasoning, a web search (detail is the query) or a web page read (detail is its URL).One of tool, note, thinking, search, fetch
step.labelstringRequired
Present tense while running, past tense when done.
step.serverstring
The Pluto product an mcp step used, e.g. Pluto Profit.
step.startedAtstring (date-time)Required
Started.
step.statusstringRequired
State.One of running, done, failed, awaiting_approval, rejected, stopped
step.toolstring or nullRequired
The MCP tool; null for every kind but tool.
stepIdstring
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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?"
  }'
POST/agent/chats/{id}/messages/{message_id}/edit

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe chat's ID.
message_idpathstringRequiredThe message's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

contextobject
context.adIdstring (uuid)
The open ad.
context.fileIdsarray of strings (uuid)
Chat files attached, each ready.
context.launchIdstring (uuid)
The open launch.
context.loopIdstring (uuid)
The loop open in the builder.
context.mediaIdsarray of strings (uuid)
Media library items attached.
context.pathstring
The app page the person is on.
context.selectedStepIdsarray of strings
Steps selected on the builder's canvas (up to 50).
effortstring
A reasoning effort the model accepts.One of low, medium, high, xhigh, max
modelstring
pluto, auto or a model ID from GET /agent/models: the chat runs on it from here on.
textstringRequired
1-16000 characters.

Response200 OK

approvalobject
approval.canApprovebooleanRequired
The viewer can approve it: the same as canDecide.
approval.canDecidebooleanRequired
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.capabilitystringRequired
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.chatIdstring (uuid)Required
Chat.
approval.createdAtstring (date-time)Required
Proposed.
approval.decidedAtstring (date-time) or nullRequired
Decided.
approval.effectobjectRequired
approval.effect.donestringRequired
The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approval.effect.entitiesarray of objectsRequired
What it changes.
approval.effect.entities[].idstring (uuid)Required
ID.
approval.effect.entities[].kindstringRequired
Kind.One of launch, adSet, ad
approval.effect.entities[].launchIdstring (uuid)Required
Its launch.
approval.effect.entities[].namestring or nullRequired
Name.
approval.effect.linesarray of objectsRequired
Human details, never field names or IDs.
approval.effect.lines[].labelstringRequired
A human label, e.g. Trigger.
approval.effect.lines[].valuestringRequired
Its value, e.g. New comment.
approval.effect.moneyarray of objectsRequired
Amounts it spends or sets.
approval.effect.money[].amountstringRequired
A decimal amount; never a float.
approval.effect.money[].currencystring or nullRequired
ISO 4217; null when the account's currency isn't known.
approval.effect.money[].labelstringRequired
Label.
approval.effect.subjectstring
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.summarystringRequired
What it does, in a sentence; empty when that would only repeat title.
approval.effect.titlestringRequired
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.warningsarray of stringsRequired
Things to know before approving.
approval.errorobject or nullRequired
Why it failed, or the reason it was declined.
approval.error.codestringRequired
Stable code.
approval.error.messagestringRequired
For the person.
approval.error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
approval.idstring (uuid)Required
Approval.
approval.messageIdstring (uuid)Required
The answer that proposed it.
approval.permissionstringRequired
The coarse permission the call asked with: the action's own (read, review or write only when the person chose Ask every time). What deciding needs is capability.One of read, review, write, publish, admin, organization
approval.resultobject or nullRequired
After approving.
approval.result.jobIdstring (uuid) or nullRequired
The job it started.
approval.result.summarystringRequired
What happened.
approval.statusstringRequired
State.One of pending, approved, rejected, failed, superseded
approval.titlestringRequired
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.toolstringRequired
The MCP tool it runs.
chatobject
chat.createdAtstring (date-time)Required
Started.
chat.effortstring or nullRequired
The reasoning effort picked for the chat; null: the model's default.
chat.idstring (uuid)Required
Chat.
chat.lastMessageAtstring (date-time) or nullRequired
Last message.
chat.loopIdstring (uuid) or nullRequired
The loop it is the history of (it made the loop, or was started in its builder).
chat.modelstringRequired
The chat's model: pluto, auto or a model ID from GET /agent/models.
chat.ownerIdstring (uuid)Required
The chat's person: only they rename, delete or share it.
chat.sharedbooleanRequired
Shared with everyone who can see its loop; false: private to its person.
chat.sourcestringRequired
Where it started.One of page, panel, home, loop
chat.statusstringRequired
What it's doing.One of idle, running, awaiting_approval
chat.titlestring or nullRequired
Title; null until the first answer names it.
chat.unreadbooleanRequired
An answer arrived after the person last read it.
chat.updatedAtstring (date-time)Required
Last change.
codestring
error: spend_limit, payment_required, model_unavailable, rate_limited, refusal, max_tokens, step_limit or internal.
deltastring
Text to append.
messageobject
message.approvalIdsarray of strings (uuid)Required
Approvals raised in this answer.
message.attachmentsarray of objectsRequired
Files the person attached.
message.attachments[].contentTypestring
A chat file's type.
message.attachments[].fileIdstring (uuid)
A chat file, uploaded for the message.
message.attachments[].kindstringRequired
Kind (a media library item is an image or a video).One of image, video, pdf, document, spreadsheet, presentation, text, code, audio, archive
message.attachments[].mediaIdstring (uuid)
A media library item.
message.attachments[].namestringRequired
File name.
message.attachments[].pageCountinteger
Pages of a PDF, Word document or presentation.
message.attachments[].previewUrlstring
A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
message.attachments[].sizeBytesinteger
A chat file's size.
message.chatIdstring (uuid)Required
Chat.
message.completedAtstring (date-time) or nullRequired
Finished.
message.createdAtstring (date-time)Required
Written.
message.errorobject or nullRequired
Why the answer failed.
message.error.codestringRequired
Stable code.
message.error.messagestringRequired
For the person.
message.error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
message.idstring (uuid)Required
Message.
message.modelstring or nullRequired
The model that produced the answer; null for the person's messages.
message.partsarray of objectsRequired
The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
message.parts[].answerstring
question: the answer once given (a choice's label, or the words of your reply).
message.parts[].choiceIdstring
question: the choice it was answered with.
message.parts[].choicesarray of objects
question: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).
message.parts[].columnsarray of objects
table: its columns.
message.parts[].dataarray of objects
Every kind but combo and table: the series.
message.parts[].descriptionstring
One line under the title: the period, the unit.
message.parts[].groupsarray of objects
combo: its groups.
message.parts[].idstringRequired
The part; the same ID again replaces it.
message.parts[].itemsarray of objects
ads: the ads, in the order shown.
message.parts[].kindstring
How it's drawn; table is a table.One of line, bar, horizontal-bar, stacked-bar, stacked-area, donut, funnel, combo, simple-bar, simple-normalized, spark-line, spark-bar, table
message.parts[].optionsarray of objects
selection: the options (POST /agent/chats/{id}/parts/{part_id}/select).
message.parts[].periodobject
ads: the days of its metrics: since, until and preset (last_30_days, …, or null).
message.parts[].proposedarray of strings
selection: the options the Agent recommends, checked at first.
message.parts[].rowsarray of objects
table: its rows.
message.parts[].selectedarray of strings
selection: the options you confirmed.
message.parts[].showLegendboolean
Whether a legend shows; absent: for two or more series.
message.parts[].sizestring
simple-normalized only.One of small, medium, large
message.parts[].textstring
question: the question. text: the words (Markdown).
message.parts[].titlestring
What it shows.
message.parts[].typestringRequired
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[].valueFormatobject
How values read: style (decimal, percent with values as percentages, currency with currency), notation, minimumFractionDigits, maximumFractionDigits, unit.
message.parts[].xAxisobject
label, hide.
message.parts[].yAxisobject
label, integersOnly.
message.rolestringRequired
Who wrote it.One of user, assistant
message.sentBystring (uuid) or nullRequired
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.sourcesarray of objectsRequired
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[].sitestringRequired
The hostname without www..
message.sources[].titlestringRequired
Its title (its site when it named none).
message.sources[].urlstringRequired
The page.
message.statusstringRequired
State: waiting for credits; awaiting_user when the answer asked a question or proposed a selection (parts) and waits for your reply.One of complete, streaming, stopped, failed, awaiting_approval, waiting, awaiting_user
message.stepsarray of objectsRequired
What the Agent did, in order.
message.steps[].categorystring
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), mcp for another Pluto product (server). Absent for narration and thinking, and on older steps.One of write, edit, read, list, search, mcp, other
message.steps[].detailstring or nullRequired
Error, reasoning or narration text; a search's query; a read page's URL.
message.steps[].entitiesarray of objectsRequired
What it touched.
message.steps[].entities[].idstring (uuid)Required
ID.
message.steps[].entities[].kindstringRequired
Kind.One of launch, adSet, ad
message.steps[].entities[].launchIdstring (uuid)Required
Its launch.
message.steps[].entities[].namestring or nullRequired
Name.
message.steps[].finishedAtstring (date-time) or nullRequired
Finished.
message.steps[].idstringRequired
Step.
message.steps[].kindstringRequired
A tool call, narration before tools, summarized reasoning, a web search (detail is the query) or a web page read (detail is its URL).One of tool, note, thinking, search, fetch
message.steps[].labelstringRequired
Present tense while running, past tense when done.
message.steps[].serverstring
The Pluto product an mcp step used, e.g. Pluto Profit.
message.steps[].startedAtstring (date-time)Required
Started.
message.steps[].statusstringRequired
State.One of running, done, failed, awaiting_approval, rejected, stopped
message.steps[].toolstring or nullRequired
The MCP tool; null for every kind but tool.
message.textstringRequired
The question, or the answer (markdown; pluto: links name launches, ad sets and ads).
message.versionintegerRequired
Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
message.versionsintegerRequired
How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
message.workedMsinteger or nullRequired
Active time, excluding waits for approval.
messageIdstring (uuid)
The Agent message a delta belongs to.
partobject
part.answerstring
question: the answer once given (a choice's label, or the words of your reply).
part.choiceIdstring
question: the choice it was answered with.
part.choicesarray of objects
question: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).
part.columnsarray of objects
table: its columns.
part.dataarray of objects
Every kind but combo and table: the series.
part.descriptionstring
One line under the title: the period, the unit.
part.groupsarray of objects
combo: its groups.
part.idstringRequired
The part; the same ID again replaces it.
part.itemsarray of objects
ads: the ads, in the order shown.
part.kindstring
How it's drawn; table is a table.One of line, bar, horizontal-bar, stacked-bar, stacked-area, donut, funnel, combo, simple-bar, simple-normalized, spark-line, spark-bar, table
part.optionsarray of objects
selection: the options (POST /agent/chats/{id}/parts/{part_id}/select).
part.periodobject
ads: the days of its metrics: since, until and preset (last_30_days, …, or null).
part.proposedarray of strings
selection: the options the Agent recommends, checked at first.
part.rowsarray of objects
table: its rows.
part.selectedarray of strings
selection: the options you confirmed.
part.showLegendboolean
Whether a legend shows; absent: for two or more series.
part.sizestring
simple-normalized only.One of small, medium, large
part.textstring
question: the question. text: the words (Markdown).
part.titlestring
What it shows.
part.typestringRequired
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.valueFormatobject
How values read: style (decimal, percent with values as percentages, currency with currency), notation, minimumFractionDigits, maximumFractionDigits, unit.
part.xAxisobject
label, hide.
part.yAxisobject
label, integersOnly.
reasonstring or null
error with spend_limit: which limit stopped it (member_limit, workspace_limit or trial_cap); with payment_required: why there's no access.
retryableboolean
error: whether retrying can help.
sourcesarray of objects
sources events: the answer's web pages so far.
sources[].sitestringRequired
The hostname without www..
sources[].titlestringRequired
Its title (its site when it named none).
sources[].urlstringRequired
The page.
stallobject or null
stall: 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) or silent_tool (a tool reported nothing for 45 s), and since, when the silence began (epoch milliseconds); null once it moves again.
stall.kindstringRequired
What went quiet.One of no_first_byte, silent_stream, silent_tool
stall.sinceintegerRequired
When the silence began, epoch milliseconds.
stepobject
step.categorystring
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), mcp for another Pluto product (server). Absent for narration and thinking, and on older steps.One of write, edit, read, list, search, mcp, other
step.detailstring or nullRequired
Error, reasoning or narration text; a search's query; a read page's URL.
step.entitiesarray of objectsRequired
What it touched.
step.entities[].idstring (uuid)Required
ID.
step.entities[].kindstringRequired
Kind.One of launch, adSet, ad
step.entities[].launchIdstring (uuid)Required
Its launch.
step.entities[].namestring or nullRequired
Name.
step.finishedAtstring (date-time) or nullRequired
Finished.
step.idstringRequired
Step.
step.kindstringRequired
A tool call, narration before tools, summarized reasoning, a web search (detail is the query) or a web page read (detail is its URL).One of tool, note, thinking, search, fetch
step.labelstringRequired
Present tense while running, past tense when done.
step.serverstring
The Pluto product an mcp step used, e.g. Pluto Profit.
step.startedAtstring (date-time)Required
Started.
step.statusstringRequired
State.One of running, done, failed, awaiting_approval, rejected, stopped
step.toolstring or nullRequired
The MCP tool; null for every kind but tool.
stepIdstring
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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?"
  }'
PUT/agent/chats/{id}/messages/{message_id}/feedback

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe chat's ID.
message_idpathstringRequiredThe message's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

commentstring
Optional; kept only with "Help improve Pluto's AI" on.
ratingstringRequired
Thumbs up or down.One of up, down
reasonstring
Why it was rated down (ignored for a thumbs up).One of wrong_answer, ignored_request, wrong_changes, too_slow, other

Response200 OK

commentstring or nullRequired
Kept only while the organization has "Help improve Pluto's AI" on; null otherwise.
messageIdstring (uuid)Required
The rated answer.
ratingstringRequired
Thumbs up or down.One of up, down
reasonstring or nullRequired
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
updatedAtstring (date-time)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
  }'
DELETE/agent/chats/{id}/messages/{message_id}/feedback

Clear your rating

Removes your rating of the answer. Clearing one that isn't there succeeds too.

Permission: write

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe chat's ID.
message_idpathstringRequiredThe message's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response204 No Content

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-After seconds. 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"
POST/agent/chats/{id}/messages/{message_id}/retry

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe chat's ID.
message_idpathstringRequiredThe message's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

approvalobject
approval.canApprovebooleanRequired
The viewer can approve it: the same as canDecide.
approval.canDecidebooleanRequired
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.capabilitystringRequired
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.chatIdstring (uuid)Required
Chat.
approval.createdAtstring (date-time)Required
Proposed.
approval.decidedAtstring (date-time) or nullRequired
Decided.
approval.effectobjectRequired
approval.effect.donestringRequired
The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approval.effect.entitiesarray of objectsRequired
What it changes.
approval.effect.entities[].idstring (uuid)Required
ID.
approval.effect.entities[].kindstringRequired
Kind.One of launch, adSet, ad
approval.effect.entities[].launchIdstring (uuid)Required
Its launch.
approval.effect.entities[].namestring or nullRequired
Name.
approval.effect.linesarray of objectsRequired
Human details, never field names or IDs.
approval.effect.lines[].labelstringRequired
A human label, e.g. Trigger.
approval.effect.lines[].valuestringRequired
Its value, e.g. New comment.
approval.effect.moneyarray of objectsRequired
Amounts it spends or sets.
approval.effect.money[].amountstringRequired
A decimal amount; never a float.
approval.effect.money[].currencystring or nullRequired
ISO 4217; null when the account's currency isn't known.
approval.effect.money[].labelstringRequired
Label.
approval.effect.subjectstring
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.summarystringRequired
What it does, in a sentence; empty when that would only repeat title.
approval.effect.titlestringRequired
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.warningsarray of stringsRequired
Things to know before approving.
approval.errorobject or nullRequired
Why it failed, or the reason it was declined.
approval.error.codestringRequired
Stable code.
approval.error.messagestringRequired
For the person.
approval.error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
approval.idstring (uuid)Required
Approval.
approval.messageIdstring (uuid)Required
The answer that proposed it.
approval.permissionstringRequired
The coarse permission the call asked with: the action's own (read, review or write only when the person chose Ask every time). What deciding needs is capability.One of read, review, write, publish, admin, organization
approval.resultobject or nullRequired
After approving.
approval.result.jobIdstring (uuid) or nullRequired
The job it started.
approval.result.summarystringRequired
What happened.
approval.statusstringRequired
State.One of pending, approved, rejected, failed, superseded
approval.titlestringRequired
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.toolstringRequired
The MCP tool it runs.
chatobject
chat.createdAtstring (date-time)Required
Started.
chat.effortstring or nullRequired
The reasoning effort picked for the chat; null: the model's default.
chat.idstring (uuid)Required
Chat.
chat.lastMessageAtstring (date-time) or nullRequired
Last message.
chat.loopIdstring (uuid) or nullRequired
The loop it is the history of (it made the loop, or was started in its builder).
chat.modelstringRequired
The chat's model: pluto, auto or a model ID from GET /agent/models.
chat.ownerIdstring (uuid)Required
The chat's person: only they rename, delete or share it.
chat.sharedbooleanRequired
Shared with everyone who can see its loop; false: private to its person.
chat.sourcestringRequired
Where it started.One of page, panel, home, loop
chat.statusstringRequired
What it's doing.One of idle, running, awaiting_approval
chat.titlestring or nullRequired
Title; null until the first answer names it.
chat.unreadbooleanRequired
An answer arrived after the person last read it.
chat.updatedAtstring (date-time)Required
Last change.
codestring
error: spend_limit, payment_required, model_unavailable, rate_limited, refusal, max_tokens, step_limit or internal.
deltastring
Text to append.
messageobject
message.approvalIdsarray of strings (uuid)Required
Approvals raised in this answer.
message.attachmentsarray of objectsRequired
Files the person attached.
message.attachments[].contentTypestring
A chat file's type.
message.attachments[].fileIdstring (uuid)
A chat file, uploaded for the message.
message.attachments[].kindstringRequired
Kind (a media library item is an image or a video).One of image, video, pdf, document, spreadsheet, presentation, text, code, audio, archive
message.attachments[].mediaIdstring (uuid)
A media library item.
message.attachments[].namestringRequired
File name.
message.attachments[].pageCountinteger
Pages of a PDF, Word document or presentation.
message.attachments[].previewUrlstring
A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
message.attachments[].sizeBytesinteger
A chat file's size.
message.chatIdstring (uuid)Required
Chat.
message.completedAtstring (date-time) or nullRequired
Finished.
message.createdAtstring (date-time)Required
Written.
message.errorobject or nullRequired
Why the answer failed.
message.error.codestringRequired
Stable code.
message.error.messagestringRequired
For the person.
message.error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
message.idstring (uuid)Required
Message.
message.modelstring or nullRequired
The model that produced the answer; null for the person's messages.
message.partsarray of objectsRequired
The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
message.parts[].answerstring
question: the answer once given (a choice's label, or the words of your reply).
message.parts[].choiceIdstring
question: the choice it was answered with.
message.parts[].choicesarray of objects
question: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).
message.parts[].columnsarray of objects
table: its columns.
message.parts[].dataarray of objects
Every kind but combo and table: the series.
message.parts[].descriptionstring
One line under the title: the period, the unit.
message.parts[].groupsarray of objects
combo: its groups.
message.parts[].idstringRequired
The part; the same ID again replaces it.
message.parts[].itemsarray of objects
ads: the ads, in the order shown.
message.parts[].kindstring
How it's drawn; table is a table.One of line, bar, horizontal-bar, stacked-bar, stacked-area, donut, funnel, combo, simple-bar, simple-normalized, spark-line, spark-bar, table
message.parts[].optionsarray of objects
selection: the options (POST /agent/chats/{id}/parts/{part_id}/select).
message.parts[].periodobject
ads: the days of its metrics: since, until and preset (last_30_days, …, or null).
message.parts[].proposedarray of strings
selection: the options the Agent recommends, checked at first.
message.parts[].rowsarray of objects
table: its rows.
message.parts[].selectedarray of strings
selection: the options you confirmed.
message.parts[].showLegendboolean
Whether a legend shows; absent: for two or more series.
message.parts[].sizestring
simple-normalized only.One of small, medium, large
message.parts[].textstring
question: the question. text: the words (Markdown).
message.parts[].titlestring
What it shows.
message.parts[].typestringRequired
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[].valueFormatobject
How values read: style (decimal, percent with values as percentages, currency with currency), notation, minimumFractionDigits, maximumFractionDigits, unit.
message.parts[].xAxisobject
label, hide.
message.parts[].yAxisobject
label, integersOnly.
message.rolestringRequired
Who wrote it.One of user, assistant
message.sentBystring (uuid) or nullRequired
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.sourcesarray of objectsRequired
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[].sitestringRequired
The hostname without www..
message.sources[].titlestringRequired
Its title (its site when it named none).
message.sources[].urlstringRequired
The page.
message.statusstringRequired
State: waiting for credits; awaiting_user when the answer asked a question or proposed a selection (parts) and waits for your reply.One of complete, streaming, stopped, failed, awaiting_approval, waiting, awaiting_user
message.stepsarray of objectsRequired
What the Agent did, in order.
message.steps[].categorystring
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), mcp for another Pluto product (server). Absent for narration and thinking, and on older steps.One of write, edit, read, list, search, mcp, other
message.steps[].detailstring or nullRequired
Error, reasoning or narration text; a search's query; a read page's URL.
message.steps[].entitiesarray of objectsRequired
What it touched.
message.steps[].entities[].idstring (uuid)Required
ID.
message.steps[].entities[].kindstringRequired
Kind.One of launch, adSet, ad
message.steps[].entities[].launchIdstring (uuid)Required
Its launch.
message.steps[].entities[].namestring or nullRequired
Name.
message.steps[].finishedAtstring (date-time) or nullRequired
Finished.
message.steps[].idstringRequired
Step.
message.steps[].kindstringRequired
A tool call, narration before tools, summarized reasoning, a web search (detail is the query) or a web page read (detail is its URL).One of tool, note, thinking, search, fetch
message.steps[].labelstringRequired
Present tense while running, past tense when done.
message.steps[].serverstring
The Pluto product an mcp step used, e.g. Pluto Profit.
message.steps[].startedAtstring (date-time)Required
Started.
message.steps[].statusstringRequired
State.One of running, done, failed, awaiting_approval, rejected, stopped
message.steps[].toolstring or nullRequired
The MCP tool; null for every kind but tool.
message.textstringRequired
The question, or the answer (markdown; pluto: links name launches, ad sets and ads).
message.versionintegerRequired
Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
message.versionsintegerRequired
How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
message.workedMsinteger or nullRequired
Active time, excluding waits for approval.
messageIdstring (uuid)
The Agent message a delta belongs to.
partobject
part.answerstring
question: the answer once given (a choice's label, or the words of your reply).
part.choiceIdstring
question: the choice it was answered with.
part.choicesarray of objects
question: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).
part.columnsarray of objects
table: its columns.
part.dataarray of objects
Every kind but combo and table: the series.
part.descriptionstring
One line under the title: the period, the unit.
part.groupsarray of objects
combo: its groups.
part.idstringRequired
The part; the same ID again replaces it.
part.itemsarray of objects
ads: the ads, in the order shown.
part.kindstring
How it's drawn; table is a table.One of line, bar, horizontal-bar, stacked-bar, stacked-area, donut, funnel, combo, simple-bar, simple-normalized, spark-line, spark-bar, table
part.optionsarray of objects
selection: the options (POST /agent/chats/{id}/parts/{part_id}/select).
part.periodobject
ads: the days of its metrics: since, until and preset (last_30_days, …, or null).
part.proposedarray of strings
selection: the options the Agent recommends, checked at first.
part.rowsarray of objects
table: its rows.
part.selectedarray of strings
selection: the options you confirmed.
part.showLegendboolean
Whether a legend shows; absent: for two or more series.
part.sizestring
simple-normalized only.One of small, medium, large
part.textstring
question: the question. text: the words (Markdown).
part.titlestring
What it shows.
part.typestringRequired
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.valueFormatobject
How values read: style (decimal, percent with values as percentages, currency with currency), notation, minimumFractionDigits, maximumFractionDigits, unit.
part.xAxisobject
label, hide.
part.yAxisobject
label, integersOnly.
reasonstring or null
error with spend_limit: which limit stopped it (member_limit, workspace_limit or trial_cap); with payment_required: why there's no access.
retryableboolean
error: whether retrying can help.
sourcesarray of objects
sources events: the answer's web pages so far.
sources[].sitestringRequired
The hostname without www..
sources[].titlestringRequired
Its title (its site when it named none).
sources[].urlstringRequired
The page.
stallobject or null
stall: 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) or silent_tool (a tool reported nothing for 45 s), and since, when the silence began (epoch milliseconds); null once it moves again.
stall.kindstringRequired
What went quiet.One of no_first_byte, silent_stream, silent_tool
stall.sinceintegerRequired
When the silence began, epoch milliseconds.
stepobject
step.categorystring
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), mcp for another Pluto product (server). Absent for narration and thinking, and on older steps.One of write, edit, read, list, search, mcp, other
step.detailstring or nullRequired
Error, reasoning or narration text; a search's query; a read page's URL.
step.entitiesarray of objectsRequired
What it touched.
step.entities[].idstring (uuid)Required
ID.
step.entities[].kindstringRequired
Kind.One of launch, adSet, ad
step.entities[].launchIdstring (uuid)Required
Its launch.
step.entities[].namestring or nullRequired
Name.
step.finishedAtstring (date-time) or nullRequired
Finished.
step.idstringRequired
Step.
step.kindstringRequired
A tool call, narration before tools, summarized reasoning, a web search (detail is the query) or a web page read (detail is its URL).One of tool, note, thinking, search, fetch
step.labelstringRequired
Present tense while running, past tense when done.
step.serverstring
The Pluto product an mcp step used, e.g. Pluto Profit.
step.startedAtstring (date-time)Required
Started.
step.statusstringRequired
State.One of running, done, failed, awaiting_approval, rejected, stopped
step.toolstring or nullRequired
The MCP tool; null for every kind but tool.
stepIdstring
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
POST/agent/chats/{id}/messages/{message_id}/version

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}.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe chat's ID.
message_idpathstringRequiredThe message's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

versionintegerRequired
1-based, as version on the message.

Response200 OK

approvalsarray of objectsRequired
The approvals these messages carry.
approvals[].canApprovebooleanRequired
The viewer can approve it: the same as canDecide.
approvals[].canDecidebooleanRequired
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[].capabilitystringRequired
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[].chatIdstring (uuid)Required
Chat.
approvals[].createdAtstring (date-time)Required
Proposed.
approvals[].decidedAtstring (date-time) or nullRequired
Decided.
approvals[].effectobjectRequired
approvals[].effect.donestringRequired
The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approvals[].effect.entitiesarray of objectsRequired
What it changes.
approvals[].effect.entities[].idstring (uuid)Required
ID.
approvals[].effect.entities[].kindstringRequired
Kind.One of launch, adSet, ad
approvals[].effect.entities[].launchIdstring (uuid)Required
Its launch.
approvals[].effect.entities[].namestring or nullRequired
Name.
approvals[].effect.linesarray of objectsRequired
Human details, never field names or IDs.
approvals[].effect.lines[].labelstringRequired
A human label, e.g. Trigger.
approvals[].effect.lines[].valuestringRequired
Its value, e.g. New comment.
approvals[].effect.moneyarray of objectsRequired
Amounts it spends or sets.
approvals[].effect.money[].amountstringRequired
A decimal amount; never a float.
approvals[].effect.money[].currencystring or nullRequired
ISO 4217; null when the account's currency isn't known.
approvals[].effect.money[].labelstringRequired
Label.
approvals[].effect.subjectstring
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.summarystringRequired
What it does, in a sentence; empty when that would only repeat title.
approvals[].effect.titlestringRequired
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.warningsarray of stringsRequired
Things to know before approving.
approvals[].errorobject or nullRequired
Why it failed, or the reason it was declined.
approvals[].error.codestringRequired
Stable code.
approvals[].error.messagestringRequired
For the person.
approvals[].error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
approvals[].idstring (uuid)Required
Approval.
approvals[].messageIdstring (uuid)Required
The answer that proposed it.
approvals[].permissionstringRequired
The coarse permission the call asked with: the action's own (read, review or write only when the person chose Ask every time). What deciding needs is capability.One of read, review, write, publish, admin, organization
approvals[].resultobject or nullRequired
After approving.
approvals[].result.jobIdstring (uuid) or nullRequired
The job it started.
approvals[].result.summarystringRequired
What happened.
approvals[].statusstringRequired
State.One of pending, approved, rejected, failed, superseded
approvals[].titlestringRequired
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[].toolstringRequired
The MCP tool it runs.
createdAtstring (date-time)Required
Started.
effortstring or nullRequired
The reasoning effort picked for the chat; null: the model's default.
hasEarlierbooleanRequired
Older messages exist: ?before=<first message id>.
idstring (uuid)Required
Chat.
lastMessageAtstring (date-time) or nullRequired
Last message.
loopIdstring (uuid) or nullRequired
The loop it is the history of (it made the loop, or was started in its builder).
messagesarray of objectsRequired
The newest page (100 by default), oldest first.
messages[].approvalIdsarray of strings (uuid)Required
Approvals raised in this answer.
messages[].attachmentsarray of objectsRequired
Files the person attached.
messages[].attachments[].contentTypestring
A chat file's type.
messages[].attachments[].fileIdstring (uuid)
A chat file, uploaded for the message.
messages[].attachments[].kindstringRequired
Kind (a media library item is an image or a video).One of image, video, pdf, document, spreadsheet, presentation, text, code, audio, archive
messages[].attachments[].mediaIdstring (uuid)
A media library item.
messages[].attachments[].namestringRequired
File name.
messages[].attachments[].pageCountinteger
Pages of a PDF, Word document or presentation.
messages[].attachments[].previewUrlstring
A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
messages[].attachments[].sizeBytesinteger
A chat file's size.
messages[].chatIdstring (uuid)Required
Chat.
messages[].completedAtstring (date-time) or nullRequired
Finished.
messages[].createdAtstring (date-time)Required
Written.
messages[].errorobject or nullRequired
Why the answer failed.
messages[].error.codestringRequired
Stable code.
messages[].error.messagestringRequired
For the person.
messages[].error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
messages[].idstring (uuid)Required
Message.
messages[].modelstring or nullRequired
The model that produced the answer; null for the person's messages.
messages[].partsarray of objectsRequired
The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
messages[].parts[].answerstring
question: the answer once given (a choice's label, or the words of your reply).
messages[].parts[].choiceIdstring
question: the choice it was answered with.
messages[].parts[].choicesarray of objects
question: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).
messages[].parts[].columnsarray of objects
table: its columns.
messages[].parts[].dataarray of objects
Every kind but combo and table: the series.
messages[].parts[].descriptionstring
One line under the title: the period, the unit.
messages[].parts[].groupsarray of objects
combo: its groups.
messages[].parts[].idstringRequired
The part; the same ID again replaces it.
messages[].parts[].itemsarray of objects
ads: the ads, in the order shown.
messages[].parts[].kindstring
How it's drawn; table is a table.One of line, bar, horizontal-bar, stacked-bar, stacked-area, donut, funnel, combo, simple-bar, simple-normalized, spark-line, spark-bar, table
messages[].parts[].optionsarray of objects
selection: the options (POST /agent/chats/{id}/parts/{part_id}/select).
messages[].parts[].periodobject
ads: the days of its metrics: since, until and preset (last_30_days, …, or null).
messages[].parts[].proposedarray of strings
selection: the options the Agent recommends, checked at first.
messages[].parts[].rowsarray of objects
table: its rows.
messages[].parts[].selectedarray of strings
selection: the options you confirmed.
messages[].parts[].showLegendboolean
Whether a legend shows; absent: for two or more series.
messages[].parts[].sizestring
simple-normalized only.One of small, medium, large
messages[].parts[].textstring
question: the question. text: the words (Markdown).
messages[].parts[].titlestring
What it shows.
messages[].parts[].typestringRequired
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[].valueFormatobject
How values read: style (decimal, percent with values as percentages, currency with currency), notation, minimumFractionDigits, maximumFractionDigits, unit.
messages[].parts[].xAxisobject
label, hide.
messages[].parts[].yAxisobject
label, integersOnly.
messages[].rolestringRequired
Who wrote it.One of user, assistant
messages[].sentBystring (uuid) or nullRequired
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[].sourcesarray of objectsRequired
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[].sitestringRequired
The hostname without www..
messages[].sources[].titlestringRequired
Its title (its site when it named none).
messages[].sources[].urlstringRequired
The page.
messages[].statusstringRequired
State: waiting for credits; awaiting_user when the answer asked a question or proposed a selection (parts) and waits for your reply.One of complete, streaming, stopped, failed, awaiting_approval, waiting, awaiting_user
messages[].stepsarray of objectsRequired
What the Agent did, in order.
messages[].steps[].categorystring
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), mcp for another Pluto product (server). Absent for narration and thinking, and on older steps.One of write, edit, read, list, search, mcp, other
messages[].steps[].detailstring or nullRequired
Error, reasoning or narration text; a search's query; a read page's URL.
messages[].steps[].entitiesarray of objectsRequired
What it touched.
messages[].steps[].entities[].idstring (uuid)Required
ID.
messages[].steps[].entities[].kindstringRequired
Kind.One of launch, adSet, ad
messages[].steps[].entities[].launchIdstring (uuid)Required
Its launch.
messages[].steps[].entities[].namestring or nullRequired
Name.
messages[].steps[].finishedAtstring (date-time) or nullRequired
Finished.
messages[].steps[].idstringRequired
Step.
messages[].steps[].kindstringRequired
A tool call, narration before tools, summarized reasoning, a web search (detail is the query) or a web page read (detail is its URL).One of tool, note, thinking, search, fetch
messages[].steps[].labelstringRequired
Present tense while running, past tense when done.
messages[].steps[].serverstring
The Pluto product an mcp step used, e.g. Pluto Profit.
messages[].steps[].startedAtstring (date-time)Required
Started.
messages[].steps[].statusstringRequired
State.One of running, done, failed, awaiting_approval, rejected, stopped
messages[].steps[].toolstring or nullRequired
The MCP tool; null for every kind but tool.
messages[].textstringRequired
The question, or the answer (markdown; pluto: links name launches, ad sets and ads).
messages[].versionintegerRequired
Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
messages[].versionsintegerRequired
How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
messages[].workedMsinteger or nullRequired
Active time, excluding waits for approval.
modelstringRequired
The chat's model: pluto, auto or a model ID from GET /agent/models.
ownerIdstring (uuid)Required
The chat's person: only they rename, delete or share it.
sharedbooleanRequired
Shared with everyone who can see its loop; false: private to its person.
sourcestringRequired
Where it started.One of page, panel, home, loop
statusstringRequired
What it's doing.One of idle, running, awaiting_approval
titlestring or nullRequired
Title; null until the first answer names it.
unreadbooleanRequired
An answer arrived after the person last read it.
updatedAtstring (date-time)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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
  }'
GET/agent/chats/{id}/messages/{message_id}/versions

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.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe chat's ID.
message_idpathstringRequiredThe message's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
Oldest first.
items[].attachmentsarray of objectsRequired
Its files.
items[].attachments[].contentTypestring
A chat file's type.
items[].attachments[].fileIdstring (uuid)
A chat file, uploaded for the message.
items[].attachments[].kindstringRequired
Kind (a media library item is an image or a video).One of image, video, pdf, document, spreadsheet, presentation, text, code, audio, archive
items[].attachments[].mediaIdstring (uuid)
A media library item.
items[].attachments[].namestringRequired
File name.
items[].attachments[].pageCountinteger
Pages of a PDF, Word document or presentation.
items[].attachments[].previewUrlstring
A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
items[].attachments[].sizeBytesinteger
A chat file's size.
items[].createdAtstring (date-time)Required
Sent.
items[].currentbooleanRequired
In the conversation now.
items[].idstring (uuid)Required
This version's message.
items[].textstringRequired
Its text.
items[].versionintegerRequired
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-After seconds. 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"
POST/agent/chats/{id}/parts/{part_id}/answer

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe chat's ID.
part_idpathstringRequiredThe part's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

choiceIdstringRequired
One of the question's choices[].id.

Response200 OK

approvalobject
approval.canApprovebooleanRequired
The viewer can approve it: the same as canDecide.
approval.canDecidebooleanRequired
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.capabilitystringRequired
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.chatIdstring (uuid)Required
Chat.
approval.createdAtstring (date-time)Required
Proposed.
approval.decidedAtstring (date-time) or nullRequired
Decided.
approval.effectobjectRequired
approval.effect.donestringRequired
The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approval.effect.entitiesarray of objectsRequired
What it changes.
approval.effect.entities[].idstring (uuid)Required
ID.
approval.effect.entities[].kindstringRequired
Kind.One of launch, adSet, ad
approval.effect.entities[].launchIdstring (uuid)Required
Its launch.
approval.effect.entities[].namestring or nullRequired
Name.
approval.effect.linesarray of objectsRequired
Human details, never field names or IDs.
approval.effect.lines[].labelstringRequired
A human label, e.g. Trigger.
approval.effect.lines[].valuestringRequired
Its value, e.g. New comment.
approval.effect.moneyarray of objectsRequired
Amounts it spends or sets.
approval.effect.money[].amountstringRequired
A decimal amount; never a float.
approval.effect.money[].currencystring or nullRequired
ISO 4217; null when the account's currency isn't known.
approval.effect.money[].labelstringRequired
Label.
approval.effect.subjectstring
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.summarystringRequired
What it does, in a sentence; empty when that would only repeat title.
approval.effect.titlestringRequired
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.warningsarray of stringsRequired
Things to know before approving.
approval.errorobject or nullRequired
Why it failed, or the reason it was declined.
approval.error.codestringRequired
Stable code.
approval.error.messagestringRequired
For the person.
approval.error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
approval.idstring (uuid)Required
Approval.
approval.messageIdstring (uuid)Required
The answer that proposed it.
approval.permissionstringRequired
The coarse permission the call asked with: the action's own (read, review or write only when the person chose Ask every time). What deciding needs is capability.One of read, review, write, publish, admin, organization
approval.resultobject or nullRequired
After approving.
approval.result.jobIdstring (uuid) or nullRequired
The job it started.
approval.result.summarystringRequired
What happened.
approval.statusstringRequired
State.One of pending, approved, rejected, failed, superseded
approval.titlestringRequired
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.toolstringRequired
The MCP tool it runs.
chatobject
chat.createdAtstring (date-time)Required
Started.
chat.effortstring or nullRequired
The reasoning effort picked for the chat; null: the model's default.
chat.idstring (uuid)Required
Chat.
chat.lastMessageAtstring (date-time) or nullRequired
Last message.
chat.loopIdstring (uuid) or nullRequired
The loop it is the history of (it made the loop, or was started in its builder).
chat.modelstringRequired
The chat's model: pluto, auto or a model ID from GET /agent/models.
chat.ownerIdstring (uuid)Required
The chat's person: only they rename, delete or share it.
chat.sharedbooleanRequired
Shared with everyone who can see its loop; false: private to its person.
chat.sourcestringRequired
Where it started.One of page, panel, home, loop
chat.statusstringRequired
What it's doing.One of idle, running, awaiting_approval
chat.titlestring or nullRequired
Title; null until the first answer names it.
chat.unreadbooleanRequired
An answer arrived after the person last read it.
chat.updatedAtstring (date-time)Required
Last change.
codestring
error: spend_limit, payment_required, model_unavailable, rate_limited, refusal, max_tokens, step_limit or internal.
deltastring
Text to append.
messageobject
message.approvalIdsarray of strings (uuid)Required
Approvals raised in this answer.
message.attachmentsarray of objectsRequired
Files the person attached.
message.attachments[].contentTypestring
A chat file's type.
message.attachments[].fileIdstring (uuid)
A chat file, uploaded for the message.
message.attachments[].kindstringRequired
Kind (a media library item is an image or a video).One of image, video, pdf, document, spreadsheet, presentation, text, code, audio, archive
message.attachments[].mediaIdstring (uuid)
A media library item.
message.attachments[].namestringRequired
File name.
message.attachments[].pageCountinteger
Pages of a PDF, Word document or presentation.
message.attachments[].previewUrlstring
A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
message.attachments[].sizeBytesinteger
A chat file's size.
message.chatIdstring (uuid)Required
Chat.
message.completedAtstring (date-time) or nullRequired
Finished.
message.createdAtstring (date-time)Required
Written.
message.errorobject or nullRequired
Why the answer failed.
message.error.codestringRequired
Stable code.
message.error.messagestringRequired
For the person.
message.error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
message.idstring (uuid)Required
Message.
message.modelstring or nullRequired
The model that produced the answer; null for the person's messages.
message.partsarray of objectsRequired
The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
message.parts[].answerstring
question: the answer once given (a choice's label, or the words of your reply).
message.parts[].choiceIdstring
question: the choice it was answered with.
message.parts[].choicesarray of objects
question: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).
message.parts[].columnsarray of objects
table: its columns.
message.parts[].dataarray of objects
Every kind but combo and table: the series.
message.parts[].descriptionstring
One line under the title: the period, the unit.
message.parts[].groupsarray of objects
combo: its groups.
message.parts[].idstringRequired
The part; the same ID again replaces it.
message.parts[].itemsarray of objects
ads: the ads, in the order shown.
message.parts[].kindstring
How it's drawn; table is a table.One of line, bar, horizontal-bar, stacked-bar, stacked-area, donut, funnel, combo, simple-bar, simple-normalized, spark-line, spark-bar, table
message.parts[].optionsarray of objects
selection: the options (POST /agent/chats/{id}/parts/{part_id}/select).
message.parts[].periodobject
ads: the days of its metrics: since, until and preset (last_30_days, …, or null).
message.parts[].proposedarray of strings
selection: the options the Agent recommends, checked at first.
message.parts[].rowsarray of objects
table: its rows.
message.parts[].selectedarray of strings
selection: the options you confirmed.
message.parts[].showLegendboolean
Whether a legend shows; absent: for two or more series.
message.parts[].sizestring
simple-normalized only.One of small, medium, large
message.parts[].textstring
question: the question. text: the words (Markdown).
message.parts[].titlestring
What it shows.
message.parts[].typestringRequired
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[].valueFormatobject
How values read: style (decimal, percent with values as percentages, currency with currency), notation, minimumFractionDigits, maximumFractionDigits, unit.
message.parts[].xAxisobject
label, hide.
message.parts[].yAxisobject
label, integersOnly.
message.rolestringRequired
Who wrote it.One of user, assistant
message.sentBystring (uuid) or nullRequired
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.sourcesarray of objectsRequired
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[].sitestringRequired
The hostname without www..
message.sources[].titlestringRequired
Its title (its site when it named none).
message.sources[].urlstringRequired
The page.
message.statusstringRequired
State: waiting for credits; awaiting_user when the answer asked a question or proposed a selection (parts) and waits for your reply.One of complete, streaming, stopped, failed, awaiting_approval, waiting, awaiting_user
message.stepsarray of objectsRequired
What the Agent did, in order.
message.steps[].categorystring
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), mcp for another Pluto product (server). Absent for narration and thinking, and on older steps.One of write, edit, read, list, search, mcp, other
message.steps[].detailstring or nullRequired
Error, reasoning or narration text; a search's query; a read page's URL.
message.steps[].entitiesarray of objectsRequired
What it touched.
message.steps[].entities[].idstring (uuid)Required
ID.
message.steps[].entities[].kindstringRequired
Kind.One of launch, adSet, ad
message.steps[].entities[].launchIdstring (uuid)Required
Its launch.
message.steps[].entities[].namestring or nullRequired
Name.
message.steps[].finishedAtstring (date-time) or nullRequired
Finished.
message.steps[].idstringRequired
Step.
message.steps[].kindstringRequired
A tool call, narration before tools, summarized reasoning, a web search (detail is the query) or a web page read (detail is its URL).One of tool, note, thinking, search, fetch
message.steps[].labelstringRequired
Present tense while running, past tense when done.
message.steps[].serverstring
The Pluto product an mcp step used, e.g. Pluto Profit.
message.steps[].startedAtstring (date-time)Required
Started.
message.steps[].statusstringRequired
State.One of running, done, failed, awaiting_approval, rejected, stopped
message.steps[].toolstring or nullRequired
The MCP tool; null for every kind but tool.
message.textstringRequired
The question, or the answer (markdown; pluto: links name launches, ad sets and ads).
message.versionintegerRequired
Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
message.versionsintegerRequired
How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
message.workedMsinteger or nullRequired
Active time, excluding waits for approval.
messageIdstring (uuid)
The Agent message a delta belongs to.
partobject
part.answerstring
question: the answer once given (a choice's label, or the words of your reply).
part.choiceIdstring
question: the choice it was answered with.
part.choicesarray of objects
question: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).
part.columnsarray of objects
table: its columns.
part.dataarray of objects
Every kind but combo and table: the series.
part.descriptionstring
One line under the title: the period, the unit.
part.groupsarray of objects
combo: its groups.
part.idstringRequired
The part; the same ID again replaces it.
part.itemsarray of objects
ads: the ads, in the order shown.
part.kindstring
How it's drawn; table is a table.One of line, bar, horizontal-bar, stacked-bar, stacked-area, donut, funnel, combo, simple-bar, simple-normalized, spark-line, spark-bar, table
part.optionsarray of objects
selection: the options (POST /agent/chats/{id}/parts/{part_id}/select).
part.periodobject
ads: the days of its metrics: since, until and preset (last_30_days, …, or null).
part.proposedarray of strings
selection: the options the Agent recommends, checked at first.
part.rowsarray of objects
table: its rows.
part.selectedarray of strings
selection: the options you confirmed.
part.showLegendboolean
Whether a legend shows; absent: for two or more series.
part.sizestring
simple-normalized only.One of small, medium, large
part.textstring
question: the question. text: the words (Markdown).
part.titlestring
What it shows.
part.typestringRequired
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.valueFormatobject
How values read: style (decimal, percent with values as percentages, currency with currency), notation, minimumFractionDigits, maximumFractionDigits, unit.
part.xAxisobject
label, hide.
part.yAxisobject
label, integersOnly.
reasonstring or null
error with spend_limit: which limit stopped it (member_limit, workspace_limit or trial_cap); with payment_required: why there's no access.
retryableboolean
error: whether retrying can help.
sourcesarray of objects
sources events: the answer's web pages so far.
sources[].sitestringRequired
The hostname without www..
sources[].titlestringRequired
Its title (its site when it named none).
sources[].urlstringRequired
The page.
stallobject or null
stall: 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) or silent_tool (a tool reported nothing for 45 s), and since, when the silence began (epoch milliseconds); null once it moves again.
stall.kindstringRequired
What went quiet.One of no_first_byte, silent_stream, silent_tool
stall.sinceintegerRequired
When the silence began, epoch milliseconds.
stepobject
step.categorystring
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), mcp for another Pluto product (server). Absent for narration and thinking, and on older steps.One of write, edit, read, list, search, mcp, other
step.detailstring or nullRequired
Error, reasoning or narration text; a search's query; a read page's URL.
step.entitiesarray of objectsRequired
What it touched.
step.entities[].idstring (uuid)Required
ID.
step.entities[].kindstringRequired
Kind.One of launch, adSet, ad
step.entities[].launchIdstring (uuid)Required
Its launch.
step.entities[].namestring or nullRequired
Name.
step.finishedAtstring (date-time) or nullRequired
Finished.
step.idstringRequired
Step.
step.kindstringRequired
A tool call, narration before tools, summarized reasoning, a web search (detail is the query) or a web page read (detail is its URL).One of tool, note, thinking, search, fetch
step.labelstringRequired
Present tense while running, past tense when done.
step.serverstring
The Pluto product an mcp step used, e.g. Pluto Profit.
step.startedAtstring (date-time)Required
Started.
step.statusstringRequired
State.One of running, done, failed, awaiting_approval, rejected, stopped
step.toolstring or nullRequired
The MCP tool; null for every kind but tool.
stepIdstring
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
  }'
POST/agent/chats/{id}/parts/{part_id}/select

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe chat's ID.
part_idpathstringRequiredThe part's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

optionIdsarray of stringsRequired
The options[].id you keep, up to 100.

Response200 OK

approvalobject
approval.canApprovebooleanRequired
The viewer can approve it: the same as canDecide.
approval.canDecidebooleanRequired
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.capabilitystringRequired
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.chatIdstring (uuid)Required
Chat.
approval.createdAtstring (date-time)Required
Proposed.
approval.decidedAtstring (date-time) or nullRequired
Decided.
approval.effectobjectRequired
approval.effect.donestringRequired
The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approval.effect.entitiesarray of objectsRequired
What it changes.
approval.effect.entities[].idstring (uuid)Required
ID.
approval.effect.entities[].kindstringRequired
Kind.One of launch, adSet, ad
approval.effect.entities[].launchIdstring (uuid)Required
Its launch.
approval.effect.entities[].namestring or nullRequired
Name.
approval.effect.linesarray of objectsRequired
Human details, never field names or IDs.
approval.effect.lines[].labelstringRequired
A human label, e.g. Trigger.
approval.effect.lines[].valuestringRequired
Its value, e.g. New comment.
approval.effect.moneyarray of objectsRequired
Amounts it spends or sets.
approval.effect.money[].amountstringRequired
A decimal amount; never a float.
approval.effect.money[].currencystring or nullRequired
ISO 4217; null when the account's currency isn't known.
approval.effect.money[].labelstringRequired
Label.
approval.effect.subjectstring
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.summarystringRequired
What it does, in a sentence; empty when that would only repeat title.
approval.effect.titlestringRequired
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.warningsarray of stringsRequired
Things to know before approving.
approval.errorobject or nullRequired
Why it failed, or the reason it was declined.
approval.error.codestringRequired
Stable code.
approval.error.messagestringRequired
For the person.
approval.error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
approval.idstring (uuid)Required
Approval.
approval.messageIdstring (uuid)Required
The answer that proposed it.
approval.permissionstringRequired
The coarse permission the call asked with: the action's own (read, review or write only when the person chose Ask every time). What deciding needs is capability.One of read, review, write, publish, admin, organization
approval.resultobject or nullRequired
After approving.
approval.result.jobIdstring (uuid) or nullRequired
The job it started.
approval.result.summarystringRequired
What happened.
approval.statusstringRequired
State.One of pending, approved, rejected, failed, superseded
approval.titlestringRequired
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.toolstringRequired
The MCP tool it runs.
chatobject
chat.createdAtstring (date-time)Required
Started.
chat.effortstring or nullRequired
The reasoning effort picked for the chat; null: the model's default.
chat.idstring (uuid)Required
Chat.
chat.lastMessageAtstring (date-time) or nullRequired
Last message.
chat.loopIdstring (uuid) or nullRequired
The loop it is the history of (it made the loop, or was started in its builder).
chat.modelstringRequired
The chat's model: pluto, auto or a model ID from GET /agent/models.
chat.ownerIdstring (uuid)Required
The chat's person: only they rename, delete or share it.
chat.sharedbooleanRequired
Shared with everyone who can see its loop; false: private to its person.
chat.sourcestringRequired
Where it started.One of page, panel, home, loop
chat.statusstringRequired
What it's doing.One of idle, running, awaiting_approval
chat.titlestring or nullRequired
Title; null until the first answer names it.
chat.unreadbooleanRequired
An answer arrived after the person last read it.
chat.updatedAtstring (date-time)Required
Last change.
codestring
error: spend_limit, payment_required, model_unavailable, rate_limited, refusal, max_tokens, step_limit or internal.
deltastring
Text to append.
messageobject
message.approvalIdsarray of strings (uuid)Required
Approvals raised in this answer.
message.attachmentsarray of objectsRequired
Files the person attached.
message.attachments[].contentTypestring
A chat file's type.
message.attachments[].fileIdstring (uuid)
A chat file, uploaded for the message.
message.attachments[].kindstringRequired
Kind (a media library item is an image or a video).One of image, video, pdf, document, spreadsheet, presentation, text, code, audio, archive
message.attachments[].mediaIdstring (uuid)
A media library item.
message.attachments[].namestringRequired
File name.
message.attachments[].pageCountinteger
Pages of a PDF, Word document or presentation.
message.attachments[].previewUrlstring
A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
message.attachments[].sizeBytesinteger
A chat file's size.
message.chatIdstring (uuid)Required
Chat.
message.completedAtstring (date-time) or nullRequired
Finished.
message.createdAtstring (date-time)Required
Written.
message.errorobject or nullRequired
Why the answer failed.
message.error.codestringRequired
Stable code.
message.error.messagestringRequired
For the person.
message.error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
message.idstring (uuid)Required
Message.
message.modelstring or nullRequired
The model that produced the answer; null for the person's messages.
message.partsarray of objectsRequired
The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
message.parts[].answerstring
question: the answer once given (a choice's label, or the words of your reply).
message.parts[].choiceIdstring
question: the choice it was answered with.
message.parts[].choicesarray of objects
question: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).
message.parts[].columnsarray of objects
table: its columns.
message.parts[].dataarray of objects
Every kind but combo and table: the series.
message.parts[].descriptionstring
One line under the title: the period, the unit.
message.parts[].groupsarray of objects
combo: its groups.
message.parts[].idstringRequired
The part; the same ID again replaces it.
message.parts[].itemsarray of objects
ads: the ads, in the order shown.
message.parts[].kindstring
How it's drawn; table is a table.One of line, bar, horizontal-bar, stacked-bar, stacked-area, donut, funnel, combo, simple-bar, simple-normalized, spark-line, spark-bar, table
message.parts[].optionsarray of objects
selection: the options (POST /agent/chats/{id}/parts/{part_id}/select).
message.parts[].periodobject
ads: the days of its metrics: since, until and preset (last_30_days, …, or null).
message.parts[].proposedarray of strings
selection: the options the Agent recommends, checked at first.
message.parts[].rowsarray of objects
table: its rows.
message.parts[].selectedarray of strings
selection: the options you confirmed.
message.parts[].showLegendboolean
Whether a legend shows; absent: for two or more series.
message.parts[].sizestring
simple-normalized only.One of small, medium, large
message.parts[].textstring
question: the question. text: the words (Markdown).
message.parts[].titlestring
What it shows.
message.parts[].typestringRequired
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[].valueFormatobject
How values read: style (decimal, percent with values as percentages, currency with currency), notation, minimumFractionDigits, maximumFractionDigits, unit.
message.parts[].xAxisobject
label, hide.
message.parts[].yAxisobject
label, integersOnly.
message.rolestringRequired
Who wrote it.One of user, assistant
message.sentBystring (uuid) or nullRequired
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.sourcesarray of objectsRequired
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[].sitestringRequired
The hostname without www..
message.sources[].titlestringRequired
Its title (its site when it named none).
message.sources[].urlstringRequired
The page.
message.statusstringRequired
State: waiting for credits; awaiting_user when the answer asked a question or proposed a selection (parts) and waits for your reply.One of complete, streaming, stopped, failed, awaiting_approval, waiting, awaiting_user
message.stepsarray of objectsRequired
What the Agent did, in order.
message.steps[].categorystring
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), mcp for another Pluto product (server). Absent for narration and thinking, and on older steps.One of write, edit, read, list, search, mcp, other
message.steps[].detailstring or nullRequired
Error, reasoning or narration text; a search's query; a read page's URL.
message.steps[].entitiesarray of objectsRequired
What it touched.
message.steps[].entities[].idstring (uuid)Required
ID.
message.steps[].entities[].kindstringRequired
Kind.One of launch, adSet, ad
message.steps[].entities[].launchIdstring (uuid)Required
Its launch.
message.steps[].entities[].namestring or nullRequired
Name.
message.steps[].finishedAtstring (date-time) or nullRequired
Finished.
message.steps[].idstringRequired
Step.
message.steps[].kindstringRequired
A tool call, narration before tools, summarized reasoning, a web search (detail is the query) or a web page read (detail is its URL).One of tool, note, thinking, search, fetch
message.steps[].labelstringRequired
Present tense while running, past tense when done.
message.steps[].serverstring
The Pluto product an mcp step used, e.g. Pluto Profit.
message.steps[].startedAtstring (date-time)Required
Started.
message.steps[].statusstringRequired
State.One of running, done, failed, awaiting_approval, rejected, stopped
message.steps[].toolstring or nullRequired
The MCP tool; null for every kind but tool.
message.textstringRequired
The question, or the answer (markdown; pluto: links name launches, ad sets and ads).
message.versionintegerRequired
Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
message.versionsintegerRequired
How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
message.workedMsinteger or nullRequired
Active time, excluding waits for approval.
messageIdstring (uuid)
The Agent message a delta belongs to.
partobject
part.answerstring
question: the answer once given (a choice's label, or the words of your reply).
part.choiceIdstring
question: the choice it was answered with.
part.choicesarray of objects
question: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).
part.columnsarray of objects
table: its columns.
part.dataarray of objects
Every kind but combo and table: the series.
part.descriptionstring
One line under the title: the period, the unit.
part.groupsarray of objects
combo: its groups.
part.idstringRequired
The part; the same ID again replaces it.
part.itemsarray of objects
ads: the ads, in the order shown.
part.kindstring
How it's drawn; table is a table.One of line, bar, horizontal-bar, stacked-bar, stacked-area, donut, funnel, combo, simple-bar, simple-normalized, spark-line, spark-bar, table
part.optionsarray of objects
selection: the options (POST /agent/chats/{id}/parts/{part_id}/select).
part.periodobject
ads: the days of its metrics: since, until and preset (last_30_days, …, or null).
part.proposedarray of strings
selection: the options the Agent recommends, checked at first.
part.rowsarray of objects
table: its rows.
part.selectedarray of strings
selection: the options you confirmed.
part.showLegendboolean
Whether a legend shows; absent: for two or more series.
part.sizestring
simple-normalized only.One of small, medium, large
part.textstring
question: the question. text: the words (Markdown).
part.titlestring
What it shows.
part.typestringRequired
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.valueFormatobject
How values read: style (decimal, percent with values as percentages, currency with currency), notation, minimumFractionDigits, maximumFractionDigits, unit.
part.xAxisobject
label, hide.
part.yAxisobject
label, integersOnly.
reasonstring or null
error with spend_limit: which limit stopped it (member_limit, workspace_limit or trial_cap); with payment_required: why there's no access.
retryableboolean
error: whether retrying can help.
sourcesarray of objects
sources events: the answer's web pages so far.
sources[].sitestringRequired
The hostname without www..
sources[].titlestringRequired
Its title (its site when it named none).
sources[].urlstringRequired
The page.
stallobject or null
stall: 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) or silent_tool (a tool reported nothing for 45 s), and since, when the silence began (epoch milliseconds); null once it moves again.
stall.kindstringRequired
What went quiet.One of no_first_byte, silent_stream, silent_tool
stall.sinceintegerRequired
When the silence began, epoch milliseconds.
stepobject
step.categorystring
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), mcp for another Pluto product (server). Absent for narration and thinking, and on older steps.One of write, edit, read, list, search, mcp, other
step.detailstring or nullRequired
Error, reasoning or narration text; a search's query; a read page's URL.
step.entitiesarray of objectsRequired
What it touched.
step.entities[].idstring (uuid)Required
ID.
step.entities[].kindstringRequired
Kind.One of launch, adSet, ad
step.entities[].launchIdstring (uuid)Required
Its launch.
step.entities[].namestring or nullRequired
Name.
step.finishedAtstring (date-time) or nullRequired
Finished.
step.idstringRequired
Step.
step.kindstringRequired
A tool call, narration before tools, summarized reasoning, a web search (detail is the query) or a web page read (detail is its URL).One of tool, note, thinking, search, fetch
step.labelstringRequired
Present tense while running, past tense when done.
step.serverstring
The Pluto product an mcp step used, e.g. Pluto Profit.
step.startedAtstring (date-time)Required
Started.
step.statusstringRequired
State.One of running, done, failed, awaiting_approval, rejected, stopped
step.toolstring or nullRequired
The MCP tool; null for every kind but tool.
stepIdstring
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
    ]
  }'
POST/agent/chats/{id}/read

Mark a chat read

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe chat's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response204 No Content

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-After seconds. 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"
POST/agent/chats/{id}/retry

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).

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe chat's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

approvalobject
approval.canApprovebooleanRequired
The viewer can approve it: the same as canDecide.
approval.canDecidebooleanRequired
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.capabilitystringRequired
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.chatIdstring (uuid)Required
Chat.
approval.createdAtstring (date-time)Required
Proposed.
approval.decidedAtstring (date-time) or nullRequired
Decided.
approval.effectobjectRequired
approval.effect.donestringRequired
The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approval.effect.entitiesarray of objectsRequired
What it changes.
approval.effect.entities[].idstring (uuid)Required
ID.
approval.effect.entities[].kindstringRequired
Kind.One of launch, adSet, ad
approval.effect.entities[].launchIdstring (uuid)Required
Its launch.
approval.effect.entities[].namestring or nullRequired
Name.
approval.effect.linesarray of objectsRequired
Human details, never field names or IDs.
approval.effect.lines[].labelstringRequired
A human label, e.g. Trigger.
approval.effect.lines[].valuestringRequired
Its value, e.g. New comment.
approval.effect.moneyarray of objectsRequired
Amounts it spends or sets.
approval.effect.money[].amountstringRequired
A decimal amount; never a float.
approval.effect.money[].currencystring or nullRequired
ISO 4217; null when the account's currency isn't known.
approval.effect.money[].labelstringRequired
Label.
approval.effect.subjectstring
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.summarystringRequired
What it does, in a sentence; empty when that would only repeat title.
approval.effect.titlestringRequired
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.warningsarray of stringsRequired
Things to know before approving.
approval.errorobject or nullRequired
Why it failed, or the reason it was declined.
approval.error.codestringRequired
Stable code.
approval.error.messagestringRequired
For the person.
approval.error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
approval.idstring (uuid)Required
Approval.
approval.messageIdstring (uuid)Required
The answer that proposed it.
approval.permissionstringRequired
The coarse permission the call asked with: the action's own (read, review or write only when the person chose Ask every time). What deciding needs is capability.One of read, review, write, publish, admin, organization
approval.resultobject or nullRequired
After approving.
approval.result.jobIdstring (uuid) or nullRequired
The job it started.
approval.result.summarystringRequired
What happened.
approval.statusstringRequired
State.One of pending, approved, rejected, failed, superseded
approval.titlestringRequired
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.toolstringRequired
The MCP tool it runs.
chatobject
chat.createdAtstring (date-time)Required
Started.
chat.effortstring or nullRequired
The reasoning effort picked for the chat; null: the model's default.
chat.idstring (uuid)Required
Chat.
chat.lastMessageAtstring (date-time) or nullRequired
Last message.
chat.loopIdstring (uuid) or nullRequired
The loop it is the history of (it made the loop, or was started in its builder).
chat.modelstringRequired
The chat's model: pluto, auto or a model ID from GET /agent/models.
chat.ownerIdstring (uuid)Required
The chat's person: only they rename, delete or share it.
chat.sharedbooleanRequired
Shared with everyone who can see its loop; false: private to its person.
chat.sourcestringRequired
Where it started.One of page, panel, home, loop
chat.statusstringRequired
What it's doing.One of idle, running, awaiting_approval
chat.titlestring or nullRequired
Title; null until the first answer names it.
chat.unreadbooleanRequired
An answer arrived after the person last read it.
chat.updatedAtstring (date-time)Required
Last change.
codestring
error: spend_limit, payment_required, model_unavailable, rate_limited, refusal, max_tokens, step_limit or internal.
deltastring
Text to append.
messageobject
message.approvalIdsarray of strings (uuid)Required
Approvals raised in this answer.
message.attachmentsarray of objectsRequired
Files the person attached.
message.attachments[].contentTypestring
A chat file's type.
message.attachments[].fileIdstring (uuid)
A chat file, uploaded for the message.
message.attachments[].kindstringRequired
Kind (a media library item is an image or a video).One of image, video, pdf, document, spreadsheet, presentation, text, code, audio, archive
message.attachments[].mediaIdstring (uuid)
A media library item.
message.attachments[].namestringRequired
File name.
message.attachments[].pageCountinteger
Pages of a PDF, Word document or presentation.
message.attachments[].previewUrlstring
A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
message.attachments[].sizeBytesinteger
A chat file's size.
message.chatIdstring (uuid)Required
Chat.
message.completedAtstring (date-time) or nullRequired
Finished.
message.createdAtstring (date-time)Required
Written.
message.errorobject or nullRequired
Why the answer failed.
message.error.codestringRequired
Stable code.
message.error.messagestringRequired
For the person.
message.error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
message.idstring (uuid)Required
Message.
message.modelstring or nullRequired
The model that produced the answer; null for the person's messages.
message.partsarray of objectsRequired
The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
message.parts[].answerstring
question: the answer once given (a choice's label, or the words of your reply).
message.parts[].choiceIdstring
question: the choice it was answered with.
message.parts[].choicesarray of objects
question: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).
message.parts[].columnsarray of objects
table: its columns.
message.parts[].dataarray of objects
Every kind but combo and table: the series.
message.parts[].descriptionstring
One line under the title: the period, the unit.
message.parts[].groupsarray of objects
combo: its groups.
message.parts[].idstringRequired
The part; the same ID again replaces it.
message.parts[].itemsarray of objects
ads: the ads, in the order shown.
message.parts[].kindstring
How it's drawn; table is a table.One of line, bar, horizontal-bar, stacked-bar, stacked-area, donut, funnel, combo, simple-bar, simple-normalized, spark-line, spark-bar, table
message.parts[].optionsarray of objects
selection: the options (POST /agent/chats/{id}/parts/{part_id}/select).
message.parts[].periodobject
ads: the days of its metrics: since, until and preset (last_30_days, …, or null).
message.parts[].proposedarray of strings
selection: the options the Agent recommends, checked at first.
message.parts[].rowsarray of objects
table: its rows.
message.parts[].selectedarray of strings
selection: the options you confirmed.
message.parts[].showLegendboolean
Whether a legend shows; absent: for two or more series.
message.parts[].sizestring
simple-normalized only.One of small, medium, large
message.parts[].textstring
question: the question. text: the words (Markdown).
message.parts[].titlestring
What it shows.
message.parts[].typestringRequired
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[].valueFormatobject
How values read: style (decimal, percent with values as percentages, currency with currency), notation, minimumFractionDigits, maximumFractionDigits, unit.
message.parts[].xAxisobject
label, hide.
message.parts[].yAxisobject
label, integersOnly.
message.rolestringRequired
Who wrote it.One of user, assistant
message.sentBystring (uuid) or nullRequired
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.sourcesarray of objectsRequired
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[].sitestringRequired
The hostname without www..
message.sources[].titlestringRequired
Its title (its site when it named none).
message.sources[].urlstringRequired
The page.
message.statusstringRequired
State: waiting for credits; awaiting_user when the answer asked a question or proposed a selection (parts) and waits for your reply.One of complete, streaming, stopped, failed, awaiting_approval, waiting, awaiting_user
message.stepsarray of objectsRequired
What the Agent did, in order.
message.steps[].categorystring
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), mcp for another Pluto product (server). Absent for narration and thinking, and on older steps.One of write, edit, read, list, search, mcp, other
message.steps[].detailstring or nullRequired
Error, reasoning or narration text; a search's query; a read page's URL.
message.steps[].entitiesarray of objectsRequired
What it touched.
message.steps[].entities[].idstring (uuid)Required
ID.
message.steps[].entities[].kindstringRequired
Kind.One of launch, adSet, ad
message.steps[].entities[].launchIdstring (uuid)Required
Its launch.
message.steps[].entities[].namestring or nullRequired
Name.
message.steps[].finishedAtstring (date-time) or nullRequired
Finished.
message.steps[].idstringRequired
Step.
message.steps[].kindstringRequired
A tool call, narration before tools, summarized reasoning, a web search (detail is the query) or a web page read (detail is its URL).One of tool, note, thinking, search, fetch
message.steps[].labelstringRequired
Present tense while running, past tense when done.
message.steps[].serverstring
The Pluto product an mcp step used, e.g. Pluto Profit.
message.steps[].startedAtstring (date-time)Required
Started.
message.steps[].statusstringRequired
State.One of running, done, failed, awaiting_approval, rejected, stopped
message.steps[].toolstring or nullRequired
The MCP tool; null for every kind but tool.
message.textstringRequired
The question, or the answer (markdown; pluto: links name launches, ad sets and ads).
message.versionintegerRequired
Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
message.versionsintegerRequired
How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
message.workedMsinteger or nullRequired
Active time, excluding waits for approval.
messageIdstring (uuid)
The Agent message a delta belongs to.
partobject
part.answerstring
question: the answer once given (a choice's label, or the words of your reply).
part.choiceIdstring
question: the choice it was answered with.
part.choicesarray of objects
question: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).
part.columnsarray of objects
table: its columns.
part.dataarray of objects
Every kind but combo and table: the series.
part.descriptionstring
One line under the title: the period, the unit.
part.groupsarray of objects
combo: its groups.
part.idstringRequired
The part; the same ID again replaces it.
part.itemsarray of objects
ads: the ads, in the order shown.
part.kindstring
How it's drawn; table is a table.One of line, bar, horizontal-bar, stacked-bar, stacked-area, donut, funnel, combo, simple-bar, simple-normalized, spark-line, spark-bar, table
part.optionsarray of objects
selection: the options (POST /agent/chats/{id}/parts/{part_id}/select).
part.periodobject
ads: the days of its metrics: since, until and preset (last_30_days, …, or null).
part.proposedarray of strings
selection: the options the Agent recommends, checked at first.
part.rowsarray of objects
table: its rows.
part.selectedarray of strings
selection: the options you confirmed.
part.showLegendboolean
Whether a legend shows; absent: for two or more series.
part.sizestring
simple-normalized only.One of small, medium, large
part.textstring
question: the question. text: the words (Markdown).
part.titlestring
What it shows.
part.typestringRequired
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.valueFormatobject
How values read: style (decimal, percent with values as percentages, currency with currency), notation, minimumFractionDigits, maximumFractionDigits, unit.
part.xAxisobject
label, hide.
part.yAxisobject
label, integersOnly.
reasonstring or null
error with spend_limit: which limit stopped it (member_limit, workspace_limit or trial_cap); with payment_required: why there's no access.
retryableboolean
error: whether retrying can help.
sourcesarray of objects
sources events: the answer's web pages so far.
sources[].sitestringRequired
The hostname without www..
sources[].titlestringRequired
Its title (its site when it named none).
sources[].urlstringRequired
The page.
stallobject or null
stall: 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) or silent_tool (a tool reported nothing for 45 s), and since, when the silence began (epoch milliseconds); null once it moves again.
stall.kindstringRequired
What went quiet.One of no_first_byte, silent_stream, silent_tool
stall.sinceintegerRequired
When the silence began, epoch milliseconds.
stepobject
step.categorystring
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), mcp for another Pluto product (server). Absent for narration and thinking, and on older steps.One of write, edit, read, list, search, mcp, other
step.detailstring or nullRequired
Error, reasoning or narration text; a search's query; a read page's URL.
step.entitiesarray of objectsRequired
What it touched.
step.entities[].idstring (uuid)Required
ID.
step.entities[].kindstringRequired
Kind.One of launch, adSet, ad
step.entities[].launchIdstring (uuid)Required
Its launch.
step.entities[].namestring or nullRequired
Name.
step.finishedAtstring (date-time) or nullRequired
Finished.
step.idstringRequired
Step.
step.kindstringRequired
A tool call, narration before tools, summarized reasoning, a web search (detail is the query) or a web page read (detail is its URL).One of tool, note, thinking, search, fetch
step.labelstringRequired
Present tense while running, past tense when done.
step.serverstring
The Pluto product an mcp step used, e.g. Pluto Profit.
step.startedAtstring (date-time)Required
Started.
step.statusstringRequired
State.One of running, done, failed, awaiting_approval, rejected, stopped
step.toolstring or nullRequired
The MCP tool; null for every kind but tool.
stepIdstring
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
POST/agent/chats/{id}/stop

Stop a running answer

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe chat's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response202 Accepted

createdAtstring (date-time)Required
Started.
effortstring or nullRequired
The reasoning effort picked for the chat; null: the model's default.
idstring (uuid)Required
Chat.
lastMessageAtstring (date-time) or nullRequired
Last message.
loopIdstring (uuid) or nullRequired
The loop it is the history of (it made the loop, or was started in its builder).
modelstringRequired
The chat's model: pluto, auto or a model ID from GET /agent/models.
ownerIdstring (uuid)Required
The chat's person: only they rename, delete or share it.
sharedbooleanRequired
Shared with everyone who can see its loop; false: private to its person.
sourcestringRequired
Where it started.One of page, panel, home, loop
statusstringRequired
What it's doing.One of idle, running, awaiting_approval
titlestring or nullRequired
Title; null until the first answer names it.
unreadbooleanRequired
An answer arrived after the person last read it.
updatedAtstring (date-time)Required
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-After seconds. 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/agent/guidance

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.

Permission: read

Parameters

NameTypeRequiredDescription
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

textstringRequired
The guidance; empty when there's none. Up to 4,000 characters.
updatedAtstring (date-time) or nullRequired
Last saved; null before the first save.
versionintegerRequired
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.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/agent/guidance" \
  -H "Authorization: Bearer $PLUTO_KEY"
PUT/agent/guidance

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

expectedVersioninteger
The version you last read. A mismatch is a conflict that returns the current entity.
textstringRequired
The whole guidance; empty clears it.

Response200 OK

textstringRequired
The guidance; empty when there's none. Up to 4,000 characters.
updatedAtstring (date-time) or nullRequired
Last saved; null before the first save.
versionintegerRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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?"
  }'
GET/agent/memories

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.

Permission: read

Parameters

NameTypeRequiredDescription
queryquerystringOptionalWords to search for.
typequerystringOptionalOnly preference, rule, fact or reference entries.
scopequerystringOptionalOnly personal (yours) or workspace entries.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
Entries, rules first, then newest first.
items[].bodystringRequired
Details and why (up to 4,000 characters); the Agent reads it when the entry matters.
items[].canEditbooleanRequired
The caller may change or delete it.
items[].createdAtstring (date-time)Required
Saved.
items[].createdBystring (uuid) or nullRequired
Who saved it.
items[].descriptionstringRequired
The one line the Agent recalls it by, in every chat's prompt (up to 200 characters).
items[].idstring (uuid)Required
The entry.
items[].limitsobject or nullRequired
A rule's limits, enforced by Pluto. budgetIncrease: the largest budget or bid raise the Agent makes without asking (percent, and/or amount per change, per day for daily budgets, with its currency; decimal strings). askBefore: actions that always ask first.
items[].limits.askBeforearray of strings
items[].limits.budgetIncreaseobject
items[].limits.budgetIncrease.amountstring
items[].limits.budgetIncrease.currencystring
items[].limits.budgetIncrease.percentstring
items[].scopestringRequired
The person's own, or the workspace's (every member's chats).One of personal, workspace
items[].sourceobjectRequired
Where it came from: kind is chat (saved from an Agent chat, with chatId and messageId), settings, api or mcp.
items[].source.chatIdstring (uuid)
items[].source.kindstringRequired
One of chat, settings, api, mcp
items[].source.messageIdstring (uuid)
items[].titlestringRequired
A few words (up to 80 characters).
items[].typestringRequired
preference, rule, fact or reference.One of preference, rule, fact, reference
items[].updatedAtstring (date-time)Required
Last changed.
items[].versionintegerRequired
Send it back as expectedVersion.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/agent/memories" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/agent/memories

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

bodystring
Details and why.
descriptionstringRequired
The one line the Agent recalls it by, without tags.
limitsobject or null
A rule's limits, enforced by Pluto. budgetIncrease: the largest budget or bid raise the Agent makes without asking (percent, and/or amount per change, per day for daily budgets, with its currency; decimal strings). askBefore: actions that always ask first.
limits.askBeforearray of strings
limits.budgetIncreaseobject
limits.budgetIncrease.amountstring
limits.budgetIncrease.currencystring
limits.budgetIncrease.percentstring
scopestring
personal (the default) or workspace.One of personal, workspace
titlestringRequired
A few words; unique in its scope.
typestringRequired
preference, rule, fact or reference.One of preference, rule, fact, reference

Response201 Created

bodystringRequired
Details and why (up to 4,000 characters); the Agent reads it when the entry matters.
canEditbooleanRequired
The caller may change or delete it.
createdAtstring (date-time)Required
Saved.
createdBystring (uuid) or nullRequired
Who saved it.
descriptionstringRequired
The one line the Agent recalls it by, in every chat's prompt (up to 200 characters).
idstring (uuid)Required
The entry.
limitsobject or nullRequired
A rule's limits, enforced by Pluto. budgetIncrease: the largest budget or bid raise the Agent makes without asking (percent, and/or amount per change, per day for daily budgets, with its currency; decimal strings). askBefore: actions that always ask first.
limits.askBeforearray of strings
limits.budgetIncreaseobject
limits.budgetIncrease.amountstring
limits.budgetIncrease.currencystring
limits.budgetIncrease.percentstring
scopestringRequired
The person's own, or the workspace's (every member's chats).One of personal, workspace
sourceobjectRequired
Where it came from: kind is chat (saved from an Agent chat, with chatId and messageId), settings, api or mcp.
source.chatIdstring (uuid)
source.kindstringRequired
One of chat, settings, api, mcp
source.messageIdstring (uuid)
titlestringRequired
A few words (up to 80 characters).
typestringRequired
preference, rule, fact or reference.One of preference, rule, fact, reference
updatedAtstring (date-time)Required
Last changed.
versionintegerRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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/agent/memories/{id}

Get a memory entry

Yours or the workspace's; another person's entry is 404. Also in MCP as get_agent_memory.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe memory's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

bodystringRequired
Details and why (up to 4,000 characters); the Agent reads it when the entry matters.
canEditbooleanRequired
The caller may change or delete it.
createdAtstring (date-time)Required
Saved.
createdBystring (uuid) or nullRequired
Who saved it.
descriptionstringRequired
The one line the Agent recalls it by, in every chat's prompt (up to 200 characters).
idstring (uuid)Required
The entry.
limitsobject or nullRequired
A rule's limits, enforced by Pluto. budgetIncrease: the largest budget or bid raise the Agent makes without asking (percent, and/or amount per change, per day for daily budgets, with its currency; decimal strings). askBefore: actions that always ask first.
limits.askBeforearray of strings
limits.budgetIncreaseobject
limits.budgetIncrease.amountstring
limits.budgetIncrease.currencystring
limits.budgetIncrease.percentstring
scopestringRequired
The person's own, or the workspace's (every member's chats).One of personal, workspace
sourceobjectRequired
Where it came from: kind is chat (saved from an Agent chat, with chatId and messageId), settings, api or mcp.
source.chatIdstring (uuid)
source.kindstringRequired
One of chat, settings, api, mcp
source.messageIdstring (uuid)
titlestringRequired
A few words (up to 80 characters).
typestringRequired
preference, rule, fact or reference.One of preference, rule, fact, reference
updatedAtstring (date-time)Required
Last changed.
versionintegerRequired
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-After seconds. 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"
PATCH/agent/memories/{id}

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe memory's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

bodystring
Details and why.
descriptionstring
The one line the Agent recalls it by, without tags.
expectedVersionintegerRequired
The version you last read. A mismatch is a conflict that returns the current entity.
limitsobject or null
A rule's limits, enforced by Pluto. budgetIncrease: the largest budget or bid raise the Agent makes without asking (percent, and/or amount per change, per day for daily budgets, with its currency; decimal strings). askBefore: actions that always ask first.
limits.askBeforearray of strings
limits.budgetIncreaseobject
limits.budgetIncrease.amountstring
limits.budgetIncrease.currencystring
limits.budgetIncrease.percentstring
titlestring
A few words; unique in its scope.
typestring
preference, rule, fact or reference.One of preference, rule, fact, reference

Response200 OK

bodystringRequired
Details and why (up to 4,000 characters); the Agent reads it when the entry matters.
canEditbooleanRequired
The caller may change or delete it.
createdAtstring (date-time)Required
Saved.
createdBystring (uuid) or nullRequired
Who saved it.
descriptionstringRequired
The one line the Agent recalls it by, in every chat's prompt (up to 200 characters).
idstring (uuid)Required
The entry.
limitsobject or nullRequired
A rule's limits, enforced by Pluto. budgetIncrease: the largest budget or bid raise the Agent makes without asking (percent, and/or amount per change, per day for daily budgets, with its currency; decimal strings). askBefore: actions that always ask first.
limits.askBeforearray of strings
limits.budgetIncreaseobject
limits.budgetIncrease.amountstring
limits.budgetIncrease.currencystring
limits.budgetIncrease.percentstring
scopestringRequired
The person's own, or the workspace's (every member's chats).One of personal, workspace
sourceobjectRequired
Where it came from: kind is chat (saved from an Agent chat, with chatId and messageId), settings, api or mcp.
source.chatIdstring (uuid)
source.kindstringRequired
One of chat, settings, api, mcp
source.messageIdstring (uuid)
titlestringRequired
A few words (up to 80 characters).
typestringRequired
preference, rule, fact or reference.One of preference, rule, fact, reference
updatedAtstring (date-time)Required
Last changed.
versionintegerRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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/agent/memories/{id}

Delete a memory entry

For good. Yours to delete; the workspace's for owners and admins. Also in MCP as delete_agent_memory.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe memory's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response204 No Content

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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
GET/agent/models

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.

Permission: read

Parameters

NameTypeRequiredDescription
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

defaultModelstring or nullRequired
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.
modelsarray of objectsRequired
Every model offered, Pluto first, then auto, then grouped by provider.
models[].aliasesarray of stringsRequired
Family words search matches (pluto, sonnet, gpt, ...).
models[].allowedbooleanRequired
Members may pick it (Settings, Agent).
models[].availablebooleanRequired
It can run now; false while its provider isn't set up yet.
models[].contextWindowinteger or nullRequired
Tokens of context; null for Pluto and auto.
models[].defaultEffortstring or nullRequired
The effort used when none is picked.
models[].effortsarray of stringsRequired
Reasoning effort levels it accepts; empty: none to pick.
models[].hintstringRequired
One line: what it's good at.
models[].idstringRequired
pluto, auto or a model ID, e.g. pluto.
models[].namestringRequired
Display name.
models[].olderbooleanRequired
A previous generation, still served.
models[].previewbooleanRequired
Preview at the provider.
models[].providerstring or nullRequired
Null for Pluto and auto.One of anthropic, openai, xai
models[].providerNamestring or nullRequired
Anthropic, OpenAI or xAI; null for Pluto and auto.
models[].recommendedbooleanRequired
In the recommended set people see until they choose otherwise.
models[].retentionstring or nullRequired
How long the provider keeps requests when longer than usual (e.g. 30d); null for Pluto.
models[].streamingbooleanRequired
Streams its answer.
models[].toolsbooleanRequired
Uses tools.
models[].usOnlystringRequired
How requests stay in the US.
models[].visiblebooleanRequired
In the caller's own model picker.
recentarray of stringsRequired
The viewer's last models (up to 3, newest first), only ones they may pick.
settingsobjectRequired
settings.allowedModelsarray of strings or nullRequired
Null: every model that can run.
settings.canEditbooleanRequired
The viewer is an owner or admin.
settings.updatedAtstring (date-time) or nullRequired
Last saved.
settings.versionintegerRequired
0 until first saved.
visibilityobjectRequired
visibility.hiddenarray of stringsRequired
Recommended models turned off.
visibility.shownarray of stringsRequired
Turned on beyond the recommended set.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/agent/models" \
  -H "Authorization: Bearer $PLUTO_KEY"
PUT/agent/models/settings

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.

Permission: adminCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

allowedModelsarray of strings or nullRequired
Model IDs (and auto) members may pick; null allows every model that can run.
expectedVersionintegerRequired
settings.version the change is based on (0 before the first save).

Response200 OK

defaultModelstring or nullRequired
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.
modelsarray of objectsRequired
Every model offered, Pluto first, then auto, then grouped by provider.
models[].aliasesarray of stringsRequired
Family words search matches (pluto, sonnet, gpt, ...).
models[].allowedbooleanRequired
Members may pick it (Settings, Agent).
models[].availablebooleanRequired
It can run now; false while its provider isn't set up yet.
models[].contextWindowinteger or nullRequired
Tokens of context; null for Pluto and auto.
models[].defaultEffortstring or nullRequired
The effort used when none is picked.
models[].effortsarray of stringsRequired
Reasoning effort levels it accepts; empty: none to pick.
models[].hintstringRequired
One line: what it's good at.
models[].idstringRequired
pluto, auto or a model ID, e.g. pluto.
models[].namestringRequired
Display name.
models[].olderbooleanRequired
A previous generation, still served.
models[].previewbooleanRequired
Preview at the provider.
models[].providerstring or nullRequired
Null for Pluto and auto.One of anthropic, openai, xai
models[].providerNamestring or nullRequired
Anthropic, OpenAI or xAI; null for Pluto and auto.
models[].recommendedbooleanRequired
In the recommended set people see until they choose otherwise.
models[].retentionstring or nullRequired
How long the provider keeps requests when longer than usual (e.g. 30d); null for Pluto.
models[].streamingbooleanRequired
Streams its answer.
models[].toolsbooleanRequired
Uses tools.
models[].usOnlystringRequired
How requests stay in the US.
models[].visiblebooleanRequired
In the caller's own model picker.
recentarray of stringsRequired
The viewer's last models (up to 3, newest first), only ones they may pick.
settingsobjectRequired
settings.allowedModelsarray of strings or nullRequired
Null: every model that can run.
settings.canEditbooleanRequired
The viewer is an owner or admin.
settings.updatedAtstring (date-time) or nullRequired
Last saved.
settings.versionintegerRequired
0 until first saved.
visibilityobjectRequired
visibility.hiddenarray of stringsRequired
Recommended models turned off.
visibility.shownarray of stringsRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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
  }'
PUT/agent/models/visibility

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.

Permission: readCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

hiddenarray of stringsRequired
Recommended models to hide.
shownarray of stringsRequired
Models to show although not recommended.

Response200 OK

defaultModelstring or nullRequired
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.
modelsarray of objectsRequired
Every model offered, Pluto first, then auto, then grouped by provider.
models[].aliasesarray of stringsRequired
Family words search matches (pluto, sonnet, gpt, ...).
models[].allowedbooleanRequired
Members may pick it (Settings, Agent).
models[].availablebooleanRequired
It can run now; false while its provider isn't set up yet.
models[].contextWindowinteger or nullRequired
Tokens of context; null for Pluto and auto.
models[].defaultEffortstring or nullRequired
The effort used when none is picked.
models[].effortsarray of stringsRequired
Reasoning effort levels it accepts; empty: none to pick.
models[].hintstringRequired
One line: what it's good at.
models[].idstringRequired
pluto, auto or a model ID, e.g. pluto.
models[].namestringRequired
Display name.
models[].olderbooleanRequired
A previous generation, still served.
models[].previewbooleanRequired
Preview at the provider.
models[].providerstring or nullRequired
Null for Pluto and auto.One of anthropic, openai, xai
models[].providerNamestring or nullRequired
Anthropic, OpenAI or xAI; null for Pluto and auto.
models[].recommendedbooleanRequired
In the recommended set people see until they choose otherwise.
models[].retentionstring or nullRequired
How long the provider keeps requests when longer than usual (e.g. 30d); null for Pluto.
models[].streamingbooleanRequired
Streams its answer.
models[].toolsbooleanRequired
Uses tools.
models[].usOnlystringRequired
How requests stay in the US.
models[].visiblebooleanRequired
In the caller's own model picker.
recentarray of stringsRequired
The viewer's last models (up to 3, newest first), only ones they may pick.
settingsobjectRequired
settings.allowedModelsarray of strings or nullRequired
Null: every model that can run.
settings.canEditbooleanRequired
The viewer is an owner or admin.
settings.updatedAtstring (date-time) or nullRequired
Last saved.
settings.versionintegerRequired
0 until first saved.
visibilityobjectRequired
visibility.hiddenarray of stringsRequired
Recommended models turned off.
visibility.shownarray of stringsRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
    ]
  }'
GET/agent/scripts

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.

Permission: read

Parameters

NameTypeRequiredDescription
loopIdquerystringOptionalA loop: its scripts and the workspace's.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
The scripts, a loop's first.
items[].createdAtstring (date-time)
Created.
items[].createdByKindstring
person, agent, api_key or system.
items[].idstring (uuid)Required
The script.
items[].inputsstring
What its main(inputs) takes and what it returns, prints or writes.
items[].languagestring
python.
items[].lastUsedAtstring or null
Last loaded to run.
items[].loopIdstring (uuid) or null
Its loop; null: the whole workspace's.
items[].namestringRequired
Its name, unique in its loop (or the workspace).
items[].purposestringRequired
What it does and when to use it.
items[].updatedAtstring (date-time)
Last saved.
items[].usedCountinteger
Times it was loaded to run.
items[].versionintegerRequired
The latest version.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/agent/scripts" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/agent/scripts/{id}

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.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe script's ID.
versionquerystringOptionalAn older version's code.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

codestring
The code of shownVersion.
createdAtstring (date-time)
Created.
createdByKindstring
person, agent, api_key or system.
idstring (uuid)Required
The script.
inputsstring
What its main(inputs) takes and what it returns, prints or writes.
languagestring
python.
lastUsedAtstring or null
Last loaded to run.
loopIdstring (uuid) or null
Its loop; null: the whole workspace's.
namestringRequired
Its name, unique in its loop (or the workspace).
purposestringRequired
What it does and when to use it.
shownVersioninteger
The version code is.
updatedAtstring (date-time)
Last saved.
usedCountinteger
Times it was loaded to run.
versionintegerRequired
The latest version.
versionsarray of objects
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-After seconds. 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"
GET/agent/shared/{token}

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.

Permission: write

Parameters

NameTypeRequiredDescription
tokenpathstringRequired
beforequerystringOptionalA message ID: the messages before it.
limitquerystringOptional1-200; 100 by default.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

approvalsarray of objectsRequired
The approvals these messages carry, as they read.
approvals[].canApprovebooleanRequired
The viewer can approve it: the same as canDecide.
approvals[].canDecidebooleanRequired
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[].capabilitystringRequired
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[].chatIdstring (uuid)Required
Chat.
approvals[].createdAtstring (date-time)Required
Proposed.
approvals[].decidedAtstring (date-time) or nullRequired
Decided.
approvals[].effectobjectRequired
approvals[].effect.donestringRequired
The same once it ran: Deleted loop “Facebook comment moderator”. Show it for an approved approval.
approvals[].effect.entitiesarray of objectsRequired
What it changes.
approvals[].effect.entities[].idstring (uuid)Required
ID.
approvals[].effect.entities[].kindstringRequired
Kind.One of launch, adSet, ad
approvals[].effect.entities[].launchIdstring (uuid)Required
Its launch.
approvals[].effect.entities[].namestring or nullRequired
Name.
approvals[].effect.linesarray of objectsRequired
Human details, never field names or IDs.
approvals[].effect.lines[].labelstringRequired
A human label, e.g. Trigger.
approvals[].effect.lines[].valuestringRequired
Its value, e.g. New comment.
approvals[].effect.moneyarray of objectsRequired
Amounts it spends or sets.
approvals[].effect.money[].amountstringRequired
A decimal amount; never a float.
approvals[].effect.money[].currencystring or nullRequired
ISO 4217; null when the account's currency isn't known.
approvals[].effect.money[].labelstringRequired
Label.
approvals[].effect.subjectstring
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.summarystringRequired
What it does, in a sentence; empty when that would only repeat title.
approvals[].effect.titlestringRequired
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.warningsarray of stringsRequired
Things to know before approving.
approvals[].errorobject or nullRequired
Why it failed, or the reason it was declined.
approvals[].error.codestringRequired
Stable code.
approvals[].error.messagestringRequired
For the person.
approvals[].error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
approvals[].idstring (uuid)Required
Approval.
approvals[].messageIdstring (uuid)Required
The answer that proposed it.
approvals[].permissionstringRequired
The coarse permission the call asked with: the action's own (read, review or write only when the person chose Ask every time). What deciding needs is capability.One of read, review, write, publish, admin, organization
approvals[].resultobject or nullRequired
After approving.
approvals[].result.jobIdstring (uuid) or nullRequired
The job it started.
approvals[].result.summarystringRequired
What happened.
approvals[].statusstringRequired
State.One of pending, approved, rejected, failed, superseded
approvals[].titlestringRequired
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[].toolstringRequired
The MCP tool it runs.
hasEarlierbooleanRequired
Earlier messages exist: ?before=<first message id>.
linkIdstring (uuid)Required
The link.
messagesarray of objectsRequired
This page of the snapshot, oldest first.
messages[].approvalIdsarray of strings (uuid)Required
Approvals raised in this answer.
messages[].attachmentsarray of objectsRequired
Files the person attached.
messages[].attachments[].contentTypestring
A chat file's type.
messages[].attachments[].fileIdstring (uuid)
A chat file, uploaded for the message.
messages[].attachments[].kindstringRequired
Kind (a media library item is an image or a video).One of image, video, pdf, document, spreadsheet, presentation, text, code, audio, archive
messages[].attachments[].mediaIdstring (uuid)
A media library item.
messages[].attachments[].namestringRequired
File name.
messages[].attachments[].pageCountinteger
Pages of a PDF, Word document or presentation.
messages[].attachments[].previewUrlstring
A chat file's thumbnail: a path on the app's origin that answers it; absent without one.
messages[].attachments[].sizeBytesinteger
A chat file's size.
messages[].chatIdstring (uuid)Required
Chat.
messages[].completedAtstring (date-time) or nullRequired
Finished.
messages[].createdAtstring (date-time)Required
Written.
messages[].errorobject or nullRequired
Why the answer failed.
messages[].error.codestringRequired
Stable code.
messages[].error.messagestringRequired
For the person.
messages[].error.reasonstring
For spend_limit, the limit that stopped the Agent; for payment_required, why there's no access.
messages[].idstring (uuid)Required
Message.
messages[].modelstring or nullRequired
The model that produced the answer; null for the person's messages.
messages[].partsarray of objectsRequired
The charts, tables, questions and selections the answer shows, in the order shown. Empty for most answers.
messages[].parts[].answerstring
question: the answer once given (a choice's label, or the words of your reply).
messages[].parts[].choiceIdstring
question: the choice it was answered with.
messages[].parts[].choicesarray of objects
question: 2 to 4 choices (POST /agent/chats/{id}/parts/{part_id}/answer).
messages[].parts[].columnsarray of objects
table: its columns.
messages[].parts[].dataarray of objects
Every kind but combo and table: the series.
messages[].parts[].descriptionstring
One line under the title: the period, the unit.
messages[].parts[].groupsarray of objects
combo: its groups.
messages[].parts[].idstringRequired
The part; the same ID again replaces it.
messages[].parts[].itemsarray of objects
ads: the ads, in the order shown.
messages[].parts[].kindstring
How it's drawn; table is a table.One of line, bar, horizontal-bar, stacked-bar, stacked-area, donut, funnel, combo, simple-bar, simple-normalized, spark-line, spark-bar, table
messages[].parts[].optionsarray of objects
selection: the options (POST /agent/chats/{id}/parts/{part_id}/select).
messages[].parts[].periodobject
ads: the days of its metrics: since, until and preset (last_30_days, …, or null).
messages[].parts[].proposedarray of strings
selection: the options the Agent recommends, checked at first.
messages[].parts[].rowsarray of objects
table: its rows.
messages[].parts[].selectedarray of strings
selection: the options you confirmed.
messages[].parts[].showLegendboolean
Whether a legend shows; absent: for two or more series.
messages[].parts[].sizestring
simple-normalized only.One of small, medium, large
messages[].parts[].textstring
question: the question. text: the words (Markdown).
messages[].parts[].titlestring
What it shows.
messages[].parts[].typestringRequired
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[].valueFormatobject
How values read: style (decimal, percent with values as percentages, currency with currency), notation, minimumFractionDigits, maximumFractionDigits, unit.
messages[].parts[].xAxisobject
label, hide.
messages[].parts[].yAxisobject
label, integersOnly.
messages[].rolestringRequired
Who wrote it.One of user, assistant
messages[].sentBystring (uuid) or nullRequired
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[].sourcesarray of objectsRequired
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[].sitestringRequired
The hostname without www..
messages[].sources[].titlestringRequired
Its title (its site when it named none).
messages[].sources[].urlstringRequired
The page.
messages[].statusstringRequired
State: waiting for credits; awaiting_user when the answer asked a question or proposed a selection (parts) and waits for your reply.One of complete, streaming, stopped, failed, awaiting_approval, waiting, awaiting_user
messages[].stepsarray of objectsRequired
What the Agent did, in order.
messages[].steps[].categorystring
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), mcp for another Pluto product (server). Absent for narration and thinking, and on older steps.One of write, edit, read, list, search, mcp, other
messages[].steps[].detailstring or nullRequired
Error, reasoning or narration text; a search's query; a read page's URL.
messages[].steps[].entitiesarray of objectsRequired
What it touched.
messages[].steps[].entities[].idstring (uuid)Required
ID.
messages[].steps[].entities[].kindstringRequired
Kind.One of launch, adSet, ad
messages[].steps[].entities[].launchIdstring (uuid)Required
Its launch.
messages[].steps[].entities[].namestring or nullRequired
Name.
messages[].steps[].finishedAtstring (date-time) or nullRequired
Finished.
messages[].steps[].idstringRequired
Step.
messages[].steps[].kindstringRequired
A tool call, narration before tools, summarized reasoning, a web search (detail is the query) or a web page read (detail is its URL).One of tool, note, thinking, search, fetch
messages[].steps[].labelstringRequired
Present tense while running, past tense when done.
messages[].steps[].serverstring
The Pluto product an mcp step used, e.g. Pluto Profit.
messages[].steps[].startedAtstring (date-time)Required
Started.
messages[].steps[].statusstringRequired
State.One of running, done, failed, awaiting_approval, rejected, stopped
messages[].steps[].toolstring or nullRequired
The MCP tool; null for every kind but tool.
messages[].textstringRequired
The question, or the answer (markdown; pluto: links name launches, ad sets and ads).
messages[].versionintegerRequired
Which version of an edited question or a retried answer this is (1-based, oldest first); 1 for every other message.
messages[].versionsintegerRequired
How many versions the message has (each edit or retry adds one, each keeps the messages that followed it); 1 otherwise.
messages[].workedMsinteger or nullRequired
Active time, excluding waits for approval.
sharedAtstring (date-time)Required
Shared or last updated.
sharedByobjectRequired
sharedBy.idstring (uuid)Required
The person.
sharedBy.namestringRequired
Their name.
titlestring or nullRequired
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-After seconds. 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"
GET/agent/shared/{token}/files/{fileId}/content

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.

Permission: write

Parameters

NameTypeRequiredDescription
tokenpathstringRequired
fileIdpathstringRequiredThe file's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response302 Found

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-After seconds. 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"
GET/agent/shared/{token}/files/{fileId}/preview

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.

Permission: write

Parameters

NameTypeRequiredDescription
tokenpathstringRequired
fileIdpathstringRequiredThe file's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response302 Found

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-After seconds. 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"
GET/agent/skills

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.

Permission: read

Parameters

NameTypeRequiredDescription
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
Every skill, by name, without its body.
items[].canEditboolean
The caller may change or delete it.
items[].createdAtstring (date-time)Required
Created.
items[].descriptionstringRequired
What it does and when to use it (up to 1,024 characters): the Agent picks skills by it.
items[].idstring (uuid)Required
The skill.
items[].namestringRequired
Lowercase letters, numbers and hyphens (up to 64); run it in the Agent as /name.
items[].sharedboolean
Shared with everyone in the workspace (owners and admins change it); otherwise the author's own.
items[].sourceobject
Where it came from: kind is chat (saved from an Agent chat, with chatId and messageId), settings, api or mcp.
items[].source.chatIdstring (uuid)
items[].source.kindstringRequired
One of chat, settings, api, mcp
items[].source.messageIdstring (uuid)
items[].updatedAtstring (date-time)Required
Last changed.
items[].versionintegerRequired
Send it back as expectedVersion.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/agent/skills" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/agent/skills

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

bodystringRequired
The prompt the skill runs.
descriptionstringRequired
What the skill does and when to use it, without tags: the Agent picks skills by it.
namestringRequired
Lowercase letters, numbers and single hyphens, up to 64; unique among your skills (and among shared ones). Run it as /name.
sharedboolean
Shared with everyone in the workspace (owners and admins share and change it).

Response201 Created

bodystringRequired
The prompt the skill runs (up to 20,000 characters).
canEditboolean
The caller may change or delete it.
createdAtstring (date-time)Required
Created.
descriptionstringRequired
What it does and when to use it (up to 1,024 characters): the Agent picks skills by it.
idstring (uuid)Required
The skill.
namestringRequired
Lowercase letters, numbers and hyphens (up to 64); run it in the Agent as /name.
sharedboolean
Shared with everyone in the workspace (owners and admins change it); otherwise the author's own.
sourceobject
Where it came from: kind is chat (saved from an Agent chat, with chatId and messageId), settings, api or mcp.
source.chatIdstring (uuid)
source.kindstringRequired
One of chat, settings, api, mcp
source.messageIdstring (uuid)
updatedAtstring (date-time)Required
Last changed.
versionintegerRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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/agent/skills/{id}

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.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe skill's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

bodystringRequired
The prompt the skill runs (up to 20,000 characters).
canEditboolean
The caller may change or delete it.
createdAtstring (date-time)Required
Created.
descriptionstringRequired
What it does and when to use it (up to 1,024 characters): the Agent picks skills by it.
idstring (uuid)Required
The skill.
namestringRequired
Lowercase letters, numbers and hyphens (up to 64); run it in the Agent as /name.
sharedboolean
Shared with everyone in the workspace (owners and admins change it); otherwise the author's own.
sourceobject
Where it came from: kind is chat (saved from an Agent chat, with chatId and messageId), settings, api or mcp.
source.chatIdstring (uuid)
source.kindstringRequired
One of chat, settings, api, mcp
source.messageIdstring (uuid)
updatedAtstring (date-time)Required
Last changed.
versionintegerRequired
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-After seconds. 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"
PATCH/agent/skills/{id}

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe skill's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

bodystring
The prompt the skill runs.
descriptionstring
What the skill does and when to use it, without tags: the Agent picks skills by it.
expectedVersionintegerRequired
The version you last read. A mismatch is a conflict that returns the current entity.
namestring
Lowercase letters, numbers and single hyphens, up to 64; unique among your skills (and among shared ones). Run it as /name.
sharedboolean
Shared with everyone in the workspace (owners and admins share and change it).

Response200 OK

bodystringRequired
The prompt the skill runs (up to 20,000 characters).
canEditboolean
The caller may change or delete it.
createdAtstring (date-time)Required
Created.
descriptionstringRequired
What it does and when to use it (up to 1,024 characters): the Agent picks skills by it.
idstring (uuid)Required
The skill.
namestringRequired
Lowercase letters, numbers and hyphens (up to 64); run it in the Agent as /name.
sharedboolean
Shared with everyone in the workspace (owners and admins change it); otherwise the author's own.
sourceobject
Where it came from: kind is chat (saved from an Agent chat, with chatId and messageId), settings, api or mcp.
source.chatIdstring (uuid)
source.kindstringRequired
One of chat, settings, api, mcp
source.messageIdstring (uuid)
updatedAtstring (date-time)Required
Last changed.
versionintegerRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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/agent/skills/{id}

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe skill's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response204 No Content

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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
GET/agent/suggestions

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.

Permission: read

Parameters

NameTypeRequiredDescription
chatIdquerystringOptionalThe chat. Required: without it the answer is 400.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
Oldest first.
items[].actionstringRequired
What it would do.One of create, update, delete
items[].autobooleanRequired
Saved without asking (Save automatically).
items[].chatIdstring (uuid)Required
The chat.
items[].createdAtstring (date-time)Required
Suggested.
items[].currentobject or nullRequired
For an update or delete, what's saved now; null when it's gone.
items[].decidedAtstring (date-time) or nullRequired
Saved or dismissed.
items[].idstring (uuid)Required
The suggestion.
items[].kindstringRequired
A memory entry or a skill.One of memory, skill
items[].messageIdstring (uuid)Required
The answer it came with.
items[].proposalobjectRequired
The fields to save (for an update, only what changes).
items[].savedIdstring (uuid) or nullRequired
The entry or skill it saved.
items[].statusstringRequired
Where it stands.One of pending, saved, dismissed
items[].targetIdstring (uuid) or nullRequired
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.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/agent/suggestions" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/agent/suggestions/{id}/dismiss

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.

Permission: write

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe suggestion's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

actionstringRequired
What it would do.One of create, update, delete
autobooleanRequired
Saved without asking (Save automatically).
chatIdstring (uuid)Required
The chat.
createdAtstring (date-time)Required
Suggested.
currentobject or nullRequired
For an update or delete, what's saved now; null when it's gone.
decidedAtstring (date-time) or nullRequired
Saved or dismissed.
idstring (uuid)Required
The suggestion.
kindstringRequired
A memory entry or a skill.One of memory, skill
messageIdstring (uuid)Required
The answer it came with.
proposalobjectRequired
The fields to save (for an update, only what changes).
savedIdstring (uuid) or nullRequired
The entry or skill it saved.
statusstringRequired
Where it stands.One of pending, saved, dismissed
targetIdstring (uuid) or nullRequired
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-After seconds. 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"
POST/agent/suggestions/{id}/save

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe suggestion's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

fieldsobject
The fields to save instead of the suggested ones.

Response200 OK

actionstringRequired
What it would do.One of create, update, delete
autobooleanRequired
Saved without asking (Save automatically).
chatIdstring (uuid)Required
The chat.
createdAtstring (date-time)Required
Suggested.
currentobject or nullRequired
For an update or delete, what's saved now; null when it's gone.
decidedAtstring (date-time) or nullRequired
Saved or dismissed.
idstring (uuid)Required
The suggestion.
kindstringRequired
A memory entry or a skill.One of memory, skill
messageIdstring (uuid)Required
The answer it came with.
proposalobjectRequired
The fields to save (for an update, only what changes).
savedIdstring (uuid) or nullRequired
The entry or skill it saved.
statusstringRequired
Where it stands.One of pending, saved, dismissed
targetIdstring (uuid) or nullRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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": {}
  }'