# Calendone Content API and MCP

Publish articles written in Calendone on any website: a custom CMS, a static site, or through an AI agent. Use the REST API to pull articles, webhooks to get notified, or MCP for agents. Base URL: `https://mapp.calendone.io/api/v1`. MCP endpoint: `https://mapp.calendone.io/api/mcp`. HTML version: https://mapp.calendone.io/developers/api

## Get started

Add your site, plan your content in Calendone, then automate publishing with the API or MCP.

- Create a free account at https://mapp.calendone.io/register and add your website.
- Calendone plans topics and writes the articles.
- In the app go to Team → API & MCP and create a token. Choose "Read and mark published" so you can report live URLs. The token is shown once.
- Send it as `Authorization: Bearer YOUR_TOKEN` on every request. One token works for every website in your team.

## Publishing flow

1. `GET /websites` to find your website id.
2. `GET /websites/{website_id}/articles?status=approved` to find articles ready to publish.
3. `GET /websites/{website_id}/articles/{article_id}` for the full article.
4. Publish it on your site, using `slug`, `meta_title`, `meta_description`, `content_html` (or `content_markdown`) and `featured_image`.
5. `PUT /websites/{website_id}/articles/{article_id}/publication` with the live `url`. The article becomes `published`, so it won't show up as approved again.

If an article is edited in Calendone after you published it, `publication.needs_update` becomes `true`. Fetch it again and update your post.

## Article statuses

- `in_review`: Finished, waiting for your approval in Calendone.
- `approved`: Approved and not yet published. This is what you publish.
- `published`: You reported it live with the publication endpoint.
- `rejected`: Rejected in Calendone. Don’t publish it.

## Endpoints

All responses are JSON. Successful responses wrap results in `data`.

### Check your token

`GET https://mapp.calendone.io/api/v1/me`

Returns the team and token you’re using. Call it first to confirm the token works.

Request:

cURL:

```bash
curl "https://mapp.calendone.io/api/v1/me" \
  -H "Authorization: Bearer $CALENDONE_TOKEN"
```

Node.js:

```js
const res = await fetch("https://mapp.calendone.io/api/v1/me", {
  headers: {
    Authorization: `Bearer ${process.env.CALENDONE_TOKEN}`,
  },
});
const data = await res.json();
```

PHP:

```php
$ch = curl_init('https://mapp.calendone.io/api/v1/me');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('CALENDONE_TOKEN'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
```

Python:

```python
import os
import requests

res = requests.get(
    "https://mapp.calendone.io/api/v1/me",
    headers={"Authorization": f"Bearer {os.environ['CALENDONE_TOKEN']}"},
)
data = res.json()
```

Go:

```go
package main

import (
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://mapp.calendone.io/api/v1/me", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("CALENDONE_TOKEN"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var data map[string]any
	json.NewDecoder(res.Body).Decode(&data)
}
```

Response:

```json
{
    "data": {
        "team": {
            "id": 3,
            "name": "Fitalert"
        },
        "token": {
            "name": "fitalert.com blog",
            "abilities": [
                "read",
                "write"
            ],
            "last_used_at": "2026-11-09T08:00:01+00:00"
        }
    }
}
```

### List websites

`GET https://mapp.calendone.io/api/v1/websites`

All websites in your team. You need a website id for every article call.

Request:

cURL:

```bash
curl "https://mapp.calendone.io/api/v1/websites" \
  -H "Authorization: Bearer $CALENDONE_TOKEN"
```

Node.js:

```js
const res = await fetch("https://mapp.calendone.io/api/v1/websites", {
  headers: {
    Authorization: `Bearer ${process.env.CALENDONE_TOKEN}`,
  },
});
const data = await res.json();
```

PHP:

```php
$ch = curl_init('https://mapp.calendone.io/api/v1/websites');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('CALENDONE_TOKEN'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
```

Python:

```python
import os
import requests

res = requests.get(
    "https://mapp.calendone.io/api/v1/websites",
    headers={"Authorization": f"Bearer {os.environ['CALENDONE_TOKEN']}"},
)
data = res.json()
```

Go:

```go
package main

import (
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://mapp.calendone.io/api/v1/websites", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("CALENDONE_TOKEN"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var data map[string]any
	json.NewDecoder(res.Body).Decode(&data)
}
```

Response:

```json
{
    "data": [
        {
            "id": 7,
            "url": "https://fitalert.com",
            "name": "fitalert.com",
            "created_at": "2026-11-01T10:00:00+00:00"
        }
    ]
}
```

### List articles

`GET https://mapp.calendone.io/api/v1/websites/{website_id}/articles`

Finished articles for one website, most recently updated first. The list leaves out the article body; fetch one article to get it.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `status` | query | string | all (default), approved, in_review, published or rejected. Use approved to find what to publish next. |
| `updated_since` | query | ISO 8601 | Only articles changed at or after this time. Good for polling. |
| `page` | query | integer | Page number, default 1. |
| `per_page` | query | integer | 1–100, default 20. |

Request:

cURL:

```bash
curl "https://mapp.calendone.io/api/v1/websites/7/articles?status=approved" \
  -H "Authorization: Bearer $CALENDONE_TOKEN"
```

Node.js:

```js
const res = await fetch("https://mapp.calendone.io/api/v1/websites/7/articles?status=approved", {
  headers: {
    Authorization: `Bearer ${process.env.CALENDONE_TOKEN}`,
  },
});
const data = await res.json();
```

PHP:

```php
$ch = curl_init('https://mapp.calendone.io/api/v1/websites/7/articles?status=approved');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('CALENDONE_TOKEN'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
```

Python:

```python
import os
import requests

res = requests.get(
    "https://mapp.calendone.io/api/v1/websites/7/articles?status=approved",
    headers={"Authorization": f"Bearer {os.environ['CALENDONE_TOKEN']}"},
)
data = res.json()
```

Go:

```go
package main

import (
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://mapp.calendone.io/api/v1/websites/7/articles?status=approved", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("CALENDONE_TOKEN"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var data map[string]any
	json.NewDecoder(res.Body).Decode(&data)
}
```

Response:

```json
{
    "data": [
        {
            "id": 412,
            "website_id": 7,
            "status": "approved",
            "title": "How to choose running shoes for flat feet",
            "slug": "how-to-choose-running-shoes-for-flat-feet",
            "excerpt": "What actually matters when you have flat feet, and how to test a shoe before you buy it.",
            "language": "en",
            "primary_keyword": "running shoes for flat feet",
            "planned_for": "2026-11-12",
            "revision": 3,
            "replaces_article_id": null,
            "approved_at": "2026-11-09T08:12:44+00:00",
            "created_at": "2026-11-08T21:03:10+00:00",
            "updated_at": "2026-11-09T08:12:44+00:00",
            "publication": null
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 20,
        "total": 1,
        "last_page": 1
    }
}
```

### Get an article

`GET https://mapp.calendone.io/api/v1/websites/{website_id}/articles/{article_id}`

One article with everything you need to publish it: HTML and Markdown body, meta title and description, slug and image URLs. Images are hosted by Calendone; download them if your site serves its own.

Request:

cURL:

```bash
curl "https://mapp.calendone.io/api/v1/websites/7/articles/412" \
  -H "Authorization: Bearer $CALENDONE_TOKEN"
```

Node.js:

```js
const res = await fetch("https://mapp.calendone.io/api/v1/websites/7/articles/412", {
  headers: {
    Authorization: `Bearer ${process.env.CALENDONE_TOKEN}`,
  },
});
const data = await res.json();
```

PHP:

```php
$ch = curl_init('https://mapp.calendone.io/api/v1/websites/7/articles/412');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('CALENDONE_TOKEN'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
```

Python:

```python
import os
import requests

res = requests.get(
    "https://mapp.calendone.io/api/v1/websites/7/articles/412",
    headers={"Authorization": f"Bearer {os.environ['CALENDONE_TOKEN']}"},
)
data = res.json()
```

Go:

```go
package main

import (
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://mapp.calendone.io/api/v1/websites/7/articles/412", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("CALENDONE_TOKEN"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var data map[string]any
	json.NewDecoder(res.Body).Decode(&data)
}
```

Response:

```json
{
    "data": {
        "id": 412,
        "website_id": 7,
        "status": "approved",
        "title": "How to choose running shoes for flat feet",
        "slug": "how-to-choose-running-shoes-for-flat-feet",
        "excerpt": "What actually matters when you have flat feet, and how to test a shoe before you buy it.",
        "language": "en",
        "primary_keyword": "running shoes for flat feet",
        "planned_for": "2026-11-12",
        "revision": 3,
        "replaces_article_id": null,
        "approved_at": "2026-11-09T08:12:44+00:00",
        "created_at": "2026-11-08T21:03:10+00:00",
        "updated_at": "2026-11-09T08:12:44+00:00",
        "publication": null,
        "meta_title": "How to choose running shoes for flat feet",
        "meta_description": "What actually matters when you have flat feet, and how to test a shoe before you buy it.",
        "featured_image": {
            "url": "https://calendone-io.s3.eu-north-1.amazonaws.com/website-content/7/412/cover.webp",
            "alt": "Runner tying a stability shoe",
            "width": 1536,
            "height": 1024
        },
        "images": [
            {
                "url": "https://calendone-io.s3.eu-north-1.amazonaws.com/website-content/7/412/cover.webp",
                "alt": "Runner tying a stability shoe",
                "width": 1536,
                "height": 1024
            }
        ],
        "content_markdown": "![Runner tying a stability shoe](https://calendone-io.s3.eu-north-1.amazonaws.com/website-content/7/412/cover.webp)\n\nFlat feet don’t automatically need…\n\n## What support actually means\n…",
        "content_html": "<p><img src=\"https://calendone-io.s3.eu-north-1.amazonaws.com/website-content/7/412/cover.webp\" alt=\"Runner tying a stability shoe\" /></p>\n<p>Flat feet don’t automatically need…</p>\n<h2>What support actually means</h2>\n<p>…</p>"
    }
}
```

### Mark as published

`PUT https://mapp.calendone.io/api/v1/websites/{website_id}/articles/{article_id}/publication`

Tell Calendone an approved article is live and where. Calendone then tracks it and moves it to published. Calling it again updates the record, so retries are safe. Needs a token with write access.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `url` | body | string, required | Full live URL of the article. |
| `remote_id` | body | string | Your own id for the post, up to 191 characters. |
| `published_at` | body | ISO 8601 | When it went live. Default: now. |

Request:

cURL:

```bash
curl -X PUT "https://mapp.calendone.io/api/v1/websites/7/articles/412/publication" \
  -H "Authorization: Bearer $CALENDONE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://fitalert.com/blog/running-shoes-flat-feet","remote_id":"post_8812"}'
```

Node.js:

```js
const res = await fetch("https://mapp.calendone.io/api/v1/websites/7/articles/412/publication", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.CALENDONE_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "url": "https://fitalert.com/blog/running-shoes-flat-feet",
    "remote_id": "post_8812"
  }),
});
const data = await res.json();
```

PHP:

```php
$ch = curl_init('https://mapp.calendone.io/api/v1/websites/7/articles/412/publication');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('CALENDONE_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'url' => 'https://fitalert.com/blog/running-shoes-flat-feet',
        'remote_id' => 'post_8812',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
```

Python:

```python
import os
import requests

res = requests.put(
    "https://mapp.calendone.io/api/v1/websites/7/articles/412/publication",
    headers={"Authorization": f"Bearer {os.environ['CALENDONE_TOKEN']}"},
    json={
        "url": "https://fitalert.com/blog/running-shoes-flat-feet",
        "remote_id": "post_8812"
    },
)
data = res.json()
```

Go:

```go
package main

import (
	"encoding/json"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{"url":"https://fitalert.com/blog/running-shoes-flat-feet","remote_id":"post_8812"}`)
	req, _ := http.NewRequest("PUT", "https://mapp.calendone.io/api/v1/websites/7/articles/412/publication", body)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer "+os.Getenv("CALENDONE_TOKEN"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var data map[string]any
	json.NewDecoder(res.Body).Decode(&data)
}
```

Response:

```json
{
    "data": {
        "id": 412,
        "status": "published",
        "…": "…",
        "publication": {
            "url": "https://fitalert.com/blog/running-shoes-flat-feet",
            "remote_id": "post_8812",
            "published_at": "2026-11-12T07:00:00+00:00",
            "needs_update": false
        }
    }
}
```

### List page updates

`GET https://mapp.calendone.io/api/v1/websites/{website_id}/page-updates`

