Social API

Social features let users follow creators, like REPLRs, view feeds, and share. All endpoints require authentication via a Bearer token.

Base URL

https://api.replr.ai/v1

Follow & Unfollow

POST/v1/social/follow/:user_idAuth Required

Follow a user or creator. Silently succeeds if the caller already follows them.

Path Parameters

Name	Type	Required	Description
`user_id`	string	Required	Unique identifier of the target user.

Response

{
  "id": "flw_a1b2c3d4e5f6",
  "follower_id": "usr_k8m2x9q4w1",
  "following_id": "usr_j7n3v6t0p2",
  "created_at": "2026-03-09T14:22:08Z"
}

DELETE/v1/social/follow/:user_idAuth Required

Unfollow a user. Returns 204 on success, even if the relationship did not exist.

Path Parameters

Name	Type	Required	Description
`user_id`	string	Required	Unique identifier of the target user.

Response

{
  "success": true
}

Followers & Following

GET/v1/social/followersAuth Required

List the current authenticated user's followers, ordered by most recent.

Path Parameters

Name	Type	Required	Description
`limit`	integer	Optional	Max items to return (default 20, max 100).
`offset`	integer	Optional	Number of items to skip for pagination.

Response

{
  "data": [
    {
      "id": "usr_j7n3v6t0p2",
      "username": "synthwave_sam",
      "avatar_url": "https://cdn.replr.ai/avatars/usr_j7n3v6t0p2.webp",
      "followed_at": "2026-03-08T09:15:32Z"
    },
    {
      "id": "usr_q4r8y2e6m0",
      "username": "pixel_nova",
      "avatar_url": "https://cdn.replr.ai/avatars/usr_q4r8y2e6m0.webp",
      "followed_at": "2026-03-05T21:47:10Z"
    }
  ],
  "total": 84,
  "limit": 20,
  "offset": 0
}

GET/v1/social/followingAuth Required

List users the current authenticated user follows.

Path Parameters

Name	Type	Required	Description
`limit`	integer	Optional	Max items to return (default 20, max 100).
`offset`	integer	Optional	Number of items to skip for pagination.

Response

{
  "data": [
    {
      "id": "usr_m5w1z8c3a9",
      "username": "echo_creator",
      "avatar_url": "https://cdn.replr.ai/avatars/usr_m5w1z8c3a9.webp",
      "followed_at": "2026-03-07T16:33:44Z"
    }
  ],
  "total": 12,
  "limit": 20,
  "offset": 0
}

Profile & Search

GET/v1/social/profile/:user_idAuth Required

Get a user's public profile including username, bio, avatar, REPLR count, and follower count.

Path Parameters

Name	Type	Required	Description
`user_id`	string	Required	Unique identifier of the target user.

Response

{
  "id": "usr_m5w1z8c3a9",
  "username": "echo_creator",
  "bio": "Building conversational AI companions that feel alive.",
  "avatar_url": "https://cdn.replr.ai/avatars/usr_m5w1z8c3a9.webp",
  "replr_count": 7,
  "follower_count": 2341,
  "following_count": 58,
  "created_at": "2025-11-02T08:14:00Z"
}

GET/v1/social/searchAuth Required

Search for users by username or display name. Returns up to limit results ranked by relevance.

Path Parameters

Name	Type	Required	Description
`q`	string	Required	Search query (min 2 characters).
`limit`	integer	Optional	Max results to return (default 20, max 50).

Response

{
  "data": [
    {
      "id": "usr_m5w1z8c3a9",
      "username": "echo_creator",
      "avatar_url": "https://cdn.replr.ai/avatars/usr_m5w1z8c3a9.webp",
      "follower_count": 2341
    },
    {
      "id": "usr_t6h0b4f8k2",
      "username": "echo_dev",
      "avatar_url": "https://cdn.replr.ai/avatars/usr_t6h0b4f8k2.webp",
      "follower_count": 189
    }
  ],
  "total": 2,
  "limit": 20
}

Likes

POST/v1/social/likes/:replr_idAuth Required

Like a REPLR. Silently succeeds if the caller has already liked it.

Path Parameters

Name	Type	Required	Description
`replr_id`	string	Required	Unique identifier of the REPLR.

