Social API reference

Social API · Bookmarks

post/v1/communities/{community_id}/posts/{post_id}/bookmarkAuth

Bookmark a post on behalf of an actor. Idempotent — returns the existing row with `created: false` on retry.

Visibility-aware: the actor must be allowed to read the post. If they can't, returns 404 (opaque), matching the read-path opacity rule used everywhere else in Social.

Path parameters

community_id*string

Social community UUID. Must belong to the PAK's workspace.

post_id*string

Social post UUID.

Request body

actor_id*string · uuid

Social actor UUID who is bookmarking — the customer-backend supplies the end-user identity here.

Example: "aaaaaaaa-0000-0000-0000-000000000001"

collection_idsarray

Optional collection UUIDs (task 020) to file this post into alongside the flat bookmark. Only the actor's own collections are written; unknown/other-owner ids are silently skipped. Max 20.

Example: ["99999999-0000-0000-0000-000000000001"]

Response · 201 Bookmark created (or returned via idempotent retry).

bookmark*object
actor_id*string · uuid

Social actor UUID who saved the post.

Example: "aaaaaaaa-0000-0000-0000-000000000001"

post_id*string · uuid

Saved post UUID.

Example: "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"

community_id*string · uuid

Owning community UUID.

Example: "cccccccc-cccc-cccc-cccc-cccccccccccc"

created_at*string · date-time

ISO timestamp the bookmark was created.

Example: "2026-05-01T12:00:00.000Z"

created*boolean

`true` on first call (row inserted); `false` on idempotent retry of an existing bookmark.

Example: true

Example

Request

POST https://social.productcraft.co/v1/communities/{community_id}/posts/{post_id}/bookmark
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "actor_id": "aaaaaaaa-0000-0000-0000-000000000001",
  "collection_ids": [
    "99999999-0000-0000-0000-000000000001"
  ]
}

Response

{
  "bookmark": {
    "actor_id": "aaaaaaaa-0000-0000-0000-000000000001",
    "post_id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
    "community_id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
    "created_at": "2026-05-01T12:00:00.000Z"
  },
  "created": true
}