SDK Reference

The Articles API provides methods to fetch, filter, search, and list articles from your Simplist project.

MethodDescriptionReturns
List articles with pagination and filtersApiResponse<ArticleListItem[]>
Get a single article by slugApiResponse<Article>
Search articles by queryApiResponse<ArticleListItem[]>
Get only published articlesApiResponse<ArticleListItem[]>
Get latest articlesApiResponse<ArticleListItem[]>
Get most popular articlesApiResponse<ArticleListItem[]>

Retrieve a paginated list of articles with filtering and sorting options.

Method Signature
async client.articles.list(params?: ArticleListParams): Promise<ApiResponse<ArticleListItem[]>>

PropertyTypeDescriptionDefault
pagenumberPage number1
limitnumberItems per page (max 100)10
sort'createdAt' | 'updatedAt' | 'title' | 'publishedAt' | 'viewCount'Sort fieldcreatedAt
order'asc' | 'desc'Sort directiondesc
publishedbooleanFilter by published status-
searchstringSearch in title and content-
status'draft' | 'published'Filter by status-
selectArticleSelectFieldsCustomize which fields to include/exclude in response-
tagsstring[]Filter by tags (OR logic: at least one)-
tagsAllstring[]Filter by tags (AND logic: all required)-
excludeTagsstring[]Exclude articles with these tags-

const { data, meta } = await client.articles.list({
  page: 1,
  limit: 20,
  sort: 'createdAt',
  order: 'desc',
  published: true
})

Get articles with at least one of the specified tags:

// Articles about JavaScript OR TypeScript
const { data } = await client.articles.list({
  tags: ['JavaScript', 'TypeScript']
})

// Articles with web development tags
const { data: webArticles } = await client.articles.list({
  tags: ['JavaScript', 'HTML', 'CSS'],
  published: true
})

Get articles that have all specified tags:

// Articles that are BOTH tutorials AND about JavaScript
const { data: jsTutorials } = await client.articles.list({
  tagsAll: ['Tutorial', 'JavaScript']
})

// Complex requirements: beginner tutorials about web development
const { data: beginnerWeb } = await client.articles.list({
  tagsAll: ['Tutorial', 'Beginner', 'Web Development']
})

Get articles that don't have specific tags:

// Articles without Advanced or Deprecated tags
const { data: beginnerArticles } = await client.articles.list({
  excludeTags: ['Advanced', 'Deprecated']
})

// Published articles, excluding work in progress
const { data: finishedArticles } = await client.articles.list({
  published: true,
  excludeTags: ['WIP', 'Draft']
})

Combine multiple tag filters for complex queries:

const { data: beginnerWebTutorials } = await client.articles.list({
  tags: ['JavaScript', 'TypeScript'],      // OR: at least one of these
  tagsAll: ['Tutorial'],                   // AND: must have this tag
  excludeTags: ['Advanced'],               // NOT: must not have this tag
  published: true
})

Control which fields are included in the response to optimize payload size and performance.

By default, articles include all fields including the full content. Use select to exclude heavy fields:

// Exclude content for list views (lighter response)
const { data: articles } = await client.articles.list({
  select: {
    content: false, // Exclude content
    variants: false // Exclude translations
  },
  published: true,
  limit: 20
})

// Perfect for blog listing pages where you only need title and excerpt
articles.forEach(article => {
  console.log(article.title) // ✓ Available
  console.log(article.excerpt) // ✓ Available
  console.log(article.content) // undefined
})

Set fields to true to explicitly include them (especially useful with tag metadata):

// Get articles with tag colors and icons
const { data: articlesWithTags } = await client.articles.list({
  select: {
    tagColor: true, // Include tag hex colors
    tagIcon: true   // Include tag icons
  }
})

articlesWithTags[0].tags.forEach(tag => {
  console.log(`${tag.name}: ${tag.color} (${tag.icon})`)
})
// Output: "React: #61DAFB (react)"

