Card Collections API

The Card Collections endpoints allow you to retrieve card collections from your Storyteller tenant. They return basic identifiers and titles. Use the list endpoint to browse or search collections, and the lookup endpoint to fetch or validate one collection by its ID.

Endpoints

Get All Card Collections

GET https://integrations.usestoryteller.com/api/card-collections

Get Card Collection by External ID

GET https://integrations.usestoryteller.com/api/card-collections/{externalId}

Headers

Header	Required	Description
x-storyteller-api-key	Yes	Your API key for authentication

Get All Card Collections

Returns card collections sorted alphabetically by title.

Query Parameters

Parameter	Type	Required	Default	Description
searchText	string	No	-	Filter card collections by title
currentPage	integer	No	1	Page number for pagination. Ignored when skipCount or maxResultCount is supplied.
pageSize	integer	No	10	Number of items per page. Must be between 1 and 1000. Ignored when skipCount or maxResultCount is supplied.
skipCount	integer	No	0	Legacy offset-style pagination alias. Defaults to 0 when omitted while using legacy pagination.
maxResultCount	integer	No	10	Legacy offset-style page-size alias. Defaults to 10 when omitted while using legacy pagination. Maximum 1000.

You can page this endpoint using either currentPage + pageSize or legacy-style skipCount + maxResultCount.

In legacy mode, omitted aliases fall back to skipCount=0 and maxResultCount=10. Because integrations responses still return currentPage, skipCount must land on a page boundary for the effective page size.

Response

Success Response (200 OK)

{
  "cardCollections": [
    {
      "id": "product-tutorials",
      "title": "Product Tutorials",
      "externalId": "product-tutorials",
      "displayTitle": "Product Tutorials",
      "internalTitle": "Product Tutorials"
    },
    {
      "id": "marketing-campaigns",
      "title": "Marketing Campaigns",
      "externalId": "marketing-campaigns",
      "displayTitle": "Marketing Campaigns",
      "internalTitle": "Marketing Campaigns"
    }
  ],
  "pageSize": 10,
  "currentPage": 1,
  "totalPages": 1,
  "totalCount": 1
}

Response Fields

Card Collection Object

Field	Type	Description
id	string	Unique card collection internal identifier
title	string	Display title or internal title if display title is missing
externalId	string	Alias of id for consistency with other endpoints
displayTitle	string	Display name of the card collection
internalTitle	string	Internal name of the card collection

Pagination Object

Field	Type	Description
pageSize	integer	Number of items per page
currentPage	integer	Current page number
totalPages	integer	Total number of pages available
totalCount	integer	Exact total number of matching card collections

Get Card Collection by External ID

Use this endpoint to check that a card collection exists, for example before saving a configuration that references it, without paging through the list.

Path Parameters

Parameter	Type	Required	Description
externalId	string	Yes	The card collection's ID, as returned in id and externalId by the list endpoint. IDs are lowercase and the lookup ignores case, so store the returned id.

Response (200 OK)

Returns a single card collection object with the same fields as the list endpoint (without pagination fields):

{
  "id": "product-tutorials",
  "title": "Product Tutorials",
  "externalId": "product-tutorials",
  "displayTitle": "Product Tutorials",
  "internalTitle": "Product Tutorials"
}

Response (404 Not Found)

Returned when your tenant has no card collection with that ID.

{
  "status": 404,
  "type": "https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.4",
  "title": "Not Found",
  "detail": "Card collection with externalId product-tutorials not found",
  "instance": ""
}

Examples

cURL

# Get card collections
curl -X GET "https://integrations.usestoryteller.com/api/card-collections" \
  -H "x-storyteller-api-key: your-api-key-here"

# Search for specific card collections
curl -X GET "https://integrations.usestoryteller.com/api/card-collections?searchText=product&pageSize=20" \
  -H "x-storyteller-api-key: your-api-key-here"

# Get one card collection by its ID
curl -X GET "https://integrations.usestoryteller.com/api/card-collections/product-tutorials" \
  -H "x-storyteller-api-key: your-api-key-here"

JavaScript

async function getCardCollections(searchText = '', currentPage = 1, pageSize = 10) {
  const params = new URLSearchParams({
    ...(searchText && { searchText }),
    currentPage: currentPage.toString(),
    pageSize: pageSize.toString()
  });

  const response = await fetch(`https://integrations.usestoryteller.com/api/card-collections?${params}`, {
    method: 'GET',
    headers: { 'x-storyteller-api-key': process.env.STORYTELLER_API_KEY }
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return await response.json();
}

const { cardCollections } = await getCardCollections('product', 1, 20);
console.log(cardCollections.map(c => c.id));

// Returns the card collection, or null if the ID does not exist in your tenant
async function getCardCollection(externalId) {
  const response = await fetch(`https://integrations.usestoryteller.com/api/card-collections/${encodeURIComponent(externalId)}`, {
    method: 'GET',
    headers: { 'x-storyteller-api-key': process.env.STORYTELLER_API_KEY }
  });
  if (response.status === 404) return null;
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return await response.json();
}

const collection = await getCardCollection('product-tutorials');
console.log(collection ? `Found ${collection.title}` : 'Card collection not found');