Skip to content

Blogs & articles

Read the store's blogs, write and update blog articles, and take an SEO tool's publishing webhook

Updated View as Markdown

A store’s blog is a set of articles shown at /blogs/{blog}/{article} on its storefront. These endpoints let your own systems, or an SEO tool, publish to it: write and update articles in this API’s format, or send an SEO tool’s publish_articles webhook straight to POST /v1/articles/webhook.

Reading needs the blogs:read ability and every write needs blogs:write. See Authentication for how abilities are attached to a token. All seven endpoints share the standard 60 requests-per-minute-per-store budget.

Identifiers

Blogs and articles are addressed by UUID: blog_id and article_id. An article also keeps your own id for it in external_id, unique per store. Sending an article again with the same external_id updates it instead of creating a copy, so a retried request never duplicates a post.

Publishing from an SEO tool

Some AI SEO tools push each article they publish to a webhook, in their own publish_articles format. When the tool lets you set the access token it sends, you can publish its articles to a FirearmCart store:

  1. Create an API token with Blogs: Write on the store.
  2. In the tool’s webhook settings, set the URL to https://api.firearmcart.com/v1/articles/webhook and the access token to that API token.
  3. Send the tool’s test.

Add ?blog=<handle> to the URL to publish into a particular blog, and ?status=draft to save new articles as drafts for review. The field mapping and update rules are under the webhook endpoint.

What this API cannot do

There is no delete: unpublish an article with PATCH and "status": "draft", and delete it in the dashboard. Blogs can’t be renamed or removed through the API, an article can’t be moved to another blog, and its handle never changes after it’s created, so a published URL keeps working.

List blogs

GET/v1/blogs
Returns every blog on the store, oldest first, with how many articles each has and how many are published. A store has a handful of blogs at most, so the list is not paginated.
Required ability
blogs:read
Rate limit
60 requests/minute per team
Caveats
  • A store that has never had an article has no blogs. The first article creates a "News" blog, the same as the dashboard does.
Requestbash
curl https://api.firearmcart.com/v1/blogs \
  -H "Authorization: Bearer $FIREARMCART_TOKEN" \
  -H "Accept: application/json"
200Every blog, in `data`, with no `links` or `meta`.
{
  "data": [
    {
      "blog_id": "0199f3a2-5d1e-7c40-9a6b-2e8f4c1d7b30",
      "title": "News",
      "handle": "news",
      "path": "/blogs/news",
      "url": "https://www.example.com/blogs/news",
      "is_active": true,
      "articles_count": 14,
      "published_articles_count": 12,
      "created_at": "2026-01-19T16:02:11+00:00",
      "updated_at": "2026-01-19T16:02:11+00:00"
    }
  ]
}
403The token is valid but was not granted the `blogs:read` ability.
{
  "message": "Invalid ability provided."
}

Create a blog

POST/v1/blogs
Adds a blog to the store. Its URL is `/blogs/{handle}`.
Required ability
blogs:write
Rate limit
60 requests/minute per team

Body parameters

titlestringrequired
Between 2 and 255 characters.
Example: Guides
handlestringoptional
The URL handle, max 100 characters. Defaults to the title, made URL-safe. It is made unique within the store by adding `-2`, `-3`.
Example: guides
Requestbash
curl -X POST https://api.firearmcart.com/v1/blogs \
  -H "Authorization: Bearer $FIREARMCART_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"title": "Guides"}'
201The new blog. The two article counts are left out.
{
  "data": {
    "blog_id": "0199f3c1-07aa-7d51-8e2f-91b4d6a0c3e8",
    "title": "Guides",
    "handle": "guides",
    "path": "/blogs/guides",
    "url": "https://www.example.com/blogs/guides",
    "is_active": true,
    "created_at": "2026-10-22T15:40:12+00:00",
    "updated_at": "2026-10-22T15:40:12+00:00"
  }
}
403The token is valid but was not granted the `blogs:write` ability.
{
  "message": "Invalid ability provided."
}

List articles

