API Reference

Base URL and authentication

https://api.naven.network

Every Events request requires a server-side Project API key:

Authorization: Bearer naven_api_...
Content-Type: application/json

Responses use:

{
  "code": 0,
  "message": "ok",
  "data": {}
}

Event Queues

Method	Path	Description
`POST`	`/v1/event-queues`	Create a Queue
`GET`	`/v1/event-queues`	List Project Queues
`POST`	`/v1/event-queues/:queueId/claim`	Long-poll and lease one Event
`GET`	`/v1/event-queues/:queueId/events`	List Queue Events

Create Queue

Field	Required	Limits
`name`	yes	1–100 characters; letters, numbers, `.`, `_`, and `-`
`defaultLeaseSeconds`	no	30–3600; default `900`
`maxAttempts`	no	1–100; default `10`

Claim

Field	Required	Limits
`leaseSeconds`	no	30–3600; defaults to the Queue setting
`waitSeconds`	no	0–20; default `0`

The response data is null when no Event is available. A successful claim increments attemptCount.

List Events

Query parameters:

Parameter	Values
`status`	`available`, `leased`, `completed`, `failed`, or `expired`
`limit`	1–100; default `50`
`cursor`	Event ID returned as `nextCursor`

Schedules

Method	Path	Description
`POST`	`/v1/schedules`	Create a Schedule
`GET`	`/v1/schedules`	List Project Schedules
`GET`	`/v1/schedules/:scheduleId`	Get a Schedule
`PATCH`	`/v1/schedules/:scheduleId`	Update mutable configuration
`DELETE`	`/v1/schedules/:scheduleId`	Delete a Schedule
`POST`	`/v1/schedules/:scheduleId/pause`	Pause future invocations
`POST`	`/v1/schedules/:scheduleId/resume`	Resume invocations
`POST`	`/v1/schedules/:scheduleId/trigger`	Create an immediate manual Event

Create Schedule

Field	Required	Limits
`queueId`	yes	Queue UUID in the same Project
`externalId`	yes	1–200 characters; letters, numbers, `.`, `_`, and `-`
`name`	yes	1–200 characters
`description`	no	Maximum 2000 characters
`schedule`	yes	Cron, interval, or one-time definition
`payload`	no	JSON object up to 64 KiB
`overlapPolicy`	no	`queue`, `skip`, `latest`, or `parallel`
`maxConcurrency`	no	1–100; default `1`
`maxEventAgeSeconds`	no	60–86400; default `86400`

The queueId and externalId cannot be changed after creation.

Schedule synchronization is asynchronous. Inspect sync.status, sync.syncedRevision, and sync.lastError after create, update, pause, resume, or delete.

Event lease operations

Method	Path	Description
`POST`	`/v1/events/:eventId/heartbeat`	Extend an active lease
`POST`	`/v1/events/:eventId/ack`	Mark leased work completed
`POST`	`/v1/events/:eventId/nack`	Release or fail leased work
`POST`	`/v1/events/:eventId/replay`	Replay a failed or expired Event

The lease token is secret and valid only while the current lease remains active.

Heartbeat

{
  "leaseToken": "...",
  "leaseSeconds": 900
}

Acknowledge

{
  "leaseToken": "..."
}

Negative acknowledgement

{
  "leaseToken": "...",
  "error": "Exchange temporarily unavailable",
  "retryDelaySeconds": 30
}

retryDelaySeconds may be 0–3600. When maxAttempts is reached, the Event moves to failed.

Replay

Replay is accepted only for failed or expired Events. It creates a new manual Event with a new ID and current scheduledAt; it does not mutate the original Event.

Common HTTP responses

HTTP	Meaning
`400`	Input or schedule expression is invalid
`401`	Project API key is missing, expired, or revoked
`404`	Queue or Schedule does not exist in the Project
`409`	Lease is invalid/expired, state conflicts, or replay is not allowed
`500`	Unexpected infrastructure failure

On this page