Orshot

https://orshot.com/docs
Admin
Orshot is an image and PDF generation API that lets you create dynamic visuals programmatically from...
Tokens:564,980
Snippets:3,759
Trust Score:7.7
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install @orshot/embed-react with npm, pnpm, or yarn

Source: https://orshot.com/docs/orshot-embed/react-sdk

Install the React SDK package using your preferred package manager. The example shows npm, pnpm, and yarn alternatives.

```bash
npm install @orshot/embed-react
# or
pnpm add @orshot/embed-react
# or
yarn add @orshot/embed-react
```

--------------------------------

### Get Studio Template - Response

Source: https://orshot.com/docs/api-reference/studio-template-get

Example JSON response returned by the Get Studio Template endpoint.

```json
{
  "id": 123,
  "created_at": "2025-09-10T15:30:45.123Z",
  "workspace_id": "workspace-uuid-456",
  "user_id": "user-uuid-789",
  "canvas_width": 1200,
  "canvas_height": 630,
  "updated_at": "2025-10-15T10:20:30.456Z",
  "name": "Social Media Post",
  "description": "Template for social media posts",
  "tags": ["social", "media"]
}
```

--------------------------------

### Response example

Source: https://orshot.com/docs/api-reference/approvals-preferences-get

Example JSON response showing empty preferences and null timezone.

```json
{
  "preferences": [],
  "timezone": null
}
```

--------------------------------

### Installation

Source: https://orshot.com/docs/sdks/php

Install the Orshot PHP SDK using Composer.

```APIDOC
## Installation

### Description
Install the Orshot PHP SDK using Composer.

### Command
```bash
composer require rishimohan/orshot
```
```

--------------------------------

### Multi-page .prompt example

Source: https://orshot.com/docs/dynamic-parameters/prompt

Example of using the .prompt parameter with page-specific syntax (pageN@parameterID.prompt) for multi-page templates.

```json
{
  "modifications": {
    "page1@title.prompt": "Write a title about morning routines",
    "page2@title.prompt": "Write a title about evening habits",
    "page1@body.prompt": "Write 3 tips for productive mornings",
    "page2@body.prompt": "Write 3 tips for better sleep"
  }
}
```

--------------------------------

### Install Orshot SDK with pip

Source: https://orshot.com/docs/sdks/python

Install the Orshot Python SDK via pip.

```bash
pip install orshot
```

--------------------------------

### GET /v1/approval-flows

Source: https://orshot.com/docs/api-reference/approvals-flows-list

Lists the workspace's approval flows (for example Brand, Legal) in sidebar order, without stages. Start here to find a flow's slug before working with its stages or templates.

```APIDOC
## [GET] /v1/approval-flows

### Description
Lists the workspace's approval flows (for example Brand, Legal) in sidebar order, without stages. Start here to find a flow's slug before working with its stages or templates.

### Method
GET

### Endpoint
https://api.orshot.com/v1/approval-flows

### Parameters
#### Query Parameters
- **includeArchived** (Boolean) - Optional - Include archived approval flows. Default `false`.

#### Headers
- **Authorization** (string) - Required - `Bearer <API key or OAuth token>`
- **x-workspace-id** (string) - Optional - OAuth tokens with several workspaces: the workspace to act in. API keys ignore it.
- **X-Orshot-User-Id** (string) - Optional - API keys only: the user id of the owner, admin or member this call is for. See Acting for a Team Member below.
- **X-Session-Id** (string) - Optional - Groups the calls of one agent or MCP session in the activity history.

### Response
#### Success Response (200)
- **flows** (array) - List of approval flows in sidebar order.
- **flow.slug** (string) - Unique identifier for the flow.
- **flow.name** (string) - Display name of the flow.
- **flow.overPlanLimit** (boolean) - Indicates if the flow is past the plan's limit.

#### Response Example
{
  "flows": [
    {
      "slug": "brand",
      "name": "Brand",
      "overPlanLimit": false
    },
    {
      "slug": "legal",
      "name": "Legal",
      "overPlanLimit": false
    }
  ]
}
```

--------------------------------

### Create Next.js project and install dependencies

Source: https://orshot.com/docs/examples/instant-polaroid-app

