Headless CMS Content API Documentation

Welcome to the Typeflo Headless CMS Content API documentation. This API allows you to access content from your Typeflo-powered blog programmatically. With it, you can retrieve posts, authors, categories, tags, and more to build custom applications, frontends, or integrations.


Authentication

To use the Typeflo's Content API, you need a Content API key.

Retrieving Your API Key

  1. Log in to your Typeflo admin dashboard.

  2. Navigate to Settings > Apps.

  3. Under Manage Custom Apps , click on +Add

  4. Create new custom app with the name of your choice

  5. Once created, head over to the newely created app settings to view the API Keys

  6. From the Settings page, you will be able to get the below credentials:-

    1. Content & Admin API keys

    2. Content & Admin API URLs


Base URL

GET https://<your-subdomain>.typeflo.io/api/headless/content

Usage

To authenticate requests, pass the Content API key as a bearer token in the Authorization header.

For example:

GET https://<your-subdomain>.typeflo.io/api/headless/content/posts
Authorization: Bearer YOUR_CONTENT_API_KEY

Endpoints

The Typeflo Content API provides endpoints for:

  • Posts: Retrieve posts created in your blog.

  • Categories: Retrieve categories used in your content.

  • Tags: Retrieve tags used in your content.

  • Pages: Retrieve static pages.

  • Authors: Retrieve information about authors.

  • Settings: Retrieve site-wide settings.

All responses are returned in JSON format.


1. Posts

Retrieve published posts from your Typeflo blog.

Endpoint

GET /posts
GET /posts/{id}
GET /posts/{slug}

Example Request

GET https://<your-subdomain>.typeflo.io/api/headless/content/posts
Authorization: Bearer YOUR_CONTENT_API_KEY

Example Response

{
  "data": [
    {
      "id": "596334f38-e133-4de5-a3e9-8a18420ee03c",
      "title": "Sample Post",
      "slug": "sample-post",
      "excerpt": "",
      "content": "<p>This is the content of the post</p>",
      "author": "0423169c-5te3-43e6-bb1c-cbbfa4047247",
      "categories": [
        {
          "label": "General",
          "value": "e2324fe2-343b-4154-a69c-f2624c94d7ee"  
        },
        ....
      ],
      "created_at": "2025-01-01T12:00:00.000Z",
      "featured_image": {
        "hd": "https://auth.typeflo.io/storage/..../hd.jpeg",
        "sd": "https://auth.typeflo.io/storage/..../sd.jpeg"
      },
      "docsid": "...",
      "metatitle": "Sample Post",
      "metadescription": "....."
      "reading_time": "3 min read",
      "tags": [
        {
          "label": "Social",
          "value": "e43285ae2-343b-4154-a69c-f2624c94d7ee"
        },
        ....
      ],
      "toc_status": true,
      "opengraph": {
         "twitter": {
           "metatitle": "...",
           "metadescription": "......",
           "image": "....."
         },
         "facebook": {
           "metatitle": "...",
           "metadescription": "......",
           "image": "....."
        },
        ....
      }
      "restriction": {
        "status": false,
        "percentage": 30
      },
      "is_draft": false,
      "scheduled": null
    },
    ......
  ],
  "error": null,
  "current_start_range": 0,
  "current_end_range": 11
}

Fields overview

Field

Type

Description

id

String

Unique identifier for the post.

title

String

The title of the post.

slug

String

URL-friendly version of the title, used in the post's URL.

excerpt

String

A short summary or introduction to the post.

content

String (HTML)

The main content of the post in HTML format.

author

String

The ID of the author who created the post.

categories

Array of Objects

List of categories assigned to the post. Each object includes label (category name) and value (ID).

created_at

String (ISO 8601 Date)

Timestamp indicating when the post was created.

featured_image

Object

URLs for the post's featured image in HD and SD resolutions.

docsid

String

The Google Docs ID associated with this post.

metatitle

String

The meta title for the post, used in SEO and previews.

metadescription

String

The meta description for the post, used in SEO and previews.

