> ## Documentation Index
> Fetch the complete documentation index at: https://vlyai-1c28d863.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Welcome to the vly.ai REST API. Authentication, base URLs, common patterns, SDKs, and the full endpoint catalog.

The vly.ai REST API lets you create projects, trigger agent runs, list deployments, manage files, and read billing usage from your own code. Use it to integrate vly into your own dashboards, build automations, or extend vly with custom tooling.

<Note>
  The public API is currently **v0** — endpoints, paths, and shapes may change before general availability. Subscribe to the [changelog](/resources/changelog) for breaking-change notices.
</Note>

## Base URLs

| Environment | URL |
| - | - |
| Production | `https://api.vly.ai` |
| Staging | `https://api.staging.vly.ai` |

All URLs in the endpoint reference are relative to the production base URL.

## Authentication

Every request requires an API key in the `Authorization` header:

All requests to the vly.ai API must include your API key in the `Authorization` header as a bearer token. Generate keys from your **Workspace settings → API keys**.

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.vly.ai/v1/projects \
    -H "Authorization: Bearer $VLY_API_KEY"
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch("https://api.vly.ai/v1/projects", {
    headers: { Authorization: `Bearer ${process.env.VLY_API_KEY}` },
  });
  ```

  ```python Python theme={null}
  import os, httpx
  res = httpx.get(
      "https://api.vly.ai/v1/projects",
      headers={"Authorization": f"Bearer {os.environ['VLY_API_KEY']}"},
  )
  ```

  ```go Go theme={null}
  req, _ := http.NewRequest("GET", "https://api.vly.ai/v1/projects", nil)
  req.Header.Set("Authorization", "Bearer "+os.Getenv("VLY_API_KEY"))
  ```
</CodeGroup>

<Warning>
  Never commit API keys to source control. Use environment variables and a secrets manager. See [Secrets management](/security/secrets-management).
</Warning>

For the full reference, see [Authentication](/api-reference/authentication).

## Quick start

The four steps to make your first API call:

<Steps>
  <Step title="Generate an API key">
    In vly, **Workspace settings → API keys → Create new key**. Copy and store securely.
  </Step>

  <Step title="Export it as an environment variable">
    ```bash theme={null}
    export VLY_API_KEY=vly_live_...
    ```
  </Step>

  <Step title="Make your first request">
    ```bash theme={null}
    curl https://api.vly.ai/v1/projects \
      -H "Authorization: Bearer $VLY_API_KEY"
    ```
  </Step>

  <Step title="Browse the endpoints">
    See the sidebar for the full catalog. Each endpoint page has an interactive playground.
  </Step>
</Steps>

## Endpoint catalog

<CardGroup cols={2}>
  <Card title="Projects" icon="folder" href="/api-reference/projects/list">
    Create, list, get, update vly projects.
  </Card>

  <Card title="Deployments" icon="rocket" href="/api-reference/deployments/create">
    Trigger and inspect deployments.
  </Card>

  <Card title="Agents" icon="bot" href="/api-reference/agents/trigger">
    Trigger an AI agent run programmatically.
  </Card>

  <Card title="Files" icon="file" href="/api-reference/files/upload">
    Upload assets to a project.
  </Card>

  <Card title="Billing" icon="credit-card" href="/api-reference/billing/usage">
    Inspect plan usage and credits.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks/test">
    Send and verify webhook events.
  </Card>
</CardGroup>

## SDKs

First-class SDKs for the languages most vly users work in:

<CardGroup cols={2}>
  <Card title="TypeScript / JavaScript" icon="code" href="/api-reference/sdks/typescript">
    `npm install @vly/sdk` — full type safety, streaming support, retries.
  </Card>

  <Card title="Python" icon="code" href="/api-reference/sdks/python">
    `pip install vly` — async + sync clients, type hints, retries.
  </Card>

  <Card title="CLI" icon="terminal" href="/api-reference/sdks/cli">
    `npm install -g @vly/cli` — terminal access to the same API.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/sdks/webhooks">
    Signature verification helpers for every supported language.
  </Card>
</CardGroup>

## Common patterns

### Pagination

List endpoints return up to 20 items by default and include a `next_cursor`:

```json theme={null}
{
  "data": [ /* up to 20 items */ ],
  "next_cursor": "eyJpZCI6Ii4uLiJ9"
}
```

Pass `next_cursor` as the `cursor` query parameter on the next request to get the next page. See [Pagination](/api-reference/pagination).

### Errors

All errors return a consistent shape:

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "The 'prompt' field is required.",
    "param": "prompt"
  }
}
```

See [Errors](/api-reference/errors) for the complete error code reference.

### Rate limits

Default rate limit is **60 requests/minute per API key**. Burst capacity allows \~10 requests in the first second. Plans above Pro raise the limit.

When rate-limited, the API returns `429 Too Many Requests` with a `Retry-After` header. See [Rate limits](/api-reference/rate-limits).

### Idempotency

For `POST` endpoints that create resources (Create project, Create deployment, Trigger agent), pass an `Idempotency-Key` header to safely retry:

```bash theme={null}
curl -X POST https://api.vly.ai/v1/projects \
  -H "Authorization: Bearer $VLY_API_KEY" \
  -H "Idempotency-Key: my-unique-key-123" \
  -H "Content-Type: application/json" \
  -d '{ "name": "My project", "prompt": "..." }'
```

Within 24 hours, repeated requests with the same key return the original response without creating a duplicate.

### Webhooks

For long-running operations (agent runs, deployments), use webhooks rather than polling. Register webhook endpoints in **Workspace settings → Webhooks**, and you'll receive `POST` requests when events occur.

Verify webhook signatures using the `X-Vly-Signature` header. Helpers in every [SDK](/api-reference/sdks/typescript).

## Versioning

The API is versioned by URL path: `/v1/...`. Breaking changes trigger a new major version (`/v2/...`); minor changes are backward-compatible additions. We commit to supporting old versions for 12 months after deprecation.

## Support

<CardGroup cols={3}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Detailed reference.
  </Card>

  <Card title="Rate limits" icon="gauge" href="/api-reference/rate-limits">
    Limits, headers, retry guidance.
  </Card>

  <Card title="Errors" icon="alert-triangle" href="/api-reference/errors">
    Full error code reference.
  </Card>
</CardGroup>

For questions or feature requests, email [api@vly.ai](mailto:api@vly.ai) or join the `#api` channel in [Discord](https://discord.gg/vly).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.