# REST API — LLM Integration Guide

You are an autonomous agent that has been given a **base URL** and an **API key** for the service documented below. This document is self-contained: it tells you everything needed to call the API. Follow it literally.

- **Base URL:** `https://wzpgp78g.vibecode.cloud`
- **API key:** provided to you separately; it starts with `sk_`.
- **All paths below are relative to the base URL** (e.g. `https://wzpgp78g.vibecode.cloud/api/v1/health`).

> Generated from the app's single source of truth. If an endpoint
> behaves differently from what you read here, trust the live response
> and report the mismatch — the docs are meant to be authoritative.

## Essentials

### Base URL

All endpoints live under `https://wzpgp78g.vibecode.cloud/api/v1`. `https://wzpgp78g.vibecode.cloud` is the origin you were given (scheme + host, e.g. `https://example.com`). Do not add a trailing slash.

### Authentication

Every endpoint requires an API key sent as a Bearer token:
`Authorization: Bearer sk_your_key_here`. Keys always start with `sk_`. A missing or invalid key returns `401 { "error": "Invalid or missing API key" }`. Create keys in the app under Profile → API Keys.

### Content type

Responses are JSON unless noted (file download returns raw bytes). Request bodies are JSON (`Content-Type: application/json`) except file upload, which is `multipart/form-data`.

### Rate limiting

Requests are rate limited per API key. When you exceed a limit you get `429` (or `403` if the limit is configured to block) with an `error` message and, when applicable, a `Retry-After` header (seconds). Back off and retry.

### Published endpoints are separate

Actions you publish get their own public URL `https://wzpgp78g.vibecode.cloud/api/p/<slug>` (GET with query params as input, or POST a JSON object). Those are NOT part of this API and do not use `sk_` keys: depending on the endpoint they are open, password-protected (HTTP Basic or `?key=`) or use a per-endpoint key (`X-API-Key: spk_...`). Their output format (json/csv/html/xml/md/text) is chosen per endpoint and can be overridden with `?format=`.

### Errors

Errors are JSON with an `error` string and a matching HTTP status (`400` bad input, `401` unauthenticated, `403` forbidden, `404` not found, `413` payload too large, `429` rate limited, `500` server error).

## Quick start

```bash
# 1. Verify your key works
curl https://wzpgp78g.vibecode.cloud/api/v1/health -H "Authorization: Bearer sk_your_key_here"
# A 200 with {"status":"healthy",...} means you are authenticated.
```

## Endpoints

### GET /api/v1/health

**Health check** — Confirms the API is up and your key is valid. Handy as a first call to verify credentials and connectivity.

- **Auth:** `Authorization: Bearer sk_...` required
- **Access:** Any valid API key.

**Request**

```bash
curl https://wzpgp78g.vibecode.cloud/api/v1/health \
  -H "Authorization: Bearer sk_your_key_here"
```

**Response**

```
{
  "status": "healthy",
  "timestamp": "2026-07-19T12:00:00.000Z",
  "uptime": 1234.56,
  "version": "1.0.0",
  "apiKey": "My key",
  "userId": "usr_...",
  "message": "API is running successfully"
}
```

---

### GET /api/v1/stats

**Account & API usage stats** — Returns the calling user together with API-usage counters (requests today / this week / this month, error rate, API-key count).

- **Auth:** `Authorization: Bearer sk_...` required
- **Access:** Any valid API key (scoped to the key owner).

**Request**

```bash
curl https://wzpgp78g.vibecode.cloud/api/v1/stats \
  -H "Authorization: Bearer sk_your_key_here"
```

**Response**

```
{
  "user": { "id": "usr_...", "email": "you@example.com", "name": "You", "role": "user", "createdAt": "..." },
  "apiStats": {
    "totalApiKeys": 2,
    "requestsToday": 14,
    "requestsThisWeek": 98,
    "requestsThisMonth": 412,
    "errorRate": "1.20%",
    "errorCount": 5
  },
  "meta": { "timestamp": "...", "apiKey": "My key" }
}
```

---

### GET /api/v1/users