Initializes a new Next.js project named instant-polaroid and installs the required packages: framer-motion, lucide-react, jszip, clsx, and tailwind-merge.

```bash
npx create-next-app@latest instant-polaroid
cd instant-polaroid
```

```bash
npm install framer-motion lucide-react jszip clsx tailwind-merge
```

--------------------------------

### Basic Workflow: Authenticate, List Templates, and Generate

Source: https://orshot.com/docs/integrations/orshot-cli

Shows the core Orshot CLI workflow: authenticate with an API key, list available library templates, and generate a website screenshot with a modification and custom output filename.

```bash
# Authenticate
orshot auth login your-api-key

# List available templates
orshot templates library

# Generate with modifications
orshot generate library website-screenshot \
  -m websiteUrl="https://github.com" \
  -o github-screenshot.png
```

--------------------------------

### Response: Template Versions

Source: https://orshot.com/docs/api-reference/template-versions-list

Example JSON response showing the version timeline, including plan restore limits, current version info, and a list of versions with metadata.

```json
{
  "template_id": 12345,
  "total": 6,
  "named": 1,
  "hidden": 0,
  "plan": { "restore": true, "visible": 15, "restorable": 12, "named": 6 },
  "current": {
    "updated_at": "2026-09-15T10:37:45.459+00:00",
    "current_version": "95b4cf5f-0adb-4f13-a89f-703a3065fad7",
    "page_count": 3,
    "previews": ["https://storage.orshot.com/.../p1.png", "", ""]
  },
  "versions": [
    {
      "id": 51,
      "number": null,
      "kind": "checkpoint",
      "source": "studio",
      "actor_type": "user",
      "actor_id": "fc68…",
      "label": null,
      "protected": false,
      "ref_version_id": null,
      "row_updated_at": "2026-09-15T10:19:42.403+00:00",
      "page_count": 3,
      "previews": ["https://storage.orshot.com/.../p1.png", "", ""],
      "meta": { "summary": { "text": 1, "media": 0, "changed_pages": [{ "index": 0, "id": "p1", "name": "Cover" }] } },
      "restorable": true,
      "created_at": "2026-09-15T10:37:46.589+00:00"
    },
    {
      "id": 48,
      "number": 9,
      "kind": "session",
      "source": "studio",
      "label": null,
      "protected": false,
      "restorable": true,
      "row_updated_at": "2026-09-15T10:37:45.459+00:00",
      "created_at": "2026-09-15T11:08:41.120+00:00"
    },
    {
      "id": 10,
      "number": 7,
      "kind": "named",
      "source": "agent:claude",
      "label": "Approved for launch",
      "protected": true,
      "restorable": true
    },
    {
      "id": 7,
      "number": 4,
      "kind": "restored",
      "source": "restore",
      "ref_version_id": 3,
      "restorable": false
    }
  ]
}
```

--------------------------------

### GET /social/accounts

Source: https://orshot.com/docs/api-reference/social-accounts-list

Documentation for the GET /social/accounts endpoint, including request examples, response fields, error codes, and rate limits.

