Use themes and folders

How to use the themes and folders endpoints to fetch the IDs you need for generation requests.

Use these endpoints when you need to look up IDs for a generation request.

Quick reference

• Call GET /v1.0/themes to get a themeId.

• Call GET /v1.0/folders to get values for folderIds.

• Both endpoints use cursor-based pagination with query, limit, after, hasMore, and nextCursor.

• Theme objects include type (standard or custom), colorKeywords, and toneKeywords.

This page focuses on how to use theme and folder IDs in your workflow. For the exact parameter and response schema, see the GET /themes and GET /folders endpoint reference pages.

List themes

Returns a paginated list of themes in your workspace, including both workspace-specific and global themes.

Request

curl -X GET https://public-api.gamma.app/v1.0/themes \
-H "X-API-KEY: sk-gamma-xxxxxxxx"

Response fields -- each theme object in the data array contains:

Sample response

{
  "id": "abcdefghi",
  "name": "Prism",
  "type": "custom",
  "colorKeywords": ["light","blue","pink","purple","pastel","gradient","vibrant"],
  "toneKeywords": ["playful","friendly","creative","inspirational","fun"]
}

The type field distinguishes between standard (global themes available to all workspaces) and custom (workspace-specific themes).

List folders

Returns a paginated list of folders in your workspace.

Request

curl -X GET https://public-api.gamma.app/v1.0/folders \
-H "X-API-KEY: sk-gamma-xxxxxxxx"

Response fields -- each folder object in the data array contains:

Sample response

{
  "id": "abc123def456",
  "name": "Business Proposals"
}

Pagination

Both endpoints use the same cursor-based pagination. The example below uses folders, but the pattern is identical for themes.

First page:

Request

GET /v1.0/folders?limit=50

Response

{
  "data": [
    { "id": "abcdef", "name": "Design" },
    { "id": "xyzabc", "name": "Marketing" }
  ],
  "hasMore": true,
  "nextCursor": "abc123def456ghi789"
}

Next page -- pass the previous nextCursor as after. When hasMore is false and nextCursor is null, you've reached the end.

Request

GET /v1.0/folders?limit=50&after=abc123def456ghi789

Response

{
  "data": [
    { "id": "lmnop1", "name": "Sales" },
    { "id": "qrstuv", "name": "Product" }
  ],
  "hasMore": false,
  "nextCursor": null
}

Searching by name

Use the query parameter to filter results by name. Works on both themes and folders.

Request

GET /v1.0/themes?query=dark&limit=50

Response

{
  "data": [
    {
      "id": "abc123def456",
      "name": "Standard Dark",
      "type": "standard",
      "colorKeywords": ["black", "gray", "accent"],
      "toneKeywords": ["sophisticated", "modern"]
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

The returned id can be used as themeId in the Generate and Create from Template APIs.

Related

• Generate from text for where themeId and folderIds fit in the request

• Generate from template for using theme and folder IDs with templates

• GET /themes for the full API reference

• GET /folders for the full API reference