Firecrawl API SOP

Appearance

Go SDK ​

Updated Feb 2026

A community-maintained Go SDK for Firecrawl. Supports the v1 API with core scraping, crawling, and mapping functionality.

Packagegithub.com/mendableai/firecrawl-go
API Versionsv1
Maintained byCommunity
Sourcegithub.com/mendableai/firecrawl-go

Community SDK

This SDK is community-maintained and only supports the v1 API. For v2 features like batch scrape, extract, agent, and browser sessions, use the Python SDK or Node.js SDK.

Installation ​

bash
go get github.com/mendableai/firecrawl-go

Initialization ​

Create a FirecrawlApp instance with your API key:

go
package main

import (
    "fmt"
    firecrawl "github.com/mendableai/firecrawl-go"
)

func main() {
    app, err := firecrawl.NewFirecrawlApp("fc-YOUR-API-KEY", "")
    if err != nil {
        panic(err)
    }
    fmt.Println("Firecrawl client initialized")
}

Constructor parameters:

ParameterTypeRequiredDescription
apiKeystringYesYour Firecrawl API key (format: fc-...)
apiURLstringNoCustom API URL (defaults to https://api.firecrawl.dev)

Methods ​

ScrapeUrl() ​

Scrapes a single URL and returns the content. See Scrape feature docs for general parameter details.

Signature:

go
func (app *FirecrawlApp) ScrapeUrl(url string, params *ScrapeParams) (map[string]interface{}, error)

Parameters:

ParameterTypeRequiredDescription
urlstringYesThe URL to scrape
params*ScrapeParamsNoScrape configuration (formats, etc.)

ScrapeParams fields:

FieldTypeDescription
Formats[]stringOutput formats: "markdown", "html"

Example:

go
params := &firecrawl.ScrapeParams{
    Formats: []string{"markdown", "html"},
}

data, err := app.ScrapeUrl("https://firecrawl.dev", params)
if err != nil {
    panic(err)
}
fmt.Println(data["markdown"])

Without parameters (defaults to markdown):

go
data, err := app.ScrapeUrl("https://firecrawl.dev", nil)
if err != nil {
    panic(err)
}
fmt.Println(data)

CrawlUrl() ​

Crawls a website starting from a URL. This is a blocking call that initiates the crawl and returns the results.

Signature:

go
func (app *FirecrawlApp) CrawlUrl(url string, params *CrawlParams, idempotencyKey ...string) (interface{}, error)

Parameters:

ParameterTypeRequiredDescription
urlstringYesStarting URL
params*CrawlParamsNoCrawl configuration
idempotencyKeystringNoOptional idempotency key to prevent duplicate jobs

CrawlParams fields:

FieldTypeDescription
ExcludePaths[]stringURL paths to exclude
MaxDepthintMaximum crawl depth
LimitintMaximum pages to crawl
ScrapeOptions*ScrapeParamsOptions for scraping each page

Example:

go
params := &firecrawl.CrawlParams{
    ExcludePaths: []string{"/blog/*", "/admin/*"},
    MaxDepth:     3,
    Limit:        100,
    ScrapeOptions: &firecrawl.ScrapeParams{
        Formats: []string{"markdown"},
    },
}

result, err := app.CrawlUrl("https://docs.firecrawl.dev", params)
if err != nil {
    panic(err)
}
fmt.Println(result)

With idempotency key:

go
import "github.com/google/uuid"

key := uuid.New().String()
result, err := app.CrawlUrl("https://docs.firecrawl.dev", params, key)

CheckCrawlStatus() ​

Checks the status of an ongoing crawl job.

Signature:

go
func (app *FirecrawlApp) CheckCrawlStatus(crawlID string) (interface{}, error)

Parameters:

ParameterTypeRequiredDescription
crawlIDstringYesJob ID from CrawlUrl()

Example:

go
status, err := app.CheckCrawlStatus("<crawl-id>")
if err != nil {
    panic(err)
}
fmt.Println(status)

MapUrl() ​

Discovers all URLs on a website without scraping their content. See Map feature docs for general parameter details.

Signature:

go
func (app *FirecrawlApp) MapUrl(url string, params ...interface{}) ([]string, error)

Parameters:

ParameterTypeRequiredDescription
urlstringYesTarget URL
paramsinterface{}NoOptional map configuration

Example:

go
urls, err := app.MapUrl("https://firecrawl.dev")
if err != nil {
    panic(err)
}

for _, u := range urls {
    fmt.Println(u)
}

Complete Example ​

Here is a full working example that scrapes a page, crawls a site, and maps URLs:

go
package main

import (
    "fmt"
    firecrawl "github.com/mendableai/firecrawl-go"
)

func main() {
    // Initialize client
    app, err := firecrawl.NewFirecrawlApp("fc-YOUR-API-KEY", "")
    if err != nil {
        panic(err)
    }

    // Scrape a single page
    scrapeResult, err := app.ScrapeUrl("https://firecrawl.dev", &firecrawl.ScrapeParams{
        Formats: []string{"markdown"},
    })
    if err != nil {
        fmt.Println("Scrape error:", err)
    } else {
        fmt.Println("Scraped:", scrapeResult["markdown"])
    }

    // Crawl a site
    crawlResult, err := app.CrawlUrl("https://docs.firecrawl.dev", &firecrawl.CrawlParams{
        Limit:    5,
        MaxDepth: 2,
    })
    if err != nil {
        fmt.Println("Crawl error:", err)
    } else {
        fmt.Println("Crawled:", crawlResult)
    }

    // Map site URLs
    urls, err := app.MapUrl("https://firecrawl.dev")
    if err != nil {
        fmt.Println("Map error:", err)
    } else {
        fmt.Printf("Found %d URLs\n", len(urls))
    }
}

Error Handling ​

The SDK returns Go-standard error values. All methods return an error as the second return value:

go
data, err := app.ScrapeUrl("https://example.com", nil)
if err != nil {
    // Handle error: invalid API key, rate limit, network issue, etc.
    fmt.Println("Error:", err)
    return
}

Common error scenarios:

ScenarioCause
Invalid API keyKey is missing, expired, or malformed
Rate limit exceededToo many requests in a short period
URL not reachableTarget URL is down or blocked
Network errorConnection timeout or DNS failure

Dependencies ​

The Go SDK uses the following dependency:

  • github.com/google/uuid -- for generating idempotency keys

Limitations ​

Since this is a community SDK targeting v1, the following v2 features are not available:

  • Search
  • Batch scrape
  • Extract
  • Agent
  • Browser sessions
  • WebSocket watcher
  • Auto-pagination

For these features, use the Python SDK, Node.js SDK, or CLI.