Keyword Hub

The API endpoints are:

HTTP JSON: https://api.thorn-hub.com/api/keywords
GraphQL: https://api.thorn-hub.com/api

Authentication

You will be provided an access token that is used to authenticate with the API. You can either pass this authentication token via an HTTP header or via a URL query parameter:

Header


Authorization: token <TOKEN>

Query Parameter


https://api.thorn-hub.com/api?token=<TOKEN>

API Varients

The API is available in two variants, a simple HTTP JSON API and as a GraphQL endpoint. The JSON API offers all essential functionality via simple HTTP calls, and the GraphQL endpoint offers a more structured response. The HTTP API is simpler, while the GraphQL API can be used with existing client libraries for fast integration.

HTTP JSON

GET /api/keywords

This returns the list of all keywords.

Request


GET https://api.thorn-hub.com/api/keywords

Response


{
  "data": {
    "keywords": [
      {
        "id": "af0cba51-ccc0-434f-a1b2-53906fdd4c74",
        "isOwnKeyword": false,
        "sourceID": null,
        "keyword": "...",
        "category": null,
        "language": "...",
        "translation": "...",
        "description": null,
        "isAmbiguous": false,
        "isAmbiguousNote": "..."
      },
      ...
    ]
  }
}

The only required fields are id and keyword, all other fields may be unspecified.

Field	Description
`id`	A unique ID identifying this keyword.
`isOwnKeyword`	If true, this keyword was created by your organization, and you are able to modify or delete it.
`sourceID`	If this keyword was created by your organization, it may optionally have a sourceID, which is an ID referencing your internal ID for this keyword. Your keyword source IDs are not visiable to any other organization.
`category`	The keyword category.
`language`	The keyword language.
`translation`	The keyword translation.
`description`	A description of the keyword.
`isAmbiguous`	Is the keyword ambiguous?
`isAmbiguousNote`	If the keyword is ambiguous, a note about why.

POST /api/keywords

This adds or updates keywords. When sending keywords to this list, they will update existing keywords if they match keywords already in the list. The keywords are identified as matching if one of the following is true:

The sourceID fields match
The keyword and language fields match
The keyword fields match and the language field is empty

If an existing keyword is not found that matches, a new keyword will be added to the list.

Request


POST https://api.thorn-hub.com/api/keywords

{
  "keywords": [
    {
      "sourceID": null,
      "keyword": "...",
      "category": null,
      "language": "...",
      "translation": "...",
      "description": null,
      "isAmbiguous": false,
      "isAmbiguousNote": "..."
    },
    {
      "sourceID": null,
      "keyword": "...",
      "category": null,
      "language": "...",
      "translation": "...",
      "description": null,
      "isAmbiguous": false,
      "isAmbiguousNote": "..."
    },
    ...
  ]
}

Response


{
  "data": {
    "keywords": [
      {
        "id": "af0cba51-ccc0-434f-a1b2-53906fdd4c74",
        "isOwnKeyword": false,
        "sourceID": null,
        "keyword": "...",
        "category": null,
        "language": "...",
        "translation": "...",
        "description": null,
        "isAmbiguous": false,
        "isAmbiguousNote": "..."
      },
      ...
    ]
  }
}

POST /api/keywords/remove

This removes existing keywords. The keywords to remove are identified as matching if one of the following is true:

The sourceID fields match
The keyword and language fields match
The keyword fields match and the language field is empty

Request


POST https://api.thorn-hub.com/api/keywords/remove

{
  "keywords": [
    {
      "sourceID": "123"
    },
    {
      "keyword": "abc",
      "language": "abc"
    },
    {
      "keyword": "xyz"
    },
    ...
  ]
}

Response


{
  "success": true,
}

GraphQL

The GraphQL endpoint is located at:


POST https://api.thorn-hub.com/api

For your convenience, there is a visual GraphQL interface located at:


https://api.thorn-hub.com/api/graphiql

Please see the schema documentation for the full details about the available queries and mutations. You may also wish to use one of the available client libraries to interface with the GraphQL API.