RUNBOOK

• Agent-skill standard entrypoint is SKILL.md.
• This runbook is an operational convention (recommended), not a required skill file.
• SKILL.md is also a navigation convention for larger skill docs.

1) Confirm Auth Flow and Endpoint

• Choose matching OAuth flow for use case (S2S/User/PKCE/Device).
• Use token URL https://zoom.us/oauth/token.

Wrong flow or token endpoint causes immediate auth failures.

2) Confirm Scope and Account Context

• Verify token contains required scopes.
• For admin/account-level operations, verify app/account permissions.
• Re-authorize after scope changes.

3) Confirm ID Semantics

• Distinguish Meeting ID vs Meeting UUID.
• Apply required URL encoding (double-encoding for UUID where needed).

ID Sanity Rules

• Use numeric Meeting ID for many standard meeting operations.
• Use Meeting UUID for some past-instance/recording/report operations.
• If endpoint docs mention UUID and your value contains / or +, encode carefully.

If a resource “exists” in UI but API returns not found, ID type/encoding mismatch is a top cause.

4) Confirm Pagination and Rate Limits

• Handle next_page_token where applicable.
• Implement retry/backoff on 429 and transient 5xx.

Minimal Retry Policy

• 429 or 5xx: exponential backoff with jitter.
• Respect retry headers when provided.
• Put high-volume endpoints behind queue/batch workers.

5) Confirm Webhook-Driven Workflows

• If pipeline is event-driven, validate webhook signatures and retry behavior.
• Respond quickly and process asynchronously.

6) Quick Probes

• GET /v2/users/me succeeds with current token.
• Representative endpoint (e.g., list meetings) returns expected schema.
• Error payload includes actionable code/details (not HTML response).

Copy/Paste Validation Commands

Expected: JSON responses with HTTP 200 (or clear JSON error codes), not HTML error pages.

7) Fast Decision Tree

• 401/invalid token -> wrong flow, expired token, or scope mismatch.
• 404-like behavior -> wrong endpoint path/version or wrong resource ID.
• 429 spikes -> missing backoff/queue strategy.

8) Common Integration Mixups

• REST join_url is a browser link, not a Meeting SDK join payload.
• REST API creates/manages Zoom resources; Meeting SDK and Video SDK are separate integration surfaces.
• If auth works but operation fails, check scope and resource ownership before endpoint debugging.