Go

This guide uses only the standard library (net/http, encoding/json), with no external dependencies. A reusable client is built with methods to upload a local file, convert from a signed URL and poll an asynchronous job, with idiomatic error handling in Go (own error type implemented by error, wrapped with %w).

Local file (minimal example)

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

const apiURL = "https://api.markpdf.tech"
const apiKey = "YOUR_API_KEY"

func main() {
	f, _ := os.Open("report.pdf")
	defer f.Close()

	req, _ := http.NewRequest("POST", apiURL+"/convert/raw?filename=report.pdf&mode=fast", f)
	req.Header.Set("x-api-key", apiKey)
	req.Header.Set("content-type", "application/pdf")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

URL signed (minimal example)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	payload := `{"url":"https://bucket.s3.amazonaws.com/report.pdf?X-Amz-Signature=...","filename":"report.pdf","mode":"fast"}`

	req, _ := http.NewRequest("POST", "https://api.markpdf.tech/convert/from-url", strings.NewReader(payload))
	req.Header.Set("x-api-key", "YOUR_API_KEY")
	req.Header.Set("content-type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Cliente reutilizable

For real use, it is convenient to encapsulate the authentication logic, construction of requests, handling of 202 and errors in a struct with methods. This client covers ConvertRaw (local file), ConvertFromURL (URL signed), and pollJob (%%0005% polling).

package flashmd

import (
	"bytes"
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"time"
)

// Client is a reusable HTTP client for API Flash PDF to Markdown.
type Client struct {
	BaseURL    string
	APIKey     string
	HTTPClient *http.Client
}

// NewClient creates a client with reasonable timeouts for production.
func NewClient(baseURL, apiKey string) *Client {
	return &Client{
		BaseURL: baseURL,
		APIKey:  apiKey,
		HTTPClient: &http.Client{
			Timeout: 120 * time.Second,
		},
	}
}

// APIError represents a business error returned by API (4xx/5xx).
// Implements the error interface and exposes StatusCode and Detail for
// so the caller can decide whether to retry or not.
type APIError struct {
	StatusCode int
	Detail     string
}

func (e *APIError) Error() string {
	return fmt.Sprintf("flashmd: HTTP %d: %s", e.StatusCode, e.Detail)
}

// Retryable indicates whether this request is worth retrying (429 or 5xx).
func (e *APIError) Retryable() bool {
	return e.StatusCode == http.StatusTooManyRequests || e.StatusCode >= 500
}

type errorBody struct {
	Detail string `json:"detail"`
}

type acceptedJob struct {
	JobID             string `json:"job_id"`
	RetryAfterSeconds int    `json:"retry_after_seconds"`
}

type jobStatus struct {
	Status string `json:"status"`
	Body   string `json:"body"`
	Error  string `json:"error"`
}

// ConvertOptions groups optional conversion parameters.
type ConvertOptions struct {
	Filename string
	Mode     string // fast | ultra_fast | balanced | quality | auto
	Clean    *bool // nil = use default (true)
}

func (o ConvertOptions) toQuery() url.Values {
	q := url.Values{}
	if o.Filename != "" {
		q.Set("filename", o.Filename)
	}
	if o.Mode != "" {
		q.Set("mode", o.Mode)
	}
	if o.Engine != "" {
		q.Set("engine", o.Engine)
	}
	}
	if o.Clean != nil {
		q.Set("clean", fmt.Sprintf("%t", *o.Clean))
	}
	return q
}

// ConvertRaw uploads the binary content of a document to POST /convert/raw
// and returns the resulting markdown, resolving flow 202 -> polling
// transparently for the caller.
func (c *Client) ConvertRaw(ctx context.Context, content io.Reader, contentType string, opts ConvertOptions) (string, error) {
	endpoint := c.BaseURL + "/convert/raw?" + opts.toQuery().Encode()

	req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, content)
	if err != nil {
		return "", fmt.Errorf("flashmd: building request: %w", err)
	}
	req.Header.Set("x-api-key", c.APIKey)
	req.Header.Set("content-type", contentType)

	return c.doAndResolve(ctx, req)
}

