Articles

As the name suggests, Articles are a core part of VaporCMS — the very reason VaporCMS exists is so you can have Headless CMS that takes care of your content marketing lifecycle. On this page, we'll dive into the different article endpoints you can use to manage articles programmatically.

The article model

The article model contains all the information about your articles, such as their title, status, slug, content(in html), and more. Here are the base properties:

Properties

Name
id
Type
string
Description
Unique identifier for the article.
Name
status
Type
Draft | Published
Description
The status of the article.
Name
slug
Type
string
Description
The article slug.
Name
exerpt
Type
string
Description
The short description userd to preview the article (usually used on the articles list).
Name
html
Type
string
Description
The articles content, returned as an HTML string. This is usually used to render the article on the page.
Name
seo
Type
object
Description
The seo object contains the information to use as og:title, og:description and og:imge in your article head.
Name
tableOfContents
Type
array
Description
Array of objects representin the table of contents of your articles. You can use this information to render a table of contents section for your article.

GET/v0/:blogId/articles

List all articles

This endpoint allows you to retrieve a paginated list of all your articles. The article information is returned in the localized field, which can contain one or more objects, based on how many localizations an article has. By default, we return all article localizations.

Optional attributes

Name
categoryIds
Type
array
Description
Get articles by category or caregories.
Name
authorIds
Type
array
Description
Get articles by author or authors(s).
Name
page
Type
number
Description
The page number.
Name
pageSize
Type
number
Description
How many articles do you want to fetch.
Name
localeCode
Type
string
Description
Filter articles by locale code.

Response Type (Typescript)

export interface Author {
  id: string
  name: string
  slug: string
  description: {
    [languageCode: string]: string
  }
  media: {
    [languageCode: string]: Media
  }
}

interface Media {
  id: string
  url: string
  createdAt: string
  updatedAt: string
}

export interface ArticleResponseData {
  articles: Article[]
  totalCount: number
  pagination: Pagination
}

interface Pagination {
  page: number
  pageSize: number
  totalPages: number
}

type Status = 'Draft' | 'Published'

export interface Article {
  id: string
  status: Status
  localized: {
    [languageCode: string]: LocalizedArticle
  }
}

interface ArticleAuthor {
  id: string
  name: string
  slug: string
  profile: string
  createdAt: string
  upatedAt: string
}

export interface LocalizedArticle {
  id: string
  status: Status
  publishedAt: string
  updatedAt: string
  title: string
  slug: string
  excerpt: string
  content: Content
  seo: {
    title: string
    description: string
    image: {
      url: string
      alt: string | null
      width: string | null
      height: string | null
    } | null
  }
  cover: Cover | null
  authors: ArticleAuthor[]
  categories: Category[]
  locales?: string[]
  locale: string
  tableOfContents: TOCItem[]
}

export interface TOCItem {
  id: string
  text: string
  level: number
  subHeadings: TOCItem[]
}

interface Content {
  html: string
}

interface Cover {
  id: string
  url: string
  alt: string
  width: number | null
  height: number | null
  createdAt: string
  updatedAt: string
}

interface Category {
  id: string
  name: string
  slug: string
  description: string
  createdAt: string
  updatedAt: string
}

export interface BlogPost {
  id: string
  title: string
  slug: string
  excerpt: string
  date: string
  coverImage: {
    url: string
    alt: string
  }
  author: {
    name: string
    imageUrl: string
  }
  seo: {
    title: string
    description: string
    imageUrl: string
  }
}

Request

GET

/v0/:blogId/articles

curl -G https://api.vaporcms.com/v0/{blogId}/articles \
  -H "Authorization: Bearer {token}" \

Response

