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

> Learn how to use the provider API catalog system to research external services in Agent Native. Discover, document, and execute HTTP requests seamlessly with our three-step workflow.

- Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native)
- Tags: how-to-guide
- Published: 2026-06-28

---

**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](https://github.com/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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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.

```typescript
// 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.

```typescript
// 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.

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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.