API usage

Bytebard offers some endpoints for API access. Before you start using it, you would need an API key.

While creating an API key is optional, you will not be able to use API endpoints without it. Configure it in Settings page of your account.

Use the API key to send it in request header as x-api-key: your-key. In addition, you must send site identifier as URL parameter, like ?site=32a75776bb4ae45be4e8f88a. You can see your site identifier next to your API key in settings.

The API endpoints do not perform an automated reindex after updates. You must call reindex API specifically to drop indexes and cache.

Example of request

POST /api/blog?action=some-action
Host: bytebard.co
Content-Type: application/json
x-api-key: your-key
Body:
{
    "some": "data"
}

Endpoints

While it is recommended to use HTTP methods as described below, there is no strict validation on that.

GET /api/blog?action=list-posts

Returns list of all posts in the blog. You can use limit parameter and page parameter to paginate results. For example, ?action=list-posts&limits=10&page=2 will return 10 posts starting from 11th post.

---

GET /api/blog?action=list-files

Returns list of all images in the blog for a specified folder. You can use limit parameter to set maximum number of files returned. This API returns nextFile which can be used as URL parameter to paginate through results. For example, ?action=list-files&folder=images&limit=10&nextFile=images/my-blog-post.jpg will return 10 images starting from 11th image, which is my-blog-post.jpg.

Two folders are allowed to use: images and users. images folder is used for blog images, while users folder is used for user avatars.

---

POST /api/upload

Uploads an image to a specified folder. Send the image file in request body (not multipart). Preferable WebP format, however JPEG is also accepted. Please optimize and resize images before uploading as upload size is limited.

const fileContent = toBlob(inputElement.file.arrayBuffer());
await fetch("/api/upload?folder=images", {
    method: "POST", body: fileContent
});

---

GET /api/blog?action=get-post&id=64a7137vbb4ae55be4e8f88a

Returns a single post with id 64a7137vbb4ae55be4e8f88a. Alternatively, you can specify slug like /api/blog?action=get-post&slug=my-post.

---

POST /api/blog?action=create-post

Creates a post. Send the post object in request body. This API will respond with status of creation, ID of new post and URL. Some fields have special behavior:

Field	Description
slug	URL slug of the post. Must be unique.
author	Author number in site settings. Can be 0 (first) or any integer. If passed, author_name and author_picture will be used from list
autopost	You can disable autopost by passing false to this field

{
    "slug": "my-blog-post",
    "title": "My blog post",
    "content": "This is my blog post",
    "description": "Description of my blog post",
    "keywords": "blog, post",
    "image": "my-blog-post.jpg",
    "image_credit": "Pic taken from google.com",
    "author_name": "John Doe",
    "author_picture": "john-doe.jpg"
}

---

POST /api/blog?action=update-post

Updates a post. Send the post object in request body. Body should contain id of the post, like:

{
    "id": "64a7137vbb4ae55be4e8f88a",
    "slug": "my-new-post-title",
    "title": "My new post title",
    ...
}

---

POST /api/blog?action=import-posts

Imports posts in bulk. Only creates posts, no other functionality is enabled for this endpoint. Limited to 100 posts per request. Returns inserted as a number of posts inserted.

{
    "posts": [{
        "slug": "my-blog-post",
        ...
    }, {
        "slug": "my-second-blog-post",
        ...
    }]
}

---

DELETE /api/blog?action=remove-post&id=64a7137vbb4ae55be4e8f88a

Removes a post with id 64a7137vbb4ae55be4e8f88a.

---

DELETE /api/blog?action=remove-file&folder=images&name=my-blog-post.jpg

Removes an image by path images/my-blog-post.jpg.

---

POST /api/blog?action=reindex

Performs reindex for all posts in the blog. Revalidates cache, build sitemap and RSS feed. Body is optional, but can be used to specify additional parameters.

Field	Description
urls	Array of URLs to drop cache for. If passed, only these URLs will be impacted; otherwise, entire site cache will be dropped

{
    "urls": [
        "/blog/my-blog-post"
    ]
}