Skip to main content

SocialProfiler API skill for AI agents

The SocialProfiler API skill is a single Markdown file that teaches an AI agent (Claude Code, Claude Agent SDK, or any agent that loads SKILL.md files) how to use this API safely.

Download: SKILL.md

https://dashboard.socialprofiler.com/docs/agent-skills/socialprofiler-api/SKILL.md

What the skill covers​

  • Sign-in with token: true to get a JWT, and why an agent cannot sign up (reCAPTCHA).
  • The report lifecycle: create by username or by name+state, pick matched profiles (skipping ones with a blocking badReason), add them one at a time, confirm, then wait via /check or SSE (ping/follows/summary/confirm events).
  • The paywall: creating a report (POST /create) spends the credit check — 402 there means no report credits left; what 403/401/409 mean at each step (including a repeat confirm, which returns 409); and why confirm needs a real signed-in account (not a guest session).
  • Soft errors: auth calls that return HTTP 200 with "status": "error" in the body.
  • Guardrails: keep credentials out of logs, only create/confirm a report the user asked for, let the user pick the profiles before confirming (confirmation is permanent).

Install​

Claude Code​

Download the file into a skills folder, either for your user or for one project:

# user-wide
mkdir -p ~/.claude/skills/socialprofiler-api
curl -fsSL https://dashboard.socialprofiler.com/docs/agent-skills/socialprofiler-api/SKILL.md \
  -o ~/.claude/skills/socialprofiler-api/SKILL.md

# or per project
mkdir -p .claude/skills/socialprofiler-api
curl -fsSL https://dashboard.socialprofiler.com/docs/agent-skills/socialprofiler-api/SKILL.md \
  -o .claude/skills/socialprofiler-api/SKILL.md

Restart the session. The agent loads the skill when a task mentions SocialProfiler or a profile analysis report.

Other agents​

Put the file's content in the agent's system prompt or tool instructions. It is plain Markdown with a short YAML header (name, description).

Credentials​

The skill expects the account email and password in environment variables:

export SP_EMAIL="you@example.com"
export SP_PASSWORD="..."

Use a dedicated account for agent work, so its report credits and history are separate from your own.

Keeping it current​

The skill describes the same API as the API Reference. If a call in the skill and the reference disagree, the reference is correct. Please tell support@socialprofiler.com.