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

# Go SDK Overview

> Get started with the Reducto Go SDK

The Reducto Go SDK provides a strongly-typed interface to the Reducto API. It handles authentication, request formatting, and response parsing automatically.

<Note>
  The Go SDK is in alpha (v0.1.0-alpha.1). **Edit** and **Pipeline** endpoints are not yet supported. Use the REST API directly for those features.
</Note>

***

## Quick Start

```go theme={null}
package main

import (
    "context"
    "fmt"
    "io"
    "os"

    reducto "github.com/reductoai/reducto-go-sdk"
    "github.com/reductoai/reducto-go-sdk/option"
    "github.com/reductoai/reducto-go-sdk/shared"
)

func main() {
    // Initialize the client (reads REDUCTO_API_KEY from environment)
    client := reducto.NewClient(option.WithAPIKey(os.Getenv("REDUCTO_API_KEY")))

    // Upload a document
    file, _ := os.Open("invoice.pdf")
    defer file.Close()
    
    upload, _ := client.Upload(context.Background(), reducto.UploadParams{
        File: reducto.F[io.Reader](file),
    })

    // Parse the document
    result, _ := client.Parse.Run(context.Background(), reducto.ParseRunParams{
        ParseConfig: reducto.ParseConfigParam{
            DocumentURL: reducto.F[reducto.ParseConfigDocumentURLUnionParam](
                shared.UnionString(upload.FileID),
            ),
        },
    })

    // Access the extracted content using union type
    if result.Result.Type == shared.ParseResponseResultTypeFull {
        fullResult := result.Result.AsUnion().(shared.ParseResponseResultFullResult)
        for _, chunk := range fullResult.Chunks {
            fmt.Println(chunk.Content)
        }
    }
}
```

***

## Key Features

<CardGroup cols={2}>
  <Card title="Strong Typing" icon="shield-check">
    Full type safety with Go's type system and generated types for all API responses.
  </Card>

  <Card title="Context Support" icon="code">
    All methods accept `context.Context` for cancellation and timeouts.
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation">
    Standard Go error handling with detailed error types.
  </Card>

  <Card title="Concurrent Safe" icon="clock">
    Client instances are safe for concurrent use.
  </Card>
</CardGroup>

***

## Installation

```bash theme={null}
go get github.com/reductoai/reducto-go-sdk
```

Requires Go 1.18+. The SDK requires no additional dependencies.

***

## Authentication

Set your API key as an environment variable:

```bash theme={null}
export REDUCTO_API_KEY="your_api_key_here"
```

The SDK reads it automatically:

```go theme={null}
import (
    "os"
    reducto "github.com/reductoai/reducto-go-sdk"
    "github.com/reductoai/reducto-go-sdk/option"
)

// Recommended: pass explicitly for clarity
client := reducto.NewClient(option.WithAPIKey(os.Getenv("REDUCTO_API_KEY")))
```

