
Table of contents
It's possible to create and manage your content using the Ghost Admin API. Our content management interface, Ghost Admin, uses the Admin API - which means that everything Ghost Admin can do is also possible with the API, and a whole lot more!
Secure authentication is available either as a User with role-based permissions, or as an integration with a single standard set of permissions designed to support common publishing workflows.
The API is RESTful with predictable resource URLs, standard HTTP verbs, response codes and authentication used throughout. Requests and responses are JSON-encoded with consistent patterns and inline relations and responses are customisable using powerful query parameters.
API Clients
JavaScript Client Library
We've developed an API client for JavaScript, that simplifies authenticating with the Admin API, and makes reading and writing data a breeze. The client is designed for use with integrations, supporting token authentication and the endpoints available to integrations.
Structure
Base URL
https://{admin_domain}/ghost/api/{version}/admin/
All Admin API requests start with this base URL.
Admin Domain
Your admin domain can be different to your main domain, and may include a subdirectory. Using the correct domain and protocol are critical to getting consistent behaviour, particularly when dealing with CORS in the browser. All Ghost(Pro) blogs have a *.ghost.io
domain as their admin domain and require https.
Version
Version strings are required and usually start with v
. The api versioning guide explains the current available versions and stability index. The Admin API also has a stability index for specific endpoints.
JSON Format
The API uses a consistent JSON structure for all requests and responses:
{
"resource_type": [{
...
}],
"meta": {}
}
resource_type
: will always match the resource name in the URL. All resources are returned wrapped in an array, with the exception of/site/
and/settings/
.meta
: contains pagination information for browse requests.
Composing requests
When composing JSON payloads to send to the API as POST or PUT requests, you must always use this same format, unless the documentation for an endpoint says otherwise.
Requests with JSON payloads require the Content-Type: application/json
header. Most request libraries have JSON-specific handling that will do this for you.
Pagination
All browse endpoints are paginated, returning 15 records by default. You can use the page and limit parameters to move through the pages of records. The response object contains a meta.pagination
key with information on the current location within the records:
"meta":{
"pagination":{
"page":1,
"limit":2,
"pages":1,
"total":1,
"next":null,
"prev":null
}
}
Parameters
Query parameters provide fine-grained control over responses. All endpoints accept include
and fields
. Browse endpoints additionally accept filter
, limit
, page
and order
. Some endpoints have their own specific parameters.
The values provided as query parameters MUST be url encoded when used directly. The client libraries will handle this for you.
Filtering
See the Content API.
Authentication
There are two methods for authenticating with the Admin API: token authentication and user authentication. Most applications integrating with the Ghost Admin API should use token authentication.
The JavaScript Admin API Client supports token authentication.
Choosing an authentication method
Token authentication is intended for integrations that handle common workflows, such as publishing new content, or sharing content to other platforms.
Using tokens, you authenticate as an integration. Each integration can have associated API keys & webhooks and are able to perform API requests independently of users. Admin API keys are used to generate short-lived single-use JSON Web Tokens (JWTs), which are then used to authenticate a request. The API Key is secret, and therefore this authentication method is only suitable for secure server side environments.
User authentication is intended for fully-fledged clients where different users login and manage various resources as themselves.
Using an email address and password, you authenticate as a specific user, with their role-based permissions. Via the session API, credentials are swapped for a cookie-based session, which is then used to authenticate further API requests. Provided that passwords are entered securely, user-authentication is safe for use in the browser.
Permissions
Integrations have a restricted set of fixed permissions allowing access to certain endpoints e.g. GET /users/
or POST /posts/
. The full set of endpoints that integrations can access are those listed as endpoints on this page.
User permissions are dependent entirely on their role. You can find more details in the team management guide. Authenticating as a user with the Owner or Admin role will give access to the full set of API endpoints. Many endpoints can be discovered by inspecting the requests made by Ghost Admin, the endpoints listed on this page are those stable enough to document.
Token Authentication
Token authentication is a simple, secure authentication mechanism using JSON Web Tokens (JWTs) to authenticate as an integration. Each integration is issued with an admin API key, which is used to generate a JWT token and then provided to the API via the standard HTTP Authorization header.
The Admin API key must be kept private, therefore token authentication is not suitable for browsers or other insecure environments, unlike the Content API key.
Key
Admin API keys can be obtained by creating a new Custom Integration
under the Integrations screen in Ghost Admin.

Admin API keys are made up of an id and secret, separated by a colon. These values are used separately to get a signed JWT token, which is used in the Authorization header of the request:
curl -H "Authorization: Ghost $token" https://{admin_domain}/ghost/api/{version}/admin/{resource}/
The Admin API JavaScript client handles all the technical details of generating a JWT from an Admin API key, meaning you only have to provide your url, version and key to start making requests.
Leave a comment