Docs

Everything an agent needs to call SwooshConnect: wire up a client, see what the six tools do, and connect a client's own account.

Get started

Get a key

Every call authenticates with one bearer key. Get a key, then wire it into whichever client you use below.

Get a keyManage keys

Your dashboard lives at swooshrank.com.

Claude Code

Claude Code

Terminal
claude mcp add --transport http swooshconnect https://swooshrank.com/api/mcp --header "Authorization: Bearer <your key>"
Codex

Codex

config.toml
[mcp_servers.swooshconnect]
url = "https://swooshrank.com/api/mcp"
bearer_token_env_var = "SWOOSHCONNECT_API_KEY"

Set SWOOSHCONNECT_API_KEY in your shell before starting Codex.

Cursor

Cursor

.cursor/mcp.json

.cursor/mcp.json
{
  "mcpServers": {
    "swooshconnect": {
      "url": "https://swooshrank.com/api/mcp",
      "headers": {
        "Authorization": "Bearer <your key>"
      }
    }
  }
}
Reference

The six tools

Every tool acts only on your own organization's connected accounts. The request and response bodies below are generated examples, not a real account's data.

connect_accountPOST /connect/accounts

Create a connect link

Create a single-use link for a customer's client to connect one of their social or Google Business accounts.

Request
{
  "provider": "google_business",
  "label": "string",
  "maxAccounts": 1
}
Response
{
  "data": {
    "connectUrl": "string",
    "expiresAt": "string",
    "provider": "google_business",
    "label": "string"
  },
  "summary": "string"
}
curl
curl -X POST "https://swooshrank.com/api/v1/connect/accounts" \
  -H "Authorization: Bearer <your key>" \
  -H "Content-Type: application/json" \
  -d '{"provider":"google_business","label":"string","maxAccounts":1}'
list_accountsGET /connect/accounts

List connected accounts

List every account connected so far, any pending connect invites, and the current billing position.

Response
{
  "data": {
    "accounts": [
      {
        "accountId": "string",
        "provider": "google_business",
        "label": "string",
        "name": "string",
        "status": "pending",
        "locked": true,
        "connectedAt": "string"
      }
    ],
    "pendingInvites": [
      {
        "id": "string",
        "label": "string",
        "provider": "google_business",
        "maxAccounts": 1,
        "expiresAt": "string"
      }
    ],
    "billing": {
      "connected": 1,
      "free": 1,
      "billable": 1,
      "needsPayment": true
    }
  },
  "summary": "string"
}
curl
curl "https://swooshrank.com/api/v1/connect/accounts" \
  -H "Authorization: Bearer <your key>"
create_postPOST /connect/accounts/{accountId}/posts

Publish a post

Publish a post (text, and optionally an image or a link) to a connected account.

Request
{
  "text": "string",
  "media": {
    "imageUrl": "https://example.com/photo.jpg"
  },
  "link": "https://example.com/photo.jpg"
}
Response
{
  "data": {
    "postId": "string",
    "permalink": "string"
  },
  "summary": "string"
}
curl
curl -X POST "https://swooshrank.com/api/v1/connect/accounts/{accountId}/posts" \
  -H "Authorization: Bearer <your key>" \
  -H "Content-Type: application/json" \
  -d '{"text":"string","media":{"imageUrl":"https://example.com/photo.jpg"},"link":"https://example.com/photo.jpg"}'
list_reviewsGET /connect/accounts/{accountId}/reviews

List reviews

List reviews left on a connected account, newest information first.

Response
{
  "data": {
    "reviews": [
      {
        "reviewId": "string",
        "author": "string",
        "rating": 1,
        "text": "string",
        "date": "string",
        "replied": true,
        "replyText": "string"
      }
    ],
    "nextCursor": "string",
    "aggregate": {
      "ratingValue": 1,
      "reviewCount": 1
    }
  },
  "summary": "string"
}
curl
curl "https://swooshrank.com/api/v1/connect/accounts/{accountId}/reviews" \
  -H "Authorization: Bearer <your key>"
reply_reviewPOST /connect/accounts/{accountId}/reviews/{reviewId}/reply

Reply to a review

Post a reply to one review on a connected account.

Request
{
  "text": "string"
}
Response
{
  "data": {
    "repliedAt": "string"
  },
  "summary": "string"
}
curl
curl -X POST "https://swooshrank.com/api/v1/connect/accounts/{accountId}/reviews/{reviewId}/reply" \
  -H "Authorization: Bearer <your key>" \
  -H "Content-Type: application/json" \
  -d '{"text":"string"}'
get_insightsGET /connect/accounts/{accountId}/insights

Get insights

Get performance metrics for a connected account over a recent date range.

Response
{
  "data": {
    "range": {
      "startDate": "string",
      "endDate": "string"
    },
    "metrics": [
      {
        "key": "string",
        "label": "string",
        "total": 1,
        "points": [
          {
            "date": "string",
            "value": 1
          }
        ]
      }
    ]
  },
  "summary": "string"
}
curl
curl "https://swooshrank.com/api/v1/connect/accounts/{accountId}/insights" \
  -H "Authorization: Bearer <your key>"
Flow

The connect link

Connecting a client's account is a link, not a form you build.

  1. connect_account

    Call connect_account with the provider and a label naming the client. It returns a one-time link.

  2. Send the link

    Send that link to your client — by email, chat, however you already reach them.

  3. Two screens

    Your client opens it and sees a short interstitial naming SwooshConnect, then the platform's own consent screen. A SwooshRank product. That is why the screen names SwooshRank, not SwooshConnect.

  4. Pick the accounts

    If the grant exposes several accounts, your client picks which ones to connect, and each account they choose counts.

  5. list_accounts

    Call list_accounts to see what they connected, and any invite still pending.

Billing: $1 a month per connected account. You pay for what you connect. Nothing else.

Reference

Errors

Every failure carries one of these stable codes — never a raw provider error or a stack trace.

unauthorized
The API key is missing, invalid, or revoked.
invalid_input
The request body or parameters failed validation.
not_found
The account, review, or post referenced doesn't exist for your organization.
not_supported
The action isn't available on this platform.
payment_required
The organization needs an active subscription to connect another account.
subscription_inactive
The subscription isn't active; billable accounts are locked until it is.
provider_auth
The platform no longer accepts the stored authorization — reconnect the account.
provider_permission
The connected account lacks a permission this action needs on the platform.
rate_limited
Too many requests; retry after the interval in the response.
provider_error
The platform returned an error.
transient
A temporary failure on the platform's side — retry.
Reference

Rate limits

Limits are per key, not per organization and not per platform.

A request over the limit answers 429, carrying three headers that describe it: X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.

Reference

OpenAPI + MCP

The same schemas that validate every request generate this document — nothing here is written twice.

Full spec: OpenAPI (this host) or the live document.

MCP endpoint: https://swooshrank.com/api/mcp

REST base: https://swooshrank.com/api/v1

Consent

Consent screens

Your client sees two screens before anything connects: a short interstitial naming SwooshConnect, then the platform's own consent screen, which names SwooshRank. Nothing connects until they approve there — SwooshConnect never sees a password, and the grant is theirs to revoke on the platform at any time.