Event Ingest API Quickstart & Error Handling

Scenario

Northstar Event API is a fictional HTTPS API that accepts security-event records. This sample takes a developer from credentials to a validated first request.

What This Sample Demonstrates

This sample demonstrates task-first developer onboarding, authentication, HTTP and JSON, request validation, actionable error guidance, and a clear distinction between required and optional metadata.

Quickstart: Send Your First Event

Before You Begin

Obtain a token with events:write permission.
Confirm that your environment has HTTPS access to api.example.invalid.
Install curl and choose a unique source event ID.

Treat the token as a secret. Do not place it in source control, screenshots, tickets, or readable shell history.

1. Set the Token

export NORTHSTAR_TOKEN="replace-with-your-token"

2. Submit an Event

curl --request POST \
  --url https://api.example.invalid/v1/events \
  --header "Authorization: Bearer ${NORTHSTAR_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "event_id": "fw-20260817-000184",
    "occurred_at": "2026-08-17T12:41:09Z",
    "source": "edge-firewall-03",
    "event_type": "authentication.failure",
    "severity": "medium",
    "message": "Repeated failed administrative login attempts"
  }'

3. Confirm Acceptance

A successful request returns 202 Accepted.

{
  "event_id": "fw-20260817-000184",
  "ingest_status": "accepted",
  "request_id": "req_71c8d4b9"
}

Request Fields

Field	Required?	Purpose
`event_id`	Yes	Stable source identifier; supports duplicate detection.
`occurred_at`	Yes	Original event time in RFC 3339 UTC.
`source`	Yes	System or component that produced the event.
`event_type`	Yes	Normalized category used for routing and analysis.
`severity`	No	Source-assigned severity.
`message`	No	Short description for an operator.

Common Errors

400 Bad Request

Correct the named field; do not retry an unchanged invalid payload.

401 Unauthorized

Check the Bearer scheme, token status, and environment variable without printing the token.

403 Forbidden

Use a credential with events:write permission.

409 Conflict

Determine whether the source reused an ID; do not generate a random replacement before investigating.

429 Too Many Requests

Honor Retry-After and use bounded retries with backoff.

Integration Checklist

Keep tokens out of code and logs.
Send UTC timestamps and stable source event IDs.
Log the returned request ID.
Distinguish validation failures from retryable failures.
Test a success and a representative error path.

Why the Documentation Is Shaped This Way

The smallest successful path comes first, followed by reference detail and failure handling. Error guidance focuses on corrective decisions because a status code without a next step is only half a diagnostic.