Get your API key from [Reducto Studio](https://studio.reducto.ai/) → API Keys.

***

## Core Methods

The SDK provides methods for all Reducto endpoints:

### Upload

Upload documents to Reducto's servers before processing:

```go theme={null}
upload, err := client.Upload(context.Background(), reducto.UploadParams{
    File: reducto.F[io.Reader](file),
})
// Returns: UploadResponse with FileID field
```

<Card title="Upload Documentation" icon="upload" href="/sdk/go/upload">
  File upload options, size limits, and presigned URLs.
</Card>

### Parse

Convert documents into structured JSON with text, tables, and figures:

```go theme={null}
result, err := client.Parse.Run(context.Background(), reducto.ParseRunParams{
    ParseConfig: reducto.ParseConfigParam{
        DocumentURL: reducto.F[reducto.ParseConfigDocumentURLUnionParam](
            shared.UnionString(upload.FileID),
        ),
    },
})
```

<Card title="Parse Documentation" icon="file-lines" href="/sdk/go/parse">
  Parse configuration, chunking options, and response structure.
</Card>

### Extract

Pull specific fields from documents using JSON schemas:

```go theme={null}
result, err := client.Extract.Run(context.Background(), reducto.ExtractRunParams{
    ExtractConfig: reducto.ExtractConfigParam{
        DocumentURL: reducto.F[reducto.ExtractConfigDocumentURLUnionParam](
            shared.UnionString(upload.FileID),
        ),
        Schema: reducto.F[interface{}](schema),
    },
})
```

<Card title="Extract Documentation" icon="brackets-curly" href="/sdk/go/extract">
  Schema design, array extraction, and citations.
</Card>

### Split

Divide documents into sections based on content descriptions:

```go theme={null}
result, err := client.Split.Run(context.Background(), reducto.SplitRunParams{
    DocumentURL: reducto.F[reducto.SplitRunParamsDocumentURLUnion](
        shared.UnionString(upload.FileID),
    ),
    SplitDescription: reducto.F([]shared.SplitCategoryParam{
        {Name: reducto.F("Introduction"), Description: reducto.F("Introduction section")},
        {Name: reducto.F("Results"), Description: reducto.F("Results section")},
    }),
})
```

<Card title="Split Documentation" icon="scissors" href="/sdk/go/split">
  Split configuration and section types.
</Card>

### Edit & Pipeline

<Note>
  Edit and Pipeline endpoints are not available in the Go SDK. Use the [REST API](/api-reference/edit) directly or the client's `Post` method. See [Edit](/sdk/go/edit) and [Pipeline](/sdk/go/pipeline) pages for workarounds.
</Note>

***

## Async Jobs

For long-running operations, use `RunJob` methods to get a job ID:

```go theme={null}
// Start async job
job, err := client.Parse.RunJob(context.Background(), reducto.ParseRunJobParams{
    DocumentURL: reducto.F[reducto.ParseRunJobParamsDocumentURLUnion](
        shared.UnionString(upload.FileID),
    ),
})
fmt.Println(job.JobID)

// Check status
status, err := client.Job.Get(context.Background(), job.JobID)
if status.Status == "Completed" {
    fmt.Println(status.Result)
}
```

<Card title="Async Processing" icon="clock" href="/sdk/go/async">
  Concurrent processing with goroutines and async job management.
</Card>

***

## Type System

The Go SDK uses a strongly-typed system with `param.Field` wrappers and union types:

### Param Fields

All request parameters use `param.Field[T]` to distinguish zero values from null or omitted fields:

```go theme={null}
// Wrap values with F[T]()
DocumentURL: reducto.F[reducto.ParseConfigDocumentURLUnionParam](
    shared.UnionString(upload.FileID),
)

// For integers
ChunkSize: reducto.Int(1000)

// For strings
SystemPrompt: reducto.String("Extract financial data")

// For booleans
Enabled: reducto.Bool(true)
```

### Union Types

Response types that can have different structures use union types. Use `AsUnion()` to cast:

```go theme={null}
if result.Result.Type == shared.ParseResponseResultTypeFull {
    fullResult := result.Result.AsUnion().(shared.ParseResponseResultFullResult)
    for _, chunk := range fullResult.Chunks {
        // ...
    }
}
```

***

## Error Handling

The SDK uses standard Go error handling:

```go theme={null}
result, err := client.Parse.Run(context.Background(), params)
if err != nil {
    fmt.Printf("Error: %v\n", err)
    return
}
```

<Card title="Error Handling Guide" icon="triangle-exclamation" href="/sdk/go/error-handling">
  Complete error handling reference with all error types.
</Card>

***

## Next Steps

<Steps>
  <Step title="Get your API key">
    Create an API key in [Reducto Studio](https://studio.reducto.ai/) and set it as `REDUCTO_API_KEY`.
  </Step>

  <Step title="Try the quickstart">
    Run your first parse operation with the [quickstart example](/quickstart).
  </Step>

  <Step title="Explore the methods">
    Check out the [core methods documentation](/sdk/go/parse) for detailed usage.
  </Step>
</Steps>