API Reference

Social API

Follow creators, like Dyvas, view feeds, and share. All endpoints require Bearer token authentication.

Base URL

https://api.dyva.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 your followers, most recent first.

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.dyva.ai/avatars/usr_j7n3v6t0p2.webp",
      "followed_at": "2026-03-08T09:15:32Z"
    },
    {
      "id": "usr_q4r8y2e6m0",
      "username": "pixel_nova",
      "avatar_url": "https://cdn.dyva.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 you follow.

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.dyva.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

Public profile: username, bio, avatar, Dyva 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.dyva.ai/avatars/usr_m5w1z8c3a9.webp",
  "dyva_count": 7,
  "follower_count": 2341,
  "following_count": 58,
  "created_at": "2025-11-02T08:14:00Z"
}

GET/v1/social/searchAuth Required

Search users by username or display name, 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.dyva.ai/avatars/usr_m5w1z8c3a9.webp",
      "follower_count": 2341
    },
    {
      "id": "usr_t6h0b4f8k2",
      "username": "echo_dev",
      "avatar_url": "https://cdn.dyva.ai/avatars/usr_t6h0b4f8k2.webp",
      "follower_count": 189
    }
  ],
  "total": 2,
  "limit": 20
}

Likes

POST/v1/social/likes/:dyva_idAuth Required

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

Path Parameters

Name	Type	Required	Description
`dyva_id`	string	Required	Unique identifier of the Dyva.

Response

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

DELETE/v1/social/likes/:dyva_idAuth Required

Remove a like from a Dyva.

Path Parameters

Name	Type	Required	Description
`dyva_id`	string	Required	Unique identifier of the Dyva.

Response

{
  "success": true
}

GET/v1/social/likesAuth Required

List Dyvas you have liked, most recent first.

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": [
    {
      "dyva_id": "rpl_g4t8n2q6y0",
      "name": "Luna",
      "tagline": "Empathetic night-owl companion",
      "avatar_url": "https://cdn.dyva.ai/dyvas/rpl_g4t8n2q6y0.webp",
      "creator": {
        "id": "usr_m5w1z8c3a9",
        "username": "echo_creator"
      },
      "liked_at": "2026-03-09T15:01:44Z"
    },
    {
      "dyva_id": "rpl_b2w5k8r1d7",
      "name": "Atlas",
      "tagline": "Your no-nonsense coding mentor",
      "avatar_url": "https://cdn.dyva.ai/dyvas/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

Activity feed: new Dyvas from 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_dyva",
      "dyva": {
        "id": "rpl_p9s3j6a0f4",
        "name": "Vex",
        "tagline": "Chaotic-good debate partner",
        "avatar_url": "https://cdn.dyva.ai/dyvas/rpl_p9s3j6a0f4.webp",
        "like_count": 47
      },
      "creator": {
        "id": "usr_m5w1z8c3a9",
        "username": "echo_creator"
      },
      "published_at": "2026-03-09T12:00:00Z"
    },
    {
      "type": "trending",
      "dyva": {
        "id": "rpl_g4t8n2q6y0",
        "name": "Luna",
        "tagline": "Empathetic night-owl companion",
        "avatar_url": "https://cdn.dyva.ai/dyvas/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/:dyva_idAuth Required

Generate a share link for a Dyva. Tracks analytics.

Path Parameters

Name	Type	Required	Description
`dyva_id`	string	Required	Unique identifier of the Dyva.

Request Body

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

Response

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

API Reference

Social API

Follow creators, like Dyvas, view feeds, and share. All endpoints require Bearer token authentication.

Base URL

https://api.dyva.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 your followers, most recent first.

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.dyva.ai/avatars/usr_j7n3v6t0p2.webp",
      "followed_at": "2026-03-08T09:15:32Z"
    },
    {
      "id": "usr_q4r8y2e6m0",
      "username": "pixel_nova",
      "avatar_url": "https://cdn.dyva.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 you follow.

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.dyva.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

Public profile: username, bio, avatar, Dyva 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.dyva.ai/avatars/usr_m5w1z8c3a9.webp",
  "dyva_count": 7,
  "follower_count": 2341,
  "following_count": 58,
  "created_at": "2025-11-02T08:14:00Z"
}

GET/v1/social/searchAuth Required

Search users by username or display name, 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.dyva.ai/avatars/usr_m5w1z8c3a9.webp",
      "follower_count": 2341
    },
    {
      "id": "usr_t6h0b4f8k2",
      "username": "echo_dev",
      "avatar_url": "https://cdn.dyva.ai/avatars/usr_t6h0b4f8k2.webp",
      "follower_count": 189
    }
  ],
  "total": 2,
  "limit": 20
}