Response

{
  "id": "lik_x3f9c1v7m2",
  "user_id": "usr_k8m2x9q4w1",
  "replr_id": "rpl_g4t8n2q6y0",
  "created_at": "2026-03-09T15:01:44Z"
}

DELETE/v1/social/likes/:replr_idAuth Required

Remove a like from a REPLR.

Path Parameters

Name	Type	Required	Description
`replr_id`	string	Required	Unique identifier of the REPLR.

Response

{
  "success": true
}

GET/v1/social/likesAuth Required

List REPLRs the authenticated user has liked, ordered by most recent.

Path Parameters

Name	Type	Required	Description
`limit`	integer	Optional	Max items to return (default 20, max 100).
`offset`	integer	Optional	Number of items to skip for pagination.

Response

{
  "data": [
    {
      "replr_id": "rpl_g4t8n2q6y0",
      "name": "Luna",
      "tagline": "Empathetic night-owl companion",
      "avatar_url": "https://cdn.replr.ai/replrs/rpl_g4t8n2q6y0.webp",
      "creator": {
        "id": "usr_m5w1z8c3a9",
        "username": "echo_creator"
      },
      "liked_at": "2026-03-09T15:01:44Z"
    },
    {
      "replr_id": "rpl_b2w5k8r1d7",
      "name": "Atlas",
      "tagline": "Your no-nonsense coding mentor",
      "avatar_url": "https://cdn.replr.ai/replrs/rpl_b2w5k8r1d7.webp",
      "creator": {
        "id": "usr_t6h0b4f8k2",
        "username": "echo_dev"
      },
      "liked_at": "2026-03-06T10:29:17Z"
    }
  ],
  "total": 23,
  "limit": 20,
  "offset": 0
}

Feed

GET/v1/social/feedAuth Required

Get the authenticated user's activity feed. Includes new REPLRs published by followed users and trending items.

Path Parameters

Name	Type	Required	Description
`limit`	integer	Optional	Max items to return (default 20, max 100).
`offset`	integer	Optional	Number of items to skip for pagination.

Response

{
  "data": [
    {
      "type": "new_replr",
      "replr": {
        "id": "rpl_p9s3j6a0f4",
        "name": "Vex",
        "tagline": "Chaotic-good debate partner",
        "avatar_url": "https://cdn.replr.ai/replrs/rpl_p9s3j6a0f4.webp",
        "like_count": 47
      },
      "creator": {
        "id": "usr_m5w1z8c3a9",
        "username": "echo_creator"
      },
      "published_at": "2026-03-09T12:00:00Z"
    },
    {
      "type": "trending",
      "replr": {
        "id": "rpl_g4t8n2q6y0",
        "name": "Luna",
        "tagline": "Empathetic night-owl companion",
        "avatar_url": "https://cdn.replr.ai/replrs/rpl_g4t8n2q6y0.webp",
        "like_count": 1580
      },
      "creator": {
        "id": "usr_m5w1z8c3a9",
        "username": "echo_creator"
      },
      "trending_since": "2026-03-08T00:00:00Z"
    }
  ],
  "total": 56,
  "limit": 20,
  "offset": 0
}

POST/v1/social/share/:replr_idAuth Required

Generate a platform-specific share link for a REPLR. Tracks share analytics.

Path Parameters

Name	Type	Required	Description
`replr_id`	string	Required	Unique identifier of the REPLR.

Request Body

Name	Type	Required	Description
`platform`	string	Required	Target platform. One of "twitter", "discord", or "link".

Response

{
  "share_url": "https://replr.ai/s/rpl_g4t8n2q6y0?ref=tw_usr_k8m2x9q4w1",
  "platform": "twitter",
  "replr_id": "rpl_g4t8n2q6y0",
  "expires_at": null
}

Social API

Social features let users follow creators, like REPLRs, view feeds, and share. All endpoints require authentication via a Bearer token.

Base URL

https://api.replr.ai/v1

Follow & Unfollow

POST/v1/social/follow/:user_idAuth Required

Follow a user or creator. Silently succeeds if the caller already follows them.

Path Parameters

Name	Type	Required	Description
`user_id`	string	Required	Unique identifier of the target user.

