Social API reference

Social API · Edges

post/v1/communities/{community_id}/followsAuth

Follow another actor. Idempotent. If the destination is private (task 014), a follow request is created instead and the response is `{ status: "pending", edge: null }`; approve/decline it via the follow-request routes. Refused if either side has a block.

Path parameters

community_id*string

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

Headers

Idempotency-Keystring

Opaque client-generated string (1-256 chars, `[A-Za-z0-9._:-]`) that makes a retry safe: within 24 h a repeat with the same key and body returns the original response with `Idempotent-Replay: true` instead of running again. Same key with a different body is `409 IDEMPOTENCY_KEY_REUSE`.

Request body

actor_id*string · uuid

Acting social actor UUID (the one performing the follow / mute / block / restrict). Standardized name (task 008 / G11).

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

dst_actor_id*string · uuid

Destination social actor UUID (the one being followed / muted / blocked / restricted).

Example: "aaaaaaaa-0000-0000-0000-000000000002"

payloadobject

Optional free-form payload stored on the edge (e.g. mute reason).

Response · 201 Follow edge created / exists (`status: followed`), or a follow request created (`status: pending`).

status*object

`followed` = an edge exists; `pending` = a follow request was created (private dst).

Example: "followed"

edge*object

The follow edge when `status=followed`; null when `pending`.

created*boolean

`true` if the edge / request was created on this call; `false` on idempotent retry.

Example: true

Example

Request

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

{
  "actor_id": "aaaaaaaa-0000-0000-0000-000000000001",
  "dst_actor_id": "aaaaaaaa-0000-0000-0000-000000000002",
  "payload": {}
}

Response

{
  "status": "followed",
  "edge": {},
  "created": true
}