# SharksAPI.AI — Agent Advertised Interfaces (AAIF)

> Version: 2.2.0 | Protocol: A2A v1.0 + MCP 2024-11-05 | Updated: 2026-05-20

SharksAPI.AI is an AI Agent API Platform exposing 430+ tools across marketing, sales, ops, and management. It supports two agent protocol surfaces simultaneously:

- **A2A v1.0** — Google Agent-to-Agent protocol at `POST /a2a`
- **MCP Streamable HTTP** — Model Context Protocol at `POST /mcp`
- **ChatGPT MCP connector** — OpenAI-compatible `search`/`fetch` profile at `POST /mcp/chatgpt`

---

## Overview

| Property | Value |
|---|---|
| Platform name | SharksAPI.AI |
| Base URL | `https://sharksapi.ai` |
| A2A endpoint | `POST https://sharksapi.ai/a2a` |
| MCP endpoint | `POST https://sharksapi.ai/mcp` |
| ChatGPT MCP endpoint | `POST https://sharksapi.ai/mcp/chatgpt` |
| Agent Card | `GET https://sharksapi.ai/.well-known/agent.json` |
| MCP Server Card | `GET https://sharksapi.ai/.well-known/mcp.json` |
| OAuth metadata | `GET https://sharksapi.ai/.well-known/oauth-authorization-server` |
| Tool count | 430+ tools across 20 tool classes |
| Skill count | 44 skills across 3 plugin packages |
| A2A protocol version | 1.0 |
| MCP protocol version | 2024-11-05 |

---

## Authentication

SharksAPI supports two OAuth 2.1 grant types depending on the surface:

## Endpoint Discipline For Agents

Do not guess endpoint paths. Use the exact URLs in this document.

| Goal | Correct interface | Endpoint |
|---|---|---|
| Register an autonomous A2A agent | REST | `POST https://sharksapi.ai/api/v1/agents/register` |
| Exchange agent credentials for a Bearer token | OAuth 2.1 client credentials | `POST https://sharksapi.ai/oauth/token` |
| Connect OAuth services such as GA4, GSC, Facebook, LinkedIn, Google Ads, Gmail, Notion | REST connection API | `POST https://sharksapi.ai/api/v1/agents/{agent_id}/connections/init` or `init-bulk` |
| Store API-key credentials such as Pipedrive, Bing, Stripe | REST connection API | `POST https://sharksapi.ai/api/v1/agents/{agent_id}/connections/store-credentials` |
| Check or finish a connection | REST connection API | `GET /api/v1/agents/{agent_id}/connections/{service}/status`, `PUT /api/v1/agents/{agent_id}/connections/{service}/configure` |
| Send a natural-language A2A task | A2A v1.0 | `POST https://sharksapi.ai/a2a` |
| Call a specific SharksAPI tool by name | Legacy direct A2A tool call | `POST https://sharksapi.ai/api/v1/a2a` |
| Use normal ChatGPT Apps/Connectors | ChatGPT MCP profile | `POST https://sharksapi.ai/mcp/chatgpt` |
| Use full MCP tools in Claude, Cursor, ChatGPT Developer Mode, or other full MCP clients | MCP Streamable HTTP | `POST https://sharksapi.ai/mcp/{botType}` |

Invalid examples: do not call `/api/v1/store-credentials`, `/api/v1/credentials`, `/api/v1/connections/store`, or invented variants. If a request fails with 404, re-check this table instead of trying random paths.

### A2A: OAuth 2.1 Client Credentials (machine-to-machine)

Used by agents integrating via `POST /a2a`.

1. **Register your agent** (one-time, no approval needed):
   ```
   POST https://sharksapi.ai/api/v1/agents/register
   Content-Type: application/json

   {
     "agent_name": "my-agent",
     "agent_type": "managementbot",
     "owner_email": "you@example.com"
   }
   ```
   Response: `{ "client_id": "...", "client_secret": "..." }`

2. **Exchange for a Bearer token** (valid 1 year):
   ```
   POST https://sharksapi.ai/oauth/token
   Content-Type: application/x-www-form-urlencoded

   grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET
   ```
   Response: `{ "access_token": "...", "token_type": "bearer", "expires_in": 31536000 }`

3. **Call A2A endpoint** with `Authorization: Bearer <token>`.

### Connection Setup Uses The REST Connection API

