> 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/get-started/understanding-the-api-options.md). # 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), `exportUrl` (download as PDF, PPTX, or a PNG `.zip` with one image per card), and `gammaId` for archive or delete actions. {% endstep %} {% step %} #### Archive or delete when done `POST /v1.0/gammas/{gammaId}/archive` removes the Gamma from the active workspace. `DELETE /v1.0/gammas/{gammaId}` deletes it and requires a workspace admin role. {% 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. * Both generation endpoints accept an optional `title` when you want to set the Gamma name explicitly. * 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. * Use `DELETE /v1.0/gammas/{gammaId}` when you need to remove a Gamma entirely. This requires a workspace admin role. ### 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` | `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 `title`, `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 | | -------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------- | | `title` | Explicit Gamma title | `"Q3 Board Update"` | | `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. | | `DELETE /v1.0/gammas/{gammaId}` | Delete a Gamma. Also uses the completed generation's `gammaId` and requires a workspace admin role. | 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 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 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= ``` 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.