From b19bf791a4e85c486dfa13e0f9ce0753fd80ff4c Mon Sep 17 00:00:00 2001
From: Jeremy Stretch <jstretch@digitalocean.com>
Date: Thu, 5 Jul 2018 11:58:07 -0400
Subject: [PATCH] Closes #2138: Added documentation for filtering on custom
 fields

---
 docs/api/overview.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/docs/api/overview.md b/docs/api/overview.md
index ba7e11bbf..85d972008 100644
--- a/docs/api/overview.md
+++ b/docs/api/overview.md
@@ -206,3 +206,28 @@ The maximum number of objects that can be returned is limited by the [`MAX_PAGE_
 
 !!! warning
     Disabling the page size limit introduces a potential for very resource-intensive requests, since one API request can effectively retrieve an entire table from the database.
+
+# Filtering
+
+A list of objects retrieved via the API can be filtered by passing one or more query parameters. The same parameters used by the web UI work for the API as well. For example, to return only prefixes with a status of "Active" (`1`):
+
+```
+GET /api/ipam/prefixes/?status=1
+```
+
+The same filter can be incldued multiple times. These will effect a logical OR and return objects matching any of the given values. For example, the following will return all active and reserved prefixes:
+
+```
+GET /api/ipam/prefixes/?status=1&status=2
+```
+
+## Custom Fields
+
+To filter on a custom field, prepend `cf_` to the field name. For example, the following query will return only sites where a custom field named `foo` is equal to 123:
+
+```
+GET /api/dcim/sites/?cf_foo=123
+```
+
+!!! note
+    Full versus partial matching when filtering is configurable per custom field. Filtering can be toggled (or disabled) for a custom field in the admin UI.