How to use approvals from the API or an agent

Approvals reach your code in two ways. Every API client and agent meets them when a render is blocked, on any plan with approval flows. The Approvals API goes further and lets your code add, move and approve templates.

Handle a blocked render#

When a template's flow needs approval for automation, a render from the REST API, an SDK, n8n, Make, Zapier or the Orshot MCP server is refused with a 403 until the template is approved:

{
  "error": "This template is waiting for approval in 'Brand and legal' and can't be rendered through the API yet.",
  "code": "template_not_approved",
  "message": "This template is waiting for approval in 'Brand and legal' and can't be rendered through the API yet.",
  "blockers": [
    {
      "flow": { "slug": "brand-and-legal", "name": "Brand and legal" },
      "stage": { "slug": "brand-review", "name": "Brand review", "category": "review" },
      "reason": "not_in_render_stage",
      "waitingOn": ["Priya Shah"],
      "renderStage": { "slug": "approved-for-automation", "name": "Automation approved" }
    }
  ],
  "helpUrl": "https://orshot.com/docs/error-reference#template-not-approved"
}

1. Branch on code: template_not_approved, output_not_approved, edited_since_approval or condition_violated.
2. Show message as it is. It's written for people, and names the flow and the stage.
3. Send the render again once it's approved. Nothing was rendered or queued, and no credits were used.

Every code is explained in Approval errors.

AI agents#

An agent connected through the Orshot MCP server acts as the person who connected it, with their access. When it renders a template that's waiting for approval, it gets the message above and can tell you the stage and who can approve it. When it tries to change a template in a locked stage, it gets stage_locked.

The Approvals API#

It does what the Approvals page does, from your own code. A typical automation adds new templates to a flow, submits them for review, and checks they're approved before it renders.

const headers = { Authorization: "Bearer <ORSHOT_API_KEY>" };

const { status } = await fetch(
  "https://api.orshot.com/v1/studio/templates/101/approval",
  { headers },
).then((r) => r.json());

if (status.canRender.image) {
  await fetch("https://api.orshot.com/v1/studio/render", {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({
      templateId: 101,
      modifications: { headline: "Summer sale" },
      response: { type: "url", format: "png" },
    }),
  });
} else {
  console.log(status.blockers[0]); // which stage, and who it waits on
}

An API key acts as the workspace, so its moves show in the activity history "via API". An OAuth token acts as the person who connected your app, with their own access in each flow.

To act for one person on your team with an API key, send their user id in the X-Orshot-User-Id header. The call then needs both the key's access and theirs, their own inbox and notifications answer, and changes read as "Priya Shah, via API key". Approving always comes from the person. See acting for a team member.

Common problems#

Related#