> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deepface.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# AI and agents

> Machine-readable docs, anonymous agent signup, self-serve REST and MCP keys, and MCP access on https://deepface.dev/mcp.

# 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](https://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.

## Recommended agent workflow

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](https://deepface.dev/signup).
* AI agents may open [deepface.dev/signup?agent=1](https://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.
* MCP compute image inputs may be raw base64, `data:image/...` strings, or
  public `https://` image URLs. Non-HTTPS, localhost, private-network,
  metadata, and `.local` URLs are rejected before compute forwarding.
* MCP resource and search failures return stable public error codes instead of
  raw provider or filesystem details. Keep `x-request-id` and MCP audit entries
  when debugging a failed client run.
* 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`, `502 upstream_response_too_large`, and `504
  upstream_timeout`: retry only after reducing payload size, compare target
  count, 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.