Docs index

REST examples

Copy-paste API examples for common workflows.

Context guidance: Use when an agent needs concrete curl/request/response examples.

Examples

Structured request and response examples are available in /docs/examples.json.

Credit summary

Inspect the shared account credit pool, current API key usage, active search rate card, and billing semantics.

curl -X GET "https://api.supercarl.ai/api/v1/credits?range=30d" \
  -H "X-API-Key: <YOUR_API_KEY>"

Communication capabilities

Inspect which outbound channels are currently available for the acting user and target.

curl -X POST https://api.supercarl.ai/api/v1/communications/capabilities \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "x_profile_url": "https://x.com/benkeighran"
  }'

LinkedIn durable draft

Save an MCP-session outreach draft without sending. Link macros are expanded before the draft is returned and stored for review.

curl -X POST https://api.supercarl.ai/api/v1/communications \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "draft",
    "channel": "linkedin_send_message",
    "agent_session_id": "agent_session_uuid",
    "linkedin_profile_url": "https://www.linkedin.com/in/target-person/",
    "message": "Worth connecting on this? [JoinLink]"
  }'

X dry-run send

Create a dry-run X communication record and inspect it later through the status endpoint or SSE stream.

curl -X POST https://api.supercarl.ai/api/v1/communications \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "x_send_message",
    "x_profile_url": "https://x.com/benkeighran",
    "message": "Quick note from Super Carl.",
    "dry_run": true
  }'

LinkedIn lookup

Lookup a profile by LinkedIn username or full LinkedIn profile URL.

curl -X POST https://api.supercarl.ai/api/v1/search/people \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "linkedin_profile_url": "https://www.linkedin.com/in/reidhoffman/"
  }'

Profile chunks (cached)

Fetch cached profile chunks without refreshing.

curl -X GET https://api.supercarl.ai/api/v1/profiles/user_123/chunks?posts_limit=10 \
  -H "X-API-Key: <YOUR_API_KEY>"

Profile text

Fetch profile text ready for LLM embeddings.

curl -X GET https://api.supercarl.ai/api/v1/profiles/user_123/text?mode=full&posts_limit=5 \
  -H "X-API-Key: <YOUR_API_KEY>"

Description search (auto-translated)

Run a natural language description that is auto-translated into AdvancedFilters.

curl -X POST https://api.supercarl.ai/api/v1/search/people \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "VP of Sales at mid-size companies in San Francisco",
    "limit": 10,
    "offset": 0
  }'

Full people search

Run a full search with explicit AdvancedFilters and inline evidence_text for evaluator-friendly matching context.

curl -X POST https://api.supercarl.ai/api/v1/search/people \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Head of Growth in New York",
    "limit": 10,
    "offset": 0,
    "include_evidence_text": true,
    "evidence_text_mode": "full",
    "evidence_posts_limit": 5,
    "filters": {
      "job_titles": {
        "include": ["Head of Growth"],
        "exclude": [],
        "mode": "must",
        "exact": false,
        "current_only": true
      },
      "locations": {
        "include": ["New York, NY"],
        "exclude": [],
        "radius_miles": 25,
        "strict": false,
        "scope": "current"
      }
    }
  }'

Social proximity detail

Inspect authenticated score breakdown, evidence, connector paths, and LinkedIn mutual research status for one target.

curl -X GET https://api.supercarl.ai/users/<TARGET_USER_ID>/social-proximity \
  -H "Authorization: Bearer <JWT_TOKEN>"

Preview search

Run a lightweight preview search (auto-translated description, not enrichable).

Enrich search results

Re-run a previous search_id and enrich the current page of results. Add target_user_id if you only want one user.

Company search preview

Search companies in detailed mode with inline evidence_text for downstream ranking or eval workflows.

People search joined to company search

Use a company search_id as a people-search filter (include or exclude).

Profile snapshot

Fetch a profile snapshot by user id.

Machine-readable JSON