{
    "articles": [
        {
            "id": "cm28vvx25000x1lkotbqphcw3",
            "status": "Published",
            "createdAt": "2024-10-14T10:41:01.468Z",
            "updatedAt": "2024-10-17T08:02:12.676Z",
            "localized": {
                "en": {
                    "id": "cm2d0j8n2007ovastv52e0w0y",
                    "status": "Published",
                    "publishedAt": "2024-10-14T15:08:47.197Z",
                    "title": "Explore VaporCMS - The Headless CMS built for blogs",
                    "slug": "explore-vaporcms",
                    "excerpt": "In this blog post we'll explain the core VaporCMS features, and what makes it unique compared to other headless CMS. Let's dive into the major VaporCMS Features.",
                    "content": {
                        "html": "<p>.."
                    },
                    "seo": {
                        "title": "Explore VaporCMS - The Headless CMS built for blogs",
                        "description": "In this blog post we'll explain the core VaporCMS features, and what makes it unique compared to other headless CMS. Let's dive into the major VaporCMS Features.",
                        "image": {
                            "id": "cm28werj1001j1lkonxpz4dto",
                            "url": "...",
                            "alt": null,
                            "width": null,
                            "height": null,
                            "createdAt": "2024-10-14T10:55:40.765Z",
                            "updatedAt": "2024-10-14T15:53:31.303Z"
                        }
                    },
                    "cover": {
                        "id": "cm28werj1001j1lkonxpz4dto",
                        "url": "...",
                        "alt": null,
                        "width": null,
                        "height": null,
                        "createdAt": "2024-10-14T10:55:40.765Z",
                        "updatedAt": "2024-10-14T15:53:31.303Z"
                    },
                    "authors": [
                        {
                            "id": "cm28vtwlz000e1lkoiv0zrbjs",
                            "name": "Michael Scott",
                            "slug": "michael-scott",
                            "url": "url-here",
                            "createdAt": "2024-10-14T10:39:27.575Z",
                            "updatedAt": "2024-10-14T17:42:20.685Z"
                        }
                    ],
                    "categories": [
                        {
                            "id": "cm2d0j0m7007hvastomwei7w4",
                            "name": "Software",
                            "slug": "software",
                            "description": "",
                            "createdAt": "2024-10-17T08:02:02.333Z",
                            "updatedAt": "2024-10-17T08:02:02.333Z"
                        }
                    ]
                },
                "de": {
                    "id": "cm2d0j8n2007qvastik4psgpw",
                    "status": "Published",
                    "publishedAt": "2024-10-14T15:08:47.172Z",
                    "content": {
                        "title": "Erkunde VaporCMS - Das Headless CMS, das für Blogs entwickelt wurde.",
                        "slug": "erkunde-vaporcms",
                        "excerpt": "In diesem Blogbeitrag werden wir die Kernfunktionen von VaporCMS erläutern und herausstellen, was es im Vergleich zu anderen Headless CMS einzigartig macht.",
                        "html": "<p>..."
                    },
                    "seo": {
                        "title": "Erkunde VaporCMS - Das Headless CMS, das für Blogs entwickelt wurde.",
                        "description": "In diesem Blogbeitrag werden wir die Kernfunktionen von VaporCMS erläutern und herausstellen, was es im Vergleich zu anderen Headless CMS einzigartig macht.",
                        "image": {
                            "id": "cm28werj1001j1lkonxpz4dto",
                            "url": "...",
                            "alt": null,
                            "width": null,
                            "height": null,
                            "createdAt": "2024-10-14T10:55:40.765Z",
                            "updatedAt": "2024-10-14T15:53:31.303Z"
                        }
                    },
                    "cover": {
                        "id": "cm28werj1001j1lkonxpz4dto",
                        "url": "...",
                        "alt": null,
                        "width": null,
                        "height": null,
                        "createdAt": "2024-10-14T10:55:40.765Z",
                        "updatedAt": "2024-10-14T15:53:31.303Z"
                    },
                    "authors": [
                        {
                            "id": "cm28vtwlz000e1lkoiv0zrbjs",
                            "name": "Michael Scott",
                            "slug": "michael-scott",
                            "url": "url-here",
                            "createdAt": "2024-10-14T10:39:27.575Z",
                            "updatedAt": "2024-10-14T17:42:20.685Z"
                        }
                    ],
                    "categories": [
                        {
                            "id": "cm2d0j0m7007hvastomwei7w4",
                            "name": "Software",
                            "slug": "software",
                            "description": "",
                            "createdAt": "2024-10-17T08:02:02.333Z",
                            "updatedAt": "2024-10-17T08:02:02.333Z"
                        }
                    ]
                }
            }
        }
    ],
    "totalCount": 1,
    "pagination": {
        "page": 1,
        "pageSize": 10,
        "totalPages": 1
    }
}

