> ## Documentation Index
> Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Posts

> Search blog posts using full-text search with intelligent relevance scoring and filtering options.

Search blog posts using advanced full-text search capabilities across titles and content, with intelligent relevance scoring to surface the most relevant results first.

**Search Algorithm**: The search engine performs comprehensive full-text indexing across post titles, body content, and summary fields using natural language processing. Results are ranked by relevance score, taking into account factors like keyword frequency, title matches, content quality signals, and publication recency.

**Content Scope**: The search indexes all published post content including titles, body text, summary fields, and associated metadata. Draft and scheduled posts are excluded from search results unless you're using preview mode through other endpoints.

**Result Optimization**: Returns complete post objects with calculated relevance scores by default. Use the `exclude_body=true` parameter when building search result pages to significantly reduce response size and improve loading performance, particularly for mobile applications.

**Performance Features**: Search results are automatically cached to ensure fast response times for repeated queries. The search index is updated in real-time as content is published, ensuring fresh results without manual reindexing.


## OpenAPI

````yaml /api/openapi/read_api.yaml get /posts/search/
openapi: 3.1.0
info:
  title: ButterCMS Read API
  version: 2.0.0
  description: >
    Read endpoints for the ButterCMS API — Pages, Collections, Blog Posts, Blog
    Metadata, and Feeds.
  contact:
    email: support@buttercms.com
  license:
    name: ButterCMS Terms of Service
    url: https://buttercms.com/terms/
servers:
  - url: https://api.buttercms.com/v2
    description: ButterCMS API v2
security:
  - readTokenAuthHeader: []
  - readTokenAuthQuery: []