GET/v1/articles
Returns the store's articles across all its blogs, newest first by `created_at`, in a standard length-aware page. Each article is returned without its `content`; fetch one article to read its body.
Required ability
blogs:read
Rate limit
60 requests/minute per team

Query parameters

blog_idstring (uuid)optional
Only articles in this blog.
Example: 0199f3a2-5d1e-7c40-9a6b-2e8f4c1d7b30
statusstringoptional
`draft`, `published` or `scheduled`.
Example: published
tagstringoptional
Only articles with this tag, matched by name regardless of case and punctuation.
Example: Holsters
external_idstringoptional
The article with this `external_id`, if the store has one.
Example: cms-42
updated_sincestring (ISO 8601)optional
Only articles changed at or after this time. Useful for syncing.
Example: 2026-10-01T00:00:00Z
per_pageintegeroptional
Results per page. Defaults to 25, clamped between 1 and 100.
Example: 50
pageintegeroptional
Page number. Defaults to 1.
Example: 2
Caveats
  • Pagination links drop your filters. Re-send them with each page rather than following `links.next` as-is.
Requestbash
curl -G https://api.firearmcart.com/v1/articles \
  -H "Authorization: Bearer $FIREARMCART_TOKEN" \
  -H "Accept: application/json" \
  --data-urlencode "status=published" \
  --data-urlencode "per_page=50"
200A page of articles in the standard `data` / `links` / `meta` envelope, each without `content`.
No response body.
422A filter is malformed, such as a `blog_id` that isn't a UUID or an unknown `status`.
{
  "message": "The blog id field must be a valid UUID.",
  "errors": {
    "blog_id": ["The blog id field must be a valid UUID."]
  }
}
403The token is valid but was not granted the `blogs:read` ability.
{
  "message": "Invalid ability provided."
}

Retrieve an article

GET/v1/articles/{article_id}
Returns one article with its full `content`.
Required ability
blogs:read
Rate limit
60 requests/minute per team

Path parameters

article_idstring (uuid)required
The article's `article_id`. Anything that isn't a UUID is a 404.
Example: 0199f3b8-41c7-7e2a-b5d0-6c3a9e7f1d24
Requestbash
curl https://api.firearmcart.com/v1/articles/0199f3b8-41c7-7e2a-b5d0-6c3a9e7f1d24 \
  -H "Authorization: Bearer $FIREARMCART_TOKEN" \
  -H "Accept: application/json"
200The article, wrapped in `data`.
{
  "data": {
    "article_id": "0199f3b8-41c7-7e2a-b5d0-6c3a9e7f1d24",
    "blog": {
      "blog_id": "0199f3a2-5d1e-7c40-9a6b-2e8f4c1d7b30",
      "handle": "news",
      "title": "News"
    },
    "title": "Choosing a carry holster",
    "handle": "choosing-a-carry-holster",
    "path": "/blogs/news/choosing-a-carry-holster",
    "url": "https://www.example.com/blogs/news/choosing-a-carry-holster",
    "status": "published",
    "published_at": "2026-10-22T15:30:00+00:00",
    "excerpt": "What to look for in an everyday carry holster.",
    "content": "<h2>Fit</h2><p>Comfort first.</p>",
    "author_name": "Range Staff",
    "tags": ["Carry", "Holsters"],
    "image": {
      "url": "https://cdn.firearmcart.com/media/8812/holster.jpg",
      "alt": "A leather IWB holster"
    },
    "meta_title": "Choosing a carry holster",
    "meta_description": "Fit, retention and comfort: how to pick an everyday carry holster.",
    "external_id": "cms-42",
    "created_at": "2026-10-22T15:30:00+00:00",
    "updated_at": "2026-10-22T15:30:00+00:00"
  }
}
404No article with that id belongs to your store.
{
  "error": "not_found",
  "message": "Article not found."
}

Create an article

POST/v1/articles
Writes a blog article. Send `external_id` with your own system's id for it, and sending the same `external_id` again updates that article instead of creating a copy, so a retried request is always safe.
Required ability
blogs:write
Rate limit
60 requests/minute per team

