Skip to main content

Follows API

The Follows API adds a social layer on top of user-to-user sharing:

  • Private profile: a follow starts as a request and must be approved.
  • Public profile: a follow is auto-accepted and grants read-only access to everything.

Under the hood, accepting a follow creates a read-only SharingPermission (see Sharing API).

Base URL​

https://api.ofself.ai/api/v1

Authentication​

All endpoints require a JWT token:

  • Authorization: Bearer <token>

Endpoints​

POST /follows​

Create a follow (or follow request for private accounts).

curl -X POST "https://api.ofself.ai/api/v1/follows" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "target_user_id": "user-uuid",
    "message": "optional message"
  }'

Behavior

  • If the target user has is_public=true: the follow is created as accepted and grants read-only sharing (scope=all).
  • If the target user has is_public=false: the follow is created as pending.

GET /follows/incoming​

List follow requests/relationships where you are the followed user.

Query parameters:

  • status: pending|accepted|declined|revoked (optional)
  • limit (default 20, max 100)
  • offset (default 0)
curl -X GET "https://api.ofself.ai/api/v1/follows/incoming?status=pending&limit=50&offset=0" \
  -H "Authorization: Bearer your-jwt-token"

GET /follows/outgoing​

List follow requests/relationships where you are the follower.

curl -X GET "https://api.ofself.ai/api/v1/follows/outgoing?limit=50&offset=0" \
  -H "Authorization: Bearer your-jwt-token"

PUT /follows/:follow_id/respond​

Accept or decline a follow request (only the followed user can respond).

Body:

  • action: accept | decline
  • share (required for accept):
    • scope: all|specific_tags|specific_nodes
    • tag_ids: required if scope=specific_tags
    • node_ids: required if scope=specific_nodes
curl -X PUT "https://api.ofself.ai/api/v1/follows/<follow_id>/respond" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "accept",
    "share": {
      "scope": "specific_tags",
      "tag_ids": ["tag-uuid-1", "tag-uuid-2"]
    }
  }'

Notes:

  • Sharing is read-only for now (write/delete/share are disabled).

DELETE /follows/:follow_id​

Unfollow / remove follower. This also revokes the associated SharingPermission (if any).

curl -X DELETE "https://api.ofself.ai/api/v1/follows/<follow_id>" \
  -H "Authorization: Bearer your-jwt-token"