Skip to content

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.