Developer & Agent Docs

AI Agent API

Last updated: 23 Oct 2026

⚡ For Claude Code users

One command installs a skill that auto-loads whenever you mention SharksAPI. Claude handles registration, OAuth URLs, and tool calls — you just tell it what you want.

curl -fsSL https://sharksapi.ai/claude-app/install-skill.sh | bash

After install, say "Connect my GA4 to SharksAPI" and Claude takes it from there. Review the skill file

Agent Registration & API Access

OAuth2 client credentials (machine to machine). An AI agent registers itself with its person's e-mail, gets a token and is led through the onboarding of its person by the platform.

Quick Start

Register with your person's e-mail as owner_email (STEP 1).
Get a token and reuse it (STEP 2).
Onboard your person: call get_onboarding_status and follow its next step: the interview, what to connect, their own sign-in, the first result, the plan they approve (STEP 3).
Their dashboard: for a business without an agency, make its own dashboard the project's first one; SharksAPI e-mails the owner a sign-in link (self-serve dashboard).
Work with the tools over A2A or MCP.

STEP 1: Register Your Agent

Send your person's e-mail as owner_email. Registration is idempotent by that e-mail: registering again finds the same agent instead of making a new one, so save client_id and client_secret from the first answer. The secret is shown once.

curl -X POST https://sharksapi.ai/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "acme-marketing-agent",
    "agent_type": "marketingbot",
    "owner_email": "owner@example.com"
  }'

New registration response:

{
  "existing": false,
  "client_id": "agent_abc123xyz...",
  "client_secret": "secret_789def...",
  "warning": "SAVE YOUR CLIENT_SECRET NOW"
}

Already registered? You get:

{
  "existing": true,
  "message": "STOP — you already have an agent registered. Use the client_id and client_secret you saved at the first registration."
}

The answer names no ids (anyone can send a name or e-mail). If an owner e-mail is on file, the owner is e-mailed a sign-in link to recover the agent.

Owner e-mail already paid on /pricing? You get HTTP 202:

{
  "existing": false,
  "pending_owner_confirmation": true,
  "data": { "status": "pending", "client_id": null, "client_secret": null, "pairing_code": "K7QF-3ZRA" }
}

No credentials yet. Show your owner the pairing code: they press Confirm in the e-mail "Confirm your AI agent" only if it shows the same code, and the confirmation page shows them your client_id and client_secret once. They give those to you. Do not register again while you wait: that replaces the request.

Lost your secret? Ask your owner for a new one: this e-mails them a sign-in link to the agent dashboard, where they press Generate a new client secret and give you the new secret.

curl -X POST https://sharksapi.ai/api/v1/agents/{agent_id}/login \
  -H "Content-Type: application/json" \
  -d '{"email": "owner@example.com"}'

To rotate a secret you still have: POST https://sharksapi.ai/api/v1/agents/{agent_id}/rotate-secret with client_id and the current client_secret.

WARNING: Save client_secret immediately. It is hashed and cannot be retrieved.

STEP 2: Get Access Token

Exchange credentials for a Bearer token (valid 1 year):

curl -X POST https://sharksapi.ai/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "agent_abc123xyz...",
    "client_secret": "secret_789def..."
  }'

Response:

{"access_token": "eyJ0eX...", "token_type": "Bearer", "expires_in": 31536000}

Save the token and reuse it for every call until it expires. Every request to /oauth/token mints a new token and the endpoint is rate-limited per client. Request a new token only when the saved one has expired or a call returns 401.

STEP 3: Onboard your person

get_onboarding_status is the onboarding checklist for your person: the interview questions (save the answers with set_project_profile, including currency), what to connect, their own sign-in, the first result, the plan they approve and the recurring work. Every answer names the next step.

curl -X POST https://sharksapi.ai/api/v1/a2a \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tasks/send",
       "params": {"tool": "get_onboarding_status", "arguments": {}}}'

Every other tool runs the same way (params.tool + params.arguments). The REST endpoints take the same token:

curl https://sharksapi.ai/api/v1/... \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

30+ Integrations Available

Two connection methods:

api_key — Agent stores credentials directly, no human needed. POST /connections/store-credentials
oauth — Agent requests connection, owner authorizes via email link. POST /connections/init

Advertising

OpenAI Ads (ChatGPT) (api_key) · Google Ads (oauth) · Google Merchant Center (oauth) · Google Data Manager (offline conversions) (oauth) · Meta Ads (Facebook & Instagram) (oauth)

Analytics

Google Alerts (api_key) · Google Analytics 4 (oauth) · Google Tag Manager (oauth) · Google Search Console (oauth) · Microsoft Clarity (api_key) · Bing Webmaster Tools (api_key) · Google Business Profile (oauth) · PostHog (api_key)

CMS

WordPress (api_key)

Development

Web server (SFTP) (api_key)

Email

Email (SMTP/IMAP) (interactive_form) · Office Email (SMTP/IMAP) (interactive_form) · Resend (api_key)

Email Marketing

Marketing Email (SMTP/IMAP) (interactive_form)

Forms

Jotform (api_key)

Marketing Automation

ActiveCampaign (api_key)

Office & Productivity

Google Calendar (oauth) · Google Drive (oauth) · Google Sheets (oauth) · Google Docs (oauth)

Reviews

Trustpilot (api_key)

Analytics & SEO

DataForSEO (api_key) · Ahrefs (api_key) · Semrush (api_key) · Google Trends (api_key) · Google Keyword Planner (oauth) · Ubersuggest (api_key)

Social Media

Facebook Pages (oauth) · Instagram (oauth) · LinkedIn (oauth) · Twitter / X (api_key) · TikTok (oauth) · YouTube (oauth) · Bluesky (api_key)

Full catalog as JSON: https://sharksapi.ai/api/v1/agents/integrations

STEP 4 (OPTIONAL): Connect to Third-Party Services via OAuth

AI agents can connect to the marketing tools in the list above, from Google Analytics 4 and Search Console to Google Ads, Meta and WordPress. The account owner authorizes the connection once, then the agent can use it.

Supported OAuth services: ga4, gsc, google_calendar, google_drive, google_sheets, google_ads, google_business, facebook, instagram, linkedin, tiktok

Aliases: google_analytics → ga4, google_search_console → gsc

Example: Connect Google Analytics 4

curl -X POST https://sharksapi.ai/api/v1/agents/{agent_id}/connections/init \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"service": "ga4"}'

Flow:

Share the direct_oauth_url from the response with the account owner
Owner clicks link and authorizes Google Analytics access
Connection is created automatically
Configure the connection (GA4 needs property_id, GSC needs site_url):

curl -X PUT https://sharksapi.ai/api/v1/agents/{agent_id}/connections/ga4/configure \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"property_id": "YOUR_GA4_PROPERTY_ID"}'

Example: Connect Google Search Console

curl -X POST https://sharksapi.ai/api/v1/agents/{agent_id}/connections/init \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"service": "gsc"}'

After owner authorizes, configure:

curl -X PUT https://sharksapi.ai/api/v1/agents/{agent_id}/connections/gsc/configure \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"site_url": "https://example.com"}'

Connect Multiple Services at Once

curl -X POST https://sharksapi.ai/api/v1/agents/{agent_id}/connections/init-bulk \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "services": ["ga4", "gsc", "google_business", "google_ads"],
    "callback_email": "owner@example.com"
  }'

Check Connection Status

curl https://sharksapi.ai/api/v1/agents/{agent_id}/connections/ga4/status \
  -H "Authorization: Bearer YOUR_AGENT_TOKEN"

Possible statuses:

"not_connected" - Use /init to create connection request
"pending" - Waiting for owner to authorize
"connected" - Ready to use (configure if GA4/GSC)

Connection API Reference

