openapi: 3.1.0 info: title: Ghost Admin API description: >- The Ghost Admin API provides full read and write access to all content and configuration within a Ghost publication. It enables developers to create, update, and delete posts, pages, tags, members, tiers, newsletters, and offers programmatically. Authentication is handled via JSON Web Tokens generated from an Admin API key, integration tokens, or staff access tokens. The Admin API supports everything the Ghost Admin interface can do and more, making it suitable for building custom publishing workflows, content automation, member management systems, and advanced integrations. version: '5.0' contact: name: Ghost Foundation url: https://ghost.org/docs/admin-api/ termsOfService: https://ghost.org/terms/ externalDocs: description: Ghost Admin API Documentation url: https://ghost.org/docs/admin-api/ servers: - url: https://{site}.ghost.io/ghost/api/admin description: Ghost Pro Hosted Site variables: site: default: your-site description: Your Ghost site subdomain - url: '{protocol}://{domain}/ghost/api/admin' description: Self-Hosted Ghost Instance variables: protocol: default: https enum: - https - http domain: default: localhost:2368 description: Your Ghost instance domain and port tags: - name: Images description: >- Upload images to the Ghost publication for use in posts, pages, and settings. - name: Members description: >- Manage publication members including creating, reading, updating, and deleting member records. Members are people who have signed up for the publication. - name: Newsletters description: >- Manage email newsletters that members can subscribe to. Each newsletter has its own design, sender details, and subscription list. - name: Offers description: >- Manage promotional offers for paid membership tiers, including discounts and trial periods. - name: Pages description: >- Create, read, update, and delete pages. Pages share the same structure as posts but are used for static content. - name: Posts description: >- Create, read, update, and delete posts. Posts are the primary content resource in Ghost and support rich content via the Lexical editor format. - name: Site description: >- Read basic information about the Ghost site. - name: Themes description: >- Upload, activate, and manage themes that control the front-end appearance of the Ghost publication. - name: Tiers description: >- Manage membership tiers including creating, reading, and updating tier configurations with pricing and benefits. - name: Users description: >- Read staff user accounts for the Ghost publication. - name: Webhooks description: >- Create, update, and delete webhooks that send HTTP POST notifications when events occur within the publication. security: - adminApiToken: [] paths: /posts/: get: operationId: adminBrowsePosts summary: Browse posts description: >- Retrieve a paginated list of posts with all statuses including draft, scheduled, and published. Supports filtering, ordering, and including related resources. tags: - Posts parameters: - $ref: '#/components/parameters/includePostRelations' - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/filter' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/order' - $ref: '#/components/parameters/formats' responses: '200': description: A list of posts content: application/json: schema: type: object properties: posts: type: array items: $ref: '#/components/schemas/Post' meta: $ref: '#/components/schemas/PaginationMeta' '401': $ref: '#/components/responses/Unauthorized' post: operationId: adminCreatePost summary: Create a post description: >- Create a new post. The title field is required, all other fields are optional and will have defaults applied. Content can be provided in Lexical or HTML format. Tags can be specified by name or as full tag objects. If a tag does not exist, it will be created automatically. tags: - Posts requestBody: required: true content: application/json: schema: type: object required: - posts properties: posts: type: array items: $ref: '#/components/schemas/PostInput' minItems: 1 maxItems: 1 responses: '201': description: Post created successfully content: application/json: schema: type: object properties: posts: type: array items: $ref: '#/components/schemas/Post' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/ValidationError' /posts/{id}/: get: operationId: adminReadPost summary: Read a post by ID description: >- Retrieve a single post by its unique identifier, including draft and scheduled posts. tags: - Posts parameters: - $ref: '#/components/parameters/resourceId' - $ref: '#/components/parameters/includePostRelations' - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/formats' responses: '200': description: A single post content: application/json: schema: type: object properties: posts: type: array items: $ref: '#/components/schemas/Post' minItems: 1 maxItems: 1 '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' put: operationId: adminUpdatePost summary: Update a post description: >- Update an existing post. The updated_at field must be sent with the current value to prevent update collisions. Only the fields being changed need to be included in the request body, along with updated_at. tags: - Posts parameters: - $ref: '#/components/parameters/resourceId' requestBody: required: true content: application/json: schema: type: object required: - posts properties: posts: type: array items: $ref: '#/components/schemas/PostInput' minItems: 1 maxItems: 1 responses: '200': description: Post updated successfully content: application/json: schema: type: object properties: posts: type: array items: $ref: '#/components/schemas/Post' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': description: Update collision due to stale updated_at value content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': $ref: '#/components/responses/ValidationError' delete: operationId: adminDeletePost summary: Delete a post description: >- Permanently delete a post by its unique identifier. tags: - Posts parameters: - $ref: '#/components/parameters/resourceId' responses: '204': description: Post deleted successfully '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /pages/: get: operationId: adminBrowsePages summary: Browse pages description: >- Retrieve a paginated list of pages including draft and published pages. tags: - Pages parameters: - $ref: '#/components/parameters/includePostRelations' - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/filter' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/order' - $ref: '#/components/parameters/formats' responses: '200': description: A list of pages content: application/json: schema: type: object properties: pages: type: array items: $ref: '#/components/schemas/Post' meta: $ref: '#/components/schemas/PaginationMeta' '401': $ref: '#/components/responses/Unauthorized' post: operationId: adminCreatePage summary: Create a page description: >- Create a new page. Pages share the same structure as posts and require a title field. tags: - Pages requestBody: required: true content: application/json: schema: type: object required: - pages properties: pages: type: array items: $ref: '#/components/schemas/PostInput' minItems: 1 maxItems: 1 responses: '201': description: Page created successfully content: application/json: schema: type: object properties: pages: type: array items: $ref: '#/components/schemas/Post' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/ValidationError' /pages/{id}/: get: operationId: adminReadPage summary: Read a page by ID description: >- Retrieve a single page by its unique identifier. tags: - Pages parameters: - $ref: '#/components/parameters/resourceId' - $ref: '#/components/parameters/includePostRelations' - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/formats' responses: '200': description: A single page content: application/json: schema: type: object properties: pages: type: array items: $ref: '#/components/schemas/Post' minItems: 1 maxItems: 1 '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' put: operationId: adminUpdatePage summary: Update a page description: >- Update an existing page. The updated_at field must be included to prevent update collisions. tags: - Pages parameters: - $ref: '#/components/parameters/resourceId' requestBody: required: true content: application/json: schema: type: object required: - pages properties: pages: type: array items: $ref: '#/components/schemas/PostInput' minItems: 1 maxItems: 1 responses: '200': description: Page updated successfully content: application/json: schema: type: object properties: pages: type: array items: $ref: '#/components/schemas/Post' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': description: Update collision due to stale updated_at value content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': $ref: '#/components/responses/ValidationError' delete: operationId: adminDeletePage summary: Delete a page description: >- Permanently delete a page by its unique identifier. tags: - Pages parameters: - $ref: '#/components/parameters/resourceId' responses: '204': description: Page deleted successfully '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /tags/: get: operationId: adminBrowseTags summary: Browse tags description: >- Retrieve a paginated list of all tags, including internal tags. tags: [] parameters: - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/filter' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/order' responses: '200': description: A list of tags content: application/json: schema: type: object properties: tags: type: array items: $ref: '#/components/schemas/Tag' meta: $ref: '#/components/schemas/PaginationMeta' '401': $ref: '#/components/responses/Unauthorized' post: operationId: adminCreateTag summary: Create a tag description: >- Create a new tag. The name field is required. Tags with names starting with a hash character are treated as internal tags. tags: [] requestBody: required: true content: application/json: schema: type: object required: - tags properties: tags: type: array items: $ref: '#/components/schemas/TagInput' minItems: 1 maxItems: 1 responses: '201': description: Tag created successfully content: application/json: schema: type: object properties: tags: type: array items: $ref: '#/components/schemas/Tag' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/ValidationError' /tags/{id}/: get: operationId: adminReadTag summary: Read a tag by ID description: >- Retrieve a single tag by its unique identifier. tags: [] parameters: - $ref: '#/components/parameters/resourceId' - $ref: '#/components/parameters/fields' responses: '200': description: A single tag content: application/json: schema: type: object properties: tags: type: array items: $ref: '#/components/schemas/Tag' minItems: 1 maxItems: 1 '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' put: operationId: adminUpdateTag summary: Update a tag description: >- Update an existing tag by its unique identifier. tags: [] parameters: - $ref: '#/components/parameters/resourceId' requestBody: required: true content: application/json: schema: type: object required: - tags properties: tags: type: array items: $ref: '#/components/schemas/TagInput' minItems: 1 maxItems: 1 responses: '200': description: Tag updated successfully content: application/json: schema: type: object properties: tags: type: array items: $ref: '#/components/schemas/Tag' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationError' delete: operationId: adminDeleteTag summary: Delete a tag description: >- Permanently delete a tag by its unique identifier. tags: [] parameters: - $ref: '#/components/parameters/resourceId' responses: '204': description: Tag deleted successfully '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /members/: get: operationId: adminBrowseMembers summary: Browse members description: >- Retrieve a paginated list of publication members. Supports filtering by status, label, newsletter subscription, and other member properties. tags: - Members parameters: - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/filter' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/order' responses: '200': description: A list of members content: application/json: schema: type: object properties: members: type: array items: $ref: '#/components/schemas/Member' meta: $ref: '#/components/schemas/PaginationMeta' '401': $ref: '#/components/responses/Unauthorized' post: operationId: adminCreateMember summary: Create a member description: >- Create a new member. The email field is required. Optionally include name, labels, and newsletter subscriptions. tags: - Members requestBody: required: true content: application/json: schema: type: object required: - members properties: members: type: array items: $ref: '#/components/schemas/MemberInput' minItems: 1 maxItems: 1 responses: '201': description: Member created successfully content: application/json: schema: type: object properties: members: type: array items: $ref: '#/components/schemas/Member' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/ValidationError' /members/{id}/: get: operationId: adminReadMember summary: Read a member by ID description: >- Retrieve a single member by their unique identifier. tags: - Members parameters: - $ref: '#/components/parameters/resourceId' - $ref: '#/components/parameters/fields' responses: '200': description: A single member content: application/json: schema: type: object properties: members: type: array items: $ref: '#/components/schemas/Member' minItems: 1 maxItems: 1 '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' put: operationId: adminUpdateMember summary: Update a member description: >- Update an existing member by their unique identifier. Can be used to change name, email, labels, note, and newsletter subscriptions. tags: - Members parameters: - $ref: '#/components/parameters/resourceId' requestBody: required: true content: application/json: schema: type: object required: - members properties: members: type: array items: $ref: '#/components/schemas/MemberInput' minItems: 1 maxItems: 1 responses: '200': description: Member updated successfully content: application/json: schema: type: object properties: members: type: array items: $ref: '#/components/schemas/Member' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationError' delete: operationId: adminDeleteMember summary: Delete a member description: >- Permanently delete a member by their unique identifier. tags: - Members parameters: - $ref: '#/components/parameters/resourceId' responses: '204': description: Member deleted successfully '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /tiers/: get: operationId: adminBrowseTiers summary: Browse tiers description: >- Retrieve a paginated list of membership tiers. tags: - Tiers parameters: - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/filter' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/page' responses: '200': description: A list of tiers content: application/json: schema: type: object properties: tiers: type: array items: $ref: '#/components/schemas/Tier' meta: $ref: '#/components/schemas/PaginationMeta' '401': $ref: '#/components/responses/Unauthorized' post: operationId: adminCreateTier summary: Create a tier description: >- Create a new membership tier with pricing, benefits, and visibility configuration. tags: - Tiers requestBody: required: true content: application/json: schema: type: object required: - tiers properties: tiers: type: array items: $ref: '#/components/schemas/TierInput' minItems: 1 maxItems: 1 responses: '201': description: Tier created successfully content: application/json: schema: type: object properties: tiers: type: array items: $ref: '#/components/schemas/Tier' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/ValidationError' /tiers/{id}/: get: operationId: adminReadTier summary: Read a tier by ID description: >- Retrieve a single membership tier by its unique identifier. tags: - Tiers parameters: - $ref: '#/components/parameters/resourceId' - $ref: '#/components/parameters/fields' responses: '200': description: A single tier content: application/json: schema: type: object properties: tiers: type: array items: $ref: '#/components/schemas/Tier' minItems: 1 maxItems: 1 '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' put: operationId: adminUpdateTier summary: Update a tier description: >- Update an existing membership tier by its unique identifier. tags: - Tiers parameters: - $ref: '#/components/parameters/resourceId' requestBody: required: true content: application/json: schema: type: object required: - tiers properties: tiers: type: array items: $ref: '#/components/schemas/TierInput' minItems: 1 maxItems: 1 responses: '200': description: Tier updated successfully content: application/json: schema: type: object properties: tiers: type: array items: $ref: '#/components/schemas/Tier' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationError' /newsletters/: get: operationId: adminBrowseNewsletters summary: Browse newsletters description: >- Retrieve a list of all newsletters configured for the publication. tags: - Newsletters parameters: - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/filter' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/order' responses: '200': description: A list of newsletters content: application/json: schema: type: object properties: newsletters: type: array items: $ref: '#/components/schemas/Newsletter' meta: $ref: '#/components/schemas/PaginationMeta' '401': $ref: '#/components/responses/Unauthorized' post: operationId: adminCreateNewsletter summary: Create a newsletter description: >- Create a new newsletter for the publication with customizable design, sender details, and subscription settings. tags: - Newsletters requestBody: required: true content: application/json: schema: type: object required: - newsletters properties: newsletters: type: array items: $ref: '#/components/schemas/NewsletterInput' minItems: 1 maxItems: 1 responses: '201': description: Newsletter created successfully content: application/json: schema: type: object properties: newsletters: type: array items: $ref: '#/components/schemas/Newsletter' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/ValidationError' /newsletters/{id}/: get: operationId: adminReadNewsletter summary: Read a newsletter by ID description: >- Retrieve a single newsletter by its unique identifier. tags: - Newsletters parameters: - $ref: '#/components/parameters/resourceId' - $ref: '#/components/parameters/fields' responses: '200': description: A single newsletter content: application/json: schema: type: object properties: newsletters: type: array items: $ref: '#/components/schemas/Newsletter' minItems: 1 maxItems: 1 '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' put: operationId: adminUpdateNewsletter summary: Update a newsletter description: >- Update an existing newsletter by its unique identifier. tags: - Newsletters parameters: - $ref: '#/components/parameters/resourceId' requestBody: required: true content: application/json: schema: type: object required: - newsletters properties: newsletters: type: array items: $ref: '#/components/schemas/NewsletterInput' minItems: 1 maxItems: 1 responses: '200': description: Newsletter updated successfully content: application/json: schema: type: object properties: newsletters: type: array items: $ref: '#/components/schemas/Newsletter' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationError' /offers/: get: operationId: adminBrowseOffers summary: Browse offers description: >- Retrieve a list of all promotional offers configured for the publication. tags: - Offers parameters: - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/filter' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/page' responses: '200': description: A list of offers content: application/json: schema: type: object properties: offers: type: array items: $ref: '#/components/schemas/Offer' meta: $ref: '#/components/schemas/PaginationMeta' '401': $ref: '#/components/responses/Unauthorized' post: operationId: adminCreateOffer summary: Create an offer description: >- Create a new promotional offer for a paid membership tier, including percentage or fixed amount discounts and trial periods. tags: - Offers requestBody: required: true content: application/json: schema: type: object required: - offers properties: offers: type: array items: $ref: '#/components/schemas/OfferInput' minItems: 1 maxItems: 1 responses: '201': description: Offer created successfully content: application/json: schema: type: object properties: offers: type: array items: $ref: '#/components/schemas/Offer' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/ValidationError' /offers/{id}/: get: operationId: adminReadOffer summary: Read an offer by ID description: >- Retrieve a single offer by its unique identifier. tags: - Offers parameters: - $ref: '#/components/parameters/resourceId' - $ref: '#/components/parameters/fields' responses: '200': description: A single offer content: application/json: schema: type: object properties: offers: type: array items: $ref: '#/components/schemas/Offer' minItems: 1 maxItems: 1 '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' put: operationId: adminUpdateOffer summary: Update an offer description: >- Update an existing offer by its unique identifier. tags: - Offers parameters: - $ref: '#/components/parameters/resourceId' requestBody: required: true content: application/json: schema: type: object required: - offers properties: offers: type: array items: $ref: '#/components/schemas/OfferInput' minItems: 1 maxItems: 1 responses: '200': description: Offer updated successfully content: application/json: schema: type: object properties: offers: type: array items: $ref: '#/components/schemas/Offer' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationError' /users/: get: operationId: adminBrowseUsers summary: Browse users description: >- Retrieve a paginated list of staff users for the publication. tags: - Users parameters: - name: include in: query required: false description: >- Include related resources. Supports count.posts and roles. schema: type: string - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/filter' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/order' responses: '200': description: A list of users content: application/json: schema: type: object properties: users: type: array items: $ref: '#/components/schemas/User' meta: $ref: '#/components/schemas/PaginationMeta' '401': $ref: '#/components/responses/Unauthorized' /users/{id}/: get: operationId: adminReadUser summary: Read a user by ID description: >- Retrieve a single staff user by their unique identifier. tags: - Users parameters: - $ref: '#/components/parameters/resourceId' - $ref: '#/components/parameters/fields' responses: '200': description: A single user content: application/json: schema: type: object properties: users: type: array items: $ref: '#/components/schemas/User' minItems: 1 maxItems: 1 '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /webhooks/: post: operationId: adminCreateWebhook summary: Create a webhook description: >- Create a new webhook subscription that will send HTTP POST notifications to the specified target URL when the specified event occurs. Webhooks must be associated with an integration. tags: - Webhooks requestBody: required: true content: application/json: schema: type: object required: - webhooks properties: webhooks: type: array items: $ref: '#/components/schemas/WebhookInput' minItems: 1 maxItems: 1 responses: '201': description: Webhook created successfully content: application/json: schema: type: object properties: webhooks: type: array items: $ref: '#/components/schemas/Webhook' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/ValidationError' /webhooks/{id}/: put: operationId: adminUpdateWebhook summary: Update a webhook description: >- Update an existing webhook subscription by its unique identifier. tags: - Webhooks parameters: - $ref: '#/components/parameters/resourceId' requestBody: required: true content: application/json: schema: type: object required: - webhooks properties: webhooks: type: array items: $ref: '#/components/schemas/WebhookInput' minItems: 1 maxItems: 1 responses: '200': description: Webhook updated successfully content: application/json: schema: type: object properties: webhooks: type: array items: $ref: '#/components/schemas/Webhook' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationError' delete: operationId: adminDeleteWebhook summary: Delete a webhook description: >- Permanently delete a webhook subscription by its unique identifier. tags: - Webhooks parameters: - $ref: '#/components/parameters/resourceId' responses: '204': description: Webhook deleted successfully '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /images/upload/: post: operationId: adminUploadImage summary: Upload an image description: >- Upload an image file to the Ghost publication. The image is uploaded as multipart form data and the response includes the URL where the image can be accessed. tags: - Images requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: The image file to upload purpose: type: string description: >- Purpose of the image, such as image, profile_image, or icon enum: - image - profile_image - icon ref: type: string description: Reference identifier for the image responses: '201': description: Image uploaded successfully content: application/json: schema: type: object properties: images: type: array items: type: object properties: url: type: string format: uri description: URL of the uploaded image ref: type: string description: Reference identifier nullable: true '401': $ref: '#/components/responses/Unauthorized' '415': description: Unsupported media type content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': $ref: '#/components/responses/ValidationError' /themes/upload/: post: operationId: adminUploadTheme summary: Upload a theme description: >- Upload a new theme as a zip file to the Ghost publication. tags: - Themes requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: The theme zip file to upload responses: '201': description: Theme uploaded successfully content: application/json: schema: type: object properties: themes: type: array items: $ref: '#/components/schemas/Theme' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/ValidationError' /themes/{name}/activate/: put: operationId: adminActivateTheme summary: Activate a theme description: >- Activate an installed theme by its name, making it the active front-end theme for the publication. tags: - Themes parameters: - name: name in: path required: true description: The name of the theme to activate schema: type: string responses: '200': description: Theme activated successfully content: application/json: schema: type: object properties: themes: type: array items: $ref: '#/components/schemas/Theme' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /site/: get: operationId: adminReadSite summary: Read site information description: >- Retrieve basic information about the Ghost site including title, URL, version, and other configuration details. tags: - Site responses: '200': description: Site information content: application/json: schema: type: object properties: site: $ref: '#/components/schemas/Site' '401': $ref: '#/components/responses/Unauthorized' components: securitySchemes: adminApiToken: type: http scheme: bearer bearerFormat: JWT description: >- JSON Web Token generated from an Admin API key. The key is split into an ID and secret at the colon separator. The ID is used as the kid header and the secret is used to sign the token with HS256. parameters: resourceId: name: id in: path required: true description: The unique identifier of the resource schema: type: string format: uuid includePostRelations: name: include in: query required: false description: >- Comma-separated list of related resources to include. Supported values are authors and tags. schema: type: string fields: name: fields in: query required: false description: >- Comma-separated list of fields to return in the response. schema: type: string filter: name: filter in: query required: false description: >- Apply fine-grained filters using Ghost's NQL query language. schema: type: string limit: name: limit in: query required: false description: >- Maximum number of resources to return per page. Defaults to 15. schema: oneOf: - type: integer minimum: 1 - type: string enum: - all default: 15 page: name: page in: query required: false description: >- Page number for paginated results. Defaults to 1. schema: type: integer minimum: 1 default: 1 order: name: order in: query required: false description: >- Field and direction to order results by. schema: type: string formats: name: formats in: query required: false description: >- Comma-separated list of content formats to include in the response. schema: type: string responses: Unauthorized: description: Authentication failed or token is missing or invalid content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: The requested resource was not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ValidationError: description: Request body validation failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' schemas: Post: type: object description: >- A post or page resource with all content, metadata, and relationships. properties: id: type: string format: uuid description: Unique identifier uuid: type: string format: uuid description: Universally unique identifier title: type: string description: Title of the post slug: type: string description: URL-safe slug lexical: type: string description: Post content in Lexical editor format (JSON string) html: type: string description: Rendered HTML content plaintext: type: string description: Plain text content comment_id: type: string description: Commenting system identifier feature_image: type: string format: uri description: Featured image URL nullable: true feature_image_alt: type: string description: Alt text for the featured image nullable: true feature_image_caption: type: string description: Caption for the featured image nullable: true featured: type: boolean description: Whether the post is featured status: type: string description: Publication status enum: - published - draft - scheduled - sent visibility: type: string description: Access visibility level enum: - public - members - paid - tiers created_at: type: string format: date-time description: Creation timestamp updated_at: type: string format: date-time description: Last update timestamp published_at: type: string format: date-time description: Publication timestamp nullable: true custom_excerpt: type: string description: Custom excerpt nullable: true codeinjection_head: type: string description: Code injection in the page head nullable: true codeinjection_foot: type: string description: Code injection in the page foot nullable: true custom_template: type: string description: Custom Handlebars template name nullable: true canonical_url: type: string format: uri description: Canonical URL nullable: true url: type: string format: uri description: Full URL on the Ghost site excerpt: type: string description: Auto-generated excerpt reading_time: type: integer description: Estimated reading time in minutes minimum: 0 email_subject: type: string description: Custom email newsletter subject nullable: true frontmatter: type: string description: Custom frontmatter nullable: true og_image: type: string format: uri nullable: true description: Open Graph image URL og_title: type: string nullable: true description: Open Graph title og_description: type: string nullable: true description: Open Graph description twitter_image: type: string format: uri nullable: true description: Twitter card image URL twitter_title: type: string nullable: true description: Twitter card title twitter_description: type: string nullable: true description: Twitter card description meta_title: type: string nullable: true description: SEO meta title meta_description: type: string nullable: true description: SEO meta description tags: type: array description: Associated tags items: $ref: '#/components/schemas/Tag' authors: type: array description: Post authors items: $ref: '#/components/schemas/User' primary_author: $ref: '#/components/schemas/User' description: Primary author primary_tag: $ref: '#/components/schemas/Tag' nullable: true description: Primary tag email: type: object description: Email newsletter delivery details nullable: true properties: id: type: string format: uuid description: Email record identifier opened_count: type: integer description: Number of email opens minimum: 0 PostInput: type: object description: >- Input fields for creating or updating a post or page. properties: title: type: string description: Title of the post slug: type: string description: Custom URL slug lexical: type: string description: Content in Lexical editor format (JSON string) html: type: string description: Content in HTML format, converted to Lexical on save status: type: string description: Publication status enum: - published - draft - scheduled visibility: type: string description: Access visibility level enum: - public - members - paid - tiers featured: type: boolean description: Whether the post is featured feature_image: type: string format: uri description: Featured image URL nullable: true feature_image_alt: type: string description: Alt text for the featured image nullable: true feature_image_caption: type: string description: Caption for the featured image nullable: true custom_excerpt: type: string description: Custom excerpt nullable: true codeinjection_head: type: string description: Code injection in the head nullable: true codeinjection_foot: type: string description: Code injection in the foot nullable: true custom_template: type: string description: Custom template name nullable: true canonical_url: type: string format: uri description: Canonical URL nullable: true published_at: type: string format: date-time description: Scheduled publication time nullable: true updated_at: type: string format: date-time description: Required for updates to prevent collisions tags: type: array description: Tags to associate, can be name strings or tag objects items: oneOf: - type: object properties: name: type: string slug: type: string - $ref: '#/components/schemas/Tag' authors: type: array description: Authors to associate items: type: object properties: id: type: string format: uuid slug: type: string email: type: string format: email email_subject: type: string description: Custom email newsletter subject nullable: true og_image: type: string format: uri nullable: true description: Open Graph image URL og_title: type: string nullable: true description: Open Graph title og_description: type: string nullable: true description: Open Graph description twitter_image: type: string format: uri nullable: true description: Twitter card image URL twitter_title: type: string nullable: true description: Twitter card title twitter_description: type: string nullable: true description: Twitter card description meta_title: type: string nullable: true description: SEO meta title meta_description: type: string nullable: true description: SEO meta description Tag: type: object description: >- A tag for organizing and categorizing content. properties: id: type: string format: uuid description: Unique identifier name: type: string description: Tag name slug: type: string description: URL-safe slug description: type: string description: Tag description nullable: true feature_image: type: string format: uri description: Featured image URL nullable: true visibility: type: string description: Visibility setting enum: - public - internal og_image: type: string format: uri nullable: true description: Open Graph image URL og_title: type: string nullable: true description: Open Graph title og_description: type: string nullable: true description: Open Graph description twitter_image: type: string format: uri nullable: true description: Twitter card image URL twitter_title: type: string nullable: true description: Twitter card title twitter_description: type: string nullable: true description: Twitter card description meta_title: type: string nullable: true description: SEO meta title meta_description: type: string nullable: true description: SEO meta description codeinjection_head: type: string nullable: true description: Code injection in the head codeinjection_foot: type: string nullable: true description: Code injection in the foot canonical_url: type: string format: uri nullable: true description: Canonical URL accent_color: type: string nullable: true description: Accent color hex code pattern: '^#[0-9a-fA-F]{6}$' url: type: string format: uri description: Full URL of the tag page created_at: type: string format: date-time description: Creation timestamp updated_at: type: string format: date-time description: Last update timestamp TagInput: type: object description: >- Input fields for creating or updating a tag. required: - name properties: name: type: string description: Tag name, prefix with hash for internal tags slug: type: string description: Custom URL slug description: type: string description: Tag description nullable: true feature_image: type: string format: uri description: Featured image URL nullable: true visibility: type: string description: Visibility setting enum: - public - internal meta_title: type: string nullable: true description: SEO meta title meta_description: type: string nullable: true description: SEO meta description accent_color: type: string nullable: true description: Accent color hex code pattern: '^#[0-9a-fA-F]{6}$' Member: type: object description: >- A member represents a person who has signed up for the publication, either as a free or paid subscriber. properties: id: type: string format: uuid description: Unique identifier uuid: type: string format: uuid description: Universally unique identifier email: type: string format: email description: Member email address name: type: string description: Member display name nullable: true note: type: string description: Internal note about the member nullable: true geolocation: type: string description: Geolocation data from signup nullable: true status: type: string description: Member status based on subscription state enum: - free - paid - comped labels: type: array description: Labels applied to the member items: $ref: '#/components/schemas/Label' subscriptions: type: array description: Paid subscriptions associated with the member items: $ref: '#/components/schemas/Subscription' newsletters: type: array description: Newsletters the member is subscribed to items: type: object properties: id: type: string format: uuid description: Newsletter identifier name: type: string description: Newsletter name status: type: string description: Subscription status avatar_image: type: string format: uri description: Gravatar URL for the member email_count: type: integer description: Number of emails sent to this member minimum: 0 email_opened_count: type: integer description: Number of emails opened by this member minimum: 0 email_open_rate: type: number description: Email open rate percentage nullable: true minimum: 0 maximum: 100 created_at: type: string format: date-time description: Signup timestamp updated_at: type: string format: date-time description: Last update timestamp MemberInput: type: object description: >- Input fields for creating or updating a member. properties: email: type: string format: email description: Member email address name: type: string description: Member display name nullable: true note: type: string description: Internal note about the member nullable: true labels: type: array description: Labels to apply to the member items: type: object properties: name: type: string description: Label name slug: type: string description: Label slug newsletters: type: array description: Newsletter subscriptions items: type: object properties: id: type: string format: uuid description: Newsletter identifier Label: type: object description: >- A label for categorizing and segmenting members. properties: id: type: string format: uuid description: Unique identifier name: type: string description: Label name slug: type: string description: URL-safe slug created_at: type: string format: date-time description: Creation timestamp updated_at: type: string format: date-time description: Last update timestamp Subscription: type: object description: >- A paid subscription associated with a member, typically managed through Stripe. properties: id: type: string description: Subscription identifier customer: type: object description: Stripe customer details properties: id: type: string description: Stripe customer ID name: type: string description: Customer name nullable: true email: type: string format: email description: Customer email status: type: string description: Subscription status enum: - active - trialing - canceled - unpaid - past_due start_date: type: string format: date-time description: Subscription start date default_payment_card_last4: type: string description: Last 4 digits of the payment card nullable: true pattern: '^\d{4}$' cancel_at_period_end: type: boolean description: Whether the subscription cancels at period end cancellation_reason: type: string description: Reason for cancellation nullable: true current_period_end: type: string format: date-time description: End of current billing period price: type: object description: Price details properties: id: type: string description: Stripe price ID price_id: type: string description: Ghost price identifier nickname: type: string description: Price nickname amount: type: integer description: Amount in smallest currency unit minimum: 0 interval: type: string description: Billing interval enum: - month - year type: type: string description: Price type currency: type: string description: ISO 4217 currency code pattern: '^[A-Z]{3}$' tier: $ref: '#/components/schemas/Tier' Tier: type: object description: >- A membership tier with pricing and benefits configuration. properties: id: type: string format: uuid description: Unique identifier name: type: string description: Tier name slug: type: string description: URL-safe slug description: type: string description: Tier description nullable: true active: type: boolean description: Whether the tier is active type: type: string description: Tier type enum: - free - paid welcome_page_url: type: string format: uri description: Welcome page URL after signup nullable: true visibility: type: string description: Public visibility enum: - public - none monthly_price: type: integer description: Monthly price in smallest currency unit nullable: true minimum: 0 yearly_price: type: integer description: Yearly price in smallest currency unit nullable: true minimum: 0 currency: type: string description: ISO 4217 currency code nullable: true pattern: '^[A-Z]{3}$' trial_days: type: integer description: Number of free trial days minimum: 0 benefits: type: array description: Tier benefits items: type: string created_at: type: string format: date-time description: Creation timestamp updated_at: type: string format: date-time description: Last update timestamp TierInput: type: object description: >- Input fields for creating or updating a tier. required: - name properties: name: type: string description: Tier name description: type: string description: Tier description nullable: true active: type: boolean description: Whether the tier is active visibility: type: string description: Public visibility enum: - public - none welcome_page_url: type: string format: uri description: Welcome page URL nullable: true monthly_price: type: integer description: Monthly price in smallest currency unit minimum: 0 yearly_price: type: integer description: Yearly price in smallest currency unit minimum: 0 currency: type: string description: ISO 4217 currency code pattern: '^[A-Z]{3}$' trial_days: type: integer description: Number of free trial days minimum: 0 benefits: type: array description: Tier benefits items: type: string Newsletter: type: object description: >- A newsletter that members can subscribe to for email delivery of content. properties: id: type: string format: uuid description: Unique identifier uuid: type: string format: uuid description: Universally unique identifier name: type: string description: Newsletter name slug: type: string description: URL-safe slug description: type: string description: Newsletter description nullable: true sender_name: type: string description: Display name of the email sender nullable: true sender_email: type: string format: email description: Email address used as the sender nullable: true sender_reply_to: type: string description: Reply-to email setting enum: - newsletter - support status: type: string description: Newsletter status enum: - active - archived visibility: type: string description: Who can subscribe to this newsletter subscribe_on_signup: type: boolean description: Whether new members are automatically subscribed sort_order: type: integer description: Display order of the newsletter minimum: 0 header_image: type: string format: uri description: Header image URL nullable: true show_header_icon: type: boolean description: Whether to show the publication icon in the header show_header_title: type: boolean description: Whether to show the publication title in the header show_header_name: type: boolean description: Whether to show the newsletter name in the header title_font_category: type: string description: Font category for titles enum: - serif - sans_serif title_alignment: type: string description: Title alignment enum: - center - left show_feature_image: type: boolean description: Whether to show featured images body_font_category: type: string description: Font category for body text enum: - serif - sans_serif footer_content: type: string description: Custom footer content nullable: true show_badge: type: boolean description: Whether to show the Ghost badge show_latest_posts: type: boolean description: Whether to show latest posts background_color: type: string description: Background color border_color: type: string description: Border color nullable: true title_color: type: string description: Title color nullable: true created_at: type: string format: date-time description: Creation timestamp updated_at: type: string format: date-time description: Last update timestamp NewsletterInput: type: object description: >- Input fields for creating or updating a newsletter. required: - name properties: name: type: string description: Newsletter name description: type: string description: Newsletter description nullable: true sender_name: type: string description: Display name of the sender nullable: true sender_email: type: string format: email description: Sender email address nullable: true sender_reply_to: type: string description: Reply-to setting enum: - newsletter - support status: type: string description: Newsletter status enum: - active - archived subscribe_on_signup: type: boolean description: Auto-subscribe new members sort_order: type: integer description: Display order minimum: 0 header_image: type: string format: uri nullable: true description: Header image URL show_header_icon: type: boolean description: Show publication icon show_header_title: type: boolean description: Show publication title show_header_name: type: boolean description: Show newsletter name title_font_category: type: string enum: - serif - sans_serif description: Title font category body_font_category: type: string enum: - serif - sans_serif description: Body font category show_feature_image: type: boolean description: Show featured images show_badge: type: boolean description: Show Ghost badge background_color: type: string description: Background color border_color: type: string nullable: true description: Border color title_color: type: string nullable: true description: Title color Offer: type: object description: >- A promotional offer for a paid membership tier. properties: id: type: string format: uuid description: Unique identifier name: type: string description: Internal name for the offer code: type: string description: URL-safe code used in the offer link display_title: type: string description: Public-facing title shown to visitors display_description: type: string description: Public-facing description nullable: true type: type: string description: Discount type enum: - percent - fixed - trial cadence: type: string description: Which billing cadence the offer applies to enum: - month - year amount: type: integer description: >- Discount amount. For percent type this is a percentage (1-100). For fixed type this is in the smallest currency unit. For trial type this is the number of days. minimum: 0 duration: type: string description: How long the discount applies enum: - once - repeating - forever - trial duration_in_months: type: integer description: Number of months for repeating duration nullable: true minimum: 1 currency_restriction: type: boolean description: Whether the offer has a currency restriction currency: type: string description: Currency for the offer nullable: true pattern: '^[A-Z]{3}$' status: type: string description: Offer status enum: - active - archived redemption_count: type: integer description: Number of times the offer has been redeemed minimum: 0 tier: $ref: '#/components/schemas/Tier' created_at: type: string format: date-time description: Creation timestamp updated_at: type: string format: date-time description: Last update timestamp OfferInput: type: object description: >- Input fields for creating or updating an offer. required: - name - code - display_title - type - cadence - amount - duration - tier properties: name: type: string description: Internal name code: type: string description: URL-safe code display_title: type: string description: Public-facing title display_description: type: string description: Public-facing description nullable: true type: type: string enum: - percent - fixed - trial description: Discount type cadence: type: string enum: - month - year description: Billing cadence amount: type: integer description: Discount amount minimum: 0 duration: type: string enum: - once - repeating - forever - trial description: Discount duration duration_in_months: type: integer description: Months for repeating duration nullable: true minimum: 1 currency: type: string description: Currency code for fixed discounts nullable: true pattern: '^[A-Z]{3}$' status: type: string enum: - active - archived description: Offer status tier: type: object description: Tier to apply the offer to required: - id properties: id: type: string format: uuid description: Tier identifier User: type: object description: >- A staff user account in the Ghost publication. properties: id: type: string format: uuid description: Unique identifier name: type: string description: Display name slug: type: string description: URL-safe slug email: type: string format: email description: Email address profile_image: type: string format: uri description: Profile image URL nullable: true cover_image: type: string format: uri description: Cover image URL nullable: true bio: type: string description: Biography nullable: true website: type: string format: uri description: Personal website URL nullable: true location: type: string description: Location nullable: true facebook: type: string description: Facebook username nullable: true twitter: type: string description: Twitter handle nullable: true accessibility: type: string description: Accessibility settings JSON nullable: true status: type: string description: User account status enum: - active - inactive - locked meta_title: type: string nullable: true description: SEO meta title meta_description: type: string nullable: true description: SEO meta description tour: type: string description: Onboarding tour progress JSON nullable: true last_seen: type: string format: date-time description: Last login timestamp nullable: true url: type: string format: uri description: Full URL of the author page roles: type: array description: Assigned roles items: type: object properties: id: type: string format: uuid description: Role identifier name: type: string description: Role name description: type: string description: Role description created_at: type: string format: date-time description: Account creation timestamp updated_at: type: string format: date-time description: Last update timestamp Webhook: type: object description: >- A webhook subscription that sends HTTP POST notifications for events. properties: id: type: string format: uuid description: Unique identifier event: type: string description: The event that triggers the webhook target_url: type: string format: uri description: URL that receives the webhook POST request name: type: string description: Webhook name nullable: true secret: type: string description: Secret used for signature validation nullable: true api_version: type: string description: API version for the webhook payload integration_id: type: string format: uuid description: Integration this webhook belongs to status: type: string description: Webhook status last_triggered_at: type: string format: date-time description: Timestamp of the last trigger nullable: true last_triggered_status: type: string description: HTTP status from the last trigger nullable: true last_triggered_error: type: string description: Error from the last trigger attempt nullable: true created_at: type: string format: date-time description: Creation timestamp updated_at: type: string format: date-time description: Last update timestamp WebhookInput: type: object description: >- Input fields for creating or updating a webhook. required: - event - target_url properties: event: type: string description: >- The event to subscribe to. Available events include site.changed, post.added, post.deleted, post.edited, post.published, post.published.edited, post.unpublished, post.scheduled, post.unscheduled, post.rescheduled, page.added, page.deleted, page.edited, page.published, page.published.edited, page.unpublished, page.scheduled, page.unscheduled, page.rescheduled, tag.added, tag.edited, tag.deleted, post.tag.attached, post.tag.detached, page.tag.attached, page.tag.detached, member.added, member.edited, member.deleted. enum: - site.changed - post.added - post.deleted - post.edited - post.published - post.published.edited - post.unpublished - post.scheduled - post.unscheduled - post.rescheduled - page.added - page.deleted - page.edited - page.published - page.published.edited - page.unpublished - page.scheduled - page.unscheduled - page.rescheduled - tag.added - tag.edited - tag.deleted - post.tag.attached - post.tag.detached - page.tag.attached - page.tag.detached - member.added - member.edited - member.deleted target_url: type: string format: uri description: URL to receive webhook POST requests name: type: string description: Webhook name nullable: true secret: type: string description: Secret for signature validation nullable: true Theme: type: object description: >- A Ghost theme controlling the front-end appearance. properties: name: type: string description: Theme name package: type: object description: Theme package.json metadata properties: name: type: string description: Package name version: type: string description: Package version active: type: boolean description: Whether this is the currently active theme Site: type: object description: >- Basic information about the Ghost site. properties: title: type: string description: Site title description: type: string description: Site description logo: type: string format: uri description: Site logo URL nullable: true icon: type: string format: uri description: Site icon URL nullable: true accent_color: type: string description: Accent color nullable: true url: type: string format: uri description: Site URL version: type: string description: Ghost version PaginationMeta: type: object description: Pagination metadata properties: pagination: type: object properties: page: type: integer description: Current page minimum: 1 limit: type: integer description: Items per page minimum: 1 pages: type: integer description: Total pages minimum: 1 total: type: integer description: Total items minimum: 0 next: type: integer description: Next page number nullable: true prev: type: integer description: Previous page number nullable: true ErrorResponse: type: object description: Standard Ghost API error response properties: errors: type: array items: type: object properties: message: type: string description: Human-readable error message type: type: string description: Error type identifier context: type: string description: Additional error context nullable: true