me.linkna.linkinbio

linkna.me

Documentation

A user's link-in-bio page containing cards, theme configuration, and social icons.

main record

A user's link-in-bio page containing cards, theme configuration, and social icons.

Record Key literal:self Fixed literal value

Properties

socialIcons array of ref #socialIcon Optional

Social media icons displayed on the profile.

theme string Optional

Deprecated: use themeConfig instead.

themeConfig ref #themeConfig Optional

No description available.

View raw schema 
{
  "description": "A user's link-in-bio page containing cards, theme configuration, and social icons.",
  "key": "literal:self",
  "record": {
    "properties": {
      "cards": {
        "description": "Ordered list of cards on the page.",
        "items": {
          "refs": [
            "#linkCard",
            "#headerCard",
            "#widgetGoodreads",
            "#widgetGithub",
            "#widgetTealfm",
            "#widgetLastfm",
            "#widgetClock",
            "#widgetYoutube",
            "#widgetPatreon",
            "#widgetSubstack",
            "#widgetBeehiiv",
            "#widgetVideo",
            "#widgetTwitch",
            "#widgetDiscord",
            "#widgetReddit",
            "#widgetMedium",
            "#widgetMap"
          ],
          "type": "union"
        },
        "type": "array"
      },
      "connectedServices": {
        "ref": "#connectedServices",
        "type": "ref"
      },
      "socialIcons": {
        "description": "Social media icons displayed on the profile.",
        "items": {
          "ref": "#socialIcon",
          "type": "ref"
        },
        "type": "array"
      },
      "theme": {
        "description": "Deprecated: use themeConfig instead.",
        "type": "string"
      },
      "themeConfig": {
        "ref": "#themeConfig",
        "type": "ref"
      }
    },
    "required": [
      "cards"
    ],
    "type": "object"
  },
  "type": "record"
}
connectedServices object

Saved service credentials/identifiers for pre-filling widget forms.

Properties

githubUsername string Optional

GitHub username.

goodreadsUserId string Optional

Goodreads numeric user ID.

lastfmUsername string Optional

Last.fm username.

View raw schema 
{
  "description": "Saved service credentials/identifiers for pre-filling widget forms.",
  "properties": {
    "githubUsername": {
      "description": "GitHub username.",
      "type": "string"
    },
    "goodreadsUserId": {
      "description": "Goodreads numeric user ID.",
      "type": "string"
    },
    "lastfmUsername": {
      "description": "Last.fm username.",
      "type": "string"
    }
  },
  "type": "object"
}
githubContributionDay object

A single day's contribution data from GitHub.

Properties

count integer Required

Number of contributions on this day.

date string Required

Date in YYYY-MM-DD format.

level integer Required

Contribution intensity level (0=none, 4=highest).