Connection setup is not performed through `/a2a` and not through MCP `tools/call`. Use the REST endpoints below with the same agent Bearer token.

#### OAuth services: human login required

Use this for Google Analytics, Search Console, Google Ads, Facebook, Instagram, Meta Ads, LinkedIn, Gmail, Google Drive, Google Calendar, Microsoft, Notion, and similar providers:

```http
POST https://sharksapi.ai/api/v1/agents/{agent_id}/connections/init
Authorization: Bearer <token>
Content-Type: application/json

{"service":"ga4","callback_email":"owner@example.com"}
```

The response includes `authorization_url` / `direct_oauth_url`. The agent must show that URL to the human owner. The human opens it in a browser, signs into the provider, and clicks Allow. The agent must not try to fetch, follow, automate, or complete OAuth URLs itself.

After authorization:

```http
GET https://sharksapi.ai/api/v1/agents/{agent_id}/connections/{service}/status
Authorization: Bearer <token>
```

If `needs_configuration` is true, call:

```http
PUT https://sharksapi.ai/api/v1/agents/{agent_id}/connections/{service}/configure
Authorization: Bearer <token>
Content-Type: application/json

{"property_id":"123456789"}
```

Use the metadata field appropriate to the service, for example `property_id` for `ga4`, `site_url` for `gsc`/`bing`, `page_id` for `facebook`, `organization_urn` for `linkedin`, `ad_account_id` for `meta_ads`, `customer_id` for `google_ads`, or `domain` for `pipedrive`.

#### API-key services: store credentials directly

```http
POST https://sharksapi.ai/api/v1/agents/{agent_id}/connections/store-credentials
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

{
  "service": "pipedrive",
  "credentials": { "api_key": "PIPEDRIVE_API_TOKEN" },
  "metadata": { "domain": "mycompany" }
}
```

For Pipedrive, `domain` is the subdomain before `.pipedrive.com`. Example: `https://acme.pipedrive.com` means `"domain": "acme"`. `api_key` is accepted as an alias and stored internally as `api_token`.

If Pipedrive credentials are saved without `metadata.domain`, the response is `needs_configuration`; finish with:

```http
PUT https://sharksapi.ai/api/v1/agents/{agent_id}/connections/pipedrive/configure
Authorization: Bearer <token>
Content-Type: application/json

{"domain":"mycompany"}
```

Only start calling Pipedrive tools after status is `connected`.

### MCP: OAuth 2.1 Authorization Code + PKCE (user-delegated)

Used by ChatGPT, Claude.ai, Cursor, and other MCP clients.

- Authorization endpoint: `https://sharksapi.ai/authorize`
- Token endpoint: `https://sharksapi.ai/oauth/token`
- Dynamic client registration: `https://sharksapi.ai/oauth/register` (RFC 7591)
- PKCE required: S256 only (`plain` is rejected per OAuth 2.1)
- Token endpoint auth method: `none` (public clients — no client_secret)
- Full OAuth 2.1 metadata: `https://sharksapi.ai/.well-known/oauth-authorization-server`

---

## Capabilities

| Capability | A2A v1.0 | MCP |
|---|---|---|
| Streaming | No | No (Streamable HTTP, non-streaming) |
| Push notifications | Yes (`callbackUrl` in `message/send`) | No |
| State transition history | No | — |
| Tool discovery | Via `/.well-known/agent.json` skills | Via `tools/list` |
| Project scoping | Agent-level (registered project) | Token-level (`project_id:N` ability) |
| Multi-bot routing | Via A2A skill categories | Via `/mcp/{botType}` URL variants |

---

## A2A v1.0 Interface

### Endpoint

```
POST https://sharksapi.ai/a2a
Content-Type: application/json
Authorization: Bearer <token>
```

Use `/a2a` when you want the platform to interpret a user-style message and create a Task v1.0 object. Use `/api/v1/a2a` only when you intentionally want the legacy direct tool-call shape with `params.tool` and `params.arguments`.

### Methods

#### `message/send` — Create and execute a task

Request:
```json
{
  "jsonrpc": "2.0",
  "id": "req-1",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [{ "type": "text", "text": "List available marketing tools" }],
      "messageId": "msg-uuid",
      "contextId": "ctx-uuid"
    },
    "callbackUrl": "https://your-agent.example.com/a2a-callback"
  }
}
```