reading_time

String

Estimated reading time for the post (e.g., "3 min read").

tags

Array of Objects

List of tags associated with the post. Each object includes label (tag name) and value (ID).

toc_status

Boolean

Indicates whether the table of contents is enabled ( true) or disabled ( false).

opengraph

Object

Open Graph metadata for social media platforms, including Twitter and Facebook.

restriction

Object

Gated content restriction settings for the post: status (if restricted) and percentage (preview percentage).

is_draft

Boolean

Indicates whether the post is a draft ( true) or published ( false).

scheduled

String or null

Timestamp for when the post is scheduled to go live, or null if not scheduled.

error

String or null

Error message if any issues occurred, otherwise null.

current_start_range

Integer

Index of the first post in the current range of displayed posts.

current_end_range

Integer

Index of the last post in the current range of displayed posts.


2. Pages

Retrieve static pages from your Typeflo site.

Endpoint

GET /pages
GET /pages/{id}
GET /pages/{slug}

Example Request

GET https://<your-subdomain>.typeflo.io/api/headless/content/pages
Authorization: Bearer YOUR_CONTENT_API_KEY

Example Response

{
  "data": [
    {
      "id": "596313c38-e133-5fs4-a3e9-8a18420ee03c",
      "title": "Sample Page",
      "slug": "sample-page",
      "content": "<p>This is the content of the post</p>",
      "postedby": "046dasd9c-8e4b-43e6-aa42-cbbfa4047247",
      "created_at": "2025-01-01T12:00:00.000Z",
      "docsid": "...",
      "metatitle": "Sample Page",
      "metadescription": ".....",
      "is_draft": false,
    },
    ......
  ],
  "error": null,
  "current_start_range": 0,
  "current_end_range": 11
}

Fields overview

Field

Type

Description

id

String

Unique identifier for the page.

title

String

The title of the page.

slug

String

URL-friendly version of the title, used in the page's URL.

content

String (HTML)

The main content of the page in HTML format.

postedby

String

The ID of the user who created the page.

created_at

String (ISO 8601 Date)

Timestamp indicating when the page was created.

docsid

String

The Google Docs ID associated with the page.

metatitle

String

The meta title for the page, used in SEO and previews.

metadescription

String

The meta description for the page, used in SEO and previews.

is_draft

Boolean

Indicates whether the page is a draft ( true) or published ( false).

error

String or null

Error message if any issues occurred, otherwise null.

current_start_range

Integer

Index of the first page in the current range of displayed pages.

current_end_range

Integer

Index of the last page in the current range of displayed pages.


3. Authors

Retrieve information about authors.

Endpoint

GET /authors
GET /authors/{id}
GET /authors/{slug}

Example Request

GET https://<your-subdomain>.typeflo.io/api/headless/content/authors
Authorization: Bearer YOUR_CONTENT_API_KEY

Example Response

{
  "data": [
    {
      "id": "596313c38-e133-4de5-b94c-8a18420ee03c",
      "name": "Adam Steve",
      "email": "[email protected]",
      "slug": "adam-steve",
      "description": ".....",
      "socials": [
        {
          "name": "Facebook",
          "link": "https://fb.com/..."
        },
        {
          "name": "Twitter",
          "link": "https://x.com/...."
        },
        ....
      ],
      "metadescription": ".....",
      "created_at": "2025-01-01T12:00:00.000Z"
    },
    ......
  ],
  "error": null,
  "current_start_range": 0,
  "current_end_range": 11
}

Fields overview

Field

Type

Description

id

String

Unique identifier for the author.

name

String

The name of the author.

email

String

The email address of the author.

slug

String

URL-friendly version of the author's name, used in the profile's URL.

description

String

A short bio or description of the author.

socials

Array of Objects

List of social media profiles for the author. Each object includes name (platform) and link (URL).

metadescription

String

The meta description for the author, used in SEO and previews.

created_at

String (ISO 8601 Date)

Timestamp indicating when the author profile was created.

error

String or null

Error message if any issues occurred, otherwise null.