Response

{
  "id": "flw_a1b2c3d4e5f6",
  "follower_id": "usr_k8m2x9q4w1",
  "following_id": "usr_j7n3v6t0p2",
  "created_at": "2026-03-09T14:22:08Z"
}

DELETE/v1/social/follow/:user_idAuth Required

Unfollow a user. Returns 204 on success, even if the relationship did not exist.

Path Parameters

Name	Type	Required	Description
`user_id`	string	Required	Unique identifier of the target user.

Response

{
  "success": true
}

Followers & Following

GET/v1/social/followersAuth Required

List the current authenticated user's followers, ordered by most recent.

Path Parameters

Name	Type	Required	Description
`limit`	integer	Optional	Max items to return (default 20, max 100).
`offset`	integer	Optional	Number of items to skip for pagination.

Response

{
  "data": [
    {
      "id": "usr_j7n3v6t0p2",
      "username": "synthwave_sam",
      "avatar_url": "https://cdn.replr.ai/avatars/usr_j7n3v6t0p2.webp",
      "followed_at": "2026-03-08T09:15:32Z"
    },
    {
      "id": "usr_q4r8y2e6m0",
      "username": "pixel_nova",
      "avatar_url": "https://cdn.replr.ai/avatars/usr_q4r8y2e6m0.webp",
      "followed_at": "2026-03-05T21:47:10Z"
    }
  ],
  "total": 84,
  "limit": 20,
  "offset": 0
}

GET/v1/social/followingAuth Required

List users the current authenticated user follows.

Path Parameters

Name	Type	Required	Description
`limit`	integer	Optional	Max items to return (default 20, max 100).
`offset`	integer	Optional	Number of items to skip for pagination.

Response

{
  "data": [
    {
      "id": "usr_m5w1z8c3a9",
      "username": "echo_creator",
      "avatar_url": "https://cdn.replr.ai/avatars/usr_m5w1z8c3a9.webp",
      "followed_at": "2026-03-07T16:33:44Z"
    }
  ],
  "total": 12,
  "limit": 20,
  "offset": 0
}

Profile & Search

GET/v1/social/profile/:user_idAuth Required

Get a user's public profile including username, bio, avatar, REPLR count, and follower count.

Path Parameters

Name	Type	Required	Description
`user_id`	string	Required	Unique identifier of the target user.

Response

{
  "id": "usr_m5w1z8c3a9",
  "username": "echo_creator",
  "bio": "Building conversational AI companions that feel alive.",
  "avatar_url": "https://cdn.replr.ai/avatars/usr_m5w1z8c3a9.webp",
  "replr_count": 7,
  "follower_count": 2341,
  "following_count": 58,
  "created_at": "2025-11-02T08:14:00Z"
}

GET/v1/social/searchAuth Required

Search for users by username or display name. Returns up to limit results ranked by relevance.

Path Parameters

Name	Type	Required	Description
`q`	string	Required	Search query (min 2 characters).
`limit`	integer	Optional	Max results to return (default 20, max 50).

Response

{
  "data": [
    {
      "id": "usr_m5w1z8c3a9",
      "username": "echo_creator",
      "avatar_url": "https://cdn.replr.ai/avatars/usr_m5w1z8c3a9.webp",
      "follower_count": 2341
    },
    {
      "id": "usr_t6h0b4f8k2",
      "username": "echo_dev",
      "avatar_url": "https://cdn.replr.ai/avatars/usr_t6h0b4f8k2.webp",
      "follower_count": 189
    }
  ],
  "total": 2,
  "limit": 20
}

Likes

POST/v1/social/likes/:replr_idAuth Required

Like a REPLR. Silently succeeds if the caller has already liked it.

Path Parameters

Name	Type	Required	Description
`replr_id`	string	Required	Unique identifier of the REPLR.

Response

{
  "id": "lik_x3f9c1v7m2",
  "user_id": "usr_k8m2x9q4w1",
  "replr_id": "rpl_g4t8n2q6y0",
  "created_at": "2026-03-09T15:01:44Z"
}

DELETE/v1/social/likes/:replr_idAuth Required

Remove a like from a REPLR.

Path Parameters

