REST API¶
Use the REST API to call financial and personal tools over HTTP and JSON. Start with the current OpenAPI schema and the authentication method supported by your tool.
Owned CLI sessions send an opaque registered Argus session as Bearer. The API uses its configured identity component and fixed API audience, without session decryption keys or upstream secrets. MCP sessions are rejected. Existing explicit OAuth and approved machine credentials retain their governed compatibility path. See session protocol.
REST exposes the same financial and personal tool contracts as CLI and MCP under
/v1. The 20 consumer tools are not REST
endpoints; they exist only on the OAuth MCP endpoint. Use exactly one
supported credential. OAuth identities are server-managed;
private personal tools additionally require registered personal authorization
and current domain consent, which a machine API key alone cannot establish.
Use https://api.argusfa.com/openapi.json for executable request schemas. Send
either Authorization: Bearer <API-audience token> or X-Argus-API-Key as a
header. With OAuth omit institution_id and caller_id from the JSON body.
Apply the REST binding's parameter aliases and encodings: filters_json and
sort_json become filters and sort JSON arrays; feature facts_json,
nodes_json, and limits_json become facts, nodes, and limits JSON
arrays/objects; observations_json becomes an observations JSON array.
REST array parameters are arrays, not comma-separated strings.
Ordinary-user OAuth requests¶
Install the official wheel and run argus auth login, then argus auth status.
The installed package's managed_client helper also supports REST clients:
access_token() reads the same resource/profile-specific OS credential entry
as the official CLI. Upstream refresh stays in the identity component. It returns
None when login is required. Keep the opaque credential in
process memory; do not print it, copy it into configuration, or export the
credential store. This uses the API audience; it cannot authenticate MCP.
import json
from urllib.request import Request, HTTPRedirectHandler, build_opener
from argus.cli.oauth import CliOAuthProfile
from argus.cli.managed_oauth import managed_client
profile = CliOAuthProfile.from_environment()
token = managed_client(profile, "api").access_token()
if token is None:
raise RuntimeError("Run argus auth login first")
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, *args, **kwargs):
return None
request = Request(
profile.api_base_url + "/v1/entity-search",
data=json.dumps({"query": "HWUPKR0MPOU8FGXBT394",
"purpose": "factual_lookup"}).encode(),
headers={"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
"User-Agent": "Argus REST client"},
method="POST",
)
# Disable redirects so authorization is never forwarded to another origin.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
envelope = json.load(response)
The LEI is a real GLEIF subject, not a demo issuer. This request shows the
ordinary REST authentication path; its returned coverage, facts and evidence
must still be checked. HTTP 200 or success=true alone does not establish a
complete business result. Use the public Registry and OpenAPI to choose the
actual REST endpoint and arguments for each capability. Preserve audit_id,
check result_status and the expected record counts, and call the documented
source-evidence endpoint for returned evidence references. A 401 requires login
or refresh; a 403 requires the requested signed tool scopes or caller ownership.
Do not retry an authorization failure with fabricated institution/caller IDs.
Requests are structured JSON. Legacy financial fields include purpose, as_of,
and requires_redistribution; they are not common fields on personal requests.
Personal notes may contain labelled untrusted user text, never executable
instructions. Tool-specific schemas are generated from the Registry and listed
in Generated Interface Contracts.
The neutral session package endpoint accepts explicit market, session, session_date, and symbols. Universe and filter state belong to the caller or external configuration.
Successful legacy financial calls return a CliToolEnvelope containing the
typed result, evidence and governance metadata, plus an audit identifier.
Registry discovery returns an AgentToolRegistrySnapshot directly; it does not
have the business envelope's success, result, or audit_id fields.
Missing business coverage is coded as empty, partial, or unavailable.
Personal calls instead return a tool-specific personal-result-v1 response:
check HTTP status, then problem, payload, audit_id and the declared result
schema. Follow each financial child package's evidence and coverage separately.
Private object data retains its own user provenance. See
personal contracts and the matching
CLI/REST/MCP examples.
Availability preflight¶
agent_data_preflight is a diagnostics tool and needs an explicit signed grant.
The current implementation checks the authenticated caller's current
target-tool policy for the actual interface and scopes. A known
tool name is insufficient. The supported probes perform bounded reads through
their shared business boundary, producing ordinary target-call audit records:
| Target tools | subjects identifiers |
|---|---|
company_fact_snapshot, fundamental_facts, insider_transactions, news_discovery, ir_material_search, event_timeline, corporate_actions, point_in_time_snapshot |
Company IDs accepted by the target's company_id parameter |
market_bars, equity_market_data, market_quote, market_trades, etf_data |
Permanent security IDs accepted by the target's security_id parameter |
Preflight does not infer company or permanent security IDs from tickers. These probes use the target's remaining argument defaults; they do not verify a custom query, expiration, record type, or other argument combination that preflight cannot supply. Quote, trade and intraday capture is disabled (ADR 0008), and OAuth callers read only consumer-visible sources (see API overview).
Each requested field must have visible evidence and temporal records for every
subject. Duration intervals must cover the requested range without a gap;
instant records prove only their instant. A partial or capped target result,
late capture, missing subject, or unknown permission cannot yield
preflight.allowed=true. Up to 32 subjects are probed; a larger request retains
an explicit coverage gap and cannot pass. The result records measured time,
observed subject count and latest known time without claiming a freshness SLO.
Other targets currently report target_query_arguments_not_verified rather
than infer availability from unrelated filing data. Their target-specific probes
remain unfinished. A successful preflight is a measurement at that call, and
does not reserve provider quota or guarantee a later source revision.
Preflight returns an audit-specific metadata evidence locator. Once its audit is
successful, source_evidence_lookup retrieves that caller's exact archived
public metadata, with checksum verification and no internal storage address.
Use a lookup cutoff after the measurement completed; the financial range under
inspection may precede the time Argus computed the preflight. This projection
proves the recorded measurement, and is not a new financial observation.
Evidence bundles from a real call¶
In the deployed implementation, a nonempty result is archived only after
permission, license and public-output governance. Its public source package ID
is data_package: followed by that result's audit_id. Supply this ID as
source_package_id to the Registry binding for evidence_bundle_export using
the same authenticated caller and institution. The same rule applies to CLI and
MCP results; there is no public data_package_id field to guess.
The export verifies the successful source audit, reads the actual persisted public result and checks its byte length and SHA-256. It returns the original facts and evidence plus a manifest containing the source package ID, checksum, byte length, counts and evidence IDs. The checksum covers the canonical UTF-8 JSON of the original governed result, not the input ID string or the new bundle wrapper. A source that was empty, unavailable, failed, belongs to another caller or was never archived cannot produce a verified bundle. Older 1.1.7 calls were not archived and cannot be reconstructed from their shortened audit summaries.
Keep the original JSON response to verify its checksum independently. The
canonical input is the governed DataPackage in the envelope's result, excluding
the envelope and the later bundle's manifest:
import hashlib
import json
source_package_id = "data_package:" + source_response["audit_id"]
original_bytes = json.dumps(
source_response["result"], ensure_ascii=False, sort_keys=True,
separators=(",", ":"),
).encode("utf-8")
expected_sha256 = hashlib.sha256(original_bytes).hexdigest()
Compare this value with the exported fact named
evidence_bundle.content_hash_sha256. This snippet performs local verification;
source_response must come from the actual successful authenticated call.
The source result's coverage status and license restrictions remain attached.
include_restricted=true never expands the stored public projection or opens
controlled source text. Evidence lookup uses each returned locator and the
original result's effective_as_of; a later revision may require that historical
cutoff. Internal object-storage addresses are never export destinations. These
rules describe prepared source behavior; they do not establish deployment or
complete data coverage.
The personal endpoints support authorized private reads/writes; sensitive account actions use the separate trusted management API. Financial responses remain structured facts and calculations, without generated recommendations, trading strategies, orders or agent orchestration. Retired endpoint mappings remain in the Registry's structured major-version migration manifest.