Argus API

Argus has its own hosts and its own credentials, separate from the platform API. This page lists every endpoint you can call directly, the key each one takes, and what it answers.

8 min read

Hosts and credentials

Argus runs on two hosts:

Host	What it's for
`https://argus-in.naijacloud.com`	Sending data in: errors, traces, metrics, logs, cron check-ins
`https://argus-api.naijacloud.com`	Source maps and deploys from CI, and the Prometheus query API

None of these endpoints take a platform API key (nc_live_…). Each takes one of three Argus credentials, and each credential can do one job and nothing else:

Credential	Looks like	Where to get it	What it can do
DSN key	The public key in a source's DSN	Argus → Sources	Send data for that one source
Upload token	`argus_up_…`	On the source, under Upload tokens	Upload source maps and record deploys for that source
Read token	`argus_rt_…`	Argus → Dashboards → Connect Prometheus / Grafana	Query the workspace's metrics through the Prometheus API

The DSN key is public by design: it can only add data to its own source, so it is safe in browser code. An upload token can't read anything, so one that leaks from a build exposes nothing. A read token can't send or change anything. See Sources for where the DSN comes from:

DSN format

https://<public key>@argus-in.naijacloud.com/<project id>

Managing sources, issues, alerts and dashboards is done in the dashboard. Those screens aren't a public API.

Sending a DSN key

Every endpoint on argus-in except the error endpoints and the cron ping URLs takes the DSN key in any of these forms:

Authorization: Bearer <key>
X-Argus-Key: <key>
?key=<key> on the URL
HTTP basic auth, with the key as the password (the log and metrics endpoints only, for shippers that only speak basic auth)

The error endpoints follow the Sentry protocol instead. See Errors.

Errors

POST https://argus-in.naijacloud.com/api/{project id}/envelope/

POST https://argus-in.naijacloud.com/api/{project id}/store/

The Sentry ingest protocol, so every Sentry SDK and every Argus SDK sends here unchanged. The key goes in the X-Sentry-Auth header (Sentry sentry_key=<key>, sentry_version=7) or the sentry_key query parameter, and {project id} must be the DSN's project id.

Argus stores an envelope's errors, and its transactions as spans. Other item types are accepted and ignored. Argus answers 200 with the event's id:

200

json

{ "id": "9f0a3c2e8d6b4a7f91c25e3b0d4f8a16" }

A request may be up to 1 MB compressed (gzip or deflate) and 20 MB uncompressed. Over the source's rate or the plan's monthly allowance, Argus answers 429 with Retry-After and X-Sentry-Rate-Limits, which Sentry SDKs already obey.

You don't need to build envelopes yourself: an Argus SDK or a Sentry SDK does it. To check a DSN by hand, run naijacloud argus test --dsn <DSN>.

OpenTelemetry

Signal	Endpoint
Traces	`POST https://argus-in.naijacloud.com/v1/traces`
Metrics	`POST https://argus-in.naijacloud.com/v1/metrics`
Logs	`POST https://argus-in.naijacloud.com/v1/logs`

OTLP over HTTP, as protobuf (Content-Type: application/x-protobuf) or JSON (application/json). gRPC is not accepted. Point an exporter at the host and it adds the paths itself:

OpenTelemetry exporter

bash

OTEL_EXPORTER_OTLP_ENDPOINT=https://argus-in.naijacloud.com
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <your DSN key>"

Argus answers with an empty OTLP success response, in the format you sent. How spans and metrics are stored is described in Traces, metrics & logs.

Logs

POST https://argus-in.naijacloud.com/api/{project id}/logs

A log drain for any shipper. The body is a JSON array, newline-delimited JSON or plain text lines. Lines past 20,000 in one request are dropped:

Send logs

bash

curl -X POST https://argus-in.naijacloud.com/api/$PROJECT_ID/logs \
  -H "Authorization: Bearer $ARGUS_KEY" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary $'{"level":"error","message":"payment failed","order":"A-1042"}\n'

200

json

{ "ok": true }

From a JSON line, Argus reads the time, level, message, service, trace and span ids, host and stream, and keeps the other fields as searchable attributes (up to 64 a line). A line's message is kept up to 16 KB. Logs are scrubbed of tokens, card numbers and secret-looking fields before they are stored.

