Mataroa API

We provide an API to allow programmatic updating of one’s blog.

API Base Endpoint

https://mataroa.blog/api/

API Key

your-api-key

Notes

• All API endpoints end with a trailing slash.
• Content type application/json is expected.
• There is no rate limiting.

Authentication

We authenticate requests using the Authorization HTTP header, using the Bearer scheme.

Authorization: Bearer your-api-key

API Endpoints

• Posts
  • Create post
  • Get single post
  • Update post
  • Delete post
  • List all posts
• Comments
  • List all comments
  • List pending comments
  • List comments for post
  • Get single comment
  • Approve comment
  • Delete comment
• Pages
  • Create page
  • Get single page
  • Update page
  • Delete page
  • List all pages

Posts

POST /api/posts/

Create new post.

• title: string [required]
• body: string [optional]
• published_at: string (ISO date eg. 2006-01-31) [optional]

{
    "title": "New blog",
    "body": "## Why?\n\nEveryone wants a blog, right?",
    "published_at": "2020-09-21"
}

{
    "ok": true,
    "slug": "new-blog",
    "url": "https://your-username.mataroa.blog/blog/new-blog/"
}

$ curl -X POST \
    -H 'Authorization: Bearer your-api-key' \
    -d '{"title": "New blog", "body": "## Why?\n\nEveryone needs a blog, right?"}' \
    https://mataroa.blog/api/posts/

GET /api/posts/<post-slug>/

Get single post.

• (no parameters)

{
    "ok": true,
    "slug": "new-blog",
    "title": "New blog",
    "body": "Welcome!"
    "published_at": "2020-09-21"
    "url": "https://your-username.mataroa.blog/blog/new-blog/"
}

$ curl -X GET \
    -H 'Authorization: Bearer your-api-key' \
    https://mataroa.blog/api/posts/new-blog/

PATCH /api/posts/<post-slug>/

Update existing post.

• title: string [optional]
• slug: string (slug; no spaces) [optional]
• body: string [optional]
• published_at: string (ISO date eg. 2006-01-31; or empty to unpublish) [optional]

{
    "title": "Updating my new blog",
    "slug": "updating-blog",
    "body": "Welcome back!"
    "published_at": "2020-09-21"
}

{
    "ok": true,
    "slug": "updating-blog",
    "url": "https://your-username.mataroa.blog/blog/updating-blog/"
}

$ curl -X PATCH \
    -H 'Authorization: Bearer your-api-key' \
    -d '{"title": "Updating my new blog", "body": "Rethinking and rewriting."}' \
    https://mataroa.blog/api/posts/introducing-my-new-blog/

DELETE /api/posts/<post-slug>/

Delete post.

• (no parameters)

{
    "ok": true
}

$ curl -X DELETE \
    -H 'Authorization: Bearer your-api-key' \
    https://mataroa.blog/api/posts/introducing-my-new-blog/

GET /api/posts/

List all posts.

• (no parameters)

{
    "ok": true,
    "post_list": [
        {
            "title": "On life",
            "slug": "on-life",
            "body": "What is life?\n\nAn illusion, a shadow, a story.",
            "published_at": null,
            "url": "https://your-username.mataroa.blog/blog/on-life/"
        },
        {
            "title": "New blog",
            "slug": "new-blog",
            "body": "With health!",
            "published_at": "2020-10-19",
            "url": "https://your-username.mataroa.blog/blog/new-blog/"
        }
    ]
}

$ curl -X GET \
    -H 'Authorization: Bearer your-api-key' \
    https://mataroa.blog/api/posts/

Comments

GET /api/comments/

List all comments on your posts.

• (no parameters)

{
    "ok": true,
    "comment_list": [
        {
            "id": 12,
            "post_slug": "on-life",
            "post_title": "On life",
            "post_url": "https://your-username.mataroa.blog/blog/on-life/",
            "url": "https://your-username.mataroa.blog/blog/on-life/#comment-12",
            "created_at": "2024-01-15T12:33:45Z",
            "name": "Visitor",
            "email": "visitor@example.com",
            "body": "An inspiring post!",
            "is_approved": true,
            "is_author": false
        }
    ]
}

$ curl -X GET \
    -H 'Authorization: Bearer your-api-key' \
    https://mataroa.blog/api/comments/

GET /api/comments/pending/

List comments awaiting approval.

• (no parameters)

{
    "ok": true,
    "comment_list": [
        {
            "id": 13,
            "post_slug": "on-life",
            "post_title": "On life",
            "post_url": "https://your-username.mataroa.blog/blog/on-life/",
            "url": "https://your-username.mataroa.blog/blog/on-life/#comment-13",
            "created_at": "2024-01-16T09:01:02Z",
            "name": "Reader",
            "email": null,
            "body": "Please approve this comment.",
            "is_approved": false,
            "is_author": false
        }
    ]
}

$ curl -X GET \
    -H 'Authorization: Bearer your-api-key' \
    https://mataroa.blog/api/comments/pending/

