Ghost Admin API Endpoints and Routing Pattern: A Complete Technical Guide

Ghost structures its Admin API endpoints under the base path /ghost/api/admin/ (or versioned /ghost/api/v{major}/admin/), using Express routers in ghost/core/core/server/api/endpoints/ to register modular RESTful routes that support standard CRUD operations and custom sub-resource actions.

The TryGhost/Ghost repository implements a server-side HTTP interface that powers the Ghost admin UI and enables external administrative integrations. Understanding how Ghost organizes these endpoints and handles URL routing patterns is essential for developers extending the platform or building third-party tools.

Base URL Structure and Versioning

All Admin API endpoints share a common prefix and support both versioned and non-versioned access patterns. Clients can request resources using either format:

URL Type	Base Path	Example Endpoint
Non-versioned	/ghost/api/admin/	GET /ghost/api/admin/posts/
Versioned	/ghost/api/v{major}/admin/	GET /ghost/api/v4/admin/tags/

The versioned URLs are normalized to the internal non-versioned routes by the API version-compatibility middleware located at ghost/core/core/server/web/api/middleware/version-rewrites.js. This middleware rewrites incoming /ghost/api/vX/admin/ requests to /ghost/api/admin/ while preserving the requested version information in the request context for compatibility handling.

Route Registration Architecture

Individual endpoint definitions reside in the ghost/core/core/server/api/endpoints/ directory, where each resource maintains its own router file. Files such as posts.js and tags.js register their specific routes under the Admin API prefix, creating a modular structure that separates concerns by resource type.

The main Express application mounts these routers under the /ghost/api/admin/ base path, ensuring consistent middleware application across all administrative endpoints. This architecture is validated by test utilities in ghost/core/test/utils/e2e-framework.js, which references the apiURL: '/ghost/api/admin/' configuration used by automated test agents.

RESTful Resource Patterns and Special Actions

The Admin API follows RESTful conventions for standard CRUD operations while supporting resource-specific sub-actions through nested path segments.

Standard resource operations map HTTP verbs to collection and entity endpoints:

• List/Create: GET /ghost/api/admin/posts/ (list), POST /ghost/api/admin/tags/ (create)
• Read/Update/Delete: GET /ghost/api/admin/posts/:id/, PUT /ghost/api/admin/posts/:id/, DELETE /ghost/api/admin/posts/:id/

Special sub-resource actions extend this pattern for complex operations:

• POST /ghost/api/admin/posts/:id/copy/ duplicates an existing post
• GET /ghost/api/admin/emails/:id/batches/ retrieves email delivery batch data

These actions maintain predictable URL structures while handling specialized business logic outside standard CRUD semantics.

Version Compatibility Middleware

The routing system handles API versioning through middleware defined in ghost/core/core/server/web/api/middleware/version-rewrites.js. When processing versioned requests, this middleware performs three key functions:

1. Rewrites the URL path from /ghost/api/vX/admin/ to the internal /ghost/api/admin/ format
2. Stores the requested API version in the request context for downstream compatibility checks
3. Preserves query parameters and headers throughout the transformation

Unit tests in ghost/core/test/unit/server/web/api/middleware/mw-version-rewrites.test.js verify that this rewriting logic correctly maintains routing integrity across different API versions.

Limit-Capping Exceptions

Certain administrative endpoints bypass the global pagination limits enforced by the max-limit middleware to support bulk data operations. Endpoints such as /ghost/api/admin/posts/export/ and routes matching /emails/*/batches/ are specifically exempt from standard limit-capping rules.

The middleware logic, validated in ghost/core/test/unit/server/web/shared/middleware/max-limit-cap.test.js, selectively applies limits based on route patterns. This allows unrestricted exports while protecting standard list endpoints from resource exhaustion through excessive pagination parameters.

Practical API Examples

Fetching a list of posts requires an Admin API key in the authorization header:

curl -X GET "https://my-ghost-site.com/ghost/api/admin/posts/" \
     -H "Authorization: Ghost ${ADMIN_API_KEY}"

Creating a new tag via a versioned endpoint:

curl -X POST "https://my-ghost-site.com/ghost/api/v4/admin/tags/" \
     -H "Authorization: Ghost ${ADMIN_API_KEY}" \
     -H "Content-Type: application/json" \
     -d '{"tags":[{"name":"new-tag"}]}'

Executing special actions like copying a post:

curl -X POST "https://my-ghost-site.com/ghost/api/admin/posts/12345/copy/67890/" \
     -H "Authorization: Ghost ${ADMIN_API_KEY}"

Exporting posts without pagination limits:

curl -X GET "https://my-ghost-site.com/ghost/api/admin/posts/export/" \
     -H "Authorization: Ghost ${ADMIN_API_KEY}" \
     -o posts-export.json

Summary

• Ghost Admin API endpoints use a consistent base path of /ghost/api/admin/ with optional versioning via /ghost/api/v{major}/admin/.
• Routes are registered through modular Express routers in ghost/core/core/server/api/endpoints/, with each resource managing its own endpoint definitions in files like posts.js and tags.js.
• The version-rewrites middleware normalizes versioned URLs to internal routes while preserving version context for compatibility handling.
• Standard RESTful patterns support CRUD operations, while sub-resource actions such as /posts/:id/copy/ provide extended functionality through nested paths.
• Export and batch endpoints are exempt from global limit-capping rules, as verified by max-limit-cap.test.js, to facilitate bulk data operations.

Frequently Asked Questions

What is the base URL for Ghost Admin API endpoints?

All Ghost Admin API endpoints share the base path /ghost/api/admin/ for non-versioned requests, or /ghost/api/v{major}/admin/ when specifying an API version such as v4 or v5. The versioned URLs are automatically rewritten to the internal non-versioned format by the compatibility middleware while retaining the version information in the request headers.

How does Ghost handle API versioning in the routing pattern?

Ghost implements API versioning through middleware in ghost/core/core/server/web/api/middleware/version-rewrites.js that intercepts versioned requests, rewrites the URL path to the standard internal format, and stores the requested version in the request context. This allows the application to maintain backward compatibility using a single set of route definitions while supporting multiple API versions simultaneously.

Where are Admin API route definitions located in the Ghost codebase?

Route definitions are located in the ghost/core/core/server/api/endpoints/ directory, where individual files such as posts.js, tags.js, and members.js register resource-specific routes under the Admin API prefix. These endpoint modules are mounted by the main Express application, creating a modular architecture tested in ghost/core/test/unit/server/web/api/admin/middleware.test.js.

How do special actions like copying a post work in the Admin API routing pattern?

Special actions extend the standard RESTful pattern through sub-resource paths, such as POST /ghost/api/admin/posts/:id/copy/ for duplicating posts or GET /ghost/api/admin/emails/:id/batches/ for retrieving email batches. These endpoints follow the same authentication and versioning middleware as standard CRUD endpoints but execute specialized business logic defined in their respective endpoint modules.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}