How to drive the Portainer REST API correctly from curl or any plain-HTTP client using an API token — authentication with X-API-Key, the undocumented Docker/Kubernetes proxy surface, resolving environment IDs, deploying and managing stacks, keeping huge responses out of context with jq, and reading results correctly (edge agent health comes from check-in time, not Status). Use this whenever the task involves calling Portainer over HTTP — curl commands, bash/Python/Ansible automation, generated scripts, webhooks, or debugging a failing Portainer API call — even if the user doesn't say "Portainer API" explicitly. Do NOT use it when Portainer MCP tools (mcp__portainer__*) are available in the session — prefer those tools instead.
2026-06-15