Skip to content

docs: clarify JavaScript SDK quickstart #17

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
daniel-scrivner wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: clarify JavaScript SDK quickstart #17

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 18 additions & 43 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,12 @@
# SEC API JavaScript SDK

`@secapi/sdk-js` is an ESM JavaScript and TypeScript client for retrieving SEC filings, filing sections, financial statements, and ownership data from [SEC API](https://secapi.ai/developers).
`@secapi/sdk-js` is the JavaScript and TypeScript client for retrieving source-backed SEC filings, filing sections, financial statements, and ownership data.

[Documentation](https://docs.secapi.ai) · [Get an API key](https://secapi.ai/signup) · [Support](https://github.com/secapi-ai/secapi-js/issues) · [Status](https://status.secapi.ai)

## Start here

Install the package and set an API key in server-side configuration:
## Install and retrieve a filing

```bash
npm install @secapi/sdk-js
export SECAPI_API_KEY="secapi_live_..."
export SECAPI_API_KEY="secapi_..."
```

Create `first-request.mjs`:
Expand All @@ -21,16 +17,23 @@ import { SecApiClient } from "@secapi/sdk-js"
const client = new SecApiClient()
const filing = await client.agentLatestFiling({ ticker: "AAPL", form: "10-K" })

console.log(filing.accessionNumber)
console.log({
accessionNumber: filing.accessionNumber,
filingDate: filing.filingDate,
filingUrl: filing.filingUrl,
requestId: filing.requestId,
})
```

Run `node first-request.mjs`. It prints the accession number for the latest matching Apple 10-K; this live value changes when a newer filing is available. `agentLatestFiling()` requests the endpoint's `agent` view. Use `latestFiling()` for the default endpoint response.
Run `node first-request.mjs`. It prints the current filing identity and request ID for Apple's latest matching 10-K. Those live values can change when a newer filing is available.

**Compatibility and support:** REST calls require Node.js 18 or newer. `streamFilings()` requires a global `WebSocket` (Node.js 21+, Bun, Deno, or browsers); Node.js 18 callers need a polyfill or a newer runtime. Read the [JavaScript SDK guide](https://docs.secapi.ai/javascript-sdk) for API details, and [open an issue](https://github.com/secapi-ai/secapi-js/issues) for SDK support.
`SecApiClient` sends `SECAPI_API_KEY` as `x-api-key` to `https://api.secapi.ai`. It wraps public REST endpoints; use the [hosted MCP server](https://docs.secapi.ai/mcp-install) separately when your client supports MCP. Keep API keys in server-side configuration and do not use a machine key as an `Authorization: Bearer` token.

## Common requests
## Compatibility and support

Node.js 18 or newer is required. `streamFilings()` needs a global `WebSocket` (Node.js 21+, Bun, Deno, or browsers); Node.js 18 callers need a polyfill or newer runtime. See the [JavaScript SDK guide](https://docs.secapi.ai/javascript-sdk) and [API reference](https://docs.secapi.ai/api-reference), check [status](https://status.secapi.ai), or [open an SDK issue](https://github.com/secapi-ai/secapi-js/issues).

The client also resolves issuers, searches filings, extracts sections, and returns normalized statements:
## Common requests

```js
const company = await client.resolveEntity({ ticker: "AAPL", view: "agent" })
Expand All @@ -54,15 +57,9 @@ const incomeStatements = await client.agentStatement("income_statement", {
})
```

Flat methods are the complete interface. Grouped aliases, including `client.filings.latest()` and `client.sections.latest()`, are available when they make editor discovery clearer.

## Factor response modes

Use `response_mode: "compact"` when you want the smallest useful payload. Compact catalog responses still include readiness/proof summaries. Set `include: "trust"` only when you need the full trust/provenance envelope plus full methodology/materialization/revision/source-rights objects for citations or checks. For catalog/tool-discovery calls, start narrow with `category` and `limit`; the full trust envelope can be larger than a simple picker payload.
Use `latestFiling()` for the default endpoint response and `agentLatestFiling()` for the endpoint-supported `agent` view. Preserve returned filing identifiers and request IDs with derived output.

## Configuration

`new SecApiClient()` reads `SECAPI_API_KEY` and sends it in the `x-api-key` header. `SECAPI_BASE_URL` and `SECAPI_API_BASE_URL` can override the default API origin, `https://api.secapi.ai`.
## Configuration, errors, and pagination

Pass values directly when environment variables are not appropriate:

Expand All @@ -73,29 +70,7 @@ const client = new SecApiClient({
})
```

Keep API keys out of browser bundles and client-side configuration. The SDK also accepts a bearer token for signed-in account endpoints through `bearerToken` or `SECAPI_BEARER_TOKEN`.

## Errors and pagination

API failures throw `SecApiError`, which includes `status`, `code`, and `requestId` when the service supplied one. Include the request ID in a support report.

Cursor-backed endpoints can be consumed as async iterators:

```js
for await (const filing of client.paginateFilings({
ticker: "AAPL",
form: "10-K",
limit: 100,
})) {
console.log(filing.accessionNumber)
}
```

Read methods (`GET`, `HEAD`, and `OPTIONS`) retry network errors and HTTP `408`, `429`, `502`, `503`, and `504` within a bounded policy. A `429` that the API does not mark non-retryable is retried for every method by default, including mutations; pass `retry: false` per call to disable it, or set it on the client to disable retries by default. Other mutation retries require `{ retry: { enabled: true, idempotencyKey: "..." } }`; use that only with a stable key and replay-safe application handling. See the [SDK reliability guide](https://docs.secapi.ai/sdk-reliability) for retry and streaming details.

## Reference

See the [JavaScript SDK guide](https://docs.secapi.ai/javascript-sdk) for endpoint behavior and the [API reference](https://docs.secapi.ai) for parameters and response fields.
`SECAPI_BASE_URL` and `SECAPI_API_BASE_URL` can override the default origin. API failures throw `SecApiError`, including `status`, `code`, and `requestId` when supplied. Cursor-backed endpoints can be consumed as async iterators; see the [SDK reliability guide](https://docs.secapi.ai/sdk-reliability) for retry and streaming behavior.

## License

Expand Down