# One API for Agents: full documentation



> Every docs page and provider reference from https://oneapiforagents.com, as markdown. Generated at build time.



<!-- Source: https://oneapiforagents.com/docs -->

## One API for Agents docs

One API for Agents is a connection broker and data layer for AI agents. A **workspace** holds connected accounts (Google Search Console, Google Analytics 4 and Bing Webmaster Tools today; DataForSEO next). Your agents reach every one of them through one REST API and one OAuth-enabled remote MCP server.

It is a wrapper: each call is proxied to the provider when your agent makes it, then logged with its request, response, latency and cost. Nothing is synced in the background and no website is monitored.

### Start here

- [Quickstart](/docs/quickstart.md): sign in, connect an account, make your first call.
- [MCP setup](/docs/mcp.md): connect Claude, Claude Code, Codex, Cursor or any MCP client.
- [REST API](/docs/rest-api.md): authentication, `POST /v1/call` and the other endpoints.
- [Connect links](/docs/connect-links.md): let clients connect their own Google accounts.
- [Caching with max_age](/docs/caching.md): reuse a recent response instead of calling the provider again.
- [Errors](/docs/errors.md): every error code and what to do about it.

### Providers

- [Google Search Console](/providers/gsc.md): Clicks, impressions, queries, URL inspection and sitemaps.
- [Google Analytics 4](/providers/ga4.md): Traffic, landing pages and engagement from the Data API.
- [Bing Webmaster Tools](/providers/bing.md): Queries, pages, rank and traffic, and crawl health from Bing.
- [Google Sheets](/providers/gsheets.md): Read, append and update spreadsheet rows; create new sheets.
- [Google Docs](/providers/gdocs.md): Read Google Docs as markdown, create them, and append, insert or replace text.
- DataForSEO (coming soon): SERPs, keywords and backlinks, metered per call.

### Concepts

| Concept | What it is |
| --- | --- |
| Workspace | Your team's account. Holds connections, clients, members, API keys and call logs. |
| Connection | One connected account at a provider, such as a Search Console login. Credentials are encrypted and never returned. |
| Client | Optional. A customer of your agency. Connections can belong to a client, and members, keys and agents can be limited to some clients. |
| Connect link | A link you send to a client so they can connect their own accounts, with no password sharing and no sign-up. |
| Raw endpoint | A passthrough to one provider API call, such as `searchanalytics.query`. Input is validated before it is sent. |
| Smart tool | A curated call with compact output for agents, such as `gsc_top_queries`. |
| API key | A bearer token (`oa_…`) for scripts and servers. Read-only or read-write, and limited to the creator's clients. |
| MCP grant | What an agent gets when you approve it over OAuth: a workspace, read-only or read-write, and the clients it can see. |
| Call log | One record per call with the redacted request and response, status, latency and cost. |

### For agents

These docs are also available as plain markdown. Append `.md` to any docs or provider URL (for example [/docs/quickstart.md](/docs/quickstart.md)), or read [/llms.txt](/llms.txt) for an index and [/llms-full.txt](/llms-full.txt) for everything on one page.

<!-- Source: https://oneapiforagents.com/docs/quickstart -->

## Quickstart

Four steps, about five minutes: sign in, connect an account, give your agent access, make the first call.

### 1. Sign in

Open the dashboard at [https://app.oneapiforagents.com](https://app.oneapiforagents.com) and sign in with Google or with an email magic link. Create a workspace when asked. Clients are optional, so a solo developer can skip them entirely.

### 2. Connect an account

In **Accounts**, choose **Connect account** and pick a provider:

- **Search Console** or **GA4** with Google sign-in. You approve read-only access on Google's own consent screen.
- A **service account**, if you prefer. Add the service account's email to the property as a user; you can use ours or upload your own key.
- **Send a link to the owner** when the account belongs to someone else, such as a client. See [Connect links](/docs/connect-links.md).

Each connection shows as **Active** once it works.

### 3. Give your agent access

Pick one, or both.

**MCP (recommended for Claude, Cursor, Codex and other agents).** Add the server URL to your client and approve access in the browser:

```text title=MCP server URL
https://mcp.oneapiforagents.com/mcp
```

For Claude Code:

```sh
claude mcp add --transport http one-api https://mcp.oneapiforagents.com/mcp
```

Then run `/mcp` in Claude Code to sign in. Other clients are covered in [MCP setup](/docs/mcp.md).

**API key (for scripts, servers and agents that speak HTTP).** In **API keys**, choose **Create key**. Keys start with `oa_` and are shown once, so store yours in a secret manager or an environment variable:

```sh
export ONEAPI_KEY="oa_..."
```

Keys are read-only by default and inherit your client limits.

### 4. Make your first call

List the Search Console properties your connection can read:

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"gsc","endpoint":"sites.list"}'
```

```json title=Response
{
  "call_id": "call_...",
  "connection_id": "con_...",
  "cached": false,
  "cost_usd": 0,
  "latency_ms": 312,
  "data": {
    "siteEntry": [{ "siteUrl": "sc-domain:example.com", "permissionLevel": "siteOwner" }]
  }
}
```

Raw endpoints return the provider's response body, unchanged, under `data`. Now try a smart tool, which returns compact rows made for agents:

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"gsc","tool":"gsc_top_queries","input":{"siteUrl":"sc-domain:example.com"}}'
```

Both calls now appear in **Call logs** in the dashboard, with the redacted request and response, status, latency and cost.

### Next

