Overview

PubContext provides an instant pub.dev documentation API optimized for LLM agents. Written in Go and optimized for concurrency and performance, the API scrapes documentation from pub.dev with a three-tier caching mechanism (memory → disk → live scraping) and converts it to clean markdown or structured JSON with lightning-fast response times.

All endpoints return JSON by default. Use the format=markdown parameter to get documentation in markdown format for LLM consumption.

Primary Use Cases

How It Works

The API uses a 3-tier caching strategy for optimal performance. When you request package documentation, the system checks each tier in order:

1
Memory Cache X-Source: memory

In-memory LRU cache with ~1 hour TTL. Fastest response times (~instant). Data is lost on server restart.

2
Disk Storage X-Source: disk

Persistent JSON files for each package. Fast response times. Survives server restarts and is automatically refreshed when packages update.

3
Live Scraping X-Source: scrape

Fetches fresh documentation from pub.dev. Slowest (few seconds) but always current. Only used when package is not in cache or disk storage.

The X-Source response header tells you which tier served your request, and X-Cache indicates whether it was a cache hit or miss.

Quick Start

No authentication required. Start making requests immediately.

Base URL

https://blackfinch.pl/pubcontext/api/v1

Example: Search for a class

curl "https://blackfinch.pl/pubcontext/api/v1/packages/http/search?q=Client"

Example: Get package documentation

curl "https://blackfinch.pl/pubcontext/api/v1/packages/http?format=markdown"

Example: Check token estimate first

curl "https://blackfinch.pl/pubcontext/api/v1/packages/flutter/token-estimate"

Tool Definitions for LLM Agents

The API provides machine-readable tool definitions that LLM agents can use directly for function calling. This endpoint returns tool schemas compatible with OpenAI, Anthropic, and other LLM providers.

GET /api/v1/tools

Available Tools

Tool Name Description
get_token_estimate Check token counts before fetching docs - use this first!
get_package_documentation Fetch package docs with format and depth options
search_within_package BM25 semantic search within a package
search_packages Discover packages by query, category, or platform
get_package_metadata Quick metadata lookup without full docs
get_related_packages Find related packages
get_alternative_packages Find package alternatives
list_categories List all package categories
get_category_packages Get packages in a category
get_class Get specific class with constructors, properties, methods
get_function Get top-level function documentation
get_library Get all classes and functions in a specific library
⚠️
Large Package Warning: Some packages (like collection, flame) can exceed 100,000+ tokens at full depth. Always call get_token_estimate first to check token counts before fetching complete documentation. Use depth=summary or depth=classes to reduce token usage, or use search_within_package to find specific APIs without loading full docs.

Example Request

curl https://blackfinch.pl/pubcontext/api/v1/tools

Example Response

{
  "version": "1.0.0",
  "description": "PubContext API tools for retrieving Flutter/Dart package documentation...",
  "base_url": "https://blackfinch.pl/pubcontext",
  "tools": [
    {
      "name": "get_package_documentation",
      "description": "Get comprehensive documentation for a Flutter/Dart package...",
      "parameters": {
        "type": "object",
        "properties": {
          "package": {
            "type": "string",
            "description": "Package name (e.g., 'http', 'dio', 'provider')"
          },
          "format": {
            "type": "string",
            "enum": ["markdown", "json"],
            "default": "markdown"
          },
          "depth": {
            "type": "string",
            "enum": ["summary", "classes", "full"],
            "default": "full"
          }
        },
        "required": ["package"]
      }
    }
    // ... more tools
  ]
}

Usage with LLM Agents

LLM agents can fetch the tool definitions once and use them to understand available API capabilities. The tool schemas follow the JSON Schema format used by function calling APIs.

Search Within Package

Perform BM25 semantic search within a package's documentation. Search for classes, methods, properties, functions, constructors, or exceptions.

GET /api/v1/packages/{name}/search

Smart Ranking for LLM Agents

Search results are intelligently ranked for LLM agent workflows, answering the natural question flow: "What is this?" then "How do I create it?" then "How do I use it?"

  • Exact name matches prioritized: When searching for FluidAdSize, items named exactly "FluidAdSize" appear first
  • Type definitions first: Classes and exceptions with exact name matches get top priority, as they answer "what is this thing?"
  • Type priority: Results are ordered by type relevance: class > exception > function > constructor > method > property
  • Direct members preferred: Inherited methods/properties (like hashCode, toString) are ranked lower since direct members are usually more relevant

This ranking ensures that when an LLM agent searches for a class name, it gets the class definition first, followed by how to instantiate it, then its direct API surface.

Parameters

Parameter Type Description
q required string Search query
types string Comma-separated types to search: class,method,property,function,constructor,exception
limit integer Maximum results to return (default: 10)

Example Request

curl "https://blackfinch.pl/pubcontext/api/v1/packages/http/search?q=client&types=class,method"

Search Packages

Search for packages across the curated database and pub.dev. Filter by category, tags, and platform support.

