Agent quickstart

This page is written for an AI agent (Claude, GPT, or similar) that needs to onboard itself onto Pluto and start making calls, with no human in the loop. Everything here hits the live production API: https://api.joinpluto.com/v1.

There is also a machine-readable version of this guide an agent can fetch directly at joinpluto.com/agent/SKILL.md (opens in a new tab).

What Pluto is

A marketing API for AEO, SEO, GBP, ads, content, reviews, and social, plus a set of packaged AI workflows (one-shot LLM tasks). Call it over plain HTTPS with a bearer key, or as tools over a hosted MCP server.

1. Mint your own key (no card)

POST /v1/checkout/free is public - no auth required. Give it an email and an optional name; it mints a tenant plus a live API key and returns the raw key exactly once.

curl -X POST https://api.joinpluto.com/v1/checkout/free \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "name": "Acme Inc"}'

The 201 response:

{
  "tenant_id": "acme-1a2b3c4d",
  "tier": "free",
  "api_key": "sk_live_...",
  "api_key_meta": { "id": "...", "key_prefix": "sk_live_", "scopes": ["aeo:read", "..."] },
  "warning": "Store this key - it cannot be recovered."
}

Read the key from the api_key field. Pluto stores only a hash, so save it now.

The email is unique; a repeat returns 409 already_exists rather than a second key.
Free signups are rate-limited per IP and capped per day, so mint once and reuse.
POST /v1/api-keys mints more keys but needs an existing key with api-keys:write, which the free tier does not carry. Use /v1/checkout/free for your first key.

export PLUTO_API_KEY=sk_live_...

2. Confirm auth

GET /v1/usage is a cheap read that confirms the key works and shows your plan.

curl https://api.joinpluto.com/v1/usage \
  -H "Authorization: Bearer $PLUTO_API_KEY"

3. Add the MCP server

If you speak Model Context Protocol, point your client at the hosted server and every endpoint becomes a callable tool.

{
  "mcpServers": {
    "pluto": {
      "url": "https://api.joinpluto.com/v1/mcp",
      "headers": { "Authorization": "Bearer sk_live_..." }
    }
  }
}

Transport: HTTP, JSON-RPC 2.0 (one request maps to one response).
Discover tools with tools/list, invoke with tools/call.
27 curated tools spanning social, ads, SEO, AEO, content, reviews, GBP, local SEO, media, inbox, JobPins, and agent runs, plus tools auto-generated from the OpenAPI spec for the rest of the API.

curl https://api.joinpluto.com/v1/mcp \
  -H "Authorization: Bearer $PLUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

4. What you can call

Only these surfaces exist. Verbs are drawn from the live routes and tagged [free] (a free key can call it) or [paid] (a free key gets 403 forbidden; needs a paid key with a card). Section 5 explains why.

AEO - scan across eight AI platforms [free]; read gaps, blindspots, and share-of-voice [free]; generate schema, generate llms.txt, propose auto-fixes [paid].
SEO - read content decay, cannibalization, cached rankings [free]; live rank check, local grid, heatmap, keyword tracking (paid SERP lookups) [paid].
GBP - audit and metrics reads [free]; post [paid].
Content - reads [free]; grounded generation, article write, distribute, publish to WordPress or Webflow [paid].
Social - post, bulk post, list connected accounts [paid].
Ads - create and manage campaigns, deploy, pause, resume, optimize [paid].
Reviews - list, respond, request [paid].
Agents (packaged AI workflows) - run one, poll or stream a run [paid].
Sites (register/verify), connect (start OAuth), tenant settings, usage [free].

The URL namespace agents holds the packaged AI workflows. These are one-shot LLM tasks, not autonomous agents: you trigger one and read the result. They are paid.

Run an AEO scan [free]

POST /v1/aeo/scan asks the AI answer engines your queries and records whether the brand shows up. Runs asynchronously and returns 202 Accepted. Requires the aeo:scan scope, which a free key carries. It is metered as an agent run, so it draws down the small monthly agent-run allowance (see section 5).

curl -X POST https://api.joinpluto.com/v1/aeo/scan \
  -H "Authorization: Bearer $PLUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brand": "Acme Plumbing",
    "queries": ["best plumber in Austin", "emergency plumber near me"],
    "platforms": ["chatgpt", "perplexity"]
  }'

brand (string, required), queries (string array, at least one, required), platforms (optional; any of chatgpt, claude, gemini, perplexity, grok, deepseek, metaai, ai_overview - omit to scan all eight). Poll the returned poll_url (GET /v1/agents/runs/{id}) until status is completed.

Check a keyword rank [paid]

POST /v1/seo/rank is a live SERP lookup for one keyword and domain. It bills a DataForSEO request, so it requires the seo:write scope and a paid key - a free key gets 403 forbidden here before any spend. Shown because it is a common request shape once you upgrade.

curl -X POST https://api.joinpluto.com/v1/seo/rank \
  -H "Authorization: Bearer $PLUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "emergency plumber austin",
    "domain": "acmeplumbing.com",
    "location": "United States",
    "device": "desktop"
  }'

keyword (string, required), domain (string, required, no protocol), location (optional, defaults to United States), device (optional, desktop or mobile, defaults to desktop).

5. Free tier: look and scan, no card

The free tier is for looking and scanning. It needs no card, and its scope set is confined at request time, so anything that spends real money returns 403 forbidden to a free key before the spend.

A free key CAN:

run AEO citation scans (aeo:scan) - see whether a business shows up in AI answers;
read $0 SEO signals (content decay and cannibalization off your own Search Console data, plus cached rankings);
read GBP (audit, metrics), content, and your own account and usage;
do setup writes to finish onboarding: register and verify a site, save tenant settings, start an OAuth connect.

Included scopes (the ceiling; not a wildcard): aeo:read, aeo:scan, seo:read, gbp:read, content:read, sites:read, sites:write, tenant:read, tenant:write, connect:read, connect:write, usage:read, api-keys:read.

Needs a PAID key (a free key gets 403 forbidden):

anything that GENERATES: content and articles, AEO fixes, media;
anything that DEPLOYS to a platform: ads, social posts, GBP posts, review responses;
anything that RUNS an AI workflow: the packaged agents and workflows;
live SERP lookups (rank, grid, heatmap, keyword tracking) - they bill DataForSEO, so they sit behind seo:write.

Free quota (for the reads and scans it can make): 1,000 actions per month; AEO scans are metered as agent runs and the free monthly agent-run allowance is small (5); a hard $25 spend ceiling per period (billable calls fail closed once hit); 60 requests per minute.

Paid tiers (POST /v1/checkout/{hobby|pro|scale|agency}) return a Stripe Checkout URL and lift both the scope confinement and the quotas; Enterprise is a sales contact at sales@joinpluto.com.

6. Errors and metering

Every error is JSON with a stable machine-readable code (for example rate_limited, quota_exceeded, already_exists). Each metered request is one action; agent and workflow runs count against their own quotas. Once any quota or the spend cap is exhausted, billable calls return 402 quota_exceeded until the period resets or you upgrade. Watch live numbers at GET /v1/usage.

For the human walkthrough, see the Quickstart and MCP guide.

Introduction Quickstart