%20(1).png){kind=avatar}
Understanding Gamma API Surfaces, IDs, and Best Practices for Integrations and Generation Status
Hey Dan P.! 👋 Pulling this together in one place. There are really three different surfaces in play here:
- 1.
The REST API
- 2.
Gamma MCP for custom integrations
- 3.
The packaged Gamma integrations inside assistants like Claude and ChatGPT
They overlap a lot, but they don't expose exactly the same level of control. The safest rule is to use the source of truth for the specific surface you're on:
REST API - the public API docs/OpenAPI are the canonical contract.
Custom MCP integrations - the Gamma MCP docs are the right reference.
Packaged Claude connector - the practical source of truth is the live tool schema in Claude itself. If a value is rejected there, treat it as unsupported in that surface.
If you don't have REST API or MCP access yet, you'll need to apply first: https://developers.gamma.app Here are the concrete answers: generationId and gammaId are different IDs. generationId is the async job ID. gammaId is the ID of the generated Gamma returned once the job completes. gamma.app/generations/{generationId} can be used as a progress URL, but the durable final URL is the completed gammaUrl. For sharing/bookmarking, use gammaUrl, not the /generations/ URL. read_gamma accepts a Gamma file ID or a full Gamma /docs/ URL. It does not accept a generationId, so a 404 there is expected. If you need reliable browserless confirmation that a generation is done, keep the generationId and poll GET /v1.0/generations/{id} via REST until status is completed or failed. On imageOptions.source, the current REST docs include themeAccent, but if the packaged Claude connector rejects it, treat it as unavailable in that connector today. To use only your own images, put raw HTTPS image URLs in inputText and set imageOptions.source to noImages. Don't rely on markdown image syntax for production workflows. There is no structured gallery-layout parameter today. Layout hints go through additionalInstructions, and template generation is the best option if you need repeatable visual structure. inputText max is 400000 characters. For rate limits, read the X-RateLimit-* headers on responses rather than assuming fixed ceilings in client logic. If a packaged integration times out on a large generation, don't assume the generation failed. The safer pattern is to keep the generationId and confirm status via REST. Relevant docs:
There isn't a public reference implementation for this flow today. If you're building against Gamma programmatically and need finer-grained control than the packaged assistant integrations expose, use either a custom MCP integration or the REST API depending on whether you want assistant-native tools or explicit request/response control. This should cover everything you raised. Let me know if anything's unclear!