GET /api/v1/search

Parameters

Parameter Type Description
q string Search query
category string Filter by category (e.g., networking, state, ui)
tags string Comma-separated tags to filter by
platforms string Platform filter: mobile, desktop, or all

Example Request

curl "https://blackfinch.pl/pubcontext/api/v1/search?q=http&category=networking"

Get Package Documentation

⚠️
Large Packages Warning: Some packages exceed 100,000+ tokens and may hit LLM context limits. Always check /token-estimate before fetching complete documentation, or use depth filtering to reduce token usage. See Best Practices for optimization strategies.

Retrieve full documentation for a Flutter/Dart package. Supports format selection, depth control, and chunking for large packages. For token estimation, use the dedicated /token-estimate endpoint.

GET /api/v1/packages/{name}

Parameters

Parameter Type Description
name required string Package name on pub.dev
format string Response format: json (default) or markdown
depth integer Documentation depth level (1-3). Higher = more detail
chunk integer Return specific chunk (0-indexed) for large responses
chunk_size integer Number of libraries per chunk (default: 5)

Example Request

curl "https://blackfinch.pl/pubcontext/api/v1/packages/http?format=markdown&depth=2"

Example Response (JSON)

{
  "package_name": "http",
  "version": "1.2.0",
  "description": "A composable, Future-based library for making HTTP requests.",
  "repository": "https://github.com/dart-lang/http",
  "homepage": "https://pub.dev/packages/http",
  "topics": ["http", "networking"],
  "sdk_version": ">=2.19.0 <4.0.0",
  "platforms": ["android", "ios", "linux", "macos", "web", "windows"],
  "libraries": [
    {
      "name": "http",
      "description": "A composable, Future-based library for making HTTP requests.",
      "classes": [...],
      "functions": [...],
      "exceptions": [...]
    }
  ]
}

Get Package Metadata

Retrieve only metadata for a package without triggering a documentation scrape. Fast endpoint for checking package info.

GET /api/v1/packages/{name}/metadata

Example Request

curl https://blackfinch.pl/pubcontext/api/v1/packages/http/metadata

Token Estimate

Get token count estimates for a package's documentation across different depth levels and formats. Useful for LLM agents to plan context usage before fetching full documentation.

GET /api/v1/packages/{name}/token-estimate

Response

Returns token estimates for all combinations of depth (summary, classes, full) and format (markdown, json). Uses format-specific ratios: 4.0 chars/token for Markdown and 4.7 chars/token for JSON. 

{
  "package_name": "http",
  "version": "1.2.0",
  "token_method": "markdown:chars/4.0, json:chars/4.7",
  "estimates": {
    "summary": {
      "markdown": 450,
      "json": 380
    },
    "classes": {
      "markdown": 3200,
      "json": 2850
    },
    "full": {
      "markdown": 15234,
      "json": 13890
    }
  }
}

Use Cases

  • Context Planning: LLM agents can check token counts before fetching to avoid context limits
  • Format Selection: Choose between markdown or JSON based on token efficiency
  • Depth Selection: Select appropriate depth level based on available context
  • Cost Estimation: Estimate API costs before making requests

Example Request

curl https://blackfinch.pl/pubcontext/api/v1/packages/http/token-estimate

Get Class Documentation

Get documentation for a specific class from a package. Returns the class description, constructors, properties, and methods. More efficient than fetching full package docs when you only need one class.

GET /api/v1/packages/{name}/class/{className}

Parameters

Parameter Type Description
name required string Package name (e.g., 'http', 'dio')
className required string Class name (e.g., 'Client', 'Response'). Case-insensitive.
format string json (default) or markdown
include_inherited boolean Include inherited members like toString, hashCode (default: false)

Example Requests

# Get Client class from http package (JSON)
curl "https://blackfinch.pl/pubcontext/api/v1/packages/http/class/Client"

# Get Client class in markdown format
curl "https://blackfinch.pl/pubcontext/api/v1/packages/http/class/Client?format=markdown"

# Include inherited members
curl "https://blackfinch.pl/pubcontext/api/v1/packages/http/class/Client?include_inherited=true"

Example Response (JSON)

{
  "package": "http",
  "version": "1.3.0",
  "library": "http",
  "class": {
    "name": "Client",
    "description": "The interface for HTTP clients that take care of maintaining persistent connections...",
    "constructors": [
      {
        "name": "Client",
        "signature": "Client()",
        "description": "Creates a new HTTP client."
      }
    ],
    "properties": [
      {
        "name": "userAgent",
        "type": "String",
        "description": "The default user-agent header sent with requests."
      }
    ],
    "methods": [
      {
        "name": "get",
        "signature": "Future<Response> get(Uri url, {Map<String, String>? headers})",
        "description": "Sends an HTTP GET request."
      }
    ]
  }
}

Get Function Documentation

Get documentation for a top-level function from a package (not a class method). Returns the function signature, description, and parameters.

