# Renders

Create and track video render jobs. Rendering is asynchronous — the API returns immediately with a render ID; you poll or use a webhook to get the result.

## POST /renders

Create a new render job.

Request

    curl -X POST https://devmotion.app/api/v1/renders \
      -H "Authorization: Bearer dm_live_YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "template_id": "laptop-3d-intro",
        "modifications": [
          { "layer": "Browser", "property": "props.url", "value": "https://yoursite.com" },
          { "layer": "Title",   "property": "text",       "value": "My Product" }
        ],
        "webhook_url": "https://yourserver.com/webhook",
        "metadata": { "order_id": "12345" }
      }'

### Request body

Field | Type | Required | Description
--- | --- | --- | ---
`template_id` | string | ✓* | ID of a built-in template
`project_id` | string | ✓* | ID of one of your projects
`modifications` | array | — | Layer property overrides (see below)
`webhook_url` | string | — | URL to POST the result to when done
`metadata` | object | — | Arbitrary key/value data echoed back in the response and webhook
`width` | number | — | Override output width in pixels
`height` | number | — | Override output height in pixels
`fps` | number | — | Override frames per second

* Provide either `template_id` or `project_id` — not both.

### Modifications

Target any layer by name and set any property at render time:

Property | Type | Description
--- | --- | ---
`text` | string | Text content
`src` | URL | Image or video source URL
`url` | URL | Browser / iframe URL
`color` | hex | Text color
`fill` | hex | Shape fill color
`fontSize` | number | Font size in pixels
`visible` | boolean | Layer visibility
`opacity` | number | Opacity (0–1)
`transform.x` | number | X position
`transform.y` | number | Y position
`props.*` | any | Any layer-specific prop

### Response `202 Accepted`

POST /renders — response

    {
      "id": "render_abc123",
      "status": "rendering",
      "output_url": null,
      "webhook_url": "https://yourserver.com/webhook",
      "metadata": { "order_id": "12345" },
      "created_at": "2025-01-15T10:30:00Z"
    }

The render runs in the background. `output_url` is `null` until the render completes. Poll `GET /renders/:id` or wait for the webhook callback.

## GET /renders

List your render jobs with optional filters.

Request

    curl https://devmotion.app/api/v1/renders?status=completed&limit=10 \
      -H "Authorization: Bearer dm_live_YOUR_API_KEY"

### Query parameters

Parameter | Type | Default | Description
--- | --- | --- | ---
`limit` | number | `25` | Results per page (max 100)
`offset` | number | `0` | Pagination offset
`status` | string | — | Filter by status: `rendering`, `completed`, `failed`
`template_id` | string | — | Filter by template

### Response

GET /renders — response

    {
      "data": [
        {
          "id": "render_abc123",
          "project_id": null,
          "template_id": "laptop-3d-intro",
          "status": "completed",
          "output_url": "https://storage.../video.mp4",
          "file_size_bytes": 2456789,
          "duration_ms": 5000,
          "error_message": null,
          "metadata": { "order_id": "12345" },
          "created_at": "2025-01-15T10:30:00Z",
          "started_at": "2025-01-15T10:30:01Z",
          "completed_at": "2025-01-15T10:30:15Z"
        }
      ],
      "pagination": {
        "limit": 10,
        "offset": 0,
        "has_more": false
      }
    }

## GET /renders/:id

Get status and details for a single render.

Request

    curl https://devmotion.app/api/v1/renders/render_abc123 \
      -H "Authorization: Bearer dm_live_YOUR_API_KEY"

### Response

Field | Description
--- | ---
`status` | `rendering` · `completed` · `failed`
`output_url` | Download URL when `status` is `completed`, else `null`
`file_size_bytes` | File size in bytes
`duration_ms` | Video duration in milliseconds
`error_message` | Error description when `status` is `failed`, else `null`
`webhook_url` | Webhook endpoint supplied at creation
`webhook_status` | `pending` · `sent` · `failed`
`metadata` | Metadata supplied at creation

GET /renders/:id — completed

    {
      "id": "render_abc123",
      "project_id": null,
      "template_id": "laptop-3d-intro",
      "status": "completed",
      "output_url": "https://storage.../video.mp4",
      "file_size_bytes": 2456789,
      "duration_ms": 5000,
      "error_message": null,
      "error_code": null,
      "webhook_url": "https://yourserver.com/webhook",
      "webhook_status": "sent",
      "metadata": { "order_id": "12345" },
      "created_at": "2025-01-15T10:30:00Z",
      "started_at": "2025-01-15T10:30:01Z",
      "completed_at": "2025-01-15T10:30:15Z"
    }