Go SDK

Use the Go SDK when your services, CLIs, workers, or automation pipelines need typed access to Iteration Layer APIs without hand-writing HTTP requests, authorization headers, or response parsing.

Key Features

• Full API Coverage — Call document extraction, document to markdown, website extraction, image transformation, image generation, document generation, and sheet generation from one client.
• Typed Requests and Responses — Use Go structs for request and response payloads instead of unstructured maps.
• Native Binary Inputs — Pass inline file content as []byte; JSON serialization handles the API wire format.
• Native Binary Outputs — Receive generated documents, images, and sheets as []byte plus MimeType.
• Async Variants — Every long-running API has an async method that accepts WebhookURL and returns immediately after the job is accepted.
• Structured API Errors — Failed API responses return *iterationlayer.Error with StatusCode and ErrorMessage.

Installation

Install the module in the Go project that sends API requests to Iteration Layer.

go get github.com/iterationlayer/sdk-go

Client Setup

Create one client with your API key. The SDK sends requests to https://api.iterationlayer.com and adds the required bearer token automatically.

import il "github.com/iterationlayer/sdk-go"

client := il.NewClient("YOUR_API_KEY")

First Request

The SDK request shape matches the HTTP API shape, with Go structs for typed API fields. This example extracts the vendor name and invoice total from a remote PDF.

result, err := client.ExtractDocument(il.ExtractDocumentRequest{
    Files: []il.FileInput{
        {Type: "url", Name: "invoice.pdf", Url: "https://example.com/invoice.pdf"},
    },
    Schema: il.ExtractionSchema{
        Fields: []any{
            il.TextFieldConfig{Type: "TEXT", Name: "vendor", Description: "Vendor name"},
            il.CurrencyAmountFieldConfig{Type: "CURRENCY_AMOUNT", Name: "total", Description: "Total amount"},
        },
    },
})
if err != nil {
    return err
}

API Methods

Each API has a sync method and an async method. Async methods append Async, require WebhookURL, and return an acceptance result instead of the final payload.

Binary Files

Inline file inputs use []byte in Go. Binary API outputs return BinaryResult, so application code can write the buffer directly to storage, an HTTP response, or another processing step.

Error Handling

API validation errors, authentication failures, rate limits, and server errors return *iterationlayer.Error. Network-level and JSON parsing failures return regular Go errors.

import (
    "errors"
    "fmt"

    il "github.com/iterationlayer/sdk-go"
)

client := il.NewClient("YOUR_API_KEY")

result, err := client.ExtractDocument(il.ExtractDocumentRequest{
    // ...
})
if err != nil {
    var apiErr *il.Error
    if errors.As(err, &apiErr) {
        fmt.Println(apiErr.StatusCode)
        fmt.Println(apiErr.ErrorMessage)
    }
}

Async Webhooks

Use async methods when processing should continue after your application request has returned. Iteration Layer validates and accepts the job, then sends the final result to your webhook endpoint.

result, err := client.ExtractDocumentAsync(il.ExtractDocumentAsyncRequest{
    Files: []il.FileInput{
        {Type: "url", Name: "doc.pdf", Url: "https://example.com/doc.pdf"},
    },
    Schema: il.ExtractionSchema{
        Fields: []any{
            il.TextFieldConfig{Type: "TEXT", Name: "title", Description: "Document title"},
        },
    },
    WebhookURL: "https://your-app.com/webhooks/extraction",
})

fmt.Println(result.Message)

Links

• GitHub repository
• SDK overview