Poko Motion Docs
Browse API reference

API reference

Automation API

Trigger Poko Motion video generation from n8n, Zapier, Make, Claude, ChatGPT, or your own workflow.

Last updated September 2026

How it works

Poko Motion creates videos on your computer, while this API gives an external workflow a secure way to start and monitor that work. Your workflow sends a request to your personal public URL. Poko safely stores it first, then relays it to the desktop app when it is connected.

Keep Poko Motion open for immediate delivery. If it is offline, your request remains queued and is delivered when Motion reconnects. Each API key is bound to both your public URL and the workspace selected when you created it.

1. Create an API key

In Poko Motion, open Settings → API, save a public URL slug, then create a named API key. The key is bound to the workspace selected in the app. Copy the secret at creation time and store it in your workflow platform’s credential vault. Poko never shows the full key again.

Authorization header
Authorization: Bearer poko_live_your_api_key

Before you call the API

Every endpoint starts with your personal public URL: https://YOUR-SLUG.isthebest.poko.video. Replace YOUR-SLUG with the value shown in Poko Motion → Settings → API. Send the API key as a Bearer token on every request.

Generation and export creation require an Idempotency-Key header. Use the unique execution ID from n8n, Zapier, Make, or your own job runner. Repeating the same key with the same payload returns the original request instead of creating duplicate work. Reusing a key with different export settings is rejected.

ParameterDescription
AuthorizationRequired
headerWorkspace-bound API key.Bearer poko_live_…
Content-TypeRequired
headerRequired for JSON generation and export requests.application/json
Idempotency-KeyRequired
headerStable, unique ID for one generation or export attempt.1–200 characters

2. Start a generation

Create a project and start generation with one request. All fields below are required except references. sourceUrl must be a public HTTPS URL. For URL projects it is a website address; for PDF and PowerPoint projects it must point directly to that document. Add up to 10 public HTTPS references when the agent needs brand assets, a brief, or supporting material.

POST /automations/v1/generations
curl --request POST 'https://YOUR-SLUG.isthebest.poko.video/automations/v1/generations' \
  --header 'Authorization: Bearer poko_live_your_api_key' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: your-unique-workflow-run-id' \
  --data '{
    "name": "Poko product walkthrough",
    "projectType": "url",
    "sourceUrl": "https://poko.video",
    "prompt": "Create a polished 30-second product walkthrough for founders.",
    "videoStyle": "walkthrough",
    "aspectRatio": "16:9",
    "references": [
      {
        "name": "Brand guide",
        "path": "https://example.com/brand-guide.pdf"
      }
    ]
  }'

Request fields

name, sourceUrl, prompt, videoStyle, and aspectRatio are required. projectType must be url, pdf, or pptx. videoStyle must be walkthrough, motion-ad, or research-explainer; research-explainer requires a PDF. aspectRatio must be 16:9, 1:1, or 9:16. Idempotency-Key is required: use a unique workflow execution ID so retries never create duplicate videos.

A successful request returns 202 with requestId and status queued. Save requestId: it identifies the durable request while it waits for or runs on your desktop.

ParameterDescription
nameRequired
stringHuman-readable project name.1–200 characters
projectTypeRequired
stringFormat of the required sourceUrl.url (website) · pdf · pptx
sourceUrlRequired
stringPublic HTTPS URL for the source website or document.HTTPS only
promptRequired
stringGeneration brief sent to the local agent.1–20,000 characters
videoStyleRequired
stringPlanning profile for the video.walkthrough · motion-ad · research-explainer (PDF only)
aspectRatioRequired
stringOutput format chosen when the project is created.16:9 · 1:1 · 9:16
references
arrayOptional supporting public HTTPS URLs for briefs or brand material.Maximum 10; each item is { name: string, path: HTTPS URL }
Accepted response
{
  "requestId": "c3e4f6f8-...",
  "status": "queued",
  "deliveryAttempts": 0
}

3. List generations

List the durable generation requests created with this API key in its bound workspace. Filter by one or more statuses, requests created after an ISO timestamp, and paginate with the opaque cursor returned in the previous response.

ParameterDescription
status
query parameterOptional comma-separated status filter.queued · dispatching · accepted · running · completed · failed · cancelled
after
query parameterOptional ISO timestamp; returns requests created at or after it.
limit
query parameterOptional page size.1–100; default 25
cursor
query parameterOpaque cursor returned by the preceding response.
GET /automations/v1/generations
curl 'https://YOUR-SLUG.isthebest.poko.video/automations/v1/generations?status=queued,running&limit=25' \
  --header 'Authorization: Bearer poko_live_your_api_key'

