# AI and agents
Source: https://docs.deepface.dev/ai-agents

Machine-readable docs, email-first agent signup, self-serve REST and MCP keys, and MCP access on https://www.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://www.deepface.dev/mcp`

Use `docs.deepface.dev` for the docs pages plus Mintlify-generated `llms.txt`
and `llms-full.txt`. Use `www.deepface.dev/mcp` for the MCP runtime and the apex domain
for skill discovery. The direct REST API remains on
`https://api.deepface.dev`.

## Start with your coding agent

Copy this into the agent working on your project:

> I want to use deepface.dev for facial verification in this project. Follow the instructions at [https://deepface.dev/skill.md](https://deepface.dev/skill.md)

The guide asks the agent to use your current stack, ask which account email you
want, and prepare the integration while you confirm your email. Open
[agent signup](https://deepface.dev/signup?agent=1\&next=%2Faccount%2Fkeys) to receive
a sign-in link. You complete human verification and accept the terms; your agent
can continue once you are signed in. Existing keys can be reused without signup.

An optional, brief use-case summary helps the deepface.dev team understand what
you are building. Your agent can infer a generic summary from the relevant context
or ask you, and should tell you before sharing it. Private code, chat history,
customer details, images and embeddings do not belong in this field. You can edit
or remove the summary on the API keys page; it is never required to obtain a key.

Registered accounts get 50 calls free each month, or 100 with a saved card.
The explicit [anonymous trial](https://deepface.dev/signup?agent=1\&anonymous=1)
has one standard key and 10 calls per month. The coordinated gateway release
will additionally limit anonymous accounts to 2 calls per minute.

Use a standard key for REST at `https://api.deepface.dev`. For an MCP client,
create a separate MCP key in the dashboard for `https://www.deepface.dev/mcp`.
Keep keys in server-side environment variables, never in browser code or chat.

## Recommended agent workflow

1. Read `GET /capabilities` or call `get_capabilities` before choosing a model
   or detector.
2. For MCP clients, use `https://www.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.

## Spending alert configuration

Call `get_spending_alerts` and `update_spending_alerts` with an MCP key to read
and replace your account's budget alerts, spike alerts and cap-email setting.
Standard API keys and MCP keys also work with GET and PATCH at
`https://www.deepface.dev/api/billing/spending-alerts`.
The repository CLI exposes `spending-alerts get` and `spending-alerts set`.
See [spending alerts](spending-alerts) for the full schema and examples.

## Global and own-account priority

For `verify_faces`, `represent_face` and `compare_inputs`, use optional numeric
`priority`, for example `{"priority": 10}`. Every positive value goes ahead of
your account's normal queued work; lower positive values run first with FIFO ties.
Null, omitted and zero mean normal queue order. There is no upper bound of `1`.
MCP sends `X-Request-Priority`; REST accepts only the header, not a body field.

The ordering spans your account's API keys within one gateway process. It
selects enterprise-priority, non-enterprise-priority, enterprise-normal, then
non-enterprise-normal, in strict order among eligible calls. Within one group,
numeric values reorder only your account; other accounts keep their positions.
No aging or 4:1 rule overrides these groups. It does not interrupt running work,
bypass limits or guarantee latency. A full queue can still reject the request.

Any explicitly positive own-queue priority doubles the price of completed calls.
The default policy also doubles enterprise lane calls once; negotiated request-only
contracts include enterprise access at standard rates. No-face results are
billable; failures are free. See [own-queue priority](api-reference/rate-limits#request-priority).

## Authentication for agents

* Create an account at [deepface.dev/signup](https://deepface.dev/signup).
* AI agents can prepare [email signup](https://deepface.dev/signup?agent=1),
  then create the required key after the owner confirms their email.
* 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,
  when enabled, public HTTPS image URLs from any domain. Remote downloads must
  resolve to public addresses and pass redirect, image type, size, and timeout
  checks before inference.
* 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

MCP compute tools wait up to 120 seconds for the gateway. The gateway may still
be processing an accepted request after that wait ends. A timeout or lost
response can return JSON-RPC error `-32002` with data containing
`code: "compute_outcome_unknown"`, `request_id`, `outcome: "unknown"`, and
`retryable: false`. Preserve that request ID and investigate before submitting
another attempt. Do not automatically retry or change IDs to bypass the
uncertain outcome. The MCP service does not replay compute through another
adapter after losing a response.

An MCP configuration failure may instead return `mcp_compute_unavailable`.
Contact support; do not substitute a standard REST key in the MCP client.

* `429 rate_limited`: back off using `Retry-After` and the `RateLimit-*`
  headers.
* `503 queue_full`, `503 queue_timeout`, and `503 request_body_budget_full`:
  treat as temporary capacity pressure and retry with backoff. A body-budget
  rejection is zero-rated and does not dispatch inference.
* `503 gateway_draining`: retry with bounded backoff; compute has not started.
* `503 model_not_ready`, `model_busy`, and `model_queue_timeout`: the gateway
  already retries these precompute rejections within one 240-second deadline.
  If one reaches the client, another attempt may use bounded backoff.
* `502 upstream_failed`, a lost connection, or `504 upstream_timeout`: preserve
  `x-request-id` and investigate before replaying. Compute may have started or
  completed; these failures are not automatically retried by the gateway.
* `502 upstream_response_too_large`: reduce compare target count or response
  complexity before another attempt; the previous computation may have run.
* Reusing a postpaid request UUID returns `409 request_id_conflict`, not a saved
  result. Do not change request IDs to bypass an uncertain previous outcome.

## 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.


# Read spending alert settings and usage baselines
Source: https://docs.deepface.dev/api-reference/endpoints/account/read-spending-alert-settings-and-usage-baselines

/openapi/deepface.openapi.yaml get /api/billing/spending-alerts
Uses a standard API key or MCP key. The key selects the account; revoked keys and inactive accounts are rejected.



# Replace the full spending alert configuration
Source: https://docs.deepface.dev/api-reference/endpoints/account/replace-the-full-spending-alert-configuration

/openapi/deepface.openapi.yaml patch /api/billing/spending-alerts
Replace thresholds, spikeAlerts and capEmailEnabled together. Keep stable rule IDs when editing. Does not change tariffs, recipient or spending cap and does not send a test email.



# Compare image and vector pairs without storing embeddings
Source: https://docs.deepface.dev/api-reference/endpoints/compute/compare-image-and-vector-pairs-without-storing-embeddings

/openapi/deepface.openapi.yaml post /compare



# Generate an embedding for one image
Source: https://docs.deepface.dev/api-reference/endpoints/compute/generate-an-embedding-for-one-image

/openapi/deepface.openapi.yaml post /represent



# Verify whether two images match
Source: https://docs.deepface.dev/api-reference/endpoints/compute/verify-whether-two-images-match

/openapi/deepface.openapi.yaml post /verify



# Health check
Source: https://docs.deepface.dev/api-reference/endpoints/service/health-check

/openapi/deepface.openapi.yaml get /health



# Read gateway readiness
Source: https://docs.deepface.dev/api-reference/endpoints/service/read-gateway-readiness

/openapi/deepface.openapi.yaml get /readiness
Checks any configured rate limiter before proxying the model service readiness state. This route is intended for health checks and warmup visibility and does not require authentication.




# Read model and detector capabilities
Source: https://docs.deepface.dev/api-reference/endpoints/service/read-model-and-detector-capabilities

/openapi/deepface.openapi.yaml get /capabilities



# Errors
Source: https://docs.deepface.dev/api-reference/errors

Common error codes and how to respond to them.

# Errors

Most API failures return a JSON body shaped like:

```json theme={null}
{
  "error": "error_code",
  "detail": "Optional detail"
}
```

## Common gateway errors

* `missing_api_key`: no API key was provided to a compute endpoint.
* `invalid_api_key`: the provided key does not match an active account.
  If the key looks like an unexpanded shell variable such as
  `$DEEPFACE_CLOUD_KEY`, retry with double quotes around the authorization
  header so your shell expands the variable.
* `auth_backend_unavailable` (HTTP `503`): the gateway could not validate the
  key because its authentication database was unavailable. No inference or
  billing reservation started. Keep the same key, preserve `x-request-id`,
  and retry with bounded backoff after the `Retry-After: 5` delay.
* `account_inactive`: the account is not active.
* `billing_profile_mismatch` (HTTP `409`): an integration's required
  `x-deepface-billing-profile` assertion is missing or does not match its dedicated
  account. Compute has not started. Correct the integration configuration;
  ordinary clients should omit this header.
* `billing_tariff_scope_rejected` (HTTP `400`): the request uses options outside
  the account's agreed integration tariff. Compute has not started. Use the
  integration's supported request shape instead of changing credentials to bypass
  the restriction.
* `invalid_priority` (HTTP `400`): `X-Request-Priority` must contain one finite
  nonnegative number or null. Zero and null use normal own-account queue order.
  Blank, repeated, comma-separated, negative, non-finite,
  underflowing, or overflowing values are rejected before billing reservation
  or inference. Fix the header before retrying.
* `unsupported_priority` (HTTP `400`): experimental async compare does not
  support positive `X-Request-Priority` values. Omitted, null and zero are normal.
  Remove positive priority or use synchronous `/compare`.
* `insufficient_credits`: the account does not meet the minimum credit policy.
* `rate_limited`: per-account rate limit exceeded.
* `rate_limiter_unavailable`: the required shared rate limiter is unavailable.
  The gateway fails closed rather than switching to a per-machine allowance;
  treat this as temporary service unavailability and retry with backoff.
* `request_too_large`: request body exceeded the configured maximum.
* `request_body_timeout`: the upload stopped making progress before the request
  body deadline. Retry only after checking the client connection and payload.
* `request_body_budget_full` (HTTP `503`): this gateway process cannot safely
  reserve more upload memory. The request is recorded with zero usage credits,
  inference does not start, and `Retry-After` is `5` seconds.
* `gateway_draining` (HTTP `503`): this gateway has stopped accepting work.
  The rejection happens before authentication or compute; rate-limit headers
  may be absent. Preserve `x-request-id` and retry with bounded backoff.
* `queue_full`: the concurrency queue is full.
* `queue_timeout`: the request waited too long in queue.
* `upstream_failed`: the model server request failed.
* `upstream_timeout`: the model server did not finish before the gateway
  deadline. Preserve `x-request-id` and use the same operational caution as
  other uncertain 5xx results before retrying.
* `upstream_response_too_large`: the model response exceeded the gateway's
  response-size limit; reduce compare target count or response complexity.
* `model_server_secret_required`: the model tier is missing its required
  internal shared-secret configuration. Treat this as temporary service
  unavailability and contact support if it persists.

## MCP transport errors

MCP compute tools may return JSON-RPC error `-32002` with
`data.code: "compute_outcome_unknown"`, a `request_id`, `outcome: "unknown"`,
and `retryable: false`. This can follow the 120-second MCP gateway wait or a
lost response. Accepted gateway work may continue; preserve the request ID
and investigate before retrying. MCP does not automatically replay it.

`mcp_compute_unavailable` indicates missing or invalid MCP server configuration.
Contact support. Changing to a standard REST key inside an MCP client does not
fix server configuration.

## Completed no-face results

HTTP `422` with `error: "no_face_detected"` means detection completed without
finding a face. These calls are billable at the applicable standard or priority
rate. Other non-2xx outcomes, including invalid requests and service failures,
are not billed. The HTTP status remains unchanged for compatibility.

## Common model-server errors

* `model_not_ready` (HTTP `503`): the model runtime is still warming or is not
  ready to accept compute.
* `model_busy` (HTTP `503`): the model process already has one active compute
  request and one queued request.
* `model_queue_timeout` (HTTP `503`): the request exceeded the model's
  15-second queue-only wait limit before compute began.
* `model_name is not allowed.`
* `detector_backend is not allowed.`
* `distance_metric must be cosine, euclidean, or euclidean_l2.`
* `missing image input: ...`

The gateway automatically retries these three explicit admission responses
within the same 240-second upstream deadline, using bounded backoff with jitter.
That deadline includes cold-start recovery, model queue waiting, and inference;
retrying does not reset it. The model queue allows 15 seconds and active work
has a separate 210-second watchdog. A watchdog expiry can interrupt the model
connection, leaving an uncertain result. Slow startup plus inference can exceed
the shared gateway deadline.

If an explicit admission rejection reaches your client, inference did not start
for that request; use bounded backoff before another attempt. A lost response,
`upstream_failed`, or `upstream_timeout` is different: work may already have
started or completed. The gateway does not replay those ambiguous failures.
Preserve `x-request-id` and investigate before submitting another computation.
The same normalized request UUID follows all gateway admission retries, and
only their final outcome is settled. Capacity recovery waiting is recorded as
queue time rather than compute time. After the coordinated gateway release, prepaid and free requests gain the same replay protection. Reusing a postpaid request UUID returns
`409 request_id_conflict`; it does not retrieve or replay a saved result.

## Debugging tips

* Capture `x-request-id` for every failed request.
* Parse the `error` field as the stable machine-readable code.
* Use `detail` for human-readable remediation context.
* If you get `missing_api_key` and you are an AI agent with no configured key,
  open [deepface.dev/signup?agent=1](https://deepface.dev/signup?agent=1),
  ask which email the account owner wants to use, and let them confirm their email.
  Create a standard API key in their dashboard, then retry. Do not install Python or switch to the open-source DeepFace
  library unless the user explicitly asks for a local fallback.
* Check `GET /capabilities` when a model or detector becomes unavailable.
* Re-run with a single known-good image pair before escalating compare issues.

## Concurrent anonymous requests

After the coordinated gateway release, `429 inflight_limit` means that this anonymous account already has an active
inference request. Wait for it to finish, then retry; the response includes
`Retry-After: 5`. Normal account rate limits also use HTTP 429.

A used `X-Request-ID` cannot be reserved again by prepaid or free requests.
`409 request_id_conflict` rejects the duplicate; it does not replay a result.


# API overview
Source: https://docs.deepface.dev/api-reference/overview

Public endpoint surface and media types for deepface.dev.

# API overview

The managed public API currently exposes six routes:

* `GET /health`
* `GET /readiness`
* `GET /capabilities`
* `POST /verify`
* `POST /represent`
* `POST /compare`

## Input modes

* `multipart/form-data` for file uploads
* `application/json` for base64 payloads
* authenticated API requests may use public HTTPS image URLs from any domain
  when remote URL input is enabled on the model server

The homepage shows precomputed examples and makes no live inference requests.
Use the signed-in tester for your own files. Local filesystem paths are disabled
unless explicitly enabled on the model server.

## Integration guidance

* Use `GET /capabilities` before choosing models or detectors in automation.
* Use `x-request-id` for traceability on compute calls.
* Use optional `X-Request-Priority` on synchronous compute calls to order your
  account's waiting requests. Lower positive values run first; the default is
  `1`. See [request priority](/api-reference/rate-limits#request-priority) for scope and limits.
* Expect `RateLimit-*` and `Retry-After` headers on throttled or retryable
  responses.

## Generated endpoint docs

The endpoint pages in this section are generated from the bundled OpenAPI
document. The canonical source of truth lives in
`openapi/deepface.openapi.yaml` in the repository and also powers the Mintlify
MCP surface for agent tooling.


# Rate limits
Source: https://docs.deepface.dev/api-reference/rate-limits

Throughput, queueing, and retry behavior.

# Rate limits

deepface.dev applies rate limiting and queue controls at the gateway.

## Enforcement points

* Per-account requests per minute within the configured limiter scope
* Maximum inflight compute requests
* Queue depth
* Queue timeout

## Account tiers

The allowance is shared across all API keys for an account within the configured
limiter scope. Paid tiers use **lifetime USD value added to the wallet**, not API
usage or the remaining balance. Free credits, failed or pending payments,
card-setup payments, sandbox payments and test payments do not count.

| Account | Requests/minute |
| - | -: |
| Enterprise | 300 |
| Paid wallet funded above \$100 | 300 |
| Paid wallet funded above \$50 | 200 |
| Paid wallet funded above \$20 | 100 |
| Paid wallet funded above \$10 | 60 |
| Paid wallet with any positive funding | 30 |
| Full account, no paid funding | 15 |
| Anonymous account (pending coordinated gateway release) | 2 |

After the coordinated gateway release, anonymous accounts are limited to one active inference request, with no waiting
queue. The two-per-minute limit is shared across gateway Machines and all keys
for the account. Anonymous accounts cannot enqueue batch comparisons; create a
full account first. The homepage displays saved examples, so browsing them uses
no API quota. Live testing requires a signed-in account and follows its limits.

Thresholds are strict: exactly $50 receives 100/minute; the 200/minute tier starts
above $50. Tiers refresh when a verified live payment is credited to the wallet.

Paid wallets with active auto top-up and a valid live saved card receive **20%
off standard usage pricing**, including priority usage. New requests lose this
discount when auto top-up is disabled or the card is revoked. Monthly invoice
contracts use their agreed tariff.

## Request priority

Send optional `X-Request-Priority` on synchronous `POST /verify`, `POST /represent`
and `POST /compare`, with JSON or multipart uploads. It lets a request jump
**your own account's normal waiting queue**, across all of that account's API keys,
on one gateway process. A positive value also selects a higher global scheduling
group.

The global waiting queue on each gateway process uses strict precedence:

1. Enterprise with an explicitly positive priority.
2. Non-enterprise with an explicitly positive priority.
3. Enterprise normal.
4. Non-enterprise normal.

Only eligible calls compete: an account at its in-flight limit is skipped.
Within a group, accounts retain their queue positions; lower positive values
can jump that account's own waiting calls, with FIFO ties. Numeric values do not
rank different accounts. The old 4:1 rotation and aging override are removed.
Sustained higher-group traffic can delay lower groups until their original queue
timeout; active work is never preempted. This ordering is per gateway process.

Every finite positive value requests own-queue priority, with no upper limit of
`1`. Lower positive numbers run first: `0.5`, then `1`, then `10`, then `100`,
then requests with no priority. Equal effective values keep arrival order.
**Omitted, `null`, and `0` use normal FIFO order**; zero is handled normally
without rejecting the request. They add no per-request priority surcharge.
For REST, send literal `null` for a null header or omit the header.

Numbers use double precision and JSON spelling, including scientific notation.
Negative, blank, repeated, comma-separated, nonfinite, overflowing and underflowing
values return `400 invalid_priority` before admission. Close decimals may round
equal. Write `0.79`, not `.79`, `+0.79`, or `00.79`.

Own-queue priority does not interrupt running work, reorder model-server work,
reserve capacity, bypass RPM/concurrency/upload limits or extend queue deadlines.
A full queue can still reject a priority request. Sustained priority traffic can
delay normal requests until their original timeout. Ordering is per gateway
process and does not guarantee latency.

For MCP, use optional `priority` on `verify_faces`, `represent_face` or
`compare_inputs`; null/omitted means no header, and zero is accepted as normal.
REST priority is header-only. Experimental async compare rejects a positive
header with `400 unsupported_priority`.

### Billing and audit

Completed calls with **any explicitly positive own-queue priority cost 2×**, even
when the queue is idle. Under the default billing policy, enterprise lane access
also costs 2×; both together cost 2× once. Negotiated `request_only` contracts
include enterprise access at the standard rate. Completed no-face results are
billable; failures are free.

The gateway records the requested value, whether a header was supplied, whether
own-queue priority applied, the `global_tier_and_own_account_queue` scope, actual enterprise
lane, and scheduling transitions. Each event freezes `schedulerPolicy: four_tier_v1`
and `schedulingClass`, with per-group queue counts at scheduling decisions. Billing receipts freeze `request_priority_scheme`,
contract policy and multiplier. Historical `below_one_v1` receipts retain their
original interpretation; `optional_positive_v2` uses the optional scheme above.
Existing financial and scheduling history is not reinterpreted.

## Retry behavior

`429 rate_limited` responses include:

* `Retry-After`
* `RateLimit-Limit`
* `RateLimit-Remaining`
* `RateLimit-Reset`

These headers describe the limiter that enforced the request. With a configured
shared Redis limiter, gateways share the account counter. Without Redis, each
gateway process has its own in-memory counter; multiple gateway Machines do not
provide one strict fleet-wide RPM allowance. A configured required shared
limiter fails closed when unavailable. Concurrency and queue admission remain
local to each gateway process, with account overrides within its global limits.

`503 queue_full`, `503 queue_timeout`, and `503 request_body_budget_full`
indicate temporary capacity pressure. Treat them as retryable with bounded
backoff unless your own SLA policy says otherwise. A body-budget rejection is
zero-rated, does not dispatch inference, and includes `Retry-After: 5`.
`503 gateway_draining` also rejects before compute and includes `x-request-id`.
Rate-limit headers may be absent.

For explicit model `503 model_not_ready`, `model_busy`, and
`model_queue_timeout` responses, the gateway already retries admission with
jittered backoff within one 240-second upstream deadline. These retries do not
consume another account RPM token or create a separate billing request. A
client's new HTTP request passes through admission and rate limiting again.
Generic `502`, connection loss, and `504 upstream_timeout` do not prove that
compute failed to run: preserve the request ID and investigate before replaying.
See [Errors](/api-reference/errors) for request-ID and timeout behavior.

## Capacity planning

If you need higher sustained throughput, dedicated queue capacity, or custom
limits, contact the deepface.dev team before scaling traffic abruptly.


# Authentication
Source: https://docs.deepface.dev/authentication

Account access, REST API keys, MCP keys, and request tracing for deepface.dev. AI agents can prepare passwordless signup and create keys after the owner confirms their email.

# Authentication

This page covers authentication for the direct REST API on
`https://api.deepface.dev`. MCP clients use dedicated MCP keys from the
dashboard and connect through `https://www.deepface.dev/mcp`.
Use this endpoint directly so a hostname redirect cannot remove your authorization header.

## Account access

* Create an account at [deepface.dev/signup](https://deepface.dev/signup).
* AI agents that do not already have a configured REST key can open
  [deepface.dev/signup?agent=1](https://deepface.dev/signup?agent=1), prepare email signup,
  wait for the owner to confirm their email, then create their own standard REST API key or dedicated MCP key
  in the dashboard.
* Return to [deepface.dev/signin](https://deepface.dev/signin) to manage usage,
  billing, and API keys.
* Accounts created through the public auth flow receive an active account record
  automatically.
* Remote image URL fetching is an authenticated API feature only when it is
  enabled on the model server. Public HTTPS image URLs from any domain are
  accepted under the runtime download checks; the public tester does not use
  remote URL input.

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.

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.

## Create and store REST API keys

* Open the dashboard `API keys` page after sign-in.
* Create a named key per app, environment, or integration.
* If you are an AI agent operating directly from the browser flow, you may
  create this key yourself after signup. You do not need to wait for a
  pre-provisioned key.
* Store the full key when it is shown. It is only returned once.
* Do not reuse standard REST API keys for MCP clients. Create dedicated MCP
  keys for `https://www.deepface.dev/mcp`.

## Create and store MCP keys

* Open the dashboard `MCP` page after sign-in.
* Anonymous agent sessions can create these keys themselves after signup.
* Create a dedicated MCP key per agent, client, or environment.
* Store the full key when it is shown. It is only returned once.
* Use MCP keys only with `https://www.deepface.dev/mcp`.
* Do not reuse MCP keys for direct REST requests.
* No additional shared secret or internal header is needed in an MCP client.
  The hosted service handles its own server-to-server authentication.
* MCP compute image inputs may be raw base64, `data:image/...` strings, or,
  when enabled, public HTTPS image URLs from any domain. The model server
  rejects non-public destinations, redirects, unsupported image types,
  oversized images, and downloads that exceed the timeout.

## Supported headers

* `Authorization: Bearer YOUR_API_KEY`
* `x-api-key: YOUR_API_KEY`

## Public vs authenticated REST endpoints

* `GET /health` and `GET /capabilities` are public.
* `POST /verify`, `POST /represent`, and `POST /compare` require an API key.
* If you hit `missing_api_key`, create or retrieve a standard REST API key from
  the account dashboard before retrying. Do not switch to a local Python or
  open-source DeepFace run unless the user explicitly asks for that fallback.

## Request tracing

You can provide `x-request-id` with a UUID value. If you do not send one, the
gateway will generate it for you and echo it back in the response.

For MCP compute, preserve `request_id` from any `compute_outcome_unknown`
error as well. The MCP gateway wait is 120 seconds; a timeout or lost response
does not prove that inference or billing stopped. Investigate the original
request before retrying. MCP does not automatically replay uncertain compute.


# Changelog and versioning
Source: https://docs.deepface.dev/changelog-and-versioning

Versioning expectations and how deepface.dev publishes API changes.

## No-face compatibility hold (6 October 2026)

The public API retains HTTP `422` with `error: "no_face_detected"` and `detail`
for completed no-face detections while clients prepare for a coordinated change.
These detections remain billable; genuine processing failures are not billed.
The HTTP 200 rollout described below is superseded by this compatibility hold.

## 6 October 2026 — completed no-face responses

Completed no-face detections now return HTTP 200 with `outcome: "no_face_detected"`,
`faces: []` and `detail`, rather than HTTP 422. Check `outcome` before reading
match or embedding fields. These completed calls remain billable; failures are
uncharged. Historical usage statuses are preserved.

# Changelog and versioning

deepface.dev ships the public API as a `v1` contract.

## 2026-10-05 — Global scheduling groups

Queued eligible calls now run in strict order: enterprise with positive request
priority, non-enterprise with positive priority, enterprise normal, then
non-enterprise normal. Lower positive numbers still order the caller's own
waiting work within a group. The former 4:1 rotation and aging override no longer
apply. Scheduling events record `four_tier_v1` and the selected group. Billing
rates and the `optional_positive_v2` interpretation are unchanged.

## 5 October 2026: optional priority within your own account queue

`X-Request-Priority` now lets a call jump its own account's normal waiting queue,
across the account's API keys on each gateway process. Any finite positive value
requests priority; lower positive numbers run first. There is no upper bound of
`1`. Omitted, null and zero mean normal order, and zero is accepted. Other
accounts' turns and enterprise classes stay unchanged; active work is not preempted.

Any explicitly positive own-queue priority doubles completed-call pricing.
Negotiated request-only contracts include enterprise access at the standard
rate. No-face results are billable; failures are free. Logs record own-queue
priority application and scope separately from actual enterprise treatment. New receipts use `optional_positive_v2`;
historical `below_one_v1` receipts retain their earlier interpretation and charges.

## 5 October 2026: negotiated priority billing

Negotiated request-only contracts include enterprise access at the standard
rate. Enterprise lane access alone adds no surcharge under this policy. Each
call snapshots the contract billing policy separately from its actual scheduling
conditions. Historical receipts retain their original interpretation and charges.

## Wallet benefits — 5 October 2026

Enterprise accounts receive 300 requests/minute. Other accounts receive 15/minute
by default, or 30/minute after funding a paid wallet. Lifetime USD wallet funding
strictly above $10, $20, $50 and $100 raises the allowance to 60, 100, 200 and
300/minute. Verified credited live top-ups count; free credits and test payments
do not. The existing limiter scope is per gateway process unless Redis is shared.

Paid wallets with active auto top-up and a valid saved card receive 20% off
usage prices, including priority usage. Each request records its discount;
queued async jobs retain the discount agreed at enqueue. Monthly invoice
contracts use their agreed tariff. See [rate tiers](api-reference/rate-limits#account-tiers).

## Priority billing — 3 October 2026

Calls admitted from 21:10 UTC are charged at
2x the standard rate when they use an enterprise priority lane or a request
priority below `1`. Both together still cost 2x, even when the queue is idle.
Failed calls remain uncharged. Existing charges and issued invoices are unchanged;
historical priority is not inferred. Async compare keeps its standard service.

The branded email/PDF and accounting integration were deployed on 3 October.
Emails distinguish billable standard-rate and priority API calls. Period dates
end on the last calendar day; Tech Local EFT details appear in the PDF only.
Usage records now retain per-call priority treatment and the effective multiplier.

## Request priority — 15 September 2026

* Synchronous `/verify`, `/represent`, and `/compare` accept the optional
  `X-Request-Priority` header, a finite positive number defaulting to `1`.
  Lower numbers go first within an account's waiting queue on each gateway
  process; equal effective priorities keep arrival order.
* MCP compute tools accept the equivalent numeric `priority` argument.
* Invalid values return `400 invalid_priority` before billing reservation or
  inference. Experimental async compare rejects the header with
  `400 unsupported_priority`.
* Existing requests keep their ordering when priority is omitted. Priority
  provides no preemption, reserved capacity, or latency guarantee.
  See [request priority](api-reference/rate-limits#request-priority).

## Versioning rules

* Breaking API changes require an explicit versioning decision before release.
* Non-breaking additions land in the changelog and OpenAPI spec together.
* Docs changes that alter endpoint behavior must update the canonical OpenAPI
  file in the same pull request.

## Change process

* Update `openapi/deepface.openapi.yaml`.
* Regenerate `docs-site/openapi/deepface.openapi.yaml`.
* Run `npm run docs:check`.
* Include any customer-facing behavior changes in the pull request summary.


# Customer-owned face search with Supabase pgvector
Source: https://docs.deepface.dev/customer-owned-face-search

Use deepface.dev to generate face embeddings while storing and searching the face database in your own Supabase project.

# Customer-owned face search with Supabase pgvector

Use this pattern when you want scalable face search, but you do not want
deepface.dev to host your face database.

The flow is:

1. Send an image to `POST /represent`.
2. Store the returned embedding in your own Supabase `pgvector` table.
3. For a new query image, call `POST /represent` again.
4. Search your own Supabase table for the closest embeddings.

deepface.dev still processes the images and embeddings you submit so it can
return API results. The difference is that your enrolled face database, person
IDs, labels, and search index stay in your Supabase project.

## How this relates to DeepFace register and search

Open-Source DeepFace now includes database-backed `register`, `search`, and
`build_index` functions for stateless face recognition pipelines. In that model,
`register` stores embeddings in a backend database and `search` queries that
database.

deepface.dev does not expose hosted `/register` or `/search` endpoints today.
Instead, use `POST /represent` for the compute step and keep registration,
storage, indexing, and search in your own database.

References:

* [Sefik's write-up on DeepFace register, search, and build\_index](https://sefiks.com/2026/01/01/introducing-brand-new-face-recognition-in-deepface/)
* [Open-Source DeepFace database-backed search in the README](https://github.com/serengil/deepface)

## Create the Supabase table

This example uses `Facenet`, which returns 128-dimensional embeddings. If you
choose another model, confirm its embedding length and change `vector(128)` to
match.

```sql theme={null}
create extension if not exists vector;

create table if not exists public.face_embeddings (
  id uuid primary key default gen_random_uuid(),
  person_id text not null,
  label text,
  embedding vector(128) not null,
  metadata jsonb not null default '{}'::jsonb,
  created_at timestamptz not null default now()
);

alter table public.face_embeddings enable row level security;

create index if not exists face_embeddings_embedding_hnsw_idx
  on public.face_embeddings
  using hnsw (embedding vector_cosine_ops);
```

For production, add RLS policies that match your app's account model. If you use
a service-role key in a backend job, keep it server-side only and never expose it
in browser code.

## Query nearest faces

Use cosine distance (`<=>`) to match deepface.dev's default `cosine` comparison
metric. Smaller distances are closer matches.

Create a database function so Postgres can order by vector distance directly:

```sql theme={null}
create or replace function public.match_faces(
  query_embedding vector(128),
  match_count int default 5
)
returns table (
  id uuid,
  person_id text,
  label text,
  metadata jsonb,
  distance float
)
language sql
stable
as $$
  select
    face_embeddings.id,
    face_embeddings.person_id,
    face_embeddings.label,
    face_embeddings.metadata,
    face_embeddings.embedding <=> query_embedding as distance
  from public.face_embeddings
  order by face_embeddings.embedding <=> query_embedding
  limit match_count;
$$;
```

## JavaScript example

Install the Supabase client in your backend project:

```bash theme={null}
npm install @supabase/supabase-js
```

Then generate, store, and search embeddings from a server-side script or API
route:

```javascript theme={null}
import { createClient } from "@supabase/supabase-js";

const deepfaceApiBaseUrl =
  process.env.DEEPFACE_API_BASE_URL || "https://api.deepface.dev";
const deepfaceApiKey = process.env.DEEPFACE_API_KEY;
const supabaseUrl = process.env.SUPABASE_URL;
const supabaseServiceRoleKey = process.env.SUPABASE_SERVICE_ROLE_KEY;

if (!deepfaceApiKey || !supabaseUrl || !supabaseServiceRoleKey) {
  throw new Error("Missing DEEPFACE_API_KEY, SUPABASE_URL, or SUPABASE_SERVICE_ROLE_KEY.");
}

const supabase = createClient(supabaseUrl, supabaseServiceRoleKey, {
  auth: { persistSession: false },
});

async function represent(imageBase64) {
  const response = await fetch(`${deepfaceApiBaseUrl}/represent`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${deepfaceApiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model_name: "Facenet",
      img: imageBase64,
    }),
  });

  if (!response.ok) {
    throw new Error(`deepface.dev /represent failed: ${response.status}`);
  }

  const result = await response.json();
  const embedding = Array.isArray(result) ? result[0]?.embedding : result.embedding;

  if (!Array.isArray(embedding)) {
    throw new Error("No embedding returned by deepface.dev.");
  }

  return embedding;
}

async function registerFace({ personId, label, imageBase64, metadata = {} }) {
  const embedding = await represent(imageBase64);

  const { error } = await supabase.from("face_embeddings").insert({
    person_id: personId,
    label,
    embedding,
    metadata,
  });

  if (error) {
    throw error;
  }
}

async function searchFace({ imageBase64, limit = 5 }) {
  const embedding = await represent(imageBase64);

  const { data, error } = await supabase.rpc("match_faces", {
    query_embedding: embedding,
    match_count: limit,
  });

  if (error) {
    throw error;
  }

  return data;
}
```

## When to use this pattern

Use customer-owned search when you need:

* face search across many enrolled identities;
* control over where biometric data and metadata are stored;
* your own RLS, audit, retention, and deletion rules;
* database-level ANN search as your dataset grows.

For small request-time comparisons, `POST /compare` can still compare one image
or vector against vectors you include in the request. For larger datasets, keep
the database search in Supabase and use deepface.dev only for embedding
generation.


# deepface.dev Docs
Source: https://docs.deepface.dev/index

Managed API docs for face verification, embeddings, and vector comparison. Coding agents can guide email signup, create API keys after confirmation, and connect over REST or MCP.

# deepface.dev Docs

deepface.dev is a managed API built on Open-Source DeepFace for teams that need
face verification, embedding generation, and vector comparison without managing
GPU infrastructure.

## Access and integrations

* Self-serve account creation at [deepface.dev/signup](https://deepface.dev/signup)
* Coding agents can guide [email signup](https://deepface.dev/signup?agent=1);
  the account owner confirms their email before creating a standard API key or MCP key
* Standard REST API keys and dedicated MCP keys from the account dashboard after sign-in
* Public docs, runnable examples, and Mintlify-generated API reference pages
* Direct REST API access on `https://api.deepface.dev`
* Machine-readable docs on `docs.deepface.dev/llms.txt` and `docs.deepface.dev/llms-full.txt`
* Owned agent surfaces at `https://deepface.dev/skill.md`, `https://deepface.dev/.well-known/skills`, and `https://www.deepface.dev/mcp`

## AI agent first step

Read [the setup instructions](https://deepface.dev/skill.md) before integrating.
Reuse a suitable existing account and key. Otherwise:

1. Ask which email the account owner wants to use.
2. Open [email signup](https://deepface.dev/signup?agent=1).
3. Let the owner accept the terms and confirm their email.
4. Create a standard REST key or a dedicated MCP key for `https://www.deepface.dev/mcp`.

A confirmed account gets 50 free calls each month, plus 50 more with a saved card.
An explicitly requested [anonymous trial](https://deepface.dev/signup?agent=1\&anonymous=1)
has one standard key and 10 calls per month. A two-request-per-minute limit
is pending the coordinated gateway release.

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.

## Public API surface

* `POST /verify` to compare two images.
* `POST /represent` to generate embeddings.
* `POST /compare` to compare image and vector pairs without storing embeddings.
* `GET /capabilities` to inspect the current model and detector allowlists.

For face search across a customer-owned database, see
[Customer-owned face search with Supabase pgvector](customer-owned-face-search).

## Next steps

* Read the [quickstart](quickstart).
* Review [authentication](authentication).
* Review the [AI and agents guide](ai-agents).
* Build [customer-owned face search with Supabase pgvector](customer-owned-face-search).
* Check [models and licensing](models-and-licensing) before choosing a model.
* Browse the [API reference](api-reference/overview).


# Models and licensing
Source: https://docs.deepface.dev/models-and-licensing

Approved models, detector support, and commercial licensing boundaries.

# Models and licensing

deepface.dev only exposes models and detectors that have been reviewed for the
managed service. Agents and integrations should rely on `GET /capabilities` for
the current allowlist instead of hard-coding assumptions.

## Approved backbone models

* Facenet
* Facenet512
* OpenFace
* Dlib
* SFace

The current production default model is `Facenet`. The API allowlist is still
authoritative through `GET /capabilities`, but if you need a stable baseline
for smoke tests and synthetics, assume `Facenet` first and then confirm the
live capabilities response.

## Excluded models

### VGG-Face

VGG-Face remains excluded. Its released weights are restricted to
non-commercial research use and are not available on deepface.dev.

### DeepFace backbone

The DeepFace backbone is excluded because the current managed TensorFlow
runtime does not provide the `LocallyConnected2D` support required by its
upstream implementation. This is a technical compatibility boundary, not a
licensing determination. Enabling it would require a validated compatible
runtime plus coordinated updates to the build policy, runtime allowlist,
capabilities response, tests, and documentation.

### ArcFace via InsightFace weights

ArcFace models derived from InsightFace weights may require a separate
commercial license. Do not assume those weights are cleared for commercial use
without explicit legal review.

## Detector guidance

The active detector allowlist is exposed through `GET /capabilities`. Start
with the default detector unless you have measured a better fit for your input
distribution.

The current production default detector is `opencv`. deepface.dev also pre-bakes
and pre-warms `retinaface` to reduce startup risk during cold recovery, but
that warmup choice is operational only and does not change the default detector
reported by `GET /capabilities`.

When `opencv` cannot extract a face, the managed service may retry
`retinaface` before returning `no_face_detected`. That fallback remains inside
the approved detector allowlist and does not expand the commercial model
surface.

## Attribute analysis

Attribute analysis is intentionally absent from the managed API. The upstream
attribute stack depends on VGG-Face-based components that are not approved for
commercial use in this service.

## Operational notes

Readiness and warmup are now first-class service concerns. `GET /readiness`
reports whether the managed runtime has finished warming the approved model and
detector stack. This route exists for health checks and incident diagnosis; it
does not expand the commercial model surface beyond what `GET /capabilities`
already exposes. Before readiness turns healthy, the runtime completes a
synthetic embedding inference for each configured prewarm model and detector;
every model involved must already be present in the approved allowlist. Warmup
failures are reported with symbolic readiness errors; raw runtime exception
details remain in server logs.

Image normalization enforces byte, request-size, and decoded pixel safety
limits before detector downscale. These operational limits protect the managed
runtime and do not change the approved model or detector allowlist.

When enabled, public HTTPS image URLs from any domain use this same
normalization path. Enabling that transport does not expand
the model or detector surface.

If you store embeddings in your own vector database, the same model licensing
rules still apply. Use `GET /capabilities` before choosing the model for
[customer-owned face search](customer-owned-face-search), and keep the stored
embedding dimension aligned with that model.


# Pricing and governance
Source: https://docs.deepface.dev/pricing-governance

Usage-based pricing, throughput controls, and enterprise escalation paths.

# Pricing and governance

deepface.dev uses usage-based pricing with governance around throughput,
concurrency, and queue behavior.

## Free calls and your balance

Full accounts receive 50 completed calls per UTC calendar month. An active saved
card adds 50, for 100 total. Free calls are used before your balance, including
when the wallet is funded. Saving a card does not enable automatic top-ups.
Invalid requests and service failures do not use the allowance. Completed
processing, including a no-face result or a non-match, counts as a call.

## Standard request prices

The account charge is recorded with each request. A fixed self-serve tariff is
being introduced separately from agreed monthly invoice tariffs. Once active,
standard face comparisons and embeddings cost $2 per 1,000 requests. Vector
comparisons cost $0.20 per 1,000 vector pairs. An image-to-vector comparison also
includes one embedding request; for example, an image compared with ten vectors
costs \$0.004 before free calls or discounts.

Until the fixed tariff is active, processing time and the operation determine
the price. There is no separate image-size price multiplier. Existing image and
request size limits still apply. Queue priority can double the standard price;
see [rate limits](/api-reference/rate-limits).

## What is governed today

* Request rate limits
* Queue depth and queue timeout
* Concurrency limits
* Rolling-usage-aware pricing logic in the gateway

## What customers should expect

* Self-serve account access and dashboard-managed API keys.
* Public docs that explain endpoint behavior and constraints.
* Enterprise throughput, dedicated capacity, and SLA discussions still happen
  directly with the deepface.dev team.
* Production changes that affect pricing are reflected in the API changelog and
  OpenAPI source before rollout.

## Auto top-up discount

Paid wallets receive 20% off the full standard usage price while auto top-up is
active with a valid saved card. The discount applies after usage-based markup
and any priority multiplier. For example, a standard price of $1.00 becomes
$0.80; its priority price of $2.00 becomes $1.60. Disable auto top-up or revoke
the card to remove the discount for new requests. Monthly invoice contracts
continue to use their agreed tariff.

[Account rate tiers](/api-reference/rate-limits) depend on lifetime wallet funding,
not on the number of API calls or the current balance.


# Quickstart
Source: https://docs.deepface.dev/quickstart

Create an account, generate your own API key, and send your first request. AI agents can prepare email signup and the integration while the account owner confirms their email.

# Quickstart

The public API is served by the gateway at `https://api.deepface.dev`.
This quickstart is for direct REST integrations. If you are wiring an MCP
client, use the [AI and agents guide](ai-agents) and create an MCP key instead
of a standard REST API key.

## 1. If you are an AI agent and no key is configured, connect an account first

Prepare the integration while the account owner confirms their email.

1. Open [deepface.dev/signup?agent=1](https://deepface.dev/signup?agent=1).
2. Enter the account email chosen by the user and an optional project summary.
3. Let the owner complete verification and open the sign-in link; continue preparing their integration while they confirm.
4. Open the dashboard `API keys` page.
5. Create a standard REST API key for this integration.

If you are wiring MCP instead of direct REST, create a dedicated MCP key on the
dashboard `MCP` page and follow the [AI and agents guide](ai-agents).

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.

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.

## 2. Create your account

If you are setting up without a coding agent:

[Sign up](https://deepface.dev/signup) for deepface.dev, then
[sign in](https://deepface.dev/signin) to open the account dashboard.

The first-use guide opens in a five-step modal: welcome, what the API does,
using it in your app, creating a key, and getting a result.

## 3. Create an API key

Create a key in the guide, or open `API keys`. The full key is shown once;
save it in your secrets manager.

The final step offers **Run sample**: a real `/represent` call with a
synthetic portrait. It uses your normal allowance. Then try your own image and
copy a cURL or Python example for your server. Test your own images before
relying on the API in your application.

## 4. Pick a supported model

Start with `Facenet` unless you have a compatibility reason to choose another
approved model. Review the full [models and licensing](models-and-licensing)
guide before production use.

## 5. Call `/verify`

```bash theme={null}
curl --request POST \
  --url https://api.deepface.dev/verify \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --form 'img1=@./person-a.jpg' \
  --form 'img2=@./person-b.jpg' \
  --form 'model_name=Facenet'
```

Example response:

```json theme={null}
{
  "verified": true,
  "distance": 0.19,
  "threshold": 0.4,
  "model": "Facenet"
}
```

## Runnable examples

### Give a request higher priority

Add `--header 'X-Request-Priority: 0.79'` to the multipart request above.
The same header works for JSON requests:

```bash theme={null}
curl --request POST \
  --url https://api.deepface.dev/compare \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'X-Request-Priority: 0.79' \
  --data '{"model_name":"Facenet","source_vector":[1,0,0],"target_vectors":[[1,0,0]]}'
```

Omitted, null and zero mean normal priority. Any positive value jumps your
account's normal waiting requests; lower positive numbers run first on the same gateway process. This does not
interrupt work already dispatched or guarantee an instant response. Global
eligible calls run enterprise-priority, non-enterprise-priority, enterprise-normal,
then non-enterprise-normal.
See [request priority and its limits](api-reference/rate-limits#request-priority).

### Client examples

* [JavaScript verify example](https://github.com/techlocal-accounts/deepface/blob/main/examples/javascript/verify.mjs)
* [JavaScript represent example](https://github.com/techlocal-accounts/deepface/blob/main/examples/javascript/represent.mjs)
* [JavaScript compare example](https://github.com/techlocal-accounts/deepface/blob/main/examples/javascript/compare.mjs)
* [Python verify example](https://github.com/techlocal-accounts/deepface/blob/main/examples/python/verify.py)
* [Python represent example](https://github.com/techlocal-accounts/deepface/blob/main/examples/python/represent.py)
* [Python compare example](https://github.com/techlocal-accounts/deepface/blob/main/examples/python/compare.py)

## 6. Inspect capabilities

Use `GET /capabilities` to read the active model and detector allowlists before
rolling requests into production.

Authenticated API integrations can also use public HTTPS image URLs from any
domain when remote URL fetching is enabled on the model server. Downloads must
resolve to public addresses and pass the image type, size, redirect, and timeout
checks. The homepage shows saved API examples; sign in to test with your own files.

## 7. Keep request IDs

Every compute response includes `x-request-id`. Log it on your side for support
handoffs and incident debugging.


# Spending alerts
Source: https://docs.deepface.dev/spending-alerts

Configure budget, usage-spike and spending-cap emails through the dashboard, account API, repository CLI or MCP.

The dashboard, API, CLI and MCP use the same saved account settings.
Configure up to three budget alerts and three independent spike alerts, including
their enabled switches, amounts, lookbacks and percentages. `capEmailEnabled`
controls cap-hit emails; it does not change the spending cap itself.

## Settings

Settings amounts are **USD cents**. Snapshot totals are **micro-USD**
(1 USD = 1,000,000 micro-USD). Calendar boundaries use the returned billing
timezone. Charged usage and completed no-face results count toward spend;
failures, free calls and wallet top-ups are excluded.

```json theme={null}
{
  "thresholds": [
    { "id": "monthly-budget", "enabled": true, "amountCents": 5000, "period": "monthly" }
  ],
  "spikeAlerts": [
    { "id": "matching-weekday", "enabled": true, "mode": "same_weekday", "samples": 5, "percentAbove": 40, "minimumSpendCents": 100 },
    { "id": "weekly-spike", "enabled": true, "mode": "weeks", "samples": 4, "percentAbove": 50, "minimumSpendCents": 100 },
    { "id": "monthly-spike", "enabled": false, "mode": "months", "samples": 3, "percentAbove": 30, "minimumSpendCents": 100 }
  ],
  "capEmailEnabled": true
}
```

Budget periods are `daily` or `monthly`. Spike modes are `days`, `weekdays`,
`same_weekday`, `weeks` and `months`. Lookbacks use previous completed periods:
up to 90 days/weekdays, 52 matching weekdays/weeks, or 12 months. Weeks start
on Monday; months use calendar boundaries. Today, this week or this month is
compared with the corresponding completed-period average. Alerts wait for the
full lookback history. Weekday alerts are inactive on weekends.

Keep rule IDs stable when editing to preserve delivery history. IDs must be
unique within each list and contain 1–64 letters, digits, underscores or hyphens.
Budget and minimum-spend amounts are integer cents from 1 to 1,000,000,000.
`percentAbove` accepts numbers from 0 to 10,000. The minimum-spend amount prevents
small spikes from triggering an email.

Checks run every five minutes, with at most one accepted notice per rule/period.
Disabling or removing a rule cancels only its unattempted notices. Saving
settings does not send a test email.

## Account API

Use **`https://www.deepface.dev`**, rather than the compute gateway, with your
existing standard API key or MCP key. Both `Authorization: Bearer` and
`X-API-Key` work. The key selects the account; there is no account parameter.
Revoked keys and inactive accounts cannot access settings.

```bash theme={null}
curl --fail-with-body https://www.deepface.dev/api/billing/spending-alerts \
  -H "Authorization: Bearer $DEEPFACE_API_KEY"

# Save the settings example above as settings.json first.
curl --fail-with-body -X PATCH https://www.deepface.dev/api/billing/spending-alerts \
  -H "Authorization: Bearer $DEEPFACE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @settings.json
```

`GET` and successful `PATCH` return a snapshot containing `settings`, usage
totals, the billing timezone and per-rule `spikeEvaluations` with baseline
readiness. `PATCH` replaces the **complete settings document**: read first,
edit the `settings` object, then submit it. Do not submit the entire snapshot.
Empty arrays remove all rules of that type. Invalid settings return HTTP 400
without writing. Invalid explicit credentials return HTTP 401 even if a browser
session is present. Responses are private and are not cached.

## Repository CLI

Use Node.js 24 in a deepface.dev repository checkout; no extra package or global
installation is required. Set `DEEPFACE_API_KEY` through your shell's secret
manager or environment. Keys are not accepted as command arguments.

```bash theme={null}
npm run --silent cli -- spending-alerts get
npm run --silent cli -- spending-alerts set --file settings.json
npm run --silent cli -- spending-alerts set --file - < settings.json
```

Commands return JSON and a nonzero exit status on failure.
`DEEPFACE_BASE_URL` optionally selects another deployment. HTTPS is required
except for HTTP loopback during local development. Redirects are rejected.

## MCP

Connect to `https://www.deepface.dev/mcp` with an MCP key.

| Tool | Arguments | Result |
| - | - | - |
| `get_spending_alerts` | `{}` | Current settings, usage and baseline readiness |
| `update_spending_alerts` | `{ "settings": { ... } }` | Snapshot after replacing the full settings document |

The `settings` argument uses the JSON shape above. Tools configure only the
MCP key's account. They cannot change the recipient, tariffs, spending cap or
another account's settings. Refresh the client's tool list after upgrading
an existing connection.