Create a blog post

curl --request POST \
  --url https://api.mercemur.com/api/v1/blog-posts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "slug": "<string>",
  "title": "<string>",
  "excerpt": "<string>",
  "body": {},
  "cover_image_url": "<string>",
  "author_name": "<string>",
  "author_bio": "<string>",
  "tags": [
    "<string>"
  ],
  "reading_time_minutes": 123,
  "seo_meta_title": "<string>",
  "seo_meta_description": "<string>",
  "seo_og_image_url": "<string>",
  "category_id": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    slug: '<string>',
    title: '<string>',
    excerpt: '<string>',
    body: JSON.stringify({}),
    cover_image_url: '<string>',
    author_name: '<string>',
    author_bio: '<string>',
    tags: ['<string>'],
    reading_time_minutes: 123,
    seo_meta_title: '<string>',
    seo_meta_description: '<string>',
    seo_og_image_url: '<string>',
    category_id: '<string>'
  })
};

fetch('https://api.mercemur.com/api/v1/blog-posts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.mercemur.com/api/v1/blog-posts"

payload = {
    "slug": "<string>",
    "title": "<string>",
    "excerpt": "<string>",
    "body": {},
    "cover_image_url": "<string>",
    "author_name": "<string>",
    "author_bio": "<string>",
    "tags": ["<string>"],
    "reading_time_minutes": 123,
    "seo_meta_title": "<string>",
    "seo_meta_description": "<string>",
    "seo_og_image_url": "<string>",
    "category_id": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mercemur.com/api/v1/blog-posts"

	payload := strings.NewReader("{\n  \"slug\": \"<string>\",\n  \"title\": \"<string>\",\n  \"excerpt\": \"<string>\",\n  \"body\": {},\n  \"cover_image_url\": \"<string>\",\n  \"author_name\": \"<string>\",\n  \"author_bio\": \"<string>\",\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"reading_time_minutes\": 123,\n  \"seo_meta_title\": \"<string>\",\n  \"seo_meta_description\": \"<string>\",\n  \"seo_og_image_url\": \"<string>\",\n  \"category_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.mercemur.com/api/v1/blog-posts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'slug' => '<string>',
    'title' => '<string>',
    'excerpt' => '<string>',
    'body' => [
        
    ],
    'cover_image_url' => '<string>',
    'author_name' => '<string>',
    'author_bio' => '<string>',
    'tags' => [
        '<string>'
    ],
    'reading_time_minutes' => 123,
    'seo_meta_title' => '<string>',
    'seo_meta_description' => '<string>',
    'seo_og_image_url' => '<string>',
    'category_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "data": {
    "author_bio": "<string>",
    "author_name": "<string>",
    "body": {
      "content": [
        {
          "content": [
            {
              "text": "<string>",
              "type": "<string>"
            }
          ],
          "type": "<string>"
        }
      ],
      "type": "<string>"
    },
    "category": {
      "id": "<string>",
      "name": "<string>",
      "slug": "<string>"
    },
    "cover_image_url": "<string>",
    "created_at": "<string>",
    "excerpt": "<string>",
    "id": "<string>",
    "published_at": "<string>",
    "reading_time_minutes": 123,
    "seo_meta_description": "<string>",
    "seo_meta_title": "<string>",
    "seo_og_image_url": "<string>",
    "slug": "<string>",
    "status": "<string>",
    "tags": [
      "<string>"
    ],
    "title": "<string>",
    "updated_at": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

POST

api

blog-posts

Create a blog post

curl --request POST \
  --url https://api.mercemur.com/api/v1/blog-posts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "slug": "<string>",
  "title": "<string>",
  "excerpt": "<string>",
  "body": {},
  "cover_image_url": "<string>",
  "author_name": "<string>",
  "author_bio": "<string>",
  "tags": [
    "<string>"
  ],
  "reading_time_minutes": 123,
  "seo_meta_title": "<string>",
  "seo_meta_description": "<string>",
  "seo_og_image_url": "<string>",
  "category_id": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    slug: '<string>',
    title: '<string>',
    excerpt: '<string>',
    body: JSON.stringify({}),
    cover_image_url: '<string>',
    author_name: '<string>',
    author_bio: '<string>',
    tags: ['<string>'],
    reading_time_minutes: 123,
    seo_meta_title: '<string>',
    seo_meta_description: '<string>',
    seo_og_image_url: '<string>',
    category_id: '<string>'
  })
};

