Spree Commerce Posts API

openapi: 3.0.3
info:
  title: Admin Account / Address Posts API
  contact:
    name: Spree Commerce
    url: https://spreecommerce.org
    email: hello@spreecommerce.org
  description: "Spree Admin API v3 - Administrative API for managing products, orders, and store settings.\n\n## Authentication\n\nThe Admin API requires a secret API key passed in the `x-spree-api-key` header.\nSecret API keys can be generated in the Spree admin dashboard.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\nSingle resource endpoints return a flat JSON object.\n\n## Resource IDs\n\nEvery resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,\n`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,\nrequest bodies, and Ransack filters all accept them directly.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n  \"error\": {\n    \"code\": \"validation_error\",\n    \"message\": \"Validation failed\",\n    \"details\": { \"name\": [\"can't be blank\"] }\n  }\n}\n```\n"
  version: v3
servers:
- url: http://{defaultHost}
  variables:
    defaultHost:
      default: localhost:3000
tags:
- name: Posts
paths:
  /api/v2/storefront/posts:
    get:
      summary: List all Posts
      description: Returns a list of published Posts. This endpoint is only available in Spree 5.2 or later.
      tags:
      - Posts
      operationId: posts-list
      parameters:
      - $ref: '#/components/parameters/FilterByIds'
      - in: query
        name: filter[title]
        schema:
          type: string
        example: Hello World
        description: Filter Posts by title
      - in: query
        name: filter[post_category_id]
        schema:
          type: string
        example: '1'
        description: Filter Posts by Post Category ID
      - in: query
        name: filter[post_category_slug]
        schema:
          type: string
        example: news
        description: Filter Posts by Post Category slug
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PerPageParam'
      - in: query
        name: sort
        schema:
          type: string
          enum:
          - id
          - -id
          - title
          - -title
          - published_at
          - -published_at
          - created_at
          - -created_at
          - updated_at
          - -updated_at
        example: -published_at
        description: 'Sort posts by attribute. Prefix with "-" for descending order. Available options: id, title, published_at, created_at, updated_at'
      - in: query
        name: include
        schema:
          type: string
        example: post_category
        description: 'Include related resources (available: post_category)'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Post'
                  meta:
                    $ref: '#/components/schemas/ListMeta'
                  links:
                    $ref: '#/components/schemas/ListLinks'
              examples:
                success:
                  value:
                    data:
                    - id: '1'
                      type: post
                      attributes:
                        title: Hello World
                        slug: hello-world
                        published_at: '2025-08-11T21:03:00.000Z'
                        meta_title: ''
                        meta_description: ''
                        created_at: '2025-08-11T21:03:00.128Z'
                        updated_at: '2025-08-27T10:09:23.007Z'
                        excerpt: null
                        content: This is a test post
                        content_html: <div class="trix-content">\n  <div>This is a test post</div>\n</div>\n
                        description: This is a test post
                        shortened_description: This is a test post
                        author_name: Spree Admin
                        post_category_title: News
                        tags: []
                        image_url: null
                      relationships:
                        post_category:
                          data:
                            id: '3'
                            type: post_category
                    meta:
                      count: 1
                      total_count: 1
                      total_pages: 1
                    links:
                      self: http://localhost:3000/api/v2/storefront/posts
                      next: http://localhost:3000/api/v2/storefront/posts?page=1
                      prev: http://localhost:3000/api/v2/storefront/posts?page=1
                      last: http://localhost:3000/api/v2/storefront/posts?page=1
                      first: http://localhost:3000/api/v2/storefront/posts?page=1
  /api/v2/storefront/posts/{id}:
    get:
      summary: Retrieve a Post
      description: Returns the details of a specified Post. You can use either the post slug or ID. This endpoint is only available in Spree 5.2 or later.
      tags:
      - Posts
      operationId: show-post
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        example: hello-world
        description: Post slug or ID
      - in: query
        name: include
        schema:
          type: string
        example: post_category
        description: 'Include related resources (available: post_category)'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Post'
              examples:
                success:
                  value:
                    data:
                      id: '1'
                      type: post
                      attributes:
                        title: Hello World
                        slug: hello-world
                        published_at: '2025-08-11T21:03:00.000Z'
                        meta_title: ''
                        meta_description: ''
                        created_at: '2025-08-11T21:03:00.128Z'
                        updated_at: '2025-08-27T10:09:23.007Z'
                        excerpt: null
                        content: This is a test post
                        content_html: <div class="trix-content">\n  <div>This is a test post</div>\n</div>\n
                        description: This is a test post
                        shortened_description: This is a test post
                        author_name: Spree Admin
                        post_category_title: News
                        tags: []
                        image_url: null
                      relationships:
                        post_category:
                          data:
                            id: '3'
                            type: post_category
        '404':
          $ref: '#/components/responses/404NotFound'