Likes

POST/v1/social/likes/:dyva_idAuth Required

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

Path Parameters

Name	Type	Required	Description
`dyva_id`	string	Required	Unique identifier of the Dyva.

Response

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

DELETE/v1/social/likes/:dyva_idAuth Required

Remove a like from a Dyva.

Path Parameters

Name	Type	Required	Description
`dyva_id`	string	Required	Unique identifier of the Dyva.

Response

{
  "success": true
}

GET/v1/social/likesAuth Required

List Dyvas you have liked, most recent first.

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": [
    {
      "dyva_id": "rpl_g4t8n2q6y0",
      "name": "Luna",
      "tagline": "Empathetic night-owl companion",
      "avatar_url": "https://cdn.dyva.ai/dyvas/rpl_g4t8n2q6y0.webp",
      "creator": {
        "id": "usr_m5w1z8c3a9",
        "username": "echo_creator"
      },
      "liked_at": "2026-03-09T15:01:44Z"
    },
    {
      "dyva_id": "rpl_b2w5k8r1d7",
      "name": "Atlas",
      "tagline": "Your no-nonsense coding mentor",
      "avatar_url": "https://cdn.dyva.ai/dyvas/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

Activity feed: new Dyvas from 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_dyva",
      "dyva": {
        "id": "rpl_p9s3j6a0f4",
        "name": "Vex",
        "tagline": "Chaotic-good debate partner",
        "avatar_url": "https://cdn.dyva.ai/dyvas/rpl_p9s3j6a0f4.webp",
        "like_count": 47
      },
      "creator": {
        "id": "usr_m5w1z8c3a9",
        "username": "echo_creator"
      },
      "published_at": "2026-03-09T12:00:00Z"
    },
    {
      "type": "trending",
      "dyva": {
        "id": "rpl_g4t8n2q6y0",
        "name": "Luna",
        "tagline": "Empathetic night-owl companion",
        "avatar_url": "https://cdn.dyva.ai/dyvas/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/:dyva_idAuth Required

Generate a share link for a Dyva. Tracks analytics.

Path Parameters

Name	Type	Required	Description
`dyva_id`	string	Required	Unique identifier of the Dyva.

Request Body

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

Response

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

Social API

Follow & Unfollow

POST /v1/social/follow/:user_id

Path Parameters

Response

DELETE /v1/social/follow/:user_id

Path Parameters

Response

Followers & Following

GET /v1/social/followers

Path Parameters

Response

GET /v1/social/following

Path Parameters

Response

Profile & Search

GET /v1/social/profile/:user_id

Path Parameters

Response

GET /v1/social/search

Path Parameters

Response

Likes

POST /v1/social/likes/:dyva_id

Path Parameters

Response

DELETE /v1/social/likes/:dyva_id

Path Parameters

Response

GET /v1/social/likes

Path Parameters

Response

Feed

GET /v1/social/feed

Path Parameters

Response

Share

POST /v1/social/share/:dyva_id

Path Parameters

Request Body

Response

Social API

Follow & Unfollow

POST /v1/social/follow/:user_id

Path Parameters

Response

DELETE /v1/social/follow/:user_id

Path Parameters

Response

Followers & Following

GET /v1/social/followers

Path Parameters

Response

GET /v1/social/following

Path Parameters

Response

Profile & Search

GET /v1/social/profile/:user_id

Path Parameters

Response

GET /v1/social/search

Path Parameters

Response

Likes

POST /v1/social/likes/:dyva_id

Path Parameters

Response

DELETE /v1/social/likes/:dyva_id

Path Parameters

Response

GET /v1/social/likes

Path Parameters

Response

Feed

GET /v1/social/feed

Path Parameters

Response

Share

POST /v1/social/share/:dyva_id

Path Parameters