GET/v0/:blogId/articles

List all articles metadata

This endpoint allows you to retrieve a paginated list of all your articles metadata. The structure is similar to the /articles endpoint, with the difference being that the content is not returned. This API is usually used when listing all the articles in your blog (content is not needed).

By default, we return all article localizations.

Optional attributes

Name
categoryIds
Type
array
Description
Get articles by category or caregories.
Name
authorIds
Type
array
Description
Get articles by author or authors(s).
Name
page
Type
number
Description
The page number.
Name
pageSize
Type
number
Description
How many articles do you want to fetch.
Name
localeCode
Type
string
Description
Filter articles by locale code.

Response Type (Typescript)

export interface Author {
  id: string
  name: string
  slug: string
  description: {
    [languageCode: string]: string
  }
  media: {
    [languageCode: string]: Media
  }
}

interface Media {
  id: string
  url: string
  createdAt: string
  updatedAt: string
}

export interface ArticleResponseData {
  articles: Article[]
  totalCount: number
  pagination: Pagination
}

interface Pagination {
  page: number
  pageSize: number
  totalPages: number
}

type Status = 'Draft' | 'Published'

export interface Article {
  id: string
  status: Status
  localized: {
    [languageCode: string]: LocalizedArticle
  }
}

interface ArticleAuthor {
  id: string
  name: string
  slug: string
  profile: string
  createdAt: string
  upatedAt: string
}

export interface LocalizedArticle {
  id: string
  status: Status
  publishedAt: string
  updatedAt: string
  title: string
  slug: string
  excerpt: string
  seo: {
    title: string
    description: string
    image: {
      url: string
      alt: string | null
      width: string | null
      height: string | null
    } | null
  }
  cover: Cover | null
  authors: ArticleAuthor[]
  categories: Category[]
  locales?: string[]
  locale: string
  tableOfContents: TOCItem[]
}

export interface TOCItem {
  id: string
  text: string
  level: number
  subHeadings: TOCItem[]
}

interface Cover {
  id: string
  url: string
  alt: string
  width: number | null
  height: number | null
  createdAt: string
  updatedAt: string
}

interface Category {
  id: string
  name: string
  slug: string
  description: string
  createdAt: string
  updatedAt: string
}

export interface BlogPost {
  id: string
  title: string
  slug: string
  excerpt: string
  date: string
  coverImage: {
    url: string
    alt: string
  }
  author: {
    name: string
    imageUrl: string
  }
  seo: {
    title: string
    description: string
    imageUrl: string
  }
}

Request

GET

/v0/:blogId/articles/metadata

curl -G https://api.vaporcms.com/v0/{blogId}/articles/metadata \
  -H "Authorization: Bearer {token}" \

Response

