SwooshConnect

Docs

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

On this page
Get started

Get a key

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

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 30 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,
      "frozen": true,
      "complimentary": 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>"
inbox_listGET /connect/accounts/{accountId}/inbox

List inbox items

List everything that has come in on a connected account — reviews and comments — newest first.

Response
{
  "data": {
    "items": [
      {
        "id": "string",
        "channel": "review",
        "author": "string",
        "text": "string",
        "createdAt": "string",
        "rating": 1,
        "replied": true,
        "replyText": "string"
      }
    ],
    "nextCursor": "string",
    "aggregate": {
      "ratingValue": 1,
      "reviewCount": 1
    }
  },
  "summary": "string"
}
curl
curl "https://swooshrank.com/api/v1/connect/accounts/{accountId}/inbox" \
  -H "Authorization: Bearer <your key>"
inbox_replyPOST /connect/accounts/{accountId}/inbox/{itemId}/reply

Reply to an inbox item

Post a reply to one inbox item (a review or a comment) 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}/inbox/{itemId}/reply" \
  -H "Authorization: Bearer <your key>" \
  -H "Content-Type: application/json" \
  -d '{"text":"string"}'
calendar_upcomingGET /connect/accounts/{accountId}/calendar

List upcoming calendar events

List the owner's next events on a connected calendar, soonest first.

Response
{
  "data": {
    "items": [
      {
        "id": "string",
        "title": "string",
        "start": "string",
        "end": "string",
        "link": "string"
      }
    ]
  },
  "summary": "string"
}
curl
curl "https://swooshrank.com/api/v1/connect/accounts/{accountId}/calendar" \
  -H "Authorization: Bearer <your key>"
calendar_slotsGET /connect/accounts/{accountId}/calendar/slots

Find open calendar slots

Find open booking slots on a connected calendar over the next few days.

Response
{
  "data": {
    "slots": [
      {
        "start": "string",
        "end": "string"
      }
    ]
  },
  "summary": "string"
}
curl
curl "https://swooshrank.com/api/v1/connect/accounts/{accountId}/calendar/slots" \
  -H "Authorization: Bearer <your key>"
calendar_bookPOST /connect/accounts/{accountId}/calendar/book

Book a calendar appointment

Book a new appointment on the owner's real calendar. This changes their calendar.

Request
{
  "start": "2026-09-21T09:00:00.000Z",
  "end": "2026-09-21T09:00:00.000Z",
  "leadName": "string"
}
Response
{
  "data": {
    "id": "string",
    "start": "string",
    "end": "string",
    "link": "string"
  },
  "summary": "string"
}
curl
curl -X POST "https://swooshrank.com/api/v1/connect/accounts/{accountId}/calendar/book" \
  -H "Authorization: Bearer <your key>" \
  -H "Content-Type: application/json" \
  -d '{"start":"2026-09-21T09:00:00.000Z","end":"2026-09-21T09:00:00.000Z","leadName":"string"}'
calendar_movePOST /connect/accounts/{accountId}/calendar/{eventId}/move

Move a calendar appointment

Reschedule an existing appointment on the owner's real calendar. This changes their calendar.

Request
{
  "start": "2026-09-21T09:00:00.000Z",
  "end": "2026-09-21T09:00:00.000Z"
}
Response
{
  "data": {
    "id": "string",
    "start": "string",
    "end": "string",
    "link": "string"
  },
  "summary": "string"
}
curl
curl -X POST "https://swooshrank.com/api/v1/connect/accounts/{accountId}/calendar/{eventId}/move" \
  -H "Authorization: Bearer <your key>" \
  -H "Content-Type: application/json" \
  -d '{"start":"2026-09-21T09:00:00.000Z","end":"2026-09-21T09:00:00.000Z"}'
calendar_cancelPOST /connect/accounts/{accountId}/calendar/{eventId}/cancel

Cancel a calendar appointment

Cancel an existing appointment on the owner's real calendar. This changes their calendar.

Request
{}
Response
{
  "data": {
    "id": "string",
    "cancelled": true
  },
  "summary": "string"
}
curl
curl -X POST "https://swooshrank.com/api/v1/connect/accounts/{accountId}/calendar/{eventId}/cancel" \
  -H "Authorization: Bearer <your key>" \
  -H "Content-Type: application/json" \
  -d '{}'
customers_listGET /connect/accounts/{accountId}/customers

List customers

List the owner's contacts on a connected customer list.

Response
{
  "data": {
    "contacts": [
      {
        "name": "string",
        "emails": [
          "string"
        ],
        "phones": [
          "string"
        ]
      }
    ],
    "nextCursor": "string"
  },
  "summary": "string"
}
curl
curl "https://swooshrank.com/api/v1/connect/accounts/{accountId}/customers" \
  -H "Authorization: Bearer <your key>"
