# Get capability, provider, or endpoint details
Source: https://docs.dumplingai.com/api-reference/catalog/details

/api-reference/openapi-v2.yaml post /api/v2/details



# Search capabilities, providers, and endpoints
Source: https://docs.dumplingai.com/api-reference/catalog/search

/api-reference/openapi-v2.yaml post /api/v2/search



# Run a capability or endpoint
Source: https://docs.dumplingai.com/api-reference/execution/run

/api-reference/openapi-v2.yaml post /api/v2/run



# Unified API
Source: https://docs.dumplingai.com/api-reference/unified-api

Capability-first execution and provider endpoints under /api/v2.

# Unified API

DumplingAI's Unified API is the capability-first API lane under `/api/v2`.

It is the recommended default for new focused data integrations. Use Direct Endpoints under `/api/v1` when you need legacy request shapes or the current Make.com module flow.

This surface is organized around two ways to work:

* `capabilities`: ask DumplingAI to do a job like `search_news`, `extract_document`, or `scrape_page`
* `provider endpoints`: call a specific managed upstream endpoint like `serper.search`, `perplexity.search`, or `firecrawl.scrape`

Direct Endpoints under `/api/v1` remain available and unchanged.

## Base URL

```text theme={null}
https://app.dumplingai.com
```

## Capability lane

Use capabilities when you want the cleanest interface.

### Endpoints

* `POST /api/v2/search`
* `POST /api/v2/details`
* `POST /api/v2/run`

`POST /api/v2/details` now returns a lean default object. Pass `includeRelated: true` when you also want related providers, endpoints, and capabilities.

### Example

```bash theme={null}
curl -X POST https://app.dumplingai.com/api/v2/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "capability",
    "id": "search_news",
    "input": {
      "query": "latest AI regulation",
      "dateRange": "pastWeek"
    }
  }'
```

## Provider endpoint lane

Use provider endpoints when you know the upstream API you want.

### Endpoints

* `POST /api/v2/search`
* `POST /api/v2/details`
* `POST /api/v2/run`

### Example

```bash theme={null}
curl -X POST https://app.dumplingai.com/api/v2/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "endpoint",
    "id": "serper.search",
    "input": {
      "query": "best seo keywords for plumbers in nyc"
    },
    "options": {
      "include_native": true
    }
  }'
```

## Response envelope

Both lanes share the same outer response shape:

```json theme={null}
{
  "success": true,
  "requestId": "req_123",
  "object": "capability_result",
  "data": {},
  "meta": {}
}
```

Error responses:

```json theme={null}
{
  "success": false,
  "requestId": "req_123",
  "error": "Provider not allowed for this API key",
  "code": "PROVIDER_NOT_ALLOWED"
}
```

## Current capabilities

* `google_search`
* `search_news`
* `search_places`
* `get_google_reviews`
* `crawl_site`
* `screenshot`
* `extract_web`
* `extract_document`
* `extract_image`
* `extract_audio`
* `extract_video`
* `scrape_page`
* `get_youtube_transcript`

Discovery aliases:

* `crawl` resolves to `crawl_site`
* `extract` resolves to `extract_web`

Provider notes:

* `screenshot` supports `firecrawl`, `scrapingfish`, and `phantomjscloud`
* `extract_web`, `extract_document`, `extract_image`, `extract_audio`, and `extract_video` are DumplingAI-managed capabilities and surface `provider: "dumplingai"`
* `crawl_site` defaults to `firecrawl` and falls back to `spidercloud` when needed

## Current provider endpoints

Examples:

* `serper.search`
* `serper.news`
* `serper.places`
* `serper.maps`
* `serper.autocomplete`
* `serper.images`
* `serper.videos`
* `serper.shopping`
* `serper.scholar`
* `serper.patents`
* `perplexity.search`
* `firecrawl.scrape`
* `firecrawl.search`
* `firecrawl.map`
* `firecrawl.crawl`
* `firecrawl.screenshot`
* `scrapingfish.screenshot`
* `spidercloud.scrape`
* `spidercloud.crawl`
* `spidercloud.links`
* `dataforseo.google_reviews`
* `phantomjscloud.screenshot`
* `phantomjscloud.scrape`
* `scrapecreators.youtube_transcript`
* `transcriptapi.youtube_transcript`
* `transcriptapi.youtube_search`
* `transcriptapi.youtube_channel_videos`
* `perplexity.search`
* `dataforseo.dataforseo_labs_google_keyword_ideas`

### Screenshot example

```bash theme={null}
curl -X POST https://app.dumplingai.com/api/v2/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "capability",
    "id": "screenshot",
    "provider": "firecrawl",
    "input": {
      "url": "https://example.com",
      "fullPage": true,
      "wait": 1000,
      "viewport": {
        "width": 1280,
        "height": 800
      }
    }
  }'
```

## Related docs

* [MCP Server](/mcp-server)
* [API Reference Overview](/api-reference/introduction)


# Get balance and budget information for the authenticated API key
Source: https://docs.dumplingai.com/api-reference/usage/balance

/api-reference/openapi-v2.yaml get /api/v2/balance



# Get usage and request logs for the authenticated API key
Source: https://docs.dumplingai.com/api-reference/usage/requests

/api-reference/openapi-v2.yaml get /api/v2/usage



# Get credit transactions for the authenticated API key
Source: https://docs.dumplingai.com/api-reference/usage/transactions

/api-reference/openapi-v2.yaml get /api/v2/transactions



