Introduction

Welcome to the Remarq API! You can use our API to access Remarq API endpoints, which allows you to create new documents programatically.

We have code examples for Shell and Ruby! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

This example API documentation page was created with Slate.

The source is available on GitHub. Feel free suggest modifications or to edit it and use it as a base for your own API’s documentation.

JSON API Standard

The Remarq API uses the JSON API standard. The arrangement of endpoints and the structure of reqeust and response data is based on that standard.

The official list of JSON API implementations is a good place to look for tools to help with client implementations.

Authentication

To authorize, use this code:

require "net/http"
require "uri"

url = URI.parse("https://app.remarq.io/api/me")

req = Net::HTTP::Get.new(url.path)
req.add_field("Authorization", "yyz123")

res = Net::HTTP.new(url.host, url.port).start do |http|
  http.request(req)
end

puts res.body

# With shell, you can just pass the correct header with each request
curl "https://app.remarq.io/api/me"
  -H "Authorization: yyz123"

Make sure to replace yyz123 with your API key.

Remarq uses API keys to allow access to the API. You can register a new Remarq API key at our developer portal.

Remarq expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: yyz123

You must replace yyz123 with your personal API key.

Documents

Create a new document

TODO : shell script

require 'net/http'

document_attributes = {
  data: {
    type: "documents",
    attributes: {
      "title":"MyString",
      "markdown":"# oh, hai! \n\n hello, there!",
      "webhook-url": "http://your-callback-url"
    },
    relationships: {
      style: { data: { type: "styles", id: 2 } }
    }
  }
}

uri = URI('https://app.remarq.io/api/documents')
http = Net::HTTP.new(uri.host, uri.port)
req = Net::HTTP::Post.new(uri.path, initheader = {'Content-Type' =>'application/json'})
req.add_field("Authorization", "yyz123")
req.body = document_attributes.to_json
res = http.request(req)
puts "response #{res.body}"

The response contains JSON structured like this:

{
  "data":{
    "id":"107",
    "type":"reports",
    "links":{"self":"http://test.host/api/reports/107"},
    "attributes":{
      "title":"MyString",
      "markdown":"# oh, hai! \n\n hello, there!",
      "webhook-url": "http://your-callback-url"
    },
    "relationships":{
      "style":{
        "links":{
          "self":"http://test.host/api/reports/107/relationships/style",
          "related":"http://test.host/api/reports/107/style"
        }
      }
    }
  }
}

HTTP Request

POST https://app.remarq.io/api/documents

Get All Documents

require "net/http"
require "uri"

url = URI.parse("https://app.remarq.io/api/documents")

req = Net::HTTP::Get.new(url.path)
req.add_field("Authorization", "yyz123")

res = Net::HTTP.new(url.host, url.port).start do |http|
  http.request(req)
end

puts res.body

# With shell, you can just pass the correct header with each request
curl "https://app.remarq.io/api/documents"
  -H "Authorization: yyz123"

The above command returns JSON structured like this:

{
  "data":[
    {
      "id":"191",
      "type":"documents",
      "links":{
        "self":"https://app.remarq.io/api/documents/191"
      },
      "attributes":{
        "title": "Remarq Demo Document",
        "markdown": "# Chapter 1 \n First the Universe bean to cool...",
        "webhook-url": "http://your-callback-url"
      }
    }
  ]
}

This endpoint retrieves all documents.

HTTP Request

GET https://app.remarq.io/api/documents

Get a Specific Document

require "net/http"
require "uri"

url = URI.parse("https://app.remarq.io/api/documents/2")

req = Net::HTTP::Get.new(url.path)
req.add_field("Authorization", "yyz123")

res = Net::HTTP.new(url.host, url.port).start do |http|
  http.request(req)
end

puts res.body

curl "https://app.remarq.io/api/documents/2"
  -H "Authorization: yyz123"

The above command returns JSON structured like this:

{
  "data":{
    "id":"75",
    "type":"reports",
    "links":{
      "self":"https://app.remarq.io/api/reports/75"
    },
    "attributes":{
      "title":"MyString",
      "markdown":"# oh, hai! \n\n hello, there!",
      "webhook-url": "http://your-callback-url"
    },
    "relationships":{
      "style":{
        "links":{
          "self":"https://app.remarq.io/api/reports/75/relationships/style",
          "related":"https://app.remarq.io/api/reports/75/style"
        }
      }
    }
  }
}

This endpoint retrieves a specific document.

HTTP Request

GET https://app.remarq.io/api/documents/<ID>

URL Parameters

Parameter	Description
ID	The ID of the document to retrieve

Update document

TODO Shell script

require 'net/http'