Body parameters

blog_idstring (uuid)optional
The blog to write into. Without it the article goes into the store's only blog, or into a new "News" blog when the store has none. A store with several blogs needs it.
Example: 0199f3a2-5d1e-7c40-9a6b-2e8f4c1d7b30
titlestringrequired
Max 255 characters.
Example: Choosing a carry holster
contentstring (HTML)required
The article body as HTML. It is cleaned before it is saved (see the notes): scripts, frames, forms, event handlers and styles other than text alignment are removed, and images keep an https `src` only.
Example: <h2>Fit</h2><p>Comfort first.</p>
excerptstringoptional
Short summary shown in blog listings, max 500 characters. Themes fall back to the start of the body.
Example: What to look for in an everyday carry holster.
statusstringoptional
`draft`, `published` or `scheduled`. Defaults to `draft`. Only `published` shows on the storefront.
Example: published
published_atstring (ISO 8601)optional
For `scheduled`, the future time it goes live (required). For `published`, an optional past date to backdate it; otherwise it is the time of publishing, and re-publishing keeps the original date. Ignored for drafts.
Example: 2026-10-22T15:30:00Z
author_namestringoptional
The byline, max 255 characters.
Example: Range Staff
tagsarray<string>optional
Tag names, up to 50. Tags that don't exist yet are created.
Example: ["Carry", "Holsters"]
imageobjectoptional
The featured image: `{ "url": "https://…", "alt": "…" }` or `{ "media_id": "…", "alt": "…" }`. A `url` is copied into the store's media library in the background, so `image` reads `null` until the copy is done (usually under a minute). A `media_id` is an image already in the library.
Example: {"url": "https://images.example.com/holster.jpg", "alt": "A leather IWB holster"}
meta_titlestringoptional
SEO title, max 70 characters. Without one, the storefront uses the title.
Example: Choosing a carry holster
meta_descriptionstringoptional
SEO description, max 160 characters. Without one, the storefront uses the excerpt.
Example: Fit, retention and comfort: how to pick an everyday carry holster.
handlestringoptional
The URL handle, max 100 characters. Defaults to the title, made URL-safe and unique within the blog.
Example: choosing-a-carry-holster
external_idstringoptional
Your own id for the article, max 191 characters, unique per store. An article that already has it is updated: the fields you send replace its own, and its blog and handle stay as they are.
Example: cms-42
Caveats
  • **What a body keeps.** Paragraphs, headings, bold and italic, lists, quotes, tables, links and https images. Scripts, styles, frames and embeds, forms and every event handler are removed; a `<figure>` is kept as plain blocks and a `<picture>` as its `<img>`. Links are not made `nofollow`, and a `rel` of `nofollow`, `sponsored` or `ugc` is kept.
  • **Handles never change.** The handle is set when the article is created (from `handle`, or from the title), made unique within its blog by adding `-2`, `-3`, and kept for the life of the article so its URL never breaks.
  • **Images are copies.** An image `url` is downloaded once into the store's media library (the **Files** page) and the article points at the copy. It must be a public https JPG, PNG, GIF or WebP up to 10 MB. If it can't be copied, the article has no featured image; nothing else about the write fails.
Requestbash
curl -X POST https://api.firearmcart.com/v1/articles \
  -H "Authorization: Bearer $FIREARMCART_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Choosing a carry holster",
    "content": "<h2>Fit</h2><p>Comfort first.</p>",
    "status": "published",
    "tags": ["Carry", "Holsters"],
    "image": {"url": "https://images.example.com/holster.jpg", "alt": "A leather IWB holster"},
    "external_id": "cms-42"
  }'