```APIDOC
## GET /social/accounts

### Description
Retrieves all connected social media accounts for the workspace. Use this to find account IDs for publishing operations.

### Method
GET

### Endpoint
https://api.orshot.com/v1/social/accounts

### Parameters
#### Query Parameters
- **include_health** (boolean) - Optional - When set to `true`, includes the `requires_reconnect` field to indicate if any accounts need reconnection.

### Request Example
```js
await fetch("https://api.orshot.com/v1/social/accounts", {
  method: "GET",
  headers: {
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
});
```

### With Account Health
```js
await fetch("https://api.orshot.com/v1/social/accounts?include_health=true", {
  method: "GET",
  headers: {
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
});
```

### Response
#### Success Response (200)
- **data** (array) - List of connected social accounts.
  - **id** (integer) - Account ID, used in the `publish.accounts` array.
  - **platform** (string) - Platform name (e.g., `twitter`, `instagram`, `linkedin`, `facebook`, `tiktok`, `youtube`, `pinterest`, `reddit`, `bluesky`, `threads`, `telegram`, `snapchat`, `googlebusiness`, `whatsapp`, `discord`).
  - **account_name** (string) - Display name of the account.
  - **account_username** (string) - Username/handle on the platform.
  - **account_avatar** (string) - Avatar image URL.
  - **connected_at** (string) - ISO timestamp when the account was connected.
  - **requires_reconnect** (boolean) - Whether the account needs reconnection (only with `include_health=true`).

#### Response Example
```json
{
  "data": [
    {
      "id": 1,
      "platform": "twitter",
      "account_name": "Acme HQ",
      "account_username": "acmehq",
      "account_avatar": "https://pbs.twimg.com/profile_images/.../avatar.jpg",
      "connected_at": "2026-03-15T10:30:00.000Z"
    },
    {
      "id": 2,
      "platform": "linkedin",
      "account_name": "Acme Inc",
      "account_username": "acme-inc",
      "account_avatar": "https://media.licdn.com/.../avatar.jpg",
      "connected_at": "2026-03-16T14:00:00.000Z"
    }
  ]
}
```

### Error Responses
| Code | Description |
| ---- | ----------- |
| 401  | Invalid or expired API key |
| 403  | Missing Authorization header |
| 429  | Rate limit exceeded |

### Rate Limits
This endpoint is rate limited to **20 requests per minute** per workspace. Rate limit headers are included in every response:

| Header                  | Description              |
| ----------------------- | ------------------------ |
| `X-RateLimit-Limit`     | Maximum requests per minute |
| `X-RateLimit-Remaining` | Remaining requests in the current window |
| `Retry-After`           | Seconds to wait (only on `429` responses) |
```

--------------------------------

### GET /v1/workspace/logs

Source: https://orshot.com/docs/api-reference/workspace-logs

This snippet documents the GET /v1/workspace/logs endpoint, including its query parameters, request example, and response structure with pagination details.

```APIDOC
## [GET] /v1/workspace/logs

### Description
Retrieves a paginated list of workspace logs, including render requests, statuses, response times, and credits used.

### Method
GET

### Endpoint
https://api.orshot.com/v1/workspace/logs

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of logs to return per page. Example: `50`.
- **cursor** (string) - Optional - Opaque cursor for pagination. Pass the `next_cursor` from the previous response to fetch the next page.

### Request Example
```js
await fetch("https://api.orshot.com/v1/workspace/logs?limit=50", {
  method: "GET",
  headers: {
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
});
```

### Response
#### Success Response (200)
- **data** (array) - List of log entries.
  - **id** (integer) - Unique identifier of the log entry.
  - **created_at** (string) - Timestamp when the log was created (ISO 8601).
  - **status** (integer) - HTTP status code of the render request.
  - **source** (string) - Source of the request (e.g., `api`).
  - **template_id** (string) - Identifier of the template used.
  - **template_type** (string) - Type of template (e.g., `library`).
  - **format** (string) - Output format (e.g., `jpg`).
  - **type** (string) - Output type (e.g., `url`).
  - **response_time_ms** (number) - Response time in milliseconds.
  - **response** (object) - Response details.
    - **url** (string) - URL of the rendered output.
    - **totalPages** (integer) - Total number of pages.
    - **renderedPages** (integer) - Number of pages rendered.
  - **credits_used** (integer) - Credits consumed by the request.
  - **is_overage** (boolean) - Whether the request used overage credits.
  - **error** (string|null) - Error message if any, otherwise `null`.
- **pagination** (object) - Pagination metadata.
  - **limit** (integer) - The limit used for the request.
  - **has_more** (boolean) - Whether more logs are available.
  - **next_cursor** (integer|null) - Cursor for the next page, or `null` if no more logs.

#### Response Example
```json
{
  "data": [
    {
      "id": 15384,
      "created_at": "2026-06-29T07:14:02.118Z",
      "status": 200,
      "source": "api",
      "template_id": "tweet-image",
      "template_type": "library",
      "format": "jpg",
      "type": "url",
      "response_time_ms": 8082.03,
      "response": {
        "url": "https://cdn.orshot.com/renders/abc123.jpg",
        "totalPages": 1,
        "renderedPages": 1
      },
      "credits_used": 1,
      "is_overage": false,
      "error": null
    }
  ],
  "pagination": {
    "limit": 50,
    "has_more": true,
    "next_cursor": 15384
  }
}
```
```

--------------------------------

### Complete video parameters example

Source: https://orshot.com/docs/dynamic-parameters/video

Shows all video parameters in one request: background video URL, trim start/end, mute, loop, and text styling. Use as a reference for a complete render request.

```json
{
  "templateId": "your-template-id",
  "modifications": {
    "bgVideo": "https://example.com/product-demo.mp4",
    "bgVideo.trimStart": 0,
    "bgVideo.trimEnd": 10,
    "bgVideo.muted": false,
    "bgVideo.loop": false,
    "title": "Product Launch",
    "title.fontSize": "48px"
  },
  "response": {
    "type": "url",
    "format": "mp4"
  }
}
```

--------------------------------

### Request Example

Source: https://orshot.com/docs/api-reference/social-analytics-accounts

Example GET request to the social analytics accounts endpoint with a `from` query parameter. Requires an ORSHOT API key in the Authorization header.

```js
await fetch(
  "https://api.orshot.com/v1/social/analytics/accounts?from=2026-07-14",
  {
    method: "GET",
    headers: {
      Authorization: "Bearer <ORSHOT_API_KEY>",
    },
  },
);
```

--------------------------------

### List available templates

Source: https://orshot.com/docs/integrations/orshot-cli

Lists library and studio templates available to the authenticated user. The two commands are separate but both are used to discover templates.

```bash
# List library templates
orshot templates library

# List studio templates
orshot templates studio
```

--------------------------------

### Get Workspace - Response

Source: https://orshot.com/docs/api-reference/workspace-get

Example JSON response returned by the Get Workspace endpoint. Contains the workspace object with id, title, slug, url, and created_at fields.

```json
{
  "data": {
    "id": 890,
    "title": "My Workspace",
    "slug": "my-workspace",
    "url": "https://orshot.com/workspace/my-workspace",
    "created_at": "2026-03-27T00:04:45.557267+00:00"
  }
}
```

--------------------------------

### Response for Get Template Version

Source: https://orshot.com/docs/api-reference/template-version-get

Example response for the Get Template Version endpoint. Includes version metadata and, when snapshot=true, the full stored design under the snapshot object.

```json
{
  "version": {
    "id": 57,
    "number": 12,
    "kind": "named",
    "label": "Approved for launch",
    "protected": true,
    "row_updated_at": "2026-09-15T11:31:19.576+00:00",
    "page_count": 3
  },
  "snapshot": {
    "v": 1,
    "name": "Launch banner",
    "description": "",
    "tags": "[\"launch\"]",
    "thumbnail_mode": "auto",
    "canvas_width": 1200,
    "canvas_height": 630,
    "canvas_data": { "width": 1200, "height": 630 },
    "elements_data": [],
    "pages_data": [{ "id": "p1", "name": "Cover", "elements": [ "…" ] }],
    "context": { "folder_id": null, "public_sharing_enabled": false }
  }
}
```

--------------------------------

### Studio Templates: List and Generate

Source: https://orshot.com/docs/integrations/orshot-cli

Studio templates work the same way as library templates. List studio templates and generate from a studio template with multiple modifications.

```bash
# List studio templates
orshot templates studio

# Generate from studio template
orshot generate studio def456 -m name="John Doe" -m title="CEO"
```

--------------------------------

### Detailed prompts for multiple elements

Source: https://orshot.com/docs/dynamic-parameters/prompt

Example of providing detailed prompts for multiple elements to get better results.

```json
{
  "modifications": {
    "description.prompt": "Write a 2-sentence product description for wireless headphones with noise cancellation, emphasizing comfort and battery life",
    "tagline.prompt": "Create a 5-word motivational tagline about productivity"
  }
}
```

--------------------------------

### Product Catalog: JSON modifications example

Source: https://orshot.com/docs/dynamic-parameters/link

Real-world example for a product catalog. Sets image hrefs and product names with their own hrefs for two products, and requests a PDF response.

```json
{
  "modifications": {
    "product1_image.href": "https://shop.com/products/item-1",
    "product1_name": "Wireless Headphones",
    "product1_name.href": "https://shop.com/products/item-1",

    "product2_image.href": "https://shop.com/products/item-2",
    "product2_name": "Smart Watch",
    "product2_name.href": "https://shop.com/products/item-2"
  },
  "response": {
    "format": "pdf"
  }
}
```

--------------------------------

### Get Workflow Response

Source: https://orshot.com/docs/api-reference/workflow-get

Example response for a successful workflow retrieval. Contains the full workflow object with steps, schedule, and run statistics.

```json
{
  "workflow": {
    "id": 44,
    "name": "Renders from new Drive files",
    "description": "Render a card for every new file in the folder",
    "status": "active",
    "trigger_type": "google_drive_new_file",
    "steps": [
      {
        "key": "google_drive_new_file",
        "type": "trigger",
        "config": { "folderId": "<DRIVE_FOLDER_ID>", "pollInterval": 10 }
      },
      {
        "key": "render",
        "type": "action",
        "config": {
          "templateId": "1443",
          "format": "jpg",
          "mapping": { "headline": "name", "hero_image": "image_url" }
        }
      },
      { "key": "orshot_url", "type": "destination", "config": {} }
    ],
    "schedule_config": { "poll": true, "frequency": "custom", "intervalMinutes": 10 },
    "next_run_at": "2026-07-11T09:00:00.000Z",
    "run_count": 128,
    "success_count": 126,
    "last_run_at": "2026-07-11T08:00:03.412Z",
    "last_status": "success",
    "required_connections": ["google_drive"],
    "is_shared": false,
    "share_slug": null,
    "created_at": "2026-06-20T11:24:09.551Z",
    "updated_at": "2026-07-11T08:00:04.101Z"
  }
}
```

--------------------------------

### Expose Local Server with ngrok

Source: https://orshot.com/docs/orshot-embed/webhooks

Commands to install ngrok, expose a local server on port 3000, and obtain an HTTPS URL for webhook settings.

```bash
# Install ngrok
npm install -g ngrok

# Expose your local server
ngrok http 3000

# Use the HTTPS URL in your webhook settings
https://abc123.ngrok.io/api/studio-webhook
```

--------------------------------

### Fetch Workflow with JavaScript

Source: https://orshot.com/docs/api-reference/workflow-get

Example GET request to fetch workflow with ID 44. Requires an Orshot API key in the Authorization header.

```js
await fetch("https://api.orshot.com/v1/workflows/44", {
  method: "GET",
  headers: {
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
});
```

--------------------------------

### POST /v1/studio/templates/create

Source: https://orshot.com/docs/api-reference/enterprise-template-create

Creates a new studio template in your workspace. Use the includeThumbnails query parameter to control thumbnail generation behavior.

```APIDOC
## POST /v1/studio/templates/create

### Description
Creates a new studio template in your workspace. This endpoint allows you to define the template structure, dimensions, and optionally include pre-built pages with elements.

### Method
POST

### Endpoint
https://api.orshot.com/v1/studio/templates/create

### Parameters
#### Query Parameters
- **includeThumbnails** (Boolean) - Optional - Default: `false` - When `true`, the endpoint renders a thumbnail for every page and waits for all uploads before responding. When `false` or absent, thumbnails are generated asynchronously after the response is sent.

### Request Example
(No request body documented in source)

### Response
(No response schema documented in source)

```

--------------------------------

### List Social Posts - Request (JavaScript)

Source: https://orshot.com/docs/api-reference/social-posts-list

Example GET request to list social posts with status filter and limit. Requires an ORSHOT_API_KEY for authorization.

```js
await fetch("https://api.orshot.com/v1/social/posts?status=draft&limit=10", {
  method: "GET",
  headers: {
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
});
```

--------------------------------

### Response example

Source: https://orshot.com/docs/api-reference/brand-colors-get

Example JSON response containing an array of color objects with fields like id, created_at, type, value, tags, workspace_id, and user_id.

```json
{
  "data": [
    {
      "id": 123,
      "created_at": "2025-09-10T15:30:45.123Z",
      "type": "hex",
      "value": "#FF5733",
      "tags": ["primary", "brand"],
      "workspace_id": 50,
      "user_id": "abcdef01-2345-6789-abcd-ef0123456789"
    },
    {
      "id": 124,
      "created_at": "2025-09-10T14:20:30.456Z",
      "type": "gradient",
      "value": "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
      "tags": ["brand"],
      "workspace_id": 50,
      "user_id": "abcdef01-2345-6789-abcd-ef0123456789"
    }
  ]
}
```

--------------------------------

### Render video from Studio template with format and videoOptions

Source: https://orshot.com/docs/api-reference/render-from-studio-template

Use this snippet to render a video from a Studio template. Set response.format to mp4, webm, mov, mkv, or gif. For multi-page video, set videoOptions.combinePages to true to get one combined video (supported for mp4/webm; GIF always returns per-page files). Video renders can take minutes; add mode: "async" to the response object to get a job back immediately.

```javascript
body: JSON.stringify({
  templateId: <TEMPLATE_ID>,
  modifications: {
    promoVideo: "https://example.com/clip.mp4", // a video element's parameter ID
    "promoVideo.trimStart": 0,
    "promoVideo.trimEnd": 10,
  },
  response: { type: "url", format: "mp4" }, // or "webm", "mov", "mkv", "gif"
  videoOptions: { fps: 30, muted: true, combinePages: true, pageTransition: "fade" },
}),
```

--------------------------------

### Fetch Social Analytics for a Post

Source: https://orshot.com/docs/api-reference/social-analytics-post

Example GET request to fetch analytics for post 512. Requires an Orshot API key in the Authorization header.

```js
await fetch("https://api.orshot.com/v1/social/analytics/posts/512", {
  method: "GET",
  headers: {
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
});
```

--------------------------------

### POST /studio/render with response.mode "async"

Source: https://orshot.com/docs/api-reference/async-render-start

The endpoint for starting an async render. It returns immediately with a job instead of holding the connection.

```markdown
POST https://api.orshot.com/v1/studio/render   (with response.mode: "async")
```

--------------------------------

### GET /v1/approvals/inbox with X-Orshot-User-Id header

Source: https://orshot.com/docs/api-reference/approvals-overview

Example of making a call to the approvals inbox endpoint while acting for a specific team member by including the X-Orshot-User-Id header.

```APIDOC
## GET /v1/approvals/inbox

### Description
Fetches the approvals inbox for a specific team member by including the `X-Orshot-User-Id` header. The API key acts for the workspace, but this header allows the call to act on behalf of a single user.

### Method
GET

### Endpoint
https://api.orshot.com/v1/approvals/inbox

### Headers
- **Authorization** (string) - Required - Bearer token with the Orshot API key.
- **X-Orshot-User-Id** (string) - Required - The user ID of the team member to act on behalf of.

### Request Example
```js
await fetch("https://api.orshot.com/v1/approvals/inbox", {
  headers: {
    Authorization: "Bearer <ORSHOT_API_KEY>",
    "X-Orshot-User-Id": "9a4c7e2b-1d6f-4e3a-8b5c-2f7d0e9a4c61",
  },
});
```

### Response
#### Success Response (200)
Returns the inbox data for the specified user.

#### Error Responses
- **403 permission_denied** - code `approval.member_header_not_member` - The user is not an owner, admin, or member of the key's workspace.
- **403 permission_denied** - code `approval.decision_person_required` - Attempting to approve, request changes, withdraw an approval, or put/reorder a template in an approved stage with the header.
- **403 permission_denied** - code `approval.member_header_not_allowed` - OAuth tokens cannot send the header.
- **422 validation_failed** - code `approval.member_header_invalid` - The header value is not a valid user ID.
```

--------------------------------

### Generate image from template

Source: https://orshot.com/docs/integrations/orshot-cli

Generates an image from a library template. Supports custom modifications via -m flag and interactive mode for guided setup.

```bash
# Basic generation
orshot generate library website-screenshot

# Generate with custom modifications
orshot generate library website-screenshot -m websiteUrl="https://example.com"

# Interactive mode for guided setup
orshot generate library website-screenshot --interactive
```
Tokens:
Raw