components:
  parameters:
    PageParam:
      name: page
      in: query
      description: Number of requested page when paginating collection
      schema:
        type: integer
      example: 1
    FilterByIds:
      in: query
      name: filter[ids]
      schema:
        type: string
      example: 1,2,3
      description: Fetch only resources with corresponding IDs
    PerPageParam:
      name: per_page
      in: query
      description: Number of requested records per page when paginating collection
      schema:
        type: integer
      example: 25
  schemas:
    Timestamp:
      type: string
      format: date-time
      example: '2020-02-16T07:14:54.617Z'
      x-internal: false
      title: Time Stamp
      x-examples:
        example-1: '2020-02-16T07:14:54.617Z'
    ListMeta:
      type: object
      x-internal: false
      title: Pagination Meta
      properties:
        count:
          type: number
          example: 7
          description: Number of items on the current listing
        total_count:
          type: number
          example: 145
          description: Number of all items matching the criteria
        total_pages:
          type: number
          example: 10
          description: Number of all pages containing items matching the criteria
    ListLinks:
      x-internal: false
      type: object
      title: Pagination Links
      properties:
        self:
          type: string
          description: URL to the current page of the listing
        next:
          type: string
          description: URL to the next page of the listing
        prev:
          type: string
          description: URL to the previous page of the listing
        last:
          type: string
          description: URL to the last page of the listing
        first:
          type: string
          description: URL to the first page of the listing
    Post:
      type: object
      title: Post
      description: Post represents a blog post or news article that can be displayed on the storefront.
      properties:
        id:
          type: string
          example: '1'
        type:
          type: string
          default: post
        attributes:
          type: object
          properties:
            title:
              type: string
              example: Hello World
              description: Title of the post
            slug:
              type: string
              example: hello-world
              description: URL-friendly identifier for the post
            published_at:
              type: string
              format: date-time
              example: '2025-08-11T21:03:00.000Z'
              description: Date and time when the post was published
              nullable: true
            meta_title:
              type: string
              example: ''
              description: SEO meta title
              nullable: true
            meta_description:
              type: string
              example: ''
              description: SEO meta description
              nullable: true
            created_at:
              $ref: '#/components/schemas/Timestamp'
            updated_at:
              $ref: '#/components/schemas/Timestamp'
            excerpt:
              type: string
              example: null
              description: Short excerpt of the post content
              nullable: true
            content:
              type: string
              example: This is a test post
              description: Plain text content of the post
              nullable: true
            content_html:
              type: string
              example: "<div class=\"trix-content\">\n  <div>This is a test post</div>\n</div>\n"
              description: HTML formatted content of the post
              nullable: true
            description:
              type: string
              example: This is a test post
              description: Description of the post
              nullable: true
            shortened_description:
              type: string
              example: This is a test post
              description: Shortened description of the post
              nullable: true
            author_name:
              type: string
              example: Spree Admin
              description: Name of the post author
              nullable: true
            post_category_title:
              type: string
              example: News
              description: Title of the associated post category
              nullable: true
            tags:
              type: array
              items:
                type: string
              example: []
              description: List of tags associated with the post
            image_url:
              type: string
              example: null
              description: URL of the post's featured image
              nullable: true
        relationships:
          type: object
          properties:
            post_category:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    id:
                      type: string
                      example: '3'
                    type:
                      type: string
                      example: post_category
          required:
          - title
          - slug
          - created_at
          - updated_at
      required:
      - id
      - type
      - attributes
  responses:
    404NotFound:
      description: 404 Not Found - Resource not found.
      content:
        application/vnd.api+json:
          schema:
            properties:
              error:
                type: string
                example: The resource you were looking for could not be found.
                default: The resource you were looking for could not be found.
          examples:
            404 Example:
              value:
                error: The resource you were looking for could not be found.
  securitySchemes:
    api_key:
      type: apiKey
      name: x-spree-api-key
      in: header
      description: Secret API key for admin access
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token for admin user authentication
x-tagGroups:
- name: Authentication
  tags:
  - Authentication
- name: Products & Catalog
  tags:
  - Products
  - Variants
  - Option Types
  - Custom Fields
  - Channels
- name: Pricing
  tags:
  - Pricing
  - Markets
- name: Orders & Fulfillment
  tags:
  - Orders
  - Payments
  - Fulfillments
  - Refunds
- name: Customers
  tags:
  - Customers
  - Customer Groups
- name: Promotions & Gift Cards
  tags:
  - Promotions
  - Gift Cards
- name: Data
  tags:
  - Exports
- name: Configuration
  tags:
  - Settings
  - Stock Locations
  - Payment Methods
  - Staff
  - API Keys
  - Allowed Origins
  - Webhooks