How to Use the Provider API Catalog System for Research in Agent Native

The Provider API Catalog system provides a flexible three-step workflow to discover, document, and execute HTTP requests against any external service using the provider-api-catalog, provider-api-docs, and provider-api-request actions, even when no first-class action exists for the specific endpoint.

The Provider API Catalog system in the BuilderIO/agent-native repository acts as a generic escape hatch for researching and interacting with external HTTP APIs. This system allows researchers to explore provider capabilities, extract endpoint specifications, and execute authenticated requests with automatic pagination and data staging.

Understanding the Provider API Catalog Architecture

The system consists of three discrete actions that work together to provide complete API research capabilities. These actions delegate their core logic to a shared runtime layer that handles credential resolution, SSRF protection, and request signing.

The Three Core Actions

According to the source code in packages/dispatch/src/actions/, the workflow relies on:

• provider-api-catalog (provider-api-catalog.ts): Lists all available provider APIs, including built-in providers and custom registrations, returning metadata such as base URLs, authentication styles, and documentation links.
• provider-api-docs (provider-api-docs.ts): Fetches and extracts documentation for a specific provider, supporting OpenAPI specs, changelogs, and README files with multiple response formats.
• provider-api-request (provider-api-request.ts): Executes authenticated HTTP requests against provider endpoints with built-in pagination support and optional data staging.

Runtime Implementation

The underlying runtime in packages/dispatch/src/server/lib/provider-api.ts provides the implementation for these actions. The runtime aggregates built-in provider IDs from PROVIDER_API_IDS and custom providers registered via provider-api-register. The core provider-API runtime in packages/core/src/provider-api/ (created via createProviderApiRuntime) manages credential injection through getCredentialContext, enforces SSRF guards, and handles pagination logic using cursor paths and parameter mappings.

Discovering Provider Capabilities

To begin researching an external API, first list all available providers using the provider-api-catalog action. This returns a catalog containing each provider's id, baseUrl, authType, credential keys, documentation URLs, and placeholder variables.

// CLI usage
pnpm action provider-api-catalog

// Programmatic usage with React hook
const { mutate: listProviders } = useActionMutation('provider-api-catalog');
listProviders({});

The listProviderApiCatalog function in the runtime aggregates results from both built-in providers and user-scoped custom registrations, providing a unified view of available integrations.

Fetching Provider Documentation

Once you identify a provider, extract its documentation using provider-api-docs. This action supports fetching OpenAPI specifications, changelogs, or arbitrary documentation URLs, with options to return raw text, markdown, or extracted link matches.

// Fetch built-in HubSpot documentation
pnpm action provider-api-docs provider=hubspot

// Fetch custom documentation URL with specific format
pnpm action provider-api-docs provider=hubspot url=https://api.hubspot.com/openapi.json responseMode=markdown

The fetchProviderApiDocs runtime method respects SSRF guards and can extract readable markdown or specific regex matches, allowing you to locate exact endpoint definitions, query parameters, and request body schemas.

Executing Authenticated Requests

After identifying the required endpoint, execute requests using provider-api-request. This action automatically injects stored credentials, supports pagination configuration, and can stage large results as queryable datasets.

pnpm action provider-api-request \
  provider=hubspot \
  method=GET \
  path=/crm/v3/objects/contacts \
  query='{"limit":100}' \
  stageAs=hubspot_contacts \
  itemsPath=results \
  pagination='{"nextCursorPath":"paging.next","cursorParam":"after"}'

Key parameters include:

• stageAs: Creates a named staged dataset for later analysis
• itemsPath: JSON path to the array of results (e.g., results or items)
• pagination: Configuration object specifying nextCursorPath (where to find the next cursor in the response), cursorParam (the query parameter name for the cursor), and optional fetchAllPages flag

The executeProviderApiRequest runtime function uses getCredentialContext to inject appropriate authentication headers (OAuth tokens, API keys, etc.) and automatically redacts secrets from responses.

Staging Data for Analysis

When you specify stageAs in a request, the system automatically paginates through all results and stores them as a staged dataset. Query this data using SQL-like syntax:

pnpm query-staged-dataset hubspot_contacts \
  "SELECT email, firstname, lastname FROM hubspot_contacts WHERE createdAt > '2024-01-01'"

This staged data can be joined with internal tables, aggregated, or fed into LLM prompts for deeper analysis without requiring repeated API calls.

Complete Research Workflow Example

Combine all three actions in a single research script to discover, document, and extract data from any provider:

import { useActionMutation } from '@agent-native/react';

// Step 1: List providers and select target
const { data: catalog } = await useActionMutation('provider-api-catalog').mutateAsync({});
const providerId = 'google_calendar';

// Step 2: Fetch documentation to discover endpoints
const { data: docs } = await useActionMutation('provider-api-docs').mutateAsync({
  provider: providerId,
});

// Step 3: Execute paginated request and stage results
await useActionMutation('provider-api-request').mutateAsync({
  provider: providerId,
  method: 'GET',
  path: '/calendars/primary/events',
  query: {
    timeMin: '2024-05-01T00:00:00Z',
    timeMax: '2024-06-01T00:00:00Z',
    maxResults: 250,
  },
  stageAs: 'google_events_may2024',
  itemsPath: 'items',
  pagination: {
    nextCursorPath: 'nextPageToken',
    cursorParam: 'pageToken',
  },
});

This pattern works identically for any provider registered in the system, whether built-in or custom, providing a consistent interface for API research across heterogeneous services.

Summary

• The Provider API Catalog system provides three actions (provider-api-catalog, provider-api-docs, provider-api-request) that enable complete API research workflows without custom code.
• The runtime implementation in packages/dispatch/src/server/lib/provider-api.ts and packages/core/src/provider-api/ handles credential injection, SSRF protection, and pagination automatically.
• Use stageAs and pagination parameters to extract large datasets and store them as queryable staged datasets for downstream analysis.
• Any provider registered via provider-api-register becomes discoverable and callable using the same three-action pattern.

Frequently Asked Questions

What is the provider API catalog system?

The provider API catalog system is a generic interface in Agent Native that allows researchers to interact with any external HTTP API through a standardized three-step workflow. It consists of actions to list available providers (provider-api-catalog), fetch their documentation (provider-api-docs), and execute authenticated requests (provider-api-request), enabling exploration of APIs even when no first-class integration exists for specific endpoints.

How does authentication work with provider-api-request?

The provider-api-request action automatically handles authentication by injecting stored credentials from the credential context. According to the runtime implementation in packages/core/src/provider-api/, the system uses getCredentialContext to resolve the appropriate auth header (OAuth tokens, API keys, or other methods) based on the provider's authType configuration, and automatically redacts secrets from response logs for security.

Can I use custom providers not built into Agent Native?

Yes, the system supports custom providers registered via the provider-api-register action. The runtime in packages/dispatch/src/server/lib/provider-api.ts aggregates both built-in provider IDs from PROVIDER_API_IDS and user- or org-scoped custom providers, making them discoverable through the same provider-api-catalog action and callable via provider-api-request using consistent credential management and request signing.

How do I handle pagination when extracting large datasets?

Configure pagination using the pagination parameter object in provider-api-request, specifying nextCursorPath (the JSON path to the cursor in responses), cursorParam (the query parameter name for the cursor), and itemsPath (the JSON path to the result array). When combined with stageAs, the runtime automatically loops through all pages and stores the complete dataset, eliminating the need for manual pagination logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}