Keys

All API requests must have a HTTP header with one of your API keys enabled for the intended operation (SPARQL access or API access).

You can manage your API keys from the dedicated panel, in your account: create as many keys as you want, and grant them the proper access for each.

API

Authentication

All requests must have a X-SB-Key header containing the value of one of your API key enabled for "Access to API".

Utilities

There are a few API endpoints in Semantic Builders exposed for your convenience.

The following endpoints can be used at no charge.

Available endpoints:

• GET https://semantic.builders/api/probe

  To just test the authentication key given in the X-SB-Key header.

  If valid, returns a simple feedback payload.

  {
    "code": 200,
    "message": "OK"
  }

  Error codes:

  • 400 no key has been provided.
  • 401 the provided key is invalid.

Retrieve Data

Semantic Builders exposed a simple API to access your Saved Queries and Extractions.

The following endpoints can be used at no charge.

Available endpoints:

• GET https://semantic.builders/api/extracts

  To access the list of your extractions. This returns a JSON array, containing a JSON object for each query.

  [
    {
      "id": "ee8b2837-62c4-4be0-8aba-969e4b118a03",
      "title": "My Extraction",
      "created_at": "2025-04-12T04:58:14",
      "size": 6712080
    },
    {
      "id": "5318480e-ccc9-4fb8-b45b-c1c8f4747131",
      "title": "My Other Extraction",
      "created_at": "2025-04-08T03:52:14",
      "size": 203848
    }
  ]

  Each extraction is described by:

  • id - the unique identifier of the element; use it to retrive contents with the related API endpoint
  • title - the title assigned to the element
  • created_at - date of creation of the element
  • size - filesize, in bytes

  Error codes:

  • 401 no key has been provided, or the provided one is invalid.
  • 403 the provided key is not enabled for API access.

• GET https://semantic.builders/api/extracts/ID

  To access the actual contents of a given extraction, identified by the id (provided by the listing endpoint).

  Contents are returned in CSV.

  Q1868,"Paul Otlet",+1868-08-23T00:00:00Z,+1944-12-10T00:00:00Z
  Q23,"George Washington",+1732-02-22T00:00:00Z,+1799-12-14T00:00:00Z
  Q42,"Douglas Adams",+1952-03-11T00:00:00Z,+2001-05-11T00:00:00Z
  Q368,"Augusto Pinochet",+1915-11-25T00:00:00Z,+2006-12-10T00:00:00Z

  Error codes:

  • 400 no key has been provided.
  • 401 the provided key is invalid.
  • 404 the required ID does not exists, or is not accessible with the given key.

Entity Recognition

Semantic Builders provides an API to handle arbitrary texts and retrieve named entities from Wikidata, ready to be referenced within text's self metadata.

Each call to the following endpoints is individual charged accordly to the given pricing for the service.

Available endpoints:

• GET https://semantic.builders/api/entities

  Parameters:

  • body the actual text you want to analyze. This can be a GET parameter, or just put in the HTTP request's body (suggested option for text longer than 2000 chars). If it is formatted in HTML, it is automatically flattered to plain text before execution. An empty result set is returned if the length of "body" is <= 10 characters.
  • language [optional] the language of the text. May have one of the following values:
    • en English
    • fr French
    • de German
    • it Italian
    • ja Japanese
    • pt Portuguese
    • ru Russian
    • es Spanish
    If not specified, or if not recognized, the language is auto detected.

  To analyze a text and retrieve references to Wikidata entities. This returns a JSON array, containing a JSON item for each identifier named entity.

  [
    {
      "entity": "Japan",
      "wikidata": "https://www.wikidata.org/wiki/Q17"
    },
    {
      "entity": "Tokyo",
      "wikidata": "https://www.wikidata.org/wiki/Q1490"
    },
    {
      "entity": "Sapporo Snow Festival",
      "wikidata": "https://www.wikidata.org/wiki/Q929531"
    }
  ]

  Each item in response is described by:

  • entity - the recognized named entity
  • wikidata - the link to the same Wikidata entity

  Error codes:

  • 400 no key has been provided.
  • 401 the provided key is invalid.
  • 403 the provided key is not enabled for API access.
  • 403 the provided key is not enabled for API access