How to use our API

Architectural Overview

Integrate content automation into your system:

1. upload your data or/and download your text through our REST API
2. the AX NLG Cloud generates a text from data and your pre-configured instructions: every data object will be converted to one text
3. you can retrieve the generated text from the API or define a webhook to which we can send your text when it is ready.

Authentication

You authenticate with the API (documented in the API Reference).

TIP

Generate an id_token once and use it in all your processes until it almost expires. Then generate a new one. By generating a new id_token the old one automatically expires.

Uploading documents

Upload your documents to the appropriate collection. The upload process is briefly described in the Basic Chapter of the API Reference and documented in detail in the Description of documents in the API Reference.

Generating texts

To generate text you need to select one of three possible options:

1. you press the Generate button on the website
2. you activate automatic generation for the new data in your Collection
3. you use the API to start a generation for a specific document or Collection. This is useful, for example, to refresh your text(s) using the same data or to update them with modified data. This is documented in the API Reference

Receiving the generated texts

The generated text goes back to you. This can be done in three ways:

1. setting up a webhook
2. using the Direct API
3. checking the API response until the text is generated and then retrieve it (API Reference for text delivery)

TIP

We strongly recommend using a webhook unless you need real-time text production. In that case you should use our Direct API.

Using Webhooks for receiving content

You set up a webhook and store it in the collection's settings, so that finished texts are sent there. You find the documentation about this in the API Reference

What you need

1. your side of the data integration to get data in
2. a working ruleset
3. a collection in the cockpit

Setting up the Webhooks on the AX platform

• Go to Data Sources and into the corresponding collection
• Click on edit
• Enter your URL in the Webhook field and save your changes.

Now you will receive any updated content on this URL. Manually generate a text to verify your setup. Then set the checkbox "Autogenerate new documents" in the collection's settings to enable automatic generation and save the changes.

Setup the Webhook on your end

Only SSL Webhook targets are allowed. The request is cryptographically signed with a shared key, we recommend evaluating that signature. More information about the setup can be found in the chapter Webhook for receiving text of the API Reference.

TIP

For a more in-depth introduction of the questions around API and the NLG Platform see the Webinar: "API for data and texts"