current_start_range

Integer

Index of the first author in the current range of displayed authors.

current_end_range

Integer

Index of the last author in the current range of displayed authors.


4. Category

Retrieve categories used in your content.

Endpoint

GET /category
GET /category/{id}
GET /category/{slug}

Example Request

GET https://<your-subdomain>.typeflo.io/api/headless/content/category
Authorization: Bearer YOUR_CONTENT_API_KEY

Example Response

{
  "data": [
    {
      "id": "596313c38-e133-3235-a3e9-8a18420ee03c",
      "name": "General",
      "title": "general",
      "createdby": "046dasd9c-9c43-43e6-bb1c-cbbfa4047247",
      "created_at": "2025-01-01T12:00:00.000Z",
      "metadescription": "....."
    },
    ......
  ],
  "error": null,
  "current_start_range": 0,
  "current_end_range": 11
}

Fields overview

Field

Type

Description

id

String

Unique identifier for the category.

name

String

The display name of the category.

title

String

URL-friendly version of the category name, used in the category's URL.

createdby

String

The ID of the user who created the category.

created_at

String (ISO 8601 Date)

Timestamp indicating when the category was created.

metadescription

String

The meta description for the category, used in SEO and previews.

error

String or null

Error message if any issues occurred, otherwise null.

current_start_range

Integer

Index of the first tag in the current range of displayed categories.

current_end_range

Integer

Index of the last category in the current range of displayed categories.


5. Tags

Retrieve tags used in your content.

Endpoint

GET /tags
GET /tags/{id}
GET /tags/{slug}

Example Request

GET https://<your-subdomain>.typeflo.io/api/headless/content/tags
Authorization: Bearer YOUR_CONTENT_API_KEY

Example Response

{
  "data": [
    {
      "id": "596313c38-e133-943f-a3e9-8a18420ee03c",
      "name": "Social",
      "title": "social",
      "createdby": "046dasd9c-8e4b-9h5f-bb1c-cbbfa4047247",
      "created_at": "2025-01-01T12:00:00.000Z",
      "metadescription": "....."
    },
    ......
  ],
  "error": null,
  "current_start_range": 0,
  "current_end_range": 11
}

Fields overview

Field

Type

Description

id

String

Unique identifier for the tag.

name

String

The display name of the tag.

title

String

URL-friendly version of the tag name, used in the tag's URL.

createdby

String

The ID of the user who created the tag.

created_at

String (ISO 8601 Date)

Timestamp indicating when the tag was created.

metadescription

String

The meta description for the tag, used in SEO and previews.

error

String or null

Error message if any issues occurred, otherwise null.

current_start_range

Integer

Index of the first tag in the current range of displayed tags.

current_end_range

Integer

Index of the last tag in the current range of displayed tags.


6. Settings

Retrieve blog-wide settings.

Endpoint

GET /settings

Example Request

GET https://<your-subdomain>.typeflo.io/api/headless/content/settings
Authorization: Bearer YOUR_CONTENT_API_KEY

Example Response

