Guide 06 · Developer docs

The APIs: REST, GraphQL and custom endpoints

Every Core dna site answers three kinds of API request under /cdna-api: REST for everything, GraphQL for reads that span several entity types, and web events for endpoints you define yourself as jobs. Which fits which task, one worked request for each, and what is true of all three. Jobs were called hooks until the module was renamed Orchestration; the API's routes still use the old name.

L1–L3

Unit 01 of 07 8 pages

The REST API

Updated 23/10/2026 01:49

How the REST API is laid out, so that you can predict an endpoint instead of looking it up, then its parameters, its answers and the checks that confirm a request did what you asked. For anyone who reads or writes records over REST.

Read the first page before the others: it gives the rule that turns a module and an entity into a path, the handful of prefixes that are exceptions to it, and the six requests every entity gets. The next three pages are about reading: narrowing a list, choosing the fields that come back, and where each parameter travels when a selector grows long. Then what comes back, the envelope, the status codes and validation errors, and the two forms a related record may take in a payload.

Read the page on checks before you trust a filtered list or a write: name fields exactly, and compare counts to confirm a filter took effect. The last page says where each record's real shape is written down. How a write changes versioned content (revisions, areas, collections, custom fields) has a unit of its own, Writing content, which comes next.

In this unit

Read in order

01 Predicting an endpoint Every module answers under /cdna-api on a predictable prefix, and every entity gets the same requests from the same generic controllers. The rule, the handful of prefixes that differ from it, and the standard set, so you can write a request without looking it up. 02 Filters, ordering and paging Everything in a list's query string that is not a shared parameter is a filter on the entity's own fields. How to write one, how to page and order a list, and the two habits that keep a filter honest: check it against a count, and always send a limit. 03 Shaping the response with properties One parameter decides what a response contains: properties, a selector that names fields, renames them, reaches into relations and calls getters with arguments. How to write one, what shape the response then takes, and how a mistake shows up, which is not as an error. 04 Query string or request body Where each part of a request goes: filters and paging in the query string, the record in the body, and properties in either, depending on the method. The long selector that does not fit in a URL, and the one client that cannot send it. 05 Responses and errors Every JSON answer has the same envelope, and the status codes mean the same thing everywhere. What each code tells a client to do, the 401 that has no body, the 403 that means “refresh your token”, and how to put a validation error next to the field that caused it. 06 A relation as an id or an object A payload can set a relation with a bare id or with an object carrying one, and both do the same thing. What the neighbouring forms do, which is not the same thing at all: an object with more fields edits the related record, and one without an id creates a new one. 07 Confirming a request did what you asked What to send for each kind of request, and the checks that confirm a read or a write did what you asked. Each one below was reproduced on this site. 08 The generated documentation What a record looks like in a response is declared in the platform's code, and the documentation of it is generated from that declaration. Which pages are generated, which are written by hand, and which to trust first when they differ.