# Viibeo Agent REST API (reference)

Base URL: `https://www.viibeo.com/api/v1`  
Auth: `Authorization: Bearer vii_…`  
OpenAPI: `https://www.viibeo.com/api/v1/openapi.json`

Use `www.viibeo.com` so redirects do not strip Authorization.

## Endpoints

| Method | Path | Purpose |
| --- | --- | --- |
| GET | `/credits` | Balance + plan |
| GET | `/videos?page=&limit=` | List videos |
| POST | `/videos` | Create faceless/story short |
| GET | `/videos/{videoId}` | Video details |
| GET | `/jobs/{jobId}` | Poll generation |
| POST | `/exports` | Start MP4 export |
| GET | `/exports/{jobId}` | Poll export / render |
| POST | `/ideas` | Niche idea suggestions |
| POST | `/publish` | Publish to connected socials |
| GET | `/autopilot/series` | List Autopilot series |
| POST | `/autopilot/series` | Create Autopilot series |
| GET | `/webhooks` | List webhook endpoints |
| POST | `/webhooks` | Create webhook endpoint |
| PATCH | `/webhooks/{id}` | Update webhook |
| DELETE | `/webhooks/{id}` | Delete webhook |
| GET | `/openapi.json` | This schema (no auth) |

## POST `/videos` body

| Field | Required | Notes |
| --- | --- | --- |
| `prompt` | yes | Concrete niche prompt |
| `title` | no | Title hint |
| `type` | no | `Faceless` (default) or `Story` |
| `duration` | no | `15s` \| `30s` \| `1m` \| `2m` \| `3m` |
| `narrator` | no | Deepgram voice id (default `aura-asteria-en`) |
| `mediaSource` | no | `AI Images` \| `AI Video` \| `Stock Footage` |
| `language` | no | default `en` |
| `captionStyle` | no | default `hormozi` |
| `style` | no | Visual style hint |

Agent-created jobs skip interactive script review — poll or wait for webhook until complete.

## POST `/exports` body

```json
{ "videoId": "...", "resolution": "1080p", "quality": 80 }
```

`resolution`: `720p` \| `1080p`.

## POST `/publish` body

```json
{
  "videoId": "...",
  "platforms": ["TIKTOK", "INSTAGRAM", "YOUTUBE"],
  "caption": "optional",
  "title": "optional"
}
```

Platforms must already be connected in the dashboard.

## POST `/autopilot/series` body

Required: `name`, `prompt`.  
Optional: `scheduleType` (`ONE_TIME` \| `RECURRING`), `scheduleCron`, `scheduledFor`, `timezone`, `platforms`, `duration`, `mediaSource`, `captionStyle`.

## Webhook events

- `generation.completed`
- `generation.failed`
- `export.ready`
- `export.failed`
- `publish.completed`

## Credits check

```bash
curl -sS "${VIIBEO_BASE_URL}/api/v1/credits" \
  -H "Authorization: Bearer ${VIIBEO_API_KEY}"
```

## Ideas

```bash
curl -sS -X POST "${VIIBEO_BASE_URL}/api/v1/ideas" \
  -H "Authorization: Bearer ${VIIBEO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"niche":"scary facts","count":5}'
```