API reference

Comments

Comment threads on ads, with reactions, attachments and subscriptions.

PATCH/comments/{id}

Edit your comment

Permission: reviewCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe comment'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

attachmentsarray of objects
Attachments.
bodystringRequired
Text.
expectedVersionintegerRequired
The version you last read. A mismatch is a conflict that returns the current entity.

Response200 OK

adIdstring (uuid)
Ad.
attachmentsarray of objects
Attachments.
attachments[].contentTypestringRequired
MIME type.
attachments[].idstring (uuid)Required
Attachment.
attachments[].mediaIdstring (uuid)
Library media, when attached from it.
attachments[].namestringRequired
Name.
attachments[].sizeintegerRequired
Bytes.
attachments[].urlstring or null
Signed download URL (an hour); null in stored command results.
authorobject
author.avatarUrlstring or null
Avatar.
author.idstring (uuid)Required
Their ID.
author.kindstringRequired
Who wrote it.One of person, agent, api_key
author.namestringRequired
Name.
author.userIdstring (uuid) or null
The person behind it (the author, or the person an agent acts for); null for an API key.
bodystring
Markdown subset with @[Name](user:<id>) mentions.
createdAtstring (date-time)
Posted.
deletedboolean
Deleted.
deletedAtstring (date-time) or null
Deleted at.
editedAtstring (date-time) or null
Last edit.
idstring (uuid)Required
ID.
internalboolean
Hidden from guests: a thread kept from guests before guest access became per launch; guests never see it, its replies or reactions. Read only: no thread becomes hidden any more.
mentionsarray of strings (uuid)
Mentioned people.
parentIdstring (uuid) or null
The thread it replies to.
reactionsarray of objects
Reactions.
reactions[].countintegerRequired
How many.
reactions[].emojistringRequired
Emoji.
reactions[].userIdsarray of strings (uuid)Required
Who.
resolvedboolean
Thread resolved.
resolvedAtstring (date-time) or null
Resolved at.
resolvedBystring (uuid) or null
Who resolved it.
versioninteger
Increments on every change; send 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/comments/65d5adb8-9b81-44dc-9131-33b87d15eb2a" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 4eb7b26a-5068-452f-b23d-121cbda20077" \
  -H "Content-Type: application/json" \
  -d '{
    "attachments": [
      {}
    ],
    "body": "Can we try the 4x5 cut for Instagram feed before we publish?",
    "expectedVersion": 3
  }'
DELETE/comments/{id}

Delete a comment

Permission: reviewCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe comment's ID.
expectedVersionquerystringOptionalVersion.
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

adIdstring (uuid)
Ad.
attachmentsarray of objects
Attachments.
attachments[].contentTypestringRequired
MIME type.
attachments[].idstring (uuid)Required
Attachment.
attachments[].mediaIdstring (uuid)
Library media, when attached from it.
attachments[].namestringRequired
Name.
attachments[].sizeintegerRequired
Bytes.
attachments[].urlstring or null
Signed download URL (an hour); null in stored command results.
authorobject
author.avatarUrlstring or null
Avatar.
author.idstring (uuid)Required
Their ID.
author.kindstringRequired
Who wrote it.One of person, agent, api_key
author.namestringRequired
Name.
author.userIdstring (uuid) or null
The person behind it (the author, or the person an agent acts for); null for an API key.
bodystring
Markdown subset with @[Name](user:<id>) mentions.
createdAtstring (date-time)
Posted.
deletedboolean
Deleted.
deletedAtstring (date-time) or null
Deleted at.
editedAtstring (date-time) or null
Last edit.
idstring (uuid)Required
ID.
internalboolean
Hidden from guests: a thread kept from guests before guest access became per launch; guests never see it, its replies or reactions. Read only: no thread becomes hidden any more.
mentionsarray of strings (uuid)
Mentioned people.
parentIdstring (uuid) or null
The thread it replies to.
reactionsarray of objects
Reactions.
reactions[].countintegerRequired
How many.
reactions[].emojistringRequired
Emoji.
reactions[].userIdsarray of strings (uuid)Required
Who.
resolvedboolean
Thread resolved.
resolvedAtstring (date-time) or null
Resolved at.
resolvedBystring (uuid) or null
Who resolved it.
versioninteger
Increments on every change; send 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 DELETE "$PLUTO_API/comments/65d5adb8-9b81-44dc-9131-33b87d15eb2a" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 1a2296f1-ba3e-4925-9086-198d4eed0414"
GET/comments/{id}/attachments/{attachment_id}

