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.

The public API is currently v0 — endpoints, paths, and shapes may change before general availability. Subscribe to the changelog for breaking-change notices.

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.

curl

curl https://api.vly.ai/v1/projects \
  -H "Authorization: Bearer $VLY_API_KEY"

Never commit API keys to source control. Use environment variables and a secrets manager. See Secrets management.

For the full reference, see Authentication.

Quick start

The four steps to make your first API call:

1. Generate an API key

   In vly, Workspace settings → API keys → Create new key. Copy and store securely.

2. Export it as an environment variable

   export VLY_API_KEY=vly_live_...
   
3. Make your first request

   curl https://api.vly.ai/v1/projects \
     -H "Authorization: Bearer $VLY_API_KEY"
   
4. Browse the endpoints

   See the sidebar for the full catalog. Each endpoint page has an interactive playground.

Endpoint catalog

Projects

Create, list, get, update vly projects.

Deployments

Trigger and inspect deployments.

Agents

Trigger an AI agent run programmatically.

Files

Upload assets to a project.

Billing

Inspect plan usage and credits.

Webhooks

Send and verify webhook events.

SDKs

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

TypeScript / JavaScript

npm install @vly/sdk — full type safety, streaming support, retries.

Python

pip install vly — async + sync clients, type hints, retries.

CLI

npm install -g @vly/cli — terminal access to the same API.

Webhooks

Signature verification helpers for every supported language.

Common patterns

Pagination

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

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

Errors

All errors return a consistent shape:

{
  "error": {
    "code": "invalid_request",
    "message": "The 'prompt' field is required.",
    "param": "prompt"
  }
}

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

Idempotency

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

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.

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

Authentication

Detailed reference.

Rate limits

Limits, headers, retry guidance.

Errors

Full error code reference.

For questions or feature requests, email [e-mail] or join the #api channel in Discord.