Gamma Cost Tuning

Output

Record the measurement window, aggregate usage, approved plan/workflow decision, owner, verification date, and rollback state. Do not include private presentation content, billing credentials, or user data.

Examples

Use a fictional staging workspace to compare aggregate usage after an approved asset or workflow change, then promote only when the owner accepts the evidence and publishing/privacy behavior is unchanged.

Overview

Optimize Gamma API usage to minimize credit consumption. Gamma uses a credit-based billing system where costs are driven by image generation model tier and content complexity. API access requires Pro or higher subscription.

Prerequisites

• Active Gamma Pro/Ultra/Teams/Business subscription
• Understanding of credit system
• Completed gamma-install-auth setup

Gamma Credit System

Image Model Tiers

Card text generation also costs credits based on the AI model used.

Plan Comparison

Instructions

Step 1: Track Credit Usage

// src/gamma/cost-tracker.ts
interface UsageEntry {
  generationId: string;
  creditsUsed: number;
  outputFormat: string;
  timestamp: Date;
}

class CreditTracker {
  private usage: UsageEntry[] = [];

  record(entry: UsageEntry) {
    this.usage.push(entry);
  }

  getDaily(): { total: number; count: number; avg: number } {
    const today = new Date().toDateString();
    const todayUsage = this.usage.filter(
      (u) => u.timestamp.toDateString() === today
    );
    const total = todayUsage.reduce((sum, u) => sum + u.creditsUsed, 0);
    return {
      total,
      count: todayUsage.length,
      avg: todayUsage.length > 0 ? Math.round(total / todayUsage.length) : 0,
    };
  }