Get a comment attachment

Stable link to a comment attachment.

Redirects to a fresh short-lived download URL.

Permission: readGuests too

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe comment's ID.
attachment_idpathstringRequiredThe attachment'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/comments/65d5adb8-9b81-44dc-9131-33b87d15eb2a/attachments/2f768d03-7ea0-4ca6-ad4e-7adf9c3214c2" \
  -H "Authorization: Bearer $PLUTO_KEY"
PUT/comments/{id}/reactions/{emoji}

Add your reaction

Needs a person: API keys and M2M clients get 403; a connected agent or an mcp agent client acts for its person and can.

Permission: reviewCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe comment's ID.
emojipathstringRequired
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

Reactions.

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/comments/65d5adb8-9b81-44dc-9131-33b87d15eb2a/reactions/%F0%9F%91%8D" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 33ba0d0c-70df-4e0c-8134-cc6dc58d41c4"
DELETE/comments/{id}/reactions/{emoji}

Remove your reaction

Needs a person: API keys and M2M clients get 403; a connected agent or an mcp agent client acts for its person and can.

Permission: reviewCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe comment's ID.
emojipathstringRequired
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

Reactions.

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/comments/65d5adb8-9b81-44dc-9131-33b87d15eb2a/reactions/%F0%9F%91%8D" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 44bb6440-6d6a-4006-b306-c7ef01251050"
POST/comments/{id}/reopen

Reopen a thread

Permission: reviewCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe comment'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

adIdstring (uuid)
Ad.
attachmentsarray of objects
Attachments.
attachments[].contentTypestringRequired
MIME type.
attachments[].idstring (uuid)Required
Attachment.
attachments[].mediaIdstring (uuid)
Library media, when attached from it.
attachments[].namestringRequired
Name.
attachments[].sizeintegerRequired
Bytes.
attachments[].urlstring or null
Signed download URL (an hour); null in stored command results.
authorobject
author.avatarUrlstring or null
Avatar.
author.idstring (uuid)Required
Their ID.
author.kindstringRequired
Who wrote it.One of person, agent, api_key
author.namestringRequired
Name.
author.userIdstring (uuid) or null
The person behind it (the author, or the person an agent acts for); null for an API key.
bodystring
Markdown subset with @[Name](user:<id>) mentions.
createdAtstring (date-time)
Posted.
deletedboolean
Deleted.
deletedAtstring (date-time) or null
Deleted at.
editedAtstring (date-time) or null
Last edit.
idstring (uuid)Required
ID.
internalboolean
Hidden from guests: a thread kept from guests before guest access became per launch; guests never see it, its replies or reactions. Read only: no thread becomes hidden any more.
mentionsarray of strings (uuid)
Mentioned people.
parentIdstring (uuid) or null
The thread it replies to.
reactionsarray of objects
Reactions.
reactions[].countintegerRequired
How many.
reactions[].emojistringRequired
Emoji.
reactions[].userIdsarray of strings (uuid)Required
Who.
resolvedboolean
Thread resolved.
resolvedAtstring (date-time) or null
Resolved at.
resolvedBystring (uuid) or null
Who resolved it.
versioninteger
Increments on every change; send 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 POST "$PLUTO_API/comments/65d5adb8-9b81-44dc-9131-33b87d15eb2a/reopen" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 5ae7004b-c133-43c2-837f-6ea0bb7dacda"
POST/comments/{id}/resolve

Resolve a thread

Permission: reviewCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe comment'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