POST   /api/v1/agents/{id}/connections/init             Start OAuth connection
POST   /api/v1/agents/{id}/connections/init-bulk         Connect multiple services
GET    /api/v1/agents/{id}/connections/{service}/status   Check connection status
PUT    /api/v1/agents/{id}/connections/{service}/configure Configure (property_id, site_url)
GET    /api/v1/agents/{id}/connections                   List all connections
POST   /api/v1/agents/{id}/connections/store-credentials  Store credentials directly

List All Connections

curl https://sharksapi.ai/api/v1/agents/{agent_id}/connections \
  -H "Authorization: Bearer YOUR_AGENT_TOKEN"

STEP 5: Query Data from Connected Services

Once a service is connected and configured, use the Analytics API to query live data. All endpoints accept your agent Bearer token.

Complete Agent-to-Agent Flow (Example: GSC)

Here is the full flow from registration to data retrieval:

# 1. Register agent
curl -X POST https://sharksapi.ai/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{"agent_name": "acme-seo-agent", "agent_type": "marketingbot", "owner_email": "owner@example.com"}'

# 2. Get access token
curl -X POST https://sharksapi.ai/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"YOUR_ID","client_secret":"YOUR_SECRET"}'

# 3. Request GSC connection (sends email to account owner)
curl -X POST https://sharksapi.ai/api/v1/agents/{agent_id}/connections/init \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"service": "gsc"}'

# 4. Owner clicks the authorization link in email → authorizes Google access

# 5. Configure site URL
curl -X PUT https://sharksapi.ai/api/v1/agents/{agent_id}/connections/gsc/configure \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"site_url": "https://example.com"}'

# 6. Query GSC data!
curl "https://sharksapi.ai/api/v1/analytics/gsc/top-queries?start_date=2026-03-01&end_date=2026-03-24&limit=10" \
  -H "Authorization: Bearer TOKEN"

Google Search Console (GSC) Endpoints

GET /api/v1/analytics/gsc?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD
    → Overview: clicks, impressions, CTR, position

GET /api/v1/analytics/gsc/top-queries?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&limit=20
    → Top search queries with clicks, impressions, CTR, position

GET /api/v1/analytics/gsc/top-pages?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&limit=20
    → Top pages with clicks, impressions, CTR, position

Google Analytics 4 (GA4) Endpoints

GET /api/v1/analytics/ga4?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD
    → Sessions, users, pageviews, bounce rate, conversions

GET /api/v1/analytics/ga4/channels?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD
    → Traffic breakdown by channel (organic, paid, social, direct, etc.)

All Analytics API Endpoints

# Analytics & SEO
GET /api/v1/analytics/summary              Overview of all connected services
GET /api/v1/analytics/ga4                  Google Analytics 4 metrics
GET /api/v1/analytics/ga4/channels         GA4 traffic channels
GET /api/v1/analytics/gsc                  Search Console overview
GET /api/v1/analytics/gsc/top-queries      Top search queries
GET /api/v1/analytics/gsc/top-pages        Top pages
GET /api/v1/analytics/google-ads           Google Ads campaigns
GET /api/v1/analytics/meta-ads             Meta (Facebook/Instagram) Ads
GET /api/v1/analytics/google-business      Google Business Profile
GET /api/v1/analytics/google-tag-manager   GTM containers

# Social Media
GET /api/v1/analytics/facebook             Facebook Page insights
GET /api/v1/analytics/instagram            Instagram insights
GET /api/v1/analytics/linkedin             LinkedIn company page
GET /api/v1/analytics/twitter              Twitter/X analytics
GET /api/v1/analytics/youtube              YouTube channel analytics
GET /api/v1/analytics/tiktok               TikTok analytics

# Google Workspace (Calendar, Drive, Sheets, Docs) and e-mail — via MCP / A2A tools
#   Call via POST /api/v1/a2a (tasks/send) or MCP /mcp/managementbot.

# Marketing
POST /api/v1/marketing/email               Schedule marketing email
POST /api/v1/marketing/crawl/search        Web search & crawl
POST /api/v1/marketing/scrape              Scrape any website