GET /api/posts/<post-slug>/comments/

List comments for a specific post.

• (no parameters)

{
    "ok": true,
    "comment_list": [
        {
            "id": 12,
            "post_slug": "on-life",
            "post_title": "On life",
            "post_url": "https://your-username.mataroa.blog/blog/on-life/",
            "url": "https://your-username.mataroa.blog/blog/on-life/#comment-12",
            "created_at": "2024-01-15T12:33:45Z",
            "name": "Visitor",
            "email": "visitor@example.com",
            "body": "An inspiring post!",
            "is_approved": true,
            "is_author": false
        }
    ]
}

$ curl -X GET \
    -H 'Authorization: Bearer your-api-key' \
    https://mataroa.blog/api/posts/on-life/comments/

GET /api/comments/<comment-id>/

Get details for a single comment.

• (no parameters)

{
    "ok": true,
    "comment": {
        "id": 13,
        "post_slug": "on-life",
        "post_title": "On life",
        "post_url": "https://your-username.mataroa.blog/blog/on-life/",
        "url": "https://your-username.mataroa.blog/blog/on-life/#comment-13",
        "created_at": "2024-01-16T09:01:02Z",
        "name": "Reader",
        "email": null,
        "body": "Please approve this comment.",
        "is_approved": false,
        "is_author": false
    }
}

$ curl -X GET \
    -H 'Authorization: Bearer your-api-key' \
    https://mataroa.blog/api/comments/13/

POST /api/comments/<comment-id>/approve/

Approve a pending comment.

• (no parameters)

{
    "ok": true,
    "comment": {
        "id": 13,
        "post_slug": "on-life",
        "post_title": "On life",
        "post_url": "https://your-username.mataroa.blog/blog/on-life/",
        "url": "https://your-username.mataroa.blog/blog/on-life/#comment-13",
        "created_at": "2024-01-16T09:01:02Z",
        "name": "Reader",
        "email": null,
        "body": "Please approve this comment.",
        "is_approved": true,
        "is_author": false
    }
}

$ curl -X POST \
    -H 'Authorization: Bearer your-api-key' \
    https://mataroa.blog/api/comments/13/approve/

DELETE /api/comments/<comment-id>/

Delete a comment.

• (no parameters)

{
    "ok": true
}

$ curl -X DELETE \
    -H 'Authorization: Bearer your-api-key' \
    https://mataroa.blog/api/comments/13/

Pages

POST /api/pages/

Create new page.

• title: string [required]
• slug: string (slug; no spaces) [required]
• body: string [optional]
• is_hidden: boolean (if true, page link will not appear on blog header) [optional]

{
    "title": "About",
    "slug": "about",
    "body": "## About\n\nThis is my about page.",
    "is_hidden": false
}

{
    "ok": true,
    "slug": "about",
    "url": "https://your-username.mataroa.blog/about/"
}

$ curl -X POST \
    -H 'Authorization: Bearer your-api-key' \
    -d '{"title": "About", "slug": "about", "body": "## About\n\nThis is my about page."}' \
    https://mataroa.blog/api/pages/

GET /api/pages/<page-slug>/

Get single page.

• (no parameters)

{
    "ok": true,
    "slug": "about",
    "title": "About",
    "body": "## About\n\nThis is my about page.",
    "is_hidden": false,
    "url": "https://your-username.mataroa.blog/about/"
}

$ curl -X GET \
    -H 'Authorization: Bearer your-api-key' \
    https://mataroa.blog/api/pages/about/

PATCH /api/pages/<page-slug>/

Update existing page.

• title: string [optional]
• slug: string (slug; no spaces) [optional]
• body: string [optional]
• is_hidden: boolean [optional]

{
    "title": "About Me",
    "slug": "about-me",
    "body": "## About Me\n\nUpdated about content.",
    "is_hidden": true
}

{
    "ok": true,
    "slug": "about-me",
    "url": "https://your-username.mataroa.blog/about-me/"
}

$ curl -X PATCH \
    -H 'Authorization: Bearer your-api-key' \
    -d '{"title": "About Me", "body": "Updated content."}' \
    https://mataroa.blog/api/pages/about/

DELETE /api/pages/<page-slug>/

Delete page.

• (no parameters)

{
    "ok": true
}

$ curl -X DELETE \
    -H 'Authorization: Bearer your-api-key' \
    https://mataroa.blog/api/pages/about/

GET /api/pages/

List all pages.

• (no parameters)

{
    "ok": true,
    "page_list": [
        {
            "title": "About",
            "slug": "about",
            "body": "## About\n\nThis is my about page.",
            "is_hidden": false,
            "url": "https://your-username.mataroa.blog/about/"
        },
        {
            "title": "Contact",
            "slug": "contact",
            "body": "Contact me at email@example.com",
            "is_hidden": true,
            "url": "https://your-username.mataroa.blog/contact/"
        }
    ]
}

$ curl -X GET \
    -H 'Authorization: Bearer your-api-key' \
    https://mataroa.blog/api/pages/