// ConvertFromURL asks API to download the document from URL
// (for example a signed URL from S3) and convert it.
func (c *Client) ConvertFromURL(ctx context.Context, sourceURL string, opts ConvertOptions) (string, error) {
	payload, err := json.Marshal(map[string]any{
		"url":      sourceURL,
		"filename": opts.Filename,
		"mode":     opts.Mode,
		"engine":   opts.Engine,
	})
	if err != nil {
		return "", fmt.Errorf("flashmd: encoding payload: %w", err)
	}

	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.BaseURL+"/convert/from-url", bytes.NewReader(payload))
	if err != nil {
		return "", fmt.Errorf("flashmd: building request: %w", err)
	}
	req.Header.Set("x-api-key", c.APIKey)
	req.Header.Set("content-type", "application/json")

	return c.doAndResolve(ctx, req)
}

// doAndResolve executes the request and, if API responds 202, polls
// of /jobs/{job_id} until the job ends (completed or failed).
func (c *Client) doAndResolve(ctx context.Context, req *http.Request) (string, error) {
	res, err := c.HTTPClient.Do(req)
	if err != nil {
		return "", fmt.Errorf("flashmd: request failed: %w", err)
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		return "", fmt.Errorf("flashmd: reading response body: %w", err)
	}

	switch res.StatusCode {
	case http.StatusOK:
		return string(body), nil
	case http.StatusAccepted:
		var job acceptedJob
		if err := json.Unmarshal(body, &job); err != nil {
			return "", fmt.Errorf("flashmd: decoding 202 payload: %w", err)
		}
		return c.PollJob(ctx, job.JobID, job.RetryAfterSeconds)
	default:
		var eb errorBody
		_ = json.Unmarshal(body, &eb)
		if eb.Detail == "" {
			eb.Detail = string(body)
		}
		return "", &APIError{StatusCode: res.StatusCode, Detail: eb.Detail}
	}
}

// PollJob queries GET /jobs/{job_id} every retryAfterSeconds (or 5s per
// default) until the job becomes "completed" or "failed".
func (c *Client) PollJob(ctx context.Context, jobID string, retryAfterSeconds int) (string, error) {
	delay := time.Duration(retryAfterSeconds) * time.Second
	if delay <= 0 {
		delay = 5 * time.Second
	}

	timer := time.NewTimer(delay)
	defer timer.Stop()

	for {
		select {
		case <-ctx.Done():
			return "", fmt.Errorf("flashmd: polling job %s: %w", jobID, ctx.Err())
		case <-timer.C:
		}

		req, err := http.NewRequestWithContext(ctx, http.MethodGet, fmt.Sprintf("%s/jobs/%s", c.BaseURL, jobID), nil)
		if err != nil {
			return "", fmt.Errorf("flashmd: building poll request: %w", err)
		}
		req.Header.Set("x-api-key", c.APIKey)

		res, err := c.HTTPClient.Do(req)
		if err != nil {
			return "", fmt.Errorf("flashmd: polling job %s: %w", jobID, err)
		}

		var status jobStatus
		decodeErr := json.NewDecoder(res.Body).Decode(&status)
		res.Body.Close()
		if decodeErr != nil {
			return "", fmt.Errorf("flashmd: decoding job status: %w", decodeErr)
		}

		switch status.Status {
		case "completed":
			return status.Body, nil
		case "failed":
			return "", fmt.Errorf("flashmd: job %s failed: %s", jobID, status.Error)
		}

		timer.Reset(delay)
	}
}

The code above assumes that you import context in addition to the packages already listed; add it to the import block of your actual file ("context").

Client usage

package main

import (
	"context"
	"errors"
	"fmt"
	"os"

	"tu-modulo/flashmd"
)