**List users** — Lists users. A regular key returns only its own user record; an admin key returns all users with pagination.

- **Auth:** `Authorization: Bearer sk_...` required
- **Access:** Any valid API key (admin keys see all users; others see themselves).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | no | Page size, 1–100 (default 10). Admin only; ignored for non-admins. |
| `offset` | query | integer | no | Rows to skip (default 0). Admin only. |

**Request**

```bash
curl "https://wzpgp78g.vibecode.cloud/api/v1/users?limit=20&offset=0" \
  -H "Authorization: Bearer sk_your_key_here"
```

**Response**

```
{
  "users": [
    { "id": "usr_...", "email": "you@example.com", "name": "You", "role": "user", "emailVerified": null, "createdAt": "..." }
  ],
  "meta": { "limit": 20, "offset": 0, "total": 1, "apiKey": "My key" }
}
```

---

### POST /api/v1/users

**Create user (scaffold)** — Admin-only endpoint scaffold for creating a user. Ships as a stub in this starter — it validates input and echoes it back rather than persisting. Fill in real creation logic before relying on it.

- **Auth:** `Authorization: Bearer sk_...` required
- **Access:** Admin API keys only (others get 403).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `email` | body | string | yes | New user email. |
| `name` | body | string | yes | New user display name. |
| `role` | body | string | no | 'user' (default) or 'admin'. |

**Request**

```bash
curl -X POST https://wzpgp78g.vibecode.cloud/api/v1/users \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email":"new@example.com","name":"New User","role":"user"}'
```

**Response**

```
{
  "message": "User creation endpoint - implementation needed",
  "requestedData": { "email": "new@example.com", "name": "New User", "role": "user" },
  "apiKey": "My key"
}
```

> This is a template stub — no user is actually created yet.

---

### POST /api/v1/files

**Upload a file** — Uploads a file and stores its raw bytes. Use this instead of a form/Server Action for any real upload (Server Actions cap the body at ~1MB; this endpoint does not). Send `multipart/form-data` with a single `file` field.

- **Auth:** `Authorization: Bearer sk_...` required
- **Access:** Any valid API key (the file is owned by the key owner).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `file` | form | file | yes | The file to upload (multipart field name must be "file"). |

**Request**

```bash
curl -X POST https://wzpgp78g.vibecode.cloud/api/v1/files \
  -H "Authorization: Bearer sk_your_key_here" \
  -F "file=@./photo.png"
```

**Response**

```
{
  "id": "fil_...",
  "filename": "photo.png",
  "url": "/api/v1/files/fil_..."
}
```

> Default max size is 100MB (configurable via MAX_FILE_SIZE). Oversized uploads return 413.
>
> The returned `url` is the Bearer-gated download endpoint below.

---

### GET /api/v1/files/:id

**Download / preview a file** — Streams the raw file bytes with the stored Content-Type. Because it is Bearer-gated you cannot put it directly in an `<img src>`; fetch it with the token and build an object URL client-side.

- **Auth:** `Authorization: Bearer sk_...` required
- **Access:** Any valid API key.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | File id returned by the upload endpoint. |

**Request**

```bash
curl https://wzpgp78g.vibecode.cloud/api/v1/files/fil_your_file_id \
  -H "Authorization: Bearer sk_your_key_here" \
  --output downloaded-file
```

**Response**

```
Raw binary body with the stored `Content-Type` and `Content-Disposition: inline; filename="..."`. Returns `404 { "error": "File not found" }` if unknown.
```

---

### DELETE /api/v1/files/:id

**Delete a file** — Deletes a file owned by the calling key.

- **Auth:** `Authorization: Bearer sk_...` required
- **Access:** Any valid API key (only the owner may delete).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | File id to delete. |

**Request**

```bash
curl -X DELETE https://wzpgp78g.vibecode.cloud/api/v1/files/fil_your_file_id \
  -H "Authorization: Bearer sk_your_key_here"
```

**Response**

```
{ "deleted": true }   // { "deleted": false } with status 404 if not found / not owned
```

---

### GET /api/v1/pilots