201The article was created. An image sent by `url` is still being copied, so `image` reads `null`.
{
  "data": {
    "article_id": "0199f3b8-41c7-7e2a-b5d0-6c3a9e7f1d24",
    "blog": {
      "blog_id": "0199f3a2-5d1e-7c40-9a6b-2e8f4c1d7b30",
      "handle": "news",
      "title": "News"
    },
    "title": "Choosing a carry holster",
    "handle": "choosing-a-carry-holster",
    "path": "/blogs/news/choosing-a-carry-holster",
    "url": "https://www.example.com/blogs/news/choosing-a-carry-holster",
    "status": "published",
    "published_at": "2026-10-22T15:30:00+00:00",
    "excerpt": "What to look for in an everyday carry holster.",
    "content": "<h2>Fit</h2><p>Comfort first.</p>",
    "author_name": "Range Staff",
    "tags": ["Carry", "Holsters"],
    "image": {
      "url": "https://cdn.firearmcart.com/media/8812/holster.jpg",
      "alt": "A leather IWB holster"
    },
    "meta_title": "Choosing a carry holster",
    "meta_description": "Fit, retention and comfort: how to pick an everyday carry holster.",
    "external_id": "cms-42",
    "created_at": "2026-10-22T15:30:00+00:00",
    "updated_at": "2026-10-22T15:30:00+00:00"
  }
}
200An article with this `external_id` already existed and was updated.
{
  "data": {
    "article_id": "0199f3b8-41c7-7e2a-b5d0-6c3a9e7f1d24",
    "blog": {
      "blog_id": "0199f3a2-5d1e-7c40-9a6b-2e8f4c1d7b30",
      "handle": "news",
      "title": "News"
    },
    "title": "Choosing a carry holster",
    "handle": "choosing-a-carry-holster",
    "path": "/blogs/news/choosing-a-carry-holster",
    "url": "https://www.example.com/blogs/news/choosing-a-carry-holster",
    "status": "published",
    "published_at": "2026-10-22T15:30:00+00:00",
    "excerpt": "What to look for in an everyday carry holster.",
    "content": "<h2>Fit</h2><p>Comfort first.</p>",
    "author_name": "Range Staff",
    "tags": ["Carry", "Holsters"],
    "image": {
      "url": "https://cdn.firearmcart.com/media/8812/holster.jpg",
      "alt": "A leather IWB holster"
    },
    "meta_title": "Choosing a carry holster",
    "meta_description": "Fit, retention and comfort: how to pick an everyday carry holster.",
    "external_id": "cms-42",
    "created_at": "2026-10-22T15:30:00+00:00",
    "updated_at": "2026-10-22T15:30:00+00:00"
  }
}
422The request can't be saved. A failed field rule gives the standard validation body; a rule about the store gives an `error` slug: `blog_not_found`, `blog_required`, `handle_invalid`, `published_at_invalid`, `content_empty` or `image_not_found`.
{
  "success": false,
  "error": "blog_required",
  "message": "This store has several blogs (news, guides). Send blog_id to say which one."
}
409Another request with the same `external_id` is still being saved. Retry it unchanged.
{
  "success": false,
  "error": "in_progress",
  "message": "Another request with this external_id is still being saved. Retry shortly."
}
403The token is valid but was not granted the `blogs:write` ability.
{
  "message": "Invalid ability provided."
}

Update an article

PATCH/v1/articles/{article_id}
Changes the fields you send and leaves the rest. An article's handle, blog and `external_id` can't be changed, so its URL stays the same.
Required ability
blogs:write
Rate limit
60 requests/minute per team

Path parameters

article_idstring (uuid)required
The article's `article_id`.
Example: 0199f3b8-41c7-7e2a-b5d0-6c3a9e7f1d24

Body parameters

