Ingest Events

Send an event to Ackly from any HTTP client.

Endpoint

POST https://www.ackly.dev/api/ingest

Authentication

Authentication is done via a Bearer token in the Authorization header:

Authorization: Bearer YOUR_INGEST_KEY

The key identifies both the source and the workspace the event belongs to. Obtain your ingest key from the Sources page in www.ackly.dev. See Sources for details on keeping keys secure and rotating them.

Request

Content-Type: application/json

Body parameters

Parameter	Type	Required	Description
`status`	`"success"` \| `"failure"` \| `"partial"`	Yes	Outcome of the event
`message`	string	No	Human-readable description
`eventType`	string	No	Category or label (e.g. `"deploy"`, `"cron"`)
`externalId`	string	No	An ID from your own system to correlate this event
`durationMs`	number	No	How long the operation took, in milliseconds
`metadata`	any	No	Arbitrary JSON payload — any valid JSON value

Example request

bash

curl -X POST https://www.ackly.dev/api/ingest \
  -H "Authorization: Bearer YOUR_INGEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "success",
    "message": "Nightly backup completed",
    "eventType": "backup",
    "durationMs": 4820,
    "metadata": { "sizeBytes": 104857600 }
  }'

Response

201 Created

The event was successfully ingested.

{
	"id": "6634a1f2c8d9e3b4a2f10001"
}

Field	Type	Description
`id`	string	The unique ID of the newly created event

Error responses

Status	Cause
`400 Bad Request`	The request body is missing `status`, contains an invalid `status` value, or is not valid JSON
`401 Unauthorized`	The `Authorization` header is missing, malformed (not `Bearer <key>`), or the key does not exist
`429 Too Many Requests`	You’ve reached your monthly event limit. Ingestion resumes automatically when the counter resets at the start of your next billing period — or upgrade your plan to raise the limit

Notes

Monthly limits — once the monthly limit is reached, additional events are not ingested until the counter resets at the start of your next billing period. Upgrade your plan to raise the limit.
Event retention is determined by your plan. See Plans & Limits for retention windows by tier.
Real-time delivery — successfully ingested events are broadcast immediately to any live dashboard sessions open for that workspace.
The ingest endpoint does not require a user session. It is safe to call from server-side code, CLI scripts, and CI pipelines.