> For the complete documentation index, see [llms.txt](https://docs.byazma.ir/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.byazma.ir/byazma-api-v2.md).

# Byazma API v2

## General architecture

All requests are sent as `POST` in `JSON` format. The server also responds in `JSON`. There is only one endpoint and all parameters must be defined as json object in request body. Finally, for API verification, a checksum must be sent in the form of a header so that the server can respond to the request.

In the following, we will explain the details of these items.

### API Keys

for API verification you need two keys:

* `API_KEY` : your public api key.
* `API_SECRET` : use this private key to make a checksum.

### API endpoint

```url
https://byazma.ir/api/v2/API_KEY
```

### Body format

Every API action has a keyword, for example `post` for receiving content data. These keywords must be defined as a top-level json object in payload. you can also define multiple action in a single request, these actions will be in separate objects in respond body.

```json
{
    "post": {
        ...
    },
    "blog": {
        ...
    }
}
```

{% hint style="info" %}
**custom names :** you can make multiple action with same keyword ! just use `_` after a keyword and name your objects.

```json
{
    "post_foo": {
        ...
    },
    "post_bar": {
        ...
    }
}
```

{% endhint %}

### checksum

to create a checksum you must compute **HMAC-SHA256** (in hex format) of your request body using your `API_SECRET` key and send it in`byazma-checksum` header.

## Respond Body

respond body will contains following objects.

* `status` : general request status
* `body` (if status is *200*) : contains all actions respond object.
* `error` (if status is not *200*) : error string.

```json
{
    "status": 200,
    "body": {
        "post_foo": {
            ...
        }
    }
}
```

{% hint style="info" %}
if an error occurs in any action there will be an `error` object in that action respond object.
{% endhint %}