> 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/agent-gamma-5/create-agent-generation.md).

# POST /agent/generations

Start an asynchronous Gamma agent generation from a natural-language prompt.

Start a Gamma 5 agent generation from a `prompt`. This is the recommended endpoint for new presentations, documents, and social posts, and it also covers template-based generation through `templateId`; webpages and multi-page gammas are Classic-only ([`POST /generations`](/generations-classic/create-generation.md)). Returns a `gen_`-prefixed `generationId` to poll with [`GET /agent/generations/{generationId}`](/agent-gamma-5/get-agent-generation-status.md), whose completed or failed response reports the credits charged (`credits.deducted`) and your remaining balance (`credits.remaining`) when those lookups succeed.

## Create agent generation

> Creates an asynchronous generation job run by the Gamma agent. \`prompt\` is the only required field. Guidance fields (\`numCards\`, \`sourceUrls\`, \`additionalInstructions\`) are soft targets; \`numCards\` must not exceed the card maximum for the workspace plan. A \`folderId\` or \`sharingOptions\` setting that a workspace admin restricts is ignored and reported in \`warnings\`. Returns a \`gen\_\`-prefixed generation ID to poll with \`GET /v1.0/agent/generations/{generationId}\`.

```json
{"openapi":"3.0.0","info":{"title":"Gamma Public API","version":"1.0"},"tags":[{"name":"public-api","description":"Public API endpoints for external integrations"}],"servers":[{"url":"https://public-api.gamma.app","description":"Production"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"API key for authentication"}},"schemas":{"CreateAgentGeneration":{"type":"object","properties":{"themeId":{"type":"string","description":"Optional saved theme to apply, using an `id` from `GET /v1.0/themes`. The theme is applied on Gamma's Standard Brand Base design for the requested `format`. Cannot be combined with `templateId`: a template or gamma keeps its own look.","minLength":1,"maxLength":128},"numCards":{"type":"integer","description":"Target number of cards, capped at the plan's maximum (10 on free plans,\n100 on paid plans); a higher value is rejected with 400. Within the cap\nit is a soft target: the agent may deviate by a card or two, and the\nresult is not validated against it.","minimum":1,"maximum":100},"prompt":{"type":"string","description":"The brief: what to generate. The only required field.","maxLength":400000},"folderId":{"type":"string","description":"Folder to place the generated Gamma in, within the caller's workspace.\nUse an `id` from `GET /v1.0/folders`."},"sharingOptions":{"description":"Access settings for the generated Gamma.","allOf":[{"$ref":"#/components/schemas/AgentGenerationSharingOptions"}]},"format":{"type":"string","description":"Output format. Defaults to \"presentation\" when omitted. `webpage` is\nnot supported by the agent engine and is rejected.","enum":["document","presentation","social"]},"templateId":{"type":"string","description":"Optional starting point: the id of an accessible workspace template, of\na regular gamma in the workspace, or of an official\nGamma template (the `exploreTemplates[].id` returned by\n`GET /v1.0/templates/search`). The selection works the way picking the\nsame template or gamma in the Gamma app does: the prompt decides how the\nsource is used, from filling its layouts with new content to borrowing\nonly its look or moving its content onto a new design, and the source\nitself stays unchanged. An official template id names the currently\npublished copy: it survives routine\nupdates but can change when Gamma rebuilds or reintroduces the template,\nso rediscover it through the search endpoint if a saved id stops being\naccepted. Unknown, unauthorized, other-workspace, archived and retired\nids are all rejected with the same 400; no other template is substituted\nfor a rejected id.","minLength":1,"maxLength":128},"quality":{"type":"string","description":"Quality preset: \"lite\", \"standard\", or \"max\" — the same presets the\nGamma app offers. `max` requires a plan that includes it and can use more\ncredits. Omitting the field uses the API default, capped at what the\nplan includes.","enum":["lite","max","standard"]},"sourceUrls":{"description":"Guidance: up to 10 http or https URLs the agent should read and use as source material\n— a soft request, not a binding fetch list. A URL that cannot be read is\nskipped; it does not fail the generation.","maxItems":10,"type":"array","items":{"type":"string","format":"uri"}},"additionalInstructions":{"type":"string","description":"Guidance: extra direction for the generation (tone, audience,\nlanguage, style). Treated as guidance the agent aims to follow, not\na constraint the output is validated against.","minLength":0,"maxLength":5000},"exportAs":{"type":"string","description":"Export the finished gamma after a successful generation as a PDF, PPTX,\nor PNG zip. Export failure is reported as a warning on the generation,\nnever as a failed generation.","enum":["pdf","png","pptx"]},"disableConnectors":{"type":"boolean","description":"Opt this run out of workspace connector access (e.g. Notion, Slack)."}},"required":["prompt"]},"AgentGenerationSharingOptions":{"type":"object","properties":{"workspaceAccess":{"description":"Default access level for workspace members","enum":["comment","edit","fullAccess","noAccess","view"],"type":"string"},"externalAccess":{"description":"Access level for external users (via shared link)","enum":["comment","edit","noAccess","view"],"type":"string"},"emailOptions":{"description":"Email sharing configuration","allOf":[{"$ref":"#/components/schemas/EmailOptions"}]}}},"EmailOptions":{"type":"object","properties":{"access":{"description":"Permission level for email recipients","enum":["comment","edit","fullAccess","view"],"type":"string"},"recipients":{"description":"Email addresses to share with","minItems":1,"type":"array","items":{"type":"string","format":"email"}}},"required":["recipients"]},"CreateAgentGenerationResponse":{"type":"object","properties":{"generationId":{"type":"string","description":"Unique id for the generation job, prefixed `gen_`.","pattern":"^gen_[A-Za-z0-9]+$"},"status":{"type":"string","description":"Always \"pending\" on create.","enum":["pending"]},"warnings":{"description":"Request-level warnings. Empty array when there are none.","type":"array","items":{"$ref":"#/components/schemas/AgentGenerationWarning"}}},"required":["generationId","status","warnings"]},"AgentGenerationWarning":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable warning code.","enum":["email_full_access_members_only","email_invites_failed","export_failed","external_access_failed","folder_placement_failed","ignored_email_options","ignored_email_recipients","ignored_external_access","ignored_folder_id","ignored_workspace_access","workspace_access_failed"]},"message":{"type":"string","description":"Human-readable explanation, suitable for display."}},"required":["code","message"]}}},"paths":{"/v1.0/agent/generations":{"post":{"description":"Creates an asynchronous generation job run by the Gamma agent. `prompt` is the only required field. Guidance fields (`numCards`, `sourceUrls`, `additionalInstructions`) are soft targets; `numCards` must not exceed the card maximum for the workspace plan. A `folderId` or `sharingOptions` setting that a workspace admin restricts is ignored and reported in `warnings`. Returns a `gen_`-prefixed generation ID to poll with `GET /v1.0/agent/generations/{generationId}`.","operationId":"createAgentGeneration","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentGeneration"}}}},"responses":{"202":{"description":"Generation job created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentGenerationResponse"}}}},"400":{"description":"Invalid request parameters, `numCards` above the plan maximum, a `templateId` that is not an accessible template or gamma, a `themeId` that is not an available theme, or `themeId` combined with `templateId`"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Insufficient credits, a `quality` tier the plan does not include, or access denied"},"429":{"description":"Rate limit exceeded, or the workspace has too many in-flight agent jobs (`code: workspace_concurrency_limit_exceeded`, with a `Retry-After` header)"},"503":{"description":"The service is busy; retry the request"}},"summary":"Create agent generation","tags":["public-api"]}}}}
```

{% hint style="info" %}
Poll [GET /agent/generations/{generationId}](/agent-gamma-5/get-agent-generation-status.md) with the returned id. Request-level `warnings` (for example ignored sharing or folder settings) appear on the create response and may appear again on the completed status response.

Optional `themeId` uses an `id` from [GET /themes](/workspace/list-themes.md). The theme applies on Gamma's Standard Brand Base for the requested `format`. Do not send `themeId` with `templateId`; the request fails with `400`. An unknown or inaccessible theme also returns `400`.
{% endhint %}

## Related

* [GET /agent/generations/{generationId}](/agent-gamma-5/get-agent-generation-status.md) to poll for completion
* [GET /themes](/workspace/list-themes.md) to look up a `themeId`
* [Poll for results](/guides/async-patterns-and-polling.md) for polling patterns and rate limit guidance
* [Warnings](/reference/warnings.md) for agent generation warning codes


---

# 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/agent-gamma-5/create-agent-generation.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.