Key takeaways on the OpenAPI documentation
- The Raisetalk API documentation is now published in OpenAPI format, available at api.raisetalk.com/docs
- It is generated automatically from the API source code and updated on every deployment: no drift between the documentation and the actual behavior of the endpoints
- A client SDK can be generated in a single command in virtually any common language (PHP, Python, TypeScript, Java, Go, Ruby, C#, etc.) using the open-source
openapi-generator-clitool - The raw specification file is also available at api.raisetalk.com/openapi.yaml to feed your own tools (Postman, Insomnia, contract tests, CI/CD)
An API documentation in the market standard format
The Raisetalk API has, from day one, allowed our customers and partners to integrate the platform into their own tools: uploading conversations for analysis, retrieving transcripts and analyses, managing Quality Monitoring / Voice of the Customer scorecards, real-time callbacks, etc.
Until now, the documentation lived as a static page, exposed to the classic risk: documentation drifting away from the code. A renamed parameter, a new field, a deprecated endpoint, and the gap sets in.
We have migrated this documentation to an OpenAPI specification — the de facto standard for describing a REST API. More importantly: this specification is generated automatically from the API source code, and published on every deployment. The documentation you read reflects exactly the behavior of the endpoints in production.
What it changes for your integrations
Zero drift between documentation and reality
Every deployment regenerates the spec. If a field is added, a parameter renamed or an endpoint deprecated, the documentation reflects it immediately. No more manual consistency checks, no more tickets about "the doc doesn't match what the API returns".
An SDK in the language of your choice, in one command
From the openapi.yaml file, the open-source openapi-generator-cli tool (maintained by the OpenAPI Tools community) generates a working client in more than 50 target languages: PHP, Python, TypeScript, Java, Go, Ruby, C#, Kotlin, Swift, Rust, etc. Example for PHP:
docker run --rm \
-v "${PWD}:/local" \
openapitools/openapi-generator-cli generate \
-i https://api.raisetalk.com/openapi.yaml \
-g php \
-o /local/sdk/php
To switch to a different target language, simply change the value of the -g parameter. For example:
| Language | -g parameter |
|---|---|
| PHP | php |
| Python | python |
| TypeScript (axios) | typescript-axios |
| Java | java |
| Go | go |
| Ruby | ruby |
| C# | csharp |
The full list of available generators and configuration options is documented on the official site: openapi-generator.tech.
A spec usable by your existing tools
The openapi.yaml file can be imported directly into most API tools: Postman, Insomnia, Bruno, as well as contract testing tools (Pact, Dredd, Schemathesis), proxies and gateways (Kong, Tyk), or your CI/CD pipelines to automatically detect contract breakages between two versions.
How to explore the documentation
Head over to api.raisetalk.com/docs: each endpoint is presented with its parameters, sample responses, possible error codes and payload examples. The interface also lets you try endpoints directly from the browser, with your Bearer token.
The API Documentation page of our website now points directly to this spec, as well as to the openapi.yaml file if you want to grab it for your own tools.
Going further
- Explore the OpenAPI documentation: api.raisetalk.com/docs
- Grab the spec file: api.raisetalk.com/openapi.yaml
- Generate an SDK: openapi-generator.tech
- Discuss an integration use case: get in touch with us
Publishing an auto-generated OpenAPI specification is not just an engineering detail — it is a commitment to documentation reliability and platform openness. For your technical teams, it means what the documentation describes is exactly what is running in production, and a working SDK is only one command away.
