What is Argus?

Argus checks whether an LLM's response is factually accurate. You submit a question and an AI-generated answer; Argus finds evidence, evaluates each claim, and returns a verdict with a confidence score. This doc covers the REST API.

Prerequisites

Before you call Detect or Observe, get an API key through AWS Marketplace registration. Detect and Observe require authentication on every request. Playground accepts an API key optionally — you can call it anonymously (rate-limited) or with a key.

How to get an API key

Subscribe to Argus on AWS Marketplace.
Marketplace redirects you to the Argus registration site with a one-time registration token.
Argus exchanges that token for your AWS buyer identity and completes registration.
After registration succeeds, Argus issues your API key (typically prefixed ts_api_).

Keep the key secret. You only need it to authenticate API calls. Subscription status is tracked separately and is not required for using the key in the Playground or client code.

Using the API key

Send it on Detect / Observe requests as either:

x-api-key: ts_api_… (preferred), or
Authorization: Bearer ts_api_…

In the Playground, click Authorize and paste the key once per browser tab (required for Detect / Observe; optional for playground).

API key is optional in playground: omit it to run anonymously with X-Device-ID (rate-limited), or send a key for signed-in usage. Detect / Observe without a key return 401 Unauthorized.

APIs

Argus exposes Detect and Observe as product APIs (API key required).

Detect — create and retrieve fact-checking submissions (POST /detect, GET /detect/{submission_id}, GET /detect).
Observe — fetch an aggregated quality report for a date range (GET /observe).

Quick Start

This guide walks you through a complete hallucination detection request — from submitting a query to reading the verdict — in under five minutes.

Detection is asynchronous. When you POST a request, Argus immediately returns a submission_id and starts processing in the background. You then poll the GET endpoint every few seconds until the status flips to completed.

The flow: POST /detect → GET /detect/{submission_id} → read results

Step 1 — Submit a detection request

Send the original user question (query_text) and the AI-generated answer you want to check (response_1). Both are required.

import httpx, time

client = httpx.Client(
    base_url="https://api.trustscale.ai",
    headers={"x-api-key": "YOUR_API_KEY"},
    timeout=120.0,
)

payload = {
    "input": {
        "query_text": "Who won the 2024 US presidential election?",
        "response_1": "Donald Trump won the 2024 US presidential election.",
        "answer_date": "2026-01-15",
    },
    "locale": "en_US",
    "external_group_id": "quickstart-test",
}

response = client.post("/detect", json=payload)
submission_id = response.json()["submission_id"]
print(f"Submitted. ID: {submission_id}")

Step 2 — Poll for results

Most requests complete in 10–30 seconds. Poll every 3 seconds and stop when status is completed. If 2 minutes pass without a result, re-submit the original POST.

for _ in range(40):  # max ~2 min
    result = client.get(f"/detect/{submission_id}").json()
    if result["status"] == "completed":
        print("Done!")
        break
    time.sleep(3)
else:
    raise TimeoutError("Detection timed out after 2 minutes.")

Step 3 — Read the verdict

Each claim in the AI response is evaluated separately. For each one, Argus returns a verdict, a confidence score between 0 and 1, and the web evidence used to reach that verdict.

for claim in result["results"]["claims"]:
    print(claim["claim_text"])
    print(f"  Verdict:    {claim['verdict']}")
    print(f"  Confidence: {claim['confidence']}")
    for e in claim["evidence"]:
        print(f"  Source: {e['domain']} — {e['snippet'][:80]}…")

Example response

This is what GET /detect/{submission_id} returns once processing finishes.

{
  "submission_id": "3361679b-057a-49de-8903-07eb704774b1",
  "status": "completed",
  "locale": "en_US",
  "external_group_id": "quickstart-test",
  "created_at": "2026-01-15T14:32:00Z",
  "input": {
    "query_text": "Who won the 2024 US presidential election?",
    "response_1": "Donald Trump won the 2024 US presidential election.",
    "answer_date": "2026-01-15"
  },
  "results": {
    "overall_verdict": "supported",
    "overall_confidence": 0.98,
    "claims": [
      {
        "claim_text": "Donald Trump won the 2024 US presidential election.",
        "verdict": "supported",
        "confidence": 0.98,
        "evidence": [
          {
            "domain": "apnews.com",
            "source_url": "https://apnews.com/article/2024-election-results",
            "snippet": "Donald Trump defeated Kamala Harris in the 2024 presidential election, winning both the Electoral College and popular vote.",
            "relevance_score": 0.96
          },
          {
            "domain": "reuters.com",
            "source_url": "https://reuters.com/world/us/trump-wins-2024",
            "snippet": "Republican Donald Trump won the U.S. presidential election on Tuesday...",
            "relevance_score": 0.94
          }
        ]
      }
    ]
  }
}