Metrics

JSON push

POST https://argus-in.naijacloud.com/api/{project id}/metrics

For a metric or two from a script, without an OpenTelemetry or Prometheus setup:

Push metrics

bash

curl -X POST https://argus-in.naijacloud.com/api/$PROJECT_ID/metrics \
  -H "Authorization: Bearer $ARGUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": [
      { "name": "orders_paid_total", "labels": { "region": "lagos" }, "value": 42 },
      { "name": "queue_depth", "value": 7, "timestamp": 1793616000 }
    ]
  }'

Field	Required	Notes
`name`	yes	The metric's name, in Prometheus style
`value`	yes	A number. A metric with no value is skipped
`labels`	no	String labels
`timestamp`	no	Unix time in seconds, milliseconds, microseconds or nanoseconds. Defaults to when it arrives

Argus answers 200 with { "ok": true }. One request may carry up to 100,000 points.

Prometheus remote-write

POST https://argus-in.naijacloud.com/prometheus/api/v1/write

POST https://argus-in.naijacloud.com/api/{project id}/prometheus/write

Prometheus remote-write 1.0, snappy-compressed protobuf, as Prometheus sends it. Use the first form with the key as the bearer credential:

prometheus.yml

yaml

remote_write:
  - url: https://argus-in.naijacloud.com/prometheus/api/v1/write
    authorization:
      credentials: <your DSN key>

Argus answers 204. A request carrying only native histograms is refused with 400, since Argus stores classic histograms.

The series limit

Your plan sets how many active series (seen in the last day) a workspace can have. Past it, new series are dropped and the rest of the request still lands. The X-Argus-Dropped-Series response header says how many were dropped.

Cron check-ins

Every cron monitor has a ping URL. It takes no key, because the URL is the secret. Any method works (GET, HEAD or POST), so curl, wget or a browser can ping it:

URL	Means
`https://argus-in.naijacloud.com/c/{token}`	The run succeeded
`https://argus-in.naijacloud.com/c/{token}/start`	A run started (lets Argus measure how long it took)
`https://argus-in.naijacloud.com/c/{token}/fail`	The run failed
`https://argus-in.naijacloud.com/c/{token}/{exit code}`	`0` is success, `1` to `255` is a failure

The first 2 KB of a POST body is kept with the run, scrubbed, so you can send the job's output. Argus answers 200 with the text OK, and 404 for a token it doesn't know.

From code with a DSN key, check in by the monitor's slug instead:

POST https://argus-in.naijacloud.com/v1/cron/{slug}

POST https://argus-in.naijacloud.com/v1/cron/{slug}/{start|fail|exit code}

Check in by slug

bash

curl -X POST https://argus-in.naijacloud.com/v1/cron/nightly-report \
  -H "Authorization: Bearer $ARGUS_KEY"

The slug is looked up in the key's workspace. An unknown slug answers 404, so create the monitor in Argus first. See Cron monitors.

Feature flags

POST https://argus-in.naijacloud.com/v1/flags/evaluate

(also served on argus-api.naijacloud.com)

Which variant a subject gets for each live flag. The website script calls this for you; call it yourself to evaluate flags on a server:

Evaluate flags

bash

curl -X POST https://argus-in.naijacloud.com/v1/flags/evaluate \
  -H "Authorization: Bearer $ARGUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject": "user_8812", "environment": "production", "flags": ["new-checkout"]}'

200

json

{ "flags": { "new-checkout": "on" }, "environment": "production" }

Field	Required	Notes
`subject`	yes	Who is asking: a user id, or the script's anonymous id. The same subject always gets the same variant
`environment`	no	Defaults to `production`
`attributes`	no	String attributes that targeting rules match on, such as `{ "plan": "pro" }`
`flags`	no	Only these flags. Leave it out for every live flag

A flag that doesn't exist is missing from flags, so fall back to your default.

Source maps and deploys

These take an upload token as Authorization: Bearer argus_up_…, and nothing else: a DSN key, read token or login is refused. They are what naijacloud argus and argus-cli call. See Source maps for how to build with maps on.

Upload a source map

