FinanceSec API Reference

Welcome to the Financial SEC API reference. The FinanceSec engine leverages the Volumetric Lattice Network (VLN) to provide secure, deterministic answers to natural language questions about SEC 10-K, 10-Q, and 8-K filings.

The Zero Hallucination Guarantee

By using a physics-based lattice readout instead of probabilistic transformer generation, FinanceSec guarantees a 0.00% fabrication rate. Every fact returned includes a trace mapping directly back to the original filing location, page number, and SEC XBRL concept.

Authentication

API requests are authenticated using a license key passed in the header. To access restricted endpoints, you must include your key in the X-License-Key header of all outgoing requests.

X-License-Key: your_license_key_here

For browser dashboard integrations, requests use PQC (Post-Quantum Cryptography) Session JWTs issued via the /auth/verify endpoint.

Error Codes

The API returns standard HTTP status codes along with a structured JSON error body when calls fail.

Status	Error Code	Description
400	bad_request	Invalid payload, parsing failure, or syntax error.
401	unauthorized	Missing or invalid authentication credential.
402	payment_required	License key is required or subscription has expired.
403	forbidden	Endpoint access is restricted for the current plan tier.
429	too_many_requests	Daily API query capacity has been exceeded.

Health Check

GET /api/health

Get the current operational health state, API version, and server timestamp. This endpoint requires no authentication.

Retrieve Supported Companies

GET /api/companies

Returns the full array of SEC EDGAR companies supported by the model instance.

Query Parameters

Parameter	Type	Required	Description
q	string	No	Filter list matching ticker symbols or company names (prefix lookup).

Get Subscription Tiers

GET /api/tiers

Retrieves pricing configuration, query limits, support availability, and SLA metrics for the Hacker, Startup, Starter, Professional, and Enterprise plans.

Get Engine Statistics

GET /api/stats

Retrieve operational lattice metrics, answer rate ratios, target companies, and the test battery verification SHA-256 hash.

Submit SEC Query

POST /api/query

Query the VLN lattice for factual answers regarding SEC filings. The engine will decompose the prompt and match parameters. It will refuse to guess if no verifiable data is found.

Request Body

Property	Type	Required	Description
query	string	Yes	Natural language question about SEC filings.
max_results	integer	No	Maximum candidate matches to search. Defaults to 5.

Retrieve Provenance

GET /api/provenance/{id}

Fetch details of the cryptographic grounding trace for a specific facts entity, identifying the source filing, exact page location, and target XBRL concept.

Get Multi-Year Trends

GET /api/trends

Collects multi-year historical financial datasets for a specific company, including revenue, net income, and operating margins.

Query Parameters

Parameter	Type	Required	Description
company	string	Yes	Ticker symbol of the target company.

Submit Batch Job

POST /api/batch

Submit up to 100 queries for background processing. Available for Professional and Enterprise plans only.

Get Batch Status

GET /api/batch/{batch_id}

Poll the state and retrieve completed results of a background batch job.

Ingest Custom XBRL

POST /api/xbrl/ingest

Allows Enterprise customers to ingest raw SEC-style XBRL data dynamically to extend their lattice's knowledge base.

Manage API Keys

GET /api/keys

Retrieve and generate key credentials for programmatic organization access.

Manage Webhooks

GET /api/webhooks

Register and list webhook endpoints for notification of real-time SEC filing ingest events.

Export Audit Logs

GET /api/audit/export

Downloads organization log logs in JSON Lines format.

Create Organization

POST /api/org/create

Initializes a multi-seat organization with role mapping configuration.

PQC Hybrid Authentication Flow

The Developer Console uses a hybrid signature scheme to register and verify sessions, ensuring defense against future post-quantum threats.

Authentication Lifecycle Steps

1. Register an ML-DSA-65 public key in Firestore.

2. Retrieve a challenge nonce from the server.

3. Generate a signature locally using the private key and post it back to verify.

Register PQC Key

POST /auth/register-pqc-key

Registers the user's public post-quantum cryptographic key.

Request Challenge Nonce

POST /auth/challenge

Generates a transient challenge nonce linked to the user's account.

Verify Signature

POST /auth/verify

Verifies the ML-DSA challenge signature and returns a session token.