The base URL
Every Core dna site answers on its own hostname under /cdna-api, and each module has a prefix below that: /cdna-api/pages, /cdna-api/blogs, /cdna-api/custom-entities. A prefix on its own is not an endpoint. The list of pages is /cdna-api/pages/pages, and one page is /cdna-api/pages/page/{id}. The hostname decides which site answers, so use the site's own.
1. Get a credential
Every request carries a credential in the Authorization header. Two kinds work:
- An OAuth access token, the preferred method. Register an OAuth client in the admin (Users › OAuth Authentication › Clients), sign in through the authorization code flow as the user the integration acts for, and keep the refresh token it returns. For an integration between servers, create a backend user for it with only the permissions it needs, and sign in as that user once. An access token lasts four hours, and the refresh token renews it.
- An API key, the older method. Added on a backend user's record in the admin, it works until it is deleted. Existing integrations can keep using it.
Both are sent the same way, as Authorization: Bearer YOUR_ACCESS_TOKEN, and both act as their user, with that user's permissions. Authentication has the requests for each.
2. Send a request
The request below lists two pages with three fields each. Add Accept: application/json to every request: without it, some errors come back as an HTML page instead of JSON.
3. Read the response
Every JSON response has result, either success or error. A list adds totalCount, the number of matches before paging. The records are in data: as the list itself when properties is a bare selector such as {id,name,fullPath}, and under the entity's plural, data.pages, without one. An error carries a message, and a failed validation a validationErrors object keyed by field. Requests and responses has every shape, the status codes, and the failures that still answer 200.
What the examples stand for
| In an example | Use |
|---|---|
https://hub.coredna.com | Your site's own hostname |
YOUR_ACCESS_TOKEN | An OAuth access token or an API key |
YOUR_SESSION_COOKIE, YOUR_CSRF_TOKEN | For a script on the site's own pages with someone signed in: the browser sends the cookie, and the token is _csrfToken in the page's template |
Ids, such as 1885 | Records on this documentation site. Use your own |
Each example says where its response came from. Real response from this documentation site means the request was sent to this site with the documentation's test user. Saved response from the Postman collection means it comes from the platform team's collection, with personal data replaced. An example with no response is a write that would change this site; its endpoint says what comes back. The tabs above an example show the same request as raw HTTP, cURL, PHP, Python and JavaScript, and Open in Postman docs opens it in the collection.
Versions, caching and cross-origin calls
- Versions. There is one API, at
/cdna-api; it changes with the platform. - 201 and 429. A create answers 200, and nothing is rate-limited.
- Cross-origin requests. The API sends no CORS headers, so a browser on another origin cannot read its responses. Call it from your server, or from pages on the site itself.
- Conditional requests. There are no ETags, and responses are not cached for you.
- Default paging. A list without
limitreturns every match, except jobs and custom entity records, which page by 100.