liforma docs

Experience Catalog

List published experiences in a project for creator-managed galleries.

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_01K3Q9M5WJQ2P9X7B4R8S1N6D",
      "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.