{
  "data": [
    {
      "id": "fafa8eee5-a7eb-4134-ad56-b9865822de4b",
      "subdomain": "demo",
      "heading": "Hi 👋 We are Growmmerce",
      "description": "<p>Growmmerce enables individuals ....</p>",
      "posts": 5,
      "category": 3,
      "authors": 3,
      "subscribers": 10,
      "created_at": "2023-10-20T13:54:46.592+00:00",
      "logoimg": "https://auth.typeflo.io/storage/..../logo.jpeg",
      "logoimgdark": "https://auth.typeflo.io/storage/..../logodark.jpeg",
      "faviconimg": "https://auth.typeflo.io/storage/..../favicon.jpeg",
      "metatitle": "Growmmerce Blog",
      "metadescription": "....",
      "custom_domain": {
        "status": true,
        "domain": "https://example.com"
      },
      "theme": {
        "theme_colour": "#1E3A8A",
        "layout": "list",
        "translation_strings": null,
        "toc_global": true,
        "rtl": false
      },
      "integrations": {
        "disqus": {
          "disqus_url": "",
          "status": "disabled"
        },
        "ga4": null,
        "gsc": {
          "script_url": "",
          "status": "disabled"
        },
        "adsense": {
          "pub_id": "",
          "status": "disabled"
        }
      },
      "custom_code": {
        "header_code": "",
        "footer_code": "",
        "custom_css": ""
      },
      "newslettermode": true,
      "newsletter": {
        "title": "Signup for the newsletter",
        "subtitle": "....",
        "popup": {
          "title": "Signup for the newsletter",
          "subtitle": "....",
          "acceptance": ""
        },
        "exit_intent": {
          "title": "Wait! Signup for our newsletter before you go?",
          "subtitle": "....",
          "acceptance": ""
        },
        "webhook_url": ""
      },
      "darkmode": true,
      "footertxt": ""
    },
    ......
  ],
  "error": null,
  "current_start_range": 0,
  "current_end_range": 11
}

Fields overview

Field

Type

Description

id

String

Unique identifier for the blog.

subdomain

String

The subdomain associated with the blog.

heading

String

The main heading for the project or blog.

description

String (HTML)

HTML content describing the blog.

posts

Integer

The number of posts published.

category

Integer

The number of categories available.

authors

Integer

The number of authors contributing to the blog.

subscribers

Integer

The number of subscribers.

created_at

String (ISO 8601 Date)

Timestamp indicating when the blog were created.

logoimg

String (URL)

URL for the logo image used in light mode.

logoimgdark

String (URL)

URL for the logo image used in dark mode.

faviconimg

String (URL)

URL for the favicon image.

metatitle

String

The meta title for the blog, used in SEO and previews.

metadescription

String

The meta description for the blog, used in SEO and previews.

custom_domain

Object

Details of the custom domain configuration. Includes status (Boolean) and domain (String).

theme

Object

Theme configuration, including theme_colour, layout, translation_strings, toc_global, and rtl.

integrations

Object

Integrations configuration. Includes options for Disqus, Google Analytics 4 (GA4), Google Search Console (GSC), and AdSense.

custom_code

Object

Custom code injection options. Includes header_code, footer_code, and custom_css.

newslettermode

Boolean

Indicates if the newsletter mode is enabled.

newsletter

Object

Newsletter configuration, including title, subtitle, and options for popup and exit_intent.

darkmode

Boolean

Indicates if dark mode is enabled.

footertxt

String

Custom text to display in the footer.

error

String or null

Error message if any issues occurred, otherwise null.


Filters

Filtering are the parameters that can be used in typeflo to fetch the specific content. It can be applied for below URLs

GET /posts
GET /pages
GET /category
GET /tags
GET /authors

Posts parameters

Parameter

Description

Example Query

Example Result

slug

Filters posts by their unique slug.

?slug=sample-post

Returns posts where the slug is "sample-post".

author

Filters posts by the author's unique identifier.

?author=0423169c-8e4b-43e6-bb1c-cbbfa4047247

Returns posts authored by the specified ID.

title

Filters posts by the title

?title=Sample%20Post

Returns posts with the title "Sample Post".

toc_status

Filters posts by their table of contents (ToC) status.

?toc_status=true

Returns posts with ToC enabled.

restriction.status

Filters posts based on their restriction status.

?restriction.status=false

Returns non-restricted posts.

restriction.percentage

Filters posts by the percentage of content restricted.

?restriction.percentage=30

Returns posts where 30% of the content is restricted.

is_draft

Filters posts based on their draft status.

?is_draft=true

Returns only draft posts.

Other Parameters

Any other supported field from the post schema can be used as a parameter to filter results.

?metatitle=Sample%20Post

Returns posts with the metatitle "Sample Post".

Excluded Fields

The following fields cannot be used in the query as they result in an error if included:

  • content

  • excerpt

  • reading_time

  • scheduled

  • created_at

  • featured_image

  • categories

  • tags

  • metadescription

  • docsid

  • opengraph