POST https://argus-api.naijacloud.com/v1/cli/sourcemaps?release={release}&name={name}

The body is the map's JSON.

Parameter	Value
`release`	Exactly the release your SDK sends. A map only applies to events from that release
`name`	Where the minified file is served, with `~` for the scheme and host: `https://shop.ng/assets/app.js` is `~/assets/app.js`

Upload one map

bash

curl -X POST "https://argus-api.naijacloud.com/v1/cli/sourcemaps?release=$RELEASE&name=~/assets/index.js" \
  -H "Authorization: Bearer $ARGUS_UPLOAD_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @dist/assets/index.js.map

201

json

{ "release": "1.4.2", "name": "~/assets/index.js", "sizeBytes": 48213 }

A map can be up to 16 MB (413 past it) and must be a version 3 map that lists its sources. Index maps (with sections) are refused with 400. Uploading the same release and name again replaces the map. When a release or the workspace is full, Argus answers 413. The limits are in Source maps.

Record a deploy

POST https://argus-api.naijacloud.com/v1/cli/deploys

Record a deploy

bash

curl -X POST https://argus-api.naijacloud.com/v1/cli/deploys \
  -H "Authorization: Bearer $ARGUS_UPLOAD_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"release\": \"$RELEASE\", \"environment\": \"production\", \"commitSha\": \"$GITHUB_SHA\"}"

Field	Required	Notes
`release`	yes	The release that went out
`environment`	no	Such as `production`
`commitSha`	no	The commit that was deployed
`url`	no	A link to the deploy
`deployedAt`	no	RFC 3339 time. Defaults to now

201

json

{ "recorded": true, "release": "1.4.2", "source": "checkout-api" }

Check a token

GET https://argus-api.naijacloud.com/v1/cli/whoami

Says which source an upload token belongs to, so a CI job can fail early on the wrong token:

200

json

{ "source": { "id": "3f6c…", "name": "checkout-api" } }

Querying metrics

https://argus-api.naijacloud.com/prometheus is a Prometheus-compatible HTTP API over your workspace's metrics. Grafana's Prometheus data source works against it as it is (see Reading metrics from Grafana), and so does anything else that speaks the Prometheus HTTP API.

Send a read token as Authorization: Bearer argus_rt_…, or as the password in basic auth. A workspace owner or admin creates one.

Endpoint	Method
`/prometheus/api/v1/query`	`GET` or `POST`
`/prometheus/api/v1/query_range`	`GET` or `POST`
`/prometheus/api/v1/labels`	`GET` or `POST`
`/prometheus/api/v1/series`	`GET` or `POST`
`/prometheus/api/v1/label/{name}/values`	`GET`
`/prometheus/api/v1/metadata`	`GET`
`/prometheus/api/v1/status/buildinfo`	`GET`

An instant query

bash

curl https://argus-api.naijacloud.com/prometheus/api/v1/query \
  -H "Authorization: Bearer $ARGUS_READ_TOKEN" \
  --data-urlencode 'query=sum by (service) (rate(http_requests_total[5m]))'

Answers use Prometheus's own format, {"status": "success", "data": {…}} or {"status": "error", "errorType": "bad_data", "error": "…"}. A read token sees only its own workspace's metrics, and is refused (403) everywhere else on argus-api.

Errors and limits

Outside the Prometheus API, an error answers with JSON:

401

json

{ "error": "upload token not accepted" }

Cron ping URLs answer in plain text instead, so they never confuse a shell script.

Status	Means
`400`	The body or a parameter is malformed. The message says which
`401`	No credential, or one Argus doesn't accept
`403`	The credential is valid but can't do this, such as a read token outside the Prometheus API, or a DSN key from an origin the source doesn't allow
`404`	Unknown cron token or slug
`413`	Too large: over 5 MB compressed or 50 MB uncompressed for telemetry, 16 MB for a source map, or the source map limit reached
`429`	Over the key's request rate or the plan's monthly allowance. Wait for `Retry-After`

Request bodies on argus-in may be gzip- or deflate-compressed; set Content-Encoding. Rates and monthly allowances depend on your plan, and are shown under Argus → Usage & plan.

Related: Argus overview and Argus SDKs.