fetch('https://api.mercemur.com/api/v1/blog-posts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.mercemur.com/api/v1/blog-posts"

payload = {
    "slug": "<string>",
    "title": "<string>",
    "excerpt": "<string>",
    "body": {},
    "cover_image_url": "<string>",
    "author_name": "<string>",
    "author_bio": "<string>",
    "tags": ["<string>"],
    "reading_time_minutes": 123,
    "seo_meta_title": "<string>",
    "seo_meta_description": "<string>",
    "seo_og_image_url": "<string>",
    "category_id": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mercemur.com/api/v1/blog-posts"

	payload := strings.NewReader("{\n  \"slug\": \"<string>\",\n  \"title\": \"<string>\",\n  \"excerpt\": \"<string>\",\n  \"body\": {},\n  \"cover_image_url\": \"<string>\",\n  \"author_name\": \"<string>\",\n  \"author_bio\": \"<string>\",\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"reading_time_minutes\": 123,\n  \"seo_meta_title\": \"<string>\",\n  \"seo_meta_description\": \"<string>\",\n  \"seo_og_image_url\": \"<string>\",\n  \"category_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.mercemur.com/api/v1/blog-posts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'slug' => '<string>',
    'title' => '<string>',
    'excerpt' => '<string>',
    'body' => [
        
    ],
    'cover_image_url' => '<string>',
    'author_name' => '<string>',
    'author_bio' => '<string>',
    'tags' => [
        '<string>'
    ],
    'reading_time_minutes' => 123,
    'seo_meta_title' => '<string>',
    'seo_meta_description' => '<string>',
    'seo_og_image_url' => '<string>',
    'category_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "data": {
    "author_bio": "<string>",
    "author_name": "<string>",
    "body": {
      "content": [
        {
          "content": [
            {
              "text": "<string>",
              "type": "<string>"
            }
          ],
          "type": "<string>"
        }
      ],
      "type": "<string>"
    },
    "category": {
      "id": "<string>",
      "name": "<string>",
      "slug": "<string>"
    },
    "cover_image_url": "<string>",
    "created_at": "<string>",
    "excerpt": "<string>",
    "id": "<string>",
    "published_at": "<string>",
    "reading_time_minutes": 123,
    "seo_meta_description": "<string>",
    "seo_meta_title": "<string>",
    "seo_og_image_url": "<string>",
    "slug": "<string>",
    "status": "<string>",
    "tags": [
      "<string>"
    ],
    "title": "<string>",
    "updated_at": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

Authorizations

Authorization

string

header

required

A secret API key. Publishable keys cannot reach this API. A key may carry an expiry, and an expired key is refused exactly like an unknown one, with a 401 that names no reason; check the key's expires_at in the dashboard rather than inferring it from a response. When a merchant rolls a key's secret they choose a grace window of up to 3 days, and for its duration BOTH the new secret and the one it replaced authenticate, so an integration moves over on its own deploy schedule instead of at the instant the button is pressed. Move before the window closes: after it, the old secret is refused. Nothing else about this contract moves with a roll. The key keeps its id and its scopes, so the only thing an integration updates is the credential itself.

Headers

Idempotency-Key

string

required

A unique key per logical write. Replaying a request with the same key returns the first response byte for byte instead of applying the write twice.

Body

application/json

EVERY post created here lands as a DRAFT, and status is not settable: publishing puts an article on the storefront and into the feed of every key holding read_blogs immediately, with no review step, so it is a second deliberate act at POST /blog-posts/{postId}/publish. A body carrying "status" is refused rather than ignored, because a 201 that quietly dropped it would leave the client believing an article is live that no reader can reach. The slug must be unique in the store; a taken slug is 409, which is what makes a create replayed outside the idempotency window safe. scheduled_publish_at is refused: the column exists and NOTHING reads it, so a value there would be a countdown that never fires.

slug

string

required

The storefront path segment. Unique per store.

title

string

required

excerpt

string | null

body

object | null

A ProseMirror JSON document, NOT html and not a string. It is stored byte for byte after a size check: there is no node allowlist, no mark allowlist and no URL scheme check inside it, so anything rendering it must apply its own.

cover_image_url

string | null

An absolute http(s) url under 2048 characters.

author_name

string | null

author_bio

string | null

Response

Created

data

object

Show child attributes

Overview

Endpoints

Create a blog post

Authorizations

Headers

Body

Response