diff --git a/xos/api/README.md b/xos/api/README.md
index 459e049..c0244f0 100644
--- a/xos/api/README.md
+++ b/xos/api/README.md
@@ -1 +1,13 @@
-placeholder for readme
+## XOS REST API
+
+The XOS API importer is automatic and will search this subdirectory and its hierarchy of children for valid API methods. API methods that are descendents of the django View class are discovered automatically. This should include django_rest_framework based Views and Viewsets. This processing is handled by import_methods.py.
+
+A convention is established for locating API methods within the XOS hierarchy. The root of the api will automatically be /api/. Under that are the following paths:
+
+* `/api/service` ... API endpoints that are service-wide
+* `/api/tenant` ... API endpoints that are relative to a tenant within a service
+
+For example, `/api/tenant/cord/subscriber/` contains the Subscriber API for the CORD service. 
+
+The API importer will automatically construct REST paths based on where files are placed within the directory hierarchy. For example, the files in `xos/api/tenant/cord/` will automatically appear at the API endpoint `http://server_name/api/tenant/cord/`. 
+The directory `examples` contains examples that demonstrate using the API from the Linux command line.
diff --git a/xos/api/examples/README.md b/xos/api/examples/README.md
index 459e049..9fe584e 100644
--- a/xos/api/examples/README.md
+++ b/xos/api/examples/README.md
@@ -1 +1,13 @@
-placeholder for readme
+## XOS REST API Examples
+
+This directory contains examples that demonstrate using the XOS REST API using the `curl` command-line tool.
+
+To get started, edit `config.sh` so that it points to a valid XOS server.
+
+We recommend running the following examples in order:
+
+ * `add_subscriber.sh` ... add a cord subscriber using account number 1238
+ * `update_subscriber.sh` ... update the subscriber's upstream_bandwidth feature
+ * `add_volt_to_subscriber.sh` ... add a vOLT to the subscriber with s-tag 33 and c-tag 133
+ * `delete_volt_from_subscriber.sh` ... remove the vOLT from the subscriber
+ * `delete_subscriber.sh` ... delete the subscriber that has account number 1238