Verdict values: supported (evidence confirms the claim), unsupported (evidence contradicts it), or unverifiable (not enough sources found to decide either way).

Confidence score: A score close to 1.0 means Argus found strong, consistent evidence — not that the claim is necessarily true. A low score on a supported verdict means the evidence was thin.

Detect

Detect creates and retrieves verification submissions. Create is asynchronous: POST /detect returns a submission_id; poll GET /detect/{submission_id} until status is completed.

POST /detect

Create a fact-check submission. JSON body is proxied to the upstream fact-checking service. On success you will receive status: "accepted" and a submission_id. The gateway generates input.uid automatically — do not send it.

POST /detect

Headers

Name		Description
`x-api-key` or `Authorization`	required	API key for authentication.
`Content-Type`	required	Must be `application/json`.

Body parameters

Field		Type	What it means
`input.query_text`	required	string	The user prompt / question that the assistant answered. Used as context for fact-checking.
`input.response_1`	required	string	The assistant response text to evaluate for factual claims.
`input.answer_date`	optional	string (YYYY-MM-DD)	When the answer was produced. Used as temporal context for evidence retrieval.
`locale`	optional	string	Locale for processing. Defaults to `en_US` if omitted.
`external_group_id`	optional	string	Project / batch / group id. Used to list and aggregate related submissions later.
`client_metadata`	optional	object	Free-form JSON object you can attach (task ids, source tags, etc.). Echoed back on responses.
`blocked_sources.domains`	optional	string[]	Domains to exclude from evidence search (e.g. `["example.com"]`).
`blocked_sources.patterns`	optional	string[]	URL / path patterns to exclude from evidence (e.g. `["/blog/*"]`).

Example

import httpx

client = httpx.Client(
    base_url="https://api.trustscale.ai",
    headers={"x-api-key": "YOUR_API_KEY"},
    timeout=120.0,
)

payload = {
    "input": {
        "query_text": "Who won the 2024 US presidential election?",
        "response_1": "Donald Trump won the 2024 US presidential election.",
        "answer_date": "2026-01-15",
    },
    "locale": "en_US",
    "external_group_id": "test-group",
    "client_metadata": {"source": "manual-test"},
    "blocked_sources": {
        "domains": ["example.com"],
        "patterns": ["/ads/*"],
    },
}

created = client.post("/detect", json=payload)
print(created.status_code, created.json())
# Use created.json()["submission_id"] with GET /detect/{submission_id}

const payload = {
  input: {
    query_text: "Who won the 2024 US presidential election?",
    response_1: "Donald Trump won the 2024 US presidential election.",
    answer_date: "2026-01-15",
  },
  locale: "en_US",
  external_group_id: "test-group",
  client_metadata: { source: "manual-test" },
  blocked_sources: {
    domains: ["example.com"],
    patterns: ["/ads/*"],
  },
};

const response = await fetch("https://api.trustscale.ai/detect", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
    Accept: "application/json",
  },
  body: JSON.stringify(payload),
});

const data = await response.json();
console.log(data);
// Then poll GET /detect/{data.submission_id}

curl -s -X POST 'https://api.trustscale.ai/detect' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
  "input": {
    "query_text": "Who won the 2024 US presidential election?",
    "response_1": "Donald Trump won the 2024 US presidential election.",
    "answer_date": "2026-01-15"
  },
  "locale": "en_US",
  "external_group_id": "test-group",
  "client_metadata": {"source": "manual-test"},
  "blocked_sources": {
    "domains": ["example.com"],
    "patterns": ["/ads/*"]
  }
}'

Accepted response fields

Field		Type	What it means
`submission_id`	required	string	Id to pass to `GET /detect/{submission_id}` when polling for results.
`status`	required	string	Lifecycle status (e.g. `accepted`, later `completed` on GET).
`input_kind`	optional	string	How the input was classified (e.g. single-turn record).
`created_at`	optional	string	Creation timestamp from upstream.
`locale` / `external_group_id` / `client_metadata`	optional	various	Echoed values from the create request.

GET /detect/{submission_id}

Fetch one submission by id. When processing is finished, the body includes the input record and claim-level results (verdict, confidence, evidence, sources).

