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. Engaging is free and never spends credits.

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. Publishing is live on all nine. The platform support page lists exactly what each one can do today, generated from the same table the API validates against. Some secondary features stay gated by partner review.