adIdstring (uuid)
Ad.
attachmentsarray of objects
Attachments.
attachments[].contentTypestringRequired
MIME type.
attachments[].idstring (uuid)Required
Attachment.
attachments[].mediaIdstring (uuid)
Library media, when attached from it.
attachments[].namestringRequired
Name.
attachments[].sizeintegerRequired
Bytes.
attachments[].urlstring or null
Signed download URL (an hour); null in stored command results.
authorobject
author.avatarUrlstring or null
Avatar.
author.idstring (uuid)Required
Their ID.
author.kindstringRequired
Who wrote it.One of person, agent, api_key
author.namestringRequired
Name.
author.userIdstring (uuid) or null
The person behind it (the author, or the person an agent acts for); null for an API key.
bodystring
Markdown subset with @[Name](user:<id>) mentions.
createdAtstring (date-time)
Posted.
deletedboolean
Deleted.
deletedAtstring (date-time) or null
Deleted at.
editedAtstring (date-time) or null
Last edit.
idstring (uuid)Required
ID.
internalboolean
Hidden from guests: a thread kept from guests before guest access became per launch; guests never see it, its replies or reactions. Read only: no thread becomes hidden any more.
mentionsarray of strings (uuid)
Mentioned people.
parentIdstring (uuid) or null
The thread it replies to.
reactionsarray of objects
Reactions.
reactions[].countintegerRequired
How many.
reactions[].emojistringRequired
Emoji.
reactions[].userIdsarray of strings (uuid)Required
Who.
resolvedboolean
Thread resolved.
resolvedAtstring (date-time) or null
Resolved at.
resolvedBystring (uuid) or null
Who resolved it.
versioninteger
Increments on every change; send 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 POST "$PLUTO_API/comments/65d5adb8-9b81-44dc-9131-33b87d15eb2a/resolve" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 1852fe5a-3c79-4f68-9c62-f13dde58bc18"
POST/comments/{id}/restore

Undo deleting a comment

Within an hour of the delete: content, reactions and notifications come back.

Permission: reviewCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe comment'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

adIdstring (uuid)
Ad.
attachmentsarray of objects
Attachments.
attachments[].contentTypestringRequired
MIME type.
attachments[].idstring (uuid)Required
Attachment.
attachments[].mediaIdstring (uuid)
Library media, when attached from it.
attachments[].namestringRequired
Name.
attachments[].sizeintegerRequired
Bytes.
attachments[].urlstring or null
Signed download URL (an hour); null in stored command results.
authorobject
author.avatarUrlstring or null
Avatar.
author.idstring (uuid)Required
Their ID.
author.kindstringRequired
Who wrote it.One of person, agent, api_key
author.namestringRequired
Name.
author.userIdstring (uuid) or null
The person behind it (the author, or the person an agent acts for); null for an API key.
bodystring
Markdown subset with @[Name](user:<id>) mentions.
createdAtstring (date-time)
Posted.
deletedboolean
Deleted.
deletedAtstring (date-time) or null
Deleted at.
editedAtstring (date-time) or null
Last edit.
idstring (uuid)Required
ID.
internalboolean
Hidden from guests: a thread kept from guests before guest access became per launch; guests never see it, its replies or reactions. Read only: no thread becomes hidden any more.
mentionsarray of strings (uuid)
Mentioned people.
parentIdstring (uuid) or null
The thread it replies to.
reactionsarray of objects
Reactions.
reactions[].countintegerRequired
How many.
reactions[].emojistringRequired
Emoji.
reactions[].userIdsarray of strings (uuid)Required
Who.
resolvedboolean
Thread resolved.
resolvedAtstring (date-time) or null
Resolved at.
resolvedBystring (uuid) or null
Who resolved it.
versioninteger
Increments on every change; send 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 POST "$PLUTO_API/comments/65d5adb8-9b81-44dc-9131-33b87d15eb2a/restore" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 02f3ffac-4e1e-4c8d-914e-b23caf5b2b7c"
PUT/comments/{id}/subscription

Subscribe to a thread

Needs a person: API keys and M2M clients get 403; a connected agent or an mcp agent client acts for its person and can.

Permission: readGuests tooCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe comment'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

subscribedbooleanRequired
Follow or not.

Response200 OK

Subscription.

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/comments/65d5adb8-9b81-44dc-9131-33b87d15eb2a/subscription" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: c13d6347-3894-488f-988f-7301b9009186" \
  -H "Content-Type: application/json" \
  -d '{
    "subscribed": true
  }'
GET/ads/{ad_id}/comments

List comment threads on an ad

Permission: readGuests too

Parameters

NameTypeRequiredDescription
ad_idpathstringRequiredThe ad's ID.
afterquerystringOptionalCursor: nextAfter of the previous page.
limitquerystringOptionalPage size (1-500).
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