Example Query

https://<your-subdomain>.typeflo.io/api/headless/content/posts?slug=sample-post&author=0423169c-45eb-43e6-bb1c-cbbfa4047247&is_draft=false&toc_status=true&restriction.status=false

Pages Parameters

Parameter

Description

Example Query

Example Result

slug

Filters pages by their unique slug.

?slug=sample-page

Returns pages where the slug is "sample-page".

title

Filters pages by their title.

?title=Sample%20Page

Returns pages with the title "Sample Page".

is_draft

Filters pages based on their draft status.

?is_draft=true

Returns only draft page

Other Parameters

Any other supported field from the page schema can be used as a parameter to filter results.

?metatitle=SEO%20Page

Returns pages with the meta title "SEO Page".

Excluded Fields

The following fields cannot be used in the query as they result in an error if included:

  • postedby

  • content

  • created_at

  • docsid

  • metadescription

Example Query

https://<your-subdomain>.typeflo.io/api/headless/content/pages?slug=sample-page&is_draft=false

Author Parameters

Parameter

Description

Example Query

Example Result

slug

Filters authors by their unique slug.

?slug=adam-steve

Returns authors where the slug is "adam-steve".

name

Filters authors by their name.

?name=Adam%20Steve

Returns authors with the name "Adam Steve".

email

Filters authors by their email address.

[email protected]

Returns authors with the email "[email protected]".

Excluded Fields

The following fields cannot be used in the query as they result in an error if included:

  • createdby

  • created_at

  • avatar

  • socials

  • description

  • metadescription

Example Query

https://<your-subdomain>.typeflo.io/api/headless/content/authors?slug=adam-steve&name=Adam%20Steve&[email protected]

Category Parameters

Parameter

Description

Example Query

Example Result

slug

Filters categories by their unique slug.

?slug=social-media

Returns categories where the slug is "social-media".

name

Filters categories by their name.

?name=Social%20Media

Returns categories with the name "Social Media".

Excluded Fields

The following fields cannot be used in the query as they result in an error if included:

  • createdby

  • created_at

  • metadescription

Example Query

https://<your-subdomain>.typeflo.io/api/headless/content/category?slug=social-media&name=Social%20Media

Tags Parameters

Parameter

Description

Example Query

Example Result

slug

Filters tags by their unique slug.

?slug=general

Returns tags where the slug is "general".

name

Filters tags by their name.

?name=General

Returns tagswith the name "General".

Excluded Fields

The following fields cannot be used in the query as they result in an error if included:

  • createdby

  • created_at

  • metadescription

Example Query

https://<your-subdomain>.typeflo.io/api/headless/content/tags?slug=general&name=General

Common Parameters

Parameter

Description

Example Query

Example Result

limit

Sets the maximum number of results to be returned. Default is 100 if not specified.

?limit=50

Returns up to 50 items.

Example Query

https://<your-subdomain>.typeflo.io/api/headless/content/posts?limit=150

Pagination

Parameter

Description

Example Query

Example Result

start_range

Specifies the starting index of the results to fetch, enabling pagination.

?start_range=10

Fetches results starting from the 10th record.

end_range

Specifies the ending index of the results to fetch, enabling pagination.

?end_range=19

Fetches results up to the 19th record (inclusive).

When used together, start_range and end_range allow to paginate through the dataset. Ensure that the difference between end_range and start_range aligns with the limit parameter, if used.

Error Handling

The API returns standard HTTP status codes to indicate success or failure.

Code

Meaning

Description

200

OK

The request was successful.

400

Bad Request

The request could not be understood or was missing parameters.

401

Unauthorized

The API key is missing or invalid.

404

Not Found

The requested resource could not be found.

406

Not Acceptable

The server is unable to provide a response that matches the client's requested format

500

Internal Server Error

An error occurred on the server.

Share help article

Need help? We've got your back!

If you're stuck while trying to accomplish a task or want to give feedback on our documentation, please reach out to us. You can contact us via live chat or email.
Loading...