Any example clients for REST API?



I’m evaluating using Grakn and like the look of it so far.

I see you’ve got basic REST API documentation here: . Do you have anything else to get me started using this?

More specifically my questions are:

(Q1) do you envisage REST API client libraries (say in Python or R or in my case go) using the graql or json/hal version of the api? (or working in some other way all together?)

I ask because I don’t plan to use graqn from Java, rather I have mostly golang and some python microservices that I would need to have communicating with grakn over the network.

I’ve found this:
Like the repo says it was just a proof of concept - but I’m wondering whether your official REST API client libraries in the future will parse the graql text, or the application/json/hal response, or work in some other way all together?

(Q2) Do you have perhaps a python or R library (of much less likely: golang library!) in the works I can take a peak at? Or any code that would help me start thinking about these, ie a robust way of parsing the application/graql response if that’s the way the client libraries will work.

Basically I’m at the point where I’ve read through all the docs, have done various grakn queries from the console and in the visual interface and watched Haikal’s Data Day Texas video twice in fact. I more or less get how things work and get the genius of it all :slight_smile:. But I don’t use and don’t plan to use java! So I’d now like to build out an MVP of sorts where I test the idea of using grakn as the main database backing an application running in golang and/or python. (Happy to share more details of this privately.)

(Q3) Have you guys thought about having a GRPC endpoint at all? Have you come across for example? I like your approach to ontology and schema and inference and the like much more… but I’ve found using their graph database from python and go much easier due to their GRPC-based API. I could image this working really well for grakn, with the primary benefits being:

  • it’s a binary protocol, so fast! and you get back types - so client libraries get back whether data is bool/string/numeric/etc.
  • from the specification you can generate client libraries in most languages automatically: e.g. python, C++, java, go, etc. So on the grakn server side you could make the endpoint with grpc’s java library, and have the client libraries in other languages auto-generated.

Thanks a lot in advance


REST API Content-Type header not recognised
REST API Content-Type header not recognised


I’d like to work with grakn a bit more over the next few weeks from go and python, if possible. Any help with the above questions would really be appreciated!




Hi @mikeleonard.

Sorry for the delayed response. @marco and @alex could you guys weigh in?

With regards to your question:

  1. All our REST apis will work in the same manners. The drivers to communicate with these REST apis will need their own implementation which we would like to get more into or see the community help us out with. There should be no difference from the REST side though.

  2. Sadly not at the moment. The github repo is the best we have at the moment. We will likely get back to these projects when time allows.

  3. We have mentioned using RPC before but there are no plans for it at the moment. I will look into GRPC and run it by our team. Who knows, maybe we will go for it :slight_smile: . It certainly sounds interesting.

Hope that clears a few things up.




Oh quick addendum. At this point in time the REST API lacks the ability to write to the graph. Not to worry though. We working on this at the moment.


With regards to (Q1):
I would envision any official REST client libraries using the Graql response (as this is what all of our unofficial libraries do). The HAL response is used mostly for visualization now, though one could conceivably use it for more complex applications.

As Filipe mentions above, our REST API does not support insert queries. We are working on this now and you have a couple of options for insert queries in the meantime:

  1. Use the Websocket (as Graql Shell does)
  2. Pipe queries into (as the Haskell Driver does). This is a roundabout way of using the websocket.

Hope this helps!-- Let me know if you want more info on either of those options.


Hi Mike,

Sorry for the late answer, but I had completely missed the question.

Going in order:
A1) We do not have much more than what you already found (I wrote the Python PoC and @sheldon wrote the R one). But those are already usable. Basically what they do is using the Graql Shell as an interface to GRAKN.AI
I am not aware of future plans of for the REST API.
A2) I personally do have plans to implement a more proper Python driver to interact with GRAKN, but it has been delayed due to impending deadlines I have to keep up with. My plan is to use the web socket to send graql queries to engine and receive back the JSON/HAL response, which can then be parsed to fit your need. This allows to fully use the graph and is basically the way GRAQL shell communicates with the engine. ATM I have just developed a very rough and poorly tested version of the communication layer that uses Python’s Websockets library. I am still not convinced of having picked the right library for the job, but I haven’t had time to do more research on the topic.

My plan is to:

  • Finish writing the client to a barely acceptable state and upload it somewhere (it would probably get into the same repo you already found)
  • Implement a few of the Graql objects in Python like @felix did for Haskell (see
  • Rinse and repeat

Hopefully this would serve as a useful base to develop similar clients in other language.

Since the time I can dedicate to the project is quite limited and I have no experience with Async programming and web socket, I would gladly accept your help if you are up to it.

Re. A3) I have nothing to add to what Filipe has already said.