nextAfterstring or null
Cursor for the next page; null at the end.
threadsarray of objectsRequired
Threads, oldest first.
threads[].adIdstring (uuid)
Ad.
threads[].attachmentsarray of objects
Attachments.
threads[].attachments[].contentTypestringRequired
MIME type.
threads[].attachments[].idstring (uuid)Required
Attachment.
threads[].attachments[].mediaIdstring (uuid)
Library media, when attached from it.
threads[].attachments[].namestringRequired
Name.
threads[].attachments[].sizeintegerRequired
Bytes.
threads[].attachments[].urlstring or null
Signed download URL (an hour); null in stored command results.
threads[].authorobject
threads[].author.avatarUrlstring or null
Avatar.
threads[].author.idstring (uuid)Required
Their ID.
threads[].author.kindstringRequired
Who wrote it.One of person, agent, api_key
threads[].author.namestringRequired
Name.
threads[].author.userIdstring (uuid) or null
The person behind it (the author, or the person an agent acts for); null for an API key.
threads[].bodystring
Markdown subset with @[Name](user:<id>) mentions.
threads[].createdAtstring (date-time)
Posted.
threads[].deletedboolean
Deleted.
threads[].deletedAtstring (date-time) or null
Deleted at.
threads[].editedAtstring (date-time) or null
Last edit.
threads[].idstring (uuid)Required
ID.
threads[].internalboolean
Hidden from guests: a thread kept from guests before guest access became per launch; guests never see it, its replies or reactions. Read only: no thread becomes hidden any more.
threads[].mentionsarray of strings (uuid)
Mentioned people.
threads[].parentIdstring (uuid) or null
The thread it replies to.
threads[].reactionsarray of objects
Reactions.
threads[].reactions[].countintegerRequired
How many.
threads[].reactions[].emojistringRequired
Emoji.
threads[].reactions[].userIdsarray of strings (uuid)Required
Who.
threads[].resolvedboolean
Thread resolved.
threads[].resolvedAtstring (date-time) or null
Resolved at.
threads[].resolvedBystring (uuid) or null
Who resolved it.
threads[].versioninteger
Increments on every change; send as expectedVersion.
threads[].repliesarray of objectsRequired
Replies in order.
threads[].replies[].adIdstring (uuid)
Ad.
threads[].replies[].attachmentsarray of objects
Attachments.
threads[].replies[].attachments[].contentTypestringRequired
MIME type.
threads[].replies[].attachments[].idstring (uuid)Required
Attachment.
threads[].replies[].attachments[].mediaIdstring (uuid)
Library media, when attached from it.
threads[].replies[].attachments[].namestringRequired
Name.
threads[].replies[].attachments[].sizeintegerRequired
Bytes.
threads[].replies[].attachments[].urlstring or null
Signed download URL (an hour); null in stored command results.
threads[].replies[].authorobject
threads[].replies[].author.avatarUrlstring or null
Avatar.
threads[].replies[].author.idstring (uuid)Required
Their ID.
threads[].replies[].author.kindstringRequired
Who wrote it.One of person, agent, api_key
threads[].replies[].author.namestringRequired
Name.
threads[].replies[].author.userIdstring (uuid) or null
The person behind it (the author, or the person an agent acts for); null for an API key.
threads[].replies[].bodystring
Markdown subset with @[Name](user:<id>) mentions.
threads[].replies[].createdAtstring (date-time)
Posted.
threads[].replies[].deletedboolean
Deleted.
threads[].replies[].deletedAtstring (date-time) or null
Deleted at.
threads[].replies[].editedAtstring (date-time) or null
Last edit.
threads[].replies[].idstring (uuid)Required
ID.
threads[].replies[].internalboolean
Hidden from guests: a thread kept from guests before guest access became per launch; guests never see it, its replies or reactions. Read only: no thread becomes hidden any more.
threads[].replies[].mentionsarray of strings (uuid)
Mentioned people.
threads[].replies[].parentIdstring (uuid) or null
The thread it replies to.
threads[].replies[].reactionsarray of objects
Reactions.
threads[].replies[].reactions[].countintegerRequired
How many.
threads[].replies[].reactions[].emojistringRequired
Emoji.
threads[].replies[].reactions[].userIdsarray of strings (uuid)Required
Who.
threads[].replies[].resolvedboolean
Thread resolved.
threads[].replies[].resolvedAtstring (date-time) or null
Resolved at.
threads[].replies[].resolvedBystring (uuid) or null
Who resolved it.
threads[].replies[].versioninteger
Increments on every change; send as expectedVersion.
threads[].subscribedbooleanRequired
Whether the reader follows the thread.

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/ads/a96d7456-dc02-4734-998b-3e439361abe3/comments" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/ads/{ad_id}/comments

Comment on an ad

People, agents and API keys comment as themselves: author.kind is person, agent or api_key. Who sees a comment follows its launch: guests read every comment on a launch shared with them, and none on any other.

