# SharksAPI.AI — AI Agent Onboarding Guide > Base URL: https://sharksapi.ai > Protocol: A2A (Agent-to-Agent) + MCP (Model Context Protocol) > Auth: OAuth2 Client Credentials > Discovery: https://sharksapi.ai/.well-known/agent.json ## Agent Identity Rules (read this first) **Registration is idempotent by `(owner_email, agent_type)`.** Same email + same type always returns the same agent. NEVER invent a new `agent_name` each session — use the owner's email to look up the existing agent. **Valid `agent_type` values:** `claude_cowork`, `marketingbot`, `salesbot`, `opsagent`, `managementbot`, `custom`. Any other value is rejected with HTTP 422. **Recommended agent_name format:** `claude-code-{slug(owner_email)}-{agent_type}` — e.g. `claude-code-user-at-example-com-marketingbot`. **Before registering:** If you have saved `client_id` and `client_secret` from a previous session, skip registration and POST directly to `/oauth/token`. The register endpoint does NOT return `client_secret` on subsequent lookups — it's only shown at initial creation. **If you lose credentials:** `POST /api/v1/agents/{id}/login` triggers a magic-link email. The owner clicks the link, visits the agent dashboard, and can rotate the secret via `POST /api/v1/agents/{id}/rotate-secret`. Your `agent_id`, `client_id`, and connections all remain intact. --- ## Quick Start (5 steps) ### Step 1: Register POST https://sharksapi.ai/api/v1/agents/register Content-Type: application/json { "agent_name": "your-unique-agent-name", "agent_type": "marketingbot", "owner_email": "owner@example.com", "description": "Brief description of your agent" } agent_type options: claude_cowork, marketingbot, salesbot, opsagent, managementbot, custom Response includes client_id and client_secret. SAVE client_secret — it cannot be retrieved again (it is hashed on our side). If the same agent_name + agent_type already exists, the endpoint returns the existing agent's credentials (acts as login). ### Step 2: Get Bearer Token POST https://sharksapi.ai/oauth/token Content-Type: application/json { "grant_type": "client_credentials", "client_id": "agent_xxx...", "client_secret": "secret_xxx..." } Response: {"access_token": "...", "token_type": "Bearer", "expires_in": 31536000} Use this token in all subsequent requests: Authorization: Bearer {access_token} ### Step 3: Connect Services Most services require OAuth authorization by the human owner. Use bulk init to request multiple services at once: POST https://sharksapi.ai/api/v1/agents/{agent_id}/connections/init-bulk Authorization: Bearer {token} Content-Type: application/json { "services": ["ga4", "gsc", "facebook", "linkedin"], "callback_email": "owner@example.com" } Response includes an authorization_url. Present this URL to the human user — they must open it in a browser to authorize each service via OAuth. After authorization, the human selects which specific account/property to use (e.g., which GA4 property, which Facebook Page). For single service: POST https://sharksapi.ai/api/v1/agents/{agent_id}/connections/init Body: {"service": "ga4", "callback_email": "owner@example.com"} For API-key services (no OAuth needed): POST https://sharksapi.ai/api/v1/agents/{agent_id}/connections/store-credentials Body: {"service": "pipedrive", "credentials": {"api_key": "xxx"}} ### Step 4: Check Connection Status GET https://sharksapi.ai/api/v1/agents/{agent_id}/connections Authorization: Bearer {token} Or per service: GET https://sharksapi.ai/api/v1/agents/{agent_id}/connections/{service}/status If a connection has needs_configuration: true, you must select which account to use: GET https://sharksapi.ai/api/v1/agents/{agent_id}/connections/{service}/options (Returns list of available properties/accounts/pages) PUT https://sharksapi.ai/api/v1/agents/{agent_id}/connections/{service}/configure Body depends on service: - ga4: {"property_id": "123456789"} - gsc: {"site_url": "https://example.com"} - bing: {"site_url": "https://example.com/"} // first store credentials with {"api_key": "..."} - facebook: {"page_id": "123456"} - instagram: {"ig_business_account_id": "123456"} - linkedin: {"organization_urn": "urn:li:organization:123456"} - meta_ads: {"ad_account_id": "act_123456"} - google_ads: {"customer_id": "123456"} - youtube: {"channel_id": "UCxxx"} Note: If the human owner authorized via the web UI, they may have already selected the account during OAuth. Check the connection status first. ### Step 5: Fetch Documentation & Use Tools GET https://sharksapi.ai/api/v1/agents/{agent_id}/documentation Authorization: Bearer {token} Returns all available tools grouped by category, with full parameter schemas, usage guide, and connection status. This is your primary reference for what you can do. ## Credential Recovery If you've lost your `client_secret`: 1. `POST /api/v1/agents/{agent_id}/login` Triggers a magic-link email to the owner. The owner clicks the link and lands on the agent dashboard. 2. From the dashboard, the owner generates a new secret via `POST /api/v1/agents/{agent_id}/rotate-secret`. 3. The owner pastes the new `client_secret` back into `~/.sharksapi/credentials.json` (or wherever credentials are stored). 4. Your `agent_id`, `client_id`, all existing connections, and history stay intact — only the secret changes. Do NOT re-register with a different `agent_name` — registration is idempotent by `(owner_email, agent_type)` and you will just get the same agent back (without a new secret). --- ## Calling Tools ### Option A: A2A Protocol (recommended) POST https://sharksapi.ai/api/v1/a2a Authorization: Bearer {token} Content-Type: application/json { "jsonrpc": "2.0", "method": "tasks/send", "id": "req-1", "params": { "tool": "get_ga4", "arguments": { "metrics": ["sessions", "totalUsers"], "dimensions": ["date"], "start_date": "2025-01-01", "end_date": "2025-01-31" } } } You can also route by skill instead of specific tool: "params": {"skill": "marketing", "message": {"query": "Get last 30 days traffic overview"}} ### Send an email (A2A) ``` POST https://sharksapi.ai/api/v1/a2a Authorization: Bearer {token} Content-Type: application/json { "jsonrpc": "2.0", "method": "tasks/send", "id": "req-email-1", "params": { "tool": "send_email", "arguments": { "to": "recipient@example.com", "subject": "Hello from SharksAPI", "body": "Plain text version of the message", "html": "