func main() {
	client := flashmd.NewClient("https://api.markpdf.tech", os.Getenv("FLASH_MD_API_KEY"))

	f, err := os.Open("report.pdf")
	if err != nil {
		panic(err)
	}
	defer f.Close()

	ctx := context.Background()
	markdown, err := client.ConvertRaw(ctx, f, "application/pdf", flashmd.ConvertOptions{
		Filename: "report.pdf",
		Mode:     "fast",
	})
	if err != nil {
		var apiErr *flashmd.APIError
		if errors.As(err, &apiErr) {
			switch apiErr.StatusCode {
			case 401:
				fmt.Println("API key invávalida o ausente")
			case 413:
				fmt.Println("The document exceeds the size/page limit")
			case 415:
				fmt.Println("Formato no soportado")
			default:
				fmt.Printf("Error de la API: %s\n", apiErr.Detail)
			}
			return
		}
		panic(err)
	}

	fmt.Println(markdown)
}

Language error handling

Type APIError implements Go’s error interface (method Error() string) and exposes StatusCode so that calling code can inspect it with errors.As. All internal errors (network, (de)serialization failures) are wrapped with %w to preserve the chain of causes and allow errors.Is/errors.As at any point:

markdown, err := client.ConvertRaw(ctx, f, "application/pdf", opts)
if err != nil {
	var apiErr *flashmd.APIError
	switch {
	case errors.As(err, &apiErr) && apiErr.StatusCode == 401:
		// invavalid credentials: do not retry, warn user
	case errors.As(err, &apiErr) && apiErr.Retryable():
		// 429 or 5xx: retry with backoff (see Production section)
	case errors.Is(err, context.DeadlineExceeded):
		// timeout del http.Client
	default:
		// network error or other unexpected error
	}
}

Handling of 202 (auto-async)

When all backends are saturated, API returns 202 with a job_id. The client above already resolves this transparently via PollJob, but if you prefer not to use the struct, here is the equivalent flow independently:

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"time"
)

const apiURL = "https://api.markpdf.tech"
const apiKey = "YOUR_API_KEY"

type AcceptedJob struct {
	JobID             string `json:"job_id"`
	RetryAfterSeconds int    `json:"retry_after_seconds"`
}

type JobStatus struct {
	Status string `json:"status"`
	Body   string `json:"body"`
	Error  string `json:"error"`
}

func convert(pdfPath string) (string, error) {
	f, err := os.Open(pdfPath)
	if err != nil {
		return "", err
	}
	defer f.Close()

	req, _ := http.NewRequest("POST", apiURL+"/convert/raw?filename="+pdfPath+"&mode=fast", f)
	req.Header.Set("x-api-key", apiKey)
	req.Header.Set("content-type", "application/pdf")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return "", err
	}
	defer res.Body.Close()

	if res.StatusCode == 200 {
		body, _ := io.ReadAll(res.Body)
		return string(body), nil
	}

	if res.StatusCode == 202 {
		var job AcceptedJob
		json.NewDecoder(res.Body).Decode(&job)
		delay := time.Duration(job.RetryAfterSeconds) * time.Second
		if delay == 0 {
			delay = 5 * time.Second
		}

		for {
			time.Sleep(delay)

			pollReq, _ := http.NewRequest("GET", fmt.Sprintf("%s/jobs/%s", apiURL, job.JobID), nil)
			pollReq.Header.Set("x-api-key", apiKey)
			pollRes, err := http.DefaultClient.Do(pollReq)
			if err != nil {
				return "", err
			}

			var status JobStatus
			json.NewDecoder(pollRes.Body).Decode(&status)
			pollRes.Body.Close()

			switch status.Status {
			case "completed":
				return status.Body, nil
			case "failed":
				return "", fmt.Errorf("job %s failed: %s", job.JobID, status.Error)
			}
		}
	}

	body, _ := io.ReadAll(res.Body)
	return "", fmt.Errorf("HTTP %d: %s", res.StatusCode, body)
}

func main() {
	md, err := convert("report.pdf")
	if err != nil {
		panic(err)
	}
	fmt.Println(md)
}

Production

time.Duration

default:"120s"

Always set an explicit timeout to http.Client. The NewClient client above already does this, but if you use http.DefaultClient directly, it will run out of timeout and a hung connection will block your goroutine indefinitely.

client := &http.Client{
	Timeout: 120 * time.Second,
}

For finer control (connection timeout vs. body read timeout), use a http.Transport with DialContext and ResponseHeaderTimeout:

transport := &http.Transport{
	DialContext: (&net.Dialer{
		Timeout: 10 * time.Second,
	}).DialContext,
	ResponseHeaderTimeout: 30 * time.Second,
}

client := &http.Client{
	Transport: transport,
	Timeout:   120 * time.Second, // lítotal limit, including body read
}

Retries with exponential backoff

For errors 429 (rate limit) and 5xx (transient server error), retry with exponential backoff and jitter. For the rest of the 4xx (400, 401, 403, 413, 415, 422) do not retry without correcting the request.

func withRetry(ctx context.Context, maxAttempts int, fn func() (string, error)) (string, error) {
	var lastErr error
	base := 500 * time.Millisecond

	for attempt := 0; attempt < maxAttempts; attempt++ {
		result, err := fn()
		if err == nil {
			return result, nil
		}
		lastErr = err

		var apiErr *flashmd.APIError
		if !errors.As(err, &apiErr) || !apiErr.Retryable() {
			return "", err // error no reintentable: devolver de inmediato
		}

		// exponential backoff with jitter: 0.5s, 1s, 2s, 4s...
		wait := base * time.Duration(1<<attempt)
		jitter := time.Duration(rand.Int63n(int64(wait) / 2))
		select {
		case <-ctx.Done():
			return "", ctx.Err()
		case <-time.After(wait + jitter):
		}
	}

	return "", fmt.Errorf("flashmd: agotados %d intentos: %w", maxAttempts, lastErr)
}

Uso:

markdown, err := withRetry(ctx, 5, func() (string, error) {
	return client.ConvertRaw(ctx, f, "application/pdf", opts)
})

If you prefer not to reimplement the backoff by hand, libraries like cenkalti/backoff offer configurable retry policies (exponential, maximum attempts, jitter) ready to use with any func() error.

BYOS (Bring Your Own Storage) for large files

For large documents, instead of waiting for the full markdown in the HTTP response, you can ask the API to upload it directly to your own storage (S3, GCS, R2, etc.) using a signed URL of type PUT. This avoids keeping the connection open and downloading the entire file into memory.

func convertToStorage(ctx context.Context, client *flashmd.Client, pdfPath, presignedPutURL, presignedHeadURL string) error {
	f, err := os.Open(pdfPath)
	if err != nil {
		return err
	}
	defer f.Close()

	payload, _ := json.Marshal(map[string]any{
		"filename":         filepath.Base(pdfPath),
		"mode":             "fast",
		"output_url":       presignedPutURL,
		"output_encoding":  "zstd", // enabled automatically when using output_url
		"output_head_url":  presignedHeadURL, // optional: detect cache hits antes de reprocesar
	})

	req, err := http.NewRequestWithContext(ctx, http.MethodPost, "https://api.markpdf.tech/convert/from-url", bytes.NewReader(payload))
	if err != nil {
		return err
	}
	req.Header.Set("x-api-key", os.Getenv("FLASH_MD_API_KEY"))
	req.Header.Set("content-type", "application/json")

	res, err := client.HTTPClient.Do(req)
	if err != nil {
		return err
	}
	defer res.Body.Close()

	// The response already comes in response_format=json (activated automatically
	// by output_url) confirming the upload, not the markdown itself.
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
	return nil
}

Using output_url automatically activates response_format=json, output_encoding=zstd, and slim=true. Pass output_head_url (a signed URL of type HEAD) if you want API to detect that the result already exists in your storage and avoid reprocessing the document.

Languages

Frameworks

Signed storage

Go

Go

Local file (minimal example)

URL signed (minimal example)

Cliente reutilizable

Client usage

Language error handling

Handling of 202 (auto-async)

Production

Retries with exponential backoff

BYOS (Bring Your Own Storage) for large files

​Go

​Local file (minimal example)

​URL signed (minimal example)

​Cliente reutilizable

​Client usage

​Language error handling

​Handling of 202 (auto-async)

​Production

​Retries with exponential backoff

​BYOS (Bring Your Own Storage) for large files

Go

Local file (minimal example)

URL signed (minimal example)

Cliente reutilizable

Client usage

Language error handling

Handling of 202 (auto-async)

Production

Retries with exponential backoff

BYOS (Bring Your Own Storage) for large files