Very much looking forward to the REST API being fully interactive :slight_smile: I’ve got big plans :wink:


If it still interests anyone, I have a small example of a nodejs API that uses the GRAKN driver. More endpoints and some refactoring coming tomorrow.


I’m developing a PHP-based ORM library that’s designed to be used in frameworks such as Laravel/Lumen. Using it, you can define models that directly translate to entities and does so by consuming the Grakn REST interface.

I’m currently getting it working with the syntax updates in 0.18 and shortly thereafter will be punishing it by running a fairly sizable dataset through it. Assuming this goes well and my employer continues to offer their support, I’ll see about packaging it up and making it available.

I know PHP can sometimes be thought of as a bit of a second-class citizen among so-called “real programmers” but it remains quite popular and approachable, so I suspect being able to tie into a knowledge graph directly would be of great value to many projects. I know it would be for me, which is why I’m building it. :slight_smile:


Can you share the concepts behind your ORM? That could be cool to have that for python and nodejs!


Sure thing. I’m attempting to stick to the example of (and in fact am including as a dependency) the Eloquent ORM library that is maintained by Laravel ( The intent is that anybody who has gotten familiar with that will be able to use the graph database with only a small amount of adaptation.

So, for example, here’s my latest test script, which is inserting some website access log data:

$new_page = new Artifact();
$new_page->hostname = $host;
$new_page->pagetitle = $title;
$new_page->url = $url;
$new_page = $new_page->save();

$new_hit = new Pagehit();
$new_hit->seconds = $time;
$new_hit = $new_hit->save();

$hit_relation = $new_hit->plays('container')->plays($new_page,'contained');
$hit_relation_response = $hit_relation->relate('content');

$utmsource = new UtmSource();
$utmsource->userid = $userid;
$utmsource->dimensionvalue = $utm_source_val;
$utmsource = $utmsource->save();

$utmsource_relation = $utmsource->plays('describer')->plays($new_hit,'described');
$utmsource_relation_response = $utmsource_relation->relate('description');

$utmmedium = new UtmMedium();
$utmmedium->userid = $userid;
$utmmedium->dimensionvalue = $utm_medium_val;
$utmmedium = $utmmedium->save();

$utmmedium_relation = $utmmedium->plays('describer')->plays($new_hit,'described');
$utmmedium_relation_response = $utmmedium_relation->relate('description');

In this example, we have Artifact, Pagehit, UtmSource, and UtmMedium models defined in the application. These have the normal sort of MVC-type attributes and extend my Eloquent-like ORM class. The save() function on each of these models is the same as if you were saving to a tabular database, but this is instead generating a entity according to my predefined ontology, and adding the model attributes as entity-attributes.

The other bits that are joining these models together, have no analogous function in Eloquent. These are defined by the plays() and relates() functions, which map to the normal Grakn roles and relations which I have also pre-defined in the ontology.

There’s still quite a bit to do on this:

  • Defining ontologies in the model so the model can update Grakn
  • Figuring out where rules are defined in an Eloquent-like MVC
  • Figuring out where relationships are defined in an Eloquent-like MVC
  • Actually defining those relationships in such a way that what is defined in the application remains in sync with the ontology
  • Dealing with Cassandra administrativia, such as verification of a keyspace, configuration of replication factors, etc
  • Chasing down the undoubtedly legion edge-cases that will come up applying different kinds of content

But! It is working in the limited way I need it to at the moment. So, that’s nice.


Well done. I have some laravel apps running and what you show does feel like eloquent.

That would indeed be nice to solve all the problems you mention. Did you have look at, the maybe have some ideas on how to ORMize (OGMize) some graph concepts.

That solution could then be applied to many other cases/languages


Hi @awaschick
some progress with the driver? Do you intent to put it open-source? I’m working with Laravel and it would be valuable…


Greetings all,

We have an existing UI for graph querying and visualizing that we hope to configure for Grakn. Having trouble getting the HTTP REST api working using example code from the dashboard - specifically EngineClient.js.

In theory, I was assuming the below would work as an initial test:

function request(requestData) {
    return new Promise((resolve, reject) => {
      try {
        const req = new XMLHttpRequest(); || 'GET', requestData.url);
        this.setHeaders(req, requestData);

        req.onload = function setOnLoad() {
          if (req.status === 200) {
          } else {
          // if (spinner) = 'hidden';

        // Make the request
        // if (spinner) = 'visible';
      } catch (exception) {

function setHeaders(xhr, requestData) {
    xhr.setRequestHeader('Content-Type', requestData.contentType || 'application/json; charset=utf-8');
    if (requestData.accepts) xhr.setRequestHeader('Accept', requestData.accepts);

function graqlQuery(query) {
    return this.request({
      url: `http://localhost:4567/kb/grakn/graql?infer=true&defineAllVars=true`,
      requestType: 'POST',
      data: query,
var query = "match $x isa person, has identifier $n; offset 0; limit 30; get;";

Does anyone have experience with this?





yes correct. Does it work for you?


Hi Marco,

No, I can’t get it to work - I’m sure I’m doing something wrong but I’ve tried three different methods: XMLHttpRequest (as above), fetch, and jquery ajax. For the above I get 404 (Not Found) andResponse for preflight does not have HTTP ok status errors. Wondering if anyone has a template to share specifically for queries.



FYI - here’s the fetch config I’ve tried:

function queryGrakn(url, data) {
  // Default options are marked with *
    return fetch(url, {
        method: "POST",
        mode: "no-cors", // no-cors, cors, *same-origin
        cache: "no-cache", // *default, no-cache, reload, force-cache, only-if-cached
        credentials: "include", // include, same-origin, *omit
        headers: {
            "Content-Type": "application/json; charset=utf-8",
        redirect: "follow", // manual, *follow, error
        referrer: "client", // no-referrer, *client
        body: "match $x isa person, has identifier $n; offset 0; limit 30; get;", // body data type must match "Content-Type" header
    .then(function(response) {
    return response;
    .then(function(myJson) {
    .catch(error => console.error(`Fetch Error =\n`, error));


Hi @JBatUN,

the issue you have might be due to CORS requests if you are trying to query Grakn directly from the browser.

We always though the user would connect to Grakn from some kind of backend service - and not directly from a browser (that’s also a reason why there is no docs on how to query directly Grakn from Javascript).

If you need to connect from the browser directly I can send you a modified Grakn version that allows CORS connections (just shoot me a message in Slack).
Otherwise if you have some kind of server (Express.js or other languages) that connect to Grakn, you could use one of our drivers. (Example NodeJs driver


Hi @marco,

Yes, exactly - we’re looking to connect to Grakn directly from the browser. Basically, we’d be swapping the Grakn dashboard with ours which abstracts the query syntax with ui inputs and we’ve added several visualization enhancements (e.g. graph layouts, mapping, etc.).

Will send message in Slack.

Thanks for your assistance!



Not sure if this is helpful, but I checked the log file and these are the related error messages:

no viable alternative at input '"match $x isa person, has identifier $n; offset 0; limit 30; get;"'}
2018-07-26 10:20:40,417 [qtp450186751-156] ERROR a.g.e.controller.GraqlController - REST error
ai.grakn.exception.GraqlSyntaxException: syntax error at line 1: 
"match $x isa person, has identifier $n; offset 0; limit 30; get;"
no viable alternative at input '"match $x isa person, has identifier $n; offset 0; limit 30; get;"'
	at ai.grakn.exception.GraqlSyntaxException.create(
	at ai.grakn.graql.internal.parser.QueryParserImpl$QueryPart.parse(
	at ai.grakn.graql.internal.parser.QueryParserImpl$QueryPart.parse(
	at ai.grakn.graql.internal.parser.QueryParserImpl.parseQuery(
	at ai.grakn.engine.controller.GraqlController.executeQuery(
	at ai.grakn.engine.controller.GraqlController.lambda$executeGraql$5(
	at com.github.rholder.retry.AttemptTimeLimiters$
	at ai.grakn.engine.controller.GraqlController.executeFunctionWithRetrying(
	at ai.grakn.engine.controller.GraqlController.executeGraql(
	at spark.RouteImpl$1.handle(
	at spark.http.matching.Routes.execute(
	at spark.http.matching.MatcherFilter.doFilter(
	at spark.embeddedserver.jetty.JettyHandler.doHandle(
	at org.eclipse.jetty.server.session.SessionHandler.doScope(
	at org.eclipse.jetty.server.handler.ScopedHandler.handle(
	at org.eclipse.jetty.server.handler.HandlerWrapper.handle(
	at org.eclipse.jetty.server.Server.handle(
	at org.eclipse.jetty.server.HttpChannel.handle(
	at org.eclipse.jetty.server.HttpConnection.onFillable(
	at org.eclipse.jetty.util.thread.strategy.ExecuteProduceConsume.produceAndRun(
	at org.eclipse.jetty.util.thread.QueuedThreadPool.runJob(
	at org.eclipse.jetty.util.thread.QueuedThreadPool$


Oh ok so the query gets executed by Grakn. You seem to have a quoting problem there , the query seems to be quoted twice by the time it gets to the server: no viable alternative at input '"match $x isa person, see the ' followed by "