customers_findGET /connect/accounts/{accountId}/customers/find

Find a customer

Find one contact on a connected customer list by name, email, or phone.

Response
{
  "data": {
    "match": {
      "displayName": "string",
      "emails": [
        "string"
      ],
      "phones": [
        "string"
      ]
    }
  },
  "summary": "string"
}
curl
curl "https://swooshrank.com/api/v1/connect/accounts/{accountId}/customers/find" \
  -H "Authorization: Bearer <your key>"
agents_catalogGET /connect/agents/catalog

List agent templates

List the agent templates available to deploy.

Response
{
  "data": {
    "catalog": [
      {
        "id": "string",
        "name": "string",
        "description": "string",
        "version": "string",
        "tier": "free",
        "targets": [
          "supabase"
        ],
        "modules": [
          "inbox"
        ],
        "secrets": [
          {
            "name": "string",
            "label": "string",
            "options": [
              "string"
            ],
            "sensitive": true,
            "multiline": true
          }
        ],
        "functions": [
          "string"
        ],
        "schedule": {}
      }
    ]
  },
  "summary": "string"
}
curl
curl "https://swooshrank.com/api/v1/connect/agents/catalog" \
  -H "Authorization: Bearer <your key>"
agents_listGET /connect/agents

List agent deployments

List the agents already deployed for this organization.

Response
{
  "data": {
    "deployments": [
      {
        "id": "string",
        "templateId": "string",
        "templateVersion": "string",
        "runtimeTarget": "string",
        "status": "deploying",
        "lastError": "string",
        "createdAt": "string"
      }
    ]
  },
  "summary": "string"
}
curl
curl "https://swooshrank.com/api/v1/connect/agents" \
  -H "Authorization: Bearer <your key>"
agents_targetsGET /connect/agents/targets/{runtimeAccountId}

List agent deploy targets

List the projects an agent can be deployed onto for a connected runtime account.

Response
{
  "data": {
    "targets": [
      {
        "id": "string",
        "name": "string"
      }
    ]
  },
  "summary": "string"
}
curl
curl "https://swooshrank.com/api/v1/connect/agents/targets/{runtimeAccountId}" \
  -H "Authorization: Bearer <your key>"
agents_deployPOST /connect/agents

Deploy an agent

Deploy an agent template onto a connected runtime project. Deploying creates an API key for this agent; that key lets it reply and post on your connected accounts.

Request
{
  "templateId": "string",
  "runtimeAccountId": "3f2c9c9e-8f1a-4d2b-9b1e-2f7a6c1d0e55",
  "runtimeTarget": "string",
  "secrets": {},
  "aiAccountId": "3f2c9c9e-8f1a-4d2b-9b1e-2f7a6c1d0e55"
}
Response
{
  "data": {
    "id": "string",
    "templateId": "string",
    "templateVersion": "string",
    "runtimeTarget": "string",
    "status": "deploying",
    "lastError": "string",
    "createdAt": "string"
  },
  "summary": "string"
}
curl
curl -X POST "https://swooshrank.com/api/v1/connect/agents" \
  -H "Authorization: Bearer <your key>" \
  -H "Content-Type: application/json" \
  -d '{"templateId":"string","runtimeAccountId":"3f2c9c9e-8f1a-4d2b-9b1e-2f7a6c1d0e55","runtimeTarget":"string","secrets":{},"aiAccountId":"3f2c9c9e-8f1a-4d2b-9b1e-2f7a6c1d0e55"}'
agents_statusGET /connect/agents/{deploymentId}

Get agent deployment status

Get the current status of one agent deployment.

Response
{
  "data": {
    "id": "string",
    "templateId": "string",
    "templateVersion": "string",
    "runtimeTarget": "string",
    "status": "deploying",
    "lastError": "string",
    "createdAt": "string",
    "parts": [
      {
        "name": "string",
        "status": "string"
      }
    ]
  },
  "summary": "string"
}
curl
curl "https://swooshrank.com/api/v1/connect/agents/{deploymentId}" \
  -H "Authorization: Bearer <your key>"
agents_removeDELETE /connect/agents/{deploymentId}

Remove an agent deployment

Tear down an agent deployment and revoke its API key.

Response
{
  "data": {
    "removed": true
  },
  "summary": "string"
}
curl
curl -X DELETE "https://swooshrank.com/api/v1/connect/agents/{deploymentId}" \
  -H "Authorization: Bearer <your key>"
calls_numbersGET /connect/calls/numbers/{accountId}

List phone numbers

List the active phone numbers on a connected phone account — the caller ids a dialer campaign can use.

Response
{
  "data": {
    "numbers": [
      {
        "id": "string",
        "number": "string"
      }
    ]
  },
  "summary": "string"
}
curl
curl "https://swooshrank.com/api/v1/connect/calls/numbers/{accountId}" \
  -H "Authorization: Bearer <your key>"
