Guides

Reading and engaging

Publishing is half of managing an account. These endpoints cover the other half: what happened, what people said, and answering them.

MCP equivalents are list_notifications, mark_notifications_seen, read_comments, reply_to_comment, engage, and update_profile. See the MCP guide.

What happened

GET /v1/notifications returns likes, replies, mentions, follows, reposts and quotes from every connected network, newest first, in one shape. It is the read to start from when an agent asks "what needs my attention".

curl https://api.postlake.dev/v1/notifications?limit=25 \
  -H "authorization: Bearer $POSTLAKE_KEY"

Every list tells you what it could not read

Responses are { items, cursor, problems }. problems is the important part. A network that is unreachable, unauthorised or simply not supported yet is named there, so an empty items never has to stand in for "we could not look".

{
  "items": [ ... ],
  "cursor": "eyJhY2Nf...",
  "problems": [
    { "platform": "tiktok", "reason": "We cannot read this on tiktok yet." }
  ]
}

Nothing found and could not look are different answers. Check problems before concluding an account is quiet.

Paging

Pass cursor back exactly as you got it. Never build or parse one: a cross-network read encodes a separate position per network inside it, and the contents will change. cursor: null means the end.

Replies on a post

GET /v1/posts/{id}/comments reads the conversation under something you published, across every network it went to. Replies nest one level; going deeper is another call.

Add ?nested=true to read the whole thread, replies to replies included. Networks that cannot go deeper answer with the top level instead of refusing, so it is always safe to ask.

Each reply carries hidden: true if you have hidden it, false if it is visible, and null where the network does not say. Treat null as "we cannot tell", not as "not hidden", or an agent will keep trying to hide the same reply.

Hiding a reply

POST /v1/comments/{id}/hide hides a reply on one of your posts. Send {"hidden": false} to put it back.

curl -X POST https://api.postlake.dev/v1/comments/17901.../hide \
  -H "authorization: Bearer $POSTLAKE_KEY" \
  -H "content-type: application/json" \
  -d '{"account":"acc_7f3k9"}'

This is the other half of replying. Without it, the only answer to an abusive comment is to write another one. If the call fails, the reply is still visible: treat an error as "still there", never as "probably fine".

Some networks will not let you hide your own reply. Threads is one, and it says so in the error rather than failing vaguely.

Searching, and looking people up

Everything above reads your own corner of each network. /v1/discover reads the network itself, which is what lets an agent look before it speaks.

curl "https://api.postlake.dev/v1/discover/posts?q=social+media+api&sort=recent" \
  -H "authorization: Bearer $POSTLAKE_KEY"

Endpoint	What it does
`GET /v1/discover/posts`	Search public posts by keyword, or by topic tag with `mode=tag`. Narrow with `sort`, `mediaType`, `author`, `since` and `until`.
`GET /v1/discover/profiles/{handle}`	Look someone up: name, bio, verified, follower count, and recent engagement where the network publishes it.
`GET /v1/discover/profiles/{handle}/posts`	Read someone else's public posts.
`GET /v1/discover/places`	Find a place to tag on a post, by name or by `latitude` and `longitude`. The id goes in that network's `locationId` option.

Searching merges every connected network that can search, and names the ones that cannot in problems. The other three need an account, because the same handle on two networks is usually two different people and merging them would invent someone who does not exist.

Counts are null where a network does not publish them, never 0. "We could not see it" and "they have none" are different answers.

Engaging

One endpoint, one vocabulary. POST /v1/engagements takes an action of like, unlike, repost, unrepost, follow, unfollow, block, unblock, mute or unmute.

curl -X POST https://api.postlake.dev/v1/engagements \
  -H "authorization: Bearer $POSTLAKE_KEY" \
  -H "content-type: application/json" \
  -d '{"account":"acc_7f3k9","action":"like","target":"https://bsky.app/profile/alice.bsky.social/post/3l..."}'

target is a post (a uri or its web url) for likes and reposts, or a handle for follows, blocks and mutes. Other networks are free. X actions spend funded credits according to the action.

X billing and spending safeguards

X always uses PostLake's shared developer app. Customer-owned X app credentials are not supported. Stored analytics reports do not contact X or spend refresh credits.

Mentions and comments: 6 credits per returned provider row, including author lookup coverage.
Followers: 4 credits per returned user. Message events: 8 credits per event, even when several events become one conversation.
Post analytics: 4 credits per refresh attempt, covering up to two provider reads. Channel identity refresh: 4 credits.
Replies cost 8 credits for text or 90 with a link. Thread parts and first comments are separate X posts; media alt-text metadata costs 2 credits per item.
X operations reserve credits before contacting X. Free monthly grants cannot fund X. Unused read reservations return to their original monthly or pack buckets.
Provider minimum page sizes apply: 5 mentions or 10 comments. A balance too small for that page is refused before the call.
Daily safety reservations cap each workspace at 10,000 credits and the service at 50,000 credits, resetting by UTC day. Attempts count even when they fail. These safeguards are separate from ordinary request rate limits.

Read reservations settle against provider rows before filtering or grouping. Explicit rejected reads refund their reservation. An ambiguous network failure retains its reservation because the provider may already have incurred cost; contact support for reconciliation. Pricing does not assume X's app-owner Owned Reads discount for shared-app customers.

A network that does not support an action refuses and names what it does support, rather than quietly doing nothing. Check the platform tables or GET /v1/platforms first.

Which networks can do this

Inbox, engage and discovery depth varies by network. Implemented capabilities do not imply public connection access. Read connectionAvailability on GET /v1/platforms before offering a network. Purchasing credits does not unlock gated connections. The platform support page lists implementation capabilities.