- If you have more than one Search Console connection, pass `connection_id`. See [Choosing a connection](/docs/rest-api.md#choosing-a-connection).
- Browse every endpoint and tool: [Search Console](/providers/gsc.md), [GA4](/providers/ga4.md).
- Reuse recent responses with [max_age](/docs/caching.md).

<!-- Source: https://oneapiforagents.com/docs/mcp -->

## MCP setup

One API for Agents runs a remote MCP server. Add one URL to your agent and approve access in the browser; there is no API key to copy.

```text title=MCP server URL
https://mcp.oneapiforagents.com/mcp
```

- **Transport:** streamable HTTP.
- **Auth:** OAuth 2.1 with PKCE and dynamic client registration, per the MCP authorization spec. Clients discover everything from the server URL.
- **Consent:** when you approve an agent, you pick the workspace, **read-only** or **read-write** access, and which clients the agent can see. Read-only is the default.

### Claude (claude.ai and Claude Desktop)

Custom connectors work on Free, Pro, Max, Team and Enterprise plans.

1. Open **Customize → Connectors**.
2. Click **+**, then **Add custom connector**.
3. Paste the server URL and click **Add**.
4. Click **Connect**, sign in to One API for Agents and approve access.

On Team and Enterprise plans an owner first adds the connector under **Organization settings → Connectors**; members then connect it from **Customize → Connectors**. Connectors added on claude.ai are also available in Claude Desktop. Turn it on per conversation from the **+** menu under **Connectors**.

### Claude Code

```sh
claude mcp add --transport http one-api https://mcp.oneapiforagents.com/mcp
```

Then run `/mcp` inside Claude Code, pick **one-api** and sign in. Add `--scope user` to make the server available in every project, or `--scope project` to share it with your team through `.mcp.json`.

### Codex CLI

```sh
codex mcp add one-api --url https://mcp.oneapiforagents.com/mcp
codex mcp login one-api
```

Or add it to `~/.codex/config.toml` yourself, then run `codex mcp login one-api`:

```toml
[mcp_servers.one-api]
url = "https://mcp.oneapiforagents.com/mcp"
```

### Cursor

Add the server to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

```json
{
  "mcpServers": {
    "one-api": {
      "url": "https://mcp.oneapiforagents.com/mcp"
    }
  }
}
```

Cursor shows the server in its MCP settings with a sign-in prompt. Approve access in the browser window that opens.

### Any other MCP client

Point any client that supports remote servers over streamable HTTP at the server URL. It discovers the OAuth endpoints from the server (protected-resource metadata), registers itself and opens the browser for consent.

For a client that only launches local (stdio) servers, bridge with [mcp-remote](https://www.npmjs.com/package/mcp-remote):

```json
{
  "mcpServers": {
    "one-api": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.oneapiforagents.com/mcp"]
    }
  }
}
```

### Tools

| Tool | What it does |
| --- | --- |
| `whoami` | The workspace the agent is connected to, its access level (read or read-write) and the clients it can see. |
| `list_connections` | Connections the agent can see, with id, provider, label, client and status. |
| `list_endpoints` | Raw endpoints and smart tools for a provider, with input schemas. |
| `call` | Call any raw endpoint or smart tool. Takes the same fields as [`POST /v1/call`](/docs/rest-api.md#post-v1-call). |

Smart tools are also exposed directly by name:

- `gsc_top_queries` (Google Search Console): Top search queries by clicks for a property over the last N days.
- `gsc_quick_wins` (Google Search Console): Queries ranking just off page one (default positions 8–20) with meaningful impressions, sorted by impressions.
- `ga4_traffic_by_page` (Google Analytics 4): Top landing pages by sessions, with users and engagement rate, over the last N days.
- `ga4_list_properties` (Google Analytics 4): Every GA4 property this connection can read, with its account, as a flat list.
- `bing_top_queries` (Bing Webmaster Tools): Top Bing search queries by clicks for a site over the last N days, with impressions, CTR and average position. Bing updates this weekly.
- `bing_top_pages` (Bing Webmaster Tools): Top pages in Bing search by clicks for a site over the last N days, with impressions, CTR and average position.
- `bing_crawl_health` (Bing Webmaster Tools): Crawl health for a site in Bing: pages in index, crawl and HTTP error totals over the last N days, and the URLs with crawl issues (most linked first).
- `bing_list_sites` (Bing Webmaster Tools): Sites on the connected Bing Webmaster account and whether each is verified.
- `sheets_read` (Google Sheets): Read a tab or range as rows of objects keyed by the header row. Capped by `limit`; page with `offset`.
- `sheets_list_tabs` (Google Sheets): The spreadsheet's title, URL and tabs, with each tab's grid size (rows × columns, including empty cells).
- `sheets_append_rows` (Google Sheets): Append rows below a tab's existing data. Pass objects keyed by header name, or arrays in column order.
- `sheets_update_range` (Google Sheets): Overwrite cells starting at a range with rows of values.
- `sheets_create` (Google Sheets): Create a spreadsheet in the connected Google account's Drive, optionally with a frozen header row. Returns its ID and URL. Needs a Google sign-in connection (service accounts can't own files).
- `docs_read` (Google Docs): Read a Google Doc as markdown-style text (headings, lists, tables, links), with its title, revisionId, tabs, heading outline with indexes, and endIndex.
- `docs_create` (Google Docs): Create a Google Doc with a title and optional initial text (markdown headings, lists and paragraphs become Docs styles). Returns its ID and URL.
- `docs_append` (Google Docs): Append text or simple markdown to the end of a Google Doc (or of one tab).
- `docs_replace_text` (Google Docs): Replace every occurrence of some text in a Google Doc. Case-sensitive unless match_case is false.
- `docs_insert` (Google Docs): Insert text or simple markdown into a Google Doc, either below a heading (matched by its text) or at an index from docs_read. Pass exactly one of heading or index.

Every call an agent makes over MCP goes through the same pipeline as the REST API and shows up in **Call logs**.

### Try it

Once connected, ask your agent something like:

> Which queries for example.com rank between positions 8 and 20 with over 100 impressions in the last 28 days? Suggest a title tweak for the top five pages.

The agent will call `gsc_quick_wins`, then read the pages it needs.

### Revoking access

Remove the server in your client, or open **Connect agents** in the dashboard and click **Disconnect**. Access stops on the agent's next call, and its tokens are revoked.

<!-- Source: https://oneapiforagents.com/docs/rest-api -->

## REST API

One HTTP API for every connected account. Use it from scripts, servers, workflow tools or any agent that can make HTTP requests.

### Base URL and authentication

```text title=Base URL
https://api.oneapiforagents.com/v1
```

Every request carries an API key as a bearer token. Create keys in the dashboard under **API keys**; they start with `oa_` and are shown once.

```http
Authorization: Bearer oa_...
```

A key belongs to the member who created it and inherits that member's client limits. A **read-only** key (the default) cannot call endpoints or tools that change data. A missing or invalid key returns `401 unauthenticated`.

### Endpoints

| Method | Path | What it does |
| --- | --- | --- |
| `POST` | `/v1/call` | Call a raw endpoint or a smart tool on one of your connections. |
| `GET` | `/v1/providers` | List providers: id, name and supported auth methods. |
| `GET` | `/v1/providers/:id` | One provider's raw endpoints and smart tools, each with a JSON Schema for its input. |
| `GET` | `/v1/connections` | Connections this key can see. |
| `GET` | `/v1/logs` | Recent calls, newest first. |
| `GET` | `/v1/logs/:call_id` | One call with its redacted request and response. |

### POST /v1/call

Pass **exactly one** of `endpoint` or `tool`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `provider` | string | yes | Provider id, such as `gsc` or `ga4`. |
| `endpoint` | string | one of | Raw endpoint id, such as `searchanalytics.query`. |
| `tool` | string | one of | Smart tool name, such as `gsc_top_queries`. |
| `input` | object | depends | Input for the endpoint or tool. Validated against its JSON Schema before anything is sent. |
| `connection_id` | string | no | Which connection to use. Needed when more than one active connection exists for the provider. |
| `max_age` | integer | no | Seconds, 0 to 604800. Return a cached response if one is at most this old. See [Caching](/docs/caching.md). |

Raw endpoint input has up to three parts: `path` (URL placeholders), `query` (query string) and `body` (JSON body). Smart tools take a flat object.

```sh title=Raw endpoint
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gsc",
    "endpoint": "searchanalytics.query",
    "input": {
      "path": { "siteUrl": "sc-domain:example.com" },
      "body": { "startDate": "2026-08-01", "endDate": "2026-08-28", "dimensions": ["query"], "rowLimit": 10 }
    }
  }'
```

```sh title=Smart tool
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"gsc","tool":"gsc_top_queries","input":{"siteUrl":"sc-domain:example.com"}}'
```

#### Response

```json title=200 OK
{
  "call_id": "call_...",
  "connection_id": "con_...",
  "cached": false,
  "cost_usd": 0,
  "latency_ms": 312,
  "data": { "...": "provider response body, or the smart tool's compact output" }
}
```

Once a request is accepted, its response carries an `x-call-id` header, whether the call succeeded or failed. Use it to find the call in **Call logs** or at `GET /v1/logs/:call_id`.

#### Errors

Errors use the HTTP status and a stable code:

```json title=Error
{
  "call_id": "call_...",
  "error": {
    "code": "connection_ambiguous",
    "message": "Several gsc connections are available; pass connection_id",
    "details": { "connection_ids": ["con_...", "con_..."] }
  }
}
```

The full list is in [Errors](/docs/errors.md).

### Choosing a connection

If a provider has exactly one active connection you can see, calls use it. If there are several (for example one per client), the call fails with `connection_ambiguous` and lists the ids in `details.connection_ids`. Call `GET /v1/connections`, pick one and pass it as `connection_id`.

```json title=GET /v1/connections
{
  "connections": [
    {
      "id": "con_...",
      "provider": "gsc",
      "auth_type": "oauth",
      "label": "acme.com",
      "client_id": "cli_...",
      "external_account": "marketing@acme.com",
      "scopes": ["https://www.googleapis.com/auth/webmasters.readonly"],
      "status": "active",
      "last_used_at": "2026-09-26T14:02:11.000Z",
      "created_at": "2026-09-01T09:30:00.000Z"
    }
  ]
}
```

`status` is `active`, `expired` or `revoked`. Credentials are never returned.

### Discovering endpoints and tools

`GET /v1/providers/:id` returns everything an agent needs to build a valid call: each raw endpoint's id, description, method, upstream URL, whether it writes, and `input_schema`; and each smart tool's name, description and `input_schema`. The schemas are JSON Schema generated from the same validators the API uses.

```sh
curl https://api.oneapiforagents.com/v1/providers/gsc -H "Authorization: Bearer $ONEAPI_KEY"
```

### Call logs

`GET /v1/logs` returns `{ "calls": [...], "cursor": "..." }`, newest first. Query parameters:

| Parameter | Description |
| --- | --- |
| `limit` | 1 to 200. Default 50. |
| `cursor` | The `cursor` from the previous page. |
| `provider` | Only calls to this provider. |
| `outcome` | `ok` or `error`. |

Each call has its id, provider, target (`raw:<endpoint>` or `tool:<name>`), outcome, HTTP status, error code, latency, cost, whether it was cached, and a timestamp. `GET /v1/logs/:call_id` adds the request and response bodies, with tokens, keys and auth headers redacted.

### Provider reference

Generated from the provider registry. Each provider page lists inputs, types and example calls.

#### Google Search Console (`gsc`)

| Kind | Name | Description |
| --- | --- | --- |
| `endpoint` | [`sites.list`](/providers/gsc.md#sites-list) | List Search Console properties this connection can read. |
| `endpoint` | [`sites.get`](/providers/gsc.md#sites-get) | Get one property and the connection's permission level on it. |
| `endpoint` | [`searchanalytics.query`](/providers/gsc.md#searchanalytics-query) | Search Analytics: clicks, impressions, CTR and position grouped by dimensions. |
| `endpoint` | [`sitemaps.list`](/providers/gsc.md#sitemaps-list) | List sitemaps submitted for a property. |
| `endpoint` | [`sitemaps.get`](/providers/gsc.md#sitemaps-get) | Get one submitted sitemap. |
| `endpoint` | [`urlInspection.index.inspect`](/providers/gsc.md#urlinspection-index-inspect) | URL Inspection: index status, crawl and rich-result details for one URL. |
| `tool` | [`gsc_top_queries`](/providers/gsc.md#gsc-top-queries) | Top search queries by clicks for a property over the last N days. |
| `tool` | [`gsc_quick_wins`](/providers/gsc.md#gsc-quick-wins) | Queries ranking just off page one (default positions 8–20) with meaningful impressions, sorted by impressions. |

#### Google Analytics 4 (`ga4`)

| Kind | Name | Description |
| --- | --- | --- |
| `endpoint` | [`accountSummaries.list`](/providers/ga4.md#accountsummaries-list) | List GA4 accounts and properties this connection can read. |
| `endpoint` | [`properties.runReport`](/providers/ga4.md#properties-runreport) | Data API runReport: dimensions and metrics for a date range. |
| `endpoint` | [`properties.runRealtimeReport`](/providers/ga4.md#properties-runrealtimereport) | Data API realtime report (last 30 minutes). |
| `endpoint` | [`properties.getMetadata`](/providers/ga4.md#properties-getmetadata) | Dimensions and metrics available for a property, including custom ones. |
| `tool` | [`ga4_traffic_by_page`](/providers/ga4.md#ga4-traffic-by-page) | Top landing pages by sessions, with users and engagement rate, over the last N days. |
| `tool` | [`ga4_list_properties`](/providers/ga4.md#ga4-list-properties) | Every GA4 property this connection can read, with its account, as a flat list. |

#### Bing Webmaster Tools (`bing`)

| Kind | Name | Description |
| --- | --- | --- |
| `endpoint` | [`GetUserSites`](/providers/bing.md#getusersites) | List the sites on this Bing Webmaster account, with verification status. |
| `endpoint` | [`GetQueryStats`](/providers/bing.md#getquerystats) | Top search queries with clicks, impressions and average positions, by week. Updated weekly. |
| `endpoint` | [`GetPageStats`](/providers/bing.md#getpagestats) | Top pages with clicks, impressions and average positions (the page URL is in `Query`). Updated weekly. |
| `endpoint` | [`GetRankAndTrafficStats`](/providers/bing.md#getrankandtrafficstats) | Daily clicks and impressions for the whole site. Updated daily. |
| `endpoint` | [`GetQueryPageStats`](/providers/bing.md#getquerypagestats) | Pages that ranked for one query, with clicks, impressions and positions. |
| `endpoint` | [`GetPageQueryStats`](/providers/bing.md#getpagequerystats) | Queries that led to one page, with clicks, impressions and positions. |
| `endpoint` | [`GetQueryTrafficStats`](/providers/bing.md#getquerytrafficstats) | Daily clicks and impressions for one query. |
| `endpoint` | [`GetCrawlStats`](/providers/bing.md#getcrawlstats) | Daily crawl stats for the last 6 months: pages crawled, in index, HTTP code counts, robots.txt blocks. |
| `endpoint` | [`GetCrawlIssues`](/providers/bing.md#getcrawlissues) | URLs with crawl issues. `Issues` is a bit flag: 1 Code301, 2 Code302, 4 Code4xx, 8 Code5xx, 16 BlockedByRobotsTxt, 32 ContainsMalware, 64 ImportantUrlBlockedByRobotsTxt, 128 DnsErrors, 256 TimeOutErrors. |
| `endpoint` | [`GetFeeds`](/providers/bing.md#getfeeds) | Sitemaps and feeds submitted for the site. |
| `endpoint` | [`GetUrlSubmissionQuota`](/providers/bing.md#geturlsubmissionquota) | How many URLs can still be submitted today and this month. |
| `endpoint` | [`GetKeywordStats`](/providers/bing.md#getkeywordstats) | Bing search volume history for a keyword (not tied to your site). |
| `endpoint` | [`SubmitUrl`](/providers/bing.md#submiturl) | Submit one URL for indexing. Uses the site's daily quota. |
| `endpoint` | [`SubmitUrlBatch`](/providers/bing.md#submiturlbatch) | Submit up to 500 URLs for indexing. Uses the site's daily quota. |
| `tool` | [`bing_top_queries`](/providers/bing.md#bing-top-queries) | Top Bing search queries by clicks for a site over the last N days, with impressions, CTR and average position. Bing updates this weekly. |
| `tool` | [`bing_top_pages`](/providers/bing.md#bing-top-pages) | Top pages in Bing search by clicks for a site over the last N days, with impressions, CTR and average position. |
| `tool` | [`bing_crawl_health`](/providers/bing.md#bing-crawl-health) | Crawl health for a site in Bing: pages in index, crawl and HTTP error totals over the last N days, and the URLs with crawl issues (most linked first). |
| `tool` | [`bing_list_sites`](/providers/bing.md#bing-list-sites) | Sites on the connected Bing Webmaster account and whether each is verified. |

#### Google Sheets (`gsheets`)

| Kind | Name | Description |
| --- | --- | --- |
| `endpoint` | [`spreadsheets.get`](/providers/gsheets.md#spreadsheets-get) | Spreadsheet metadata: title, tabs and their grid sizes. Use `fields` (a field mask) to keep responses small; includeGridData returns cell data and is ignored when `fields` is set. |
| `endpoint` | [`values.get`](/providers/gsheets.md#values-get) | Read one range. Trailing empty rows and columns are omitted. |
| `endpoint` | [`values.batchGet`](/providers/gsheets.md#values-batchget) | Read several ranges in one request. |
| `endpoint` | [`values.update`](/providers/gsheets.md#values-update) | Overwrite one range with a ValueRange. valueInputOption is required. |
| `endpoint` | [`values.append`](/providers/gsheets.md#values-append) | Append rows after the table found in `range`. valueInputOption is required. |
| `endpoint` | [`values.batchUpdate`](/providers/gsheets.md#values-batchupdate) | Overwrite several ranges in one request. |
| `endpoint` | [`values.clear`](/providers/gsheets.md#values-clear) | Clear the values in a range. Formatting and validation are kept. |
| `endpoint` | [`spreadsheets.create`](/providers/gsheets.md#spreadsheets-create) | Create a spreadsheet from a Spreadsheet resource. Needs a Google sign-in connection: service accounts have no Drive storage to own files. |
| `endpoint` | [`spreadsheets.batchUpdate`](/providers/gsheets.md#spreadsheets-batchupdate) | Structural changes (add, rename or delete tabs, formatting, sorting, …) as a list of requests, applied atomically. |
| `tool` | [`sheets_read`](/providers/gsheets.md#sheets-read) | Read a tab or range as rows of objects keyed by the header row. Capped by `limit`; page with `offset`. |
| `tool` | [`sheets_list_tabs`](/providers/gsheets.md#sheets-list-tabs) | The spreadsheet's title, URL and tabs, with each tab's grid size (rows × columns, including empty cells). |
| `tool` | [`sheets_append_rows`](/providers/gsheets.md#sheets-append-rows) | Append rows below a tab's existing data. Pass objects keyed by header name, or arrays in column order. |
| `tool` | [`sheets_update_range`](/providers/gsheets.md#sheets-update-range) | Overwrite cells starting at a range with rows of values. |
| `tool` | [`sheets_create`](/providers/gsheets.md#sheets-create) | Create a spreadsheet in the connected Google account's Drive, optionally with a frozen header row. Returns its ID and URL. Needs a Google sign-in connection (service accounts can't own files). |

#### Google Docs (`gdocs`)

| Kind | Name | Description |
| --- | --- | --- |
| `endpoint` | [`documents.get`](/providers/gdocs.md#documents-get) | The full Document resource. Pass includeTabsContent=true to get every tab in `tabs` (otherwise `body` holds the first tab only). |
| `endpoint` | [`documents.create`](/providers/gdocs.md#documents-create) | Create a blank document. Only `title` is used; add content with documents.batchUpdate. |
| `endpoint` | [`documents.batchUpdate`](/providers/gdocs.md#documents-batchupdate) | Apply Docs requests atomically (insertText, deleteContentRange, replaceAllText, createParagraphBullets, …). Indexes are UTF-16 code units; order edits from the highest index down. |
| `tool` | [`docs_read`](/providers/gdocs.md#docs-read) | Read a Google Doc as markdown-style text (headings, lists, tables, links), with its title, revisionId, tabs, heading outline with indexes, and endIndex. |
| `tool` | [`docs_create`](/providers/gdocs.md#docs-create) | Create a Google Doc with a title and optional initial text (markdown headings, lists and paragraphs become Docs styles). Returns its ID and URL. |
| `tool` | [`docs_append`](/providers/gdocs.md#docs-append) | Append text or simple markdown to the end of a Google Doc (or of one tab). |
| `tool` | [`docs_replace_text`](/providers/gdocs.md#docs-replace-text) | Replace every occurrence of some text in a Google Doc. Case-sensitive unless match_case is false. |
| `tool` | [`docs_insert`](/providers/gdocs.md#docs-insert) | Insert text or simple markdown into a Google Doc, either below a heading (matched by its text) or at an index from docs_read. Pass exactly one of heading or index. |

<!-- Source: https://oneapiforagents.com/docs/connect-links -->

## Connect links

A connect link lets someone else, usually a client of your agency, connect their own accounts to your workspace. They never share a password, never create an account with us, and approve read-only access on Google's own consent screen.

### How it works

1. In the dashboard, open **Connect links** and create a link. Choose the client it's for (optional) and the providers to ask for. One link can ask for several providers, such as Search Console, GA4 and Bing together.
2. Send the link however you like: email, chat, your onboarding doc. Links look like `https://app.oneapiforagents.com/c/…`.
3. Your client opens it, sees your workspace name and what you're asking for, and clicks **Connect with Google** for each provider.
4. Each account appears in your workspace under that client, marked **Active**. Your agents can call it straight away.

### What your client sees

- Your workspace's name and the client name, so they know who is asking.
- Each provider with **Read-only** next to it.
- Google's consent screen, listing the read-only scope for that provider.
- A confirmation once everything is connected. They can close the page.

They can remove access at any time from their Google account's security settings. If they do, the next call fails with `credentials_expired`, the connection shows as **Token expired**, and you can send them a new link.

### Status

| Status | Meaning |
| --- | --- |
| Sent | Created, not opened yet. |
| Opened | Your client opened the link but hasn't finished. |
| Completed | Every requested provider is connected. |
| Expired | The link passed its expiry date. Create a new one. |
| Revoked | You turned the link off. |

Links expire after 7 days by default (up to 30), and you can turn a link off at any time.

### Scopes

| Provider | Google scope |
| --- | --- |
| Google Search Console | `https://www.googleapis.com/auth/webmasters.readonly` (read-only) |
| Google Analytics 4 | `https://www.googleapis.com/auth/analytics.readonly` (read-only) |
| Bing Webmaster Tools | `webmaster.read` (read-only) |
| Google Sheets | `https://www.googleapis.com/auth/spreadsheets` (read-only) |
| Google Docs | `https://www.googleapis.com/auth/documents` (read-only) |

We also ask for `openid` and `email` so the dashboard can show which Google account was connected.

### Limits for your team

Members, API keys and MCP grants can be limited to some clients. A connection that belongs to a client is only visible to people and agents allowed to see that client.

<!-- Source: https://oneapiforagents.com/docs/caching -->

## Caching with max_age

Agents often ask the same question twice in one session. `max_age` lets a call reuse a recent response instead of calling the provider again, which is faster and, for paid providers, cheaper.

### How it works

Add `max_age` in seconds to any call:

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"gsc","tool":"gsc_top_queries","input":{"siteUrl":"sc-domain:example.com"},"max_age":3600}'
```

- If a successful response for the **same connection, endpoint or tool, and input** is at most `max_age` seconds old, it is returned with `"cached": true`. The provider is not called and the call costs nothing.
- Otherwise the provider is called as usual, and the fresh response is stored for later calls that pass `max_age`.
- Without `max_age`, the call always goes to the provider and nothing is stored.

`max_age` accepts 0 to 604800 (7 days). `"max_age": 0` always fetches fresh data and stores it, which is useful to warm the cache before a batch of calls. Only successful responses are cached, and cached responses are kept for at most 7 days.

### Choosing a value

| Data | Suggested max_age |
| --- | --- |
| Search Console performance (final after about 3 days) | `86400` (1 day) |
| GA4 reports for past dates | `3600` to `86400` |
| GA4 realtime reports | leave it out |
| Property and site lists | `86400` |
| URL Inspection after you've changed a page | leave it out |

Matching uses the validated input, with defaults filled in: `{"days": 28}` and `{"days": 30}` are different entries, while leaving `days` out matches `{"days": 28}` because 28 is the default. Key order doesn't matter.

### In the logs

Cached calls are logged like any other, with `cached: true`, so you can see how often your agents reuse data.

<!-- Source: https://oneapiforagents.com/docs/errors -->

## Errors

Errors come back with an HTTP status and a JSON body with a stable `code`, a human `message` and, for some codes, `details`. Branch on `code`, not on `message`.

```json title=Error body
{
  "call_id": "call_...",
  "error": {
    "code": "invalid_input",
    "message": "Input failed validation",
    "details": [{ "path": ["siteUrl"], "message": "Invalid input: expected string, received undefined" }]
  }
}
```

Over MCP the same code and message are returned as a tool error.

### Codes

| Code | HTTP | What happened | What to do |
| --- | --- | --- | --- |
| `unauthenticated` | 401 | The API key is missing, malformed or revoked. | Send `Authorization: Bearer oa_…` with a current key. |
| `invalid_json` | 400 | The request body isn't JSON. | Send a JSON body with `Content-Type: application/json`. |
| `invalid_input` | 400 | The body or the endpoint's `input` failed validation. `details` lists each issue. | Fix the fields named in `details`. The input schema is at `GET /v1/providers/:id`. |
| `provider_not_found` | 404 | No provider with that id. | Use an id from `GET /v1/providers`. |
| `endpoint_not_found` | 404 | The provider has no raw endpoint with that id. | Use an id from `GET /v1/providers/:id`. |
| `tool_not_found` | 404 | The provider has no smart tool with that name. | Use a name from `GET /v1/providers/:id`. |
| `connection_not_found` | 404 | No active connection for this provider that you can see, or the `connection_id` doesn't exist or is outside your clients. | Connect an account, or check `GET /v1/connections`. |
| `connection_ambiguous` | 400 | Several active connections match. `details.connection_ids` lists them. | Pass `connection_id`. |
| `connection_inactive` | 409 | The connection you named is expired or revoked. | Reconnect it in the dashboard or send a new connect link. |
| `read_only` | 403 | A read-only key or grant tried an endpoint or tool that writes. | Use a read-write key, or approve the agent with read-write access. |
| `credentials_expired` | 401 | The account owner revoked access, or Google expired it. The connection is marked **Token expired**. | Reconnect the account. For a client, send a new connect link. |
| `credentials_rejected` | 502 | Google refused the stored credentials, for example a service account without access. | Check the account's access to the property, then reconnect. |
| `upstream_error` | provider's status | The provider answered with an error. `details` holds its response body. | Read `details`; often a wrong property id or a date range with no data. |
| `upstream_unreachable` | 502 | The provider couldn't be reached. | Retry with backoff. |
| `internal_error` | 500 | Something failed on our side. | Retry; if it persists, send us the `call_id`. |

Every failed call is logged. Look it up by `call_id` in **Call logs** or with `GET /v1/logs/:call_id`.

<!-- Source: https://oneapiforagents.com/providers/gsc -->

## Google Search Console

Google Search Console reports how a site performs in Google Search: which queries show it, which pages get clicks, and whether Google can crawl and index each URL. One API for Agents calls the Search Console API on your behalf with read-only access.

- Provider id: `gsc`
- Auth: Sign in with Google (OAuth), Service account
- Google scopes: `https://www.googleapis.com/auth/webmasters.readonly`
- Raw endpoints: 6. Smart tools: 2.
- Machine-readable schemas: `GET https://api.oneapiforagents.com/v1/providers/gsc`

### Smart tools

Curated calls with compact output for agents. Over MCP each one is a tool with the same name.

#### gsc_top_queries

Top search queries by clicks for a property over the last N days.

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `siteUrl` | string | yes | Property, e.g. "sc-domain:example.com" or "https://example.com/" |
| `days` | integer | no | How many days back from the latest available data Default `28`. (1–480) |
| `limit` | integer | no | Maximum rows to return Default `25`. (1–1000) |
| `page` | string (uri) | no | Only queries that led to this page |

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gsc",
    "tool": "gsc_top_queries",
    "input": {
      "siteUrl": "sc-domain:example.com",
      "days": 28,
      "limit": 10
    }
  }'
```

#### gsc_quick_wins

Queries ranking just off page one (default positions 8–20) with meaningful impressions, sorted by impressions.

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `siteUrl` | string | yes | Property, e.g. "sc-domain:example.com" or "https://example.com/" |
| `days` | integer | no | How many days back from the latest available data Default `28`. (1–480) |
| `minImpressions` | integer | no | Default `100`. (≥ 0) |
| `minPosition` | number | no | Default `8`. (≥ 1) |
| `maxPosition` | number | no | Default `20`. (≥ 1) |
| `limit` | integer | no | Maximum rows to return Default `50`. (1–500) |

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gsc",
    "tool": "gsc_quick_wins",
    "input": {
      "siteUrl": "sc-domain:example.com",
      "days": 28
    }
  }'
```

### Raw endpoints

Passthrough to the provider API. `path` fills URL placeholders, `query` the query string and `body` the JSON body. The response is the provider's own body.

#### sites.list

List Search Console properties this connection can read.

`GET https://www.googleapis.com/webmasters/v3/sites`

No input.

```json
{
  "provider": "gsc",
  "endpoint": "sites.list"
}
```

#### sites.get

Get one property and the connection's permission level on it.

`GET https://www.googleapis.com/webmasters/v3/sites/{siteUrl}`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.siteUrl` | string | yes | Search Console property, e.g. "sc-domain:example.com" or "https://example.com/" |

```json
{
  "provider": "gsc",
  "endpoint": "sites.get",
  "input": {
    "path": {
      "siteUrl": "sc-domain:example.com"
    }
  }
}
```

#### searchanalytics.query

Search Analytics: clicks, impressions, CTR and position grouped by dimensions.

`POST https://www.googleapis.com/webmasters/v3/sites/{siteUrl}/searchAnalytics/query`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.siteUrl` | string | yes | Search Console property, e.g. "sc-domain:example.com" or "https://example.com/" |
| `body.startDate` | string (date) | yes | First day, YYYY-MM-DD |
| `body.endDate` | string (date) | yes | Last day, YYYY-MM-DD |
| `body.dimensions` | array<string> | no | Group rows by these dimensions One of: `date`, `query`, `page`, `country`, `device`, `searchAppearance`, `hour`. |
| `body.type` | string | no | One of: `web`, `image`, `video`, `news`, `discover`, `googleNews`. |
| `body.dimensionFilterGroups` | array<object> | no |  |
| `body.aggregationType` | string | no | One of: `auto`, `byPage`, `byProperty`, `byNewsShowcasePanel`. |
| `body.rowLimit` | integer | no | Maximum rows to return (1–25000) |
| `body.startRow` | integer | no | Zero-based row offset for paging (≥ 0) |
| `body.dataState` | string | no | One of: `final`, `all`, `hourly_all`. |

```json
{
  "provider": "gsc",
  "endpoint": "searchanalytics.query",
  "input": {
    "path": {
      "siteUrl": "sc-domain:example.com"
    },
    "body": {
      "startDate": "2026-08-01",
      "endDate": "2026-08-28",
      "dimensions": [
        "query"
      ],
      "rowLimit": 10
    }
  }
}
```

#### sitemaps.list

List sitemaps submitted for a property.

`GET https://www.googleapis.com/webmasters/v3/sites/{siteUrl}/sitemaps`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.siteUrl` | string | yes | Search Console property, e.g. "sc-domain:example.com" or "https://example.com/" |
| `query.sitemapIndex` | string | no | Only sitemaps listed in this sitemap index |

```json
{
  "provider": "gsc",
  "endpoint": "sitemaps.list",
  "input": {
    "path": {
      "siteUrl": "sc-domain:example.com"
    }
  }
}
```

#### sitemaps.get

Get one submitted sitemap.

`GET https://www.googleapis.com/webmasters/v3/sites/{siteUrl}/sitemaps/{feedpath}`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.siteUrl` | string | yes | Search Console property, e.g. "sc-domain:example.com" or "https://example.com/" |
| `path.feedpath` | string | yes | Full sitemap URL |

```json
{
  "provider": "gsc",
  "endpoint": "sitemaps.get",
  "input": {
    "path": {
      "siteUrl": "sc-domain:example.com",
      "feedpath": "https://example.com/sitemap.xml"
    }
  }
}
```

#### urlInspection.index.inspect

URL Inspection: index status, crawl and rich-result details for one URL.

`POST https://searchconsole.googleapis.com/v1/urlInspection/index:inspect`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `body.inspectionUrl` | string (uri) | yes | Fully qualified URL to inspect, inside siteUrl |
| `body.siteUrl` | string | yes | Search Console property, e.g. "sc-domain:example.com" or "https://example.com/" |
| `body.languageCode` | string | no | Language for issue messages, e.g. "en-US" |

```json
{
  "provider": "gsc",
  "endpoint": "urlInspection.index.inspect",
  "input": {
    "body": {
      "inspectionUrl": "https://example.com/pricing",
      "siteUrl": "sc-domain:example.com"
    }
  }
}
```

<!-- Source: https://oneapiforagents.com/providers/ga4 -->

## Google Analytics 4

Google Analytics 4 measures what visitors do on a site. One API for Agents calls the GA4 Data API for reports and the Admin API to list the properties a connection can read, with read-only access.

- Provider id: `ga4`
- Auth: Sign in with Google (OAuth), Service account
- Google scopes: `https://www.googleapis.com/auth/analytics.readonly`
- Raw endpoints: 4. Smart tools: 2.
- Machine-readable schemas: `GET https://api.oneapiforagents.com/v1/providers/ga4`

### Smart tools

Curated calls with compact output for agents. Over MCP each one is a tool with the same name.

#### ga4_traffic_by_page

Top landing pages by sessions, with users and engagement rate, over the last N days.

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `propertyId` | string | yes | GA4 property id, e.g. "318204771" or "properties/318204771" |
| `days` | integer | no | How many days back from the latest available data Default `28`. (1–365) |
| `limit` | integer | no | Maximum rows to return Default `25`. (1–1000) |
| `organicOnly` | boolean | no | Only sessions from the Organic Search channel Default `false`. |

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "ga4",
    "tool": "ga4_traffic_by_page",
    "input": {
      "propertyId": "318204771",
      "days": 28,
      "organicOnly": true
    }
  }'
```

#### ga4_list_properties

Every GA4 property this connection can read, with its account, as a flat list.

No input.

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "ga4",
    "tool": "ga4_list_properties",
    "input": {}
  }'
```

### Raw endpoints

Passthrough to the provider API. `path` fills URL placeholders, `query` the query string and `body` the JSON body. The response is the provider's own body.

#### accountSummaries.list

List GA4 accounts and properties this connection can read.

`GET https://analyticsadmin.googleapis.com/v1beta/accountSummaries`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `query.pageSize` | integer | no | Maximum results per page (1–200) |
| `query.pageToken` | string | no | Token from a previous page |

```json
{
  "provider": "ga4",
  "endpoint": "accountSummaries.list"
}
```

#### properties.runReport

Data API runReport: dimensions and metrics for a date range.

`POST https://analyticsdata.googleapis.com/v1beta/properties/{propertyId}:runReport`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.propertyId` | string | yes | GA4 property id, e.g. "318204771" or "properties/318204771" |
| `body` | object (free-form) | yes | Request body, passed through to the provider API as-is |

```json
{
  "provider": "ga4",
  "endpoint": "properties.runReport",
  "input": {
    "path": {
      "propertyId": "318204771"
    },
    "body": {
      "dateRanges": [
        {
          "startDate": "28daysAgo",
          "endDate": "yesterday"
        }
      ],
      "dimensions": [
        {
          "name": "sessionDefaultChannelGroup"
        }
      ],
      "metrics": [
        {
          "name": "sessions"
        },
        {
          "name": "activeUsers"
        }
      ]
    }
  }
}
```

#### properties.runRealtimeReport

Data API realtime report (last 30 minutes).

`POST https://analyticsdata.googleapis.com/v1beta/properties/{propertyId}:runRealtimeReport`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.propertyId` | string | yes | GA4 property id, e.g. "318204771" or "properties/318204771" |
| `body` | object (free-form) | yes | Request body, passed through to the provider API as-is |

```json
{
  "provider": "ga4",
  "endpoint": "properties.runRealtimeReport",
  "input": {
    "path": {
      "propertyId": "318204771"
    },
    "body": {
      "dimensions": [
        {
          "name": "country"
        }
      ],
      "metrics": [
        {
          "name": "activeUsers"
        }
      ]
    }
  }
}
```

#### properties.getMetadata

Dimensions and metrics available for a property, including custom ones.

`GET https://analyticsdata.googleapis.com/v1beta/properties/{propertyId}/metadata`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.propertyId` | string | yes | GA4 property id, e.g. "318204771" or "properties/318204771" |

```json
{
  "provider": "ga4",
  "endpoint": "properties.getMetadata",
  "input": {
    "path": {
      "propertyId": "318204771"
    }
  }
}
```

<!-- Source: https://oneapiforagents.com/providers/bing -->

## Bing Webmaster Tools

Bing Webmaster Tools reports how a site performs in Bing search and how Bingbot crawls it. Connect with a Bing API key or by signing in with Microsoft (read-only); One API for Agents calls the Bing Webmaster API on your behalf.

- Provider id: `bing`
- Auth: API key, Sign in with Microsoft (OAuth)
- Google scopes: `webmaster.read`
- Raw endpoints: 14. Smart tools: 4.
- Machine-readable schemas: `GET https://api.oneapiforagents.com/v1/providers/bing`

### Smart tools

Curated calls with compact output for agents. Over MCP each one is a tool with the same name.

#### bing_top_queries

Top Bing search queries by clicks for a site over the last N days, with impressions, CTR and average position. Bing updates this weekly.

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `siteUrl` | string | yes | Site as added in Bing, e.g. "https://example.com/" |
| `days` | integer | no | How many days back from the latest available data Default `28`. (7–180) |
| `limit` | integer | no | Maximum rows to return Default `25`. (1–1000) |

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "bing",
    "tool": "bing_top_queries",
    "input": {
      "siteUrl": "https://example.com/",
      "days": 28,
      "limit": 10
    }
  }'
```

#### bing_top_pages

Top pages in Bing search by clicks for a site over the last N days, with impressions, CTR and average position.

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `siteUrl` | string | yes | Site as added in Bing, e.g. "https://example.com/" |
| `days` | integer | no | How many days back from the latest available data Default `28`. (7–180) |
| `limit` | integer | no | Maximum rows to return Default `25`. (1–1000) |

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "bing",
    "tool": "bing_top_pages",
    "input": {
      "siteUrl": "https://example.com/",
      "days": 28,
      "limit": 10
    }
  }'
```

#### bing_crawl_health

Crawl health for a site in Bing: pages in index, crawl and HTTP error totals over the last N days, and the URLs with crawl issues (most linked first).

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `siteUrl` | string | yes | Site as added in Bing, e.g. "https://example.com/" |
| `days` | integer | no | How many days back from the latest available data Default `30`. (1–180) |
| `issueLimit` | integer | no | Default `25`. (0–500) |

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "bing",
    "tool": "bing_crawl_health",
    "input": {
      "siteUrl": "sc-domain:example.com"
    }
  }'
```

#### bing_list_sites

Sites on the connected Bing Webmaster account and whether each is verified.

No input.

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "bing",
    "tool": "bing_list_sites",
    "input": {}
  }'
```

### Raw endpoints

Passthrough to the provider API. `path` fills URL placeholders, `query` the query string and `body` the JSON body. The response is the provider's own body.

#### GetUserSites

List the sites on this Bing Webmaster account, with verification status.

`GET https://ssl.bing.com/webmaster/api.svc/json/GetUserSites`

No input.

```json
{
  "provider": "bing",
  "endpoint": "GetUserSites"
}
```

#### GetQueryStats

Top search queries with clicks, impressions and average positions, by week. Updated weekly.

`GET https://ssl.bing.com/webmaster/api.svc/json/GetQueryStats`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `query.siteUrl` | string | yes | Site as added in Bing, e.g. "https://example.com/" |

```json
{
  "provider": "bing",
  "endpoint": "GetQueryStats",
  "input": {
    "query": {
      "siteUrl": "sc-domain:example.com"
    }
  }
}
```

#### GetPageStats

Top pages with clicks, impressions and average positions (the page URL is in `Query`). Updated weekly.

`GET https://ssl.bing.com/webmaster/api.svc/json/GetPageStats`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `query.siteUrl` | string | yes | Site as added in Bing, e.g. "https://example.com/" |

```json
{
  "provider": "bing",
  "endpoint": "GetPageStats",
  "input": {
    "query": {
      "siteUrl": "sc-domain:example.com"
    }
  }
}
```

#### GetRankAndTrafficStats

Daily clicks and impressions for the whole site. Updated daily.

`GET https://ssl.bing.com/webmaster/api.svc/json/GetRankAndTrafficStats`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `query.siteUrl` | string | yes | Site as added in Bing, e.g. "https://example.com/" |

```json
{
  "provider": "bing",
  "endpoint": "GetRankAndTrafficStats",
  "input": {
    "query": {
      "siteUrl": "sc-domain:example.com"
    }
  }
}
```

#### GetQueryPageStats

Pages that ranked for one query, with clicks, impressions and positions.

`GET https://ssl.bing.com/webmaster/api.svc/json/GetQueryPageStats`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `query.siteUrl` | string | yes | Site as added in Bing, e.g. "https://example.com/" |
| `query.query` | string | yes |  |

```json
{
  "provider": "bing",
  "endpoint": "GetQueryPageStats",
  "input": {
    "query": {
      "siteUrl": "sc-domain:example.com",
      "query": "example"
    }
  }
}
```

#### GetPageQueryStats

Queries that led to one page, with clicks, impressions and positions.

`GET https://ssl.bing.com/webmaster/api.svc/json/GetPageQueryStats`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `query.siteUrl` | string | yes | Site as added in Bing, e.g. "https://example.com/" |
| `query.page` | string | yes |  |

```json
{
  "provider": "bing",
  "endpoint": "GetPageQueryStats",
  "input": {
    "query": {
      "siteUrl": "sc-domain:example.com",
      "page": "https://example.com/pricing"
    }
  }
}
```

#### GetQueryTrafficStats

Daily clicks and impressions for one query.

`GET https://ssl.bing.com/webmaster/api.svc/json/GetQueryTrafficStats`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `query.siteUrl` | string | yes | Site as added in Bing, e.g. "https://example.com/" |
| `query.query` | string | yes |  |

```json
{
  "provider": "bing",
  "endpoint": "GetQueryTrafficStats",
  "input": {
    "query": {
      "siteUrl": "sc-domain:example.com",
      "query": "example"
    }
  }
}
```

#### GetCrawlStats

Daily crawl stats for the last 6 months: pages crawled, in index, HTTP code counts, robots.txt blocks.

`GET https://ssl.bing.com/webmaster/api.svc/json/GetCrawlStats`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `query.siteUrl` | string | yes | Site as added in Bing, e.g. "https://example.com/" |

```json
{
  "provider": "bing",
  "endpoint": "GetCrawlStats",
  "input": {
    "query": {
      "siteUrl": "sc-domain:example.com"
    }
  }
}
```

#### GetCrawlIssues

URLs with crawl issues. `Issues` is a bit flag: 1 Code301, 2 Code302, 4 Code4xx, 8 Code5xx, 16 BlockedByRobotsTxt, 32 ContainsMalware, 64 ImportantUrlBlockedByRobotsTxt, 128 DnsErrors, 256 TimeOutErrors.

`GET https://ssl.bing.com/webmaster/api.svc/json/GetCrawlIssues`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `query.siteUrl` | string | yes | Site as added in Bing, e.g. "https://example.com/" |

```json
{
  "provider": "bing",
  "endpoint": "GetCrawlIssues",
  "input": {
    "query": {
      "siteUrl": "sc-domain:example.com"
    }
  }
}
```

#### GetFeeds

Sitemaps and feeds submitted for the site.

`GET https://ssl.bing.com/webmaster/api.svc/json/GetFeeds`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `query.siteUrl` | string | yes | Site as added in Bing, e.g. "https://example.com/" |

```json
{
  "provider": "bing",
  "endpoint": "GetFeeds",
  "input": {
    "query": {
      "siteUrl": "sc-domain:example.com"
    }
  }
}
```

#### GetUrlSubmissionQuota

How many URLs can still be submitted today and this month.

`GET https://ssl.bing.com/webmaster/api.svc/json/GetUrlSubmissionQuota`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `query.siteUrl` | string | yes | Site as added in Bing, e.g. "https://example.com/" |

```json
{
  "provider": "bing",
  "endpoint": "GetUrlSubmissionQuota",
  "input": {
    "query": {
      "siteUrl": "sc-domain:example.com"
    }
  }
}
```

#### GetKeywordStats

Bing search volume history for a keyword (not tied to your site).

`GET https://ssl.bing.com/webmaster/api.svc/json/GetKeywordStats`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `query.q` | string | yes |  |
| `query.country` | string | no | Country code, e.g. "us" |
| `query.language` | string | no | Language, e.g. "en-US" |

```json
{
  "provider": "bing",
  "endpoint": "GetKeywordStats",
  "input": {
    "query": {
      "q": "example"
    }
  }
}
```

#### SubmitUrl

Submit one URL for indexing. Uses the site's daily quota.

`POST https://ssl.bing.com/webmaster/api.svc/json/SubmitUrl` (writes; needs read-write access)

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `body.siteUrl` | string | yes | Site as added in Bing, e.g. "https://example.com/" |
| `body.url` | string (uri) | yes |  |

```json
{
  "provider": "bing",
  "endpoint": "SubmitUrl",
  "input": {
    "body": {
      "siteUrl": "sc-domain:example.com",
      "url": "https://example.com/"
    }
  }
}
```

#### SubmitUrlBatch

Submit up to 500 URLs for indexing. Uses the site's daily quota.

`POST https://ssl.bing.com/webmaster/api.svc/json/SubmitUrlBatch` (writes; needs read-write access)

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `body.siteUrl` | string | yes | Site as added in Bing, e.g. "https://example.com/" |
| `body.urlList` | array<string (uri)> | yes |  |

```json
{
  "provider": "bing",
  "endpoint": "SubmitUrlBatch",
  "input": {
    "body": {
      "siteUrl": "sc-domain:example.com",
      "urlList": [
        "https://example.com/"
      ]
    }
  }
}
```

<!-- Source: https://oneapiforagents.com/providers/gsheets -->

## Google Sheets

Google Sheets holds the working data behind many reports. One API for Agents calls the Sheets API with read and write access to spreadsheets, so agents can read tabs as rows, append results and create new sheets. Agents open a spreadsheet by its ID or URL; there is no access to the rest of Google Drive.

- Provider id: `gsheets`
- Auth: Sign in with Google (OAuth), Service account
- Google scopes: `https://www.googleapis.com/auth/spreadsheets`
- Raw endpoints: 9. Smart tools: 5.
- Machine-readable schemas: `GET https://api.oneapiforagents.com/v1/providers/gsheets`

### Smart tools

Curated calls with compact output for agents. Over MCP each one is a tool with the same name.

#### sheets_read

Read a tab or range as rows of objects keyed by the header row. Capped by `limit`; page with `offset`.

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `spreadsheet` | string | yes | Spreadsheet ID, or its full docs.google.com/spreadsheets/d/<id>/... URL |
| `sheet` | string | no | Tab name. Defaults to the tab in the URL (gid), else the first tab. |
| `range` | string | no | A1 range to read, e.g. "A1:F" or "Leads!A1:F200". Its first row is the header. |
| `header` | boolean | no | Use the first row as keys. Off: keys are column letters. Default `true`. |
| `offset` | integer | no | Data rows to skip, for paging Default `0`. (≥ 0) |
| `limit` | integer | no | Maximum rows to return Default `100`. (1–1000) |
| `formatted` | boolean | no | Return values as displayed ("$1,200.00"). Off: numbers as numbers, dates as text. Default `false`. |

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gsheets",
    "tool": "sheets_read",
    "input": {
      "spreadsheet": "https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit"
    }
  }'
```

#### sheets_list_tabs

The spreadsheet's title, URL and tabs, with each tab's grid size (rows × columns, including empty cells).

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `spreadsheet` | string | yes | Spreadsheet ID, or its full docs.google.com/spreadsheets/d/<id>/... URL |

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gsheets",
    "tool": "sheets_list_tabs",
    "input": {
      "spreadsheet": "https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit"
    }
  }'
```

#### sheets_append_rows

Append rows below a tab's existing data. Pass objects keyed by header name, or arrays in column order.

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `spreadsheet` | string | yes | Spreadsheet ID, or its full docs.google.com/spreadsheets/d/<id>/... URL |
| `sheet` | string | no | Tab name. Defaults to the tab in the URL (gid), else the first tab. |
| `rows` | array<object (free-form) \| array<string \| number \| boolean \| null>> | yes | Objects are matched to the header row by name (an empty tab gets a header from their keys). Arrays are written as-is. |
| `valueInput` | string | no | RAW stores values as given. USER_ENTERED parses them as if typed into Sheets (dates, formulas, 1,000). One of: `RAW`, `USER_ENTERED`. Default `"RAW"`. |

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gsheets",
    "tool": "sheets_append_rows",
    "input": {
      "spreadsheet": "https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit",
      "rows": [
        {}
      ]
    }
  }'
```

#### sheets_update_range

Overwrite cells starting at a range with rows of values.

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `spreadsheet` | string | yes | Spreadsheet ID, or its full docs.google.com/spreadsheets/d/<id>/... URL |
| `range` | string | yes | Top-left cell or full A1 range to overwrite, e.g. "B2" or "Leads!B2:D10" |
| `sheet` | string | no | Tab name. Defaults to the tab in the URL (gid), else the first tab. |
| `values` | array<array<string \| number \| boolean \| null>> | yes | Rows of cells; null leaves a cell unchanged |
| `valueInput` | string | no | RAW stores values as given. USER_ENTERED parses them as if typed into Sheets (dates, formulas, 1,000). One of: `RAW`, `USER_ENTERED`. Default `"RAW"`. |

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gsheets",
    "tool": "sheets_update_range",
    "input": {
      "spreadsheet": "https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit",
      "range": "example",
      "values": [
        [
          null
        ]
      ]
    }
  }'
```

#### sheets_create

Create a spreadsheet in the connected Google account's Drive, optionally with a frozen header row. Returns its ID and URL. Needs a Google sign-in connection (service accounts can't own files).

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `title` | string | yes |  |
| `sheet` | string | no | Name of the first tab Default `"Sheet1"`. |
| `headers` | array<string> | no | Header row to write (and freeze) on the first tab |

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gsheets",
    "tool": "sheets_create",
    "input": {
      "title": "example"
    }
  }'
```

### Raw endpoints

Passthrough to the provider API. `path` fills URL placeholders, `query` the query string and `body` the JSON body. The response is the provider's own body.

#### spreadsheets.get

Spreadsheet metadata: title, tabs and their grid sizes. Use `fields` (a field mask) to keep responses small; includeGridData returns cell data and is ignored when `fields` is set.

`GET https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.spreadsheetId` | string | yes |  |
| `query.ranges` | array<string> | no |  |
| `query.includeGridData` | boolean | no |  |
| `query.excludeTablesInBandedRanges` | boolean | no |  |
| `query.fields` | string | no |  |

```json
{
  "provider": "gsheets",
  "endpoint": "spreadsheets.get",
  "input": {
    "path": {
      "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
    }
  }
}
```

#### values.get

Read one range. Trailing empty rows and columns are omitted.

`GET https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}/values/{range}`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.spreadsheetId` | string | yes |  |
| `path.range` | string | yes | A1 notation, e.g. "Sheet1!A1:D50" or "'Q3 data'!A:F" |
| `query.majorDimension` | string | no | One of: `ROWS`, `COLUMNS`. |
| `query.valueRenderOption` | string | no | One of: `FORMATTED_VALUE`, `UNFORMATTED_VALUE`, `FORMULA`. |
| `query.dateTimeRenderOption` | string | no | One of: `SERIAL_NUMBER`, `FORMATTED_STRING`. |

```json
{
  "provider": "gsheets",
  "endpoint": "values.get",
  "input": {
    "path": {
      "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
      "range": "example"
    }
  }
}
```

#### values.batchGet

Read several ranges in one request.

`GET https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}/values:batchGet`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.spreadsheetId` | string | yes |  |
| `query.majorDimension` | string | no | One of: `ROWS`, `COLUMNS`. |
| `query.valueRenderOption` | string | no | One of: `FORMATTED_VALUE`, `UNFORMATTED_VALUE`, `FORMULA`. |
| `query.dateTimeRenderOption` | string | no | One of: `SERIAL_NUMBER`, `FORMATTED_STRING`. |
| `query.ranges` | array<string> | yes |  |

```json
{
  "provider": "gsheets",
  "endpoint": "values.batchGet",
  "input": {
    "path": {
      "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
    },
    "query": {
      "ranges": [
        "example"
      ]
    }
  }
}
```

#### values.update

Overwrite one range with a ValueRange. valueInputOption is required.

`PUT https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}/values/{range}` (writes; needs read-write access)

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.spreadsheetId` | string | yes |  |
| `path.range` | string | yes | A1 notation, e.g. "Sheet1!A1:D50" or "'Q3 data'!A:F" |
| `query.valueInputOption` | string | yes | One of: `RAW`, `USER_ENTERED`. |
| `query.includeValuesInResponse` | boolean | no |  |
| `query.responseValueRenderOption` | string | no | One of: `FORMATTED_VALUE`, `UNFORMATTED_VALUE`, `FORMULA`. |
| `query.responseDateTimeRenderOption` | string | no | One of: `SERIAL_NUMBER`, `FORMATTED_STRING`. |
| `body.range` | string | no |  |
| `body.majorDimension` | string | no | One of: `ROWS`, `COLUMNS`. |
| `body.values` | array<array<string \| number \| boolean \| null>> | yes |  |

```json
{
  "provider": "gsheets",
  "endpoint": "values.update",
  "input": {
    "path": {
      "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
      "range": "example"
    },
    "query": {
      "valueInputOption": "RAW"
    },
    "body": {
      "values": [
        [
          null
        ]
      ]
    }
  }
}
```

#### values.append

Append rows after the table found in `range`. valueInputOption is required.

`POST https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}/values/{range}:append` (writes; needs read-write access)

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.spreadsheetId` | string | yes |  |
| `path.range` | string | yes | A1 notation, e.g. "Sheet1!A1:D50" or "'Q3 data'!A:F" |
| `query.valueInputOption` | string | yes | One of: `RAW`, `USER_ENTERED`. |
| `query.includeValuesInResponse` | boolean | no |  |
| `query.responseValueRenderOption` | string | no | One of: `FORMATTED_VALUE`, `UNFORMATTED_VALUE`, `FORMULA`. |
| `query.responseDateTimeRenderOption` | string | no | One of: `SERIAL_NUMBER`, `FORMATTED_STRING`. |
| `query.insertDataOption` | string | no | One of: `OVERWRITE`, `INSERT_ROWS`. |
| `body.range` | string | no |  |
| `body.majorDimension` | string | no | One of: `ROWS`, `COLUMNS`. |
| `body.values` | array<array<string \| number \| boolean \| null>> | yes |  |

```json
{
  "provider": "gsheets",
  "endpoint": "values.append",
  "input": {
    "path": {
      "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
      "range": "example"
    },
    "query": {
      "valueInputOption": "RAW"
    },
    "body": {
      "values": [
        [
          null
        ]
      ]
    }
  }
}
```

#### values.batchUpdate

Overwrite several ranges in one request.

`POST https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}/values:batchUpdate` (writes; needs read-write access)

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.spreadsheetId` | string | yes |  |
| `body.valueInputOption` | string | yes | One of: `RAW`, `USER_ENTERED`. |
| `body.data` | array<object> | yes |  |
| `body.includeValuesInResponse` | boolean | no |  |
| `body.responseValueRenderOption` | string | no | One of: `FORMATTED_VALUE`, `UNFORMATTED_VALUE`, `FORMULA`. |
| `body.responseDateTimeRenderOption` | string | no | One of: `SERIAL_NUMBER`, `FORMATTED_STRING`. |

```json
{
  "provider": "gsheets",
  "endpoint": "values.batchUpdate",
  "input": {
    "path": {
      "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
    },
    "body": {
      "valueInputOption": "RAW",
      "data": [
        {
          "range": "example",
          "values": [
            [
              null
            ]
          ]
        }
      ]
    }
  }
}
```

#### values.clear

Clear the values in a range. Formatting and validation are kept.

`POST https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}/values/{range}:clear` (writes; needs read-write access)

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.spreadsheetId` | string | yes |  |
| `path.range` | string | yes | A1 notation, e.g. "Sheet1!A1:D50" or "'Q3 data'!A:F" |

```json
{
  "provider": "gsheets",
  "endpoint": "values.clear",
  "input": {
    "path": {
      "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
      "range": "example"
    }
  }
}
```

#### spreadsheets.create

Create a spreadsheet from a Spreadsheet resource. Needs a Google sign-in connection: service accounts have no Drive storage to own files.

`POST https://sheets.googleapis.com/v4/spreadsheets` (writes; needs read-write access)

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `body` | object (free-form) | yes | Request body, passed through to the provider API as-is |

```json
{
  "provider": "gsheets",
  "endpoint": "spreadsheets.create",
  "input": {
    "body": {}
  }
}
```

#### spreadsheets.batchUpdate

Structural changes (add, rename or delete tabs, formatting, sorting, …) as a list of requests, applied atomically.

`POST https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}:batchUpdate` (writes; needs read-write access)

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.spreadsheetId` | string | yes |  |
| `body.requests` | array<object (free-form)> | yes |  |
| `body.includeSpreadsheetInResponse` | boolean | no |  |
| `body.responseRanges` | array<string> | no |  |
| `body.responseIncludeGridData` | boolean | no |  |

```json
{
  "provider": "gsheets",
  "endpoint": "spreadsheets.batchUpdate",
  "input": {
    "path": {
      "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
    },
    "body": {
      "requests": [
        {}
      ]
    }
  }
}
```

<!-- Source: https://oneapiforagents.com/providers/gdocs -->

## Google Docs

Google Docs holds briefs, reports and drafts. One API for Agents calls the Google Docs API with read and write access: agents read a document as clean markdown, create new ones, and append, insert or replace text. Documents are opened by ID or URL.

- Provider id: `gdocs`
- Auth: Sign in with Google (OAuth), Service account
- Google scopes: `https://www.googleapis.com/auth/documents`
- Raw endpoints: 3. Smart tools: 5.
- Machine-readable schemas: `GET https://api.oneapiforagents.com/v1/providers/gdocs`

### Smart tools

Curated calls with compact output for agents. Over MCP each one is a tool with the same name.

#### docs_read

Read a Google Doc as markdown-style text (headings, lists, tables, links), with its title, revisionId, tabs, heading outline with indexes, and endIndex.

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `document` | string | yes | Document ID, or its docs.google.com/document/d/<id>/… URL |
| `tab_id` | string | no | Read one tab only; by default every tab is included |
| `max_chars` | integer | no | Default `50000`. (1000–500000) |
| `suggestions` | string | no | How to show suggested edits; Google's default applies when omitted One of: `DEFAULT_FOR_CURRENT_ACCESS`, `SUGGESTIONS_INLINE`, `PREVIEW_SUGGESTIONS_ACCEPTED`, `PREVIEW_WITHOUT_SUGGESTIONS`. |

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gdocs",
    "tool": "docs_read",
    "input": {
      "document": "https://docs.google.com/document/d/1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-abc/edit"
    }
  }'
```

#### docs_create

Create a Google Doc with a title and optional initial text (markdown headings, lists and paragraphs become Docs styles). Returns its ID and URL.

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `title` | string | yes |  |
| `text` | string | no |  |
| `format` | string | no | markdown: # headings, - and 1. lists (indent to nest), [links](url), **bold**, *italic*. plain: text as is One of: `markdown`, `plain`. Default `"markdown"`. |

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gdocs",
    "tool": "docs_create",
    "input": {
      "title": "Weekly SEO report",
      "text": "# Summary\n- Clicks up 12%"
    }
  }'
```

#### docs_append

Append text or simple markdown to the end of a Google Doc (or of one tab).

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `document` | string | yes | Document ID, or its docs.google.com/document/d/<id>/… URL |
| `text` | string | yes |  |
| `format` | string | no | markdown: # headings, - and 1. lists (indent to nest), [links](url), **bold**, *italic*. plain: text as is One of: `markdown`, `plain`. Default `"markdown"`. |
| `tab_id` | string | no | Tab to use; defaults to the tab in the URL, else the first tab |

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gdocs",
    "tool": "docs_append",
    "input": {
      "document": "1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-abc",
      "text": "## Next steps\n- Refresh the pricing page"
    }
  }'
```

#### docs_replace_text

Replace every occurrence of some text in a Google Doc. Case-sensitive unless match_case is false.

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `document` | string | yes | Document ID, or its docs.google.com/document/d/<id>/… URL |
| `find` | string | yes |  |
| `replace` | string | yes | Plain text; an empty string deletes the matches |
| `match_case` | boolean | no | Default `true`. |
| `tab_id` | string | no | Only this tab; by default every tab |

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gdocs",
    "tool": "docs_replace_text",
    "input": {
      "document": "1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-abc",
      "find": "Q3",
      "replace": "Q4"
    }
  }'
```

#### docs_insert

Insert text or simple markdown into a Google Doc, either below a heading (matched by its text) or at an index from docs_read. Pass exactly one of heading or index.

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `document` | string | yes | Document ID, or its docs.google.com/document/d/<id>/… URL |
| `text` | string | yes |  |
| `format` | string | no | markdown: # headings, - and 1. lists (indent to nest), [links](url), **bold**, *italic*. plain: text as is One of: `markdown`, `plain`. Default `"markdown"`. |
| `heading` | string | no | Heading text to find (case-insensitive; exact match preferred) |
| `placement` | string | no | With heading: right under it, or at the end of its section (before the next heading of the same or higher level) One of: `below_heading`, `end_of_section`. Default `"below_heading"`. |
| `index` | integer | no | UTF-16 index. At a paragraph's start or end the text becomes new paragraphs; mid-paragraph it is inserted inline as plain text (≥ 1) |
| `revision_id` | string | no | revisionId from docs_read; the insert fails if the doc changed since |
| `tab_id` | string | no | Tab to use; defaults to the tab in the URL, else the first tab |

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gdocs",
    "tool": "docs_insert",
    "input": {
      "document": "1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-abc",
      "heading": "Next steps",
      "text": "- Add FAQ schema"
    }
  }'
```

### Raw endpoints

Passthrough to the provider API. `path` fills URL placeholders, `query` the query string and `body` the JSON body. The response is the provider's own body.

#### documents.get

The full Document resource. Pass includeTabsContent=true to get every tab in `tabs` (otherwise `body` holds the first tab only).

`GET https://docs.googleapis.com/v1/documents/{documentId}`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.documentId` | string | yes | Document ID or docs.google.com URL |
| `query.suggestionsViewMode` | string | no | One of: `DEFAULT_FOR_CURRENT_ACCESS`, `SUGGESTIONS_INLINE`, `PREVIEW_SUGGESTIONS_ACCEPTED`, `PREVIEW_WITHOUT_SUGGESTIONS`. |
| `query.includeTabsContent` | boolean | no |  |

```json
{
  "provider": "gdocs",
  "endpoint": "documents.get",
  "input": {
    "path": {
      "documentId": "1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-abc"
    },
    "query": {
      "includeTabsContent": true
    }
  }
}
```

#### documents.create

Create a blank document. Only `title` is used; add content with documents.batchUpdate.

`POST https://docs.googleapis.com/v1/documents` (writes; needs read-write access)

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `body.title` | string | no |  |

```json
{
  "provider": "gdocs",
  "endpoint": "documents.create",
  "input": {
    "body": {
      "title": "Weekly SEO report"
    }
  }
}
```

#### documents.batchUpdate

Apply Docs requests atomically (insertText, deleteContentRange, replaceAllText, createParagraphBullets, …). Indexes are UTF-16 code units; order edits from the highest index down.

`POST https://docs.googleapis.com/v1/documents/{documentId}:batchUpdate` (writes; needs read-write access)

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.documentId` | string | yes | Document ID or docs.google.com URL |
| `body.requests` | array<object (free-form)> | yes |  |
| `body.writeControl` | object | no |  |

```json
{
  "provider": "gdocs",
  "endpoint": "documents.batchUpdate",
  "input": {
    "path": {
      "documentId": "1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-abc"
    },
    "body": {
      "requests": [
        {
          "insertText": {
            "text": "Hello\n",
            "location": {
              "index": 1
            }
          }
        }
      ]
    }
  }
}
```