{
    "articles": [
        {
            "id": "cm28vvx25000x1lkotbqphcw3",
            "status": "Published",
            "createdAt": "2024-10-14T10:41:01.468Z",
            "updatedAt": "2024-10-17T08:02:12.676Z",
            "localized": {
                "en": {
                    "id": "cm2d0j8n2007ovastv52e0w0y",
                    "status": "Published",
                    "publishedAt": "2024-10-14T15:08:47.197Z",
                    "title": "Explore VaporCMS - The Headless CMS built for blogs",
                    "slug": "explore-vaporcms",
                    "excerpt": "In this blog post we'll explain the core VaporCMS features, and what makes it unique compared to other headless CMS. Let's dive into the major VaporCMS Features.",
                    "seo": {
                        "title": "Explore VaporCMS - The Headless CMS built for blogs",
                        "description": "In this blog post we'll explain the core VaporCMS features, and what makes it unique compared to other headless CMS. Let's dive into the major VaporCMS Features.",
                        "image": {
                            "id": "cm28werj1001j1lkonxpz4dto",
                            "url": "...",
                            "alt": null,
                            "width": null,
                            "height": null,
                            "createdAt": "2024-10-14T10:55:40.765Z",
                            "updatedAt": "2024-10-14T15:53:31.303Z"
                        }
                    },
                    "cover": {
                        "id": "cm28werj1001j1lkonxpz4dto",
                        "url": "...",
                        "alt": null,
                        "width": null,
                        "height": null,
                        "createdAt": "2024-10-14T10:55:40.765Z",
                        "updatedAt": "2024-10-14T15:53:31.303Z"
                    },
                    "authors": [
                        {
                            "id": "cm28vtwlz000e1lkoiv0zrbjs",
                            "name": "Michael Scott",
                            "slug": "michael-scott",
                            "url": "url-here",
                            "createdAt": "2024-10-14T10:39:27.575Z",
                            "updatedAt": "2024-10-14T17:42:20.685Z"
                        }
                    ],
                    "categories": [
                        {
                            "id": "cm2d0j0m7007hvastomwei7w4",
                            "name": "Software",
                            "slug": "software",
                            "description": "",
                            "createdAt": "2024-10-17T08:02:02.333Z",
                            "updatedAt": "2024-10-17T08:02:02.333Z"
                        }
                    ]
                },
                "de": {
                    "id": "cm2d0j8n2007qvastik4psgpw",
                    "status": "Published",
                    "publishedAt": "2024-10-14T15:08:47.172Z",
                    "content": {
                        "title": "Erkunde VaporCMS - Das Headless CMS, das für Blogs entwickelt wurde.",
                        "slug": "erkunde-vaporcms",
                        "excerpt": "In diesem Blogbeitrag werden wir die Kernfunktionen von VaporCMS erläutern und herausstellen, was es im Vergleich zu anderen Headless CMS einzigartig macht.",
                        "html": "<p>..."
                    },
                    "seo": {
                        "title": "Erkunde VaporCMS - Das Headless CMS, das für Blogs entwickelt wurde.",
                        "description": "In diesem Blogbeitrag werden wir die Kernfunktionen von VaporCMS erläutern und herausstellen, was es im Vergleich zu anderen Headless CMS einzigartig macht.",
                        "image": {
                            "id": "cm28werj1001j1lkonxpz4dto",
                            "url": "...",
                            "alt": null,
                            "width": null,
                            "height": null,
                            "createdAt": "2024-10-14T10:55:40.765Z",
                            "updatedAt": "2024-10-14T15:53:31.303Z"
                        }
                    },
                    "cover": {
                        "id": "cm28werj1001j1lkonxpz4dto",
                        "url": "...",
                        "alt": null,
                        "width": null,
                        "height": null,
                        "createdAt": "2024-10-14T10:55:40.765Z",
                        "updatedAt": "2024-10-14T15:53:31.303Z"
                    },
                    "authors": [
                        {
                            "id": "cm28vtwlz000e1lkoiv0zrbjs",
                            "name": "Michael Scott",
                            "slug": "michael-scott",
                            "url": "url-here",
                            "createdAt": "2024-10-14T10:39:27.575Z",
                            "updatedAt": "2024-10-14T17:42:20.685Z"
                        }
                    ],
                    "categories": [
                        {
                            "id": "cm2d0j0m7007hvastomwei7w4",
                            "name": "Software",
                            "slug": "software",
                            "description": "",
                            "createdAt": "2024-10-17T08:02:02.333Z",
                            "updatedAt": "2024-10-17T08:02:02.333Z"
                        }
                    ]
                }
            }
        }
    ],
    "totalCount": 1,
    "pagination": {
        "page": 1,
        "pageSize": 10,
        "totalPages": 1
    }
}

