Skip to content
Liforma Docs

Experience Catalog

Overview

Use the catalog API when your app should automatically reflect experiences created and ordered in Studio. Fetch the catalog server-side with your API key, render <ExperienceThumbnail> from galleryThumb, link by slug, and mint sessions with the returned experienceId.

GET /v1/projects/{projectId}/experiences

Returns published experiences in creator-defined order.

GET https://api.liforma.ai/v1/projects/proj_01ABC/experiences
Authorization: Bearer YOUR_API_KEY

Response 200

{
"experiences": [
  {
    "experienceId": "exp_01k3q9m5",
    "slug": "spanish-tutor",
    "title": "Spanish Tutor Sofia",
    "sortOrder": 10,
    "updatedAt": "2026-07-26T12:00:00.000Z",
    "catalogReady": true,
    "avatarId": "05a87620",
    "thumbnailPath": "/avatars/05a87620/256/05a87620_neutral.webp",
    "galleryThumb": {
      "avatarImage": "/avatars/05a87620/256/05a87620_neutral.webp",
      "backgroundImage": "/locations/modern/city/office/interior-desk-daytime"
    },
    "discoveryTags": []
  }
]
}

discoveryTags is an empty compatibility field (Release A). Public categorization uses catalogue taxonomy on gallery payloads (useCases, purpose, interaction mode, domain, universe, era) — not discovery tags.

GET /v1/projects/{projectId}/experiences/{slug}

Lookup one published experience by project-scoped slug.

GET https://api.liforma.ai/v1/projects/proj_01ABC/experiences/spanish-tutor
Authorization: Bearer YOUR_API_KEY

Rules

  • Only status: published experiences are returned.

  • catalogReady: false means the experience is published but missing gallery fields in Studio; routing metadata is still returned.

  • slug is unique within a project, not globally.
  • Session mint endpoints still require experienceId.

  • Prefer galleryThumb for UI cards. Pass it to <ExperienceThumbnail> as-is — image values are Liforma paths (/avatars/…, /locations/…/scene), not full CDN URLs. The component expands them to the correct plate size for the card box.

  • Never expose your API key to the browser.