Sharksapi.AI - AI Agent API

STEP 1: Register Your Agent

Each agent_name + agent_type combination is unique. Registering with the same name returns your existing agent (login).

curl -X POST https://sharksapi.ai/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "My Claude Agent",
    "agent_type": "custom"
  }'

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,
  "client_id": "agent_abc123xyz...",
  "note": "Use your existing client_secret to get a token"
}

Lost your secret? Rotate it:

curl -X POST https://sharksapi.ai/api/v1/agents/{agent_id}/rotate-secret \
  -H "Content-Type: application/json" \
  -d '{"client_id": "agent_abc123xyz..."}'

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}

STEP 3: Use API

Make API requests with your access token:

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

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

AI agents can connect to Google Analytics 4, Google Search Console, Google Calendar, Google Drive, Gmail, and Notion. The account owner authorizes the connection once, then the agent can use it.

Supported OAuth services: ga4, gsc, google_calendar, google_drive, gmail, notion

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:

1. Share the direct_oauth_url from the response with the account owner
2. Owner clicks link and authorizes Google Analytics access
3. Connection is created automatically
4. 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_calendar", "notion"],
    "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"

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": "My SEO Agent", "agent_type": "custom"}'

# 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

# Sales & CRM
GET /api/v1/sales/summary                  Sales overview
GET /api/v1/sales/pipedrive/deals          Pipedrive deals
GET /api/v1/sales/pipedrive/contacts       Pipedrive contacts
GET /api/v1/sales/merit/invoices           Merit Aktiva invoices
GET /api/v1/sales/merit/customers          Merit Aktiva customers
GET /api/v1/sales/pipedrive/organizations  Pipedrive organizations
GET /api/v1/sales/pandadoc/documents       PandaDoc documents
GET /api/v1/sales/simplbooks/invoices      SimplBooks invoices
GET /api/v1/sales/procountor/invoices      Procountor invoices
GET /api/v1/sales/lemonsoft/invoices       Lemonsoft invoices
GET /api/v1/sales/dynamics/invoices        Dynamics 365 invoices
GET /api/v1/sales/sap/invoices             SAP Business One invoices
GET /api/v1/sales/fortnox/invoices         Fortnox invoices
GET /api/v1/sales/s4hana/invoices          SAP S/4HANA invoices
GET /api/v1/sales/monitor/orders           Monitor ERP orders
GET /api/v1/sales/economic/invoices        e-conomic invoices
GET /api/v1/sales/superoffice/contacts     SuperOffice contacts
GET /api/v1/sales/tripletex/invoices       Tripletex invoices
GET /api/v1/sales/visma/invoices           Visma Net invoices
GET /api/v1/sales/xero/invoices            Xero invoices
GET /api/v1/sales/sage/invoices            Sage invoices
GET /api/v1/sales/quickbooks/invoices      QuickBooks invoices
GET /api/v1/sales/wise/balances            Wise account balances

# Office & Productivity
GET /api/v1/office/calendar/events         Google Calendar events
GET /api/v1/office/emails                  Gmail inbox
POST /api/v1/office/emails/send            Send email via Gmail
GET /api/v1/office/documents               Google Drive files
GET /api/v1/office/notion/databases        Notion databases

# 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