SDK Reference
The Articles API provides methods to fetch, filter, search, and list articles from your Simplist project.
| Method | Description | Returns |
|---|---|---|
| List articles with pagination and filters | ApiResponse<ArticleListItem[]> | |
| Get a single article by slug | ApiResponse<Article> | |
| Search articles by query | ApiResponse<ArticleListItem[]> | |
| Get only published articles | ApiResponse<ArticleListItem[]> | |
| Get latest articles | ApiResponse<ArticleListItem[]> | |
| Get most popular articles | ApiResponse<ArticleListItem[]> |
Retrieve a paginated list of articles with filtering and sorting options.
Method Signature
async client.articles.list(params?: ArticleListParams): Promise<ApiResponse<ArticleListItem[]>>| Property | Type | Description | Default |
|---|---|---|---|
page | number | Page number | 1 |
limit | number | Items per page (max 100) | 10 |
sort | 'createdAt' | 'updatedAt' | 'title' | 'publishedAt' | 'viewCount' | Sort field | createdAt |
order | 'asc' | 'desc' | Sort direction | desc |
published | boolean | Filter by published status | - |
search | string | Search in title and content | - |
status | 'draft' | 'published' | Filter by status | - |
optionalFields | ArticleOptionalFields | Request optional tag fields (color, icon) | - |
tags | string[] | Filter by tags (OR logic: at least one) | - |
tagsAll | string[] | Filter by tags (AND logic: all required) | - |
excludeTags | string[] | 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
})Retrieve a single article by its slug, including full content.
Method Signature
async client.articles.get(slug: string, options?: { optionalFields?: ArticleOptionalFields }): 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:
list()→ GET/v1/articlesget()→ GET/v1/articles/:slug
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.