**List pilots** — A pilot is one target website/SaaS you drive with SaaSPilot. Returns every pilot visible to the key: the key owner's own pilots (or its tenant's in multi-tenant mode) plus pilots other people shared with the key owner. Each has an action count, the caller's `role` (`owner` | `admin` | `editor` | `user`), `shared` and `sharedBy` (the owner's e-mail for shared pilots). Every role can read pilots/actions/runs and run actions through this API. Stored site credentials are never returned — only `hasCredentials`.

- **Auth:** `Authorization: Bearer sk_...` required
- **Access:** Any valid API key (the key owner's pilots, tenant pilots and pilots shared with them).

**Request**

```bash
curl https://wzpgp78g.vibecode.cloud/api/v1/pilots \
  -H "Authorization: Bearer sk_your_key_here"
```

**Response**

```
{
  "pilots": [
    {
      "id": "k2j4h5...",
      "name": "Acme Shop",
      "baseUrl": "https://shop.acme.test/",
      "description": "Our supplier's web shop",
      "hasCredentials": true,
      "actionCount": 3,
      "role": "owner",
      "shared": false,
      "sharedBy": null,
      "createdAt": "2026-10-03T10:00:00.000Z",
      "updatedAt": "2026-10-03T10:00:00.000Z"
    },
    {
      "id": "p9q8r7...",
      "name": "Partner portal",
      "baseUrl": "https://portal.partner.test/",
      "description": "",
      "hasCredentials": true,
      "actionCount": 1,
      "role": "user",
      "shared": true,
      "sharedBy": "owner@partner.test",
      "createdAt": "2026-10-02T09:00:00.000Z",
      "updatedAt": "2026-10-02T09:00:00.000Z"
    }
  ]
}
```

---

### GET /api/v1/pilots/:id

**Get a pilot with its actions** — One pilot (owned, tenant or shared with the key owner — with `role`, `shared`, `sharedBy` as in the list) plus all of its actions (same shape as `GET /api/v1/actions/:id`).

- **Auth:** `Authorization: Bearer sk_...` required
- **Access:** Any valid API key (owned, tenant or shared pilots — any pilot role).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Pilot id. |

**Request**

```bash
curl https://wzpgp78g.vibecode.cloud/api/v1/pilots/PILOT_ID \
  -H "Authorization: Bearer sk_your_key_here"
```

**Response**

```
{ "pilot": { "id": "...", "name": "Acme Shop", "role": "editor", "shared": true, "sharedBy": "owner@acme.test", ... }, "actions": [ { "id": "...", "name": "Search products", ... } ] }
// 404 { "error": "Pilot not found" }
```

---

### GET /api/v1/actions

**List actions** — An action is one automation on a pilot's site (e.g. "search products for {query}"), written by AI as a versioned recipe of validated steps. `status` is `authoring` | `ready` | `failed` | `broken` | `repairing`; only actions with an `activeVersion` can run. `health` reflects the daily health check (`unknown` | `passed` | `failed` | `repaired` | `broken`). Includes the actions of pilots shared with the key owner.

- **Auth:** `Authorization: Bearer sk_...` required
- **Access:** Any valid API key (owned, tenant or shared pilots — any pilot role).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `pilotId` | query | string | no | Only actions of this pilot. |

**Request**

```bash
curl "https://wzpgp78g.vibecode.cloud/api/v1/actions?pilotId=PILOT_ID" \
  -H "Authorization: Bearer sk_your_key_here"
```

**Response**

```
{
  "actions": [
    {
      "id": "a8d9f0...",
      "pilotId": "k2j4h5...",
      "name": "Search products",
      "goal": "Search the shop for {query} and list name, price, stock and URL",
      "mode": "auto",
      "inputFields": [ { "name": "query", "type": "string", "required": true } ],
      "status": "ready",
      "activeVersion": 2,
      "latestVersion": 2,
      "needsBrowser": false,
      "health": { "status": "passed", "checkedAt": "2026-10-03T06:00:00.000Z", "message": "Health check passed." },
      "job": { "id": "job_...", "kind": "refine", "status": "completed", "error": null, "startedAt": "2026-10-03T10:01:00.000Z" },
      "lastRunAt": "2026-10-03T10:05:00.000Z",
      "createdAt": "...",
      "updatedAt": "..."
    }
  ]
}
```

---

### GET /api/v1/actions/:id

**Get an action** — One action (see `GET /api/v1/actions` for the fields).

- **Auth:** `Authorization: Bearer sk_...` required
- **Access:** Any valid API key (owned, tenant or shared pilots — any pilot role).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Action id. |

**Request**

```bash
curl https://wzpgp78g.vibecode.cloud/api/v1/actions/ACTION_ID \
  -H "Authorization: Bearer sk_your_key_here"
```

**Response**

```
{ "action": { "id": "a8d9f0...", "name": "Search products", "status": "ready", ... } }
// 404 { "error": "Action not found" }
```

---

### POST /api/v1/actions/:id/run

**Run an action** — Runs the action now (synchronously — usually seconds, browser-mode actions up to ~2 minutes) with the given input and returns the run with its data and per-step validation results. Stored pilot credentials are added to the input server-side. Pass `format` to get the data rendered as csv/html/xml/md/text instead of the JSON run object.

- **Auth:** `Authorization: Bearer sk_...` required
- **Access:** Any valid API key with any role on the action's pilot (owner, admin, editor or user — running is allowed for every role). Rate limited per key (`pilot.api.run`).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Action id. |
| `input` | body | object | no | Input fields as declared in the action's `inputFields`, e.g. `{"query":"shoes"}`. |
| `version` | body | number | no | Run a specific recipe version instead of the active one. |
| `format` | body | string | no | `json` (default: the run object) or `csv` \| `html` \| `xml` \| `md` \| `text` (just the rendered data). |

**Request**

```bash
curl -X POST https://wzpgp78g.vibecode.cloud/api/v1/actions/ACTION_ID/run \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"input":{"query":"shoes"}}'
```

**Response**

```
{
  "run": {
    "id": "r1x...",
    "actionId": "a8d9f0...",
    "trigger": "api",
    "status": "passed",
    "version": 2,
    "input": { "query": "shoes" },
    "data": [ { "name": "Trail Runner", "price": 89.95, "inStock": true, "url": "https://shop.acme.test/p/1001" } ],
    "steps": [ { "id": "fetch_page", "ok": true, "errors": [], "ms": 412 }, { "id": "parse_items", "ok": true, "errors": [], "ms": 38 } ],
    "failedStep": null,
    "error": null,
    "durationMs": 450,
    "createdAt": "2026-10-03T10:05:00.000Z"
  }
}
// 502 with the same body and "status": "failed" when a step fails its validator
// 409 { "error": "This action is still being authored — ..." } when it has no version yet
```

---

### GET /api/v1/actions/:id/runs

**List recent runs of an action** — Newest first; includes runs from the dashboard, the API, published endpoints, webhooks and assistants (`trigger`).

- **Auth:** `Authorization: Bearer sk_...` required
- **Access:** Any valid API key (owned, tenant or shared pilots — any pilot role).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Action id. |
| `limit` | query | number | no | 1–100, default 20. |
| `data` | query | string | no | `0` to omit the `data` payloads. |

**Request**

```bash
curl "https://wzpgp78g.vibecode.cloud/api/v1/actions/ACTION_ID/runs?limit=5&data=0" \
  -H "Authorization: Bearer sk_your_key_here"
```

**Response**

```
{ "runs": [ { "id": "r1x...", "trigger": "endpoint", "status": "passed", "version": 2, "steps": [ ... ], "durationMs": 450, "createdAt": "..." } ] }
```

---

## Notes for automated callers

- Always send the `Authorization: Bearer sk_...` header; there is no cookie/session auth here.
- On `429`/`403` with a `Retry-After` header, wait that many seconds before retrying.
- Treat any non-2xx JSON `error` field as the human-readable failure reason.
- File downloads (`GET /api/v1/files/:id`) return raw bytes, not JSON.