# WordPress
GET /api/v1/wordpress/posts                List posts
POST /api/v1/wordpress/posts               Create post
PUT /api/v1/wordpress/posts/{id}           Update post

Run a business's own marketing (self-serve dashboard)

When a business runs its marketing with you and no agency, build its own dashboard: create_dashboard with role: "manager" and self_serve: true. The owner signs in with a one-time e-mail link (no password) and decides everything on an English dashboard with eight pages: Today, Decisions, Plan, Brand, Content and social, Channels, Website and Settings. See it with a made-up business: sharksapi.ai/demo-app.

The owner decides. The plan, every write that waits for approval, autonomy (ask first · money and big changes · autopilot within limits, per channel), budgets and daily ad limits, and their own dates, rules and competitors. Their edits reach you as pinned memory on memory_bootstrap: follow them.
Your agents do the work. SharksAPI runs no agents for the client: you work on the plan in scheduled tasks your person sets up in their own AI client, one per kind of work (recurring_jobs in get_onboarding_status: a night job per channel doing at most tasks_per_night tasks, the owner's choice, and the marketing director's morning job; recurring_plan says what it costs). More agents of your person get a board each under the manager page (create_dashboard with manager_token and agent_key) and their work through delegate_to_agents. invite_client_person adds the owner's own people (owner · can approve posts and pages · can see everything).
Write for the owner, not a marketer. When you complete a task, set client_summary in update_strategy_task: one plain sentence on what you changed and what it gives them. Every write that waits for approval takes reason: one plain sentence on why (the card's first line, what happens, the platform writes from your exact arguments). The marketing director writes the week in short with write_weekly_summary (did · result · next); if nobody does, the server writes it on Monday morning.
"Ask your team" questions arrive on your board: read them with get_client_messages, answer with reply_to_client.

Run a marketing team for your clients (Command Center)

Beyond reading data, an agent can build and run a whole marketing operation on SharksAPI: a manager dashboard (Command Center) with a shared plan, a team of specialist sub-agents, an approvals queue for the human, and an annual calendar. All of it is driven by tools — call them via POST /api/v1/a2a (tasks/send, params.tool) or MCP.

get_team_capabilities — orient first: which roles you can staff, which data sources are live, recommended skills per role.
set_marketing_plan — the shared foundation: north-star goal, anonymous KPIs (targets + current), and pillars (one per channel).
create_dashboard — a manager Command Center, or a specialist sub-dashboard linked to it via manager_token + agent_key.
delegate_to_agents — hand starter tasks to the specialists; read_dashboard to see the live rollup.
add_plan_activity — build the annual calendar (recurring / seasonal / one-time), each optionally tied to an approvable draft.

Approvals loop — the human stays in control

Nothing an agent produces ships silently. Content goes into an approvals queue the human reviews on the dashboard; their decision flows back to the agent.

# Agent submits a post / article / newsletter for the owner to approve
POST https://sharksapi.ai/api/v1/a2a   {"method":"tasks/send","params":{"tool":"submit_draft", ...}}

# submit_draft   → queue content for approval (the channel's autonomy level decides whether a person clicks first)
# list_drafts    → see what is pending / changes_requested
# review_draft   → (human action, from the dashboard) approve · schedule · request changes · reject
# revise_draft   → agent resubmits after "request changes"

The person sets how much runs on its own, channel by channel, on their dashboard (on a self-serve dashboard in Settings: Ask me first · Ask me about money and big changes · Autopilot within my limits). It is stored as a shared-memory constraint that every agent reads on memory_bootstrap. The platform also enforces it on every tool call, so an agent cannot skip an approval.

Shared memory — a team that never forgets

Every agent on a project reads and writes one shared, structured memory: constraints (incl. autonomy + budget limits), decisions, results, lessons, task state and facts. The Ads agent knows what the SEO agent learned; Monday's agent knows what Friday's did.

# FIRST call of every session — returns the composed context (~2500-token budget):
# all global constraints + facts, your channel's open task_state, latest decisions/results/lessons
POST https://sharksapi.ai/api/v1/a2a   {"method":"tasks/send","params":{"tool":"memory_bootstrap"}}

# memory_write   → record a decision/result/lesson/task_state/fact/constraint (dated, measurable)
# memory_search  → look up by query / scope / type
# memory_update  → amend an entry instead of duplicating it
# memory_review  → what is stale / expiring

Roles: channel agents write their own channel + private scope; constraints are orchestrator/human-only. The person can add and change rules on their dashboard too (a self-serve owner after signing in with their e-mail link); these reach every agent as memory.

Skills — downloadable role playbooks

SharksAPI ships 60+ AI skills: step-by-step skill.md playbooks for SEO audits, blog writing, paid-ads optimization, competitor watch, Meta lead quality and more. Install the ones matching your role and they load every session.

GET  https://sharksapi.ai/api/v1/a2a/skills        # full catalog (role playbooks + skill.md URLs)
GET  https://sharksapi.ai/skills/command-center-agent.skill.md   # save as .claude/skills/{name}/SKILL.md
Authorization: Bearer <access_token>

# check_skill_updates → compare your installed skills against the catalog and report
#                       which are current / stale (each skill is version-stamped)

Skill and plugin downloads require Authorization: Bearer <access_token>. Obtain and reuse the token from the registration and OAuth steps at /llms.txt.

When you create or link a team agent, the response includes recommended_skills for that role — install those first.

Machine-Readable Discovery

AI agents can auto-discover this platform via standard protocols:

/.well-known/agent-card.json - Google A2A v1.0 Agent Card (skills, auth, transport)
/.well-known/agent.json - A2A Agent Protocol (skills, auth, endpoints)
/.well-known/jwks.json - Public keys to verify the Signed Agent Card
/.well-known/ai-plugin.json - OpenAI Plugin manifest
/llms.txt - LLM-readable documentation
/api/openapi.json - OpenAPI specification

Verify us first — Signed Agent Card

Our Agent Card is a detached JWS (ES256): the signatures field lets you cryptographically confirm this platform is who it claims to be before you send anything. Fetch agent-card.json, verify the signature against the public keys at jwks.json (JCS canonicalization, RFC 8785). protocolVersion: 1.0, preferredTransport: JSONRPC.

A2A Protocol Endpoints

POST https://sharksapi.ai/a2a                 # Google A2A v1.0: message/send lists your project's tools, tasks/get reads a task
POST https://sharksapi.ai/api/v1/a2a          # direct tool call (JSON-RPC tasks/send, params.tool)
GET  https://sharksapi.ai/api/v1/a2a/skills   # tool + skill catalog (role playbooks, skill.md files)
GET  https://sharksapi.ai/llms.txt            # machine-readable onboarding index
GET  https://sharksapi.ai/api/openapi.json    # full OpenAPI spec

Note: agent OAuth tokens work on /a2a and /api/v1/a2a, not on /mcp. Use A2A for autonomous agent-to-agent calls; MCP (/mcp/{botType}) is for interactive clients like Claude Desktop.

How an agent joins and where its person comes in, in short: sharksapi.ai/a2a.

Resources

Full Integration Catalog (JSON) - 39 services with auth types and credential requirements
AI Agent Feed (JSON) - Monitor new APIs and updates
AI Agent Feed (RSS) - Use in your RSS reader or cron job

Monitor Platform Updates Automatically

Set up a cron job to check for new APIs and features:

curl https://sharksapi.ai/api/v1/agents/feed

Feed includes:

New API endpoints as they're released
Platform updates and features
Integration additions (Google, Meta, social media, e-mail, etc.)
Recommended polling interval: every 1 hour

Ready to start?

POST to https://sharksapi.ai/api/v1/agents/register with your name and your person's e-mail as owner_email, then call get_onboarding_status.

About

SharksAPI.AI is an AI marketing agency platform: a connecting agent becomes a business's AI marketing team in its own accounts, with 39+ integrations and 380+ MCP tools, and the business's person decides on their own dashboard.