titlestringoptional
Max 255 characters. Changing it does not change the handle or the URL.
Example: Choosing a carry holster
contentstring (HTML)optional
The article body as HTML. It is cleaned before it is saved (see the notes): scripts, frames, forms, event handlers and styles other than text alignment are removed, and images keep an https `src` only.
Example: <h2>Fit</h2><p>Comfort first.</p>
excerptstringoptional
Short summary shown in blog listings, max 500 characters. Themes fall back to the start of the body.
Example: What to look for in an everyday carry holster.
statusstringoptional
`draft`, `published` or `scheduled`. Leaving it out keeps the current status. Only `published` shows on the storefront.
Example: published
published_atstring (ISO 8601)optional
For `scheduled`, the future time it goes live (required). For `published`, an optional past date to backdate it; otherwise it is the time of publishing, and re-publishing keeps the original date. Ignored for drafts.
Example: 2026-10-22T15:30:00Z
author_namestringoptional
The byline, max 255 characters.
Example: Range Staff
tagsarray<string>optional
Tag names, up to 50. Tags that don't exist yet are created. Replaces the article's tags; `[]` removes them all.
Example: ["Carry", "Holsters"]
imageobjectoptional
The featured image: `{ "url": "https://…", "alt": "…" }` or `{ "media_id": "…", "alt": "…" }`. A `url` is copied into the store's media library in the background, so `image` reads `null` until the copy is done (usually under a minute). A `media_id` is an image already in the library. `"image": null` removes the featured image.
Example: {"url": "https://images.example.com/holster.jpg", "alt": "A leather IWB holster"}
meta_titlestringoptional
SEO title, max 70 characters. Without one, the storefront uses the title.
Example: Choosing a carry holster
meta_descriptionstringoptional
SEO description, max 160 characters. Without one, the storefront uses the excerpt.
Example: Fit, retention and comfort: how to pick an everyday carry holster.
Caveats
  • Unpublish an article with `{"status": "draft"}`. There is no delete endpoint; delete articles in the dashboard.
  • An update that changes nothing saves nothing, so the storefront isn't refreshed for it.
Requestbash
curl -X PATCH https://api.firearmcart.com/v1/articles/0199f3b8-41c7-7e2a-b5d0-6c3a9e7f1d24 \
  -H "Authorization: Bearer $FIREARMCART_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"status": "draft"}'
200The article as it now is.
{
  "data": {
    "article_id": "0199f3b8-41c7-7e2a-b5d0-6c3a9e7f1d24",
    "blog": {
      "blog_id": "0199f3a2-5d1e-7c40-9a6b-2e8f4c1d7b30",
      "handle": "news",
      "title": "News"
    },
    "title": "Choosing a carry holster",
    "handle": "choosing-a-carry-holster",
    "path": "/blogs/news/choosing-a-carry-holster",
    "url": "https://www.example.com/blogs/news/choosing-a-carry-holster",
    "status": "published",
    "published_at": "2026-10-22T15:30:00+00:00",
    "excerpt": "What to look for in an everyday carry holster.",
    "content": "<h2>Fit</h2><p>Comfort first.</p>",
    "author_name": "Range Staff",
    "tags": ["Carry", "Holsters"],
    "image": {
      "url": "https://cdn.firearmcart.com/media/8812/holster.jpg",
      "alt": "A leather IWB holster"
    },
    "meta_title": "Choosing a carry holster",
    "meta_description": "Fit, retention and comfort: how to pick an everyday carry holster.",
    "external_id": "cms-42",
    "created_at": "2026-10-22T15:30:00+00:00",
    "updated_at": "2026-10-22T15:30:00+00:00"
  }
}
422A field failed validation, or the request tried to change the handle, blog or `external_id`.
{
  "message": "An article's handle can't be changed, so its URL stays the same.",
  "errors": {
    "handle": ["An article's handle can't be changed, so its URL stays the same."]
  }
}
404No article with that id belongs to your store.
{
  "error": "not_found",
  "message": "Article not found."
}

Receive an SEO tool's publishing webhook

POST/v1/articles/webhook
Takes the `publish_articles` webhook that AI SEO tools send when an article is published, in the tool's own format, and writes each article into the store's blog. Point the tool's webhook at this URL and give it an API token with `blogs:write` as its access token.
Required ability
blogs:write
Rate limit
60 requests/minute per team

Query parameters

