Gamma Developer Docs

Gamma API and MCP for AI agents and apps: generate branded presentations, documents, webpages, and social posts, then read, edit, and export them.

Give your AI agent or app the tools to create, edit, and export on-brand gammas, through the hosted MCP server or the REST API.

Connect your agentUse the REST API

Three ways to build with Gamma:

• Connect your AI agent. MCP clients that support OAuth with Dynamic Client Registration can use the hosted server at https://mcp.gamma.app/mcp on any plan. Popular clients already work; for a custom client, register its redirect URIs first. Guide: Connect your own agent.

• Build a branded template workflow. A human approves a template; your code or agent generates on-brand variants from it (POST /agent/generations with templateId, or generate_from_template over MCP), then inspects, edits, and exports them. Guide: Generate from approved templates; what is preserved and what can change: Brand, template, and editing controls.

• Call the REST API directly. Gamma 5 agent generation and editing, plus read, search, export, and analytics endpoints, with an API key (any plan) or OAuth.

Authentication

The Gamma API supports two authentication methods. Pick based on whose Gamma account your requests act as:

	API key	OAuth 2.0
Best for	Scripts, internal tools, automation platforms (Zapier, Make, n8n)	Apps acting on behalf of your users, MCP servers, marketplace integrations
Setup	Copy a key from Settings > API Keys	Register a client, run an authorization flow
Header	X-API-KEY: sk-gamma-...	Authorization: Bearer <access_token>
Whose account	Yours	The user who authorized your app
Credential lifetime	Until revoked	Access token ~1 hour; refresh token up to 90 days (rotated)

Every request must include exactly one of the two headers, plus Content-Type: application/json. See Authenticate with OAuth for the full OAuth setup guide.

API keys are available on all plans, including Free; usage is limited by your credits and your plan's limits (see Access and pricing). Connectors do not require an API key.

Machine-readable docs are available at developers.gamma.app/llms.txt and developers.gamma.app/llms-full.txt. Every page is also available as markdown by appending .md to the URL.

Quickstart

1. Start a generation

Generation runs on the Gamma 5 agent. Describe what you want; the agent plans and builds the gamma.

cURL

curl -X POST https://public-api.gamma.app/v1.0/agent/generations \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $GAMMA_API_KEY" \
  -d '{
    "prompt": "A 10-slide Q3 product launch strategy for the sales team",
    "format": "presentation",
    "numCards": 10,
    "exportAs": "pdf"
  }'

Python

import requests, os

response = requests.post(
    "https://public-api.gamma.app/v1.0/agent/generations",
    headers={
        "X-API-KEY": os.environ["GAMMA_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "prompt": "A 10-slide Q3 product launch strategy for the sales team",
        "format": "presentation",
        "numCards": 10,
        "exportAs": "pdf",
    },
)
response.raise_for_status()  # surfaces 403 insufficient_credits, 429 concurrency limits, etc.
generation_id = response.json()["generationId"]

JavaScript

const response = await fetch(
  "https://public-api.gamma.app/v1.0/agent/generations",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": process.env.GAMMA_API_KEY,
    },
    body: JSON.stringify({
      prompt: "A 10-slide Q3 product launch strategy for the sales team",
      format: "presentation",
      numCards: 10,
      exportAs: "pdf",
    }),
  }
);
if (!response.ok) throw new Error(await response.text());
const { generationId } = await response.json();

Response

{
  "generationId": "gen_V1StGXR8Z5jdHi6B",
  "status": "pending",
  "warnings": []
}

To generate from an approved template instead, add "templateId": "<workspace template, gamma, or Explore template id>" and leave out themeId.

2. Poll for the result

Poll GET /v1.0/agent/generations/{generationId} every 5 seconds until status is completed or failed, then read gamma.gammaUrl from the completed response. While still pending, the response may include progress with done, total, and percent (0–99) once card building starts; only completed means the job is finished. Completed and failed responses also report credits.deducted (what this job charged) and credits.remaining (your balance when the status was served); either may be omitted if the lookup fails. See Poll for results for pacing, rate-limit headers, and how agent polling differs from Classic.

import time