Response (Task v1.0 object):
```json
{
  "jsonrpc": "2.0",
  "id": "req-1",
  "result": {
    "id": "task_AbCdEfGhIjKlMnOpQrSt",
    "contextId": "ctx-uuid",
    "status": {
      "state": "completed",
      "message": {
        "role": "agent",
        "parts": [{ "type": "text", "text": "Task completed successfully." }],
        "messageId": "agent-msg-uuid"
      },
      "timestamp": "2026-04-26T12:00:00+00:00"
    },
    "artifacts": [
      {
        "artifactId": "artifact-uuid",
        "parts": [{ "type": "text", "text": "{\"type\":\"skill_discovery\", \"available_tools\": 282}" }]
      }
    ],
    "metadata": { "protocol_version": "1.0", "context_id": "ctx-uuid" },
    "history": []
  }
}
```

#### `tasks/get` — Retrieve task status and result

Request:
```json
{
  "jsonrpc": "2.0",
  "id": "req-2",
  "method": "tasks/get",
  "params": { "id": "task_AbCdEfGhIjKlMnOpQrSt" }
}
```

Response: Same Task v1.0 object shape as `message/send`.

### Push Notifications

If `callbackUrl` is included in `message/send`, SharksAPI posts the full Task v1.0 object to that URL when the task reaches a terminal state (`completed` or `failed`):

```
POST https://your-agent.example.com/a2a-callback
Content-Type: application/json

{ "id": "task_...", "contextId": "...", "status": { "state": "completed", ... }, ... }
```

Delivery is fire-and-forget with a 5-second timeout. Failures are logged but do not affect the task result.

### Error Codes

| JSON-RPC Code | Meaning | HTTP Status |
|---|---|---|
| -32600 | Invalid Request (malformed JSON-RPC envelope) | 400 |
| -32601 | Method not found | 404 |
| -32602 | Invalid params (missing required fields) | 422 |
| -32001 | Unauthorized (missing/expired/rejected Bearer token) | 401 |
| -32003 | No project found — connect services first | 404 |

---

## MCP Interface

### Endpoint

```
POST https://sharksapi.ai/mcp
Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>
```

ChatGPT standard Apps/Connectors should use the OpenAI-compatible endpoint:

```
POST https://sharksapi.ai/mcp/chatgpt
Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>
```

This endpoint exposes `search` and `fetch`, which ChatGPT validates during connection setup. Use the bot-scoped URLs below only for ChatGPT Developer Mode/full MCP, Claude, Cursor, or other full MCP clients.

Bot-scoped variants (smaller tool sets):
- `https://sharksapi.ai/mcp/managementbot` — all 430+ tools
- `https://sharksapi.ai/mcp/marketingbot` — marketing + analytics + SEO
- `https://sharksapi.ai/mcp/salesbot` — CRM, ERP, accounting, payments
- `https://sharksapi.ai/mcp/opsagent` — email, calendar, HR, productivity

### Key Methods

- `tools/list` — returns all tools for the authenticated project
- `tools/call` — executes a named tool with arguments
- `initialize` — MCP handshake (protocolVersion: "2024-11-05")

---

## Skills (44 total across 3 plugin packages)

### Package 1: SharksAPI Native (8 skills)

| Skill ID | Name | Triggers |
|---|---|---|
| `seo_audit` | SEO / GEO Audit & Strategy | seo audit, geo audit, search optimization |
| `content_strategy` | Content Strategy | content strategy, blog plan, content calendar |
| `social_media_plan` | Social Media Plan | social media plan, facebook plan, linkedin plan |
| `conversion_optimization` | Conversion Optimization | cro audit, improve conversions, ux audit |
| `weekly_seo_review` | Weekly SEO & Traffic Review | weekly seo review, weekly report |
| `paid_ads_strategy` | Paid Ads Audit & Strategy | ads audit, google ads audit, meta ads audit |
| `command_center_agent` | Command Center Agent | check command center, execute strategy |
| `blog_writer` | Blog Writer | write blog, blog article, publish article |

### Package 2: Ads Skills (6 skills, from claude-ads MIT)

| Skill ID | Name |
|---|---|
| `ads_google_deep` | Google Ads Deep Audit (80 checks) |
| `ads_meta_deep` | Meta Ads Deep Audit (50 checks) |
| `ads_creative` | Ad Creative Quality Audit |
| `ads_budget` | Ad Budget Optimization |
| `ads_landing` | Landing Page Conversion Audit |
| `ads_plan` | Ads Strategic Plan |

