Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nimbleway.com/llms.txt

Use this file to discover all available pages before exploring further.

Install the Nimble Go library to interact with the Nimble API from your Go applications. Built with idiomatic Go patterns, full context support, and automatic retries.

​
Installation

go get github.com/Nimbleway/nimble-go@latest'
Requires Go 1.22+. Set your API key via the NIMBLE_API_KEY environment variable or pass it directly using option.WithAPIKey().

​
Setup

Import the package and initialize the client:
Go
package main

import (
    "context"
    "fmt"
    "os"

    nimble "github.com/Nimbleway/nimble-go"
    "github.com/Nimbleway/nimble-go/option"
)

func main() {
    client := nimble.NewClient(
        option.WithAPIKey(os.Getenv("NIMBLE_API_KEY")),
    )

    _ = client
    fmt.Println("Client ready")
}

​
Quick Start

Extract content from a URL:
Go
package main

import (
    "context"
    "fmt"
    "os"

    nimble "github.com/Nimbleway/nimble-go"
    "github.com/Nimbleway/nimble-go/option"
)

func main() {
    client := nimble.NewClient(
        option.WithAPIKey(os.Getenv("NIMBLE_API_KEY")),
    )

    result, err := client.Extract(context.TODO(), nimble.ExtractParams{
        URL: "https://www.example.com",
    })
    if err != nil {
        panic(err)
    }

    fmt.Printf("Task ID: %s\n", result.TaskID)
}

​
Core Methods

​
Extract

Get clean HTML, markdown, or structured data from any URL:
Go
result, err := client.Extract(context.TODO(), nimble.ExtractParams{
    URL:    "https://www.example.com",
    Render: nimble.Bool(true),
})
if err != nil {
    panic(err)
}
fmt.Println(result.TaskID)
Optional fields are wrapped in param.Opt[T]. Use the provided constructors — nimble.Bool(), nimble.String(), nimble.Int() — to set them.
Perform real-time web searches:
Go
result, err := client.Search(context.TODO(), nimble.SearchParams{
    Query:   "best web scraping tools",
    Country: nimble.String("US"),
})
if err != nil {
    panic(err)
}
fmt.Println(result)

​
Map

Discover all URLs within a domain or sitemap:
Go
result, err := client.Map(context.TODO(), nimble.MapParams{
    URL:     "https://www.example.com",
    Sitemap: nimble.String("only"),
})
if err != nil {
    panic(err)
}
fmt.Println(result)

​
Crawl

Recursively crawl and extract an entire website:
Go
result, err := client.Crawl.Run(context.TODO(), nimble.CrawlRunParams{
    URL:   "https://www.example.com",
    Limit: nimble.Int(100),
})
if err != nil {
    panic(err)
}
fmt.Println(result)

​
Agents

Run pre-built agents for structured data from popular platforms:
Go
result, err := client.Agent.Run(context.TODO(), nimble.AgentRunParams{
    Agent: "amazon_pdp",
    Params: map[string]interface{}{
        "asin": "B08N5WRWNW",
    },
})
if err != nil {
    panic(err)
}
fmt.Println(result)
Browse the full agent catalog in the Agent Gallery.

​
Error Handling

Check err != nil for any failed request. Use errors.As to inspect typed API errors:
Go
import (
    "errors"
    "fmt"

    nimble "github.com/Nimbleway/nimble-go"
)

result, err := client.Extract(context.TODO(), nimble.ExtractParams{
    URL: "https://www.example.com",
})
if err != nil {
    var apiErr *nimble.Error
    if errors.As(err, &apiErr) {
        fmt.Printf("API error — status: %d, message: %s\n",
            apiErr.StatusCode, apiErr.Message)
    }
    panic(err)
}
The *nimble.Error type exposes:
  • StatusCode int — HTTP status code
  • Message string — Human-readable error description

​
Configuration

​
Retries

The SDK retries automatically on connection errors, timeouts, and server failures (2 retries by default):
Go
// Configure globally
client := nimble.NewClient(
    option.WithAPIKey(os.Getenv("NIMBLE_API_KEY")),
    option.WithMaxRetries(3),
)

// Disable retries for a specific request
result, err := client.Extract(context.TODO(), nimble.ExtractParams{
    URL: "https://www.example.com",
}, option.WithMaxRetries(0))

​
Timeouts

Use Go’s standard context package for request timeouts:
Go
import (
    "context"
    "time"
)

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

result, err := client.Extract(ctx, nimble.ExtractParams{
    URL: "https://www.example.com",
})
Or set a per-request timeout directly:
Go
result, err := client.Extract(context.TODO(), nimble.ExtractParams{
    URL: "https://www.example.com",
}, option.WithRequestTimeout(30*time.Second))

​
Advanced

​
Raw Response Access

Capture the raw HTTP response alongside the parsed result:
Go
import "net/http"

var rawResponse *http.Response

result, err := client.Extract(context.TODO(), nimble.ExtractParams{
    URL: "https://www.example.com",
}, option.WithResponseInto(&rawResponse))
if err != nil {
    panic(err)
}

fmt.Println(rawResponse.Header.Get("x-request-id"))
fmt.Println(result.TaskID)

​
Custom Request Options

Attach additional headers or query parameters to any request:
Go
result, err := client.Extract(context.TODO(), nimble.ExtractParams{
    URL: "https://www.example.com",
},
    option.WithHeader("X-Custom-Header", "value"),
    option.WithQueryParam("debug", "true"),
)

​
Next Steps

API Reference

Full REST API documentation for all endpoints

Extract

Rendering, formats, stealth mode, and more

Search

Real-time web search with structured results

Agents

Pre-built extraction agents for popular platforms