tags:
  - name: Pages
    description: >
      Retrieve pages from your ButterCMS account.


      **Single Pages**: Use `*` as the page_type to get Single Pages (those
      without a Page Type) which represent unique pages on your site like your
      Homepage. Useful for creating your sitemap.xml.


      **Page Type Pages**: Use the actual page type slug to get pages of that
      specific type. Page Types allow you to create many pages with the same
      structure.


      **Note:** The fields of a page are defined by you, they are customizable.
      Sample responses below contain a basic set of fields for illustrative
      purposes.
  - name: Collections
    description: >
      Retrieve collection items from your ButterCMS account. Collections are
      flexible, user-defined content structures with completely customizable
      field schemas.


      See also: Architecture & Performance for guidance on `levels`, pagination,
      and performance best practices.
  - name: Blog posts
    description: >
      Retrieve blog posts from your ButterCMS account. List blog posts with
      pagination and filtering options, or retrieve individual posts by slug.
  - name: Blog metadata
    description: >
      Retrieve blog-related metadata including authors, categories, and tags.
      These endpoints provide access to the organizational structure of your
      blog content.
  - name: Feeds and utilities
    description: >
      Generate XML feeds for content syndication and SEO.


      - **RSS Feed**: Fully generated RSS 2.0 feed for your blog

      - **Atom Feed**: Standards-compliant Atom 1.0 feed

      - **Sitemap**: XML sitemap for search engine discovery


      All feeds can be filtered by category or tag and include only published
      content from your organization.
  - name: Images - Info
    description: >
      ButterCMS has an integration with
      [Filestack](https://www.filestack.com/docs/api/processing/) for image
      transformations. You can leverage their robust set of image transformation
      capabilities.


      After you upload an image, to create a thumbnail, here's an example:


      - **Original URL**: `https://cdn.buttercms.com/3ccPHhYHTNK2zQ14gCOy`

      - **Thumbnail URL**:
      `https://cdn.buttercms.com/resize=width:100,height:100/3ccPHhYHTNK2zQ14gCOy`


      For complete transformation options and parameters, see the [full
      Filestack documentation](https://www.filestack.com/docs/api/processing/).
paths:
  /posts/search/:
    get:
      tags:
        - Blog posts
      summary: Search Posts
      description: >
        Search blog posts using advanced full-text search capabilities across
        titles and content, with intelligent relevance scoring to surface the
        most relevant results first.


        **Search Algorithm**: The search engine performs comprehensive full-text
        indexing across post titles, body content, and summary fields using
        natural language processing. Results are ranked by relevance score,
        taking into account factors like keyword frequency, title matches,
        content quality signals, and publication recency.


        **Content Scope**: The search indexes all published post content
        including titles, body text, summary fields, and associated metadata.
        Draft and scheduled posts are excluded from search results unless you're
        using preview mode through other endpoints.


        **Result Optimization**: Returns complete post objects with calculated
        relevance scores by default. Use the `exclude_body=true` parameter when
        building search result pages to significantly reduce response size and
        improve loading performance, particularly for mobile applications.


        **Performance Features**: Search results are automatically cached to
        ensure fast response times for repeated queries. The search index is
        updated in real-time as content is published, ensuring fresh results
        without manual reindexing.
      operationId: searchPosts
      parameters:
        - name: query
          in: query
          required: false
          schema:
            type: string
            maxLength: 100
            default: ''
          description: >
            Search query string to find matching blog posts.


            The search will look for matches in both post titles and body
            content. Uses natural language processing for best results. If empty
            or not provided, no results will be returned.
          example: API development best practices
        - name: locale
          in: query
          description: >
            Search only posts in the given locale (e.g. `en`, `es`). When
            omitted, searches posts in your organization's default locale.


            Returns `400` if the value is not a locale configured on your
            organization.
          required: false
          schema:
            type: string
            maxLength: 10
          example: en
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/page_size'
        - $ref: 93cf2c7e-75ce-4beb-b455-38e9541bd339
        - $ref: 86c8b313-f5c9-4a9e-9b7a-5b789f6e0aae
        - name: exclude_body
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: >
            Exclude the full blog post body content from results to reduce
            response size.


            When set to `true`, the response will omit the `body` field from
            each post object, making responses faster and lighter for cases
            where only post metadata is needed.
          example: false
        - $ref: '#/components/parameters/auth_token'
      responses:
        '200':
          description: Search completed successfully
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/PageBasedSearchResponse'
                  - $ref: '#/components/schemas/OffsetBasedSearchResponse'
              examples:
                search_results:
                  summary: Search results with relevance ranking
                  value:
                    meta:
                      count: 2
                      next_page: null
                      previous_page: null
                    data:
                      - url: >-
                          https://api.buttercms.com/blog/api-development-best-practices
                        created: '2024-01-15T08:30:00.000Z'
                        published: '2024-01-15T10:00:00.000Z'
                        author:
                          first_name: John
                          last_name: Developer
                          email: john@buttercms.com
                          slug: john-developer
                          bio: Senior API Developer with 10+ years experience
                          title: Senior Developer
                          linkedin_url: https://linkedin.com/in/johndeveloper
                          facebook_url: null
                          twitter_handle: johndev
                          profile_image: https://cdn.buttercms.com/authors/john-developer.jpg
                        categories:
                          - name: Development
                            slug: development
                        tags:
                          - name: API
                            slug: api
                          - name: Best Practices
                            slug: best-practices
                        featured_image: https://cdn.buttercms.com/featured/api-guide.jpg
                        featured_image_alt: API Development Guide
                        slug: api-development-best-practices
                        title: API Development Best Practices for 2024
                        body: >-
                          <h2>Introduction</h2><p>Building robust APIs requires
                          following established best practices...</p>
                        summary: >-
                          Learn the essential best practices for building
                          scalable and maintainable APIs in 2024.
                        seo_title: API Development Best Practices for 2024
                        meta_description: >-
                          Complete guide to API development best practices
                          including REST design, authentication, and
                          documentation.
                        status: published
                        rank: 0.8573
                      - url: >-
                          https://api.buttercms.com/blog/rest-api-design-principles
                        created: '2024-01-10T14:20:00.000Z'
                        published: '2024-01-12T09:00:00.000Z'
                        author:
                          first_name: Sarah
                          last_name: Architect
                          email: sarah@buttercms.com
                          slug: sarah-architect
                          bio: API Architect specializing in distributed systems
                          title: API Architect
                          linkedin_url: https://linkedin.com/in/saraharchitect
                          facebook_url: null
                          twitter_handle: sarahapi
                          profile_image: >-
                            https://cdn.buttercms.com/authors/sarah-architect.jpg
                        categories:
                          - name: Architecture
                            slug: architecture
                        tags:
                          - name: REST
                            slug: rest
                          - name: API Design
                            slug: api-design
                        featured_image: https://cdn.buttercms.com/featured/rest-design.jpg
                        featured_image_alt: REST API Design
                        slug: rest-api-design-principles
                        title: RESTful API Design Principles
                        body: >-
                          <h2>Core Principles</h2><p>RESTful API design follows
                          key principles that ensure scalability...</p>
                        summary: >-
                          Master the fundamental principles of RESTful API
                          design for better developer experience.
                        seo_title: RESTful API Design Principles
                        meta_description: >-
                          Learn the core principles of REST API design for
                          building intuitive and scalable web services.
                        status: published
                        rank: 0.7234
                offset_search_results:
                  summary: Search results with offset-based pagination
                  description: Using ?limit=5&offset=0 parameters
                  value:
                    meta:
                      count: 2
                      next_offset: null
                      previous_offset: null
                    data:
                      - url: >-
                          https://api.buttercms.com/blog/api-development-best-practices
                        created: '2024-01-15T08:30:00.000Z'
                        published: '2024-01-15T10:00:00.000Z'
                        author:
                          first_name: John
                          last_name: Developer
                          email: john@buttercms.com
                          slug: john-developer
                          bio: Senior API Developer with 10+ years experience
                          title: Senior Developer
                          linkedin_url: https://linkedin.com/in/johndeveloper
                          facebook_url: null
                          twitter_handle: johndev
                          profile_image: https://cdn.buttercms.com/authors/john-developer.jpg
                        categories:
                          - name: Development
                            slug: development
                        tags:
                          - name: API
                            slug: api
                          - name: Best Practices
                            slug: best-practices
                        featured_image: https://cdn.buttercms.com/featured/api-guide.jpg
                        featured_image_alt: API Development Guide
                        slug: api-development-best-practices
                        title: API Development Best Practices for 2024
                        body: >-
                          <h2>Introduction</h2><p>Building robust APIs requires
                          following established best practices...</p>
                        summary: >-
                          Learn the essential best practices for building
                          scalable and maintainable APIs in 2024.
                        seo_title: API Development Best Practices for 2024
                        meta_description: >-
                          Complete guide to API development best practices
                          including REST design, authentication, and
                          documentation.
                        status: published
                        rank: 0.8573
                      - url: >-
                          https://api.buttercms.com/blog/rest-api-design-principles
                        created: '2024-01-10T14:20:00.000Z'
                        published: '2024-01-12T09:00:00.000Z'
                        author:
                          first_name: Sarah
                          last_name: Architect
                          email: sarah@buttercms.com
                          slug: sarah-architect
                          bio: API Architect specializing in distributed systems
                          title: API Architect
                          linkedin_url: https://linkedin.com/in/saraharchitect
                          facebook_url: null
                          twitter_handle: sarahapi
                          profile_image: >-
                            https://cdn.buttercms.com/authors/sarah-architect.jpg
                        categories:
                          - name: Architecture
                            slug: architecture
                        tags:
                          - name: REST
                            slug: rest
                          - name: API Design
                            slug: api-design
                        featured_image: https://cdn.buttercms.com/featured/rest-design.jpg
                        featured_image_alt: REST API Design
                        slug: rest-api-design-principles
                        title: RESTful API Design Principles
                        body: >-
                          <h2>Core Principles</h2><p>RESTful API design follows
                          key principles that ensure scalability...</p>
                        summary: >-
                          Master the fundamental principles of RESTful API
                          design for better developer experience.
                        seo_title: RESTful API Design Principles
                        meta_description: >-
                          Learn the core principles of REST API design for
                          building intuitive and scalable web services.
                        status: published
                        rank: 0.7234
                no_results:
                  summary: No search results found
                  value:
                    meta:
                      previous_page: null
                      next_page: null
                      count: 0
                    data: []
                excluded_body:
                  summary: Search results with body content excluded
                  value:
                    meta:
                      count: 1
                      next_page: null
                      previous_page: null
                    data:
                      - url: https://api.buttercms.com/blog/api-development-guide
                        created: '2024-01-15T08:30:00.000Z'
                        published: '2024-01-15T10:00:00.000Z'
                        author:
                          first_name: John
                          last_name: Developer
                          email: john@buttercms.com
                          slug: john-developer
                          bio: Senior API Developer
                          title: Senior Developer
                          linkedin_url: https://linkedin.com/in/johndeveloper
                          facebook_url: null
                          twitter_handle: johndev
                          profile_image: https://cdn.buttercms.com/authors/john.jpg
                        categories:
                          - name: Development
                            slug: development
                        tags:
                          - name: API
                            slug: api
                        featured_image: https://cdn.buttercms.com/featured/api.jpg
                        featured_image_alt: API Development
                        slug: api-development-guide
                        title: Complete API Development Guide
                        summary: Everything you need to know about API development.
                        seo_title: API Development Guide
                        meta_description: Complete guide to API development best practices.
                        status: published
                        rank: 0.9012
        '400':
          description: Bad Request - Invalid search parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              examples:
                invalid_pagination:
                  summary: Invalid pagination parameters
                  value:
                    page:
                      - Ensure this value is greater than or equal to 1.
                    page_size:
                      - Ensure this value is greater than or equal to 1.
                query_too_long:
                  summary: Search query too long
                  value:
                    query:
                      - Ensure this field has no more than 100 characters.
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
      security:
        - readTokenAuthHeader: []
        - readTokenAuthQuery: []
components:
  parameters:
    page:
      name: page
      in: query
      description: |
        Page number for page-based pagination.

        **Mutually exclusive with limit/offset parameters.**
      required: false
      schema:
        type: integer
        default: 1
        minimum: 1
      example: 2
    page_size:
      name: page_size
      in: query
      description: |
        Number of items per page for page-based pagination.

        **Mutually exclusive with limit/offset parameters.**
      required: false
      schema:
        type: integer
        default: 10
        minimum: 1
        maximum: 100
      example: 5
    auth_token:
      name: auth_token
      in: query
      required: false
      schema:
        type: string
      description: |
        Your ButterCMS read API token
      example: your_api_token
  schemas:
    PageBasedSearchResponse:
      type: object
      description: Blog post search response using page-based pagination
      properties:
        meta:
          $ref: '#/components/schemas/PaginationMeta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/BlogPostSearchResult'
          description: Array of blog post search results with relevance ranking
      required:
        - meta
        - data
    OffsetBasedSearchResponse:
      type: object
      description: Blog post search response using offset-based pagination
      properties:
        meta:
          $ref: '#/components/schemas/OffsetPaginationMeta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/BlogPostSearchResult'
          description: Array of blog post search results with relevance ranking
      required:
        - meta
        - data
    ValidationErrorResponse:
      type: object
      description: >-
        Response for validation errors (400 Bad Request) - supports both
        field-specific errors and general error messages
      oneOf:
        - type: object
          description: >-
            Field-specific validation errors (used by Pages, Blog Posts, and
            Collections)
          additionalProperties:
            type: array
            items:
              type: string
          example:
            title:
              - You must specify a page title.
            slug:
              - You must specify a page slug.
        - type: object
          description: General error message (used for organization limits, etc.)
          properties:
            error:
              type: string
              description: Error message
          example:
            error: >-
              Cannot create a new Collection Item. Collection Item Limit
              Reached.
    PaginationMeta:
      type: object
      properties:
        previous_page:
          type:
            - integer
            - 'null'
          description: Previous page number if it exists
        next_page:
          type:
            - integer
            - 'null'
          description: Next page number if it exists
        count:
          type: integer
          description: Total number of items
    BlogPostSearchResult:
      type: object
      description: Blog post object with search relevance ranking
      properties:
        url:
          type: string
          format: uri
          description: Full URL to the blog post
          example: https://api.buttercms.com/blog/api-development-best-practices
        created:
          type: string
          format: date-time
          description: Creation date and time in ISO 8601 format
          example: '2024-01-15T08:30:00.000Z'
        published:
          type: string
          format: date-time
          description: Publication date and time in ISO 8601 format
          example: '2024-01-15T10:00:00.000Z'
        author:
          $ref: '#/components/schemas/BlogPostAuthorObject'
          description: Author information
        categories:
          type: array
          items:
            $ref: '#/components/schemas/CategoryObject'
          description: Array of category objects
        tags:
          type: array
          items:
            $ref: '#/components/schemas/TagObject'
          description: Array of tag objects
        featured_image:
          type:
            - string
            - 'null'
          format: uri
          description: CDN URL of the featured image, null if no image
          example: https://cdn.buttercms.com/featured/api-guide.jpg
        featured_image_alt:
          type: string
          description: Alt text for the featured image
          example: API Development Guide
        slug:
          type: string
          description: URL-friendly slug identifier
          example: api-development-best-practices
        title:
          type: string
          description: Blog post title
          example: API Development Best Practices for 2024
        body:
          type: string
          description: Full HTML content of the blog post (excluded when exclude_body=true)
          example: >-
            <h2>Introduction</h2><p>Building robust APIs requires following
            established best practices...</p>
        summary:
          type: string
          description: Summary or excerpt of the blog post
          example: >-
            Learn the essential best practices for building scalable and
            maintainable APIs in 2024.
        seo_title:
          type: string
          description: SEO-optimized title
          example: API Development Best Practices for 2024
        meta_description:
          type: string
          description: Meta description for SEO
          example: >-
            Complete guide to API development best practices including REST
            design, authentication, and documentation.
        status:
          type: string
          enum:
            - published
          description: Publication status (only published posts appear in search results)
          example: published
        rank:
          type: number
          format: float
          description: Search relevance score (higher values indicate better matches)
          example: 0.8573
          minimum: 0
          maximum: 1
    OffsetPaginationMeta:
      type: object
      description: Pagination metadata for limit/offset pagination
      properties:
        count:
          type: integer
          description: Total number of items
          example: 25
        next_offset:
          type:
            - integer
            - 'null'
          description: Offset for the next page, null if no next page
          example: 20
        previous_offset:
          type:
            - integer
            - 'null'
          description: Offset for the previous page, null if no previous page
          example: null
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: Error message describing what went wrong
          example: Authentication credentials were not provided
    BlogPostAuthorObject:
      type: object
      description: Author information for blog posts
      properties:
        first_name:
          type: string
          description: Author's first name
          example: API
        last_name:
          type: string
          description: Author's last name
          example: Test
        email:
          type: string
          format: email
          description: Author's email address
          example: apitest@buttercms.com
        slug:
          type: string
          description: Author's URL-friendly slug
          example: api-test
        bio:
          type: string
          description: Author's biography
          example: This is my bio.
        title:
          type: string
          description: Author's professional title
          example: API
        linkedin_url:
          type:
            - string
            - 'null'
          format: uri
          description: Author's LinkedIn profile URL
          example: https://www.linkedin.com/in/API
        facebook_url:
          type:
            - string
            - 'null'
          format: uri
          description: Author's Facebook profile URL
          example: https://www.facebook.com/API
        twitter_handle:
          type: string
          description: Author's Twitter handle
          example: buttercmsapi
        instagram_url:
          type:
            - string
            - 'null'
          format: uri
          description: Author's Instagram profile URL
          example: https://www.instagram.com/API
        pinterest_url:
          type:
            - string
            - 'null'
          format: uri
          description: Author's Pinterest profile URL
          example: https://www.pinterest.com/API
        profile_image:
          type:
            - string
            - 'null'
          format: uri
          description: URL to author's profile image
          example: https://buttercms.com/api.png
    CategoryObject:
      type: object
      description: Category information for blog posts
      properties:
        name:
          type: string
          description: Display name of the category
          example: test category
        slug:
          type: string
          description: URL-friendly slug of the category
          example: test-category
    TagObject:
      type: object
      description: Tag information for blog posts
      properties:
        name:
          type: string
          description: Display name of the tag
          example: test tag
        slug:
          type: string
          description: URL-friendly slug of the tag
          example: test-tag
  responses:
    UnauthorizedResponse:
      description: Unauthorized - Invalid or missing API token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing_token:
              summary: Missing API token
              value:
                detail: Authentication credentials were not provided
            invalid_token:
              summary: Invalid API token
              value:
                detail: Invalid token
  securitySchemes:
    readTokenAuthHeader:
      type: apiKey
      in: header
      name: Authorization
      description: |
        Set the `Authorization` header to `Token your_read_api_token`.

        Example: `Authorization: Token abc123def456`

        Note: The header value includes the `Token` prefix.

        You can access your API token from your settings page.
    readTokenAuthQuery:
      type: apiKey
      in: query
      name: auth_token
      description: >
        Pass your API token via the `auth_token` parameter on every request:
        `?auth_token=your_read_api_token`.


        You can access your API token from your settings page.


        Requests made with a missing or invalid token will get a 401
        Unauthorized response. All requests must be made over HTTPS.

````