# Catalog Model
Source: https://docs.dumplingai.com/api-reference/v2/catalog

How capabilities, providers, and provider endpoints are presented in the Unified API.

# Workbench Model

The Unified API Workbench is organized around three human-facing objects:

* `Capabilities`
* `Providers`
* `Endpoints`

## Capabilities

Capabilities are the default lane.

Use them when you want DumplingAI to standardize the job and keep the request shape simple.

## Providers

Providers are vendor overview pages.

Use them when you know the supplier you want and want to browse everything Dumpling exposes for that provider.

## Endpoints

Endpoints are provider-native operations.

Use them when you want exact provider behavior and provider-specific output, rather than DumplingAI's normalized abstraction.


# API Reference
Source: https://docs.dumplingai.com/api-reference/v2/introduction

Reference for DumplingAI's Unified API under /api/v2.

# API Reference

Use `/api/v2` for DumplingAI's Unified API.

This is the new API lane for technical users who want either:

* standardized capabilities
* direct access to exact managed provider endpoints

## Two ways to use `/api/v2`

### Capabilities

Use capabilities when you want the simplest possible request shape.

Examples:

* `google_search`
* `search_news`
* `search_places`
* `get_google_reviews`
* `crawl_site`
* `screenshot`
* `extract_web`
* `extract_document`
* `extract_image`
* `extract_audio`
* `extract_video`
* `scrape_page`
* `get_youtube_transcript`

### Provider endpoints

Use provider endpoints when you want the exact upstream provider endpoint.

Examples:

* `serper.search`
* `serper.news`
* `serper.places`
* `serper.maps`
* `serper.autocomplete`
* `serper.images`
* `serper.videos`
* `serper.shopping`
* `serper.scholar`
* `serper.patents`
* `perplexity.search`
* `firecrawl.scrape`
* `firecrawl.screenshot`
* `scrapingfish.screenshot`
* `phantomjscloud.screenshot`
* `transcriptapi.youtube_transcript`
* `transcriptapi.youtube_search`
* `dataforseo.dataforseo_labs_google_keyword_ideas`

Provider notes:

* `screenshot` supports `firecrawl`, `scrapingfish`, and `phantomjscloud`
* `extract_web`, `extract_document`, `extract_image`, `extract_audio`, and `extract_video` are DumplingAI-managed and use `provider: "dumplingai"`

## What OpenAPI covers here

The OpenAPI spec documents the real transport endpoints under `/api/v2`:

* search
* details
* run
* balance
* usage
* transactions

Capabilities, providers, and endpoints are documented through the Unified API Workbench pages rather than fake per-operation HTTP paths.

Use the canonical execution request shape when calling `/api/v2/run`:

```json theme={null}
{
  "type": "capability",
  "id": "extract_document",
  "input": {
    "inputMethod": "url",
    "files": ["https://example.com/invoice.pdf"],
    "prompt": "Extract the invoice number and total due"
  }
}
```

Or for a provider endpoint:

```json theme={null}
{
  "type": "endpoint",
  "id": "firecrawl.scrape",
  "input": {
    "url": "https://example.com",
    "format": "markdown"
  }
}
```


# Skills + CLI
Source: https://docs.dumplingai.com/cli

Use DumplingAI's CLI and packaged skills for /api/v2 capability discovery, execution, and agent setup.

# Skills + CLI

Use the official CLI to work with DumplingAI's Unified API directly from your terminal.

The CLI is built around the `/api/v2` workflow:

1. search the catalog
2. inspect the capability or endpoint you want
3. run it with JSON input

