Skip to main content

​
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:
CredentialHeaderUsed 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

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

​
Endpoints overview

ResourceBase pathAuth required
Apps/v1/appsClient secret
Schemas/v1/apps/:appId/schemasClient secret
Ingest/v1/ingestAPI key
Events (read)/v1/apps/:appId/eventsClient secret
Notification Rules/v1/apps/:appId/notification-rulesClient 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+.