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

# Start with the JavaScript SDK

> Install the SEC API JavaScript SDK, retrieve one filing, and handle errors in a server-side runtime.

## Prerequisites

* Node.js 18 or newer.
* An API key in a trusted server-side environment.

```bash theme={null}
npm install @secapi/sdk-js
export SECAPI_API_KEY="secapi_..."
```

## Run a complete first request

Create `first-request.mjs`:

```js theme={null}
import { SecApiClient, SecApiError } from "@secapi/sdk-js"

const sec = new SecApiClient()

try {
  const filing = await sec.agentLatestFiling({
    ticker: "AAPL",
    form: "10-K",
  })

  console.log(JSON.stringify({
    accessionNumber: filing.accessionNumber,
    filingDate: filing.filingDate,
    filingUrl: filing.filingUrl,
    requestId: filing.requestId,
  }, null, 2))
} catch (error) {
  if (error instanceof SecApiError) {
    console.error({ status: error.status, code: error.code, requestId: error.requestId })
    process.exitCode = 1
  } else {
    throw error
  }
}
```

```bash theme={null}
node first-request.mjs
```

Expect an accession number, filing date, SEC filing URL, and request ID. The accession and date are live values and will change after a newer filing.

## Use the response correctly

`agentLatestFiling()` sets `view=agent`. This is a smaller, endpoint-supported response shape; it is not a guarantee that every default-response field is included. When you need the full endpoint response, use `latestFiling()` and inspect the [operation reference](/api-reference/filings/get-v1-filings-latest).

Keep the returned accession number, filing URL, and request ID with any derived output. They connect a result to its source filing and API request.

## Special Situations workflow

Use the published `situations` namespace helpers for a current roster, a filtered roster by EDGAR form, current detail, a filing timeline, and a compact summary.

```js theme={null}
const roster = await sec.situations.list({ types: ["merger"], statuses: ["pending"], limit: 25 })
const detail = await sec.situations.get("sit_abc123")
const byForm = await sec.situations.byForm("SC 13D", { limit: 25 })
const filings = await sec.situations.filings("sit_abc123", { limit: 25 })
const summary = await sec.situations.summary("sit_abc123")
```

Treat `detail` as current data. Keep source identifiers and request IDs with any derived output, and review the underlying filing before relying on a disclosed term or date. See [Special Situations workflows](/special-situations-workflows) and the [REST reference](/api-reference/situations) for the complete published API surface.

## Errors and retries

The SDK throws `SecApiError` with an HTTP status, `code`, `requestId`, and, when supplied, retry guidance. Its retry policy is bounded and honors `Retry-After`. A `429` can be retried even when it follows a mutating request; treatment of other failures depends on the HTTP method and request options.

Do not add another concurrent retry loop. Before a mutation whose replay is unsafe, disable SDK retries with `new SecApiClient({ retry: false })` or ensure the operation is idempotent and use an idempotency key.

## Production notes

* Keep `SECAPI_API_KEY` in server-only configuration.
* Set `apiVersion` explicitly after testing the endpoint behavior you depend on; log the response `SECAPI-Version`.
* Use `retry: false` when your infrastructure already owns retries.
* Paginate list endpoints with the SDK iterator rather than assuming one page is complete.

Next: [SDK reliability](/sdk-reliability), [Python SDK](/python-sdk), or [API conventions](/api-conventions).