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:
- Create an API token with Blogs: Write on the store.
- In the tool’s webhook settings, set the URL to
https://api.firearmcart.com/v1/articles/webhookand the access token to that API token. - 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
/v1/blogs- Required ability
blogs:read- Rate limit
- 60 requests/minute per team
- A store that has never had an article has no blogs. The first article creates a "News" blog, the same as the dashboard does.
curl https://api.firearmcart.com/v1/blogs \
-H "Authorization: Bearer $FIREARMCART_TOKEN" \
-H "Accept: application/json"{
"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"
}
]
}{
"message": "Invalid ability provided."
}Create a blog
/v1/blogs- 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
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"}'{
"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"
}
}{
"message": "Invalid ability provided."
}List articles
/v1/articles- 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
- Pagination links drop your filters. Re-send them with each page rather than following `links.next` as-is.
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"{
"message": "The blog id field must be a valid UUID.",
"errors": {
"blog_id": ["The blog id field must be a valid UUID."]
}
}{
"message": "Invalid ability provided."
}Retrieve an article
/v1/articles/{article_id}- 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
curl https://api.firearmcart.com/v1/articles/0199f3b8-41c7-7e2a-b5d0-6c3a9e7f1d24 \
-H "Authorization: Bearer $FIREARMCART_TOKEN" \
-H "Accept: application/json"{
"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"
}
}{
"error": "not_found",
"message": "Article not found."
}Create an article
/v1/articles- 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
- **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.
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"
}'{
"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"
}
}{
"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"
}
}{
"success": false,
"error": "blog_required",
"message": "This store has several blogs (news, guides). Send blog_id to say which one."
}{
"success": false,
"error": "in_progress",
"message": "Another request with this external_id is still being saved. Retry shortly."
}{
"message": "Invalid ability provided."
}Update an article
/v1/articles/{article_id}- 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.
- 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.
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"}'{
"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"
}
}{
"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."]
}
}{
"error": "not_found",
"message": "Article not found."
}Receive an SEO tool's publishing webhook
/v1/articles/webhook- 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.
- **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.
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"
}
]
}
}'{
"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": []
}
}{
"data": {
"created": [],
"updated": [],
"skipped": [],
"failed": [
{
"id": "789013",
"errors": ["The title field is required."]
}
]
}
}{
"message": "Unauthenticated."
}
