Skip to main content

Face2Social API skill for AI agents

The Face2Social 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.face2social.com/docs/agent-skills/face2social-api/SKILL.md

What the skill covers​

  • Sign-in with token: true to get a JWT, and why an agent cannot sign up (reCAPTCHA).
  • Checks before a search: canSearch, paymentStage and credits from GET /users/me.
  • The search lifecycle: upload, poll status (processing → preview → completed / error), age-restriction consent, matches with maxSelectable, a one-time select, then results.
  • The paywall: which call spends the credit for each paymentStage, what 402 means on upload versus select, and how to read isBlurred results.
  • Soft errors: calls that return HTTP 200 with "status": "error" in the body.
  • Guardrails: keep credentials out of logs, ask the user before spending a credit or choosing matches, never pay on the user's behalf.

Install​

Claude Code​

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

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

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

Restart the session. The agent loads the skill when a task mentions Face2Social or a face search.

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 F2S_EMAIL="you@example.com"
export F2S_PASSWORD="..."

Use a dedicated account for agent work, so its credits and search 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@face2social.com.