API Reference

Base URL

https://api.velahq.xyz/v1

For local development (default port):

http://localhost:3000/v1

All endpoints are prefixed with /v1.

Authentication

Vela uses two different credentials depending on the operation:

Credential	Header	Used for
Client secret (`vela_cs_...`)	`Authorization: Bearer <secret>`	All management endpoints — apps, schemas, notification rules, events (read)
API key (`vela_live_...`)	`x-api-key: <key>`	Event ingestion only (`POST /v1/ingest`)

# Management endpoint — use Authorization header with client secret
curl https://api.velahq.xyz/v1/apps \
  -H "Authorization: Bearer vela_cs_your_secret_here"

# Ingest endpoint — use x-api-key header
curl -X POST https://api.velahq.xyz/v1/ingest \
  -H "x-api-key: vela_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "event": "order.placed", "data": { "orderId": "ord_1" }, "level": "info" }'

See Authentication for a full explanation of the two-credential model.

Request format

All request bodies must be JSON. Set the Content-Type header on every POST, PUT, and PATCH request:

Content-Type: application/json

Response format

All responses are JSON. Successful responses return 200 or 201 with the requested data. Error responses return a consistent error object.

Success example

{
  "id": "app-uuid",
  "name": "Order Service",
  "slug": "order-service",
  "apiKeyHint": "vela_live_abc1...",
  "createdAt": "2024-06-01T12:00:00.000Z"
}

Error format

{
  "statusCode": 400,
  "timestamp": "2024-06-01T12:00:00.000Z",
  "path": "/v1/apps/order-service/schemas",
  "error": "Bad Request",
  "message": "eventName must be a non-empty string"
}

Status codes

Status	Description
`200`	Success — resource returned or updated
`201`	Created — new resource was created
`204`	No content — deletion succeeded
`400`	Bad request — validation error, check `message` for details
`401`	Unauthorized — credentials missing or invalid
`403`	Forbidden — credentials valid but insufficient for this operation
`404`	Not found — resource does not exist
`429`	Rate limited — slow down and retry with backoff
`500`	Internal server error — unexpected failure on our end

Endpoints overview

Resource	Base path	Auth required
Apps	`/v1/apps`	Client secret
Schemas	`/v1/apps/:appId/schemas`	Client secret
Ingest	`/v1/ingest`	API key
Events (read)	`/v1/apps/:appId/events`	Client secret
Notification Rules	`/v1/apps/:appId/notification-rules`	Client secret

Pagination

List endpoints return arrays directly. When the response is large, pass limit and offset query parameters:

# First 50 events
GET /v1/apps/order-service/events?limit=50&offset=0

# Next 50
GET /v1/apps/order-service/events?limit=50&offset=50

Rate limits

The API is rate-limited per account. If you exceed the limit, you receive a 429 Too Many Requests response. Implement exponential backoff before retrying:

Wait 1 second after the first 429
Wait 2 seconds after the second
Wait 4 seconds after the third
And so on up to a reasonable maximum

SDKs

If you’re using TypeScript or Python, use the SDK instead of calling the API directly — it handles authentication, serialization, and typed errors automatically:

TypeScript SDK

@vela-event/sdk — type-safe clients for Node.js and browsers.

Python SDK

vela-sdk — sync and async clients for Python 3.9+.

​Base URL

​Authentication

​Request format

​Response format

​Success example

​Error format

​Status codes

​Endpoints overview

​Pagination

​Rate limits

​SDKs