Quickstart
Create a queue, schedule an Event, and consume it over HTTP.
1. Configure server credentials
Events endpoints require a server-side Project API key:
NAVEN_API_URL=https://api.naven.network
NAVEN_API_KEY=naven_api_...Never expose this key in browser or mobile code. Project API keys currently authorize the Project's other server-side management APIs as well, so keep the consumer in infrastructure you control.
2. Create an Event Queue
curl --request POST "$NAVEN_API_URL/v1/event-queues" \
--header "Authorization: Bearer $NAVEN_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "strategy-runs",
"defaultLeaseSeconds": 900,
"maxAttempts": 10
}'Copy data.id from the response:
{
"code": 0,
"message": "Event queue created",
"data": {
"id": "00000000-0000-4000-8000-000000000000",
"name": "strategy-runs",
"status": "active",
"defaultLeaseSeconds": 900,
"maxAttempts": 10
}
}3. Create a Schedule
NAVEN_QUEUE_ID=00000000-0000-4000-8000-000000000000
curl --request POST "$NAVEN_API_URL/v1/schedules" \
--header "Authorization: Bearer $NAVEN_API_KEY" \
--header "Content-Type: application/json" \
--data "{
\"queueId\": \"$NAVEN_QUEUE_ID\",
\"externalId\": \"btc-breakout-5m\",
\"name\": \"BTC breakout every five minutes\",
\"schedule\": {
\"type\": \"cron\",
\"expression\": \"*/5 * * * *\",
\"timezone\": \"UTC\"
},
\"payload\": {
\"strategyId\": \"btc-breakout\"
},
\"overlapPolicy\": \"latest\",
\"maxConcurrency\": 1,
\"maxEventAgeSeconds\": 300
}"The Schedule is accepted before its provider finishes synchronizing. Query the returned Schedule ID until:
{
"sync": {
"status": "synced",
"revision": 1,
"syncedRevision": 1,
"lastError": null
}
}Do not treat a Schedule as active in production while sync.status is
pending or error.
4. Claim an Event
Use HTTP long polling from a backend worker:
curl --request POST \
"$NAVEN_API_URL/v1/event-queues/$NAVEN_QUEUE_ID/claim" \
--header "Authorization: Bearer $NAVEN_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"leaseSeconds": 900,
"waitSeconds": 20
}'When no work is available, data is null. Otherwise, the response contains
the Event, a secret leaseToken, and leaseExpiresAt.
5. Heartbeat and acknowledge
Extend a running lease before it expires:
curl --request POST "$NAVEN_API_URL/v1/events/$EVENT_ID/heartbeat" \
--header "Authorization: Bearer $NAVEN_API_KEY" \
--header "Content-Type: application/json" \
--data "{
\"leaseToken\": \"$LEASE_TOKEN\",
\"leaseSeconds\": 900
}"After results and external side effects are durably recorded:
curl --request POST "$NAVEN_API_URL/v1/events/$EVENT_ID/ack" \
--header "Authorization: Bearer $NAVEN_API_KEY" \
--header "Content-Type: application/json" \
--data "{
\"leaseToken\": \"$LEASE_TOKEN\"
}"If processing fails, call nack with an optional error and retry delay instead
of acknowledging the Event.