> ## Documentation Index
> Fetch the complete documentation index at: https://docs.secapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# First request flows

> Resolve an issuer, retrieve a filing, and choose a SEC API REST, SDK, CLI, or MCP workflow

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`.

```bash theme={null}
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](/api-reference/filings/get-v1-filings-latest) for exact parameters and schema.

To inspect a named section of that filing, use a documented section key:

```bash theme={null}
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.

```bash theme={null}
npm install @secapi/sdk-js
```

```ts theme={null}
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](/javascript-sdk) for a runnable error-handling example.

## CLI: verify the same path from a terminal

```bash theme={null}
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](/cli) 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.

<Prompt>
  Use tools.search to find issuer resolution, latest filing, and filing section tools. Use tools.describe on each selected tool before calling it. Resolve AAPL, retrieve its latest 10-K, then retrieve Item 1A. Return the company name, accession number, form, filing date, filing URL, requestId, and a short Item 1A summary. State when a field is absent instead of inferring it.
</Prompt>

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](/mcp-install) 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](/request-diagnostics).