Permission: reviewCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
ad_idpathstringRequiredThe ad'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

attachmentsarray of objects
Attachments.
bodystringRequired
Text; @mentions notify.
idstring (uuid)
Optional ID.
parentIdstring (uuid)
Reply to a thread.

Response201 Created

adIdstring (uuid)
Ad.
attachmentsarray of objects
Attachments.
attachments[].contentTypestringRequired
MIME type.
attachments[].idstring (uuid)Required
Attachment.
attachments[].mediaIdstring (uuid)
Library media, when attached from it.
attachments[].namestringRequired
Name.
attachments[].sizeintegerRequired
Bytes.
attachments[].urlstring or null
Signed download URL (an hour); null in stored command results.
authorobject
author.avatarUrlstring or null
Avatar.
author.idstring (uuid)Required
Their ID.
author.kindstringRequired
Who wrote it.One of person, agent, api_key
author.namestringRequired
Name.
author.userIdstring (uuid) or null
The person behind it (the author, or the person an agent acts for); null for an API key.
bodystring
Markdown subset with @[Name](user:<id>) mentions.
createdAtstring (date-time)
Posted.
deletedboolean
Deleted.
deletedAtstring (date-time) or null
Deleted at.
editedAtstring (date-time) or null
Last edit.
idstring (uuid)Required
ID.
internalboolean
Hidden from guests: a thread kept from guests before guest access became per launch; guests never see it, its replies or reactions. Read only: no thread becomes hidden any more.
mentionsarray of strings (uuid)
Mentioned people.
parentIdstring (uuid) or null
The thread it replies to.
reactionsarray of objects
Reactions.
reactions[].countintegerRequired
How many.
reactions[].emojistringRequired
Emoji.
reactions[].userIdsarray of strings (uuid)Required
Who.
resolvedboolean
Thread resolved.
resolvedAtstring (date-time) or null
Resolved at.
resolvedBystring (uuid) or null
Who resolved it.
versioninteger
Increments on every change; send 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 POST "$PLUTO_API/ads/a96d7456-dc02-4734-998b-3e439361abe3/comments" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 74e052e4-4ecd-48be-8cb4-e9264c7c3ec5" \
  -H "Content-Type: application/json" \
  -d '{
    "attachments": [
      {}
    ],
    "body": "Can we try the 4x5 cut for Instagram feed before we publish?",
    "id": "a96d7456-dc02-4734-998b-3e439361abe3",
    "parentId": "7c19c95a-2160-43ed-9554-9d8b7f4bf5a4"
  }'
GET/ads/{ad_id}/activity

List activity on an ad

Changes and comment threads, oldest first. Page forward with after, or back from an entry you have with before (its ID): the page just before it, still oldest first, with nextBefore to go further back (null at the ad's first entry).

Permission: readGuests too

Parameters

NameTypeRequiredDescription
ad_idpathstringRequiredThe ad's ID.
afterquerystringOptionalCursor: nextAfter of the previous page.
beforequerystringOptionalThe ID of an entry (a change, or a thread's first comment): the entries just before it. Not with after.
limitquerystringOptionalPage size (1-200, default 50).
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, oldest first.
nextAfterstring or null
Cursor for the next page; null at the end, and with before.
nextBeforestring (uuid) or null
With before: pass as before for the entries before this page; null at the ad's first entry.

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/ads/a96d7456-dc02-4734-998b-3e439361abe3/activity" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/ads/{ad_id}/subscription

Get an ad's subscribers

Needs a person: API keys and M2M clients get 403; a connected agent or an mcp agent client acts for its person and can.

Permission: readGuests too

Parameters

NameTypeRequiredDescription
ad_idpathstringRequiredThe ad'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

subscribed and followers.

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/ads/a96d7456-dc02-4734-998b-3e439361abe3/subscription" \
  -H "Authorization: Bearer $PLUTO_KEY"
PUT/ads/{ad_id}/subscription

Subscribe to an ad

Needs a person: API keys and M2M clients get 403; a connected agent or an mcp agent client acts for its person and can.

Permission: readGuests tooCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
ad_idpathstringRequiredThe ad'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

subscribedbooleanRequired
Follow or not.

Response200 OK

Subscription.

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/ads/a96d7456-dc02-4734-998b-3e439361abe3/subscription" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 342cec49-24e8-48a0-948a-514338dd0f42" \
  -H "Content-Type: application/json" \
  -d '{
    "subscribed": true
  }'