# Explore the API

The Gamma API generates polished presentations, documents, websites, and social posts from text. Everything runs asynchronously: you create a generation, poll for status, and retrieve the result.

For the exact request schema, field types, and response contract, see the individual endpoint reference pages.

### How it works

{% stepper %}
{% step %}
**Create a generation**

`POST /v1.0/generations` with your content and parameters. You get back a `generationId`.
{% endstep %}

{% step %}
**Poll for status**

`GET /v1.0/generations/{generationId}` every 5 seconds until `status` is `completed` or `failed`.
{% endstep %}

{% step %}
**Get your result**

The completed response includes `gammaUrl` (view it in Gamma) and `exportUrl` (download as PDF, PPTX, or PNG).
{% endstep %}

{% step %}
**Archive when done**

`POST /v1.0/gammas/{gammaId}/archive` to remove the Gamma from the active workspace. No credits deducted.
{% endstep %}
{% endstepper %}

See [Poll for results](/guides/async-patterns-and-polling.md) for full implementation examples in Python, JavaScript, and cURL.

### Quick reference

* Use `POST /v1.0/generations` when you want Gamma to create the layout from your prompt and parameters.
* Use `POST /v1.0/generations/from-template` when you want to adapt an existing Gamma — swap content, retarget the audience, transform the subject, replace images, or restructure cards.
* Poll `GET /v1.0/generations/{generationId}` until `status` is `completed` or `failed`.
* Use `GET /v1.0/themes` and `GET /v1.0/folders` to look up IDs before generation.
* Use `POST /v1.0/gammas/{gammaId}/archive` to remove a Gamma from the active workspace. Pass the file ID from the poll response, not the web app URL slug.

### Two ways to generate

|                     | Generate API                                                                                               | Create from Template API                                                                                                                                                                              |
| ------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Endpoint**        | `POST /v1.0/generations`                                                                                   | `POST /v1.0/generations/from-template`                                                                                                                                                                |
| **When to use**     | Creating from scratch. Maximum flexibility — you control format, tone, audience, images, layout, and more. | Adapting an existing Gamma — swap content, retarget the audience, transform the subject, replace images, or restructure cards. Design a template once in the Gamma app and reuse it programmatically. |
| **Required fields** | `inputText` + `textMode`                                                                                   | `prompt` + `gammaId`                                                                                                                                                                                  |
| **Key difference**  | AI determines the layout based on your parameters.                                                         | The template's structure is preserved by default; your prompt can also change content, audience, card count, or order.                                                                                |

Both endpoints support `themeId`, `exportAs`, `sharingOptions`, and `folderIds`. See the full parameter reference for each:

* [Generate API Parameters](/guides/generate-api-parameters-explained.md)
* [Create from Template Parameters](/guides/create-from-template-api-parameters-explained.md)

### Key parameters at a glance

| Parameter                  | What it controls                   | Example values                                                                                     |
| -------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------- |
| `format`                   | Output type                        | `presentation`, `document`, `webpage`, `social`                                                    |
| `textMode`                 | How input text is interpreted      | `generate` (topic → content), `condense` (summarize), `preserve` (keep as-is)                      |
| `themeId`                  | Brand theme (colors, fonts, logo)  | Get IDs from `GET /v1.0/themes`                                                                    |
| `numCards`                 | Number of slides/sections          | `1`–`75` depending on plan                                                                         |
| `exportAs`                 | Auto-export on completion          | `pdf`, `pptx`, `png`                                                                               |
| `imageOptions.source`      | Where images come from             | `aiGenerated`, `webFreeToUseCommercially`, `noImages`                                              |
| `textOptions.tone`         | Writing style                      | Any string: `"professional"`, `"casual"`, `"academic"`                                             |
| `textOptions.audience`     | Who the content is for             | Any string: `"executives"`, `"new hires"`, `"students"`                                            |
| `cardOptions.headerFooter` | Logo, page numbers, text           | 6 positions per card — see [Header and Footer Formatting](/guides/header-and-footer-formatting.md) |
| `sharingOptions`           | Permissions on the generated gamma | Workspace, external link, and email access levels                                                  |

### Supporting endpoints

| Endpoint                              | Purpose                                                                                |
| ------------------------------------- | -------------------------------------------------------------------------------------- |
| `GET /v1.0/themes`                    | List available themes (standard + custom workspace themes). Use the `id` as `themeId`. |
| `GET /v1.0/folders`                   | List workspace folders. Use folder `id` values in `folderIds`.                         |
| `POST /v1.0/gammas/{gammaId}/archive` | Archive a Gamma. Uses the `gammaId` returned by a completed generation.                |

Both list endpoints use cursor-based pagination: check `hasMore`, pass `nextCursor` as the `after` query param.

### Authentication

All requests require an API key in the `X-API-KEY` header. Generate your key from [Account Settings > API Keys](https://gamma.app/settings/api-keys).

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

API access requires a Pro, Ultra, Teams, or Business plan. See [Access and Pricing](/get-started/access-and-pricing.md) for credit costs and plan details.

{% hint style="info" %}
**Not a developer?** You can also use Gamma through [connectors and integrations](/connectors/connectors-and-integrations.md) — no code required.
{% endhint %}

### Related

* [Generate from text](/guides/generate-api-parameters-explained.md) for a parameter-by-parameter walkthrough of `POST /v1.0/generations`
* [Generate from a template](/guides/create-from-template-api-parameters-explained.md) for the template-based remix workflow
* [Poll for results](/guides/async-patterns-and-polling.md) for complete polling implementations


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.gamma.app/get-started/understanding-the-api-options.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.