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

> Explore Ghost's Admin API endpoints and routing pattern. Learn how Ghost uses Express routers to structure modular RESTful routes for CRUD operations and custom actions. Understand the admin API structure now.

- Repository: [Ghost/Ghost](https://github.com/TryGhost/Ghost)
- Tags: api-reference
- Published: 2026-05-18

---

**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`](https://github.com/TryGhost/Ghost/blob/main/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`](https://github.com/TryGhost/Ghost/blob/main/posts.js) and [`tags.js`](https://github.com/TryGhost/Ghost/blob/main/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`](https://github.com/TryGhost/Ghost/blob/main/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`](https://github.com/TryGhost/Ghost/blob/main/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`](https://github.com/TryGhost/Ghost/blob/main/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`](https://github.com/TryGhost/Ghost/blob/main/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:

```bash
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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/TryGhost/Ghost/blob/main/posts.js) and [`tags.js`](https://github.com/TryGhost/Ghost/blob/main/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`](https://github.com/TryGhost/Ghost/blob/main/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`](https://github.com/TryGhost/Ghost/blob/main/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`](https://github.com/TryGhost/Ghost/blob/main/posts.js), [`tags.js`](https://github.com/TryGhost/Ghost/blob/main/tags.js), and [`members.js`](https://github.com/TryGhost/Ghost/blob/main/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`](https://github.com/TryGhost/Ghost/blob/main/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.