Skip to main content

Quickstart

This page takes you from an API key to your first stored event. You run every command in a terminal, and every request is sent with curl.

What you need​

  • An allisall API key. The next section says how to get one.
  • bash or zsh.
  • curl 7.76.0 or later. That is the first release with --fail-with-body, which every command on this page uses. Check your version with curl --version.

Get a key​

Workspaces are by invitation. allisall issues your workspace's API key and sends it to you.

A key starts with aia_. It is shown once, so keep it in a secret manager. The key you receive holds the ingest scope, which is all this page needs.

Set two variables​

Every command reads the API's address and your key from environment variables, so one command works in every environment and your key never appears in a command line.

export AIA_BASE_URL="https://api.allisai.ai"
read -rs AIA_API_KEY && export AIA_API_KEY

The second line waits for you to paste the key, and does not echo it. The key is therefore never written to your shell history. read -s is an option of bash and zsh, which is why this page names those two shells.

Check the connection​

GET /healthz takes no credential. It tells you the API is reachable.

curl --fail-with-body --silent --show-error \
  --get "$AIA_BASE_URL/healthz"

It answers {"status":"ok",…}.

Send one event​

POST /v1/events stores a batch of events. This batch holds one session event.

curl --fail-with-body --silent --show-error \
  --request POST "$AIA_BASE_URL/v1/events" \
  --header "Authorization: Bearer $AIA_API_KEY" \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "events": [
    {
      "event_id": "quickstart-1",
      "timestamp": "2026-08-14T03:12:40Z",
      "agent_key": "quickstart-agent",
      "category": "session",
      "event_type": "session_started"
    }
  ]
}
JSON

The quoted 'JSON' stops your shell from expanding anything inside the body. That is also why the timestamp is written out rather than computed. A timestamp in the past is accepted. A timestamp more than 24 hours ahead of the server's clock is refused.

The event is stored in your workspace. Its agent, quickstart-agent, did not exist before, so the API creates it and it appears in your agent registry. A session event carries no cost and no value, so it changes no figure in your workspace.

Read the answer​

The first time your workspace receives an event with the event_id quickstart-1, the API answers 200:

{
  "accepted": 1,
  "duplicates": 0,
  "rejected": 0,
  "errors": [],
  "errors_truncated": false
}

accepted counts the events this request stored. duplicates counts the events that were already stored, which are not stored again. rejected counts the events refused.

If you have run this command before in the same workspace, the event is already stored, so the answer is the one the next section describes. To store a new event, change event_id to a value you have not sent, such as quickstart-2.

Send it again​

Run the same command again. It answers duplicates: 1 and accepted: 0, because the event_id repeats. It answers the same way however many times you run it.

This is what makes a retried batch safe. If a request fails before you read its answer, send the same batch again: every event already stored is counted as a duplicate rather than stored twice.

When it fails​

  • 401, code unauthenticated. The key is missing, mistyped or revoked. Set AIA_API_KEY again. See unauthenticated.
  • 403, code insufficient_scope. The key does not hold the ingest scope. See insufficient_scope.
  • 200 with rejected above zero. The batch was processed, and the events that broke a rule are listed in errors, each with a field-level code. See Field-level error codes.

Every error answer, with a status of 400 or above, carries a request_id. Quote it when you report a problem.

Next​