Available nowLast updated: June 2026

Ingestion API

The Ingestion API receives operational events from external systems using source-scoped API keys. It is the entry point for apps, websites, ERPs, workers, services, and integrations.

Endpoint

POST /v1/events/ingest

Authentication

X-API-Key

Retry safety

Idempotency-Key

Example request

Replace YOUR_SOURCE_API_KEY with the API key generated for your Event Source.

curl -X POST "https://api.laribacloud.com/v1/events/ingest" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_SOURCE_API_KEY" \
  -H "Idempotency-Key: demo-request-001" \
  -d '{
    "event_id": "evt_demo_001",
    "event_type": "payment.failed",
    "source_id": "src_demo",
    "environment": "production",
    "severity": "critical",
    "timestamp": "2026-06-01T10:00:00Z",
    "payload": {
      "amount": 49.99,
      "currency": "EUR",
      "reason": "card_declined"
    }
  }'

Required headers

Header	Value	Description
Content-Type	application/json	Required so the API can parse the request body as JSON.
X-API-Key	<source_api_key>	Source-scoped API key used to authenticate the producer.
Idempotency-Key	<unique_request_id>	Recommended for safe retries when the request outcome is unknown.

Event body fields

Events should use a consistent envelope so Lariba Cloud can validate, store, search, and later evaluate operational activity.

Field	Requirement	Description
event_id	Recommended	Stable event identifier from the producer. Used for traceability, replay, and duplicate protection.
event_type	Required	Event classification, such as payment.failed, erp.invoice.created, or api.error.
source_id	Required	Source identity linked to the producer sending the event.
environment	Recommended	Environment context such as production, staging, or development.
severity	Optional	Operational priority such as info, warning, error, or critical.
timestamp	Recommended	When the event happened. Prefer ISO 8601 UTC timestamps.
payload	Required	Structured JSON body containing the operational event data.

Success response

{
  "accepted": true,
  "event_id": "evt_123",
  "status": "stored"
}

Source trust boundary

The source API key authenticates the producer. The Event Source defines the trust boundary. This lets Lariba Cloud attribute each accepted event to a known project, source, and environment.

Idempotency protects retries

When the original request outcome is unknown, retry with the same Idempotency-Key. This helps prevent duplicate records when producers retry after timeouts or network failures.

Use the live API base URL configured for your environment. During local development, you can use your local backend URL instead.

Never log full source API keys. Store them securely and rotate or revoke them when a producer is retired, compromised, or moved to a new environment.