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: trueto get a JWT, whenPOST /auth/token/refreshworks and when it is refused, and why an agent cannot sign up (reCAPTCHA). - The report lifecycle with People search: create a report with
fields(a name,@handleor phone plus facts), run search rounds, pick the accounts that are the person (skipping ones with a blockingbadReason), confirm, then wait viaGET /check/{reportId}or SSE (ping/follows/summary/confirmevents) and read the report. The deprecated classic per-network flow is mentioned only so that an agent does not use it. - Credits: creating a report (
POST /create) checks the credit, so402there means no report credits are left. Confirming does not spend one: the credit is spent the first time the owner reads the finished report. What403/401/409/422mean at each step, including a repeat confirm (409), and why confirm needs a real signed-in account (not a guest session). - Readiness: what
readyandgeneratedmean inGET /check/{reportId}, and that the AI summary is ready when the SSEsummaryevent reportsdone. Times in responses are in seconds. - Soft errors: sign-up, recovery and Google calls that return HTTP
200with afieldErrorin the body (sign-in bad credentials are a401). - Guardrails: keep credentials out of logs, only create/confirm a report the user asked for, let the user pick the accounts before confirming.
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.