* npm package: [dumplingai-cli](https://www.npmjs.com/package/dumplingai-cli)
* source code: [github.com/DumplingAI/cli](https://github.com/DumplingAI/cli)

## Install

```bash theme={null}
npm install -g dumplingai-cli
dumplingai init
```

`dumplingai init` walks through authentication and can install bundled agent skills in the same flow.

## Authenticate

<CodeGroup>
  ```bash API key login theme={null}
  dumplingai login --api-key sk_yourkey
  ```

  ```bash Environment variable theme={null}
  export DUMPLINGAI_API_KEY=sk_yourkey
  ```
</CodeGroup>

Get your API key from [app.dumplingai.com/settings/api-keys](https://app.dumplingai.com/settings/api-keys).

Then confirm setup:

```bash theme={null}
dumplingai status
```

## Common commands

| Command                                       | Description                                              |
| --------------------------------------------- | -------------------------------------------------------- |
| `dumplingai init`                             | Authenticate and optionally install bundled agent skills |
| `dumplingai login --api-key <key>`            | Save API credentials                                     |
| `dumplingai logout`                           | Remove stored credentials                                |
| `dumplingai status`                           | Show CLI version, auth status, and `/v2` balance context |
| `dumplingai env pull`                         | Write API key into `.env`                                |
| `dumplingai catalog search <prompt>`          | Search `/api/v2` capabilities, providers, and endpoints  |
| `dumplingai catalog details <type> <id>`      | Inspect a specific catalog object                        |
| `dumplingai run <type> <id> --input '<json>'` | Execute a capability or endpoint                         |
| `dumplingai balance`                          | Show balance and budget information                      |
| `dumplingai usage`                            | Show request usage logs                                  |
| `dumplingai transactions`                     | Show credit transaction history                          |
| `dumplingai view-config`                      | Print resolved configuration                             |
| `dumplingai version`                          | Print CLI version                                        |

## Examples

```bash theme={null}
# Discover available capabilities
dumplingai catalog search "google search"

# Inspect a capability before running it
dumplingai catalog details capability google_search

# Execute a capability with inline JSON input
dumplingai run capability google_search --input '{"query":"latest TypeScript release"}'

# Execute an endpoint with JSON from disk
dumplingai run endpoint firecrawl.scrape --input-file payload.json

# Inspect account data
dumplingai balance
dumplingai usage --object-type capability --limit 20
```

## Output and automation tips

* Use `--input-file` when your request body is easier to manage as JSON on disk.
* Redirect large JSON responses into `.dumplingai/` or another local file when you want to inspect them incrementally.
* Use `dumplingai env pull` when you want the CLI key written into a local `.env` file for adjacent tooling.

```bash theme={null}
dumplingai run capability scrape_page --input '{"url":"https://example.com"}' > .dumplingai/page.json
head -40 .dumplingai/page.json
```

## Agent skills

The CLI repo also ships packaged skills for supported coding agents. These help agents discover DumplingAI APIs, choose the right CLI commands, and reuse workflow templates.

### Install

For Codex, Claude Code, and Cursor, `dumplingai init` is the recommended path because it can install bundled skills during setup.

Use manual installation only if:

* you skipped skills during `dumplingai init`
* you want to selectively install skills
* you are using another compatible agent environment

```bash theme={null}
npx skills add dumplingai/cli
```

You can list and selectively install packaged skills:

```bash theme={null}
npx skills add dumplingai/cli --list
npx skills add dumplingai/cli --skill discovering-dumplingai-apis --skill dumplingai-cli
```

You can also run `dumplingai init` and install skills during setup.

### Supported environments

Local agent/runtime folders such as these are intentionally supported:

* `./.claude/skills/dumplingai-cli` (Claude Code)
* `./.agents/skills/dumplingai-cli` (Agents)
* `./.cursor/skills/dumplingai-cli` (Cursor)
* `./.codex/skills/dumplingai-cli` (Codex)

### What gets installed

Depending on the package you install, these skills can include API discovery guidance, CLI usage patterns, and reusable workflow templates such as YouTube-to-blog-post or social media generation.

### Validate installation

Inspect one of the installed directories for your agent environment:

```bash theme={null}
ls -la ./.codex/skills/dumplingai-cli
```

## Next steps

* Use DumplingAI with AI clients: [MCP Server](/mcp-server)
* Learn the `/v2` model: [Unified API](/unified-api-platform)
* Browse `/v2` capabilities and endpoints: [API Reference](/api-reference/v2/introduction)


# Get Started
Source: https://docs.dumplingai.com/documentation/v2/get-started

Choose your path: no-code automation, direct API, or AI agent via MCP or CLI.

# Get Started

The Unified API under `/api/v2` is the recommended default for new focused data integrations. Pick the path that matches how you're connecting.

## Choose your path

<CardGroup>
  <Card title="Make.com, n8n or similar" icon="workflow" href="/documentation/v2/get-started#no-code-automation">
    Use your DumplingAI API key as a connection credential in any no-code or automation platform.
  </Card>

  <Card title="Building my own app" icon="code" href="/documentation/v2/get-started#direct-api">
    Call the Unified API directly from your code. Create an API key and use Workbench to explore capabilities.
  </Card>

  <Card title="Claude, Codex, Cursor or similar" icon="bot" href="/documentation/v2/get-started#ai-agents">
    Connect your AI agent through `/mcp/v2` or the DumplingAI CLI. No API key needed — sign in with OAuth.
  </Card>
</CardGroup>

***

## No-code automation

1. Create an API key in the [DumplingAI dashboard](https://app.dumplingai.com/api-keys)
2. Paste it as a connection credential in Make.com, n8n, Zapier, or any HTTP-based automation tool
3. Follow the platform-specific setup guides:
   * [Make.com setup](https://app.dumplingai.com/integrations/make-dot-com)
   * [n8n templates](https://n8n.io/creators/yang/)

***

## Direct API

1. Create an API key in the [DumplingAI dashboard](https://app.dumplingai.com/api-keys)
2. Call the Unified API run endpoint with your key:

```bash theme={null}
curl -X POST https://app.dumplingai.com/api/v2/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "type": "capability",
    "id": "search_news",
    "input": {
      "query": "latest AI infrastructure news",
      "dateRange": "pastWeek"
    }
  }'
```

3. Use [Workbench](https://app.dumplingai.com/workbench) to inspect inputs, outputs, and available capabilities.

See the [Unified API](/unified-api-platform) page for a full overview of the capability and provider-endpoint model.

***

## AI agents

No API key required — connect through MCP or the CLI and sign in with OAuth.

### MCP

Add this server URL to your AI client:

```text theme={null}
https://mcp.dumplingai.com/mcp/v2
```

Client-specific one-liners:

| Client      | Command                                                                        |
| ----------- | ------------------------------------------------------------------------------ |
| Claude Code | `claude mcp add dumplingai --transport http https://mcp.dumplingai.com/mcp/v2` |
| Codex       | `codex mcp add dumplingai --url https://mcp.dumplingai.com/mcp/v2`             |
| Cursor      | Use Cursor's remote MCP server option with `https://mcp.dumplingai.com/mcp/v2` |
| ChatGPT     | Add `https://mcp.dumplingai.com/mcp/v2` as your MCP server or connector URL    |

See the full [MCP Server guide](/mcp-server) for screenshots and OAuth flow details.

### CLI

Run capabilities, search the catalog, and inspect details from your terminal:

```bash theme={null}
npx dumplingai
```

See the [CLI guide](/cli) for all available commands.

***

## Next steps

<CardGroup>
  <Card title="MCP Server" icon="plug" href="/mcp-server">
    Client-specific MCP setup for Claude, Codex, Cursor, ChatGPT, and more
  </Card>

  <Card title="CLI" icon="terminal" href="/cli">
    Run capabilities and explore the catalog from your terminal
  </Card>

  <Card title="Unified API" icon="book" href="/unified-api-platform">
    Learn the v2 capability and provider-endpoint model
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/v2/introduction">
    Browse the transport endpoints and request model for `/api/v2`
  </Card>
</CardGroup>

## Looking for direct endpoints?

Use [the Direct Endpoints Get Started page](/documentation/v1/get-started) when you specifically want legacy request shapes, the Direct Endpoint Playground, or the current Make.com module flow.


# Migrating from Direct Endpoints
Source: https://docs.dumplingai.com/documentation/v2/migrating-from-direct-endpoints

Map common /api/v1 Direct Endpoint calls to the Unified API under /api/v2.

# Migrating from Direct Endpoints

Direct Endpoints under `/api/v1` remain supported. For new focused data integrations, prefer the Unified API under `/api/v2` so you get one request envelope, Workbench discovery, API key policies, usage logs, and provider-aware routing.

## Quick map

| Direct Endpoint                       | Unified API target                       | Notes                                                            |
| ------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------- |
| `POST /api/v1/scrape`                 | `capability:scrape_page`                 | Best default for new page scraping jobs.                         |
| `POST /api/v1/crawl`                  | `capability:crawl_site`                  | Use for crawl jobs with a simple site-level contract.            |
| `POST /api/v1/search-news`            | `capability:search_news`                 | Use for recent-news discovery.                                   |
| `POST /api/v1/get-youtube-transcript` | `capability:get_youtube_transcript`      | Use for normalized transcript output and provider fallback.      |
| `POST /api/v1/get-tiktok-profile`     | `endpoint:scrapecreators.tiktok_profile` | Provider-native TikTok data stays in the provider endpoint lane. |
| `POST /api/v1/extract-audio`          | `capability:extract_audio`               | Use for audio summarization or structured audio extraction.      |
| `POST /api/v1/extract-video`          | `capability:extract_video`               | Use for video summarization or structured video extraction.      |

## Scrape

Direct Endpoint:

```bash theme={null}
curl -X POST https://app.dumplingai.com/api/v1/scrape \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "url": "https://example.com/article",
    "format": "markdown"
  }'
```

Unified API:

```bash theme={null}
curl -X POST https://app.dumplingai.com/api/v2/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "type": "capability",
    "id": "scrape_page",
    "input": {
      "url": "https://example.com/article",
      "format": "markdown"
    }
  }'
```

## Search news

Direct Endpoint:

```bash theme={null}
curl -X POST https://app.dumplingai.com/api/v1/search-news \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "query": "latest AI infrastructure news",
    "dateRange": "pastWeek"
  }'
```

Unified API:

```bash theme={null}
curl -X POST https://app.dumplingai.com/api/v2/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "type": "capability",
    "id": "search_news",
    "input": {
      "query": "latest AI infrastructure news",
      "dateRange": "pastWeek"
    }
  }'
```

## YouTube transcript

Direct Endpoint:

```bash theme={null}
curl -X POST https://app.dumplingai.com/api/v1/get-youtube-transcript \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  }'
```

Unified API:

```bash theme={null}
curl -X POST https://app.dumplingai.com/api/v2/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "type": "capability",
    "id": "get_youtube_transcript",
    "input": {
      "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    }
  }'
```

## TikTok provider endpoint

TikTok profile data is provider-native, so use the provider endpoint lane:

```bash theme={null}
curl -X POST https://app.dumplingai.com/api/v2/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "type": "endpoint",
    "id": "scrapecreators.tiktok_profile",
    "input": {
      "handle": "duolingo"
    },
    "options": {
      "include_native": true
    }
  }'
```

## Media extraction

Use `extract_audio` or `extract_video` for focused media extraction:

```bash theme={null}
curl -X POST https://app.dumplingai.com/api/v2/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "type": "capability",
    "id": "extract_audio",
    "input": {
      "inputMethod": "url",
      "audio": "https://example.com/interview.mp3",
      "prompt": "Summarize the key action items"
    }
  }'
```

## Still use Direct Endpoints for these

Keep using `/api/v1` when you need current Make.com compatibility, PDF utility endpoints, AI image generation, agent completion, JS/Python execution, or LinkedIn endpoints.


# DumplingAI MCP Server
Source: https://docs.dumplingai.com/mcp-server

Use DumplingAI through MCP, with /mcp/v2 as the default capability-first surface and /mcp as the legacy catalog.

> ## Documentation Index
>
> Fetch the complete documentation index at: [https://docs.dumplingai.com/llms.txt](https://docs.dumplingai.com/llms.txt)
> Use this file to discover all available pages before exploring further.

# DumplingAI MCP Server

Connect Claude, Codex, Cursor, Windsurf, ChatGPT, and other MCP-compatible clients to DumplingAI.

The recommended hosted MCP server is:

```text theme={null}
https://mcp.dumplingai.com/mcp/v2
```

`/mcp/v2` is the default surface for new users. It uses OAuth, so most modern MCP clients only need the server URL and will handle browser sign-in automatically.

## Overview

DumplingAI currently exposes two MCP surfaces:

* `/mcp/v2`: the recommended capability-first surface backed by the Unified API
* `/mcp`: the legacy v1 tool catalog that still uses API keys

Start with `/mcp/v2` unless you specifically need the older v1 catalog.

## Getting started

Add this server URL to your MCP client:

```text theme={null}
https://mcp.dumplingai.com/mcp/v2
```

On first connection, DumplingAI redirects you to your browser to sign in and approve access. The OAuth grant is bound to your current active DumplingAI organization.

You do not need to configure an API key for `/mcp/v2`.

## App setup

### Claude Code

Run this command:

```bash theme={null}
claude mcp add dumplingai --transport http https://mcp.dumplingai.com/mcp/v2
```

Then restart Claude Code if needed and complete the browser-based OAuth flow on first use.

### Claude Desktop

Add a new remote MCP server in Claude Desktop and use:

```text theme={null}
https://mcp.dumplingai.com/mcp/v2
```

Claude Desktop should open the DumplingAI OAuth flow in your browser the first time you connect.

### Codex

Run this command:

```bash theme={null}
codex mcp add dumplingai --url https://mcp.dumplingai.com/mcp/v2
```

Codex will open the OAuth flow in your browser on first use.

### Cursor

Add a new MCP server in Cursor and set the URL to:

```text theme={null}
https://mcp.dumplingai.com/mcp/v2
```

Use Cursor's remote or URL-based MCP server option if it asks for a connection type.

### Windsurf

Add a remote MCP server with this URL:

```text theme={null}
https://mcp.dumplingai.com/mcp/v2
```

Then finish the OAuth flow in your browser when prompted.

### VS Code / Copilot

Add DumplingAI to your MCP settings:

```json theme={null}
{
  "servers": {
    "dumplingai": {
      "type": "http",
      "url": "https://mcp.dumplingai.com/mcp/v2"
    }
  }
}
```

### ChatGPT

Add a connector or MCP server using:

```text theme={null}
https://mcp.dumplingai.com/mcp/v2
```

Then complete the DumplingAI OAuth flow when ChatGPT prompts you.

### Other MCP clients

Any MCP client that supports hosted HTTP servers and OAuth discovery should work with:

```text theme={null}
https://mcp.dumplingai.com/mcp/v2
```

Clients discover the auth flow automatically through DumplingAI's MCP OAuth metadata.

## Authentication

`/mcp/v2` uses OAuth. That means:

* you add the server URL only
* DumplingAI handles sign-in and consent in the browser
* you do not send `Authorization: Bearer YOUR_API_KEY` for `/mcp/v2`

If your client does not support MCP OAuth yet, use the legacy `/mcp` endpoint instead.

## Available tools

`/mcp/v2` exposes these capability-first tools:

| Tool                     | Description                                                                    |
| ------------------------ | ------------------------------------------------------------------------------ |
| `google_search`          | Search the web through DumplingAI's Unified API                                |
| `search_news`            | Find current headlines and recent news results                                 |
| `search_places`          | Search local businesses and Google Maps-style place results                    |
| `get_google_reviews`     | Fetch Google business reviews and reputation data                              |
| `crawl_site`             | Crawl a site and return normalized page results                                |
| `screenshot`             | Capture a page screenshot with optional wait, viewport, and full-page controls |
| `extract_web`            | Extract schema-shaped JSON from a webpage                                      |
| `extract_document`       | Extract text or structured data from one or more files                         |
| `extract_image`          | Extract text or structured data from one or more images                        |
| `extract_audio`          | Extract summaries or structured data from an audio file                        |
| `extract_video`          | Extract summaries or structured data from a video file                         |
| `scrape_page`            | Fetch and structure page content                                               |
| `get_youtube_transcript` | Get YouTube transcripts with optional timestamps                               |

Provider notes:

* `screenshot` supports `firecrawl`, `scrapingfish`, and `phantomjscloud`
* `extract_web`, `extract_document`, `extract_image`, `extract_audio`, and `extract_video` are DumplingAI-managed and surface `provider: "dumplingai"`

Example tool calls:

```json theme={null}
{
  "name": "search_news",
  "arguments": {
    "query": "latest AI news",
    "provider": "serper"
  }
}
```

```json theme={null}
{
  "name": "screenshot",
  "arguments": {
    "url": "https://example.com",
    "provider": "firecrawl",
    "fullPage": true,
    "wait": 1000,
    "viewport": {
      "width": 1280,
      "height": 800
    }
  }
}
```

```json theme={null}
{
  "name": "extract_document",
  "arguments": {
    "inputMethod": "url",
    "files": ["https://example.com/invoice.pdf"],
    "prompt": "Extract the invoice number and total amount",
    "provider": "dumplingai"
  }
}
```

```json theme={null}
{
  "name": "get_youtube_transcript",
  "arguments": {
    "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "includeTimestamps": true,
    "provider": "transcriptapi"
  }
}
```

## Troubleshooting

### Browser flow lands on the app instead of consent

If sign-in finishes but you land on the normal app instead of returning to your MCP client, disconnect and reconnect the MCP server so the client re-runs registration and OAuth.

### `localhost` vs `127.0.0.1`

Some clients register loopback callbacks with `127.0.0.1` and then authorize with `localhost`. DumplingAI normalizes loopback redirects for supported OAuth flows, but reconnecting the client is the fastest fix if an old registration is stuck.

### OAuth is not supported in my MCP client

Use the legacy API-key surface instead:

```text theme={null}
https://mcp.dumplingai.com/mcp
```

## Legacy `/mcp` fallback

Use the legacy endpoint only if your MCP client does not support OAuth yet or if you specifically need the broader v1 tool catalog.

The hosted legacy endpoint is:

```text theme={null}
https://mcp.dumplingai.com/mcp
```

Add it with an API key header:

```json theme={null}
{
  "mcpServers": {
    "DumplingAI": {
      "url": "https://mcp.dumplingai.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

Get your API key from [app.dumplingai.com](https://app.dumplingai.com).

### n8n

1. Add an **AI Agent** node to your workflow.
2. Add an **MCP Client Tool** node.
3. Create MCP credentials with:
   * **Connection Type**: HTTP Streamable
   * **URL**: `https://mcp.dumplingai.com/mcp`
   * **Authentication**: Header Auth
   * **Header Name**: `Authorization`
   * **Header Value**: `Bearer YOUR_API_KEY`
4. Connect the MCP Client Tool to your AI Agent.

<Note>
  Replace `YOUR_API_KEY` with your DumplingAI API key from [app.dumplingai.com](https://app.dumplingai.com).
</Note>

***

## Legacy `/mcp` tool catalog

The rest of this page documents the older `/mcp` surface backed by `/api/v1/*`.

## Legacy Available Tools

### Web Scraping & Extraction

#### `scrape`

Fetch structured data and HTML from a URL.

```json theme={null}
{
  "name": "scrape",
  "arguments": {
    "url": "https://example.com",
    "format": "markdown",
    "clean": true,
    "render": false,
    "proxyCountry": "US",
    "includeLinks": false,
    "extractionPrompt": "Extract the main article content",
    "extractionSchema": {
      "type": "object",
      "properties": {
        "title": { "type": "string" },
        "body": { "type": "string" }
      }
    }
  }
}
```

#### `crawl`

Crawl a site and return captured pages with metadata.

```json theme={null}
{
  "name": "crawl",
  "arguments": {
    "url": "https://example.com/blog",
    "limit": 50,
    "maxDepth": 3,
    "format": "markdown"
  }
}
```

#### `screenshot`

Capture a screenshot of a web page.

```json theme={null}
{
  "name": "screenshot",
  "arguments": {
    "url": "https://example.com",
    "fullPage": true,
    "width": 1280,
    "height": 800
  }
}
```

#### `extract`

Extract structured data from a URL using AI.

```json theme={null}
{
  "name": "extract",
  "arguments": {
    "url": "https://example.com/product",
    "prompt": "Extract the product name, price, and description",
    "schema": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "price": { "type": "number" },
        "description": { "type": "string" }
      }
    }
  }
}
```

***

### Search & Discovery

#### `search`

Perform a federated web search.

```json theme={null}
{
  "name": "search",
  "arguments": {
    "query": "latest AI news",
    "count": 5,
    "country": "US",
    "language": "en",
    "freshness": "week"
  }
}
```

#### `search_news`

Search Google News.

```json theme={null}
{
  "name": "search_news",
  "arguments": {
    "query": "electric vehicles 2025",
    "count": 10,
    "freshness": "day"
  }
}
```

#### `search_maps`

Search Google Maps.

```json theme={null}
{
  "name": "search_maps",
  "arguments": {
    "query": "coffee shops",
    "location": "San Francisco, CA"
  }
}
```

#### `search_places`

Search Google Places for businesses and points of interest.

```json theme={null}
{
  "name": "search_places",
  "arguments": {
    "query": "pizza restaurant",
    "location": "New York"
  }
}
```

#### `get_autocomplete`

Get Google search autocomplete suggestions.

```json theme={null}
{
  "name": "get_autocomplete",
  "arguments": {
    "query": "how to learn",
    "country": "US"
  }
}
```

#### `get_google_reviews`

Retrieve Google Business reviews.

```json theme={null}
{
  "name": "get_google_reviews",
  "arguments": {
    "query": "Acme Coffee San Francisco",
    "count": 20
  }
}
```

#### `google_locations`

Search for Google location metadata.

```json theme={null}
{
  "name": "google_locations",
  "arguments": {
    "query": "New York",
    "country": "US"
  }
}
```

***

### YouTube

#### `get_youtube_transcript`

Get the transcript for a YouTube video.

```json theme={null}
{
  "name": "get_youtube_transcript",
  "arguments": {
    "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "language": "en"
  }
}
```

#### `youtube_video`

Fetch metadata for a YouTube video.

```json theme={null}
{
  "name": "youtube_video",
  "arguments": {
    "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  }
}
```

#### `youtube_video_comments`

List comments for a YouTube video.

```json theme={null}
{
  "name": "youtube_video_comments",
  "arguments": {
    "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "limit": 50,
    "sortBy": "top"
  }
}
```

#### `youtube_channel`

Fetch YouTube channel metadata.

```json theme={null}
{
  "name": "youtube_channel",
  "arguments": {
    "channelUrl": "https://www.youtube.com/@mkbhd"
  }
}
```

#### `youtube_channel_videos`

List a channel's long-form videos.

```json theme={null}
{
  "name": "youtube_channel_videos",
  "arguments": {
    "channelUrl": "https://www.youtube.com/@mkbhd",
    "limit": 20
  }
}
```

#### `youtube_channel_shorts`

List a channel's Shorts.

```json theme={null}
{
  "name": "youtube_channel_shorts",
  "arguments": {
    "channelUrl": "https://www.youtube.com/@mkbhd",
    "limit": 20
  }
}
```

#### `youtube_search`

Search YouTube.

```json theme={null}
{
  "name": "youtube_search",
  "arguments": {
    "query": "machine learning tutorial",
    "type": "video",
    "limit": 10
  }
}
```

***

### TikTok

#### `get_tiktok_profile`

Fetch a TikTok profile.

```json theme={null}
{
  "name": "get_tiktok_profile",
  "arguments": {
    "username": "@charlidamelio"
  }
}
```

#### `get_tiktok_profile_videos`

List recent videos for a TikTok profile.

```json theme={null}
{
  "name": "get_tiktok_profile_videos",
  "arguments": {
    "username": "@charlidamelio",
    "limit": 20
  }
}
```

#### `get_tiktok_transcript`

Get the transcript for a TikTok video.

```json theme={null}
{
  "name": "get_tiktok_transcript",
  "arguments": {
    "videoUrl": "https://www.tiktok.com/@user/video/1234567890"
  }
}
```

#### `get_tiktok_video`

Fetch details for a TikTok video.

```json theme={null}
{
  "name": "get_tiktok_video",
  "arguments": {
    "videoUrl": "https://www.tiktok.com/@user/video/1234567890"
  }
}
```

#### `get_tiktok_video_comments`

Get comments for a TikTok video.

```json theme={null}
{
  "name": "get_tiktok_video_comments",
  "arguments": {
    "videoUrl": "https://www.tiktok.com/@user/video/1234567890",
    "limit": 50
  }
}
```

#### `get_tiktok_user_followers`

Get followers for a TikTok account.

```json theme={null}
{
  "name": "get_tiktok_user_followers",
  "arguments": {
    "username": "@charlidamelio",
    "limit": 100
  }
}
```

#### `get_tiktok_user_following`

Get accounts a TikTok user follows.

```json theme={null}
{
  "name": "get_tiktok_user_following",
  "arguments": {
    "username": "@charlidamelio",
    "limit": 100
  }
}
```

#### `search_tiktok_users`

Search for TikTok users.

```json theme={null}
{
  "name": "search_tiktok_users",
  "arguments": {
    "query": "fitness influencer",
    "limit": 10
  }
}
```

***

### LinkedIn

#### `linkedin_profile`

Retrieve a LinkedIn profile.

```json theme={null}
{
  "name": "linkedin_profile",
  "arguments": {
    "profileUrl": "https://www.linkedin.com/in/satyanadella"
  }
}
```

#### `linkedin_company`

Retrieve a LinkedIn company profile.

```json theme={null}
{
  "name": "linkedin_company",
  "arguments": {
    "companyUrl": "https://www.linkedin.com/company/microsoft"
  }
}
```

***

### Document Processing

#### `doc_to_text`

Convert a PDF or DOCX to plain text.

```json theme={null}
{
  "name": "doc_to_text",
  "arguments": {
    "fileUrl": "https://example.com/report.pdf"
  }
}
```

#### `convert_to_pdf`

Convert a document or web page to PDF.

```json theme={null}
{
  "name": "convert_to_pdf",
  "arguments": {
    "url": "https://example.com/article"
  }
}
```

#### `merge_pdfs`

Merge multiple PDFs into one.

```json theme={null}
{
  "name": "merge_pdfs",
  "arguments": {
    "fileUrls": [
      "https://example.com/page1.pdf",
      "https://example.com/page2.pdf"
    ]
  }
}
```

#### `read_pdf_metadata`

Read metadata from a PDF.

```json theme={null}
{
  "name": "read_pdf_metadata",
  "arguments": {
    "fileUrl": "https://example.com/document.pdf"
  }
}
```

#### `write_pdf_metadata`

Update metadata in a PDF.

```json theme={null}
{
  "name": "write_pdf_metadata",
  "arguments": {
    "fileUrl": "https://example.com/document.pdf",
    "title": "Annual Report 2025",
    "author": "Finance Team"
  }
}
```

#### `extract_document`

Extract structured data from a document.

```json theme={null}
{
  "name": "extract_document",
  "arguments": {
    "fileUrl": "https://example.com/contract.pdf",
    "prompt": "Extract the parties, effective date, and key terms",
    "schema": {
      "type": "object",
      "properties": {
        "parties": { "type": "array", "items": { "type": "string" } },
        "effectiveDate": { "type": "string" },
        "keyTerms": { "type": "array", "items": { "type": "string" } }
      }
    }
  }
}
```

#### `extract_pdf`

Extract structured data from a PDF using AI.

```json theme={null}
{
  "name": "extract_pdf",
  "arguments": {
    "fileUrl": "https://example.com/invoice.pdf",
    "prompt": "Extract invoice number, date, and total amount"
  }
}
```

#### `extract_image`

Extract data from an image using AI vision.

```json theme={null}
{
  "name": "extract_image",
  "arguments": {
    "imageUrl": "https://example.com/chart.png",
    "prompt": "Describe the data shown in this chart"
  }
}
```

#### `extract_audio`

Extract structured data from an audio file.

```json theme={null}
{
  "name": "extract_audio",
  "arguments": {
    "fileUrl": "https://example.com/meeting.mp3",
    "prompt": "Summarize the key decisions made in this meeting"
  }
}
```

#### `extract_video`

Extract structured data from a video file.

```json theme={null}
{
  "name": "extract_video",
  "arguments": {
    "fileUrl": "https://example.com/presentation.mp4",
    "prompt": "List the main topics covered in this video"
  }
}
```

#### `trim_video`

Trim a video to a specified duration.

```json theme={null}
{
  "name": "trim_video",
  "arguments": {
    "fileUrl": "https://example.com/video.mp4",
    "startTime": 10,
    "endTime": 60
  }
}
```

***

### AI & Generation

#### `generate_agent_completion`

Build and interact with AI agents to automate complex tasks.

```json theme={null}
{
  "name": "generate_agent_completion",
  "arguments": {
    "messages": [
      { "role": "user", "content": "Research the top 5 competitors of Notion" }
    ]
  }
}
```

#### `generate_ai_image`

Generate an image from a text prompt.

```json theme={null}
{
  "name": "generate_ai_image",
  "arguments": {
    "prompt": "A futuristic city skyline at sunset, photorealistic",
    "width": 1024,
    "height": 1024
  }
}
```

***

### Developer Tools

#### `run_js_code`

Execute JavaScript in a secure sandbox.

```json theme={null}
{
  "name": "run_js_code",
  "arguments": {
    "code": "const data = [1, 2, 3, 4, 5];\nconst sum = data.reduce((a, b) => a + b, 0);\nconsole.log('Sum:', sum);"
  }
}
```

#### `run_python_code`

Execute Python in a secure sandbox.

```json theme={null}
{
  "name": "run_python_code",
  "arguments": {
    "code": "import statistics\ndata = [1, 2, 3, 4, 5]\nprint('Mean:', statistics.mean(data))\nprint('Stdev:', statistics.stdev(data))"
  }
}
```

***

## Authentication

All tool calls require a DumplingAI API key. Pass it as a Bearer token in the `Authorization` header when configuring your MCP client.

Discovery operations (`tools/list`, `initialize`) work without authentication so clients can enumerate tools before connecting.

## Error Handling

When a tool call fails, the response includes `"isError": true` and the body contains the error detail from the DumplingAI API:

```json theme={null}
{
  "content": [{ "type": "text", "text": "{\"error\": \"Insufficient credits\"}" }],
  "isError": true
}
```

Common errors:

| Status | Meaning                    |
| ------ | -------------------------- |
| 401    | Invalid or missing API key |
| 402    | Insufficient credits       |
| 429    | Rate limit exceeded        |
| 5xx    | DumplingAI API error       |

## Credit Usage

Each tool call consumes credits. Check your balance and usage in the [DumplingAI dashboard](https://app.dumplingai.com). See the [credit costs reference](/api-reference/credit-costs) for per-tool pricing.

## Support

Need help? Contact us at [help@dumplingai.com](mailto:help@dumplingai.com)


# Unified API
Source: https://docs.dumplingai.com/unified-api-platform

Understand DumplingAI's Unified API, when to use it, and how it differs from Direct Endpoints.

# Unified API

The Unified API is DumplingAI's `/api/v2` surface.

It is the recommended default for new focused data integrations. Direct Endpoints under `/api/v1` remain supported for legacy request shapes and Make.com compatibility.

Use it when you want:

* `capabilities` like `search_news`, `extract_document`, `extract_audio`, or `scrape_page`
* exact `endpoints` like `firecrawl.scrape` or `dataforseo.dataforseo_labs_google_keyword_ideas`
* one API key and one control surface for multiple managed providers

## How it differs from Direct Endpoints

### Direct Endpoints (`/api/v1`)

Use `/api/v1` when you want the existing endpoint-oriented Dumpling product:

* direct endpoint access
* the Direct Endpoint Playground
* legacy endpoint docs and request shapes
* current Make.com compatibility

### Unified API (`/api/v2`)

Use `/api/v2` when you want the capability- and provider-oriented platform model:

* simple capabilities for common jobs
* provider-native endpoints when the exact upstream API matters
* shared logging, policy, and spend controls across those lanes

## Two main lanes

### Capabilities

Capabilities are the default lane.

Examples:

* `google_search`
* `search_news`
* `search_places`
* `get_google_reviews`
* `crawl_site`
* `screenshot`
* `extract_web`
* `extract_document`
* `extract_image`
* `extract_audio`
* `extract_video`
* `scrape_page`
* `get_youtube_transcript`

Use them when you want DumplingAI to standardize the job and keep the request simple.

### Providers and endpoints

Providers are vendor overview pages, and endpoints are the provider-native operations under them.

Examples:

* `firecrawl`
* `serper.search`
* `serper.news`
* `serper.places`
* `serper.maps`
* `serper.autocomplete`
* `serper.images`
* `serper.videos`
* `serper.shopping`
* `serper.scholar`
* `serper.patents`
* `perplexity.search`
* `firecrawl.scrape`
* `dataforseo.dataforseo_labs_google_keyword_ideas`

Use them when you want exact provider behavior and provider-specific output.

## Best next steps

* Browse the [Workbench](https://app.dumplingai.com/workbench)
* Try a live request in [Workbench](https://app.dumplingai.com/workbench)
* Read the [API Reference](/api-reference/v2/introduction)
* See [Migrating from Direct Endpoints](/documentation/v2/migrating-from-direct-endpoints)
* Use the [MCP Server](/mcp-server) if you want to connect from Claude Code, Codex, or Cursor