Ghost Admin API

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
  

# --- truncated at 32 KB (88 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ghost/refs/heads/main/openapi/ghost-admin-api-openapi.yml