deadline = time.time() + 25 * 60  # agent jobs usually finish in minutes but may run up to 20
while time.time() < deadline:
    resp = requests.get(
        f"https://public-api.gamma.app/v1.0/agent/generations/{generation_id}",
        headers={"X-API-KEY": os.environ["GAMMA_API_KEY"]},
    )
    resp.raise_for_status()  # a 401, 404, or 429 is shown instead of failing on a missing "status"
    result = resp.json()
    if result["status"] == "completed":
        print(result["gamma"]["gammaUrl"])
        break
    if result["status"] == "failed":
        print("Generation failed:", result.get("error"))
        break
    time.sleep(5)
else:
    print("Still running after 25 minutes. Don't resubmit; check", generation_id, "again later.")

Response (completed)

{
  "generationId": "gen_V1StGXR8Z5jdHi6B",
  "status": "completed",
  "gamma": {
    "gammaId": "g_l0mf2jvf1fpmi1v",
    "gammaUrl": "https://gamma.app/docs/abc123"
  },
  "result": { "summary": "Created a 10-card launch deck covering goals, timeline, and metrics." },
  "exportUrl": "https://exports.gamma.app/.../deck.pdf",
  "warnings": [],
  "updatedTime": "2026-08-25T17:03:04.000Z",
  "credits": { "deducted": 15, "remaining": 485 }
}

3. Use your Gamma

Your presentation is live at gamma.gammaUrl. If you specified exportAs and the export succeeded, the file is at exportUrl; an export_failed entry in warnings means the gamma was created without the file, and you can export it with POST /v1.0/gammas/{gammaId}/export. To edit your gamma, call POST /v1.0/agent/gammas/{gammaId}/edits with a natural-language instruction.

Getting a 401? Gamma uses X-API-KEY as a custom header — not Authorization: Bearer. See Error codes for other common issues.

Endpoints

Endpoint	Method	Description
/agent/generations	POST	Gamma 5: generate from a prompt, optionally from a template (templateId)
/agent/generations/{generationId}	GET	Poll agent generation status
/agent/gammas/{gammaId}/edits	POST	Gamma 5: edit your gamma
/agent/edits/{editId}	GET	Poll agent edit status
/generations	POST	Classic: generate from text
/generations/from-template	POST	Classic: generate from template
/generations/{id}	GET	Poll Classic generation status
/images	POST	Generate a standalone image
/images/{id}	GET	Poll image generation status
/images/media/{savedMediaId}/archive	POST	Archive a media library item
/themes	GET	List workspace themes
/folders	GET	List workspace folders
/gammas/search	GET	Search workspace gammas
/templates/search	GET	Search workspace and explore templates
/gammas/{gammaId}	GET	Get gamma metadata
/gammas/{gammaId}/comments	GET	List comment threads
/gammas/{gammaId}/archive	POST	Archive a Gamma
/gammas/{gammaId}/export	POST	Export an existing Gamma
/exports/{id}	GET	Poll export status
/gammas/{gammaId}	DELETE	Delete a Gamma
/gammas/{gammaId}/analytics	GET	Doc-level engagement metrics
/gammas/{gammaId}/analytics/cards	GET	Per-card engagement stats
/gammas/{gammaId}/analytics/viewers	GET	Per-viewer engagement (paginated)
/gammas/{gammaId}/analytics/viewers/{userId}	GET	Single-viewer per-card engagement

Building an AI agent? Generation, template generation, editing, reading, search, export, and analytics are also available as MCP tools. The MCP server lets your agent generate gammas from text or templates, read and search existing ones, edit them, export, and read comments and analytics, authenticated with OAuth and Dynamic Client Registration. See the MCP tools reference.

Next steps

Generate with the Gamma 5 agent

One prompt, optional template, quality presets, source URLs, and export — the recommended endpoint.

Edit an existing gamma

Describe the change you want and Gamma applies it to your gamma.

Classic generation

The previous engine: parameter-driven generation and template remixing. Use it for webpages and multi-page gammas, which the Gamma 5 agent does not support, or if your integration is already built on it.

Connect integrations

Use Gamma with AI assistants and automation platforms — some require no API key.

Set up the MCP server

Give your AI agent tools to generate, read, edit, and export gammas via OAuth.