> 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/edit-gamma.md).

# POST /agent/gammas/{gammaId}/edits

Edit an existing Gamma from a natural-language prompt.

Edit an existing Gamma with a natural-language `prompt`; the call returns an `editId` to poll (the final status reports `credits.deducted` and `credits.remaining` when available), requires edit permission on the Gamma, and runs one edit per Gamma at a time.

## Edit an existing Gamma

> Creates an asynchronous AI edit of an existing Gamma from a natural-language \`prompt\`. The edit changes the target page unless the prompt names another page of the Gamma, and it can add, duplicate, reorder, rename, and archive pages when the prompt asks for it. It never archives the target page. Returns an edit ID to poll with \`GET /v1.0/agent/edits/{editId}\`. Requires at least edit permission on the Gamma. Only one edit runs on a Gamma at a time.

```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":{"EditGamma":{"type":"object","properties":{"cardIds":{"minItems":1,"description":"Limit the edit to these cards (slides) on the target page. Each ID must be a card on that page; cards outside the list are left unchanged. Omit to let the edit touch any card on the page.","maxItems":100,"items":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","maxLength":64},"type":"array"},"files":{"maxItems":50,"description":"Files stored with `POST /v1.0/uploads`, as the `{ uploadId, filename }` that route returned. The agent uses them as source material for the edit and can place their images. A presentation or PDF is not merged in as slides. At most 50 files and 250 MiB in total. Each upload can be attached to one generation or edit; to use a file again after that, upload it again.","type":"array","items":{"$ref":"#/components/schemas/EditGammaFile"}},"sourceUrls":{"maxItems":10,"description":"Up to 10 http or https URLs the agent reads as source material for the edit. When a link the prompt depends on cannot be read, the edit makes no change that depends on it and its summary says what failed. A link given only as background is skipped when it cannot be read.","items":{"type":"string","format":"uri","pattern":"^https?://"},"type":"array"},"prompt":{"type":"string","description":"Natural-language instruction describing the edit.","maxLength":10000},"quality":{"type":"string","description":"How much model effort the edit runs with, matching the quality tiers in the\nGamma agent UI. `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"]},"disableConnectors":{"type":"boolean","description":"Opt this edit out of workspace connector access (e.g. Notion, Slack)."}},"required":["prompt"]},"EditGammaFile":{"type":"object","properties":{"uploadId":{"type":"string","description":"Id returned by `POST /v1.0/uploads`."},"filename":{"type":"string","description":"Filename returned by `POST /v1.0/uploads`."}},"required":["uploadId","filename"]},"EditGammaResponse":{"type":"object","properties":{"editId":{"type":"string","description":"Unique ID for the edit job. Poll `GET /v1.0/agent/edits/{editId}` with it."},"gammaUrl":{"type":"string","description":"URL to the Gamma being edited"}},"required":["editId","gammaUrl"]}}},"paths":{"/v1.0/agent/gammas/{gammaId}/edits":{"post":{"description":"Creates an asynchronous AI edit of an existing Gamma from a natural-language `prompt`. The edit changes the target page unless the prompt names another page of the Gamma, and it can add, duplicate, reorder, rename, and archive pages when the prompt asks for it. It never archives the target page. Returns an edit ID to poll with `GET /v1.0/agent/edits/{editId}`. Requires at least edit permission on the Gamma. Only one edit runs on a Gamma at a time.","operationId":"editGamma","parameters":[{"name":"gammaId","required":true,"in":"path","description":"The Gamma to edit: a gamma (file) ID, or a page ID (the id in a\ngamma.app/docs/<id> URL). The ID sets the edit's target page: a file ID\ntargets the Gamma's main page, a page ID that page. A prompt that names no\npage edits the target page; one that names another page of the Gamma, by\ntitle or position, edits that page.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditGamma"}}}},"responses":{"201":{"description":"Edit job created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditGammaResponse"}}}},"400":{"description":"Invalid request parameters, or a Gamma that is archived, has no pages, or is of a type that cannot be edited"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Insufficient credits, no edit permission on the Gamma, or a `quality` tier the plan does not include"},"404":{"description":"Gamma not found, or a `files` upload does not exist or has expired"},"409":{"description":"An edit is already in progress for this Gamma (`code: edit_in_progress`, with the running `editId` when it belongs to your workspace)"},"413":{"description":"`files` exceed 250 MiB in total"},"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":"Edit an existing Gamma","tags":["public-api"]}}}}
```

{% hint style="info" %}
Pass a file id (`g_…`) to target the Gamma's main page, or a page id from a `gamma.app/docs/<id>` URL to target that page. Unless the prompt names another page by title or position, the edit applies to the target page. Prompts can ask to add, duplicate, reorder, rename, or archive pages; the target page is never archived. If another edit is already running on the Gamma, the API returns `409` with code `edit_in_progress`.

Optional `pace` sets how long the edit may run: `standard` (the default, up to 10 minutes) or `relaxed` (up to 20 minutes), which gives the agent more time to work on quality. Any other value, including `null`, returns `400`. See [Choose a pace](https://developers.gamma.app/guides/async-patterns-and-polling.md#choose-a-pace-for-agent-jobs).
{% endhint %}

## Related

* [GET /agent/edits/{editId}](https://developers.gamma.app/agent-gamma-5/get-edit-status.md) to poll for completion
* [GET /gammas/{gammaId}](https://developers.gamma.app/management/get-gamma.md) to confirm ids and metadata before editing
* [Error codes](https://developers.gamma.app/reference/error-codes.md) for `409` and workspace concurrency errors


---

# 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/edit-gamma.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.
