> For the complete documentation index, see [llms.txt](https://developers.gamma.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.gamma.app/guides/list-themes-and-list-folders-apis-explained.md).

# 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 a `folderId`.
* Both endpoints use cursor-based pagination with `query`, `limit`, `after`, `hasMore`, and `nextCursor`.
* `GET /v1.0/themes` also accepts `type=standard` or `type=custom` if you only want built-in or workspace themes.
* Theme objects include `type` (`standard` or `custom`), `colorKeywords`, and `toneKeywords`.

{% hint style="info" %}
For request parameters and response fields, see [GET /themes](/workspace/list-themes.md) and [GET /folders](/workspace/list-folders.md).
{% endhint %}

### List themes

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

{% code title="Request" %}

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

{% endcode %}

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

{% code title="Sample response" %}

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

{% endcode %}

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

If you only want one category, pass `type=standard` or `type=custom` on the request. When paginating, keep the same `type` value on every page so the result set stays consistent.

### List folders

Returns a paginated list of folders in your workspace.

{% code title="Request" %}

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

{% endcode %}

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

{% code title="Sample response" %}

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

{% endcode %}

### Pagination

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

**First page:**

{% code title="Request" %}

```
GET /v1.0/folders?limit=50
```

{% endcode %}

{% code title="Response" %}

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

{% endcode %}

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

{% code title="Request" %}

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

{% endcode %}

{% code title="Response" %}

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

{% endcode %}

### Searching by name

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

{% code title="Request" %}

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

{% endcode %}

{% code title="Response" %}

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

{% endcode %}

The returned `id` can be used as `themeId` in the Generate, Create from Template, and Agent generation APIs. On `POST /v1.0/agent/generations`, omit `themeId` when you also send `templateId`.

### Related

* [Generate from text](/guides/generate-api-parameters-explained.md) for where `themeId` and `folderId` fit in the request
* [Generate from template](/guides/create-from-template-api-parameters-explained.md) for using theme and folder IDs with templates
* [POST /agent/generations](/agent-gamma-5/create-agent-generation.md) for optional `themeId` on agent requests
* [GET /themes](/workspace/list-themes.md) for the full API reference
* [GET /folders](/workspace/list-folders.md) for the full API reference


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.gamma.app/guides/list-themes-and-list-folders-apis-explained.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.