NAV
shell python php

Introduction to the myAX API

Basics

The myAX web application (my.ax-semantics.com) is a self-service portal integrated in the AX NLG Cloud. It enables your access to functionality such as data transfer, text generation and integration of automated content generation into your website.

All functionality of the platform is accessible via our API at api.ax-semantics.com to ensure an easy integration into other platforms and systems.

Terms and Definitions

We recently added new functionality for which we use new terms: * Projects bundle Trainings and Collections. * Collections help organize related or similar Documents.

There is a vague resemblence to the old Content Projects; however they are very different on the inside.

These in turn seem to resemble Objects or Things, but provide a flexible and powerful storage solution.

Authentication

The API requires the input of an “Authorization header”.

To retrieve the value of this token you have to log in using the web application; then you will find it in your profile. At the moment it is not possible to login using an API call. (We are working on it though.)

The header should look like this:

Authorization: Token aa5d2e36668c11e5964038bc572ec103

You have to exchange aa5d2e36668c11e5964038bc572ec103 for your own API token.

Objects

Your data input is saved as objects, regardless of their old format. These Objects are always attached to a Content Project.

Create new objects

import axsemantics
axsemantics.login('', '')

data = {'key':'value'}
cp = axsemantics.ContentProject.all().get(id=1)
thing = axsemantics.Thing(uid=1, name='demo', pure_data=data, cp_id=cp['id']).create()
$ curl --request POST \
  --url https://api.ax-semantics.com/v1/content-project/1/thing/ \
  --header 'Authorization: Token aa5d2e36668c11e5964038bc572ec103' \
  --header 'Content-Type: application/json' \
  --data '{"uid":1, "name":"demo", "content_project":1, "pure_data": {"key":"value"}}'

To create a new object, POST its data into an existing content project. Please add the ID of the existing content project into your POST URL as well as your request data.

Mandatory information for the creation of an object are:

Depending on the type of content the object may need other mandatory information.

Notes on pure_data

Depending on the shell you’re using, you may need to escape quotation marks in the JSON-String for the pure_data field. In the example call on a cURL shell the quotation marks are escaped with a backslash prefix.