minimum: 0maximum: 4
View raw schema 
{
  "description": "A single day's contribution data from GitHub.",
  "properties": {
    "count": {
      "description": "Number of contributions on this day.",
      "type": "integer"
    },
    "date": {
      "description": "Date in YYYY-MM-DD format.",
      "type": "string"
    },
    "level": {
      "description": "Contribution intensity level (0=none, 4=highest).",
      "maximum": 4,
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "date",
    "count",
    "level"
  ],
  "type": "object"
}
goodreadsBook object

A book from a Goodreads shelf.

Properties

author string Required

Book author.

coverUrl string Optional

URL to the book cover image.

rating integer Optional

User's rating (1-5), or absent if unrated.

minimum: 0maximum: 5
title string Required

Book title.

View raw schema 
{
  "description": "A book from a Goodreads shelf.",
  "properties": {
    "author": {
      "description": "Book author.",
      "type": "string"
    },
    "coverUrl": {
      "description": "URL to the book cover image.",
      "type": "string"
    },
    "link": {
      "description": "URL to the book on Goodreads.",
      "type": "string"
    },
    "rating": {
      "description": "User's rating (1-5), or absent if unrated.",
      "maximum": 5,
      "minimum": 0,
      "type": "integer"
    },
    "title": {
      "description": "Book title.",
      "type": "string"
    }
  },
  "required": [
    "title",
    "author"
  ],
  "type": "object"
}
headerCard object

A section header/divider card.

Properties

alignment string Optional

Text alignment for the header. Defaults to the user's button alignment.

enabled boolean Optional

Whether the header is visible on the public page. Defaults to true.

id string Required

Unique identifier for the card.

text string Required

Header text displayed as a section divider.

maxLength: 100 bytes
type string Required

Card type discriminator.

View raw schema 
{
  "description": "A section header/divider card.",
  "properties": {
    "alignment": {
      "description": "Text alignment for the header. Defaults to the user's button alignment.",
      "enum": [
        "left",
        "center",
        "right"
      ],
      "type": "string"
    },
    "enabled": {
      "description": "Whether the header is visible on the public page. Defaults to true.",
      "type": "boolean"
    },
    "id": {
      "description": "Unique identifier for the card.",
      "type": "string"
    },
    "text": {
      "description": "Header text displayed as a section divider.",
      "maxLength": 100,
      "type": "string"
    },
    "type": {
      "const": "header",
      "description": "Card type discriminator.",
      "type": "string"
    }
  },
  "required": [
    "id",
    "type",
    "text"
  ],
  "type": "object"
}
linkCard object

A standard link card.

Properties

enabled boolean Optional

Whether the card is visible on the public page. Defaults to true.

highlighted boolean Optional

Whether the card is visually highlighted.

id string Optional

Unique identifier for the card.

text string Optional

Display text for the card (falls back to URL domain if empty).

maxLength: 100 bytes
type string Optional

Card type discriminator. Value: 'link' or absent for link cards.

url string uri Optional

URL the card links to.

View raw schema 
{
  "description": "A standard link card.",
  "properties": {
    "enabled": {
      "description": "Whether the card is visible on the public page. Defaults to true.",
      "type": "boolean"
    },
    "highlighted": {
      "description": "Whether the card is visually highlighted.",
      "type": "boolean"
    },
    "id": {
      "description": "Unique identifier for the card.",
      "type": "string"
    },
    "text": {
      "description": "Display text for the card (falls back to URL domain if empty).",
      "maxLength": 100,
      "type": "string"
    },
    "type": {
      "description": "Card type discriminator. Value: 'link' or absent for link cards.",
      "type": "string"
    },
    "url": {
      "description": "URL the card links to.",
      "format": "uri",
      "type": "string"
    }
  },
  "type": "object"
}
mediumArticle object

A Medium article.

Properties

claps integer Required

Number of claps.

publishedAt string Required

When the article was published.

readingTime integer Optional

Estimated reading time in minutes.

subtitle string Optional

Article subtitle.

title string Required

Article title.

url string Required

Article URL.

View raw schema 
{
  "description": "A Medium article.",
  "properties": {
    "claps": {
      "description": "Number of claps.",
      "type": "integer"
    },
    "publishedAt": {
      "description": "When the article was published.",
      "type": "string"
    },
    "readingTime": {
      "description": "Estimated reading time in minutes.",
      "type": "integer"
    },
    "subtitle": {
      "description": "Article subtitle.",
      "type": "string"
    },
    "title": {
      "description": "Article title.",
      "type": "string"
    },
    "url": {
      "description": "Article URL.",
      "type": "string"
    }
  },
  "required": [
    "title",
    "url",
    "publishedAt",
    "claps"
  ],
  "type": "object"
}
redditPost object

A Reddit post.

Properties

numComments integer Required

Number of comments.

score integer Required

Post score.

subreddit string Required

Subreddit name.

title string Required

Post title.

url string Required

Post URL.

View raw schema 
{
  "description": "A Reddit post.",
  "properties": {
    "numComments": {
      "description": "Number of comments.",
      "type": "integer"
    },
    "score": {
      "description": "Post score.",
      "type": "integer"
    },
    "subreddit": {
      "description": "Subreddit name.",
      "type": "string"
    },
    "title": {
      "description": "Post title.",
      "type": "string"
    },
    "url": {
      "description": "Post URL.",
      "type": "string"
    }
  },
  "required": [
    "title",
    "subreddit",
    "url",
    "score",
    "numComments"
  ],
  "type": "object"
}
socialIcon object

A social media icon link.

Properties

id string Required

Unique identifier for the icon.

platform string Required

Platform identifier (e.g., 'bluesky', 'twitter', 'instagram').

url string uri Required

URL to the user's profile on this platform.

View raw schema 
{
  "description": "A social media icon link.",
  "properties": {
    "id": {
      "description": "Unique identifier for the icon.",
      "type": "string"
    },
    "platform": {
      "description": "Platform identifier (e.g., 'bluesky', 'twitter', 'instagram').",
      "type": "string"
    },
    "url": {
      "description": "URL to the user's profile on this platform.",
      "format": "uri",
      "type": "string"
    }
  },
  "required": [
    "id",
    "platform",
    "url"
  ],
  "type": "object"
}
tealfmPlay object

A recently played track from teal.fm.

Properties

artistName string Required

Artist name(s).

coverUrl string Optional

URL to the album cover image (from Cover Art Archive).

originUrl string Optional

URL to the track on the original music service.

playedTime string datetime Optional

When the track was played.

releaseName string Optional

Album/release name.

trackName string Required

Track/song name.

View raw schema 
{
  "description": "A recently played track from teal.fm.",
  "properties": {
    "artistName": {
      "description": "Artist name(s).",
      "type": "string"
    },
    "coverUrl": {
      "description": "URL to the album cover image (from Cover Art Archive).",
      "type": "string"
    },
    "originUrl": {
      "description": "URL to the track on the original music service.",
      "type": "string"
    },
    "playedTime": {
      "description": "When the track was played.",
      "format": "datetime",
      "type": "string"
    },
    "releaseName": {
      "description": "Album/release name.",
      "type": "string"
    },
    "trackName": {
      "description": "Track/song name.",
      "type": "string"
    }
  },
  "required": [
    "trackName",
    "artistName"
  ],
  "type": "object"
}
themeConfig object

Theme configuration for the page appearance.

Properties

backgroundColor string Optional

Page background color.

backgroundGradient string Optional

CSS gradient for the page background.

backgroundImage blob Optional

Background wallpaper image blob.

maxSize: 10.0 MB
backgroundImageCredit string uri Optional

Optional credit URL for the wallpaper image artist. Stored for attribution purposes only, not displayed on the public page.

buttonAlignment string Optional

Button content alignment. Default: left.

Known values: left, right
buttonHoverGlow boolean Optional

Whether buttons glow on hover. Default: false.

buttonHoverGlowColor string Optional

Color for the button hover glow effect.

cardBackgroundColor string Optional

Individual card/button background color.

cardBorderColor string Optional

Card/button border color.

cardBorderRadius string Optional

Card/button border radius.

Known values: none, sm, md, lg, full
cardHoverColor string Optional

Card/button border color on hover.

cardShadow string Optional

Card/button shadow intensity.

Known values: none, sm, md, lg, xl
cardTextColor string Optional

Card/button text color.

contentCardColor string Optional

Card container background color.

cursorSparkles boolean Optional

Whether cursor has sparkle trail. Default: false.

cursorStyle string Optional

Custom cursor style. Default: default.

Known values: default, hello-kitty
fontFamily string Optional

Font family for the page.

fontSize string Optional

Font size. Default: md.

Known values: sm, md, lg
particles string Optional

Background particle effect. Default: none.

Known values: none, white, blue, leaves, grid-sm, grid-lg
preset string Optional

Theme preset ID (e.g., 'custom', 'agate', 'air', 'astrid', 'aura').

profileAlignment string Optional

Profile section alignment. Default: center.

Known values: left, center, right
profilePictureShape string Optional

Profile picture shape. Default: circle.

Known values: circle, rounded, square
profilePictureSize string Optional

Profile picture size. Default: sm.

Known values: sm, md, lg
profileTextColor string Optional

Profile section text color.

showBranding boolean Optional

Whether Linkname branding is visible. Default: true.

socialIconsBorderColor string Optional

Border color for social icons dock/sphere.

socialIconsColor string Optional

Social icons color.

socialIconsShape string Optional

Social icons container shape. Default: dock.

Known values: dock, sphere
socialIconsShapeColor string Optional

Background color for social icons dock/sphere.

View raw schema 
{
  "description": "Theme configuration for the page appearance.",
  "properties": {
    "backgroundColor": {
      "description": "Page background color.",
      "type": "string"
    },
    "backgroundGradient": {
      "description": "CSS gradient for the page background.",
      "type": "string"
    },
    "backgroundImage": {
      "accept": [
        "image/png",
        "image/jpeg",
        "image/webp"
      ],
      "description": "Background wallpaper image blob.",
      "maxSize": 10000000,
      "type": "blob"
    },
    "backgroundImageCredit": {
      "description": "Optional credit URL for the wallpaper image artist. Stored for attribution purposes only, not displayed on the public page.",
      "format": "uri",
      "type": "string"
    },
    "buttonAlignment": {
      "description": "Button content alignment. Default: left.",
      "knownValues": [
        "left",
        "right"
      ],
      "type": "string"
    },
    "buttonHoverGlow": {
      "description": "Whether buttons glow on hover. Default: false.",
      "type": "boolean"
    },
    "buttonHoverGlowColor": {
      "description": "Color for the button hover glow effect.",
      "type": "string"
    },
    "cardBackgroundColor": {
      "description": "Individual card/button background color.",
      "type": "string"
    },
    "cardBorderColor": {
      "description": "Card/button border color.",
      "type": "string"
    },
    "cardBorderRadius": {
      "description": "Card/button border radius.",
      "knownValues": [
        "none",
        "sm",
        "md",
        "lg",
        "full"
      ],
      "type": "string"
    },
    "cardHoverColor": {
      "description": "Card/button border color on hover.",
      "type": "string"
    },
    "cardShadow": {
      "description": "Card/button shadow intensity.",
      "knownValues": [
        "none",
        "sm",
        "md",
        "lg",
        "xl"
      ],
      "type": "string"
    },
    "cardTextColor": {
      "description": "Card/button text color.",
      "type": "string"
    },
    "contentCardColor": {
      "description": "Card container background color.",
      "type": "string"
    },
    "cursorSparkles": {
      "description": "Whether cursor has sparkle trail. Default: false.",
      "type": "boolean"
    },
    "cursorStyle": {
      "description": "Custom cursor style. Default: default.",
      "knownValues": [
        "default",
        "hello-kitty"
      ],
      "type": "string"
    },
    "fontFamily": {
      "description": "Font family for the page.",
      "type": "string"
    },
    "fontSize": {
      "description": "Font size. Default: md.",
      "knownValues": [
        "sm",
        "md",
        "lg"
      ],
      "type": "string"
    },
    "particles": {
      "description": "Background particle effect. Default: none.",
      "knownValues": [
        "none",
        "white",
        "blue",
        "leaves",
        "grid-sm",
        "grid-lg"
      ],
      "type": "string"
    },
    "preset": {
      "description": "Theme preset ID (e.g., 'custom', 'agate', 'air', 'astrid', 'aura').",
      "type": "string"
    },
    "profileAlignment": {
      "description": "Profile section alignment. Default: center.",
      "knownValues": [
        "left",
        "center",
        "right"
      ],
      "type": "string"
    },
    "profilePictureShape": {
      "description": "Profile picture shape. Default: circle.",
      "knownValues": [
        "circle",
        "rounded",
        "square"
      ],
      "type": "string"
    },
    "profilePictureSize": {
      "description": "Profile picture size. Default: sm.",
      "knownValues": [
        "sm",
        "md",
        "lg"
      ],
      "type": "string"
    },
    "profileTextColor": {
      "description": "Profile section text color.",
      "type": "string"
    },
    "showBranding": {
      "description": "Whether Linkname branding is visible. Default: true.",
      "type": "boolean"
    },
    "socialIconsBorderColor": {
      "description": "Border color for social icons dock/sphere.",
      "type": "string"
    },
    "socialIconsColor": {
      "description": "Social icons color.",
      "type": "string"
    },
    "socialIconsShape": {
      "description": "Social icons container shape. Default: dock.",
      "knownValues": [
        "dock",
        "sphere"
      ],
      "type": "string"
    },
    "socialIconsShapeColor": {
      "description": "Background color for social icons dock/sphere.",
      "type": "string"
    }
  },
  "type": "object"
}
videoAspectRatio object

Video aspect ratio dimensions.

Properties

height integer Required

Video height.

width integer Required

Video width.

View raw schema 
{
  "description": "Video aspect ratio dimensions.",
  "properties": {
    "height": {
      "description": "Video height.",
      "type": "integer"
    },
    "width": {
      "description": "Video width.",
      "type": "integer"
    }
  },
  "required": [
    "width",
    "height"
  ],
  "type": "object"
}
widgetBeehiiv object

A Beehiiv publication widget card.

Properties

description string Optional

Publication description.

enabled boolean Optional

Whether the widget is visible on the public page. Defaults to true.

id string Required

Unique identifier for the card.

imageUrl string Optional

Publication image URL.

lastSyncedAt string datetime Optional

When the publication data was last fetched.

publicationId string Required

Beehiiv publication ID.

publicationName string Required

Beehiiv publication name.

publicationUrl string Required

URL to the Beehiiv publication.

size string Optional

Widget display size. Default: 1x1.

Known values: 1x1, 1x2, 2x2, 2x1
type string Required

Card type discriminator.

View raw schema 
{
  "description": "A Beehiiv publication widget card.",
  "properties": {
    "description": {
      "description": "Publication description.",
      "type": "string"
    },
    "enabled": {
      "description": "Whether the widget is visible on the public page. Defaults to true.",
      "type": "boolean"
    },
    "id": {
      "description": "Unique identifier for the card.",
      "type": "string"
    },
    "imageUrl": {
      "description": "Publication image URL.",
      "type": "string"
    },
    "lastSyncedAt": {
      "description": "When the publication data was last fetched.",
      "format": "datetime",
      "type": "string"
    },
    "publicationId": {
      "description": "Beehiiv publication ID.",
      "type": "string"
    },
    "publicationName": {
      "description": "Beehiiv publication name.",
      "type": "string"
    },
    "publicationUrl": {
      "description": "URL to the Beehiiv publication.",
      "type": "string"
    },
    "size": {
      "description": "Widget display size. Default: 1x1.",
      "knownValues": [
        "1x1",
        "1x2",
        "2x2",
        "2x1"
      ],
      "type": "string"
    },
    "type": {
      "const": "beehiiv",
      "description": "Card type discriminator.",
      "type": "string"
    }
  },
  "required": [
    "id",
    "type",
    "publicationId",
    "publicationName",
    "publicationUrl"
  ],
  "type": "object"
}
widgetClock object

A clock, countdown, or stopwatch timer widget card.

Properties

enabled boolean Optional

Whether the widget is visible on the public page. Defaults to true.

id string Required

Unique identifier for the card.

label string Optional

Optional display label for the widget.

maxLength: 100 bytes
mode string Required

Widget mode: clock (timezone display), countdown (to a target date), or timer (interactive stopwatch).

Known values: clock, countdown, timer
size string Optional

Widget display size. Default: 1x1.

Known values: 1x1, 1x2, 2x2, 2x1
targetDate string datetime Optional

ISO 8601 target date for countdown mode.

timezone string Optional

IANA timezone identifier for clock mode (e.g. 'America/New_York').

type string Required

Card type discriminator.

View raw schema 
{
  "description": "A clock, countdown, or stopwatch timer widget card.",
  "properties": {
    "enabled": {
      "description": "Whether the widget is visible on the public page. Defaults to true.",
      "type": "boolean"
    },
    "id": {
      "description": "Unique identifier for the card.",
      "type": "string"
    },
    "label": {
      "description": "Optional display label for the widget.",
      "maxLength": 100,
      "type": "string"
    },
    "mode": {
      "description": "Widget mode: clock (timezone display), countdown (to a target date), or timer (interactive stopwatch).",
      "knownValues": [
        "clock",
        "countdown",
        "timer"
      ],
      "type": "string"
    },
    "size": {
      "description": "Widget display size. Default: 1x1.",
      "knownValues": [
        "1x1",
        "1x2",
        "2x2",
        "2x1"
      ],
      "type": "string"
    },
    "targetDate": {
      "description": "ISO 8601 target date for countdown mode.",
      "format": "datetime",
      "type": "string"
    },
    "timezone": {
      "description": "IANA timezone identifier for clock mode (e.g. 'America/New_York').",
      "type": "string"
    },
    "type": {
      "const": "clock",
      "description": "Card type discriminator.",
      "type": "string"
    }
  },
  "required": [
    "id",
    "type",
    "mode"
  ],
  "type": "object"
}
widgetDiscord object

A Discord server widget card.

Properties

bannerUrl string Optional

Server banner URL.

description string Optional

Server description.

enabled boolean Optional

Whether the widget is visible on the public page. Defaults to true.

iconUrl string Optional

Server icon URL.

id string Required

Unique identifier for the card.

inviteUrl string Required

Discord invite URL.

lastSyncedAt string datetime Optional

When the server data was last fetched.

memberCount integer Optional

Total member count.

presenceCount integer Optional

Online member count.

serverId string Required

Discord server ID.

serverName string Required

Discord server name.

size string Optional

Widget display size. Default: 1x1.

Known values: 1x1, 1x2, 2x2, 2x1
type string Required

Card type discriminator.

View raw schema 
{
  "description": "A Discord server widget card.",
  "properties": {
    "bannerUrl": {
      "description": "Server banner URL.",
      "type": "string"
    },
    "description": {
      "description": "Server description.",
      "type": "string"
    },
    "enabled": {
      "description": "Whether the widget is visible on the public page. Defaults to true.",
      "type": "boolean"
    },
    "iconUrl": {
      "description": "Server icon URL.",
      "type": "string"
    },
    "id": {
      "description": "Unique identifier for the card.",
      "type": "string"
    },
    "inviteUrl": {
      "description": "Discord invite URL.",
      "type": "string"
    },
    "lastSyncedAt": {
      "description": "When the server data was last fetched.",
      "format": "datetime",
      "type": "string"
    },
    "memberCount": {
      "description": "Total member count.",
      "type": "integer"
    },
    "presenceCount": {
      "description": "Online member count.",
      "type": "integer"
    },
    "serverId": {
      "description": "Discord server ID.",
      "type": "string"
    },
    "serverName": {
      "description": "Discord server name.",
      "type": "string"
    },
    "size": {
      "description": "Widget display size. Default: 1x1.",
      "knownValues": [
        "1x1",
        "1x2",
        "2x2",
        "2x1"
      ],
      "type": "string"
    },
    "type": {
      "const": "discord",
      "description": "Card type discriminator.",
      "type": "string"
    }
  },
  "required": [
    "id",
    "type",
    "serverId",
    "serverName",
    "inviteUrl"
  ],
  "type": "object"
}
widgetGithub object

A GitHub contributions graph widget card.

Properties

enabled boolean Optional

Whether the widget is visible on the public page. Defaults to true.

githubUsername string Required

GitHub username.

id string Required

Unique identifier for the card.

lastSyncedAt string datetime Optional

When the contribution data was last fetched from GitHub.

size string Optional

Widget display size. Default: 1x1.

Known values: 1x1, 1x2, 2x2
totalContributions integer Optional

Total number of contributions in the last year.

type string Required

Card type discriminator.

View raw schema 
{
  "description": "A GitHub contributions graph widget card.",
  "properties": {
    "contributions": {
      "description": "Contribution data for the last year.",
      "items": {
        "ref": "#githubContributionDay",
        "type": "ref"
      },
      "type": "array"
    },
    "enabled": {
      "description": "Whether the widget is visible on the public page. Defaults to true.",
      "type": "boolean"
    },
    "githubUsername": {
      "description": "GitHub username.",
      "type": "string"
    },
    "id": {
      "description": "Unique identifier for the card.",
      "type": "string"
    },
    "lastSyncedAt": {
      "description": "When the contribution data was last fetched from GitHub.",
      "format": "datetime",
      "type": "string"
    },
    "size": {
      "description": "Widget display size. Default: 1x1.",
      "knownValues": [
        "1x1",
        "1x2",
        "2x2"
      ],
      "type": "string"
    },
    "totalContributions": {
      "description": "Total number of contributions in the last year.",
      "type": "integer"
    },
    "type": {
      "const": "github",
      "description": "Card type discriminator.",
      "type": "string"
    }
  },
  "required": [
    "id",
    "type",
    "githubUsername",
    "contributions"
  ],
  "type": "object"
}
widgetGoodreads object

A Goodreads bookshelf widget card.

Properties

books array of ref#goodreadsBook Required

Books on the currently-reading shelf.

enabled boolean Optional

Whether the widget is visible on the public page. Defaults to true.

goodreadsUserId string Required

Goodreads numeric user ID.

id string Required

Unique identifier for the card.

lastSyncedAt string datetime Optional

When the book data was last fetched from Goodreads.

readBooks array of ref#goodreadsBook Optional

Books on the read shelf (used by 1x2 size).

shelf string Required

Shelf name (currently-reading, read, or to-read).

size string Optional

Widget display size. Default: 1x1.

Known values: 1x1, 1x2, 2x2
type string Required

Card type discriminator.

View raw schema 
{
  "description": "A Goodreads bookshelf widget card.",
  "properties": {
    "books": {
      "description": "Books on the currently-reading shelf.",
      "items": {
        "ref": "#goodreadsBook",
        "type": "ref"
      },
      "type": "array"
    },
    "enabled": {
      "description": "Whether the widget is visible on the public page. Defaults to true.",
      "type": "boolean"
    },
    "goodreadsUserId": {
      "description": "Goodreads numeric user ID.",
      "type": "string"
    },
    "id": {
      "description": "Unique identifier for the card.",
      "type": "string"
    },
    "lastSyncedAt": {
      "description": "When the book data was last fetched from Goodreads.",
      "format": "datetime",
      "type": "string"
    },
    "readBooks": {
      "description": "Books on the read shelf (used by 1x2 size).",
      "items": {
        "ref": "#goodreadsBook",
        "type": "ref"
      },
      "type": "array"
    },
    "shelf": {
      "description": "Shelf name (currently-reading, read, or to-read).",
      "type": "string"
    },
    "size": {
      "description": "Widget display size. Default: 1x1.",
      "knownValues": [
        "1x1",
        "1x2",
        "2x2"
      ],
      "type": "string"
    },
    "type": {
      "const": "goodreads",
      "description": "Card type discriminator.",
      "type": "string"
    }
  },
  "required": [
    "id",
    "type",
    "goodreadsUserId",
    "shelf",
    "books"
  ],
  "type": "object"
}
widgetLastfm object

A Last.fm recently played tracks widget card.

Properties

coverArtNotice string Optional

Copyright notice for cover art images.

enabled boolean Optional

Whether the widget is visible on the public page. Defaults to true.

id string Required

Unique identifier for the card.

lastSyncedAt string datetime Optional

When the play data was last fetched from Last.fm.

lastfmUsername string Required

Last.fm username for fetching scrobbles.

plays array of ref#tealfmPlay Required

Recently played tracks from Last.fm.

size string Optional

Widget display size. Default: 1x1.

Known values: 1x1, 1x2, 2x2
type string Required

Card type discriminator.

View raw schema 
{
  "description": "A Last.fm recently played tracks widget card.",
  "properties": {
    "coverArtNotice": {
      "description": "Copyright notice for cover art images.",
      "type": "string"
    },
    "enabled": {
      "description": "Whether the widget is visible on the public page. Defaults to true.",
      "type": "boolean"
    },
    "id": {
      "description": "Unique identifier for the card.",
      "type": "string"
    },
    "lastSyncedAt": {
      "description": "When the play data was last fetched from Last.fm.",
      "format": "datetime",
      "type": "string"
    },
    "lastfmUsername": {
      "description": "Last.fm username for fetching scrobbles.",
      "type": "string"
    },
    "plays": {
      "description": "Recently played tracks from Last.fm.",
      "items": {
        "ref": "#tealfmPlay",
        "type": "ref"
      },
      "type": "array"
    },
    "size": {
      "description": "Widget display size. Default: 1x1.",
      "knownValues": [
        "1x1",
        "1x2",
        "2x2"
      ],
      "type": "string"
    },
    "type": {
      "const": "lastfm",
      "description": "Card type discriminator.",
      "type": "string"
    }
  },
  "required": [
    "id",
    "type",
    "lastfmUsername",
    "plays"
  ],
  "type": "object"
}
widgetMap object

A map location widget card.

Properties

enabled boolean Optional

Whether the widget is visible on the public page. Defaults to true.

id string Required

Unique identifier for the card.

latitude string Required

Latitude coordinate as string (AT Protocol does not support floats).

locationName string Required

Display name for the location.

longitude string Required

Longitude coordinate as string (AT Protocol does not support floats).

mapImageRef blob Optional

Cached static map image blob to avoid repeated Stadia Maps API calls.

maxSize: 5.0 MB
size string Optional

Widget display size. Default: 1x1.

Known values: 1x1, 1x2, 2x2, 2x1
style string Optional

Map style. Default: light.

Known values: light, dark
type string Required

Card type discriminator.

zoom integer Optional

Map zoom level (1-18). Default: 12.

View raw schema 
{
  "description": "A map location widget card.",
  "properties": {
    "enabled": {
      "description": "Whether the widget is visible on the public page. Defaults to true.",
      "type": "boolean"
    },
    "id": {
      "description": "Unique identifier for the card.",
      "type": "string"
    },
    "latitude": {
      "description": "Latitude coordinate as string (AT Protocol does not support floats).",
      "type": "string"
    },
    "locationName": {
      "description": "Display name for the location.",
      "type": "string"
    },
    "longitude": {
      "description": "Longitude coordinate as string (AT Protocol does not support floats).",
      "type": "string"
    },
    "mapImageRef": {
      "accept": [
        "image/png",
        "image/jpeg"
      ],
      "description": "Cached static map image blob to avoid repeated Stadia Maps API calls.",
      "maxSize": 5000000,
      "type": "blob"
    },
    "size": {
      "description": "Widget display size. Default: 1x1.",
      "knownValues": [
        "1x1",
        "1x2",
        "2x2",
        "2x1"
      ],
      "type": "string"
    },
    "style": {
      "description": "Map style. Default: light.",
      "knownValues": [
        "light",
        "dark"
      ],
      "type": "string"
    },
    "type": {
      "const": "map",
      "description": "Card type discriminator.",
      "type": "string"
    },
    "zoom": {
      "description": "Map zoom level (1-18). Default: 12.",
      "type": "integer"
    }
  },
  "required": [
    "id",
    "type",
    "locationName",
    "latitude",
    "longitude"
  ],
  "type": "object"
}
widgetMedium object

A Medium profile widget card.

Properties

bio string Optional

Medium bio.

displayName string Optional

Medium display name.

enabled boolean Optional

Whether the widget is visible on the public page. Defaults to true.

followerCount integer Optional

Number of followers.

id string Required

Unique identifier for the card.

lastSyncedAt string datetime Optional

When the Medium data was last fetched.

profileUrl string Required

Medium profile URL.

size string Optional

Widget display size. Default: 1x1.

Known values: 1x1, 1x2, 2x2, 2x1
type string Required

Card type discriminator.

username string Required

Medium username.

View raw schema 
{
  "description": "A Medium profile widget card.",
  "properties": {
    "articles": {
      "description": "Recent articles.",
      "items": {
        "ref": "#mediumArticle",
        "type": "ref"
      },
      "type": "array"
    },
    "bio": {
      "description": "Medium bio.",
      "type": "string"
    },
    "displayName": {
      "description": "Medium display name.",
      "type": "string"
    },
    "enabled": {
      "description": "Whether the widget is visible on the public page. Defaults to true.",
      "type": "boolean"
    },
    "followerCount": {
      "description": "Number of followers.",
      "type": "integer"
    },
    "id": {
      "description": "Unique identifier for the card.",
      "type": "string"
    },
    "lastSyncedAt": {
      "description": "When the Medium data was last fetched.",
      "format": "datetime",
      "type": "string"
    },
    "profileUrl": {
      "description": "Medium profile URL.",
      "type": "string"
    },
    "size": {
      "description": "Widget display size. Default: 1x1.",
      "knownValues": [
        "1x1",
        "1x2",
        "2x2",
        "2x1"
      ],
      "type": "string"
    },
    "type": {
      "const": "medium",
      "description": "Card type discriminator.",
      "type": "string"
    },
    "username": {
      "description": "Medium username.",
      "type": "string"
    }
  },
  "required": [
    "id",
    "type",
    "username",
    "profileUrl"
  ],
  "type": "object"
}
widgetPatreon object

A Patreon campaign widget card.

Properties

campaignId string Required

Patreon campaign ID.

campaignUrl string Required

URL to the Patreon campaign.

creationName string Optional

Name of the creation/project.

creatorName string Required

Patreon creator name.

enabled boolean Optional

Whether the widget is visible on the public page. Defaults to true.

id string Required

Unique identifier for the card.

imageUrl string Optional

Campaign image URL.

lastSyncedAt string datetime Optional

When the campaign data was last fetched.

patronCount integer Optional

Number of patrons.

postCount integer Optional

Number of posts.

size string Optional

Widget display size. Default: 1x1.

Known values: 1x1, 1x2, 2x2, 2x1
type string Required

Card type discriminator.

View raw schema 
{
  "description": "A Patreon campaign widget card.",
  "properties": {
    "campaignId": {
      "description": "Patreon campaign ID.",
      "type": "string"
    },
    "campaignUrl": {
      "description": "URL to the Patreon campaign.",
      "type": "string"
    },
    "creationName": {
      "description": "Name of the creation/project.",
      "type": "string"
    },
    "creatorName": {
      "description": "Patreon creator name.",
      "type": "string"
    },
    "enabled": {
      "description": "Whether the widget is visible on the public page. Defaults to true.",
      "type": "boolean"
    },
    "id": {
      "description": "Unique identifier for the card.",
      "type": "string"
    },
    "imageUrl": {
      "description": "Campaign image URL.",
      "type": "string"
    },
    "lastSyncedAt": {
      "description": "When the campaign data was last fetched.",
      "format": "datetime",
      "type": "string"
    },
    "patronCount": {
      "description": "Number of patrons.",
      "type": "integer"
    },
    "postCount": {
      "description": "Number of posts.",
      "type": "integer"
    },
    "size": {
      "description": "Widget display size. Default: 1x1.",
      "knownValues": [
        "1x1",
        "1x2",
        "2x2",
        "2x1"
      ],
      "type": "string"
    },
    "type": {
      "const": "patreon",
      "description": "Card type discriminator.",
      "type": "string"
    }
  },
  "required": [
    "id",
    "type",
    "campaignId",
    "creatorName",
    "campaignUrl"
  ],
  "type": "object"
}
widgetReddit object

A Reddit profile widget card.

Properties

avatarUrl string Optional

Reddit avatar URL.

commentKarma integer Optional

Comment karma.

enabled boolean Optional

Whether the widget is visible on the public page. Defaults to true.

id string Required

Unique identifier for the card.

karma integer Optional

Total karma.

lastSyncedAt string datetime Optional

When the Reddit data was last fetched.

linkKarma integer Optional

Link karma.

profileUrl string Required

Reddit profile URL.

recentPosts array of ref#redditPost Optional

Recent posts.

size string Optional

Widget display size. Default: 1x1.

Known values: 1x1, 1x2, 2x2, 2x1
type string Required

Card type discriminator.

username string Required

Reddit username.

View raw schema 
{
  "description": "A Reddit profile widget card.",
  "properties": {
    "avatarUrl": {
      "description": "Reddit avatar URL.",
      "type": "string"
    },
    "commentKarma": {
      "description": "Comment karma.",
      "type": "integer"
    },
    "enabled": {
      "description": "Whether the widget is visible on the public page. Defaults to true.",
      "type": "boolean"
    },
    "id": {
      "description": "Unique identifier for the card.",
      "type": "string"
    },
    "karma": {
      "description": "Total karma.",
      "type": "integer"
    },
    "lastSyncedAt": {
      "description": "When the Reddit data was last fetched.",
      "format": "datetime",
      "type": "string"
    },
    "linkKarma": {
      "description": "Link karma.",
      "type": "integer"
    },
    "profileUrl": {
      "description": "Reddit profile URL.",
      "type": "string"
    },
    "recentPosts": {
      "description": "Recent posts.",
      "items": {
        "ref": "#redditPost",
        "type": "ref"
      },
      "type": "array"
    },
    "size": {
      "description": "Widget display size. Default: 1x1.",
      "knownValues": [
        "1x1",
        "1x2",
        "2x2",
        "2x1"
      ],
      "type": "string"
    },
    "type": {
      "const": "reddit",
      "description": "Card type discriminator.",
      "type": "string"
    },
    "username": {
      "description": "Reddit username.",
      "type": "string"
    }
  },
  "required": [
    "id",
    "type",
    "username",
    "profileUrl"
  ],
  "type": "object"
}
widgetSubstack object

A Substack publication widget card.

Properties

authorName string Optional

Author name.

coverImageUrl string Optional

Publication cover image URL.

description string Optional

Publication description.

enabled boolean Optional

Whether the widget is visible on the public page. Defaults to true.

id string Required

Unique identifier for the card.

imageUrl string Optional

Publication image URL.

lastSyncedAt string datetime Optional

When the publication data was last fetched.

postCount integer Optional

Number of posts.

publicationId string Required

Substack publication ID.

publicationName string Required

Substack publication name.

publicationUrl string Required

URL to the Substack publication.

size string Optional

Widget display size. Default: 1x1.

Known values: 1x1, 1x2, 2x2, 2x1
subscriberCount integer Optional

Number of subscribers.

type string Required

Card type discriminator.

View raw schema 
{
  "description": "A Substack publication widget card.",
  "properties": {
    "authorName": {
      "description": "Author name.",
      "type": "string"
    },
    "coverImageUrl": {
      "description": "Publication cover image URL.",
      "type": "string"
    },
    "description": {
      "description": "Publication description.",
      "type": "string"
    },
    "enabled": {
      "description": "Whether the widget is visible on the public page. Defaults to true.",
      "type": "boolean"
    },
    "id": {
      "description": "Unique identifier for the card.",
      "type": "string"
    },
    "imageUrl": {
      "description": "Publication image URL.",
      "type": "string"
    },
    "lastSyncedAt": {
      "description": "When the publication data was last fetched.",
      "format": "datetime",
      "type": "string"
    },
    "postCount": {
      "description": "Number of posts.",
      "type": "integer"
    },
    "publicationId": {
      "description": "Substack publication ID.",
      "type": "string"
    },
    "publicationName": {
      "description": "Substack publication name.",
      "type": "string"
    },
    "publicationUrl": {
      "description": "URL to the Substack publication.",
      "type": "string"
    },
    "size": {
      "description": "Widget display size. Default: 1x1.",
      "knownValues": [
        "1x1",
        "1x2",
        "2x2",
        "2x1"
      ],
      "type": "string"
    },
    "subscriberCount": {
      "description": "Number of subscribers.",
      "type": "integer"
    },
    "type": {
      "const": "substack",
      "description": "Card type discriminator.",
      "type": "string"
    }
  },
  "required": [
    "id",
    "type",
    "publicationId",
    "publicationName",
    "publicationUrl"
  ],
  "type": "object"
}
widgetTealfm object

A teal.fm recently played tracks widget card.

Properties

coverArtNotice string Optional

Copyright notice for cover art images.

enabled boolean Optional

Whether the widget is visible on the public page. Defaults to true.

id string Required

Unique identifier for the card.

lastSyncedAt string datetime Optional

When the play data was last fetched from the PDS.

plays array of ref#tealfmPlay Required

Recently played tracks.

size string Optional

Widget display size. Default: 1x1.

Known values: 1x1, 1x2, 2x2
source string Optional

Data source for the widget. 'lastfm' for imported Last.fm scrobbles, 'tealfm' (default) for native AT Protocol plays.

Known values: tealfm, lastfm
type string Required

Card type discriminator.

View raw schema 
{
  "description": "A teal.fm recently played tracks widget card.",
  "properties": {
    "coverArtNotice": {
      "description": "Copyright notice for cover art images.",
      "type": "string"
    },
    "enabled": {
      "description": "Whether the widget is visible on the public page. Defaults to true.",
      "type": "boolean"
    },
    "id": {
      "description": "Unique identifier for the card.",
      "type": "string"
    },
    "lastSyncedAt": {
      "description": "When the play data was last fetched from the PDS.",
      "format": "datetime",
      "type": "string"
    },
    "plays": {
      "description": "Recently played tracks.",
      "items": {
        "ref": "#tealfmPlay",
        "type": "ref"
      },
      "type": "array"
    },
    "size": {
      "description": "Widget display size. Default: 1x1.",
      "knownValues": [
        "1x1",
        "1x2",
        "2x2"
      ],
      "type": "string"
    },
    "source": {
      "description": "Data source for the widget. 'lastfm' for imported Last.fm scrobbles, 'tealfm' (default) for native AT Protocol plays.",
      "knownValues": [
        "tealfm",
        "lastfm"
      ],
      "type": "string"
    },
    "type": {
      "const": "tealfm",
      "description": "Card type discriminator.",
      "type": "string"
    }
  },
  "required": [
    "id",
    "type",
    "plays"
  ],
  "type": "object"
}
widgetTwitch object

A Twitch channel widget card.

Properties

displayName string Optional

Twitch display name.

enabled boolean Optional

Whether the widget is visible on the public page. Defaults to true.

id string Required

Unique identifier for the card.

isLive boolean Optional

Whether the channel is currently live.

lastSyncedAt string datetime Optional

When the channel data was last fetched.

profileImageUrl string Optional

Twitch profile image URL.

size string Optional

Widget display size. Default: 1x1.

Known values: 1x1, 1x2, 2x2, 2x1
streamGame string Optional

Current stream game/category.

streamTitle string Optional

Current stream title.

type string Required

Card type discriminator.

username string Required

Twitch username.

viewerCount integer Optional

Current viewer count.

View raw schema 
{
  "description": "A Twitch channel widget card.",
  "properties": {
    "displayName": {
      "description": "Twitch display name.",
      "type": "string"
    },
    "enabled": {
      "description": "Whether the widget is visible on the public page. Defaults to true.",
      "type": "boolean"
    },
    "id": {
      "description": "Unique identifier for the card.",
      "type": "string"
    },
    "isLive": {
      "description": "Whether the channel is currently live.",
      "type": "boolean"
    },
    "lastSyncedAt": {
      "description": "When the channel data was last fetched.",
      "format": "datetime",
      "type": "string"
    },
    "profileImageUrl": {
      "description": "Twitch profile image URL.",
      "type": "string"
    },
    "size": {
      "description": "Widget display size. Default: 1x1.",
      "knownValues": [
        "1x1",
        "1x2",
        "2x2",
        "2x1"
      ],
      "type": "string"
    },
    "streamGame": {
      "description": "Current stream game/category.",
      "type": "string"
    },
    "streamTitle": {
      "description": "Current stream title.",
      "type": "string"
    },
    "type": {
      "const": "twitch",
      "description": "Card type discriminator.",
      "type": "string"
    },
    "username": {
      "description": "Twitch username.",
      "type": "string"
    },
    "viewerCount": {
      "description": "Current viewer count.",
      "type": "integer"
    }
  },
  "required": [
    "id",
    "type",
    "username"
  ],
  "type": "object"
}
widgetVideo object

A video widget card.

Properties

alt string Optional

Alt text for accessibility.

maxLength: 1000 bytes
createdAt string datetime Optional

When the video was uploaded.

did string Required

Author DID for constructing PDS blob URLs.

enabled boolean Optional

Whether the widget is visible on the public page. Defaults to true.

id string Required

Unique identifier for the card.

loop boolean Optional

Whether the video loops. Defaults to true.

muted boolean Optional

Whether the video is muted. Defaults to true.

showOverlay boolean Optional

Whether to show the title overlay. Defaults to false.

size string Optional

Widget display size. Default: 1x1.

Known values: 1x1, 1x2, 2x2, 2x1
title string Optional

Video title overlay.

maxLength: 100 bytes
type string Required

Card type discriminator.

videoBlobRef blob Required

Reference to the uploaded video blob.

View raw schema 
{
  "description": "A video widget card.",
  "properties": {
    "alt": {
      "description": "Alt text for accessibility.",
      "maxLength": 1000,
      "type": "string"
    },
    "aspectRatio": {
      "description": "Video aspect ratio.",
      "ref": "#videoAspectRatio",
      "type": "ref"
    },
    "createdAt": {
      "description": "When the video was uploaded.",
      "format": "datetime",
      "type": "string"
    },
    "did": {
      "description": "Author DID for constructing PDS blob URLs.",
      "type": "string"
    },
    "enabled": {
      "description": "Whether the widget is visible on the public page. Defaults to true.",
      "type": "boolean"
    },
    "id": {
      "description": "Unique identifier for the card.",
      "type": "string"
    },
    "loop": {
      "description": "Whether the video loops. Defaults to true.",
      "type": "boolean"
    },
    "muted": {
      "description": "Whether the video is muted. Defaults to true.",
      "type": "boolean"
    },
    "showOverlay": {
      "description": "Whether to show the title overlay. Defaults to false.",
      "type": "boolean"
    },
    "size": {
      "description": "Widget display size. Default: 1x1.",
      "knownValues": [
        "1x1",
        "1x2",
        "2x2",
        "2x1"
      ],
      "type": "string"
    },
    "title": {
      "description": "Video title overlay.",
      "maxLength": 100,
      "type": "string"
    },
    "type": {
      "const": "video",
      "description": "Card type discriminator.",
      "type": "string"
    },
    "videoBlobRef": {
      "description": "Reference to the uploaded video blob.",
      "type": "blob"
    }
  },
  "required": [
    "id",
    "type",
    "videoBlobRef",
    "did"
  ],
  "type": "object"
}
widgetYoutube object

A YouTube channel widget card.

Properties

channelId string Required

YouTube channel ID.

channelName string Required

YouTube channel name.

channelUrl string Required

URL to the YouTube channel.

enabled boolean Optional

Whether the widget is visible on the public page. Defaults to true.

id string Required

Unique identifier for the card.

lastSyncedAt string datetime Optional

When the video data was last fetched.

latestVideo ref #youtubeVideo Optional

The latest video from the channel.

size string Optional

Widget display size. Default: 1x1.

Known values: 1x1, 1x2, 2x2, 2x1
type string Required

Card type discriminator.

View raw schema 
{
  "description": "A YouTube channel widget card.",
  "properties": {
    "channelId": {
      "description": "YouTube channel ID.",
      "type": "string"
    },
    "channelName": {
      "description": "YouTube channel name.",
      "type": "string"
    },
    "channelUrl": {
      "description": "URL to the YouTube channel.",
      "type": "string"
    },
    "enabled": {
      "description": "Whether the widget is visible on the public page. Defaults to true.",
      "type": "boolean"
    },
    "id": {
      "description": "Unique identifier for the card.",
      "type": "string"
    },
    "lastSyncedAt": {
      "description": "When the video data was last fetched.",
      "format": "datetime",
      "type": "string"
    },
    "latestVideo": {
      "description": "The latest video from the channel.",
      "ref": "#youtubeVideo",
      "type": "ref"
    },
    "size": {
      "description": "Widget display size. Default: 1x1.",
      "knownValues": [
        "1x1",
        "1x2",
        "2x2",
        "2x1"
      ],
      "type": "string"
    },
    "type": {
      "const": "youtube",
      "description": "Card type discriminator.",
      "type": "string"
    }
  },
  "required": [
    "id",
    "type",
    "channelId",
    "channelName",
    "channelUrl"
  ],
  "type": "object"
}
youtubeVideo object

A YouTube video.

Properties

isShort boolean Optional

Whether this is a YouTube Short.

publishedAt string Required

When the video was published.

title string Required

Video title.

videoId string Required

YouTube video ID.

View raw schema 
{
  "description": "A YouTube video.",
  "properties": {
    "isShort": {
      "description": "Whether this is a YouTube Short.",
      "type": "boolean"
    },
    "publishedAt": {
      "description": "When the video was published.",
      "type": "string"
    },
    "title": {
      "description": "Video title.",
      "type": "string"
    },
    "videoId": {
      "description": "YouTube video ID.",
      "type": "string"
    }
  },
  "required": [
    "videoId",
    "title",
    "publishedAt"
  ],
  "type": "object"
}

Lexicon Garden

@