Developer Documentation · Original Demonstration

Event Ingest API Quickstart & Error Handling

This fictional, original API quickstart covers prerequisites, permissions, a first request, processing verification, required fields, and safe error handling.

Scenario

Northstar Event API is a fictional HTTPS API that accepts security-event records. The sample begins with the smallest useful path from credentials to an accepted request, then stays with the developer long enough to address field meaning, failure handling, and safe retry behavior.

What This Sample Demonstrates

This sample demonstrates task-first developer onboarding, authentication, HTTP and JSON, request validation, actionable error handling, and a clear distinction between required and optional metadata. It also shows the difference between documenting a response code and helping a developer decide what that response means for the integration.

Quickstart: Send Your First Event

Before You Begin

Prerequisites

  • A POSIX-compatible shell, such as Bash or Zsh, with curl installed.
  • The Northstar base URL for the environment you are testing.
  • HTTPS access from your environment to api.example.invalid.
  • A unique source event ID that has not been submitted before.
  • A valid RFC 3339 UTC timestamp for the event.
  • A way to confirm that the processed event reached the receiving application.

Required Permissions

  • The token must have events:write permission to submit an event.
  • To check processing status through the API, the token must also have events:read permission. If you do not have that permission, arrange for an authorized operator to verify the event in the receiving application.

You do not need administrative access to the Northstar service for this procedure. Do not request broader permissions solely to complete the quickstart.

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

1. Set the Connection Values

Open a terminal in your approved development or test environment. Set the base URL for the environment you are testing. Then enter the token without placing its value in the command or shell history.

export NORTHSTAR_BASE_URL="https://api.example.invalid"
read -rsp "Northstar token: " NORTHSTAR_TOKEN
echo
export NORTHSTAR_TOKEN

Confirm that both variables are set without printing the token.

test -n "${NORTHSTAR_BASE_URL}" && echo "Base URL is set"
test -n "${NORTHSTAR_TOKEN}" && echo "Token is set"

Look for both confirmation messages. If either command returns no message, set that value again before continuing.

2. Submit an Event

Send one event with a unique event_id. Replace the example values with a test event that is safe to send to your environment. The --include option displays the HTTP status and response headers with the response body.

curl --silent --show-error --include --request POST \
  --url "${NORTHSTAR_BASE_URL}/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 and a response body like the following:

{
  "event_id": "fw-20260817-000184",
  "ingest_status": "accepted",
  "request_id": "req_71c8d4b9",
  "accepted_at": "2026-08-17T12:41:10Z"
}

Look for:

  • An HTTP status of 202 Accepted.
  • The same event_id you submitted.
  • An ingest_status of accepted.
  • A request_id you can use to trace and verify processing.
  • An accepted_at timestamp.

Record the request_id. Acceptance means that Northstar received and queued the event; it does not prove that downstream processing completed.

4. Verify Processing

If your token has events:read permission, replace the example request ID with the value returned in Step 3 and check its status.

curl --silent --show-error --include --request GET \
  --url "${NORTHSTAR_BASE_URL}/v1/requests/req_71c8d4b9" \
  --header "Authorization: Bearer ${NORTHSTAR_TOKEN}"

A processed event returns 200 OK and a response like the following:

{
  "request_id": "req_71c8d4b9",
  "event_id": "fw-20260817-000184",
  "ingest_status": "processed",
  "processed_at": "2026-08-17T12:41:11Z"
}

Look for:

  • The same request_id and event_id returned when you submitted the event.
  • An ingest_status of processed.
  • A processing timestamp later than the event's acceptance time.

Finally, confirm that the event appears in the receiving application. If the request remains accepted or pending, honor any Retry-After header and retry only within your integration's approved limit. If it reports failed, record the request ID and error details before changing the payload.

Request Fields

Field Required? Purpose
event_id Yes Stable source identifier that 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.

Verify Before Integrating

Before adding the API call to an application or automated workflow, verify the complete behavior in an approved test environment:

  1. Submit a valid event and confirm both 202 Accepted and the final processed status.
  2. Confirm that the event appears in the receiving application with the expected ID, timestamp, source, type, and message.
  3. Submit a payload that omits one required field. Confirm that the API returns 400 Bad Request, identifies the missing field, and does not ingest the event.
  4. Resubmit a previously accepted event_id. Confirm that the API returns 409 Conflict and that the original event remains unchanged.
  5. Verify that application logs retain the request_id but never record the token.

Do not deliberately trigger rate limiting or use expired credentials in a shared environment unless that test has been approved.

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.
  • Verify final processing rather than treating 202 Accepted as completion.
  • Test a success and representative 400 and 409 error paths.

Why the Documentation Is Shaped This Way

The smallest successful path comes first because developers need a working request before they need a complete reference. Field detail and failure handling follow while the request is still familiar. Each error includes a corrective decision because a status code without a next step is only half a diagnostic.

The sample also preserves operational boundaries. It does not print secrets, treat every failure as retryable, or recommend replacing evidence with a random new identifier. Those choices are part of technical accuracy, not decorative safety language added after the procedure is written.