Automation API

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. The same key works on a self-hosted worker; only the base URL changes.

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, export, and read limits are determined by the workspace billing plan. If you receive 429 Too Many Requests, wait for the number of seconds in the Retry-After response header before retrying.

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.

2. Start a generation

Create a project and start generation with one request. All fields below are required except model and 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; for MotionCut it must return the raw video file. Add up to 10 public HTTPS references when the agent needs brand assets, a brief, or supporting material.

Omit model to use the desktop’s computed default. When model is present, Poko uses exactly that model or fails the request—it never silently substitutes another model. To target a configured AI Gateway such as OpenRouter, use gateway:<provider-model-id>, for example gateway:openai/gpt-4.1. Gateway models require BYOK, a configured gateway base URL and API key, and a Pro or Agency plan. The configured gateway must support the current agent engine’s API: OpenAI Responses for Codex or Anthropic Messages for Claude Code.

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"
      }
    ]
  }'

MotionCut generation example

Set projectType to motioncut and provide a direct public HTTPS video URL. The desktop streams the recording into its local project workspace when the durable request is delivered, then uses the normal MotionCut transcription, frame analysis, original-voice, and hybrid editing flow. Supported video types are MP4, MOV, M4V, WebM, MKV, and AVI, up to 200 MB.

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-motioncut-workflow-run-id' \
  --data '{
    "name": "Founder launch video",
    "projectType": "motioncut",
    "sourceUrl": "https://media.example.com/founder-take.mp4",
    "prompt": "Turn this recording into a dark, polished YC launch video. Keep the original voice and use the attached product references as proof.",
    "videoStyle": "motion-ad",
    "aspectRatio": "16:9",
    "references": [
      {
        "name": "Product website",
        "path": "https://example.com"
      }
    ]
  }'

Rate limits by plan

Limits apply to the workspace plan bound to the API key:

• Starter: 10 generations and 5 exports per hour
• Plus: 20 generations and 10 exports per hour
• Pro: 40 generations and 20 exports per hour
• Agency: 80 generations and 40 exports per hour
• Dealify Scale: Agency limits

Every tier also has a minute-level limit and a maximum number of queued generations to protect the connected computer.

All endpoints may return 429 Too Many Requests with a Retry-After header. Wait for that duration before retrying. These limits control request frequency; normal AI-credit and model-usage rules still apply.

Request fields

name, sourceUrl, prompt, videoStyle, and aspectRatio are required.

• projectType must be url, pdf, pptx, or motioncut.
• videoStyle must be walkthrough, motion-ad, or research-explainer; research-explainer requires a PDF.
• aspectRatio must be 16:9, 1:1, or 9:16.
• MotionCut sourceUrl must remain reachable until the desktop accepts the queued request.
• 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.

{
  "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.

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.

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.

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
• 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.

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.

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: The request is safely stored and waiting.
• dispatching: Poko is sending it to the desktop.
• accepted: Motion created the local project.
• running: The agent is working.
• completed, failed, and cancelled: Terminal states.

If Motion restarts after accepting a request, its local agent session cannot resume and the request is reported as failed.

An unknown model ID is rejected before the request is stored. Engine and billing-mode compatibility are checked by the connected desktop because those settings can change while a durable request is queued. An incompatible model makes the request terminally failed with the exact reason available from the generation status endpoint.

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.

Errors

• 400: Invalid request data or an unknown/incompatible model
• 401: Invalid or revoked key
• 403: Workspace access or selected billing mode does not permit an action
• 404: Unknown request
• 409: 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.

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

{ "online": true }

Security and reliability

Secure each workflow

• 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.

Handle offline delivery

If your desktop is offline, generation and export requests are stored safely, retried with backoff, and delivered after Motion reconnects. Automation requests are retained for 30 days; after that window, they are not guaranteed to remain available for delivery or status lookup. Poll the request or export status endpoint instead of retrying with a new idempotency key. If a request is terminally failed after Motion accepted it, create a new request with a new idempotency key to run it again.

For MotionCut, Poko stores the URL—not the video bytes—while the desktop is offline. Use a URL that remains valid until delivery. Short-lived signed URLs can expire before the desktop reconnects and will make that request fail.