dialer_campaignsGET /connect/calls/campaigns

List dialer campaigns

List this organization's dialer campaigns with their settings and how many contacts are pending, done, or on the do-not-call list.

Response
{
  "data": {
    "campaigns": [
      {
        "id": "string",
        "name": "string",
        "telnyxAccountId": "string",
        "fromNumber": "string",
        "lines": 1,
        "ringTimeoutSec": 1,
        "wrapUpSec": 1,
        "amd": "off",
        "voicemailAction": "hangup",
        "hoursStart": "string",
        "hoursEnd": "string",
        "timezone": "string",
        "maxAttempts": 1,
        "retryAfterMin": 1,
        "status": "active",
        "counts": {
          "pending": 1,
          "done": 1,
          "dnc": 1
        },
        "mode": "human",
        "aiMarketing": true,
        "maxCallsPerDay": 1,
        "aiSettings": {
          "businessName": "string",
          "reason": "string",
          "callbackNumber": "string",
          "transferTo": "string"
        }
      }
    ]
  },
  "summary": "string"
}
curl
curl "https://swooshrank.com/api/v1/connect/calls/campaigns" \
  -H "Authorization: Bearer <your key>"
dialer_save_campaignPOST /connect/calls/campaigns

Save a dialer campaign

Create a dialer campaign, or update one by id: caller id, lines per agent (1, 2, 3 or 5), ring timeout, wrap-up pause, calling hours and time zone, and retry rules. mode "human" (the default) is dialed only by a person on the dialer screen. mode "ai" is dialed only by our automated caller, only to contacts with recorded consent, within calling hours and the required daily limit (maxCallsPerDay, 1 to 500); it needs aiSettings with the business name and the reason for the call. A field left out keeps its saved value.

Request
{
  "id": "3f2c9c9e-8f1a-4d2b-9b1e-2f7a6c1d0e55",
  "name": "string",
  "accountId": "3f2c9c9e-8f1a-4d2b-9b1e-2f7a6c1d0e55",
  "telnyxAccountId": "3f2c9c9e-8f1a-4d2b-9b1e-2f7a6c1d0e55",
  "fromNumber": "string",
  "lines": 1,
  "ringTimeoutSec": 5,
  "wrapUpSec": 0,
  "amd": "off",
  "voicemailAction": "hangup",
  "hoursStart": "string",
  "hoursEnd": "string",
  "timezone": "string",
  "maxAttempts": 1,
  "retryAfterMin": 1,
  "status": "active",
  "mode": "human",
  "aiMarketing": true,
  "maxCallsPerDay": 1,
  "aiSettings": {
    "businessName": "string",
    "reason": "string",
    "callbackNumber": "string",
    "transferTo": "string"
  }
}
Response
{
  "data": {
    "id": "string",
    "name": "string",
    "telnyxAccountId": "string",
    "fromNumber": "string",
    "lines": 1,
    "ringTimeoutSec": 1,
    "wrapUpSec": 1,
    "amd": "off",
    "voicemailAction": "hangup",
    "hoursStart": "string",
    "hoursEnd": "string",
    "timezone": "string",
    "maxAttempts": 1,
    "retryAfterMin": 1,
    "status": "active",
    "counts": {
      "pending": 1,
      "done": 1,
      "dnc": 1
    },
    "mode": "human",
    "aiMarketing": true,
    "maxCallsPerDay": 1,
    "aiSettings": {
      "businessName": "string",
      "reason": "string",
      "callbackNumber": "string",
      "transferTo": "string"
    }
  },
  "summary": "string"
}
curl
curl -X POST "https://swooshrank.com/api/v1/connect/calls/campaigns" \
  -H "Authorization: Bearer <your key>" \
  -H "Content-Type: application/json" \
  -d '{"id":"3f2c9c9e-8f1a-4d2b-9b1e-2f7a6c1d0e55","name":"string","accountId":"3f2c9c9e-8f1a-4d2b-9b1e-2f7a6c1d0e55","telnyxAccountId":"3f2c9c9e-8f1a-4d2b-9b1e-2f7a6c1d0e55","fromNumber":"string","lines":1,"ringTimeoutSec":5,"wrapUpSec":0,"amd":"off","voicemailAction":"hangup","hoursStart":"string","hoursEnd":"string","timezone":"string","maxAttempts":1,"retryAfterMin":1,"status":"active","mode":"human","aiMarketing":true,"maxCallsPerDay":1,"aiSettings":{"businessName":"string","reason":"string","callbackNumber":"string","transferTo":"string"}}'
dialer_import_contactsPOST /connect/calls/campaigns/{campaignId}/contacts

Import dialer contacts

