Skip to main content
GET
/
posts
/
search
Search Posts
curl --request GET \
  --url https://api.buttercms.com/v2/posts/search/ \
  --header 'Authorization: <api-key>'
{
  "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
    }
  ]
}

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 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.

Authorizations

​
Authorization
string
header
required

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.

Query Parameters

​
query
string
default:""

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.

Maximum string length: 100
​
page
integer
default:1

Page number for page-based pagination.

Mutually exclusive with limit/offset parameters.

Required range: x >= 1
​
page_size
integer
default:10

Number of items per page for page-based pagination.

Mutually exclusive with limit/offset parameters.

Required range: 1 <= x <= 100
​
exclude_body
boolean
default:false

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.

​
auth_token
string

Your ButterCMS read API token

Response

Search completed successfully

Blog post search response using page-based pagination

​
meta
object
required
​
data
object[]
required

Array of blog post search results with relevance ranking