### Package 3: SEO/GEO Protocol Skills (30 skills, from seo-geo-claude-skills Apache 2.0)

Categories: research (4), build (4), optimize (4), monitor (4), cross-cutting (3),
sales (5), ops (5), cross-platform (1).

All 44 skill `.skill.md` files served at: `https://sharksapi.ai/skills/{skill-id}.skill.md`

Skills endpoint (authenticated): `GET https://sharksapi.ai/api/v1/a2a/skills`

---

## Integration Examples

### Example 1: A2A — Discover available tools

```bash
# Register agent
curl -X POST https://sharksapi.ai/api/v1/agents/register \
  -H 'Content-Type: application/json' \
  -d '{"agent_name":"my-agent","agent_type":"managementbot","owner_email":"you@example.com"}'

# Get token
TOKEN=$(curl -s -X POST https://sharksapi.ai/oauth/token \
  -d 'grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET' \
  | jq -r .access_token)

# Send message/send via A2A v1.0
curl -X POST https://sharksapi.ai/a2a \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"type": "text", "text": "List available tools"}]
      }
    }
  }'
```

### Example 2: A2A — Get task status

```bash
curl -X POST https://sharksapi.ai/a2a \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "tasks/get",
    "params": { "id": "task_AbCdEfGhIjKlMnOpQrSt" }
  }'
```

### Example 3: REST — Connect Pipedrive For A2A/Sales Tools

```bash
curl -X POST "https://sharksapi.ai/api/v1/agents/$AGENT_ID/connections/store-credentials" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "service": "pipedrive",
    "credentials": {"api_key": "PIPEDRIVE_API_TOKEN"},
    "metadata": {"domain": "acme"}
  }'

curl "https://sharksapi.ai/api/v1/agents/$AGENT_ID/connections/pipedrive/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Accept: application/json'
```

### Example 4: MCP — List tools (Streamable HTTP)

```bash
curl -X POST https://sharksapi.ai/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

### Example 5: ChatGPT MCP — List search/fetch tools

```bash
curl -X POST https://sharksapi.ai/mcp/chatgpt \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

---

## Integrations

SharksAPI connects to 110+ external services. Key categories:

**Analytics & Marketing:** Google Analytics 4, Google Search Console, Bing Webmaster Tools, Microsoft Clarity, Google Ads, Meta Ads, Google Business Profile, Google Alerts, GA4 Service Account

**Social Media:** Facebook, LinkedIn, Instagram, Twitter/X, TikTok, YouTube, Bluesky, Buffer, Hootsuite

**CRM & Sales:** Pipedrive, HubSpot, Salesforce, SuperOffice, Zoho CRM

**ERP & Accounting (European focus):** Merit Aktiva (EST), SimplBooks, Procountor (FIN), Fortnox (SWE), Visma (NOR), e-conomic (DNK), Monitor ERP, SAP S/4HANA, Dynamics 365, Sage, Xero, QuickBooks, FreshBooks, Wave, Moneybird, Bexio, Lexware, FattureInCloud, Pennylane

**Payments & Banking:** Wise, GoCardless, Revolut, Qonto, Stripe, Mollie, LHV Bank (EST, mTLS)

**Productivity & HR:** Google Calendar, Google Drive, Notion, HiBob, Personio, Deel, Greenhouse, Microsoft Teams, Slack, ServiceNow, Azure DevOps

**SEO & Content:** SeoShark (integrated), DataForSEO, Serper, WordPress API, PageSpeed Insights

Full integrations catalog: `GET https://sharksapi.ai/api/v1/agents/integrations`

---

## Discovery Endpoints

| Resource | URL |
|---|---|
| This document | `https://sharksapi.ai/AGENTS.md` |
| Agent Card (A2A v1.0) | `https://sharksapi.ai/.well-known/agent.json` |
| MCP Server Card | `https://sharksapi.ai/.well-known/mcp.json` |
| OAuth 2.1 metadata | `https://sharksapi.ai/.well-known/oauth-authorization-server` |
| OpenAPI spec | `https://sharksapi.ai/api/openapi.json` |
| LLMs.txt | `https://sharksapi.ai/llms.txt` |
| Skills catalog | `https://sharksapi.ai/api/v1/a2a/skills` |
| Integrations catalog | `https://sharksapi.ai/api/v1/agents/integrations` |
| Agent registration | `POST https://sharksapi.ai/api/v1/agents/register` |