First request flows

Use this guide to prove one filing workflow end to end. A useful first success is not only an HTTP 200: retain the issuer identity, accession number, form, filing date, filing URL, and request ID when returned. A latest-filing result is time-dependent, so verify the returned filing identity before using it as evidence. Choose REST when your application owns HTTP and response parsing; an SDK or CLI when it already fits your runtime; and hosted MCP when an MCP client needs discovered SEC API tools. Each path should produce the same kind of source record, but their client setup and retry ownership differ.

REST: establish the filing record

Set the key in your server-side environment. Machine requests use x-api-key.

export SECAPI_API_KEY="secapi_..."

curl --fail-with-body -sS \
  -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/entities/resolve?ticker=AAPL&view=agent"

curl --fail-with-body -sS \
  -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/filings/latest?ticker=AAPL&form=10-K&view=agent"

The first request establishes the issuer identity. The second returns the current latest matching filing. Inspect the response before continuing, then retain its filing identifiers. See the latest filing reference for exact parameters and schema. To inspect a named section of that filing, use a documented section key:

curl --fail-with-body -sS \
  -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/filings/latest/sections/item_1a?ticker=AAPL&form=10-K&view=agent"

A section answers a narrower question; it does not replace the filing identity from the preceding request.

JavaScript SDK: use the same workflow

Install the SDK, then keep SECAPI_API_KEY in the server-side environment.

npm install @secapi/sdk-js

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

const sec = new SecApiClient()
const entity = await sec.resolveEntity({ ticker: "AAPL", view: "agent" })
const filing = await sec.agentLatestFiling({ ticker: "AAPL", form: "10-K" })
const section = await sec.agentSection({
  ticker: "AAPL",
  form: "10-K",
  sectionKey: "item_1a",
})

console.log({ entity, filing, section })

Inspect each returned object before assuming optional provenance or freshness fields are available. Preserve the filing identity from filing; see JavaScript SDK for a runnable error-handling example.

CLI: verify the same path from a terminal

npm install -g @secapi/cli

secapi entities resolve --ticker AAPL
secapi filings latest --ticker AAPL --form 10-K
secapi sections get --ticker AAPL --form 10-K --section item_1a --view agent

The CLI prints JSON for the current response. Run secapi <command> --help for the installed command version, and see the CLI reference for configuration and diagnostic commands.

Hosted MCP: discover before you call

Configure the hosted server in your MCP client, then let the client discover its current tool catalog instead of hard-coding tool names as a compatibility contract.

MCP output can include structured content and presentation text. Preserve the typed source record and identifiers. Use any provenance, freshness, truncation, or trace information only in the context supplied by that tool. Install MCP to configure the connection.

When a first request stops

Correct 400 validation errors from the route or tool schema. For 401 or 403, verify the credential and auth flow; machine data requests use x-api-key. Stop for a 402 billing condition. For 429, honor Retry-After when present and reduce parallel work before a bounded retry. Preserve the request ID with the failed attempt, then use Request diagnostics.

Make your first SEC API request Advanced quickstarts

Plans & pricing

Products

Workflow guides

Concepts & trust

Tutorials

Migrate to SEC API

Solutions

Compare

API guides by topic

REST: establish the filing record

JavaScript SDK: use the same workflow

CLI: verify the same path from a terminal

Hosted MCP: discover before you call

When a first request stops

​REST: establish the filing record

​JavaScript SDK: use the same workflow

​CLI: verify the same path from a terminal

​Hosted MCP: discover before you call

​When a first request stops

REST: establish the filing record

JavaScript SDK: use the same workflow

CLI: verify the same path from a terminal

Hosted MCP: discover before you call

When a first request stops