Add contacts to a dialer campaign, either as CSV text (name, phone, optional timezone, ai_consent, consent_source, consent_text, consent_at columns) or as rows. A row's consent to automated calls (aiConsent express or written) needs a consentSource and, when given, a past consentAt; a row that claims consent without them is imported with no consent and counted in consentRejected. Numbers on the do-not-call list, duplicates and invalid numbers are skipped and counted.

Request
{
  "csv": "string",
  "rows": [
    {
      "name": "string",
      "phone": "string",
      "timezone": "string",
      "aiConsent": "none",
      "consentSource": "string",
      "consentText": "string",
      "consentAt": "string"
    }
  ]
}
Response
{
  "data": {
    "added": 1,
    "duplicates": 1,
    "dnc": 1,
    "invalid": 1,
    "consentRejected": 1
  },
  "summary": "string"
}
curl
curl -X POST "https://swooshrank.com/api/v1/connect/calls/campaigns/{campaignId}/contacts" \
  -H "Authorization: Bearer <your key>" \
  -H "Content-Type: application/json" \
  -d '{"csv":"string","rows":[{"name":"string","phone":"string","timezone":"string","aiConsent":"none","consentSource":"string","consentText":"string","consentAt":"string"}]}'
dialer_add_dncPOST /connect/calls/dnc

Add a number to do-not-call

Add a phone number to this organization's do-not-call list. It is never dialed again from any campaign.

Request
{
  "phone": "string"
}
Response
{
  "data": {
    "ok": true
  },
  "summary": "string"
}
curl
curl -X POST "https://swooshrank.com/api/v1/connect/calls/dnc" \
  -H "Authorization: Bearer <your key>" \
  -H "Content-Type: application/json" \
  -d '{"phone":"string"}'
calls_logGET /connect/calls/log

List handled calls

List the calls our assistant handled on this organization's phone accounts: inbound calls it answered and outbound AI campaign calls, with the other party's number, the contact, the outcome (outbound only), consent, transfer, opt-out and summary. To poll: Start with an ISO `since` (e.g. now) and pass back `nextCursor`; each call then arrives exactly once, oldest end first, only after it ENDED and has been over for five minutes, so its outcome is final. nextCursor is the position of the last call returned ("<endedAt ISO>|<id>"), or null when nothing new arrived: keep your previous cursor then. At most limit calls per page (default 50, max 200). For a one-off look, without `since` you get a newest-first snapshot and calls may repeat between snapshots; it includes calls still in progress. The summary may arrive a few minutes after the call ends; poll again, with a snapshot or a since before that call's end, to pick it up.

Response
{
  "data": {
    "calls": [
      {
        "id": "string",
        "direction": "inbound",
        "campaignId": "string",
        "contactId": "string",
        "contactName": "string",
        "phone": "string",
        "startedAt": "string",
        "endedAt": "string",
        "outcome": "string",
        "consent": "yes",
        "transferred": true,
        "optedOut": true,
        "summary": "string"
      }
    ],
    "nextCursor": "string"
  },
  "summary": "string"
}
curl
curl "https://swooshrank.com/api/v1/connect/calls/log" \
  -H "Authorization: Bearer <your key>"
voice_settings_getGET /connect/calls/voice/{accountId}

Get receptionist settings

Get the AI receptionist settings for a connected phone account: whether it answers, the number it answers, the transfer number, business hours, greeting and instructions. settings is null when it was never set up.

Response
{
  "data": {
    "settings": {
      "accountId": "string",
      "enabled": true,
      "inboundNumber": "string",
      "transferTo": "string",
      "hoursStart": "string",
      "hoursEnd": "string",
      "timezone": "string",
      "greeting": "string",
      "instructions": "string",
      "assistantReady": true,
      "routingWarning": "string"
    }
  },
  "summary": "string"
}
curl
curl "https://swooshrank.com/api/v1/connect/calls/voice/{accountId}" \
  -H "Authorization: Bearer <your key>"
voice_settings_savePUT /connect/calls/voice/{accountId}

Save receptionist settings

Save the AI receptionist settings for a connected phone account. Enabling it routes the chosen number to the receptionist; disabling it routes the number back to where it rang before. routingWarning is set when a number could not be routed back and needs fixing on the phone account.

Response
{
  "data": {
    "accountId": "string",
    "enabled": true,
    "inboundNumber": "string",
    "transferTo": "string",
    "hoursStart": "string",
    "hoursEnd": "string",
    "timezone": "string",
    "greeting": "string",
    "instructions": "string",
    "assistantReady": true,
    "routingWarning": "string"
  },
  "summary": "string"
}
curl
curl -X PUT "https://swooshrank.com/api/v1/connect/calls/voice/{accountId}" \
  -H "Authorization: Bearer <your key>"
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
A payment method is needed, or paid accounts are paused until a renewal payment clears — the error's reason field says which.
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