> ## 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 Go SDK

> Add the SEC API Go module, make one type-safe read, and keep the response identifiers needed for production support.

## Prerequisites

* Go 1.23 or newer.
* An API key in `SECAPI_API_KEY`.

```bash theme={null}
mkdir secapi-go-quickstart
cd secapi-go-quickstart
go mod init example.com/secapi-go-quickstart
go get github.com/secapi-ai/secapi-go/v2
export SECAPI_API_KEY="secapi_..."
```

## Run a first request

Create `main.go`:

```go theme={null}
package main

import (
  "fmt"
  "log"
  "os"

  sdkgo "github.com/secapi-ai/secapi-go/v2"
)

func stringValue(value *string) string {
  if value == nil {
    return ""
  }
  return *value
}

func main() {
  client := sdkgo.NewClient(os.Getenv("SECAPI_API_KEY"))
  filing, err := client.LatestFilingAgent(map[string]string{
    "ticker": "AAPL",
    "form": "10-K",
  })
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(filing.AccessionNumber, filing.FilingDate, stringValue(filing.FilingURL))
}
```

```bash theme={null}
go run .
```

Expect the current matching filing's accession number, date, and SEC URL. Those values are live. Store them with any derived work; do not use a latest-filing response as a permanent fixture.

## Special Situations workflow

The client has helpers for a current roster and detail, filing-event activity, disclosed calendar dates, aggregate counts, archived weekly issues, Markdown exports, underwriting packs, and monitor creation. Each call returns an error; handle it at the boundary that owns the request.

```go theme={null}
func must[T any](value T, err error) T {
  if err != nil { log.Fatal(err) }
  return value
}

roster := must(client.ListSituations(map[string]string{"types": "merger", "statuses": "pending", "limit": "25"}))
detail := must(client.GetSituation("sit_abc123", nil))
byForm := must(client.SituationsByForm("SC 13D", map[string]string{"limit": "25"}))
filings := must(client.SituationFilings("sit_abc123", map[string]string{"limit": "25"}))
summary := must(client.SituationSummary("sit_abc123", nil))
feed := must(client.SituationsFeed(map[string]string{"tickers": "ACME"}))
calendar := must(client.SituationsCalendar(map[string]string{"date_types": "vote,expected_close", "days": "30"}))
stats := must(client.SituationsStats(map[string]string{"window": "30d"}))
issues := must(client.SituationsIssues(map[string]string{"limit": "12"}))
brief := must(client.ExportSituation("sit_abc123", nil))
underwriting := must(client.UnderwriteSituation("sit_abc123", nil))
publicRoster := must(client.EmbedSituations(map[string]string{"limit": "10"}))
publicBrief := must(client.EmbedSituationExport("sit_abc123", nil))
watch := must(client.WatchSituations(sdkgo.SituationWatchParams{
  Name: "ACME situation updates",
  Filters: map[string][]string{"tickers": {"ACME"}},
  Delivery: sdkgo.SituationWatchDelivery{Email: "research@example.com"},
}))
_ = []any{roster, detail, byForm, filings, summary, feed, calendar, stats, issues, brief, underwriting, publicRoster, publicBrief, watch}
```

Current detail can change as filings arrive; an issue is an immutable historical publication. Retain source identifiers and request IDs with derived output, and review the underlying filing before relying on a disclosed term or date. See [Special Situations workflows](/special-situations-workflows) for the REST and CLI workflow.

## Errors, retries, and limits

The client returns an `APIError` for API failures. Capture its HTTP status, error code, and request ID in application logs. Its retry layer honors `Retry-After`; a `429` can be retried even when it follows a mutating request, while treatment of other failures depends on the HTTP method.

Before a mutation whose replay is unsafe, disable client retries with `client.RetryConfig.MaxRetries = 0` or ensure the operation is idempotent. Keep one bounded retry owner in the service.

Typed request helpers cover common paths, but the map-based methods remain the direct path to the REST contract. Check the relevant API reference for accepted parameters and response fields before adding a query parameter.

## Production notes

* Create the client with a key from a server-side secret source; do not ship it in a binary or frontend.
* Use contexts, timeouts, and one retry owner in your service.
* Log request identity and filing provenance separately from business output.
* Treat agent response helpers as compact endpoint projections. Use the default endpoint shape when your use case needs fields not present in the compact response.

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