Name	Type	Required	Description
`replr_id`	string	Required	Unique identifier of the REPLR.

Response

{
  "success": true
}

GET/v1/social/likesAuth Required

List REPLRs the authenticated user has liked, ordered by most recent.

Path Parameters

Name	Type	Required	Description
`limit`	integer	Optional	Max items to return (default 20, max 100).
`offset`	integer	Optional	Number of items to skip for pagination.

Response

{
  "data": [
    {
      "replr_id": "rpl_g4t8n2q6y0",
      "name": "Luna",
      "tagline": "Empathetic night-owl companion",
      "avatar_url": "https://cdn.replr.ai/replrs/rpl_g4t8n2q6y0.webp",
      "creator": {
        "id": "usr_m5w1z8c3a9",
        "username": "echo_creator"
      },
      "liked_at": "2026-03-09T15:01:44Z"
    },
    {
      "replr_id": "rpl_b2w5k8r1d7",
      "name": "Atlas",
      "tagline": "Your no-nonsense coding mentor",
      "avatar_url": "https://cdn.replr.ai/replrs/rpl_b2w5k8r1d7.webp",
      "creator": {
        "id": "usr_t6h0b4f8k2",
        "username": "echo_dev"
      },
      "liked_at": "2026-03-06T10:29:17Z"
    }
  ],
  "total": 23,
  "limit": 20,
  "offset": 0
}

Feed

GET/v1/social/feedAuth Required

Get the authenticated user's activity feed. Includes new REPLRs published by followed users and trending items.

Path Parameters

Name	Type	Required	Description
`limit`	integer	Optional	Max items to return (default 20, max 100).
`offset`	integer	Optional	Number of items to skip for pagination.

Response

{
  "data": [
    {
      "type": "new_replr",
      "replr": {
        "id": "rpl_p9s3j6a0f4",
        "name": "Vex",
        "tagline": "Chaotic-good debate partner",
        "avatar_url": "https://cdn.replr.ai/replrs/rpl_p9s3j6a0f4.webp",
        "like_count": 47
      },
      "creator": {
        "id": "usr_m5w1z8c3a9",
        "username": "echo_creator"
      },
      "published_at": "2026-03-09T12:00:00Z"
    },
    {
      "type": "trending",
      "replr": {
        "id": "rpl_g4t8n2q6y0",
        "name": "Luna",
        "tagline": "Empathetic night-owl companion",
        "avatar_url": "https://cdn.replr.ai/replrs/rpl_g4t8n2q6y0.webp",
        "like_count": 1580
      },
      "creator": {
        "id": "usr_m5w1z8c3a9",
        "username": "echo_creator"
      },
      "trending_since": "2026-03-08T00:00:00Z"
    }
  ],
  "total": 56,
  "limit": 20,
  "offset": 0
}

POST/v1/social/share/:replr_idAuth Required

Generate a platform-specific share link for a REPLR. Tracks share analytics.

Path Parameters

Name	Type	Required	Description
`replr_id`	string	Required	Unique identifier of the REPLR.

Request Body

Name	Type	Required	Description
`platform`	string	Required	Target platform. One of "twitter", "discord", or "link".

Response

{
  "share_url": "https://replr.ai/s/rpl_g4t8n2q6y0?ref=tw_usr_k8m2x9q4w1",
  "platform": "twitter",
  "replr_id": "rpl_g4t8n2q6y0",
  "expires_at": null
}

Social API

Follow & Unfollow

Path Parameters

Response

Path Parameters

Response

Followers & Following

Path Parameters

Response

Path Parameters

Response

Profile & Search

Path Parameters

Response

Path Parameters

Response

Likes

Path Parameters

Response

Path Parameters

Response

Path Parameters

Response

Feed

Path Parameters

Response

Share

Path Parameters

Request Body

Response

Social API

Follow & Unfollow

Path Parameters

Response

Path Parameters

Response

Followers & Following

Path Parameters

Response

Path Parameters

Response

Profile & Search

Path Parameters

Response

Path Parameters

Response

Likes

Path Parameters

Response

Path Parameters

Response

Path Parameters

Response

Feed

Path Parameters

Response

Share

Path Parameters

Request Body

Response