API quickstart

Use a dedicated service account for applications, CI, scripts, and AI agents. For interactive terminal use, start with the CLI quickstart.

1. Create a service-account token

Open NeatLogs and go to Settings → Service Accounts in the appropriate organization. You need permission to manage service accounts.

1. Create an account for this integration.
2. Bind the project it needs and select the minimum project role.
3. Mint an expiring token with context:read and observability:read for this quickstart.
4. Copy the one-time token directly into your secret manager or CI secret store. Save the bound project UUID for the requests below.

The selected project role and token scopes both restrict access. See authentication for the complete credential model.

Service-account setup and service-account token minting, rotation and revocation consume shared security-lifecycle capacity. The default token bucket holds 10 requests per applicable bucket and replenishes at 10 requests per hour. These limits can be shared across endpoints and identities within the applicable actor or organization context; they are not ten independent requests for each token. Leave capacity for cleanup, and honor Retry-After if a 429 delays rotation or revocation. See rate-limit guidance for bucket and retry details.

2. Provide credentials to your process

Inject NEATLOGS_TOKEN from your secret store and set the project UUID. Keep tokens out of source files, command arguments, logs, and shell history. The cURL examples below pass headers through stdin configuration. Keep shell tracing off and do not log that configuration.

export NEATLOGS_PROJECT_ID='<project-uuid>'
# NEATLOGS_TOKEN is supplied by your secret manager or CI environment.

For a local test in Bash, read the token without echoing it or including it in command history:

read -r -s -p 'Service-account token: ' NEATLOGS_TOKEN
printf '\n'
export NEATLOGS_TOKEN

3. Confirm the selected project

curl --fail-with-body --silent --show-error --config - <<CURL_CONFIG
header = "Authorization: Bearer ${NEATLOGS_TOKEN}"
header = "x-project-id: ${NEATLOGS_PROJECT_ID}"
url = "https://app.neatlogs.com/api/v1/public/project"
CURL_CONFIG

A successful response returns the authorized project metadata inside data. A 401 means the token is invalid, expired, revoked, or for a different host. A 403 means the token lacks a required scope, project binding, role, or entitlement.

4. Read recent traces

curl --fail-with-body --silent --show-error --config - <<CURL_CONFIG
header = "Authorization: Bearer ${NEATLOGS_TOKEN}"
header = "x-project-id: ${NEATLOGS_PROJECT_ID}"
url = "https://app.neatlogs.com/api/v1/public/traces?limit=5"
CURL_CONFIG

The response contains data.traces and data.page. An empty trace list is a valid result. Use page.nextCursor to continue pagination.

When the test finishes, remove the token from the shell and revoke disposable tokens in Settings → Service Accounts.

unset NEATLOGS_TOKEN