Skip to content

Version 1.1.8 ยท Last updated

Getting started

This guide takes an AI agent from authentication to a verified factual response. Interactive OAuth is the default; machine API keys remain available for machine clients and service accounts. For local development, see Deployment.

1. Choose an interface

Interface Use it when Authentication Result
CLI A shell-based AI agent needs JSON on stdout Casdoor OAuth login JSON CliToolEnvelope
REST A service already uses HTTP/JSON OAuth Bearer or X-Argus-API-Key JSON CliToolEnvelope
MCP An MCP client discovers and invokes tools OAuth against the MCP resource Structured JSON tool result

All three interfaces enter the same CoreServiceBoundary with permission, tool-whitelist, tenant, license, output-policy, and audit checks. OAuth does not bypass this chain. License enforcement follows the configured runtime switches; the shipped configuration records license decisions without blocking calls (see license model). The CLI's signed argus:tools:public scope grants all 52 governed public business tools, including metric_catalog and the five bounded stream_* tools. Registry discovery is public. Check the required signed scopes and the permission_requirements.default_oauth_access metadata before calling a tool. See OAuth authorization.

2. Sign in

argus auth login
argus auth status

The CLI uses Authorization Code + PKCE S256 and the operating-system credential store. It never stores a client secret. Machine clients should keep API keys in a secret manager and explicitly set ARGUS_BASE_URL.

3. Discover tools before calling one

The public registry requires no tool execution and describes every supported binding, parameter, permission scope, return contract, prohibited capability, safe alternative, and deprecation state.

curl -fsS https://api.argusfa.com/v1/tool-registry

Start with company_fact_snapshot for disclosed facts, filing_search for cited filing fragments, or agent_data_preflight when the requested fields, time range, license, or permission status is uncertain.

4. Make the first request

argus --base-url https://api.argusfa.com entity-resolve \
  --identifier-type lei \
  --identifier-value HWUPKR0MPOU8FGXBT394 \
  --purpose factual_lookup

The CLI reads and refreshes the OAuth credential stored in step 2; it does not export access tokens into the shell. This request uses the current query time; historical requests require an aware ISO-8601 timestamp within verified coverage. Z means UTC. Unknown request fields are rejected instead of ignored.

The LEI identifies Apple Inc. in the official GLEIF records. Other real legal entities include Microsoft Corporation (INR2EJN1ERAN0W5ZP974) and Amazon.com, Inc. (ZXTILKJKG63JELOEG630). A legal entity is distinct from a listed security or SEC company ID: do not use a LEI as a ticker or a filing identifier. Inspect the returned facts, coverage and evidence, then carry returned identifiers into the appropriate downstream tool. These requests are reproducible inputs, not a claim that every production business result has passed acceptance. Resolve availability with agent_data_preflight; empty, partial and unavailable positive results remain coverage gaps until repaired.

Registry discovery proves that an invocation contract exists, not that its production data source is integrated. The current production PIT screening and export, strict security master, and stream bindings return unavailable when only local contract fixtures exist. Entity search/resolve/validate preserve persisted GLEIF legal entities, but do not use the built-in fictional security and ticker mappings. For company discovery use company_master; inspect each returned coverage code before choosing downstream calls. The prepared reader uses a captured SEC current ticker/exchange snapshot, with source CIK, issuer name, ticker and exchange label. It keeps the original listing_status_event.value.* field paths for evidence and license checks. An exchange label is not an ISO MIC, and a current snapshot does not establish past issuer/security relationships, country, industry or permanent security identity. These remain explicit gaps; the reader does not create master parent rows from defaults. This reader requires release and ordinary-user production verification; the currently deployed 1.1.7 service has not passed those checks. See PIT coverage and stream coverage.

5. Validate the response

Do not treat HTTP 200 alone as proof that data is usable. Validate the envelope and nested package:

success
  -> audit_id
  -> permission_result / license_status
  -> source_evidence
  -> output_restrictions
  -> result.data_quality
  -> result.known_time <= requested as_of
  -> every fact.evidence_ids entry exists in result.source_evidence

If data_quality.requires_human_review is true, route the package to review. If a license is restricted, preserve its field and redistribution restrictions in all downstream systems.

Evidence backed by private storage exposes evidence_lookup_id equal to its evidence_id in place of the internal storage URI. Preserve this opaque reference and source_file_id; use the authorized source_evidence_lookup tool for available evidence metadata. A reference does not grant access to controlled source text or promise a public download URL. Public packages can be parsed back into the DataPackage schema without private storage locators.

6. Handle failures by code

HTTP status Typical meaning Next action
400 Invalid arguments or a legacy policy error Correct the request using the machine-readable details
401 Missing, invalid, expired, or revoked credential; identity mismatch; rate limit Check the credential and its bound identity; rotate if needed
403 Permission, tenant, license, or output-policy denial Do not retry unchanged; request the required scope or change purpose/data
422 Request does not match the strict REST schema Correct field names, types, timestamps, or required values
500 Core operation failed after governance entry Record audit_id, stop blind retries, and investigate service health
503 Readiness or a required public artifact is unavailable Retry with backoff after checking health/operations status

Failure bodies are machine-readable. Persist the returned audit_id and error_code; do not parse the human message to drive control flow.

Next steps