# 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

## 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: 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"}
- 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.

## 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"}}

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]
- google_ads — Google Ads (campaigns, keywords, bidding)
- google_business — Google Business Profile (reviews, local SEO)
- 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)

## Error Handling

- 401: Invalid or expired token. Get a new one from /oauth/token.
- 403: Missing required connection or capability.
- 404: Agent or resource not found.
- 422: Invalid parameters. Check the tool's inputSchema.
- 429: Rate limited. Wait and retry.

Tool call errors return: {"error": {"code": -32000, "message": "description"}}
Connection-required errors include instructions on how to connect the service.

## Important Notes

- You never handle OAuth tokens or secrets directly. SharksAPI stores and refreshes all credentials.
- OAuth services require the human owner to authorize via browser. You only provide the URL.
- After OAuth, the owner selects which account/property to use (GA4 property, Facebook Page, etc.).
- API-key services can be connected without human interaction if you have the key.
- All API calls are logged and can be revoked by the owner at any time.
- Rate limits apply per agent. Check response headers for limit info.
- The /documentation endpoint returns tools filtered by your actual connected services.