document_attributes = {
  data: {
    type: "documents",
    attributes: {
      "title":"MyString",
      "markdown":"# oh, hai! \n\n hello, there!",
      "webhook-url": "http://your-callback-url"
    },
    relationships: {
      style: { data: { type: "styles", id: 2 } }
    }
  }
}

uri = URI('https://app.remarq.io/api/documents/107')
http = Net::HTTP.new(uri.host, uri.port)
req = Net::HTTP::Put.new(uri.path, initheader = {'Content-Type' =>'application/json'})
req.add_field("Authorization", "yyz123")
req.body = document_attributes.to_json
res = http.request(req)
puts "response #{res.body}"

The response contains JSON structured like this:

{
  "data":{
    "id":"107",
    "type":"reports",
    "links":{"self":"http://test.host/api/reports/107"},
    "attributes":{
      "title":"MyString",
      "markdown":"# oh, hai! \n\n hello, there!",
      "webhook-url": "http://your-callback-url"
    },
    "relationships":{
      "style":{
        "links":{
          "self":"http://test.host/api/reports/107/relationships/style",
          "related":"http://test.host/api/reports/107/style"
        }
      }
    }
  }
}

HTTP Request

PUT https://app.remarq.io/api/documents

Delete a Document

require "net/http"
require "uri"

url = URI.parse("https://app.remarq.io/api/documents/2")

req = Net::HTTP::Delete.new(url.path)
req.add_field("Authorization", "yyz123")

res = Net::HTTP.new(url.host, url.port).start do |http|
  http.request(req)
end

puts res.body

# TODO Shell script

The above command returns JSON structured like this:

{}

This endpoint deletes a specific document.

HTTP Request

DELETE https://app.remarq.io/api/documents/<ID>

URL Parameters

Parameter	Description
ID	The ID of the document to delete

Styles

Get All Styles

require "net/http"
require "uri"

url = URI.parse("https://app.remarq.io/api/styles")

req = Net::HTTP::Get.new(url.path)
req.add_field("Authorization", "yyz123")

res = Net::HTTP.new(url.host, url.port).start do |http|
  http.request(req)
end

puts res.body

# With shell, you can just pass the correct header with each request
curl "https://app.remarq.io/api/styles"
  -H "Authorization: yyz123"

The above command returns JSON structured like this:

{
  "data":[
    {
      "id":"191",
      "type":"styles",
      "links":{
        "self":"http://test.host/api/styles/191"
      },
      "attributes":{
        "name":"MyString"
      }
    }
  ]
}

This endpoint retrieves all styles.

HTTP Request

GET https://app.remarq.io/api/styles

Outputs

Get All Outputs

require "net/http"
require "uri"

url = URI.parse("https://app.remarq.io/api/outputs")

req = Net::HTTP::Get.new(url.path)
req.add_field("Authorization", "yyz123")

res = Net::HTTP.new(url.host, url.port).start do |http|
  http.request(req)
end

puts res.body

# With shell, you can just pass the correct header with each request
curl "https://app.remarq.io/api/outputs"
  -H "Authorization: yyz123"

The above command returns JSON structured like this:

{
  "data":[
    {
      "id":"191",
      "type":"outputs",
      "links":{
        "self":"http://test.host/api/outputs/191"
      },
      "attributes":{
        "name":"MyString"
      }
    }
  ]
}

This endpoint retrieves all outputs.

HTTP Request

GET https://app.remarq.io/api/outputs

Webhooks

When a document has finished processing we will send a POST to the URL registered in the webhook-url attribute of the document.

The payload is JSON string that is identical to what you get when you get a specific document.

{
  "data":{
    "id":"75",
    "type":"reports",
    "links":{
      "self":"https://app.remarq.io/api/reports/75"
    },
    "attributes":{
      "title":"MyString",
      "markdown":"# oh, hai! \n\n hello, there!",
      "webhook-url": "http://your-callback-url",
      "pdf-url": "https://..."
    },
    "relationships":{
      "style":{
        "links":{
          "self":"https://app.remarq.io/api/reports/75/relationships/style",
          "related":"https://app.remarq.io/api/reports/75/style"
        }
      }
    }
  }
}

Errors

The Kittn API uses the following error codes:

Error Code	Meaning
400	Bad Request – Your request sucks
401	Unauthorized – Your API key is wrong
403	Forbidden – The kitten requested is hidden for administrators only
404	Not Found – The specified kitten could not be found
405	Method Not Allowed – You tried to access a kitten with an invalid method
406	Not Acceptable – You requested a format that isn’t json
410	Gone – The kitten requested has been removed from our servers
418	I’m a teapot
429	Too Many Requests – You’re requesting too many kittens! Slow down!
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarially offline for maintanance. Please try again later.