  getMonthly(): { total: number; count: number } {
    const th

Gamma Data Handling

Output

Record source reference, approved field/destination policy, retention rule, aggregate validation result, owner, and exception state. Keep presentation content, viewer data, and credentials outside the receipt.

Examples

Process a fictional staging deck through a field allowlist, confirm only approved metadata reaches the test destination, and remove the fixture according to the retention policy.

Overview

Data handling, privacy controls, and compliance for Gamma API integrations. Gamma processes user-submitted content through AI to generate presentations -- understand what data flows where and how to handle PII, retention, and GDPR requirements.

Prerequisites

• Understanding of data privacy regulations (GDPR, CCPA)
• Completed gamma-install-auth setup
• Data classification policies defined

Data Flow Map

User Input (content, prompts)
     │
     ▼
┌──────────────┐
│  Your App    │  ← PII may be in content (names, company data)
│  (API key)   │
└──────┬───────┘
       │ POST /v1.0/generations
       ▼
┌──────────────┐
│  Gamma API   │  ← Content processed by AI
│  (gamma.app) │  ← Images generated
└──────┬───────┘
       │ gammaUrl + exportUrl
       ▼
┌──────────────┐
│  Generated   │  ← Presentation stored in Gamma workspace
│  Content     │  ← Export files (PDF/PPTX/PNG) temporary
└──────────────┘

Data Classification

Instructions

Step 1: Sanitize Content Before Sending

// src/gamma/sanitize.ts
// Remove PII from content before sending to Gamma if not needed

interface SanitizeOptions {
  removeEmails: boolean;
  removePhones: boolean;
  maskNames: boolean;
}

function sanitizeContent(content: string, opts: SanitizeOptions): string {
  let sanitized = content;

  if (opts.removeEmails) {
    sanitized = sanitized.replace(/[\w.-]+@[\w.-]+\.\w+/g, "[email]");
  }
  if (opts.removePhones) {
    sanitized = sanitized.replace(/\+?[\d\s()-]{10,}/g, "[phone]");
  }
  if (opts.maskNames) {
    // Only mask if 

Gamma Debug Bundle

Output

Create a redacted evidence index with opaque correlation ID, artifact list, access owner, retention date, reproduction outcome, and next action. Sensitive originals remain in the approved incident store.

Examples

For a synthetic publish failure, retain runtime/configuration references and aggregate errors only; review the bundle for private content or tokens, restrict access to the incident owner, and retire it at the retention date.

Current State

!node --version 2>/dev/null || echo 'N/A' !python3 --version 2>/dev/null || echo 'N/A' !uname -a

Overview

Debugging toolkit for Gamma API integration issues. Includes connectivity tests, request tracing, diagnostic scripts, and support ticket templates. Gamma uses a REST API at https://public-api.gamma.app/v1.0/ with X-API-KEY header authentication.

Prerequisites

• Active Gamma integration
• Node.js 18+ or Python 3.10+
• curl and jq available

Instructions

Step 1: Quick Connectivity Test (curl)

#!/bin/bash
set -euo pipefail
echo "=== Gamma API Diagnostic ==="

# 1. Check API key
if [ -z "${GAMMA_API_KEY:-}" ]; then
  echo "FAIL: GAMMA_API_KEY not set"; exit 1
fi
echo "OK: API key set (${#GAMMA_API_KEY} chars, prefix: ${GAMMA_API_KEY:0:4}...)"

# 2. Test authentication via /themes endpoint
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "X-API-KEY: $GAMMA_API_KEY" \
  "https://public-api.gamma.app/v1.0/themes")
if [ "$STATUS" = "200" ]; then
  echo "OK: Authentication successful"
elif [ "$STATUS" = "401" ]; then
  echo "FAIL: Invalid API key (401)"
elif [ "$STATUS" = "403" ]; then
  echo "FAIL: Account not on Pro+ plan (403)"
else
  echo "WARN: Unexpected status $STATUS"
fi

# 3. Check latency
echo "--- Latency (3 samples) ---"
for i in 1 2 3; do
  LATENCY=$(curl -s -o /dev/null -w "%{time_total}" \
    -H "X-API-KEY: $GAMMA_API_KEY" \
    "https://public-api.gamma.app/v1.0/themes")
  echo "  Request $i: ${LATENCY}s"
done

# 4. List themes (verify API access)
echo "--- Workspace Themes ---"
curl -s -H "X-API-KEY: $GAMMA_API_KEY" \
  "https://public-api.gamma.app/v1.0/themes" | jq '.[].name' 2>/dev/null || echo "Could not parse themes"

Step 2: TypeScript Diagnostic Script

// scripts/gamma-diagnose.ts
const BASE = "https://public-api.gamma.app/v1.0";
const headers = {
  "X-API-KEY": process.env.GAMMA_API_KEY!,
  "Content-Type": "application/json&quo

Gamma Deploy Integration

Examples

Deploy a fictional staging presentation integration with a scoped credential, verify its canary reaches only the approved audience, then simulate a failed check and roll back before production sharing.

Overview

Deploy Gamma-integrated applications to various cloud platforms with proper configuration and secret management.

Prerequisites

• Completed CI integration
• Cloud platform account (Vercel, AWS, or GCP)
• Production Gamma API key

Instructions

Vercel Deployment

Step 1: Configure Vercel Project

set -euo pipefail
# Install Vercel CLI
npm i -g vercel

# Link project
vercel link

# Set environment variable
vercel env add GAMMA_API_KEY production

Step 2: Create vercel.json

{
  "framework": "nextjs",
  "buildCommand": "npm run build",
  "env": {
    "GAMMA_API_KEY": "@gamma_api_key"
  },
  "functions": {
    "api/**/*.ts": {
      "maxDuration": 30
    }
  }
}

Step 3: Deploy

# Preview deployment
vercel

# Production deployment
vercel --prod

AWS Lambda Deployment

Step 1: Store Secret in AWS Secrets Manager

aws secretsmanager create-secret \
  --name gamma/api-key \
  --secret-string '{"apiKey":"your-gamma-api-key"}'

Step 2: Lambda Configuration

// lambda/gamma-handler.ts
import { SecretsManager } from '@aws-sdk/client-secrets-manager';
import { GammaClient } from '@gamma/sdk';

const secretsManager = new SecretsManager({ region: 'us-east-1' });
let gamma: GammaClient;

async function getGammaClient() {
  if (!gamma) {
    const secret = await secretsManager.getSecretValue({
      SecretId: 'gamma/api-key',
    });
    const { apiKey } = JSON.parse(secret.SecretString!);
    gamma = new GammaClient({ apiKey });
  }
  return gamma;
}

export async function handler(event: any) {
  const client = await getGammaClient();
  const result = await client.presentations.create({
    title: event.title,
    prompt: event.prompt,
  });
  return { statusCode: 200, body: JSON.stringify(result) };  # HTTP 200 OK
}

Step 3: SAM Template

# template.yaml
AWSTemplateFormatVersion: '2010-09-09'  # 2010 = configured value
Transform: AWS::Serverless-2016-10-31  # 2016 = configured value

Resources:
  GammaFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: dist/gamma-handler.handler
      Runtime: nodejs20.x
      Timeout: 30
      MemorySize: 256  # 256 bytes
      Policies:
        - SecretsManagerReadWrite
      Environment:
        Variables

Gamma Enterprise RBAC

Output

Maintain an access receipt with role, approved operation class, policy version, review date, approver, and revocation result. Do not include credentials or presentation content.

Examples

Grant a temporary test role view access to a fictional staging deck, attempt an unauthorized publish, confirm denial, then revoke the role and record only the opaque test outcome.

Overview

Implement role-based access control for Gamma API integrations. Gamma's API uses a single API key per workspace -- granular permissions must be implemented in your application layer. The Teams and Business plans support workspace-level collaboration with shared themes and folders.

Prerequisites

• Gamma Teams or Business subscription
• Application database for user/role storage
• Completed gamma-install-auth setup

Gamma Access Model

Gamma Workspace (1 API key)
├── Themes (shared across workspace)
├── Folders (shared across workspace)
└── Generations (tied to API key, not individual users)

Your Application Layer (you implement this):
├── Organization
│   ├── Admin (manage API key, configure themes)
│   ├── Editor (generate presentations, use templates)
│   ├── Viewer (view generated presentations, download exports)
│   └── Guest (no generation access)

Key point: Gamma's API does not have per-user authentication. All API calls use the workspace API key. You must enforce per-user permissions in your application.

Instructions

Step 1: Define Role Hierarchy

// src/auth/gamma-roles.ts
type GammaRole = "guest" | "viewer" | "editor" | "admin";

const PERMISSIONS: Record<GammaRole, string[]> = {
  guest: [],
  viewer: ["generation:view", "export:download"],
  editor: ["generation:view", "generation:create", "export:download", "template:use"],
  admin: [
    "generation:view", "generation:create", "export:download",
    "template:use", "template:manage", "theme:manage",
    "settings:manage", "member:manage",
  ],
};

function hasPermission(role: GammaRole, permission: string): boolean {
  return PERMISSIONS[role]?.includes(permission) ?? false;
}

Step 2: Authorization Middleware

// src/middleware/gamma-auth.ts
import { Request, Response, NextFunction } from "express";

function requireGammaPermission(permission: string) {
  return (req: Request, res: Response, next: NextFunction) => {
    const user = req.user; // Set by your auth middleware
    if (!user) return res.status(401).json({ error: "Unauthorized" });

    if (!hasPermission(user.gammaRole, permission)) {
     

Gamma Hello World

Output

Return an opaque test ID, schema/publish result, owner, and redacted failure reference. Keep presentation content, credentials, and viewer data out of output.

Examples

Create a disposable staging presentation with fictional content, verify it is visible only to the approved test audience, then delete or unpublish it through the documented cleanup path.

Overview

Generate your first presentation using Gamma's async Generate API. The workflow is: POST to create a generation, poll for status, then retrieve results (gammaUrl + exportUrl).

Prerequisites

• Completed gamma-install-auth setup
• Valid GAMMA_API_KEY environment variable
• Pro account with available credits

The Generate-Poll-Retrieve Pattern

All Gamma generations are asynchronous:

1. POST /v1.0/generations — submit content, receive generationId
2. GET /v1.0/generations/{generationId} — poll every 5s until completed or failed
3. Result — gammaUrl (view in app) + exportUrl (download PDF/PPTX/PNG)

Instructions

Minimal curl Example

# Step 1: Create generation
GENERATION=$(curl -s -X POST \
  "https://public-api.gamma.app/v1.0/generations" \
  -H "X-API-KEY: ${GAMMA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Create a 5-card presentation about the benefits of AI in business",
    "outputFormat": "presentation"
  }')

GEN_ID=$(echo "$GENERATION" | jq -r '.generationId')
echo "Generation started: $GEN_ID"

# Step 2: Poll until complete (every 5 seconds)
while true; do
  STATUS=$(curl -s \
    "https://public-api.gamma.app/v1.0/generations/${GEN_ID}" \
    -H "X-API-KEY: ${GAMMA_API_KEY}")
  STATE=$(echo "$STATUS" | jq -r '.status')
  echo "Status: $STATE"
  [ "$STATE" = "completed" ] || [ "$STATE" = "failed" ] && break
  sleep 5
done

# Step 3: Retrieve results
echo "$STATUS" | jq '{gammaUrl, exportUrl, creditsUsed}'

Node.js / TypeScript Example

const GAMMA_BASE = "https://public-api.gamma.app/v1.0";
const headers = {
  "X-API-KEY": process.env.GAMMA_API_KEY!,
  "Content-Type": "application/json",
};

async function generatePresentation(content: string) {
  // Step 1: Create generation
  const createRes = await fetch(`${GAMMA_BASE}/generations`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      content,
      outputFormat: "presentation",

Gamma Incident Runbook

Instructions

Assign severity and an opaque incident ID, pause unsafe publishing/sharing, classify the issue, apply the smallest safe mitigation, verify recovery with synthetic content, and record the owner’s decision.

Output

Produce a redacted incident receipt with severity, impact, mitigation, recovery verification, rollback decision, owner, and follow-ups.

Error Handling

Revoke scoped credentials on suspected exposure, do not replay content actions until access/destination checks pass, and keep private content out of incident artifacts.

Examples

During a synthetic sharing outage, pause the staging integration, confirm no duplicate publish occurs, restore one canary, and resume only after the incident owner records recovery evidence.

Overview

Systematic procedures for responding to and resolving Gamma integration incidents.

Prerequisites

• Access to monitoring dashboards
• Access to application logs
• On-call responsibilities defined
• Communication channels established

Incident Severity Levels

Quick Diagnostics

Step 1: Check Gamma Status

set -euo pipefail
# Check Gamma status page
curl -s https://status.gamma.app/api/v2/status.json | jq '.status'

# Check our integration health
curl -s https://your-app.com/health/gamma | jq '.'

# Quick connectivity test
curl -w "\nTime: %{time_total}s\n" \
  -H "Authorization: Bearer $GAMMA_API_KEY" \
  https://api.gamma.app/v1/ping

Step 2: Review Key Metrics

set -euo pipefail
# Check error rate (Prometheus)
curl -s 'http://prometheus:9090/api/v1/query?query=rate(gamma_requests_total{status=~"5.."}[5m])' | jq '.data.result'  # 9090: Prometheus port

# Check latency P95
curl -s 'http://prometheus:9090/api/v1/query?query=histogram_quantile(0.95,rate(gamma_request_duration_seconds_bucket[5m]))' | jq '.data.result'  # Prometheus port

# Check rate limit
curl -s 'http://prometheus:9090/api/v1/query?query=gamma_rate_limit_remaining' | jq '.data.result'  # Prometheus port

Step 3: Review Recent Logs

# Last 100 error logs
grep -i "gamma.*error" /var/log/app/gamma-*.log 

Gamma Install & Auth

Output

Record the authentication method, minimum scope, secret-manager reference, validation time, owner, and rotation/revocation procedure—never a token, presentation, or viewer record.

Examples

Use a scoped staging credential for a read-only fictional workspace check, record the redacted result, and verify the credential is denied after revocation.

Overview

Configure authentication for the Gamma Generate API v1.0 (GA since Nov 2025). Gamma uses a REST API at https://public-api.gamma.app/v1.0/ — there is no official SDK package. All requests authenticate via the X-API-KEY header.

Prerequisites

• Gamma Pro account or higher (API access requires Pro+)
• Node.js 18+ or Python 3.10+ for wrapper code
• curl or HTTP client library

Instructions

Step 1: Generate API Key

1. Log in at gamma.app
2. Navigate to Settings and Members (dropdown, upper-left)
3. Select the API key tab
4. Click Create API key
5. Copy and securely store the key — it will not be shown again

Step 2: Configure Environment

# Set environment variable (add to .env or shell profile)
export GAMMA_API_KEY="gma_your_api_key_here"

# .env file approach
echo 'GAMMA_API_KEY=gma_your_api_key_here' >> .env

Step 3: Verify Connection

# Quick verification with curl
curl -s -o /dev/null -w "%{http_code}" \
  -H "X-API-KEY: ${GAMMA_API_KEY}" \
  https://public-api.gamma.app/v1.0/themes
# 200 = authenticated, 401 = invalid key

Step 4: First API Call (Node.js)

// gamma-client.ts — thin wrapper around the REST API
const GAMMA_BASE = "https://public-api.gamma.app/v1.0";

interface GammaConfig {
  apiKey: string;
  baseUrl?: string;
}

export function createGammaClient(config: GammaConfig) {
  const headers = {
    "X-API-KEY": config.apiKey,
    "Content-Type": "application/json",
  };
  const base = config.baseUrl ?? GAMMA_BASE;

  return {
    async listThemes() {
      const res = await fetch(`${base}/themes`, { headers });
      if (!res.ok) throw new Error(`Gamma API ${res.status}: ${await res.text()}`);
      return res.json();
    },
    async listFolders() {
      const res = await fetch(`${base}/folders`, { headers });
      if (!res.ok) throw new Error(`Gamma API ${res.status}: ${await res.text()}`);
      return res.json();
    },
  };
}

// Verify connection
const gamma = createGammaClient({ apiKey: process.env.GAMMA_API_KEY! });
const themes = await gamma.listThemes();
console.log(`Connected — ${themes.length} workspace themes available`);

Step 5:

Gamma Migration Deep Dive

Output

Record source/target scope, mapping decision, staging and canary results, aggregate reconciliation, approver, and rollback state without copying content or viewer data.

Examples

Migrate a fictional presentation in staging, compare approved metadata and route behavior, introduce an unknown field, and confirm the canary stops for review.

Current State

!npm list 2>/dev/null | head -10

Overview

Migrate presentation workflows from PowerPoint, Google Slides, Canva, or other platforms to Gamma's AI-powered generation. Gamma takes a fundamentally different approach -- instead of manually placing slides, you provide content and Gamma generates the presentation. Migration is about converting your content pipeline, not your slide files.

Prerequisites

• Gamma API access (Pro+ plan)
• Source presentations accessible for content extraction
• Node.js 18+ for migration scripts
• Completed gamma-install-auth setup

Migration Approaches

Key insight: You don't "import" slides into Gamma. You extract content from old presentations and regenerate them using Gamma's AI. This often produces better results than the originals.

Instructions

Step 1: Inventory Source Presentations

// scripts/inventory-presentations.ts
import { readdir, stat } from "node:fs/promises";
import { join, extname } from "node:path";

interface PresentationInfo {
  path: string;
  format: string;
  sizeMB: number;
  lastModified: Date;
}

async function inventoryPresentations(dir: string): Promise<PresentationInfo[]> {
  const entries = await readdir(dir, { recursive: true });
  const presentations: PresentationInfo[] = [];

  for (const entry of entries) {
    const ext = extname(entry).toLowerCase();
    if ([".pptx", ".ppt", ".key", ".pdf", ".md"].includes(ext)) {
      const fullPath = join(dir, entry);
      const info = await stat(fullPath);
      presentations.push({
        path: fullPath,
        format: ext,
        sizeMB: info.size / (1024 * 1024),
        lastModified: info.mtime,
      });
    }
  }

  console.log(`Found ${presentations.length} presentations:`);
  const byFormat = presentations.reduce((acc, p) => {
    acc[p.for

Gamma Multi-Environment Setup

Output

Record environment identity references, approved destinations, policy version, validation result, owner, and rollback path. Do not include credentials or content.

Examples

Use a fictional staging deck to prove the development credential cannot publish to production, rotate the staging credential, and retain only redacted control evidence.

Overview

Configure Gamma API access across development, staging, and production environments. Since Gamma is a SaaS API with no self-hosted option, environment separation is achieved through separate workspaces (API keys), mock servers for development, and environment-aware client configuration.

Prerequisites

• Separate Gamma workspaces (or at minimum separate API keys) per environment
• Secret management solution
• Completed gamma-install-auth setup

Environment Architecture

┌─────────────────────────────────────────────────────────┐
│  Development                                             │
│  API: localhost:9876 (mock server) or Gamma API          │
│  Key: GAMMA_API_KEY=gma_dev_xxx                         │
│  Mock: enabled (no credits consumed)                     │
├─────────────────────────────────────────────────────────┤
│  Staging                                                 │
│  API: public-api.gamma.app (separate workspace)         │
│  Key: GAMMA_API_KEY=gma_stg_xxx                         │
│  Mock: disabled                                          │
├─────────────────────────────────────────────────────────┤
│  Production                                              │
│  API: public-api.gamma.app (production workspace)       │
│  Key: GAMMA_API_KEY=gma_prod_xxx (from secret manager)  │
│  Mock: disabled                                          │
└─────────────────────────────────────────────────────────┘

Instructions

Step 1: Environment Configuration

// src/config/gamma.ts
interface GammaEnvConfig {
  apiKey: string;
  baseUrl: string;
  useMock: boolean;
  timeoutMs: number;
  maxRetries: number;
}

function getGammaConfig(): GammaEnvConfig {
  const env = process.env.NODE_ENV ?? "development";

  const configs: Record<string, Partial<GammaEnvConfig>> = {
    development: {
      baseUrl: process.env.GAMMA_MOCK === "true"
        ? "http://localhost:9876/v1.0"
        : "https://public-api.gamma.app/v1.0",
      useMock: process.env.GAMMA_MOCK === "true",
      timeoutMs: 60000,
      maxRetries: 1,
    },
    staging: {
      baseUrl: "https://public-api.gamma.app/v1.0",
      useMock: false,
      timeoutMs: 30000,
      maxRetries: 3,
    },
    production: {
      baseUrl: "https://public-api.gamma.app/v1.0",
      useMock: false,
      timeoutMs: 30000,
      maxRetries: 5,
 

Gamma Observability

Output

Publish a monitoring receipt with metric definitions, alert/dashboards, threshold test, owner, and review date. Logs and alerts must exclude private content, viewer identities, and tokens.

Examples

Send a fictional event through staging, confirm dashboards show only aggregate outcomes and an opaque ID, and trigger a controlled alert with no presentation content in the payload.

Overview

Implement monitoring, logging, and health checks for Gamma API integrations. Since Gamma does not expose rate limit headers or internal metrics, observability is built around your API call patterns, latency, error rates, credit consumption, and generation success rates.

Prerequisites

• Working Gamma integration (see gamma-sdk-patterns)
• Monitoring stack (Prometheus/Grafana, Datadog, or CloudWatch)
• Logging infrastructure

Instructions

Step 1: Instrumented Client

// src/observability/gamma-metrics.ts
interface GammaMetrics {
  requests: number;
  errors: number;
  generations: number;
  completions: number;
  failures: number;
  totalCredits: number;
  totalLatencyMs: number;
  errorsByStatus: Record<number, number>;
}

const metrics: GammaMetrics = {
  requests: 0, errors: 0,
  generations: 0, completions: 0, failures: 0,
  totalCredits: 0, totalLatencyMs: 0,
  errorsByStatus: {},
};

export function createInstrumentedClient(apiKey: string) {
  const base = "https://public-api.gamma.app/v1.0";
  const headers = { "X-API-KEY": apiKey, "Content-Type": "application/json" };

  async function instrumentedRequest(method: string, path: string, body?: unknown) {
    metrics.requests++;
    const start = Date.now();

    try {
      const res = await fetch(`${base}${path}`, {
        method, headers,
        body: body ? JSON.stringify(body) : undefined,
      });
      metrics.totalLatencyMs += Date.now() - start;

      if (!res.ok) {
        metrics.errors++;
        metrics.errorsByStatus[res.status] = (metrics.errorsByStatus[res.status] || 0) + 1;
        throw new Error(`Gamma ${res.status}: ${await res.text()}`);
      }
      return res.json();
    } catch (err) {
      if (!metrics.errorsByStatus[0]) metrics.errorsByStatus[0] = 0;
      metrics.totalLatencyMs += Date.now() - start;
      throw err;
    }
  }

  return {
    generate: async (body: any) => {
      metrics.generations++;
      return instrumentedRequest("POST", "/generations", body);
    },
    poll: (id: string) => instrumentedRequest("GET", `/generations/${id}`),
    listThemes: () => instrumentedRequest("GET", "/themes"),
    listFolders: () => instrumentedRequest("GET", "/folders"),

    // Record completion metrics
    recordCompletion: (creditsUsed: number) => {
      metrics.c

Gamma Performance Tuning

Output

Publish a tuning receipt with baseline/post-change aggregate metrics, change owner, canary result, and rollback state. Do not include source content, viewer data, or tokens.

Examples

Optimize a fictional staging deck, compare aggregate load/render metrics, and roll back if a synthetic sharing or accessibility check regresses.

Overview

Optimize Gamma API integration performance. Gamma's generate-poll-retrieve pattern means most latency is in generation time (10-60s), not API call overhead. Optimize by: reducing poll overhead, parallelizing batch operations, caching results, and choosing the right generation parameters.

Prerequisites

• Working Gamma integration (see gamma-sdk-patterns)
• Understanding of async patterns
• Redis or in-memory cache (recommended)

Performance Characteristics

Instructions

Step 1: Optimize Poll Strategy

// src/gamma/smart-poll.ts
// Adaptive polling: start fast, slow down over time

export async function smartPoll(
  gamma: GammaClient,
  generationId: string,
  opts = { maxTimeMs: 180000 }
): Promise<GenerateResult> {
  const deadline = Date.now() + opts.maxTimeMs;
  let interval = 2000; // Start at 2s

  while (Date.now() < deadline) {
    const result = await gamma.poll(generationId);

    if (result.status === "completed") return result;
    if (result.status === "failed") throw new Error("Generation failed");

    // Adaptive backoff: poll faster early, slower later
    await new Promise((r) => setTimeout(r, interval));
    interval = Math.min(interval * 1.5, 10000); // Max 10s between polls
  }

  throw new Error(`Poll timeout after ${opts.maxTimeMs}ms`);
}

Step 2: Cache Static Data

// src/gamma/cache.ts
import NodeCache from "node-cache";

const cache = new NodeCache({ stdTTL: 3600 }); // 1 hour for static data

export async function getCachedThemes(gamma: GammaClient) {
  const key = "gamma:themes";
  const cached = cache.get(key);
  if (cached) return cached;

  const themes = await gamma.listThemes();
  cache.set(key, themes);
  return themes;
}

export async function getCachedFolders(gamma: Gamm

Gamma Production Checklist

Instructions

Attach evidence or an owner decision to each control, run a fictional-content canary, verify publishing/visibility/privacy and rollback behavior, and stop promotion on an access, destination, or health failure.

Output

Create a go-live receipt with completed controls, aggregate canary results, approver, exceptions, rollback owner, and follow-up date. Exclude private content, viewer data, and credentials.

Error Handling

Pause publishing and integrations on policy failures, restore the prior configuration, and keep only redacted incident evidence.

Examples

Publish a fictional staging deck, revoke a test viewer, and simulate a failed integration. Promote only after the owner records that access and rollback worked correctly.

Overview

Comprehensive checklist to ensure your Gamma integration is production-ready.

Prerequisites

• Completed development and testing
• Staging environment validated
• Monitoring infrastructure ready

Production Checklist

1. Authentication & Security

• [ ] Production API key obtained (not development key)
• [ ] API key stored in secret manager (not env file)
• [ ] Key rotation procedure documented and tested
• [ ] Minimum required scopes configured
• [ ] No secrets in source code or logs

// Production client configuration
const gamma = new GammaClient({
  apiKey: await secretManager.getSecret('GAMMA_API_KEY'),
  timeout: 30000,  # 30000: 30 seconds in ms
  retries: 3,
});

2. Error Handling

• [ ] All API calls wrapped in try/catch
• [ ] Exponential backoff for rate limits
• [ ] Graceful degradation for API outages
• [ ] User-friendly error messages
• [ ] Error tracking integration (Sentry, etc.)

import * as Sentry from '@sentry/node';

try {
  await gamma.presentations.create({ ... });
} catch (err) {
  Sentry.captureException(err, {
    tags: { service: 'gamma', operation: 'create' },
  });
  throw new UserError('Unable to create presentation. Please try again.');
}

3. Performance

• [ ] Client instance reused (singleton pattern)
• [ ] Connection pooling enabled
• [ ] Appropriate timeouts configured
• [ ] Response caching where applicable
• [ ] Async operations for long tasks

4. Monitoring & Logging

• [ ] Request/response logging (sanitized)
• [ ] Latency metrics collection
• [ ] Error rate alerting
• [ ] Rate limit monitoring
• [ ] Health check endpoint

// Health check
app.get('/health/gamma', async (req, res) => {
  try {
    await gamma.ping();
 

Gamma Rate Limits

Examples

Simulate a throttled request against a fictional staging presentation, honor a bounded retry under an opaque operation ID, and move repeated failures to review instead of replaying publishing actions.

Overview

Understand Gamma API rate limits and implement effective strategies for high-volume usage.

Prerequisites

• Active Gamma API integration
• Understanding of HTTP headers
• Basic queuing concepts

Rate Limit Tiers

Instructions

Step 1: Check Rate Limit Headers

const response = await gamma.presentations.list();

// Rate limit headers
const headers = response.headers;
console.log('Limit:', headers['x-ratelimit-limit']);
console.log('Remaining:', headers['x-ratelimit-remaining']);
console.log('Reset:', new Date(headers['x-ratelimit-reset'] * 1000));  # 1000: 1 second in ms

Step 2: Implement Exponential Backoff

async function withBackoff<T>(
  fn: () => Promise<T>,
  options = { maxRetries: 5, baseDelay: 1000 }  # 1000: 1 second in ms
): Promise<T> {
  for (let attempt = 0; attempt < options.maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status !== 429 || attempt === options.maxRetries - 1) {  # HTTP 429 Too Many Requests
        throw err;
      }

      const delay = err.retryAfter
        ? err.retryAfter * 1000  # 1 second in ms
        : options.baseDelay * Math.pow(2, attempt);

      console.log(`Rate limited. Retrying in ${delay}ms...`);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Max retries exceeded');
}

// Usage
const result = await withBackoff(() =>
  gamma.presentations.create({ title: 'My Deck', prompt: 'AI overview' })
);

Step 3: Request Queue

class RateLimitedQueue {
  private queue: Array<() => Promise<any>> = [];
  private processing = false;
  private requestsPerMinute: number;
  private interval: number;

  constructor(requestsPerMinute = 60) {
    this.requestsPerMinute = requestsPerMinute;
    this.interval = 60000 / requestsPerMinute;  # 60000: 1 minute in ms
  }

  async add<T>(fn: () => Promise<T>): Promise<T> {
    return new Promise((resolve, reject) => {
      this.queue.push(async () => {
        try {
          reso

Gamma Reference Architecture

Instructions

Separate content creation, review, publishing, sharing, integrations, and observability by explicit ownership and least privilege. Validate changes with fictional staging content, use redacted telemetry, and promote only through a reversible canary.

Output

Maintain an architecture record with trust boundaries, approved audiences/destinations, access/retention controls, owners, and rollback mechanism. Exclude private content and credentials.

Error Handling

Quarantine unknown destinations, sharing policies, or content schemas; disable unsafe consumers and restore the prior route before replaying work.

Examples

Route a fictional deck through a staging review/publish flow, deny an unapproved viewer, and verify duplicate publish events are suppressed.

Overview

Reference architecture patterns for building scalable, maintainable Gamma integrations.

Prerequisites

• Understanding of microservices
• Familiarity with cloud architecture
• Knowledge of event-driven systems

Architecture Patterns

Pattern 1: Basic Integration

┌─────────────────────────────────────────────────────────┐
│                    Your Application                      │
│  ┌─────────┐    ┌─────────┐    ┌─────────┐             │
│  │   UI    │───▶│   API   │───▶│ Gamma   │             │
│  │         │    │ Server  │    │ Client  │             │
│  └─────────┘    └─────────┘    └────┬────┘             │
│                                      │                   │
└──────────────────────────────────────┼──────────────────┘
                                       │
                                       ▼
                              ┌─────────────────┐
                              │   Gamma API     │
                              └─────────────────┘

Use Case: Simple applications, prototypes, small teams.

Pattern 2: Service Layer Architecture

set -euo pipefail
┌────────────────────────────────────────────────────────────────┐
│                         Your Platform                           │
│                                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
│  │  Web App │  │Mobile App│  │   CLI    │  │   API    │        │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘        │
│       │             │             │             │                │
│       └─────────────┴──────┬──────┴─────────────┘                │
│                            ▼                                     │
│                  ┌──────────────────┐                           │
│                  │ Presentation     │                           │
│                  │    Service       │                           │
│                  └────────┬─────────┘                           │
│      

Gamma API Patterns

Output

Produce a client-validation receipt with contract/fixture version, opaque operation ID, schema result, idempotency outcome, owner, and redacted failure reference. Do not log presentation content or tokens.

Examples

Use a scoped staging integration and fictional document to validate field allowlists and duplicate suppression. Reject an unknown destination before the provider call and retain only aggregate results.

Overview

Gamma has no published SDK — all interaction is via REST at https://public-api.gamma.app/v1.0/. This skill provides production-grade patterns for typed clients, generation helpers, polling, template workflows, and error handling.

Prerequisites

• Completed gamma-install-auth setup
• TypeScript project with fetch (Node.js 18+)
• Understanding of the generate-poll-retrieve workflow

Instructions

Step 1: Typed Client Singleton

// lib/gamma.ts
const GAMMA_BASE = "https://public-api.gamma.app/v1.0";

interface GammaConfig {
  apiKey: string;
  baseUrl?: string;
  timeoutMs?: number;
}

// Types based on actual API responses
interface GenerateRequest {
  content: string;
  outputFormat?: "presentation" | "document" | "webpage" | "social_post";
  themeId?: string;
  exportAs?: "pdf" | "pptx" | "png";
  textMode?: "generate" | "condense" | "preserve";
  textAmount?: "brief" | "medium" | "detailed" | "extensive";
  imageOptions?: { style?: string };
  sharingOptions?: {
    workspaceAccess?: "noAccess" | "view" | "comment" | "edit" | "fullAccess";
    externalAccess?: "noAccess" | "view" | "comment" | "edit" | "fullAccess";
  };
  folderIds?: string[];
}

interface GenerateResult {
  generationId: string;
  status: "in_progress" | "completed" | "failed";
  gammaUrl?: string;
  exportUrl?: string;
  creditsUsed?: number;
}

let instance: ReturnType<typeof createGammaClient> | null = null;

export function getGamma() {
  if (!instance) {
    instance = createGammaClient({
      apiKey: process.env.GAMMA_API_KEY!,
    });
  }
  return instance;
}

export function createGammaClient(config: GammaConfig) {
  const base = config.baseUrl ?? GAMMA_BASE;
  const headers: Record<string, string> = {
    "X-API-KEY": config.apiKey,
    "Content-Type": "application/json",
  };

  async function request<T>(method: string, path: string, body?: unknown): Promise<T> {
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), config.timeoutMs ?? 30000);
    try {
      co

Gamma Security Basics

Output

Maintain a security receipt with identity scope, secret reference, access-review date, control result, owner, and redacted incident state. Do not include tokens or private content.

Examples

Use a scoped staging credential and fictional deck to verify least-privilege access, revoke it, and confirm access is denied without exposing content or credentials in evidence.

Overview

Security best practices for Gamma API integration to protect credentials and data.

Prerequisites

• Active Gamma integration
• Environment variable support
• Understanding of secret management

Instructions

Step 1: Secure API Key Storage

// NEVER do this
const gamma = new GammaClient({
  apiKey: 'gamma_live_abc123...', // Hardcoded - BAD!
});

// DO this instead
const gamma = new GammaClient({
  apiKey: process.env.GAMMA_API_KEY,
});

Environment Setup:

# .env (add to .gitignore!)
GAMMA_API_KEY=gamma_live_abc123...

# Load in application
import 'dotenv/config';

Step 2: Key Rotation Strategy

// Support multiple keys for rotation
const gamma = new GammaClient({
  apiKey: process.env.GAMMA_API_KEY_PRIMARY
    || process.env.GAMMA_API_KEY_SECONDARY,
});

// Rotation script
async function rotateApiKey() {
  // 1. Generate new key in Gamma dashboard
  // 2. Update GAMMA_API_KEY_SECONDARY
  // 3. Deploy and verify
  // 4. Swap PRIMARY and SECONDARY
  // 5. Revoke old key
}

Step 3: Request Signing (if supported)

import crypto from 'crypto';

function signRequest(payload: object, secret: string): string {
  const timestamp = Date.now().toString();
  const message = timestamp + JSON.stringify(payload);

  return crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');
}

// Usage with webhook verification
function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Step 4: Access Control Patterns

// Scoped API keys (if supported)
const readOnlyGamma = new GammaClient({
  apiKey: process.env.GAMMA_API_KEY_READONLY,
  scopes: ['presentations:read', 'exports:read'],
});

const fullAccessGamma = new GammaClient({
  apiKey: process.env.GAMMA_API_KEY_FULL,
});

// Permission check before operations
async function createPresentation(user: User, data: object) {
  if (!user.permissions.includes('gamma:create')) {
    throw new Error('Insufficient permissions');
  

Gamma Upgrade & Migration

Output

Maintain an upgrade receipt with versions reviewed, affected integrations, compatibility/canary outcome, owner approval, and rollback state. Exclude content, viewer data, and credentials.

Error Handling

Stop promotion on schema, publishing, sharing, access, or destination mismatches; restore the prior configuration and quarantine opaque failures for review.

Examples

Test an upgrade with a fictional staging deck, verify a protected sharing setting remains intact, and roll back on a synthetic integration failure.

Current State

!npm list 2>/dev/null | head -20 !pip freeze 2>/dev/null | head -20

Overview

Guide for upgrading Gamma SDK versions and migrating between API versions safely.

Prerequisites

• Existing Gamma integration
• Version control (git)
• Test environment available

Instructions

Step 1: Check Current Version

set -euo pipefail
# Node.js
npm list @gamma/sdk

# Python
pip show gamma-sdk

# Check for available updates
npm outdated @gamma/sdk

Step 2: Review Changelog

set -euo pipefail
# View changelog
npm info @gamma/sdk changelog

# Or visit
# https://gamma.app/docs/changelog

Step 3: Upgrade SDK

set -euo pipefail
# Create upgrade branch
git checkout -b feat/gamma-sdk-upgrade

# Node.js - upgrade to latest
npm install @gamma/sdk@latest

# Python - upgrade to latest
pip install --upgrade gamma-sdk

# Or specific version
npm install @gamma/sdk@2.0.0

Step 4: Handle Breaking Changes

Common Migration Patterns:

// v1.x -> v2.x: Client initialization change
// Before (v1)
import Gamma from '@gamma/sdk';
const gamma = new Gamma(apiKey);

// After (v2)
import { GammaClient } from '@gamma/sdk';
const gamma = new GammaClient({ apiKey });

// v1.x -> v2.x: Response format change
// Before (v1)
const result = await gamma.createPresentation({ title: 'Test' });
console.log(result.id);

// After (v2)
const result = await gamma.presentations.create({ title: 'Test' });
console.log(result.data.id);

// v1.x -> v2.x: Error handling change
// Before (v1)
try {
  await gamma.create({ ... });
} catch (e) {
  if (e.code === 'RATE_LIMIT') { ... }
}

// After (v2)
import { RateLimitError } from '@gamma/sdk';
try {
  await gamma.presentations.create({ ... });
} catch (e) {
  if (e instanceof RateLimitError) { ... }
}

Step 5: Update Type Definitions

// Check for type changes
// tsconfig.json - ensure strict mode catches issues
{
  "co

Gamma Webhooks & Events

Output

Return opaque event ID, validation outcome, idempotency result, destination status, and redacted error category. Keep event payloads and credentials out of logs.

Examples

Deliver a fictional event twice, process the first once, record the second as duplicate, and reject an unknown destination before content is forwarded.

Overview

Gamma's public API (v1.0) is generation-focused and does not expose a traditional webhook system at time of writing. Instead, use the poll-based pattern (GET /v1.0/generations/{id}) to detect completion. For event-driven architectures, wrap polling in a background worker that emits application-level events when generations complete or fail.

Prerequisites

• Completed gamma-sdk-patterns setup
• Event bus or message queue (Bull, RabbitMQ, or EventEmitter)
• Understanding of the generate-poll-retrieve pattern

Gamma Event Model (Application-Level)

Since Gamma does not push events, you create them by polling:

Instructions

Step 1: Event Emitter Pattern

// src/gamma/events.ts
import { EventEmitter } from "events";
import { createGammaClient } from "./client";

export const gammaEvents = new EventEmitter();

export interface GenerationEvent {
  generationId: string;
  status: "started" | "completed" | "failed" | "timeout";
  gammaUrl?: string;
  exportUrl?: string;
  creditsUsed?: number;
  error?: string;
}

export async function generateWithEvents(
  content: string,
  options: { outputFormat?: string; exportAs?: string; themeId?: string } = {}
): Promise<GenerationEvent> {
  const gamma = createGammaClient({ apiKey: process.env.GAMMA_API_KEY! });

  // Start generation
  const { generationId } = await gamma.generate({
    content,
    outputFormat: options.outputFormat ?? "presentation",
    exportAs: options.exportAs,
    themeId: options.themeId,
  });

  gammaEvents.emit("generation", {
    generationId,
    status: "started",
  } as GenerationEvent);

  // Poll for completion
  const deadline = Date.now(