Additionally, please take care of the data types in your json structure. Non-number formats like "somekey":010 will result in errors, and may need to be put into double ticks ("somekey":"010") or converted to a number ('"somekey":10). This will result in errors messages like {"detail":"JSON parse error - Expecting ',' delimiter: line 1 column 9 (char 8)"}.

Endpoint

POST /v1/content-project/{CP_ID}/thing/

In the example you have to exchange {CP_ID} with a valid content project id.

Update an existing Object

import axsemantics
axsemantics.login('', '')

cp = axsemantics.ContentProject.all().get(id=1)
thing = cp.things.all().get(123)
thing['pure_data'] = {'different key':'different value'}
thing.save()
$ curl --request PUT \
  --url https://api.ax-semantics.com/v1/content-project/1/thing/123/ \
  --header 'Authorization: Token aa5d2e36668c11e5964038bc572ec103' \
  --header 'Content-Type: application/json' \
  --data '{"uid":1, "name":"demo", "content_project":1, "pure_data": {"diffent key":"different value"}}'

Endpoint

PUT /v1/content-project/{CP_ID}/thing/{OBJ_ID}/

In the example you have to exchange {CP_ID} with a valid Content Project ID and {OBJ_ID} with a valid Object ID. Keep in mind that this is not the UID but the object ID assigned by the platform!.

Delete an Object

import axsemantics
axsemantics.login('', '')

cp = axsemantics.ContentProject.all().get(id=1).get(123)
thing = cp.things.all().get(id=2)
thing.delete()
$ curl --request DELETE \
  --url https://api.ax-semantics.com/v1/content-project/1/thing/123/ \
  --header 'Authorization: Token 3c019382668c11e5bb5feb0c65696656'

Endpoint

DELETE /v1/content-project/{CP_ID}/thing/{OBJ_ID}/

In the example you have to exchange {CP_ID} with a valid Content Project ID and {OBJ_ID} with a valid Object ID. Keep in mind that this is not the UID but the object ID assigned by the platform!.

Get more information about Object properties

Sometimes you might require more details on object properties (like units in a field like width). This endpoint will return a description of properties including a help text, their requirement level and the expected type.

$ curl --request OPTIONS \
  --url https://api.ax-semantics.com/v1/content-project/1/thing/ \
  --header 'Authorization: Token 3c019382668c11e5bb5feb0c65696656'

The response will be structured similar to this:

{ "name": "Leaf Detail List",
  "renders":["application/json","text/html"],
  "parses":["application/json","application/x-www-form-urlencoded","multipart/form-data"],
  "actions":{"POST":{
    "uid":{
        "type":"string",
        "required":true,
        "read_only":false,
        "help_text":"A unique ID. Used for later references to this object.",
        "max_length":256,
        "requirement_level":3
    },
    "description":{
        "type":"string",
        "required":false,
        "read_only":false,
        "help_text":"A short description of the item.",
        "requirement_level":0
    }
  }}
}

Endpoint

OPTIONS /v1/content-project/{CP_ID}/thing/

In the example you have to exchange {CP_ID} with a valid Content Project ID.

Generating Content

The content generation through the API is accessible when all mandatory information is present in the object.

Generate content for a single Object

import axsemantics
axsemantics.login('', '')

cp = axsemantics.ContentProject.all().get(id=1)
thing = cp.things().get(id=334)
response = thing.generate_content(force=False)
$ curl --request POST \
  --url "https://api.ax-semantics.com/v1/content-project/1/thing/123/generate_content/?force=true" \
  --header 'Authorization: Token aa5d2e36668c11e5964038bc572ec103'

The response contains informations regarding the content request, such as:

{ "status": "CALLED",
  "number": 1,
  "content_request": {
    "id": 123,
    "content_project": 1,
    "generated_text_in_html": null,
    "thing_type": "demo",
    "state": "Started",
    "created": "2015-10-02T11:56:45.994940Z",
    "modified": "2015-10-02T11:56:46.068082Z",
    "...":"..." }}

Endpoint

POST /v1/content-project/{CP_ID}/thing/{OBJ_ID}/generate_content/{force}

In the example you have to exchange {CP_ID} with a valid Content Project ID and {OBJ_ID} with a valid Object ID. Keep in mind that this is not the UID but the object ID assigned by the platform!.

{force} is a query parameter which is used to define whether the Content Request should discard and regenerate existing content. This parameter is optional, the default is force=false.

Generate content for a whole Content Project

import axsemantics
axsemantics.login('', '')

cp = axsemantics.ContentProject.all().get(id=1)
response = cp.generate_content(force=False)
$ curl --request POST \
  --url "https://api.ax-semantics.com/v1/content-project/2123/generate_content/?force=true" \
  --header "Authorization: Token aa5d2e36668c11e5964038bc572ec103"

The API responds by returning a JSON response, such as:

{"status":"CALLED","number":3}

Endpoint

POST /v1/content_project/{CP_ID}/generate_content/{force}

In the example you have to exchange {CP_ID} with a valid Content Project ID.

{force} is a query parameter which is used to define whether the content request should discard and regenerate existing content. This parameter is optional, the default is force=false.

Request status report for a content request

import axsemantics
axsemantics.login('', '')

cp = axsemantics.ContentProject.all().get(id=1)
thing = cp.things().get(id=334)
print(thing['status'])
$ curl --request GET \
    --header "Authorization: Token aa5d2e36668c11e5964038bc572ec103" \
    --url "https://api.ax-semantics.com/v1/content-project/1/thing/123/"

The API response includes a status field:

{ "id": 123,
  "uid": "demo",
  "status": "not requested",
  "generated_text": null,
  "content_project": 1,
  "...":"..." }

Endpoint

GET /v1/content-project/{CP_ID}/thing/{OBJ_ID}/

In the example you have to exchange {CP_ID} with a valid Content Project ID and {OBJ_ID} with a valid Object ID. Keep in mind that this is not the UID but the ID assigned by the platform!.

Export generated content for a single Object

import axsemantics
axsemantics.login('', '')

cp = axsemantics.ContentProject.all().get(id=1)
thing = cp.things().get(id=334)
print(thing['generated_text'])
print(thing['text_as_html'])
$ curl --request GET \
  --url https://api.ax-semantics.com/v1/content-project/1/thing/123/ \
  --header 'Authorization: Token aa5d2e36668c11e5964038bc572ec103'

The API returns information regarding the Object, including generated text if any exists:

{ "id": 456,
  "content_project": 1,
  "state": "Success",
  "generated_text_in_html": "<h1>Überschrift</h1>\n<p>Absatz</p>",
  "generated_text": "# Überschrift\nAbsatz",
  "...": "..." }

The generated content is available in its original format or in HTML-format. Usually the original format is Markdown.

Endpoint

GET /v1/content-project/{CP_ID}/thing/{OBJ_ID}/content_request/

In the example you have to exchange {CP_ID} with a valid Content Project ID and {OBJ_ID} with a valid Object ID. Keep in mind that this is not the UID but the ID assigned by the platform!.

Push for new content via web hooks

On request, we can activate the push feature for new content: When a new text is generated MyAX will send a HTTP POST request to the web hook URL.

It has a signature header to verify the integrity/authenticity and some data about the object and the text in the post data body.

Signature header

HTTP_X_MYAX_SIGNATURE: "sha1=df589122eac0f6a7bd8795436e692e3675cadc3b"

The checksum is calculated as hmac sha1 hexdigest. The key is your API token. The message is the post data.

Please note that depending on the framework/language that is in use, the siganture header can also be X-MYAX-SIGNATURE.

POST data

{
  "id": 9001,
  "name": "<The name of the object>",
  "text": "<The new text (raw)>",
  "text_as_html": "<The new text (as html from markdown)>",
  "uid": "<The uid you put in the object>",
  "content_project_name": "<Name of the content project>",
  "content_project_id": 1337,
  "text_modified": "2015-10-21T23:29:00.000000+00:00",
  "language": "en-US"
}

You will receive POST data looking like the JSON on the right.

Verification

See the examples on the right on how to verify the hmac.

For more information about hmacs validation with your programming language and framework of choice. Eg. for PHP documentation is available in the manual.

import hmac
import hashlib

def signature_valid(request, raw_data):
    try:
        secret = AX_API_TOKEN  # your knowledge!!
        signature_header = request.META['HTTP_X_MYAX_SIGNATURE'].replace('sha1=', '')
        signature_content = hmac.new(
            key=secret.encode('utf-8'),
            msg=raw_data,   # content of request
            digestmod=hashlib.sha1
        ).hexdigest()
    except AttributeError:
        pass
    except KeyError:
        pass
    except Exception:
        raise
    else:
        return bool(signature_header == signature_content)
    return False
/* Works with PHP 5 >= 5.1.2 and PHP 7 */
$aHttpHead = isset($_SERVER) ? $_SERVER : [];
$sHttpBody = file_get_contents('php://input');
$sApiKey = '...';
$sSignature = NULL;

if(isset($aHttpHead['HTTP_X_MYAX_SIGNATURE'])) {
    $sSignature = $aHttpHead['HTTP_X_MYAX_SIGNATURE'];
} elseif(isset($aHttpHead['http_x_myax_signature'])) {
    $sSignature = $aHttpHead['http_x_myax_signature'];
}

if($sSignature !== NULL) {
    $sChecksum = hash_hmac('sha1', $sHttpBody, $sApiKey, FALSE);
    if($sSignature == 'sha1='.$sChecksum || $sSignature == $sChecksum) {
        if(($aData = json_decode($sHttpBody, TRUE))) {
            //...
        }
    }
}

Export generated content for an entire Content Project

If you want to have the content available as one big download file, you can use the export functionality.

$ curl --request GET \
  --header 'Authorization: Token aa5d2e36668c11e5964038bc572ec103' \
  --url 'https://api.ax-semantics.com/v1/download-exports/?page=1&page_size=10'
  # yields a list of available downloads
  # find your required download and use its 'download_url' attribute
$ curl --request GET \
  --output export.xlsx \
  --url https://api.ax-semantics.com/v1/content_project_export_download/7f9cc6a2-6b55-11e5-bb84-5e2c2d9baef2

Endpoint

GET /v1/download-exports/

Autoprocessing

Autoprocessing for bulkuploads

$ curl --request POST \
  --header 'Authorization: Token aa5d2e36668c11e5964038bc572ec103' \
  --url https://api.ax-semantics.com/v1/bulkupload/ \
  --form 'tag=demo' \
  --form 'content_project=1' \
  --form 'data_file=@/home/user/Desktop/demofile.xlsx;filename=demofile.xlsx' \
  --form 'autoprocess=true'

By using Autoprocessing your content will be automatically generated and prepared for download.

The Autoprocessing function is triggered if you use the checkbox during a bulkupload. Your data will then be imported into a content project. Afterwards the content will be generated for all imported objects and made available as a file in your account. You are informed by email when your content is available.

Autoprocessing for new Objects

On request, your Content Project can be configured for “automatic processing”. For any new objects, a text generation request is then triggered automatically once, saving you the call to request the content.

Endpoint

POST /v1/bulkupload/

Content Projects

Content Projects are collections of objects, coupled with an engine configuration and an engine training. The data that is used to generate content is deposited into objects. The Framework and interpretational ruleset for the text creation is represented by the engine training. Lastly meta information like language and data type is provided by the chosen engine configuration.

List Content Projects

import axsemantics
axsemantics.login('', '')

cp_list = axsemantics.ContentProjects.all()
$ curl --request GET \
  --url https://api.ax-semantics.com/v1/content-project/ \
  --header 'Authorization: Token aa5d2e36668c11e5964038bc572ec103'

The API returns a JSON string, such as:

{ "count": 1,
  "next": null,
  "previous": null,
  "results": [ { "id": 1,
      "name": "Test",
      "keyword_deviation": "33.00",
      "keyword_density": "3.00",
      "max_length": 0,
      "axcompany": 20,
      "axcompany_name": "Ihre Firma",
      "engine_configuration": 1,
      "count_things": 1,
      "count_generated_texts": 0,
      "min_length": null,
      "count_generated_texts_errors": 0 } ] }

Endpoint

GET /v1/content-project/

List a single Content Project

import axsemantics
axsemantics.login('', '')

cp = axsemantics.ContentProject.all().get(id=1)
$ curl --request GET \
  --url https://api.ax-semantics.com/v1/content-project/1/ \
  --header 'Authorization: Token aa5d2e36668c11e5964038bc572ec103'

The API returns a JSON response, such as:

{ "id": 1,
  "name": "Test",
  "keyword_deviation": "33.00",
  "keyword_density": "3.00",
  "max_length": 0,
  "axcompany": 20,
  "axcompany_name": "Ihre Firma",
  "engine_configuration": 1,
  "count_things": 1,
  "count_generated_texts": 0,
  "min_length": null,
  "count_generated_texts_errors": 0 }

Endpoint

GET /v1/content-project/{CP_ID}/

In the example you have to exchange {CP_ID} with a valid Content Project ID.

Access generated content

To get your generated content, all things with their content can be listed as follows:

GET /v1/content-project/{CP_ID}/thing/

{
    "count": 164,
    "next": "https://api.ax-semantics.com/v1/content-project/3992/thing/?page=2",
    "previous": null,
    "results": [
        {
            "id": 1637938,
            "generated_text": "Mit einem leichten Plus von 0,36 % schloss die Pearson plc-Aktie heute bei 700,5 GBP. Im Vergleich zum Vortag stieg die Aktie um 0,94 % (6,5 GBP). Im Vergleich zum Vorjahr fiel sie um -38,51 % (-438,72 GBP).",
            "status": "success",
            "error_msg": "",
            "most_important_missing_requirement_level": 0,
            "requirement_level_status_text": "Data quality for this object is satisfactory.",
            "is_content_generation_available": true,
            "created": "2016-01-14T06:24:23.221964Z",
            "modified": "2016-01-14T06:50:06.152555Z",
            "uuid": "35963a99-8849-4f0d-87d6-1e8e6ce70b73",
            "uid": "7207909",
            "alternate_name": null,
            "description": null,
            "name": "Pearson plc [LSE] (2016-01-13)",
            "url": null,
            "tag": null,
            "_text": "Mit einem leichten Plus von 0,36 % schloss die Pearson plc-Aktie heute bei 700,5 GBP. Im Vergleich zum Vortag stieg die Aktie um 0,94 % (6,5 GBP). Im Vergleich zum Vorjahr fiel sie um -38,51 % (-438,72 GBP).",
            "text_as_html": "<p>Mit einem leichten Plus von 0,36 % schloss die Pearson plc-Aktie heute bei 700,5 GBP. Im Vergleich zum Vortag stieg die Aktie um 0,94 % (6,5 GBP). Im Vergleich zum Vorjahr fiel sie um -38,51 % (-438,72 GBP).</p>",
            "text_modified": "2016-01-14T06:50:06.152029Z",
            "text_state": "SUCCESS",
            "text_error_msg": null,
            "text_duration": 1542838,
            "text_metrics": "{\n  \"text_length_in_words\": 57,\n  \"text_length_in_chars\": 207\n}",
            "stock_code": "PSON.L",
            "stock_name": "Pearson plc",
            "stock_exchange": "LSE",
            "stock_type": "stock",
            "category_name": "Publishing - Newspapers",
            "date": "2016-01-13",
            "content_project": 3992
        },

Pull Content from API

Create new Content Project

import axsemantics
axsemantics.login('', '')

cp = axsemantics.ContentProject(name='new cp', engine_configuration=123)
cp.create()
$ curl --request POST \
  --url https://api.ax-semantics.com/v1/content-project/ \
  --header 'Authorization: Token aa5d2e36668c11e5964038bc572ec103' \
  --header 'Content-type: application/json' \
  --data '{"name":"neues cp","engine_configuration":123}'

The API returns a JSON response, such as:

{ "id": 42,
  "name": "neues cp",
  "keyword_deviation": "33.00",
  "keyword_density": "3.00",
  "max_length": null,
  "axcompany": 20,
  "axcompany_name": "Ihre Firma",
  "engine_configuration": 123,
  "count_things": 0,
  "count_generated_texts": null,
  "min_length": null,
  "count_generated_texts_errors": null }

Endpoint

POST /v1/content-project/

Mandatory information to create a new content project:

Optional information for your content project:

Filter and search for Content Projects

Delete Content Projects

import axsemantics
axsemantics.login('', '')

axsemantics.ContentProject.all().get(id=1).delete()
$ curl --request DELETE \
  --url https://api.ax-semantics.com/v1/content-project/1/ \
  --header 'Authorization: Token 3c019382668c11e5bb5feb0c65696656'

The API responds with a '204 NO CONTENT’ status.

Endpoint

DELETE /v1/content-project/{CP_ID}/

In the example you have to exchange {CP_ID} with a valid Content Project ID.

Empty a Content Project

$ curl --request POST \
  --url https://api.ax-semantics.com/v1/content-project/1/empty/ \
  --header 'Authorization: Token 3c019382668c11e5bb5feb0c65696656'

The API returns status code '202 ACCEPTED’ and a JSON messges such as:

{"message": "Started emptying ContentProject (1/neues cp)"}

Endpoint

POST /v1/content-project/{CP_ID}/empty/

In the example you have to exchange {CP_ID} with a valid Content Project ID.

Clone a Content Project

Creates a new Content Project for you. It will copy Objects from the original to the new Content Project. These Objects will be seperate entities with their own IDs but otherwise same properties.

Cloning is done asynchrounosly: the new Content Project will show up in your list after a while (depending on its size).

$ curl --request POST \
  --url https://api.ax-semantics.com/v1/content-project/1/clone/ \
  --header 'Authorization: Token 3c019382668c11e5bb5feb0c65696656'

The API returns '202 ACCEPTED’ if the given Content Project could be cloned; otherwise it returns a '404 NOT ALLOWED’.

Endpoint

POST /v1/content-project/{CP_ID}/clone/

In the example you have to exchange {CP_ID} with a valid Content Project ID.

Actions affecting multiple Content Projects

Some actions are executable for objects regardless of their affiliation to a content project.

Display Objects from different Content Projects

$ curl --request GET \
  --header 'Authorization: Token aa5d2e36668c11e5964038bc572ec103' \
  --url 'https://api.ax-semantics.com/v1/allthings/?ordering=-modified&page=1&page_size=30&tag=KW+23'
  # die Objekte unter dem Schlüsselwort 'things' auswerten
  # beispielhafter Aufruf für nur ein Objekt
  curl --request POST \
  --header 'Authorization: Token aa5d2e36668c11e5964038bc572ec103' \
  --url 'https://api.ax-semantics.com/v1/content_project/1/thing/123/generate_content/?force=true

The API responds with a JSON string, such as:

{ "next_link": "https://api.ax-semantics.com/v1/allthings/?page=2",
  "count": 2,
  "ordering": "-modified",
  "next": 2,
  "page": 1,
  "results": [ {
      "id": 9001,
      "uid": "123",
      "uuid": "ea9cebc6-6c40-11e5-bd8e-3d122d9baef2",
      "name": "demoteil",
      "status": "success",
      "thing_type": "demo",
      "content_project_pk": 1,
      "...": "..." } ] }

Please keep in mind that the field id doesn’t necessarily have a one-to-one relation in this view. To establish this relation combine the fields id and content_project_pk or use the field uuid for reference.

Endpoint

GET /v1/allthings/

Automatic Story Exports

We create exports of your ContentProjects’ generated texts at intervals. These are only created when necessary, for example if content has been changed since the last export was generated.

You can only retrieve information and data but cannot trigger a story export. Read: you can only use GET.

List all automatic exports

$ curl --request GET \
  --header 'Authorization: Token aa5d2e36668c11e5964038bc572ec103' \
  --url 'https://api.ax-semantics.com/v1/bulkdownloads/'

Endpoint

GET /v1/bulkdownloads/

List automatic export for a specific ContentProject

$ curl --request GET \
  --header 'Authorization: Token aa5d2e36668c11e5964038bc572ec103' \
  --url 'https://api.ax-semantics.com/v1/bulkdownloads/by-content-project/23/'

Endpoint

GET /v1/bulkdownloads/by-content-project/{CP_ID}/

Replace {CP_ID} with the ID of one of your ContentProjects.

List automatic exports for specific Training ID

$ curl --request GET \
  --header 'Authorization: Token aa5d2e36668c11e5964038bc572ec103' \
  --url 'https://api.ax-semantics.com/v1/bulkdownloads/by-training-id/4433/'

Endpoint

GET /v1/bulkdownloads/by-training-id/{TRAINING_ID}/

Replace {TRAINING_ID} with the training ID which you can retreive from our Training Wizard.

List automatic exports matching search terms

$ curl --request GET \
  --header 'Authorization: Token aa5d2e36668c11e5964038bc572ec103' \
  --url 'https://api.ax-semantics.com/v1/bulkdownloads/search/your%20terms%20here'

Endpoint

GET /v1/bulkdownloads/search/{search terms}

You can use spaces in your search terms, but they must be encoded as %20; do not use +.

Show details of a specific automatic export

$ curl --request GET \
  --header 'Authorization: Token aa5d2e36668c11e5964038bc572ec103' \
  --url 'https://api.ax-semantics.com/v1/bulkdownloads/25e05d20-106b-11e6-b78f-a71d52357c51/'

Endpoint

GET /v1/bulkdownloads/{BD_UUID}/

Replace {BD_UUID} with the UUID of the Automatic Story Export container (we call it Bulkdownload).

Download one file of a specific automatic export

$ curl --request GET \
  --header 'Authorization: Token aa5d2e36668c11e5964038bc572ec103' \
  --url 'https://api.ax-semantics.com/v1/bulkdownloads/25e05d20-106b-11e6-b78f-a71d52357c51/4cdf787a-106b-11e6-a4c1-a71d52357c51/'

The API will respond by sending you the file to download. Headers will contain information about filename and content type.

Endpoint

GET /v1/bulkdownloads/{BD_UUID}/{BF_UUID}/

Replace {BD_UUID} with the UUID for the Automatic Story export container, and replace {BD_UUID} with the UUID of the corresponding export file.

Example use cases

Generate content from existing data

$ curl --request POST \
  --url https://api.ax-semantics.com/v1/rest-auth/login/ \
  --header 'Content-Type: application/json' \
  --data '{"email":"[email protected]","password":"SECRET_PASSWORD"}'
$ curl --request GET \
  --url https://api.ax-semantics.com/v1/content-project/ \
  --header 'Authorization: Token aa5d2e36668c11e5964038bc572ec103'
$ curl --request POST \
  --url "https://api.ax-semantics.com/v1/content-project/2123/generate_content/?force=true" \
  --header "Authorization: Token aa5d2e36668c11e5964038bc572ec103"
$ curl --request GET \
  --header 'Authorization: Token aa5d2e36668c11e5964038bc572ec103' \
  --url 'https://api.ax-semantics.com/v1/download-exports/?page=1&page_size=10'
  # ergibt Liste von möglichen Downloads, die analysiert werden müssen. Die
  # relevante Information findet sich unter dem Schlüsselwort "download_url"
$ curl --request GET \
  --output export.xlsx \
  --url https://api.ax-semantics.com/v1/content_project_export_download/7f9cc6a2-6b55-11e5-bb84-5e2c2d9baef2

To generate content for already imported data (in this example, a complete content project), follow these steps:

  1. Get your authentication token: Use your existing login information (email and password). This authentication token will be used in all further step to authenticate you with the API. (Every API client will do this for you.)
  2. Determine the Content Project ID: If you do not know the ID of your chosen Content Project, request the list of all Content Projects and look at its entries to determine the Content Project ID.
  3. Generate content for the whole Content Project: Refer to the Content Project by the ID you determined in step 2.
  4. [Optional] Request status of content generation until it is finished: this is mostly relevant for larger requests. You need to use both the Content Project ID and a Thing ID here.
  5. Download the generated content: Find the appropriate Download URL for the generated content and request the download.

Import data, then generate content

import axsemantics

axsemantics.login('', '')

data = {'key':'value'}
thing = axsemantics.Thing(uid=1, cp_id=1, pure_data=data, name='demo').create()
$ curl --request POST \
  --url https://api.ax-semantics.com/v1/rest-auth/login/ \
  --header 'Content-Type: application/json' \
  --data '{"email":"[email protected]","password":"SECRET_PASSWORD"}'
$ curl --request GET \
  --url https://api.ax-semantics.com/v1/content-project/ \
  --header 'Authorization: Token aa5d2e36668c11e5964038bc572ec103'
$ curl --request POST \
  --url https://api.ax-semantics.com/v1/content-project/1/thing/ \
  --header 'Authorization: Token aa5d2e36668c11e5964038bc572ec103' \
  --data '{"uid":1, "name":"demo", "content_project":1, "pure_data":"{\"key\":\"value\"}"}'
$ curl --request PUT \
  --url https://api.ax-semantics.com/v1/content-project/1/thing/123/ \
  --header 'Authorization: Token aa5d2e36668c11e5964038bc572ec103' \
  --data '{"uid":1, "name":"demo", "content_project":1, "pure_data":"{\"diffent key\":\"different value\"}"}'

If you have an existing Content Project, but you need to import data before content generation, follow these steps and then continue at the example for content generation above.

  1. Get your authentication token: Use your existing login information (email and password). This authentication token will be used in all further step to authenticate you with the API. (Every API client will do this for you.)
  2. Determine the Content Project ID: If you do not know the ID of your chosen Content Project, request the list of all Content Projects and look at its entries to determine the Content Project ID.
  3. Create a new Object with your data: Within that Content Project, you can now create new objects. The data you want to import should be sent in the pure_data field. You will give the Object an UID. However, if you need to look up or address the Object later on, you need to save the returned Object ID.
  4. [Optional] Update an Object’s data: Sometimes, you want to update an Object’s data. Here you will have to use the generated Object ID (instead of the UID of your choosing) to address the Object.

v2 API

Documents

We store your data in Documents. Each Document belongs to exactly one Collection.

Create a new Document

$ curl --request POST \
  --url 'https://api.ax-semantics.com/v2/collections/1/document/' \
  --header 'Authorization: Token 7de3adb043d74ca79de98cc5b6d7c405' \
  --header 'Content-Type: application/json' \
  --data '{"uid": 222333,"name":"demo","capacity":{"unit":"F","value":4"}'

To create a new Document object, POST its data into an existing Collection.

No fields are mandatory; however, if you provide name and/or uid we will make your Document accessable using these attributes. Otherwise we will generate the uid and name. We suggest you provide both uid and name: it will help you find your Document again in your Collection.

The value for uid must be unique within a Collection.

Endpoint

POST /v2/collections/{CID}/document/

Replace {CID} with a valid Collection ID.

Show details of a Document

$ curl --request GET \
  --url 'https://api.ax-semantics.com/v2/documents/d731e27cdd234e5486f1f309cd344e51/' \
  --header 'Authorization: Token f763438dac31499ba9ee5fc850f4d420'

Endpoint

GET /v2/documents/{DID}/

Replace {DID} with a valid Document ID.

Update an existing Document

$ curl --request PATCH \
  --url 'https://api.ax-semantics.com/v2/documents/fd5886af005c4ed9a9f56f8c1aa7949b/' \
  --header 'Authorization: Token 6978b4e8bb464a0fae3f4c77166caf94' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Fresh new name","sn":"644129804140"}'

Endpoint

PATCH /v2/documents/{DID}/

Replace {DID} with a valid Document ID.

Delete a Document

$ curl --request DELETE \
  --url 'https://api.ax-semantics.com/v2/documents/62e5c91175844887964c1a9a3f6af2c6' \
  --header 'Authorization: Token df3f37d1c6f948738391661c705e13df'

Endpoint

DELETE /v2/documents/{DID}/

Replace {DID} with a valid Document ID.

Generate content for a single Document

$ curl --request POST \
  --url 'https://api.ax-semantics.com/v2/documents/dca2b1cac20249edaaeb5db305362636/generate-content/' \
  --header 'Authorization: Token 9a06ea87078d4129be35262a868abc29'

Endpoint

POST /v2/documents/{DID}/generate-content

Replace {DID} with a valid Document ID.

Collections

Collections bundle Document objects. All such Documents are rendered using the same training from their Collection.

List Collections

Shows paginated list of all Collections the user has access to.

$ curl --request GET \
  --url https://api.ax-semantics.com/v2/collections/ \
  --header 'Authorization: Token f30d6b31bec34e3abe945fac786672fe'

The API returns a JSON string, such as: json { "count":1, "next":null, "previous":null, "results":[{ "id":11, "created":"2016-11-08T14:32:55.612102Z", "modified":"2016-11-08T14:32:55.612137Z", "celery_queue_suffix":"", "es_doc_type":null, "es_search_query":null, "es_taxonomy_processed":false, "flags":{ "suppress_autoregeneration":false, "autogenerate":false}, "license_holder":"customer-group-19", "language":"en-US", "name":"Test Collection", "training_id":111, "uses_published_training":false, "webhook_secret":"eiuriewqrm324321n32b4n3v21b4", "webhook_url":null, "document_processing_states":{"none":10,"generated":1000}} ]}

Endpoint

GET /v2/collections/

Create a new Collection

$ curl --request POST \
  --url 'https://api.ax-semantics.com/v2/collections/' \
  --header 'Authorization: Token bd800b0689384091936f0bec670a3e78' \
  --data '{"name":"Demo collection","language":"en-US","training_id":333}'

Endpoint

POST /v2/collections/

Show a single Collection object

$ curl --request GET \
  --url http://api.ax-semantics.com/v2/collections/11/ \
  --header 'Authorization: Token f1a9f7aa3dc545bbbf2b4d88c4713e86'

The API returns a JSON response, such as:

{ "id":11,
  "created":"2016-11-08T14:32:55.612102Z",
  "modified":"2016-11-08T14:32:55.612137Z",
  "celery_queue_suffix":"",
  "es_doc_type":null,
  "es_search_query":null,
  "es_taxonomy_processed":false,
  "flags":{
    "suppress_autoregeneration":false,
    "autogenerate":false},
  "license_holder":"customer-group-19",
  "language":"en-US",
  "name":"Test Collection",
  "training_id":111,
  "uses_published_training":false,
  "webhook_secret":"eiuriewqrm324321n32b4n3v21b4",
  "webhook_url":null,
  "document_processing_states":{"none":10,"generated":1000}}

Endpoint

GET /v2/collections/{CID}/

Replace {CID} with a valid Collection ID.

Update an existing Collection

$ curl --request PATCH \
  --url 'https://api.ax-semantics.com/v2/collections/11/' \
  --header 'Authorization: Token 535c66208b224449a834e91bae76b953' \
  --data '{"webhook_url":"http://example.com/backdoor/"}'

Endpoint

PATCH /v2/collections/{CID}/

Replace {CID} with a valid Collection ID.

Delete a Collection

$ curl --request DELETE \
  --url 'https://api.ax-semantics.com/v2/collections/22/' \
  --header 'Authorization: Token d63bcc2f75e8495493898334f197b01c'

Eventually the Collection and all its corresponding Documents will be removed from our database.

Endpoint

DELETE /v2/collections/{CID}/

Replace {CID} with a valid Collection ID.

Generate content for all Documents in a Collection

$ curl --request POST \
  --url 'https://api.ax-semantics.com/v2/collections/11/generate-content/' \
  --header 'Authorization: Token 759193889f174c33922a909ddece262a'

Endpoint

POST /v2/collections/{CID}/generate-content/

Replace {CID} with a valid Collection ID.