Twins

🤖 AI Twins API

Access public AI twin data including metadata, social profiles, and statistics.

Use Cases:

• Search twins by name, collection, or attributes

• Get detailed twin information

• Filter by collection tier (Gold, Silver, Bronze)

• Sort by rating, creation date, or name

List public twins

get

Retrieve a paginated list of public AI twins with optional filtering and sorting.

Example Use Cases:

• Get all Gold tier twins: ?collection=gold

• Search by name: ?search=Kurohane

• Top rated twins: ?sort=rating&order=DESC

Query parameters

searchstringOptional

Full-text search across name, description, collection, languages, and social profiles

Example: Kurohane

collectionstring · enumOptional

Filter by collection tier

Example: goldPossible values:

sortstring · enumOptional

Sort field

Example: ratingPossible values:

orderstring · enumOptional

Sort order (ascending or descending)

Example: DESCPossible values:

limitinteger · min: 1 · max: 50Optional

Maximum number of results per page (max 50)

Example: 10

offsetintegerOptional

Number of results to skip for pagination

Example: 0

Responses

200

OK

application/json

404

Not Found

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

get

/twins

cURLJavaScript (Fetch)Python

curl -X GET "https://api.twnlabs.com/v1/twins?collection=gold&limit=10" \
  -H "Accept: application/json"

{
  "success": true,
  "twins": [
    {
      "twin_id": "TWN-G0",
      "short_id": "G0",
      "twin_name": "Kurohane",
      "twin_description": "AI digital twin focused on creative content and digital art",
      "collection_type": "gold",
      "is_minted": true,
      "mint_date": "2025-01-15T10:30:00Z",
      "rating": 4.8,
      "like_count": 245,
      "interaction_count": 1520,
      "share_count": 89,
      "languages": [
        "English",
        "Japanese"
      ],
      "twitter": "@kurohane_ai",
      "avatar_url": "https://twnlabs.com/assets/twins/TWN-G0/avatar.png",
      "created_at": "2025-01-10T08:00:00Z"
    }
  ],
  "total": 45,
  "limit": 10,
  "offset": 0,
  "hasMore": true
}

Get twin details

get

Retrieve detailed information about a specific AI twin by its short ID.

Supported ID Formats:

• Short form: G0, S1, B12

• Full form: TWN-G0, TWN-S1, TWN-B12

Path parameters

short_idstringRequired

Short twin ID (e.g., G0, S1, B12). Full form (e.g., TWN-G0) is also accepted.

Example: G0

Responses

200

OK

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

get

/twins/{short_id}

cURLfetch

curl -s "https://api.twnlabs.com/v1/twins/G0"

{
  "success": true,
  "twin": {
    "twin_id": "text",
    "short_id": "text",
    "twin_name": "text",
    "twin_description": "text",
    "twin_birthdate": "text",
    "twin_nationality": "text",
    "languages": [
      "text"
    ],
    "collection_type": "gold",
    "is_minted": true,
    "mint_date": "text",
    "avatar_url": "https://example.com",
    "image_url": "https://example.com",
    "contract_address": "text",
    "creator_address": "text",
    "tx_hash": "text",
    "metadata_uri": "text",
    "twitter": "text",
    "instagram": "text",
    "discord": "text",
    "twitch": "text",
    "like_count": 1,
    "interaction_count": 1,
    "rating": 1,
    "rating_count": 1,
    "status": "text",
    "created_at": "text",
    "updated_at": "text"
  }
}

Get twin analytics

get

Retrieve public analytics for a specific twin (views, likes, interactions, shares, rating). Returns data for public twins, or for the owner when authenticated.

Path parameters

short_idstringRequired

Short twin ID (e.g., G0). Full form (e.g., TWN-G0) is also accepted.

Example: G0

Responses

200

OK

application/json

404

Not Found

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

get

/twins/{short_id}/analytics

HTTPcURLJavaScriptPython

GET /v1/twins/{short_id}/analytics HTTP/1.1
Host: api.twnlabs.com
Accept: */*

{
  "success": true,
  "analytics": {
    "view_count": 1520,
    "like_count": 245,
    "interaction_count": 1520,
    "share_count": 89,
    "rating": 4.8,
    "rating_count": 37,
    "rating_pending": false,
    "daily_avg_views": 24.67,
    "engagement_rate": 115.13
  }
}