Approved changes to existing pages (from “Improve this page” in Calendone): new title, meta description, sections, FAQ, text replacements. Each one targets an existing page by URL and remote_id. Update that page; never create a new one.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `status` | query | string | approved (default, waiting to be applied), applied or all. |
| `page` | query | integer | Page number, default 1. |
| `per_page` | query | integer | 1–100, default 20. |

Request:

cURL:

```bash
curl "https://mapp.calendone.io/api/v1/websites/7/page-updates" \
  -H "Authorization: Bearer $CALENDONE_TOKEN"
```

Node.js:

```js
const res = await fetch("https://mapp.calendone.io/api/v1/websites/7/page-updates", {
  headers: {
    Authorization: `Bearer ${process.env.CALENDONE_TOKEN}`,
  },
});
const data = await res.json();
```

PHP:

```php
$ch = curl_init('https://mapp.calendone.io/api/v1/websites/7/page-updates');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('CALENDONE_TOKEN'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
```

Python:

```python
import os
import requests

res = requests.get(
    "https://mapp.calendone.io/api/v1/websites/7/page-updates",
    headers={"Authorization": f"Bearer {os.environ['CALENDONE_TOKEN']}"},
)
data = res.json()
```

Go:

```go
package main

import (
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://mapp.calendone.io/api/v1/websites/7/page-updates", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("CALENDONE_TOKEN"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var data map[string]any
	json.NewDecoder(res.Body).Decode(&data)
}
```

Response:

```json
{
    "data": [
        {
            "id": 58,
            "website_id": 7,
            "status": "approved",
            "operation": "update",
            "target": {
                "url": "https://fitalert.com/blog/running-shoes-flat-feet",
                "remote_id": "post_8812",
                "page_type": "post"
            },
            "keyword": "running shoes for flat feet",
            "revision": 2,
            "base_fingerprint": "sha256:9b1c…",
            "approved_at": "2026-11-19T10:04:12+00:00",
            "applied_at": null,
            "applied_revision": null,
            "changes": [
                {
                    "id": "c1",
                    "type": "title",
                    "anchor": "",
                    "before": "Running shoes for flat feet",
                    "after": "Best running shoes for flat feet (2026): how to choose"
                },
                {
                    "id": "c2",
                    "type": "meta_description",
                    "anchor": "",
                    "before": "",
                    "after": "What flat feet really need from a running shoe, how to test support in the shop, and five models runners with flat feet like."
                },
                {
                    "id": "c3",
                    "type": "faq",
                    "anchor": "How to test a shoe",
                    "before": "",
                    "after": "## FAQ\n\n### Do flat feet need stability shoes?\nNot always…"
                },
                {
                    "id": "c4",
                    "type": "update_text",
                    "anchor": "",
                    "before": "Prices start at 2023 levels.",
                    "after": "Prices were checked in November 2026."
                }
            ]
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 20,
        "total": 1,
        "last_page": 1
    }
}
```

### Get a page update

`GET https://mapp.calendone.io/api/v1/websites/{website_id}/page-updates/{page_update_id}`

One approved page update. Find the page by target.remote_id or target.url (WordPress: url_to_postid(); Shopify: the handle in the URL), compare base_fingerprint if you store one, apply each change, then mark it applied.

Request:

cURL:

```bash
curl "https://mapp.calendone.io/api/v1/websites/7/page-updates/58" \
  -H "Authorization: Bearer $CALENDONE_TOKEN"
```

Node.js:

```js
const res = await fetch("https://mapp.calendone.io/api/v1/websites/7/page-updates/58", {
  headers: {
    Authorization: `Bearer ${process.env.CALENDONE_TOKEN}`,
  },
});
const data = await res.json();
```

PHP:

```php
$ch = curl_init('https://mapp.calendone.io/api/v1/websites/7/page-updates/58');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('CALENDONE_TOKEN'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
```

Python:

```python
import os
import requests

res = requests.get(
    "https://mapp.calendone.io/api/v1/websites/7/page-updates/58",
    headers={"Authorization": f"Bearer {os.environ['CALENDONE_TOKEN']}"},
)
data = res.json()
```

Go:

```go
package main

import (
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://mapp.calendone.io/api/v1/websites/7/page-updates/58", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("CALENDONE_TOKEN"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var data map[string]any
	json.NewDecoder(res.Body).Decode(&data)
}
```

Response:

```json
{
    "data": {
        "id": 58,
        "website_id": 7,
        "status": "approved",
        "operation": "update",
        "target": {
            "url": "https://fitalert.com/blog/running-shoes-flat-feet",
            "remote_id": "post_8812",
            "page_type": "post"
        },
        "keyword": "running shoes for flat feet",
        "revision": 2,
        "base_fingerprint": "sha256:9b1c…",
        "approved_at": "2026-11-19T10:04:12+00:00",
        "applied_at": null,
        "applied_revision": null,
        "changes": [
            {
                "id": "c1",
                "type": "title",
                "anchor": "",
                "before": "Running shoes for flat feet",
                "after": "Best running shoes for flat feet (2026): how to choose"
            },
            {
                "id": "c2",
                "type": "meta_description",
                "anchor": "",
                "before": "",
                "after": "What flat feet really need from a running shoe, how to test support in the shop, and five models runners with flat feet like."
            },
            {
                "id": "c3",
                "type": "faq",
                "anchor": "How to test a shoe",
                "before": "",
                "after": "## FAQ\n\n### Do flat feet need stability shoes?\nNot always…"
            },
            {
                "id": "c4",
                "type": "update_text",
                "anchor": "",
                "before": "Prices start at 2023 levels.",
                "after": "Prices were checked in November 2026."
            }
        ]
    }
}
```

### Mark page update applied

`PUT https://mapp.calendone.io/api/v1/websites/{website_id}/page-updates/{page_update_id}/applied`

Tell Calendone the approved revision is live on that page. Send the revision you applied; if a newer one was approved meanwhile you get 409 revision_mismatch. Needs write access.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `applied_revision` | body | integer | The revision you applied. |
| `url` | body | string | Live URL of the updated page. |
| `remote_id` | body | string | Your id for the page, up to 191 characters. |

Request:

cURL:

```bash
curl -X PUT "https://mapp.calendone.io/api/v1/websites/7/page-updates/58/applied" \
  -H "Authorization: Bearer $CALENDONE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"applied_revision":2,"url":"https://fitalert.com/blog/running-shoes-flat-feet","remote_id":"post_8812"}'
```

Node.js:

```js
const res = await fetch("https://mapp.calendone.io/api/v1/websites/7/page-updates/58/applied", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.CALENDONE_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "applied_revision": 2,
    "url": "https://fitalert.com/blog/running-shoes-flat-feet",
    "remote_id": "post_8812"
  }),
});
const data = await res.json();
```

PHP:

```php
$ch = curl_init('https://mapp.calendone.io/api/v1/websites/7/page-updates/58/applied');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('CALENDONE_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'applied_revision' => 2,
        'url' => 'https://fitalert.com/blog/running-shoes-flat-feet',
        'remote_id' => 'post_8812',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
```

Python:

```python
import os
import requests

res = requests.put(
    "https://mapp.calendone.io/api/v1/websites/7/page-updates/58/applied",
    headers={"Authorization": f"Bearer {os.environ['CALENDONE_TOKEN']}"},
    json={
        "applied_revision": 2,
        "url": "https://fitalert.com/blog/running-shoes-flat-feet",
        "remote_id": "post_8812"
    },
)
data = res.json()
```

Go:

```go
package main

import (
	"encoding/json"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{"applied_revision":2,"url":"https://fitalert.com/blog/running-shoes-flat-feet","remote_id":"post_8812"}`)
	req, _ := http.NewRequest("PUT", "https://mapp.calendone.io/api/v1/websites/7/page-updates/58/applied", body)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer "+os.Getenv("CALENDONE_TOKEN"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var data map[string]any
	json.NewDecoder(res.Body).Decode(&data)
}
```

Response:

```json
{
    "data": {
        "id": 58,
        "status": "applied",
        "…": "…",
        "applied_revision": 2
    }
}
```

### Remove publication

`DELETE https://mapp.calendone.io/api/v1/websites/{website_id}/articles/{article_id}/publication`

Use this when you took the article down. It goes back to approved. Needs write access.

Request:

cURL:

```bash
curl -X DELETE "https://mapp.calendone.io/api/v1/websites/7/articles/412/publication" \
  -H "Authorization: Bearer $CALENDONE_TOKEN"
```

Node.js:

```js
const res = await fetch("https://mapp.calendone.io/api/v1/websites/7/articles/412/publication", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.CALENDONE_TOKEN}`,
  },
});
const data = await res.json();
```

PHP:

```php
$ch = curl_init('https://mapp.calendone.io/api/v1/websites/7/articles/412/publication');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('CALENDONE_TOKEN'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
```

Python:

```python
import os
import requests

res = requests.delete(
    "https://mapp.calendone.io/api/v1/websites/7/articles/412/publication",
    headers={"Authorization": f"Bearer {os.environ['CALENDONE_TOKEN']}"},
)
data = res.json()
```

Go:

```go
package main

import (
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("DELETE", "https://mapp.calendone.io/api/v1/websites/7/articles/412/publication", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("CALENDONE_TOKEN"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var data map[string]any
	json.NewDecoder(res.Body).Decode(&data)
}
```

Response:

```json
{
    "data": {
        "id": 412,
        "status": "approved",
        "…": "…",
        "publication": null
    }
}
```

## MCP server

Endpoint: `https://mapp.calendone.io/api/mcp` (Streamable HTTP, JSON responses). Use the same bearer token.

| Tool | Arguments | What it does |
| --- | --- | --- |
| `list_websites` | — | Websites in your team. |
| `list_articles` | website_id, status?, updated_since?, page?, per_page? | Same as List articles. |
| `get_article` | website_id, article_id | Same as Get an article. |
| `mark_published` | website_id, article_id, url, remote_id?, published_at? | Same as Mark as published. Needs write access. |
| `list_page_updates` | website_id, status?, page?, per_page? | Same as List page updates. |
| `get_page_update` | website_id, page_update_id | Same as Get a page update. |
| `mark_page_update_applied` | website_id, page_update_id, applied_revision?, url?, remote_id? | Same as Mark page update applied. Needs write access. |

Claude Code:

```
claude mcp add --transport http calendone https://mapp.calendone.io/api/mcp \
  --header "Authorization: Bearer $CALENDONE_TOKEN"
```

Cursor, Windsurf and other JSON configs:

```
{
    "mcpServers": {
        "calendone": {
            "url": "https://mapp.calendone.io/api/mcp",
            "headers": {
                "Authorization": "Bearer YOUR_TOKEN"
            }
        }
    }
}
```

## Webhooks

Add a URL under Team → API & MCP → Webhooks and choose events. Calendone sends a signed `POST` with the full article.

Events:

- `article.ready_to_publish`: An approved article reached its planned publish date and isn’t published yet. Publish now moves its date to today and sends this event immediately.
- `article.approved`: An article was approved in Calendone.
- `article.ready_for_review`: Calendone finished writing an article and it needs approval.
- `article.updated`: A published article was edited in Calendone and your copy is out of date.
- `page.update_approved`: You approved changes to an existing page on your site (from “Improve this page”). Update that page — never create a new one — and reply with the applied revision.

`article.ready_to_publish` is checked every minute. It fires once per article on its planned date (UTC), or right away if an approved article's date has already passed. Every event fires once per article. The app's "Send test" button sends a `ping` event.

Headers:

- `Calendone-Event`: Event name, e.g. article.ready_to_publish.
- `Calendone-Delivery`: Unique delivery id. Retries reuse it, so you can ignore repeats.
- `Calendone-Timestamp`: Unix time when the request was signed.
- `Calendone-Signature`: v1= followed by HMAC-SHA256 of "{timestamp}.{raw body}" using your signing secret, hex encoded.

Body:

```json
{
    "id": "6f1c2a8e-4b1d-4d1e-9a51-0c7f3b2e9d10",
    "event": "article.ready_to_publish",
    "created_at": "2026-11-12T00:01:04+00:00",
    "team_id": 3,
    "website": {
        "id": 7,
        "url": "https://fitalert.com"
    },
    "data": {
        "article": {
            "id": 412,
            "website_id": 7,
            "status": "approved",
            "title": "How to choose running shoes for flat feet",
            "slug": "how-to-choose-running-shoes-for-flat-feet",
            "excerpt": "What actually matters when you have flat feet, and how to test a shoe before you buy it.",
            "language": "en",
            "primary_keyword": "running shoes for flat feet",
            "planned_for": "2026-11-12",
            "revision": 3,
            "replaces_article_id": null,
            "approved_at": "2026-11-09T08:12:44+00:00",
            "created_at": "2026-11-08T21:03:10+00:00",
            "updated_at": "2026-11-09T08:12:44+00:00",
            "publication": null,
            "meta_title": "How to choose running shoes for flat feet",
            "meta_description": "What actually matters when you have flat feet, and how to test a shoe before you buy it.",
            "featured_image": {
                "url": "https://calendone-io.s3.eu-north-1.amazonaws.com/website-content/7/412/cover.webp",
                "alt": "Runner tying a stability shoe",
                "width": 1536,
                "height": 1024
            },
            "images": [
                {
                    "url": "https://calendone-io.s3.eu-north-1.amazonaws.com/website-content/7/412/cover.webp",
                    "alt": "Runner tying a stability shoe",
                    "width": 1536,
                    "height": 1024
                }
            ],
            "content_markdown": "![Runner tying a stability shoe](https://calendone-io.s3.eu-north-1.amazonaws.com/website-content/7/412/cover.webp)\n\nFlat feet don’t automatically need…\n\n## What support actually means\n…",
            "content_html": "<p><img src=\"https://calendone-io.s3.eu-north-1.amazonaws.com/website-content/7/412/cover.webp\" alt=\"Runner tying a stability shoe\" /></p>\n<p>Flat feet don’t automatically need…</p>\n<h2>What support actually means</h2>\n<p>…</p>"
        }
    }
}
```

Verify the signature before trusting the request. Answer with any 2xx status. If you publish the article right away, reply with `{"url": "...", "remote_id": "..."}` and Calendone marks it published.

PHP (Laravel):

```
$body = $request->getContent();
$timestamp = $request->header('Calendone-Timestamp');
$expected = 'v1='.hash_hmac('sha256', $timestamp.'.'.$body, env('CALENDONE_WEBHOOK_SECRET'));

abort_unless(hash_equals($expected, (string) $request->header('Calendone-Signature')), 401);
abort_if(abs(time() - (int) $timestamp) > 300, 401); // reject old requests

$article = json_decode($body, true)['data']['article'];
// ...save the article, then optionally reply with where it went live:
return response()->json(['url' => "https://fitalert.com/blog/{$article['slug']}"]);
```

Node.js (Express):

```
import crypto from 'node:crypto';

app.post('/calendone/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.get('Calendone-Timestamp');
  const expected = 'v1=' + crypto.createHmac('sha256', process.env.CALENDONE_WEBHOOK_SECRET)
    .update(`${timestamp}.${req.body}`).digest('hex');
  const given = req.get('Calendone-Signature') || '';
  if (given.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const { article } = JSON.parse(req.body).data;
  // ...save the article
  res.json({ url: `https://fitalert.com/blog/${article.slug}` });
});
```

Only HTTPS URLs on the standard port are allowed. Requests time out after 10 seconds and redirects aren't followed. Calendone retries non-2xx answers after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, and pauses the webhook after 20 failures in a row.

### Page updates (`page.update_approved`)

Opt-in event for changes to an **existing** page that you approved in Calendone ("Improve this page"). Update the page in `target` — find it by `target.remote_id` or `target.url` (WordPress: `url_to_postid()`; Shopify: the handle in the URL). **Never create a new page.** If the page can't be found or changed since `base_fingerprint`, answer `404` or `409`: Calendone stops retrying and shows the error to the owner. When done, reply `{"url": "...", "remote_id": "...", "applied_revision": 2}`. Ignore a revision you already applied. The same updates are available from `GET /websites/{website_id}/page-updates`.

Change types:

- `title`: Replace the page’s SEO title (<title>). before = current value.
- `meta_description`: Replace the meta description.
- `h1`: Replace the main heading.
- `update_text`: Replace the exact passage in before with after. If before isn’t on the page any more, skip the change and report a conflict.
- `add_section`: Insert after (Markdown) right after the heading named in anchor, or at the end of the main content when anchor is "end".
- `faq`: Same as add_section: a Markdown FAQ block.
- `internal_link`: Same as add_section: a sentence with a link to another page on your site.
- `alt_text`: Set the alt text of the image whose src is in anchor.

Body:

```json
{
    "id": "0d6b51f2-6f0a-4f5e-8f2e-7f1f8a3c2b41",
    "event": "page.update_approved",
    "created_at": "2026-11-19T10:05:01+00:00",
    "team_id": 3,
    "website": {
        "id": 7,
        "url": "https://fitalert.com"
    },
    "data": {
        "page_update": {
            "id": 58,
            "website_id": 7,
            "status": "approved",
            "operation": "update",
            "target": {
                "url": "https://fitalert.com/blog/running-shoes-flat-feet",
                "remote_id": "post_8812",
                "page_type": "post"
            },
            "keyword": "running shoes for flat feet",
            "revision": 2,
            "base_fingerprint": "sha256:9b1c…",
            "approved_at": "2026-11-19T10:04:12+00:00",
            "applied_at": null,
            "applied_revision": null,
            "changes": [
                {
                    "id": "c1",
                    "type": "title",
                    "anchor": "",
                    "before": "Running shoes for flat feet",
                    "after": "Best running shoes for flat feet (2026): how to choose"
                },
                {
                    "id": "c2",
                    "type": "meta_description",
                    "anchor": "",
                    "before": "",
                    "after": "What flat feet really need from a running shoe, how to test support in the shop, and five models runners with flat feet like."
                },
                {
                    "id": "c3",
                    "type": "faq",
                    "anchor": "How to test a shoe",
                    "before": "",
                    "after": "## FAQ\n\n### Do flat feet need stability shoes?\nNot always…"
                },
                {
                    "id": "c4",
                    "type": "update_text",
                    "anchor": "",
                    "before": "Prices start at 2023 levels.",
                    "after": "Prices were checked in November 2026."
                }
            ]
        }
    }
}
```

PHP (WordPress):

```
// After verifying the signature (see above):
$update = json_decode($body, true)['data']['page_update'];
$postId = (int) ($update['target']['remote_id'] ?? 0) ?: url_to_postid($update['target']['url']);
if (! $postId) {
    return new WP_REST_Response(['error' => 'page_not_found'], 404); // never create a new post
}
if (get_post_meta($postId, '_calendone_revision', true) >= $update['revision']) {
    return ['url' => get_permalink($postId), 'remote_id' => (string) $postId, 'applied_revision' => $update['revision']]; // already applied
}
foreach ($update['changes'] as $change) {
    // title → post title / SEO plugin title, meta_description → SEO plugin field,
    // update_text → replace $change['before'] with $change['after'] in post_content,
    // add_section / faq / internal_link → insert converted Markdown after the heading in $change['anchor'] ("end" = append)
}
update_post_meta($postId, '_calendone_revision', $update['revision']);

return ['url' => get_permalink($postId), 'remote_id' => (string) $postId, 'applied_revision' => $update['revision']];
```

Node.js:

```
const { page_update: update } = JSON.parse(req.body).data;
const page = await db.pages.findOne(update.target.remote_id ? { id: update.target.remote_id } : { url: update.target.url });
if (!page) return res.status(404).json({ error: 'page_not_found' }); // never create a new page
if (page.calendoneRevision >= update.revision) {
  return res.json({ url: page.url, remote_id: page.id, applied_revision: update.revision }); // already applied
}
if (page.calendoneFingerprint && page.calendoneFingerprint !== update.base_fingerprint) {
  // optional: your page changed since Calendone read it — apply carefully or answer 409
}
for (const change of update.changes) applyChange(page, change); // see the change types table
page.calendoneRevision = update.revision;
await db.pages.save(page);
res.json({ url: page.url, remote_id: page.id, applied_revision: update.revision });
```


## Errors

Errors return `{"error": {"code": "...", "message": "..."}}` with a matching HTTP status.

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | — | Missing, wrong or revoked token. Body: {"message": "Unauthenticated."} |
| 403 | forbidden | The token is read-only and the endpoint needs write access. |
| 404 | website_not_found / article_not_found / page_update_not_found | The id doesn’t exist or belongs to another team. |
| 409 | not_approved | Only approved articles can be marked published, and only approved page updates can be marked applied. |
| 409 | revision_mismatch | The applied_revision you sent isn’t the approved revision. Fetch the page update again and apply the latest one. |
| 422 | invalid_status / invalid_url / invalid_date | A parameter has the wrong format. The message says which. |
| 429 | — | More than 60 requests a minute. Wait for the Retry-After header and try again. |

## Limits and versioning

- 60 requests per minute.
- `v1` only gets additive changes: new fields or endpoints. Ignore fields you don't know.
