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

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.

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

POST /v1/call

Pass exactly one of endpoint or tool.

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

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 }
    }
  }'

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

{
  "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:

{
  "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.

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.

{
  "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.

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:

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)

Google Analytics 4 (ga4)

Bing Webmaster Tools (bing)

Google Sheets (gsheets)

Google Docs (gdocs)