Skip to main content

​
JavaScript SDK

The JavaScript SDK is the fastest way to wire SEC API into TypeScript services, server actions, cron jobs, and product backends without hand-rolling request headers or metadata plumbing.

​
Install in Three Steps

1

Install the package

Install the public npm package.
2

Set the API key

Export SECAPI_API_KEY in the runtime where the code will run.
3

Verify one real investor workflow

Resolve an issuer, fetch a filing, and run one semantic investor workflow before you move to production.
npm install @secapi/sdk-js
The SDK mirrors the same endpoints and x-api-key authentication as the REST examples below.

​
What this API is good for

Application backends

Use the SDK when you want the public REST contract with less boilerplate and better ergonomics in app code.

Enrichment jobs

Good for filing enrichment, artifact generation, and scheduled data workflows.

Team tools

Resolve entities, inspect freshness, and retrieve filings without building a wrapper first.

Agent handoff

Start from a prompt and keep the metadata trail intact all the way through your coding agent.

​
First useful calls with REST

const headers = { "x-api-key": process.env.SECAPI_API_KEY! }

async function getJson<T>(path: string): Promise<T> {
  const response = await fetch(`https://api.secapi.ai${path}`, { headers })
  if (!response.ok) throw new Error(`${response.status} ${await response.text()}`)
  return response.json() as Promise<T>
}

const issuer = await getJson("/v1/entities/resolve?ticker=AAPL")
const filings = await getJson("/v1/filings?ticker=AAPL&form=10-K&limit=3")
const statements = await getJson("/v1/statements/all?ticker=AAPL&period=annual&limit=1")
const market = await getJson("/v1/market/snapshots?symbols=AAPL")

const answerResponse = await fetch("https://api.secapi.ai/v1/intelligence/query", {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    query: "Decompose AAPL's last 6M return into factors, macro drivers, filing-specific risks, then suggest hedges.",
    entities: ["AAPL"],
    lookback: "6m",
    responseMode: "compact_json_and_md",
  }),
})
const answer = await answerResponse.json()

​
SDK shape

The public SDK package name is @secapi/sdk-js: 
import { SecApiClient } from "@secapi/sdk-js"

const client = new SecApiClient({ apiKey: process.env.SECAPI_API_KEY! })
const filing = await client.latestFiling({ ticker: "AAPL", form: "10-K" })

​
Reliability defaults

The JavaScript SDK retries transient failures with exponential backoff and a per-client circuit breaker.
  • Auto-retried by default: GET, HEAD, OPTIONS
  • Opt-in required: POST, PUT, PATCH, DELETE, MCP tools/call
  • Always retried regardless of method: 429 rate limits, with Retry-After honored
Disable SDK retries when your application already owns retry behavior: 
import { SecApiClient } from "@secapi/sdk-js"

const client = new SecApiClient({
  apiKey: process.env.SECAPI_API_KEY!,
  retry: false,
  telemetry: false,
})
Opt into mutating retries only when the operation is idempotent: 
await client.createArtifact(
  { kind: "markdown_bundle", ticker: "AAPL" },
  { retry: { enabled: true, idempotencyKey: "artifact-aapl-markdown-bundle" } },
)
See SDK reliability for the full retry policy and migration notes.

​
Dilution intelligence

// Top 10 highest-dilution-risk issuers
const ratings = await client.dilutionRatings({ overall_risk: "high", limit: 10 })

// Single-ticker dilution rollup
const score = await client.dilutionScore({ ticker: "BBBB" })

// ATM offerings only (boolean filter on the events list)
const atms = await client.dilutionEvents({ ticker: "BBBB", is_atm: true })

// Coverage + freshness rollup (no agent shape — already compact)
const coverage = await client.dilutionCoverage({ ticker: "BBBB" })
The full API — dilutionEvents, dilutionEventDetail, dilutionWarrants, dilutionConvertibles, dilutionRofr, dilutionLockups, dilutionCashPosition, dilutionCorporateActions, dilutionNasdaqCompliance, dilutionRatings, dilutionReverseSplits, dilutionScore, dilutionShareFloatHistory, dilutionCoverage — mirrors the REST routes 1:1. Add view: "agent" to any list call (except dilutionCoverage) for the compact agent-mode shape.

Copy this SEC API prompt for your agent.

​
Error handling

import { SecApiClient, SecApiError } from "@secapi/sdk-js"

try {
  await client.requestDiagnostics("missing-request-id")
} catch (error) {
  if (error instanceof SecApiError) {
    console.error(error.status, error.requestId, error.body)
  }
}
Do not drop metadata on the floor. In production, keep requestId, traceparent, provenance, freshness, and materialization fields in your logs or downstream artifacts so support and audit workflows stay intact.

API Reference

Open the exact REST calls that sit underneath the SDK methods.

Hosted MCP workflows

Use the same SEC API workflows through SEC API hosted MCP.

Give this prompt to your agent

Copy a stronger starting prompt instead of writing one from scratch.