GET/v0/:blogId/articles/:slug

Get an article via slug

This endpoint allows you to retrieve an article by their slug. Refer to the list at the top of this page to see which properties are included with articles objects.

Required attributes

Name
slug
Type
string
Description
The article slug you're trying to fetch.

Optional attributes

Name
localeCode
Type
string
Description
The locale for which you want to fetch the article. You might want to include the locale if you use the same slug for multiple locales of the same article.

Request

GET

/v0/articles/:slug

curl https://api/vaprcms.com/v0/{blog-id}/articles/{slug} \
  -H "Authorization: Bearer {token}"

Response

{
    "id": "cm28vvx25000x1lkotbqphcw3",
    "status": "Published",
    "publishedAt": "2024-10-14T15:08:47.197Z",
    "title": "Explore VaporCMS - The Headless CMS built for blogs",
    "slug": "explore-vaporcms",
    "excerpt": "In this blog post we'll explain the core VaporCMS features, and what makes it unique compared to other headless CMS. Let's dive into the major VaporCMS Features.",
    "content": {
        "html":" "<p>..."
    },
    "tableOfContents": [
        {
            "id": "n1-built-for-multi-locale-content",
            "text": "1. Built for multi-locale content",
            "level": 2,
            "subHeadings": []
        },
        {
            "id": "n2-built-with-seo-performance-in-mind",
            "text": "2. Built with SEO performance in mind",
            "level": 2,
            "subHeadings": [
                {
                    "id": "vapor-warns-you-when-seo-attributes-such-as-titles",
                    "text": "Vapor warns you when SEO attributes such as titles or descriptions are too long according to best practices",
                    "level": 3,
                    "subHeadings": []
                },
                {
                    "id": "vapor-warns-you-when-your-images-are-too-large-hav",
                    "text": "Vapor warns you when your images are too large, have no alt text, or have a suboptimal format",
                    "level": 3,
                    "subHeadings": []
                }
            ]
        },
        ...
    ],
    "seo": {
        "title": "Explore VaporCMS - The Headless CMS built for blogs",
        "description": "In this blog post we'll explain the core VaporCMS features, and what makes it unique compared to other headless CMS. Let's dive into the major VaporCMS Features.",
        "image": {
            "id": "cm28werj1001j1lkonxpz4dto",
            "url": "...",
            "alt": null,
            "width": null,
            "height": null,
            "createdAt": "2024-10-14T10:55:40.765Z",
            "updatedAt": "2024-10-14T15:53:31.303Z"
        }
    },
    "cover": {
        "id": "cm28werj1001j1lkonxpz4dto",
        "url": "...",
        "alt": null,
        "width": null,
        "height": null,
        "createdAt": "2024-10-14T10:55:40.765Z",
        "updatedAt": "2024-10-14T15:53:31.303Z"
    },
    "categories": [
        {
            "id": "cm2d0j0m7007hvastomwei7w4",
            "name": "Software",
            "slug": "software",
            "description": "",
            "createdAt": "2024-10-17T08:02:02.333Z",
            "updatedAt": "2024-10-17T08:02:02.333Z"
        }
    ],
    "authors": [
        {
            "id": "cm28vtwlz000e1lkoiv0zrbjs",
            "name": "Michael Scott",
            "slug": "michael-scott",
            "url": "...",
            "createdAt": "2024-10-14T10:39:27.575Z",
            "updatedAt": "2024-10-14T17:42:20.685Z"
        }
    ],
    "createdAt": "2024-10-17T08:02:12.674Z",
    "updatedAt": "2024-10-14T15:08:47.197Z",
    "locales": [
        "en",
        "de"
    ],
    "alternates": [
        {
            "localeCode": "de",
            "slug": "erkunde-vaporcms"
        }
    ],
    "locale": "en"
}