HTML version (optional)

" } } } ``` You can also route by skill instead of a specific tool: ``` "params": {"skill": "email", "message": {"query": "Send a test email to support@example.com"}} ``` Available skills: marketing, analytics, seo, social, sales, crm, invoicing, payments, office, email, calendar, documents, management ### Option B: MCP Protocol POST https://sharksapi.ai/mcp/{botType} Content-Type: application/json Step 1 — Initialize: {"jsonrpc":"2.0","method":"initialize","id":"1","params":{}} Step 2 — List tools: {"jsonrpc":"2.0","method":"tools/list","id":"2","params":{}} Step 3 — Call tool: {"jsonrpc":"2.0","method":"tools/call","id":"3","params":{"name":"get_ga4","arguments":{...}}} botType options: marketingbot, salesbot, opsagent, managementbot ## Available Services (by category) ### Analytics & SEO (OAuth) - ga4 — Google Analytics 4 (traffic, audience, conversions) [config: property_id] - gsc — Google Search Console (search performance, keywords, indexing) [config: site_url] - bing — Bing Webmaster Tools (Bing organic search clicks/impressions/queries/pages, crawl & index stats) [api_key auth, config: site_url] - microsoft_clarity — Microsoft Clarity (UX session insights — dead clicks, rage clicks, scroll depth, JS errors; last 1–3 days only) [api_key auth, no config required] - google_ads — Google Ads (campaigns, keywords, bidding) - google_business — Google Business Profile (reviews, local SEO, Maps/Search visibility) [config: account_id, location_id] - google_alerts — Google Alerts (brand mentions, keyword monitoring, web monitoring via RSS) [no credentials needed, config: rss_feeds array] - google_tag_manager — Google Tag Manager (tags, triggers, variables) - youtube — YouTube Analytics (channel stats, video performance) ### Social Media (OAuth) - facebook — Facebook Pages (posts, insights, engagement) [config: page_id] - instagram — Instagram Business (posts, stories, insights) [config: ig_business_account_id] - linkedin — LinkedIn Company Pages (posts, analytics) [config: organization_urn] - twitter — Twitter/X (tweets, analytics) - tiktok — TikTok Business (videos, analytics) - bluesky — Bluesky (posts, engagement) ### Advertising (OAuth) - meta_ads — Meta Ads / Facebook Ads (campaigns, ad sets, performance) [config: ad_account_id] - google_ads — Google Ads (see above) ### CRM & Sales (API key) - pipedrive — Pipedrive CRM (deals, contacts, organizations, activities) - hubspot — HubSpot CRM - salesforce — Salesforce CRM ### Accounting & Invoicing (API key) - merit_aktiva — Merit Aktiva (Estonian accounting, invoices, payments) - xero — Xero Accounting - fortnox — Fortnox (Swedish accounting) - sevdesk — sevDesk (German accounting) - exact_online — Exact Online - dinero — Dinero (Danish accounting) - visma — Visma e-conomic - sage — Sage Accounting - freeagent — FreeAgent - quickbooks — QuickBooks - freshbooks — FreshBooks - wave — Wave Accounting - zoho_books — Zoho Books - moneybird — Moneybird (Dutch accounting) ### Payments (API key) - wise — Wise (international payments, balances) - stripe — Stripe (payments, subscriptions) - mollie — Mollie (European payments) - paypal — PayPal Business - gocardless — GoCardless (direct debit) - adyen — Adyen ### E-commerce (API key) - shopify — Shopify (products, orders, customers) - woocommerce — WooCommerce - bigcommerce — BigCommerce - magento — Magento / Adobe Commerce ### Office & Productivity (OAuth) - google_calendar — Google Calendar (events, scheduling) - google_drive — Google Drive (files, folders) - gmail — Gmail (send, read, search emails) - google_sheets — Google Sheets (read, write data) - notion — Notion (pages, databases) ### Email Marketing (API key) - activecampaign — ActiveCampaign - constant_contact — Constant Contact - marketo — Marketo - klaviyo — Klaviyo ### Proposals (API key) - pandadoc — PandaDoc (proposals, contracts, e-signatures) ### HR & Project Management (API key) - personio — Personio (HR management) - teamwork — Teamwork (project management) ### Other (no connection needed) - scraper — Web scraping and crawling (always available) - pagespeed — Google PageSpeed Insights (always available) ## Dashboards (always available) SharksAPI lets you build **persistent public dashboards** at `https://sharksapi.ai/{token}/index.html` that mix integration data (GA4, GSC, Facebook, LinkedIn, etc.) with agent-generated content (marketing plans, tasks, commentary). Anyone with the URL can view — no auth required. Data is fetched with hybrid caching (5 min GA4, 15 min GSC, 1h social) and the page has a built-in time range filter that re-fetches widgets live. **Five A2A tools** — always available regardless of which integrations are connected: - `create_dashboard` — Persist a new dashboard with widgets, returns a `public_url` - `get_dashboard` — Fetch a dashboard's config by token - `update_dashboard` — Partial updates (name, widgets, dates) - `delete_dashboard` — Permanently remove a dashboard (cascades to widgets + cache) - `invalidate_dashboard_cache` — Force all widgets to refetch on next view ### Widget types - `metric_card` — Single number + label (e.g. "Total Sessions: 12,345"). Uses `grid_cols: 3`. - `chart_line` — Time series line chart. Uses `grid_cols: 6-9`. - `chart_bar` — Bar chart. Uses `grid_cols: 6`. - `table` — Simple data table (first 50 rows shown). - `text_markdown` — Agent-authored markdown content (marketing plans, tasks, notes). **Never cached — stored as-is.** Uses `grid_cols: 12`. ### Create a dashboard (A2A) ``` POST https://sharksapi.ai/api/v1/a2a Authorization: Bearer {token} Content-Type: application/json { "jsonrpc": "2.0", "method": "tasks/send", "id": "req-dash-1", "params": { "tool": "create_dashboard", "arguments": { "name": "Weekly Marketing Overview", "description": "GA4 + social engagement + the plan for this week", "default_date_range": "last_30_days", "is_public": true, "widgets": [ { "type": "metric_card", "title": "Total Sessions", "position": 0, "grid_cols": 3, "source": {"tool": "get_ga4", "arguments": {"metrics": ["sessions"], "aggregate": true}} }, { "type": "chart_line", "title": "Daily Sessions", "position": 1, "grid_cols": 9, "source": {"tool": "get_ga4", "arguments": {"metrics": ["sessions", "totalUsers"], "dimensions": ["date"]}} }, { "type": "text_markdown", "title": "Marketing Plan — Week 15", "position": 2, "grid_cols": 12, "content": "## This week's focus\n\n1. Launch LinkedIn campaign for Q2 product\n2. A/B test new landing page copy\n3. Review last week's email open rates" } ] } } } ``` **Response:** ``` { "jsonrpc": "2.0", "id": "req-dash-1", "result": { "dashboard_id": 42, "public_token": "xK3p8AqM4nB2vFg7rT9yL1eHs6dZj0wQ", "public_url": "https://sharksapi.ai/xK3p8AqM4nB2vFg7rT9yL1eHs6dZj0wQ/index.html", "widget_count": 3, "message": "Dashboard created. Share the public_url with anyone — no auth required." } } ``` **Give the `public_url` to the user.** They open it in a browser, see live data with a date filter, and can share the link with anyone. ### Key rules - **Integration tool widgets** (`metric_card`, `chart_line`, `chart_bar`, `table`) need a `source: {tool, arguments}` pointing at an existing MCP tool (e.g. `get_ga4`, `get_search_console`, `get_facebook`). The dashboard's date range filter is automatically merged into the tool's arguments on each view. - **Text widgets** (`text_markdown`) use `content` (markdown string) instead of `source`. These are agent-authored — you generate the content in your conversation and pass it as-is. - **Grid layout**: 12-column system. Typical combos: `metric_card` at 3, chart at 6-9, `text_markdown` at 12 (full width). - **Soft limit**: 50 widgets per dashboard. - **Default language: English.** Use English for `name`, `description`, widget `title`, and markdown `content` unless the user explicitly asks for another language. Dashboards are public share-links — even if the user chats with you in Estonian/German/etc., they usually want an English page they can share with their team. - **Cache TTL defaults**: 5 min (GA4), 15 min (GSC, Clarity), 1h (social media). Override per widget with `cache_ttl_seconds`. - **Cross-project**: dashboards are scoped to your project. You can't access another project's dashboard. - **Strategy cards**: Widget type `strategy_card` — AI-built strategies with interactive task checklists. Human or AI can check off tasks. Mode: `human_controlled` (browser checkboxes) or `ai_controlled` (agent marks via API). Max 5 per dashboard. Tools: `update_strategy_task`, `get_strategy_status`. - **Strategy skills**: `GET /api/v1/a2a/skills` returns `strategy_skills[]` with downloadable skill.md files (SEO audit, content strategy, social media plan, CRO). Each skill describes the data collection → analysis → strategy card creation workflow. ### Update a dashboard's marketing plan (agent content) ``` { "tool": "update_dashboard", "arguments": { "token": "xK3p8AqM4nB2vFg7rT9yL1eHs6dZj0wQ", "update_widgets": [ {"position": 2, "content": "## Week 16 focus\n\n1. Publish case study\n2. Run LinkedIn ad retargeting"} ] } } ``` Updating a widget automatically invalidates its cache. ### Password-protect a dashboard If the boss wants the dashboard private, they give you (the agent) a password to share with viewers. Pass it as `password` in `create_dashboard` or `update_dashboard` — the server stores a bcrypt hash, never plaintext. ``` { "tool": "create_dashboard", "arguments": { "name": "Q2 Sales Pipeline (Private)", "password": "Spring2026!", "widgets": [...] } } ``` Response includes `has_password: true`. Tell the user **two things**: the `public_url` AND the password. Viewers see a password gate before the dashboard renders. Once unlocked, a 24h cookie keeps them in. To remove the password later (make it open again): ``` { "tool": "update_dashboard", "arguments": {"token": "...", "password": null} } ``` To change the password: ``` { "tool": "update_dashboard", "arguments": {"token": "...", "password": "new-secret"} } ``` ### Strategy cards — AI-built strategies with task checklists Create a strategy card with prioritized tasks that humans or AI can check off: ``` { "tool": "update_dashboard", "arguments": { "token": "...", "add_widgets": [{ "type": "strategy_card", "title": "SEO Strategy — Week 16", "position": 0, "grid_cols": 12, "content": "## Analysis\nBased on GSC data...", "source": { "mode": "human_controlled", "tasks": [ {"title": "Update meta description on /pricing", "description": "CTR is 1.2% with 3.4K impressions"}, {"title": "Add FAQ schema to /how-it-works"}, {"title": "Compress hero images on /features (>500KB)"} ] } }] } } ``` Mode: `human_controlled` (browser checkboxes) or `ai_controlled` (agent marks tasks via API). **Check task progress** (before creating next week's strategy): ``` {"tool": "get_strategy_status", "arguments": {"token": "...", "widget_id": 42}} ``` Returns: title, mode, progress_pct, tasks with completion state and who completed them. **Mark a task as completed** (AI-controlled mode only): ``` {"tool": "update_strategy_task", "arguments": {"token": "...", "widget_id": 42, "task_id": 7, "is_completed": true}} ``` Max 5 strategy cards per dashboard. Strategy cards appear on the dashboard with a progress bar, interactive checkboxes, and a mode toggle (Human/AI Agent). ### Strategy execution skills SharksAPI hosts downloadable skill.md files that tell the agent HOW to execute strategies. **Discover available skills:** ``` GET /api/v1/a2a/skills ``` Returns `strategy_skills[]` with `id`, `url`, `triggers[]`, and `category`. Categories: `sharksapi` (use connected data), `seo_research`, `seo_build`, `seo_optimize`, `seo_monitor`, `seo_protocol`. **Download and follow a skill:** ``` GET https://sharksapi.ai/skills/seo-audit.skill.md ``` Each skill.md contains phased instructions: data collection → analysis → strategy card creation → execution → weekly follow-up. **Available SharksAPI skills** (use connected integrations → strategy card): - `seo-audit.skill.md` — GSC + GA4 + PageSpeed → top 10 SEO tasks (one-time audit) - `weekly-seo-review.skill.md` — recurring weekly review: pull GA4 + GSC, check previous strategy card progress, carry forward incomplete tasks, create new week's card. Replaces local file-based todo tracking. Includes SEO indexing rule (don't re-optimize pages changed <2-4 weeks ago). - `content-strategy.skill.md` — search queries → content publishing plan - `social-media-plan.skill.md` — Facebook + LinkedIn → weekly posting plan - `conversion-optimization.skill.md` — GA4 events + Clarity → CRO tasks - `blog-writer.skill.md` — research topic online + via SharksAPI (GSC, GA4, WP), write SEO-optimized article with SILO internal links, styled HTML comparison tables (color-coded costs), JSON-LD schema (Article + FAQPage + Breadcrumb), featured image (AI-generated or stock suggestion), built-in proofreading checklist, topic uniqueness check against existing posts, publish as WordPress draft. Project-agnostic. - `paid-ads-strategy.skill.md` — audit Google Ads + Meta Ads via SharksAPI (get_google_ads, get_meta_ads), find wasted spend and optimization opportunities, create strategy card with tasks. Sub-skills for deep audits: ads-google (80 checks), ads-meta (50 checks), ads-creative, ads-budget, ads-landing, ads-plan. - `command-center-agent.skill.md` — recurring agent task: check dashboard strategy cards for pending AI-controlled tasks, execute them using SharksAPI tools (SEO, content, analytics), mark complete via update_strategy_task. Use as Claude Cowork recurring task or scheduled agent. Replaces Chrome-based dashboard monitoring with direct A2A API calls. **Available SEO/GEO execution skills** (20 skills from seo-geo-claude-skills): - Research: keyword-research, competitor-analysis, serp-analysis, content-gap-analysis - Build: seo-content-writer, geo-content-optimizer, meta-tags-optimizer, schema-markup-generator - Optimize: on-page-seo-auditor, technical-seo-checker, internal-linking-optimizer, content-refresher - Monitor: rank-tracker, backlink-analyzer, performance-reporter, alert-manager - Protocol: content-quality-auditor (80-item CORE-EEAT), domain-authority-auditor (40-item CITE), entity-optimizer All served at `https://sharksapi.ai/skills/{name}.skill.md` **Typical agent workflows:** One-time audit: 1. User: "Do an SEO audit for my site" 2. Agent: `GET /api/v1/a2a/skills` → match trigger → download `seo-audit.skill.md` 3. Agent follows phases: call get_gsc_top_queries, analyze_pagespeed, etc. 4. Agent creates strategy_card on dashboard with 10 tasks 5. Human checks off tasks in browser (or agent executes in AI-controlled mode) Recurring weekly review: 1. User sets up recurring task: "Weekly SEO review using SharksAPI" 2. Agent downloads `weekly-seo-review.skill.md` → follows 6 steps: - `get_strategy_status` on last week's card → see what's done - Pull GA4 + GSC for last 7 days - Carry forward incomplete tasks + add new ones from fresh data - Create new strategy_card on dashboard 3. Dashboard accumulates weekly cards as a timeline (archive after 4 weeks) Paid ads audit: 1. User: "Audit our Google Ads and Meta Ads" 2. Agent downloads `paid-ads-strategy.skill.md` 3. Calls `get_google_ads` + `get_meta_ads` + `get_ga4_channels` + `analyze_pagespeed` 4. Identifies waste (campaigns with spend but no conversions), low ROAS, fatigued creatives 5. Creates strategy_card with optimization tasks (pause waste, reallocate budget, refresh creatives) 6. For deeper audits: downloads sub-skills (ads-google 80 checks, ads-meta 50 checks, ads-creative, ads-budget, ads-landing) Command Center agent (recurring): 1. Set up as Claude Cowork recurring task or scheduled agent (1-5x daily) 2. Agent downloads `command-center-agent.skill.md` 3. Calls `get_dashboard` → finds strategy_card widgets 4. Calls `get_strategy_status` per card → finds pending ai_controlled tasks 5. Executes tasks using SharksAPI tools (analyze_pagespeed, create_wp_post, etc.) 6. Marks done via `update_strategy_task` 7. Reports summary. Uses A2A API only — no browser/Chrome needed. Blog writing: 1. User: "Write a blog post about referral marketing" 2. Agent downloads `blog-writer.skill.md` → follows phases: - Research topic online + via GSC/GA4 - Check existing posts to avoid duplicate topics - Find SILO links (service pages + related posts via list_wp_posts) - Write article with styled HTML comparison tables, JSON-LD schema - Generate featured image (AI tool) or suggest stock photo terms - Proofread via built-in checklist (grammar, links, SEO, no em-dashes) - Publish as WordPress draft via create_wp_post - If part of a strategy: mark task complete via update_strategy_task **Important:** if you omit the `password` field entirely from update_dashboard, the existing password is left unchanged. Use explicit `null` to remove it. ### Markdown widget — what's supported in `text_markdown` content The agent-authored `content` field on `text_markdown` widgets supports a practical subset of markdown for marketing plans, to-do lists, and notes: - Headings: `#`, `##`, `###` - Bullet lists: `- item` or `* item` - Numbered lists: `1. item` - **Task list checkboxes**: `- [ ] todo` (unchecked) and `- [x] done` (checked, strikethrough) - Bold: `**text**` - Italic: `*text*` - Inline code: `` `code` `` - Links: `[label](https://example.com)` — only http(s)/mailto/relative URLs (XSS-safe) - Blockquotes: `> quoted text` - Horizontal rule: `---` - Paragraphs (blank line separates) All HTML in the agent's content is escaped — `