API Documentation

Getting Started

The SocialSweep API is a REST API served over HTTPS. All routes use the /v1 prefix.

Base URL

https://api.socialsweep.ai/v1

Getting an API key

• Already have a SocialSweep account? Generate a key under Settings → Developers in the app.
• Building a partner integration and want a test key to evaluate the API? Email support@socialsweep.ai and we’ll set you up with a demo account.

Authentication

Authentication uses a simple API key passed as a Bearer token in the Authorization header. No OAuth flow is required. Keys start with ss_ak_ and are long-lived until rotated or revoked.

Using your API key

Authorization: Bearer ss_ak_YOUR_API_KEY

Quick test

curl -H "Authorization: Bearer ss_ak_YOUR_API_KEY" \
  https://api.socialsweep.ai/v1/me

Search

Search a network using natural language queries. This is the primary endpoint for mining a network.

curl -X POST https://api.socialsweep.ai/v1/search/people \
  -H "Authorization: Bearer ss_ak_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "software engineers in San Francisco",
    "limit": 10
  }'

{
  "results": [
    {
      "person": {
        "publicId": "abc-123-def",
        "fullName": "John Smith",
        "title": "Senior Software Engineer",
        "company": "Acme Corp",
        "location": "San Francisco, CA",
        "connections": [
          { "platform": "linkedin", "handle": "johnsmith" }
        ]
      },
      "matchScore": {
        "percentage": 87,
        "displayScore": 8.7,
        "grade": "excellent",
        "components": {
          "similarity": { "score": 0.85, "weight": 0.35 },
          "relationship": { "score": 0.92, "weight": 0.20 },
          "filterMatch": { "score": 1.0, "weight": 0.20 },
          "quality": { "score": 0.75, "weight": 0.10 },
          "queryContext": { "score": 0.80, "weight": 0.05 },
          "personalization": { "score": 0.60, "weight": 0.10 }
        }
      }
    }
  ],
  "total": 42,
  "processingTimeMs": 245,
  "pagination": { "limit": 10, "offset": 0 },
  "interpretation": {
    "originalQuery": "software engineers in San Francisco",
    "searchTerms": ["software", "engineer"],
    "intent": "find_people"
  }
}

Projects

Organize searches into projects for recruiting, sales, or research.

Conversations

Track multi-turn search conversations and their results.

Create message body

Imports

Import connections from various platforms to build a network graph.

Platform file uploads

Upload platform export files as multipart/form-data with a file field. Max 50 MB per file.

curl -X POST https://api.socialsweep.ai/v1/imports/linkedin/connections \
  -H "Authorization: Bearer ss_ak_YOUR_API_KEY" \
  -F "file=@Connections.csv"

CSV contact import (two-step)

For generic CSV files with contacts, use a preview → import flow.

Linked Accounts

Manage social platform accounts linked to a profile.

Link account body

OAuth Integrations

Connect email and contacts providers to automatically sync a network.

Supported providers

Profile & Anchor

The “anchor” is the Person entity that represents the account owner in the SocialSweep graph.

Update anchor body

Rate Limits

Requests that exceed the limit receive a 429 response.

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1709472000

Error Codes

All errors return a JSON object with error.code and error.message.

{
  "error": {
    "code": "INVALID_QUERY",
    "message": "Query cannot be empty"
  }
}

MCP Server

The SocialSweep MCP (Model Context Protocol) server lets AI assistants like Claude and Manus search a network on the user's behalf. Connect it once and your AI assistant can find people, run queries, and access the social graph.

{
  "mcpServers": {
    "socialsweep": {
      "url": "https://mcp.socialsweep.ai/sse",
      "headers": {
        "x-api-key": "ss_ak_YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "socialsweep": {
      "serverUrl": "https://mcp.socialsweep.ai/sse",
      "headers": {
        "x-api-key": "ss_ak_YOUR_API_KEY"
      }
    }
  }
}

Code Examples

Quick-start examples in popular languages.

import requests

API_KEY = "ss_ak_YOUR_API_KEY"
BASE = "https://api.socialsweep.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

resp = requests.post(
    f"{BASE}/search/people",
    headers=HEADERS,
    json={"query": "designers who freelance", "limit": 20},
)

for r in resp.json()["results"]:
    p = r["person"]
    s = r["matchScore"]["percentage"]
    print(f"{p['fullName']} - {p.get('title', 'N/A')} ({s}% match)")

const API_KEY = "ss_ak_YOUR_API_KEY";
const BASE = "https://api.socialsweep.ai/v1";

const res = await fetch(`${BASE}/search/people`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "engineers at YC companies",
    limit: 10,
  }),
});

const data = await res.json();
console.log(`Found ${data.total} people`);

Support

If you run into issues, contact us at support@socialsweep.ai with your request ID (from response headers), the endpoint and request body, and the full error response.