From 54d92713b2941055c99960d4a0a62d515d2e4b52 Mon Sep 17 00:00:00 2001
From: Arun <ANONYMOUSZED-beep@users.noreply.github.com>
Date: Sun, 16 Aug 2026 10:59:55 +0000
Subject: [PATCH] docs: add Python API examples

---
 docs/src/atomicserver/API.md | 94 ++++++++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)

diff --git a/docs/src/atomicserver/API.md b/docs/src/atomicserver/API.md
index 36d2bd41df..4e93be68cd 100644
--- a/docs/src/atomicserver/API.md
+++ b/docs/src/atomicserver/API.md
@@ -29,6 +29,100 @@ Typically, you pass query parameters to these endpoints to specify what you want
 
 <!-- We have a subset of the [API documented using Swagger / OpenAPI](https://editor.swagger.io/?url=https://raw.githubusercontent.com/atomicdata-dev/atomic-server/master/server/openapi.yml). -->
 
+## Python example
+
+AtomicServer does not require a Python-specific SDK for reading public data. You can use any HTTP client; the examples below use [`requests`](https://requests.readthedocs.io/).
+
+Install it with:
+
+```sh
+python -m pip install requests
+```
+
+### Fetch a resource as JSON-AD
+
+Every Atomic Data resource is available at its subject URL. Set the `Accept` header to request JSON-AD explicitly:
+
+```python
+import requests
+
+JSON_AD = "application/ad+json"
+RESOURCE_URL = "https://atomicdata.dev/properties/shortname"
+
+response = requests.get(
+    RESOURCE_URL,
+    headers={"Accept": JSON_AD},
+    timeout=10,
+)
+response.raise_for_status()
+resource = response.json()
+
+print(resource["@id"])
+print(resource["https://atomicdata.dev/properties/shortname"])
+```
+
+For a local server, replace the resource URL with one hosted by your instance, such as `http://localhost:9883/`.
+
+### Search resources
+
+The `/search` endpoint supports full-text search through the `q` parameter. `limit` controls the maximum number of results, while `include=true` includes the matched resources in the JSON-AD response instead of returning only their subjects.
+
+```python
+import requests
+
+SERVER_URL = "https://atomicdata.dev"
+
+response = requests.get(
+    f"{SERVER_URL}/search",
+    params={
+        "q": "atomic data",
+        "limit": 10,
+        "include": "true",
+    },
+    headers={"Accept": "application/ad+json"},
+    timeout=10,
+)
+response.raise_for_status()
+search_results = response.json()
+
+# Endpoint responses can contain multiple JSON-AD resources.
+resources = search_results if isinstance(search_results, list) else [search_results]
+for resource in resources:
+    print(resource.get("@id"))
+```
+
+The endpoint also accepts `parents` (a comma-separated list of ancestor resource URLs) and `filters` (a Tantivy query expression) to narrow results.
+
+### Query resources by property
+
+Use `/query` to create a dynamic Collection. Query parameter names match the shortnames documented for [Atomic Collections](../schema/collections.md). For example, this query returns resources whose `isA` property points to the Property class:
+
+```python
+import requests
+
+SERVER_URL = "https://atomicdata.dev"
+IS_A = "https://atomicdata.dev/properties/isA"
+PROPERTY_CLASS = "https://atomicdata.dev/classes/Property"
+
+response = requests.get(
+    f"{SERVER_URL}/query",
+    params={
+        "property": IS_A,
+        "value": PROPERTY_CLASS,
+        "page_size": 10,
+        "current_page": 0,
+    },
+    headers={"Accept": "application/ad+json"},
+    timeout=10,
+)
+response.raise_for_status()
+collection = response.json()
+
+print(collection)
+```
+
+Public resources can be read without authentication. Private resources require a signed authentication request. Creating or changing resources requires a signed [Atomic Commit](../commits/intro.md) containing a Loro CRDT update; use a supported [client or SDK](../tooling.md) rather than posting ordinary JSON directly.
+
 ## Libraries or API?
 
 You can use the REST API if you want, but it's recommended to use one of our [libraries](../tooling.md).