GET /api/v1/packages/{name}/function/{functionName}

Parameters

Parameter Type Description
name required string Package name
functionName required string Function name (e.g., 'get', 'post', 'read')
format string json (default) or markdown

Example Request

curl "https://blackfinch.pl/pubcontext/api/v1/packages/http/function/get"

Example Response (JSON)

{
  "package": "http",
  "version": "1.3.0",
  "library": "http",
  "function": {
    "name": "get",
    "signature": "Future<Response> get(Uri url, {Map<String, String>? headers})",
    "description": "Sends an HTTP GET request with the given headers to the given URL."
  }
}

Get Library Documentation

Get documentation for a specific library within a package. Some packages have multiple libraries (e.g., 'http' package has 'http' and 'http_testing' libraries). Returns all classes, functions, and exceptions in that library.

GET /api/v1/packages/{name}/library/{libraryName}

Parameters

Parameter Type Description
name required string Package name
libraryName required string Library name (often same as package name)
format string json (default) or markdown
include_inherited boolean Include inherited members in classes (default: false)

Example Request

curl "https://blackfinch.pl/pubcontext/api/v1/packages/http/library/http_testing"

Example Response (JSON)

{
  "package": "http",
  "version": "1.3.0",
  "library": {
    "name": "http_testing",
    "description": "A library for testing code that uses the http package.",
    "classes": [
      {
        "name": "MockClient",
        "description": "A mock HTTP client designed for testing..."
      }
    ],
    "functions": [],
    "exceptions": []
  }
}

Categories

List all available package categories or get packages in a specific category.

GET /api/v1/categories
GET /api/v1/categories/{category}

Example Request

curl https://blackfinch.pl/pubcontext/api/v1/categories/networking

Find packages related to a given package based on category and tags.

GET /api/v1/packages/{name}/related

Example Request

curl https://blackfinch.pl/pubcontext/api/v1/packages/http/related

Package Alternatives

Get alternative packages that solve the same problem as a given package.

GET /api/v1/packages/{name}/alternatives

Example Request

curl https://blackfinch.pl/pubcontext/api/v1/packages/dio/alternatives

Async Scraping

Trigger an asynchronous scrape job for a package. Useful for large packages where synchronous scraping would timeout.

POST /api/v1/packages/{name}/scrape

Example Request

curl -X POST https://blackfinch.pl/pubcontext/api/v1/packages/flutter/scrape

Example Response

{
  "job_id": "abc123",
  "package": "flutter",
  "status": "pending",
  "created_at": "2024-01-15T10:30:00Z"
}

Job Management

List recent scrape jobs and check their statuses.

GET /api/v1/jobs
GET /api/v1/jobs/{job_id}

Job States

State Description
pending Job is queued, waiting to be processed
processing Job is currently being executed
complete Job finished successfully
failed Job encountered an error

Best Practices

Recommendations for optimal API usage.

For LLM Agents

  • Search first - Use /search endpoint to find relevant classes/methods before requesting full documentation
  • Use depth parameter - Start with depth=signatures for quick overviews, drill down to depth=full only when needed
  • Check token estimates - Use /token-estimate to understand context window impact before fetching large packages
  • Leverage chunking - For large packages, use chunk and total_chunks parameters to paginate results

For Performance

  • Monitor cache headers - Check X-Source to understand response latency (memory is fastest)
  • Reuse requests - Cached responses are returned instantly, so repeated queries are efficient
  • Use async scraping - For batch operations, use POST endpoints to queue jobs

Response Format

All API responses follow a consistent JSON structure.

Success Response

{
  "package": "http",
  "version": "1.2.0",
  "description": "A composable API for making HTTP requests",
  "data": { ... }
}

Error Response

{
  "error": "Package not found",
  "code": "NOT_FOUND",
  "status": 404
}

Markdown Format

Use format=markdown to receive documentation as LLM-friendly markdown text instead of structured JSON.

Common Parameters

Parameters available across multiple endpoints.

Parameter Type Description
format string json (default) or markdown
depth string full, descriptions, or signatures
limit integer Maximum number of results to return

Cache Headers

All responses include cache-related headers for transparency.

Header Values Description
X-Cache HIT / MISS Whether the response came from cache
X-Source memory / disk / scrape Where the data was retrieved from
X-Cache-TTL integer (seconds) Time remaining until cache expiration

Documentation Freshness

The API automatically checks for documentation updates.

Background Freshness Checking

When documentation is served, if the cached data is older than the freshness interval (default: 24 hours), the API spawns a background task to check pub.dev for a newer version. If found, the documentation is re-scraped and subsequent requests receive the updated content.

Version Information

Each response includes:

  • version - The documented package version
  • published_at - When the version was published to pub.dev
  • last_scraped_at - When the documentation was last fetched

Force Refresh

To force a fresh scrape regardless of cache state, use the async scrape endpoint: 

POST /api/v1/packages/{name}/scrape