OpenAPI and Postman
The OpenAPI 3.1 specification and the Postman collection for the AISAR API: where to get them, how to import them, where to put the token and how to read the x-aisar-* extensions.
Besides the reference pages, AISAR publishes the same API description in machine-readable form: an OpenAPI 3.1 specification and a Postman collection. Both files are built from the REST reference and the webhook event catalog on every documentation release, so they describe exactly the endpoints and events you see on the site. Import them into Postman or Insomnia, feed them to an SDK generator or plug them into your team's internal tooling.
Files and URLs
| File | URL |
|---|---|
| OpenAPI 3.1, English descriptions | https://docs.aisar.app/openapi.json |
| OpenAPI 3.1, Russian descriptions | https://docs.aisar.app/openapi.ru.json |
| Postman collection, English | https://docs.aisar.app/postman/aisar.postman_collection.json |
| Postman collection, Russian | https://docs.aisar.app/postman/aisar.ru.postman_collection.json |
| Postman environment | https://docs.aisar.app/postman/aisar.postman_environment.json |
The Russian and English versions differ only in text: paths, operationIds, tags and schemas are shared. The specification has a webhooks section with the body of every event and the delivery headers; the Postman collection has one folder per endpoint group.
Importing into Postman
- In Postman open File → Import, switch to the link tab and paste the collection URL, for example
https://docs.aisar.app/postman/aisar.postman_collection.json. - Import the environment
https://docs.aisar.app/postman/aisar.postman_environment.jsonthe same way and select it in the top-right corner. - In the environment, put the token into the
apiTokenvariable and save. The collection's requests already sendAuthorization: Bearer {{apiToken}}to{{baseUrl}}.
You can import the OpenAPI specification into Postman the same way, from the openapi.json or openapi.ru.json link, and Postman will build a collection from it. The ready-made AISAR collection is handier because it already carries response examples and variables.
Variables and the token
| Variable | Declared in | Value |
|---|---|---|
baseUrl | collection and environment | https://api.aisar.app; request paths start with /v1 |
apiToken | environment only, secret type | your full API token, in the {id}|{plaintext} format |
apiToken variable. The collection deliberately has no such variable: collections are often exported and sent to colleagues, and the token must not travel with them. Do not type the token into the Authorization tab of individual requests, and do not share an environment with apiToken filled in.Create a token in the cabinet under Settings → Systems → API or with POST /v1/api-tokens, see the API tokens group. It is shown only once. What a token grants and how to revoke it is covered in the Authentication guide.
x-aisar-* extensions
Whatever standard OpenAPI fields cannot express goes into extensions prefixed with x-aisar-. SDK generators skip them; they are worth reading when you are working out why a request returned 403.
| Extension | Meaning |
|---|---|
x-aisar-token-full: true | The operation needs a full-access token; a read-only token gets 403. |
x-aisar-feature | The plan feature the operation depends on, for example api. |
x-aisar-subscription-required: true | The company needs an active subscription. |
x-aisar-business-only: true | The operation exists for business companies only. |
x-aisar-permission | The permission checked for the token's user, for example conversation.view. Not every operation has it yet. |
x-aisar-signed-url: true | The URL is signed by the server and opens without a token; such links arrive inside other responses, you never build them yourself. |
x-aisar-source-commit | The documentation commit the file was built from. Compare it to tell whether the file changed since your last import. |
Schemas inferred from examples
A response schema marked x-aisar-schema-origin: example is built from the reference example, not from the server-side validation rules. Field types are correct, but the schema is deliberately permissive: no field is marked required, extra properties are allowed (additionalProperties: true), and a field that is null in the example can hold other values too. If you generate a client from such a schema, do not make it reject unknown fields: responses gain fields over time.
Compatibility
Within /v1, responses and webhook event bodies only grow: new fields are added, existing keys are never removed or renamed. A parser that ignores unknown fields therefore survives specification updates without changes. info.version stays 1.0 for as long as this rule holds.
Why there is no Try-it button
The documentation site has no console that sends requests straight from the page. An AISAR token grants access to the whole company workspace, and there is no reason to type it into a form on a site outside your own systems. Run requests from Postman or from your own code, where the token sits in an environment.
Webhooks in the specification
The webhooks section describes the body of every event and the X-AISAR-Event, X-AISAR-Delivery-Id and X-AISAR-Signature headers. How to verify a delivery signature and how retries work is covered in the Webhooks guide.