API reference
Search stored evidence, collect fresh sources, manage owned watches, and resume durable change delivery.
GET /health is public. Every /v1/* route requires
Authorization: Bearer $ARGUS_API_TOKEN when a token is configured. Consumers use their own bearer credential for records, watches, collections, changes,
usage, source health, and scoped configuration export. Other routes require the
operator token. Configuring consumers requires an operator token, including on
loopback. Primitive routes require a configured operator token.
export ARGUS_URL=http://127.0.0.1:8788
curl -H "Authorization: Bearer $ARGUS_API_TOKEN" "$ARGUS_URL/v1/records"GET /health
GET /health returns {status, version: 2, role, intelligence}.
GET /v1/records
GET /v1/records accepts repeated source and target, plus q, since,
until, publishedSince, publishedUntil, collectedSince, collectedUntil, limit (1–200, default 50), and cursor.
Pass nextCursor back unchanged. since/until filter collection checks;
publication filters independently select source publication times. This endpoint
reads stored evidence and performs no fresh collection. Use /v1/changes for
reliable delivery; record-list pagination is not a change stream.
Each compact envelope includes id, revisionId, source, url, optional author
and publication time, firstCollectedAt, lastCheckedAt, observedChangedAt,
a 500-character excerpt, truncated, detail, and available related content.
Unknown publication times remain absent. observedChangedAt is Argus's observed
change time, not a claimed source edit time.
GET /v1/records/:id
GET /v1/records/:id returns public evidence, media pointers, relations, and latest
engagement; private watch configuration and provider raw payloads are excluded.
It returns 404 when absent. offset and relatedOffset default to 0. Text pages
contain at most 16,384 characters; media and relation pages each contain at most
50 entries. Follow pagination.nextOffset and pagination.nextRelatedOffset.
The response reports total lengths and pagination.truncated.
GET /v1/records/:id/conversation
GET /v1/records/:id/conversation returns the root record, the latest ranked X reply sample with hydrated reply records, and bounded snapshot history. History accepts limit (1–100, default 20) and an opaque cursor.
Fetch each reply through the detail route.
curl -H "Authorization: Bearer $ARGUS_API_TOKEN" \
"$ARGUS_URL/v1/records?source=x&since=2026-08-29T00%3A00%3A00.000Z&limit=50"
curl -H "Authorization: Bearer $ARGUS_API_TOKEN" \
"$ARGUS_URL/v1/records/$RECORD_ID/conversation"GET /v1/artifacts
GET /v1/artifacts?kind=summary&limit=20 returns derived artifacts with exact
record/media provenance.
POST /v1/summaries
POST /v1/summaries accepts query, watchIds, limit, and prompt. It
requires enabled OpenRouter intelligence and stores a summary artifact.
POST /v1/query
POST /v1/query accepts a required question and optional watchIds, since,
until, and limit (1–100). It selects recent matching context, produces a
sourced OpenRouter answer, stores an answer artifact, and returns numbered
source links. Both summaries and answers include each selected root's latest
bounded reply sample when available, and store the exact snapshot/reply IDs in
artifact provenance. The CLI command is the easiest client:
argus query latest-news --watch=screen-news --since=2026-08-29T09:00:00.000Z --until=2026-08-29T18:00:00.000Z --limit=50 --json
curl -X POST -H "Authorization: Bearer $ARGUS_API_TOKEN" \
-H 'content-type: application/json' \
--data '{"question":"new listings since 9am","watchIds":["listings"],"since":"2026-08-29T09:00:00.000Z"}' \
"$ARGUS_URL/v1/query"POST /v1/watches/:watchId/ingest
POST /v1/watches/:watchId/ingest queues each target in an enabled watch and
returns 202 with {queued, watchId, requests}. Consumers may ingest only their own
watches; each request is subject to collection quotas.
GET /v1/primitives/x/*
GET /v1/primitives/x/2/* proxies a normalized /2/ path to the configured
FxEmbed origin. Query parameters pass through. The agent cannot provide a host.
Only GET and HEAD are supported; response bodies are capped at 2 MiB,
same-origin redirects at five, requests at ten seconds, and each token/source
at 60 calls per minute. Every public DNS answer is validated and pinned again
for every redirect hop.
HEAD /v1/primitives/x/*
HEAD uses the same fixed-origin, path, authentication, redirect, timeout, and rate limits as GET, but returns no response body.
curl -H "Authorization: Bearer $ARGUS_API_TOKEN" \
"$ARGUS_URL/v1/primitives/x/2/conversation/1900?cursor=next"Primitive output is transient: Argus does not write records, checkpoints, artifacts, or jobs for this request.
GET /v1/primitives/web/search
GET /v1/primitives/web/search?q=... calls only the configured SearXNG service
and forces format=json. Public endpoints receive DNS/private-address validation
on every hop; only endpoints explicitly marked searchEndpointTrust: trusted
may use a private operator-controlled network. Optional allowlisted parameters
are engines, categories, language, time_range, and pageno; every other
parameter is rejected. It uses the same authentication, body, redirect, timeout,
and rate bounds and also writes nothing.
curl -H "Authorization: Bearer $ARGUS_API_TOKEN" \
"$ARGUS_URL/v1/primitives/web/search?q=new+movies"POST /v1/diagnostics/smoke-watches
Creates a temporary watch for argus doctor. Its records are isolated from
normal watches.
GET /v1/diagnostics/smoke-watches/:id/records
Returns records collected for one temporary smoke watch.
DELETE /v1/diagnostics/smoke-watches/:id
Removes the temporary watch and its isolated records.
POST /v1/management/config/plan
Previews the managed configuration operations used by the CLI. The result includes
planId, baseContentHash, desiredContentHash, and removals with each removed
watch ID and optional owner.
POST /v1/management/config/apply
Applies a previously planned managed configuration change. The exact preview is required; a changed applied snapshot or edited preview returns 409.
POST /v1/management/config/verify
Verifies the resulting managed deployment. Management routes require an exact configured bearer token; prefer the CLI rather than calling them directly.
Consumer watches and configuration
| Endpoint | Behavior |
|---|---|
GET /v1/watches | List your watches, including disabled watches; limit 1–100 (default 50), offset default 0, and nextOffset for more. |
POST /v1/watches | Create a watch; return 201. |
PUT /v1/watches/:id | Replace a watch using its complete configuration. |
DELETE /v1/watches/:id | Disable future collection; preserve evidence. |
GET /v1/config/export | Export your watches and quotas without credentials. |
POST /v1/management/config/export | Operator-only export of the applied configuration. |
Watch bodies use the configuration schema: id, schedule,
inputs, optional enabled (default true), and classify. Ownership is assigned
to the authenticated consumer. A consumer cannot transfer ownership, read another
consumer's watch, or mutate it. Duplicate IDs and concurrent configuration changes
return 409; exhausted watch capacity returns 429 with error: "watch_quota".
argus config export includes agent-created watches in the same applied snapshot
used by operator previews. Exported credentials must be restored from secret
references before reapplying.
Fresh collection
POST /v1/collections
POST /v1/collections returns a durable request immediately (202), or a throttled
request (429). JSON request bodies are capped at 65,536 bytes.
{
"source": "x",
"target": { "kind": "post", "value": "1900000000000000000" },
"coverage": { "linkedArticles": 0, "replies": 20, "media": false },
"maxAgeSeconds": 60,
"priority": "interactive"
}| Field | Accepted values and defaults |
|---|---|
source | x, telegram, or web; the source must be enabled. |
target.kind | X: post, account, query; Telegram: channel; web: url, feed, query. |
target.value | Nonempty string, at most 4,096 characters. X posts accept IDs or public X/Twitter post URLs. Accounts/channels omit @. Web URLs must be HTTP(S) without credentials. |
coverage.linkedArticles | 0–10, default 0; follows available linked article relations. |
coverage.replies | 0–200, default 0; bounded X reply sampling. |
coverage.media | Boolean, default false; available media metadata only. Binary extraction is unsupported. |
maxAgeSeconds | 0–86,400, default 0; acceptable reuse age. |
priority | interactive (default) or background. |
Root evidence is always requested. Root URL/post collection is bounded to one root; account, channel, feed, and query collection to 100 source items. Requested expansion can remain missing: inspect the receipt instead of assuming complete coverage. Background jobs receive scheduling turns alongside interactive work. Equivalent requests share upstream work when target, coverage, and freshness requirements permit; each consumer retains its own request and cancellation.
| Endpoint | Behavior |
|---|---|
GET /v1/collections | Your requests; limit 1–100 (default 50), opaque cursor. |
GET /v1/collections/:id | Request status and available partial receipt. |
GET /v1/collections/:id/receipt | Receipt, or 202 with receipt: null while unavailable. |
PATCH /v1/collections/:id | Change a queued request's priority; returns 409 when no longer queued. |
DELETE /v1/collections/:id | Cancel your unsettled request; other consumers' shared work continues. |
Request status is queued, running, complete, failed, cancelled, or
throttled. Requests expose stable id, workId when attached, reused,
remainingRequests, and optional throttleReason: request_quota, active_jobs,
or minimum_refresh. Receipts identify checked sources, start/completion times,
requested and obtained coverage, missing coverage, truncation, failures, and exact
recordId/revisionId pairs. Receipt revisions are paginated in groups of 100;
pass pagination.nextOffset as offset to the receipt endpoint. Request lists
include receiptUrl rather than embedded receipts. Partial evidence remains
reusable after failures.
Default consumer limits are 100 enabled watches, 60 requests per hour, four active jobs, 60 upstream requests per hour, and a 60-second minimum refresh interval. Configure these independently in consumer configuration. Reuse counts as a consumer request, without counting as another upstream fetch.
Immutable revisions
GET /v1/records/:id/revisions
GET /v1/records/:id/revisions lists revision metadata using limit 1–100
(default 50) and an opaque cursor.
GET /v1/records/:id/revisions/:revisionId
This endpoint retrieves that exact revision with the
same offset/relatedOffset bounds as record detail. Unknown or expired revisions
return 410 with error: "REVISION_UNAVAILABLE"; current content is never
substituted for an unavailable historical revision.
Durable changes and resume
GET /v1/changes
GET /v1/changes accepts an opaque cursor, limit 1–200 (default 50), and
repeated type, source, and recordId filters (at most 100 record IDs). Without
an explicit cursor it uses your saved delivery position.
PUT /v1/changes/cursor
Save progress only after processing the page using {"cursor":"..."}.
cursor=latest obtains a starting position for future changes.
Event types are record.created, record.revised, reply.sampled,
engagement.updated, record.deleted, job.completed, and source.health.
Delivery ordering is independent of publication time. Use stable event IDs and
record/revision IDs to handle repeated pages safely. Unchanged checks do not
create content revision events, and failed fetches do not imply deletion.
An expired cursor returns 410 with error: "CHANGE_CURSOR_EXPIRED" and explicit
resynchronization links. Save a new latest cursor first, scan stored records, then
resume from that cursor; deduplicate any overlap. Event retention defaults to 30
days; record and revision retention each default to 90 days.
Usage and health
GET /v1/usage
GET /v1/usage reports your requests, reuse, throttling, upstream fetches, active
jobs, and request quotas. Optional since is a UTC timestamp; the default window
is the previous hour.
GET /v1/sources/health
This endpoint accepts limit 1–100 (default 50) and an opaque cursor.
It reports an opaque target ID, source status, check time, successful-check time
when known, consecutive failures, and lagSeconds since success (null when
unknown). Private target configuration and provider errors are excluded. Health
transitions are delivered through source.health events, separating a quiet
source from an unavailable one. Collection, revision retrieval, delivery, and
health require no LLM calls.
collectedSince and collectedUntil filter first collection time; since and until filter the last check. Scalar fields shortened for response limits report truncatedFields; text and related arrays use explicit pagination. Watch lists accept offset and limit (1–100). /v1/usage includes remaining request, upstream, and active-job capacity for the current hour.