Overview

Frappe exposes every DocType and every whitelisted Python function over HTTP as a
JSON REST API. There is nothing to enable or scaffold. As soon as you define a
DocType or whitelist a method, it is callable over the network (subject to
Authentication and
permissions).

The API has two halves:

• Resource API: CRUD over DocTypes at /api/resource/<DocType>.
• Method API: RPC to whitelisted functions at /api/method/<dotted.path>.

Resource vs Method

/api/resource/<DocType>            # query / create a collection
/api/resource/<DocType>/<name>     # read / update / delete one document
/api/method/<dotted.path.to.fn>    # call a whitelisted function

Use the resource endpoints for standard document operations: list,
read, create, update, delete. The HTTP verb selects the operation:

Use the method endpoints when you need behaviour that isn't plain CRUD, like a
report, a bulk action, or a custom calculation. Any function decorated with
@frappe.whitelist() is reachable. See
Calling Methods and
Whitelisted Methods.

# Read a single ToDo
curl https://example.com/api/resource/ToDo/abc123 \
  -H "Authorization: token <api_key>:<api_secret>"

# Call a whitelisted function
curl https://example.com/api/method/frappe.client.get_count \
  -G --data-urlencode 'doctype=ToDo' \
  -H "Authorization: token <api_key>:<api_secret>"

API versions: v1 and v2

Frappe ships two API versions. The router mounts them like this (see
frappe/api/__init__.py):

/api/...           -> v1   (unversioned paths default to v1)
/api/v1/...        -> v1
/api/v2/...        -> v2

So /api/resource/ToDo and /api/v1/resource/ToDo are the same thing. v1 is the
unversioned default and is still used by most existing clients. For new
integrations, prefer v2. It has cleaner paths, simpler pagination, and built-in
bulk operations (see below).

What v2 changes

v2 uses different path segments and a cleaner contract. The main differences:

• The resource path is /api/v2/document/<DocType> (not /resource/), and
  the collection helpers live under /api/v2/doctype/<DocType>.
• Pagination uses start and limit (v1 uses limit_start and
  limit_page_length).
• List responses set has_next_page in the response so you can paginate
  without a separate count call.
• It adds first-class bulk operations plus count and meta endpoints.

v2 route map (from frappe/api/v2.py; not exhaustive):

Use v2 for new code. v1 is still supported and the examples across these pages
use the v1 paths, which map to the v2 endpoints above.

Response shape

Every JSON response wraps the payload in a data key:

{
  "data": { "name": "abc123", "status": "Open", "description": "Buy milk" }
}

List endpoints return an array under data. Errors return a non-2xx status with
an exc_type and a server message; with traceback logging on, an exception
field is included.

Next steps

• Authentication: get a token before you call anything
• Listing Documents: query collections
• Creating & Updating: write data
• Calling Methods: invoke whitelisted functions