GET /detect/{submission_id}

Path parameters

Field		Type	What it means
`submission_id`	required	string (path)	The id returned by `POST /detect`.

Example

import httpx

client = httpx.Client(
    base_url="https://api.trustscale.ai",
    headers={"x-api-key": "YOUR_API_KEY"},
    timeout=120.0,
)

submission_id = "3361679b-057a-49de-8903-07eb704774b1"
result = client.get(f"/detect/{submission_id}")
print(result.status_code, result.json())

const submissionId = "3361679b-057a-49de-8903-07eb704774b1";

const response = await fetch(`https://api.trustscale.ai/detect/${submissionId}`, {
  method: "GET",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    Accept: "application/json",
  },
});

console.log(await response.json());

curl -s 'https://api.trustscale.ai/detect/3361679b-057a-49de-8903-07eb704774b1' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Accept: application/json'

GET /detect

List submissions with optional group filter and pagination. Useful for browsing a project keyed by external_group_id.

GET /detect

Query parameters

Field		Type	What it means
`external_group_id`	optional	string (query)	Filter submissions belonging to this group / project.
`limit`	optional	integer (1–500)	Page size. Default `50`.
`offset`	optional	integer (≥ 0)	Number of items to skip for pagination. Default `0`.

Example

import httpx

client = httpx.Client(
    base_url="https://api.trustscale.ai",
    headers={"x-api-key": "YOUR_API_KEY"},
    timeout=120.0,
)

listed = client.get(
    "/detect",
    params={
        "external_group_id": "test-group",
        "limit": 50,
        "offset": 0,
    },
)
print(listed.status_code, listed.json())

const url = new URL("https://api.trustscale.ai/detect");
url.searchParams.set("external_group_id", "test-group");
url.searchParams.set("limit", "50");
url.searchParams.set("offset", "0");

const response = await fetch(url, {
  method: "GET",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    Accept: "application/json",
  },
});

console.log(await response.json());

curl -s 'https://api.trustscale.ai/detect?external_group_id=test-group&limit=50&offset=0' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Accept: application/json'

Observe

Observe returns an aggregated quality / trust report for the authenticated user over a date range. The gateway resolves user_id from the API key session and queries upstream observe sources.

GET /observe

Fetch the observe report for date_from … date_to (inclusive calendar dates). Both query parameters are required.

GET /observe

Headers

Name		Description
`x-api-key` or `Authorization`	required	API key. Used to authenticate and resolve the user for the report.

Query parameters

Field		Type	What it means
`date_from`	required	string (YYYY-MM-DD)	Start of the reporting window (inclusive).
`date_to`	required	string (YYYY-MM-DD)	End of the reporting window (inclusive).

Example

import httpx

client = httpx.Client(
    base_url="https://api.trustscale.ai",
    headers={"x-api-key": "YOUR_API_KEY"},
    timeout=120.0,
)

report = client.get(
    "/observe",
    params={
        "date_from": "2026-01-01",
        "date_to": "2026-01-31",
    },
)
print(report.status_code, report.json())

const url = new URL("https://api.trustscale.ai/observe");
url.searchParams.set("date_from", "2026-01-01");
url.searchParams.set("date_to", "2026-01-31");

const response = await fetch(url, {
  method: "GET",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    Accept: "application/json",
  },
});

console.log(await response.json());

curl -s 'https://api.trustscale.ai/observe?date_from=2026-01-01&date_to=2026-01-31' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Accept: application/json'

Error codes

Argus uses standard HTTP status codes. The table below covers the ones you're most likely to encounter.

Code	Meaning	What to do
`200`	Success	Request completed. Read the response body.
`401`	Unauthorized	Your API key is missing, malformed, or invalid. Check that you're sending `x-api-key: ts_api_…` on every request.
`403`	Forbidden	Your key is valid but your subscription doesn't cover this endpoint. Verify your AWS Marketplace subscription is active.
`429`	Rate limit exceeded	You've sent too many requests. Wait a few seconds and retry. Use exponential backoff if this happens repeatedly.
`500`	Internal server error	Something went wrong on Argus's side. Wait 5–10 seconds and retry the same request. If it persists, contact support.
`503`	Service unavailable	Argus is temporarily down or overloaded. Retry with backoff.

On 401 specifically: Detect and Observe always require a key — there is no anonymous fallback. Demo accepts requests without a key (rate-limited), so a 401 on /demo means you sent a key that was rejected, not that you forgot to include one.