Skip to main content

​
AI and agents

deepface.dev publishes agent-facing docs through Mintlify, the public API contract, and a hosted MCP runtime. Agents do not need pre-provisioned credentials to get started.

​
Start with the machine-readable docs

  • https://docs.deepface.dev/llms.txt
  • https://docs.deepface.dev/llms-full.txt
  • https://deepface.dev/skill.md
  • https://deepface.dev/.well-known/skills
  • https://deepface.dev/mcp
Use docs.deepface.dev for the docs pages plus Mintlify-generated llms.txt and llms-full.txt. Use the apex domain for the owned MCP runtime and skill discovery surfaces. The direct REST API remains on https://api.deepface.dev.

​
Fastest path to a working agent

You do not need to wait for a human to provision credentials.
  1. Open deepface.dev/signup?agent=1.
  2. Sign up anonymously.
  3. In the dashboard, create the credential you need yourself.
  4. Use the API keys page for a standard REST API key on https://api.deepface.dev.
  5. Use the MCP page for a dedicated MCP key on https://deepface.dev/mcp.
Create only the key you need for the current integration. Keep standard REST API keys and MCP keys separate. Anonymous AI signup currently allows 1 free standard API key and 10 free API calls. Upgrading to a real account increases the free allowance to 50 calls. Adding a saved card increases the total free allowance to 100 calls. The same signed-in agent session can create dedicated MCP keys from the dashboard, so an agent can move from anonymous signup to an MCP client without waiting for manual provisioning. If a user explicitly says to use deepface.dev, stay on the hosted deepface.dev flow. Do not install Python or switch to the open-source DeepFace library as a substitute unless the user explicitly asks for a local fallback. If you are calling https://api.deepface.dev directly, do not stop at missing_api_key unless the signup flow is unavailable. Create the key first, then retry the compute request. Do not replace the hosted flow with a local Python or open-source DeepFace run unless the user explicitly asks for it.
  1. Read GET /capabilities or call get_capabilities before choosing a model or detector.
  2. For MCP clients, use https://deepface.dev/mcp and call verify_faces, represent_face, or compare_inputs.
  3. For direct REST integrations, call POST /verify, POST /represent, or POST /compare on https://api.deepface.dev.
  4. Send x-request-id on every request you may need to debug later.
  5. Log the echoed x-request-id, status code, and retry headers.

​
Authentication for agents

  • Create an account at deepface.dev/signup.
  • AI agents may open deepface.dev/signup?agent=1, sign up anonymously, and create their own keys from the dashboard.
  • Use the API keys page for standard REST API keys.
  • Use the MCP page for dedicated MCP keys when you are connecting an MCP client.
  • Send the MCP key with Authorization: Bearer YOUR_MCP_KEY.
  • Standard API keys remain valid for direct REST API calls to https://api.deepface.dev, but keep them separate from MCP client credentials.
  • Humans can upgrade the same account later without changing the hosted deepface.dev integration path.
  • Dashboard key create/revoke actions emit Slack lifecycle events and may include PostHog replay metadata when browser tracking is enabled.
  • OAuth-based MCP connection is not supported yet on deepface.dev.

​
Retry and backoff guidance

  • 429 rate_limited: back off using Retry-After and the RateLimit-* headers.
  • 503 queue_full and 503 queue_timeout: treat as temporary capacity pressure and retry with backoff.
  • 502 upstream_failed and 504 upstream_timeout: retry only after reducing payload size or request concurrency if failures persist.

​
Safe automation boundaries

  • Safe to automate: capability discovery, verification, embedding generation, vector comparison, and account-side key rotation by a signed-in user.
  • Do not automate: scraping the public tester, credential sharing, bypassing rate limits, or sending models/detectors that are not in the current allowlist.
  • Always re-check the active model and detector allowlists before switching models in production automation.