Request and Response Conventions
JSON in, JSON out, query parameters for everything else.
Content type
Requests and responses are JSON, with two exceptions: media uploads are multipart/form-data, and the public contact endpoint is form-encoded. The API never picks a format from your Accept header. When an endpoint can return something other than JSON, you ask with a query parameter such as ?dl=yaml.
What the methods mean
| Method | Meaning here |
|---|---|
| GET | Read. Site membership is enough. |
| POST | Create, or update an existing resource. Editor role required. |
| PATCH | Partial update -- send only the fields you are changing. |
| PUT | Wholesale replace. Used by artifact roles. |
| DELETE | Remove. Returns 204 with no body. |
Send the whole object on POST when you mean to replace a resource, and use PATCH when you only want to change a few fields.
Pagination
List endpoints return 50 items per page. Use ?page= and ?page_size=, up to a maximum of 200.
Request
curl -H "Authorization: Token $ENINE_TOKEN" \
"https://e9sites.com/api/v1/site/mysite.e9sites.com/artifacts/?page=2&page_size=25"
Response
{
"count": 137,
"next": "https://e9sites.com/api/v1/site/mysite.e9sites.com/artifacts/?page=3&page_size=25",
"previous": "https://e9sites.com/api/v1/site/mysite.e9sites.com/artifacts/?page=1&page_size=25",
"results": []
}
Not every list is paginated. The theme list, an artifact's tags, and the site AEO surface always return a bare array, and ?page_size=0 switches pagination off. Write your client to accept both a bare array and a count-and-results envelope.
Repeating a call
Assigning a tag or adding a role twice is safe -- those endpoints return the existing row instead of failing. There is no Idempotency-Key header.
Request volume
Batch your calls where you can, and avoid tight polling loops. If you need to move a lot of content at once, the export and import endpoints do it in a single call.