# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.byazma.ir/byazma-api-v2.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.