{
  "generations": [{ "requestId": "c3e4f6f8-...", "status": "running" }],
  "cursor": "eyJQSyI6Ii4uLiJ9"
}

4. Check generation status

Poll this endpoint using requestId. It works while the desktop is offline and reports queued, dispatching, running, completed, failed, or cancelled. Once accepted, the response also includes the project and chat identifiers returned by Motion.

ParameterDescription
requestIdRequired
path parameterDurable request identifier returned from the create request.
GET /automations/v1/generations/:requestId
curl 'https://YOUR-SLUG.isthebest.poko.video/automations/v1/generations/c3e4f6f8-...' \
  --header 'Authorization: Bearer poko_live_your_api_key'

5. Cancel a generation

Cancel a queued or active request with DELETE. Cancelling stops delivery; if Motion has already accepted the job, it retains the project and its work in Poko Motion.

ParameterDescription
requestIdRequired
path parameterDurable request identifier returned from the create request.
DELETE /automations/v1/generations/:requestId
curl --request DELETE 'https://YOUR-SLUG.isthebest.poko.video/automations/v1/generations/c3e4f6f8-...' \
  --header 'Authorization: Bearer poko_live_your_api_key'

6. Export a completed generation locally

After a generation reports completed, create a durable local export. Motion queues the export while the desktop is offline, then renders into that project’s controlled local renders folder when it reconnects. Send a JSON body with any of the fields below, or {} to use the same defaults as the export UI: MP4, 30 fps, Standard quality, 1× speed, and one worker. The API never accepts a destinationPath or resolution—output dimensions remain fixed by the project composition—and it never provides upload or download links. Only one active export may run per project.

ParameterDescription
requestIdRequired
path parameterA completed generation request.
format
stringOptional output container.mp4 · webm; default mp4
fps
numberOptional frame rate.24 · 30 · 60; default 30
quality
stringOptional encoding quality preset.draft · standard · high; default standard
speed
numberOptional playback speed multiplier.0.5–2; default 1
workers
integerOptional number of local render workers.1–24; default 1
Idempotency-KeyRequired
headerUnique workflow execution ID for this export.
POST /automations/v1/generations/:requestId/exports
curl --request POST 'https://YOUR-SLUG.isthebest.poko.video/automations/v1/generations/c3e4f6f8-.../exports' \
  --header 'Authorization: Bearer poko_live_your_api_key' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: your-unique-export-id' \
  --data '{
    "format": "mp4",
    "fps": 30,
    "quality": "high",
    "speed": 1,
    "workers": 4
  }'

{ "exportId": "d4e5f6a7-...", "status": "queued" }

Check or cancel an export

Poll GET /automations/v1/generations/:requestId/exports/:exportId for queued, dispatching, rendering, completed, failed, or cancelled status. The response includes coarse phase and progress only; rendered files remain local to the connected Motion computer. DELETE the same URL to cancel a queued or active render.

GET export status
curl 'https://YOUR-SLUG.isthebest.poko.video/automations/v1/generations/c3e4f6f8-.../exports/d4e5f6a7-...' \
  --header 'Authorization: Bearer poko_live_your_api_key'

Status values and errors

Generation states: queued means the request is safely stored and waiting; dispatching means Poko is sending it to the desktop; accepted means Motion created the local project; running means the agent is working; completed, failed, and cancelled are terminal states.

Export states: queued, dispatching, rendering, completed, failed, and cancelled. Export responses may include a coarse phase and progress snapshot. The finished file always remains in the project’s local renders folder.

Use 400 for invalid request data, 401 for invalid/revoked keys, 403 for a key bound to another workspace, 404 for an unknown request, and 409 when an action conflicts with the current state.

Check that Motion is online

Use this lightweight endpoint before starting a workflow if you need to confirm that the desktop app is connected. It requires the same API key as the generation endpoints.

GET /automations/v1/status
curl 'https://YOUR-SLUG.isthebest.poko.video/automations/v1/status' \
  --header 'Authorization: Bearer poko_live_your_api_key'

{ "online": true }

Security and reliability

Use a different key for each workflow, store it as a secret, and revoke it immediately if it is exposed. Do not place API keys in URLs or client-side browser code. Keys are workspace-bound and are rejected if their owner no longer has workspace access.

If your desktop is offline, generation and export requests are stored safely, retried with backoff, and delivered after Motion reconnects. Poll the request or export status endpoint instead of retrying with a new idempotency key.