blogstringoptional
The handle of the blog to publish into. Without it, articles go into the store's only blog, or a new "News" blog.
Example: news
statusstringoptional
`published` (the default) or `draft`, for new articles only.
Example: draft

Body parameters

data.articlesarray<object>required
The tool's articles. Each needs an `id` and a `title`, plus `content_html` or `content_markdown`. See the notes for how each field is used. A body with no articles is acknowledged and does nothing.
Caveats
  • **Field mapping.** `id` becomes the article's `external_id`; `title`, `author_name`, `meta_title` and `meta_description` map to the same fields; `subtitle` becomes the excerpt; `slug` becomes the handle; `tags` plus `category` become tags; `image_url` becomes the featured image; `content_html` (or `content_markdown`) becomes the body. `faqs` are added to the end of the body as a "Frequently asked questions" section unless the body already has them. `type`, `read_time`, `word_count`, `author_title`, `author_initials`, `breadcrumb_title`, `video_embeds` and `recommended_articles` are ignored.
  • **Headings.** The storefront prints the title as the page's heading, so a first heading that repeats the title is dropped and any other `<h1>` in the body becomes an `<h2>`.
  • **Re-sends update.** An article whose `id` the store already has is updated in place: its title, body, excerpt, SEO fields, author, tags and images are replaced by what the tool sent. Its status, handle and publish date are kept, so an article the merchant unpublished stays unpublished.
  • **Lengths are fitted, not refused.** A `meta_title` over 70 characters, a `meta_description` over 160 or a `subtitle` over 500 is shortened at a word with an ellipsis.
  • **Publish dates.** A new published article is dated by the tool's `created_at` (or `publish_date`) when that is in the past, otherwise by the time it arrived.
  • **Images** in the body and `image_url` are copied into the store's media library in the background and the article then points at the copies. An image copied once is never downloaded again.
  • **Test sends.** A tool's documented sample article (`id` `123456` with the slug `how-to-implement-webhooks`) is listed under `skipped` with the reason `test` and never published.
Requestbash
curl -X POST "https://api.firearmcart.com/v1/articles/webhook?blog=news" \
  -H "Authorization: Bearer $FIREARMCART_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "publish_articles",
    "timestamp": "2026-10-22T12:00:00Z",
    "data": {
      "articles": [
        {
          "id": "789012",
          "title": "How to Clean a Pistol",
          "slug": "how-to-clean-a-pistol",
          "subtitle": "A step-by-step guide",
          "content_html": "<h2>What you need</h2><p>A cleaning rod, solvent and patches.</p>",
          "meta_title": "How to Clean a Pistol",
          "meta_description": "Field strip, clean and lube your pistol in ten minutes.",
          "author_name": "Range Staff",
          "category": "Maintenance",
          "tags": ["cleaning", "pistols"],
          "image_url": "https://images.example.com/cleaning.jpg",
          "faqs": [{"name": "How often should I clean it?", "answer": "After every range trip."}],
          "created_at": "2026-10-22T12:00:00Z"
        }
      ]
    }
  }'
200Every article was saved or skipped. `created` and `updated` list each article by the tool's `id` with the store's `article_id` and URL; `skipped` lists the tool's test articles.
{
  "data": {
    "created": [
      {
        "id": "789012",
        "article_id": "0199f3d4-8b2e-7f10-a3c5-4d7e9b1f6a82",
        "url": "https://www.example.com/blogs/news/how-to-clean-a-pistol"
      }
    ],
    "updated": [],
    "skipped": [],
    "failed": []
  }
}
422At least one article couldn't be saved; the others were. `failed` lists why, so the tool can show it. When the tool retries, the articles already saved are updated again rather than duplicated.
{
  "data": {
    "created": [],
    "updated": [],
    "skipped": [],
    "failed": [
      {
        "id": "789013",
        "errors": ["The title field is required."]
      }
    ]
  }
}
401The access token is missing or wrong. This endpoint always answers in JSON, even without an `Accept` header.
{
  "message": "Unauthenticated."
}
Navigation

Type to search…

↑↓ navigate↵ selectEsc close