PropertyTypeDescriptionDefault
contentbooleanFull article content (can be large)-
excerptbooleanArticle summary-
coverImagebooleanCover image URL-
titlebooleanArticle title-
slugbooleanURL-friendly identifier-
authorbooleanAuthor information-
lastUpdatedBybooleanLast editor information-
tagsbooleanAssociated tags-
variantsbooleanTranslations (can be large)-
tagColorbooleanInclude tag hex colors-
tagIconbooleanInclude tag icon names-
publishedbooleanPublication status-
viewCountbooleanNumber of views-
wordCountbooleanWord count-
readTimeMinutesbooleanEstimated reading time-
createdAtbooleanCreation timestamp-
updatedAtbooleanLast update timestamp-
publishedAtbooleanPublication timestamp-

Without select: All fields are included (backwards compatible)
With select: Only specified fields are included (defaults to false for unspecified fields)

// No select = all fields included
const { data: full } = await client.articles.list()
console.log(full[0].content) // ✓ Available (includes everything)

// With select = only specified fields
const { data: minimal } = await client.articles.list({
  select: {
    title: true,
    excerpt: true
    // content and other fields are excluded
  }
})

console.log(minimal[0].content) // undefined

Retrieve a single article by its slug, including full content.

Method Signature
async client.articles.get(slug: string, options?: { select?: ArticleSelectFields }): Promise<ApiResponse<Article>>

const { data: article } = await client.articles.get('getting-started')

console.log(article.title)
console.log(article.content) // Full Markdown content
console.log(article.author.name)
console.log(article.viewCount)

// Tags names are always included
console.log(article.tags.map(t => t.name))
// Output: ['JavaScript', 'TypeScript', 'React']

Search articles by query string (searches in title and content).

Method Signature
async client.articles.search(query: string, params?: ArticleListParams): Promise<ApiResponse<ArticleListItem[]>>

const { data: results } = await client.articles.search('typescript', {
  limit: 5,
  published: true
})

console.log(`Found ${results.length} articles matching "typescript"`)

Get only published articles (shorthand for list({ published: true })).

Method Signature
async client.articles.published(params?: ArticleListParams): Promise<ApiResponse<ArticleListItem[]>>

const { data: articles } = await client.articles.published({
  limit: 10,
  sort: 'createdAt',
  order: 'desc'
})

Get the most recently created articles.

Method Signature
async client.articles.latest(limit: number = 10): Promise<ApiResponse<ArticleListItem[]>>

const { data: latest } = await client.articles.latest(5)

console.log('Latest 5 articles:')
latest.forEach(article => {
  console.log(`- ${article.title}`)
})

Get the most popular articles by view count.

Method Signature
async client.articles.popular(limit: number = 10): Promise<ApiResponse<ArticleListItem[]>>

const { data: popular } = await client.articles.popular(3)

console.log('Top 3 articles:')
popular.forEach((article, i) => {
  console.log(`${i + 1}. ${article.title} (${article.viewCount} views)`)
})

import { SimplistClient } from "@simplist.blog/sdk"

export default async function BlogPage({
  searchParams
}: {
  searchParams: { page?: string }
}) {
  const client = new SimplistClient()
  const page = Number(searchParams.page) || 1

  const { data: articles, meta } = await client.articles.published({
    page,
    limit: 10,
    sort: 'publishedAt',
    order: 'desc'
  })

  return (
    <div>
      <h1>Blog</h1>

      <div className="articles">
        {articles.map(article => (
          <article key={article.id}>
            <h2>{article.title}</h2>
            <p>{article.excerpt}</p>
            <span>{article.readTimeMinutes} min read</span>
            <span>{article.viewCount} views</span>
            <a href={`/blog/${article.slug}`}>Read more</a>
          </article>
        ))}
      </div>

      <Pagination
        currentPage={meta.page}
        totalPages={meta.totalPages}
      />
    </div>
  )
}

These SDK methods use the following API endpoints:

See the REST API documentation for direct HTTP access.

Quick Help

list() returns all articles (including drafts if you have permissions), while published() filters to only return published articles. Use published() for public-facing content.
Use the page and limit parameters in list() or published(). The response includes meta.totalPages to help you build pagination UI. Example: client.articles.published({ page: 2, limit: 10 }).
Yes, the search() method performs full-text search across title, excerpt, and content fields. It returns ranked results based on relevance.
Edit on GitHub
Previous
Project API
Next
Analytics API

Command Palette

Search for a command to run...