Get started with the Content API

Overview

The Content API provides an interface to create and manage content and revisions.

Make a request

All API requests must be directed to the https://api.quantcdn.io/v1/ endpoint. The path is prefixed with the API version. If backwards-breaking changes are introduced into the API the version number will be bumped. Old versions of the API will be maintained and deprecated with plenty of notice. You will need to add specific headers to each request to ensure that the API endpoint can correctly identify you.

In curl a request will look like:

curl -H "Quant-Customer: [example-customer]" -H "Quant-Project: [example-project]" -H "Quant-Token: [project-token]" https://api.quantcdn.io/v1/ping

Authentication

Quant uses bearer tokens for authentication. All requests must specify the Quant-Token request header and need to send the value presented in your dashboard. If you haven’t created a project head over to your dashboard set one up to retrieve your token and start publishing!

To further identify your request you are required to add Quant-Customer and Quant-Project request headers. These will be validated against the Quant-Token to ensure that the request is valid.

Pagination

Requests that return multiple items will be paginated to 100 items by default. You can specify the page query parameter to iterate through the result set. You can also change the number returned by Quant with the per_page parameter.

Paginated API endpoints will return data under a records key.

Metadata

Paginated result sets will include metadata to help identify how many results are available for any given call. These are available in the result object as page, page_size, total_records and total_pages.

Sending content to the API

The most common API action is sending content, either new content or a content revision. Quant supports two types of files;

HTML (markup)[#sending-markup] as pages
Accompanying (assets)[#sending-assets] like images, JavaScript and stylesheets

Quant is based on atomic deployments, each time a file changes Quant treats it as if a new file was submitted to the API. This allows Quant to show point in-time representations of any asset that has been sent to Quant.

Sending markup and content

This is the main action of the Quant API and is how we register paths and content to be served from those paths. When you send markup you will need to tell Quant what URL this markup will be accessible by, if the content is published and additional metadata.

curl -X POST https://api.quantcdn.io/v1 -d @./payload.json

{
  "content": "<html><body><img src="/banner.jpg" /><h1>My static web page</h1></body></html>",
  "url": "/",
  "published": true,
  "info": {
    "author_name": "Joe Static",
    "log": "Revision log message"
  }
}

The Quant API will scan your markup and identify assets. It will respond to your request with a list of assets that already exist in Quant (along with MD5 values) so you only need to push files that have changed or do not already exist.

Custom headers

You may optionally provide custom headers along with the content payload. This allows fine-grained control of the headers that are emitted for each individual piece of content. Simply include key/value pairs under the headers key:

{
  "content": "{\"key\": \"example\", \"value\": \"example\"}",
  "headers": {
    "content-type": "application/json"
  }
}

Sending assets

The second part to a web page is all the assets that help provide the visual experience. This includes images, JavaScript, stylesheets, video files and all other static assets. Files are sent as multipart uploads directly to the Quant API. Quant will handle inspecting and creating revisions of the assets.

To add a URL for the file you need to specify the Quant-File-Url header.

curl -X POST https://api.quantcdn.io/v1 -F "filename=@./banner.jpg" -H "Quant-File-Url: /banner.jpg"

Custom headers

As with content, files may also present custom headers. These are passed in as encoded JSON using the Quant-File-Headers header on the POST request.

curl -X POST https://api.quantcdn.io/v1 -F "filename=@./image.jpg" -H "Quant-File-Url: /path/to/extensionless-image" -H "Quant-File-Headers: {\"content-type\": \"image/jpeg\"}"

Commonly used endpoints

Metadata

When you request metadata about your site, Quant will send a paginated API response containing information about your files that is not served to end users. This includes information like the published revision, the number of revisions, where the file is accessed and more.

The endpoint requires the standard authentication headers described above.

GET /global-meta

{
  "global_meta": {
    "records": [
      {
        "last_modified": "2020-07-20T10:21:11",
        "meta": {
          "url": "/about-us",
          "type": "content",
          "seq_num": 3,
          "published": true,
          "byte_length": 41750,
          "published_md5": "1476374aafe25fb499729ee7e4505e62",
          "date_timestamp": 1595240471,
          "revision_count": 3,
          "published_revision": 3,
          "highest_revision_number": 3
        }
      },
    ]
  }
}

You may query for the metadata of individual URLs using the /url-meta endpoint.

curl -X POST -d '{"Quant-Url": ["/styles.css", "/about-us" ]}' https://api.quantcdn.io/v1/url-meta

Unpublish content

PATCH /unpublish instructs Quant that a particular path is no longer accessible. This will cause Quant to issue a 404 for the path instead of the content stored for the path.

curl -X PATCH -H "Quant-Url: /path/to/unpublish"

Restore a previous revision

PATCH /publish/[REVISION_ID] allows a previous revision to become the actively published content. You may retrieve revision ids via the metadata endpoints.

curl -X PATCH -H "Quant-Url: /content" https://api.quantcdn.io/v1/publish/123

Create a redirect

POST /redirect creates a redirect.

This allows you to redirect one path to another when Quant is serving pages. You can control the status code that Quant serve when you create this redirect.

{
  "url" : "/url/to/redirect",
  "redirect_url" : "/target/path",
  "redirect_http_code" : 301,
  "published" : true
}

Purge the cache

POST /purge to purge content paths or cache-tags from the edge caches.

This will delete cached items from the edge caches so the next request will reload fresh content.

Provide individual paths using the Quant-Url header
Provide space separated cache tags/keys using the Cache-Keys header
Trigger a soft purge by using the Soft-Purge header

Example: Purge an individual content path

curl -X POST -H "Quant-Url: /content" https://api.quantcdn.io/v1/purge

Example: Purge the entire cache

curl -X POST -H "Quant-Url: /*" https://api.quantcdn.io/v1/purge

Example: Soft-purge an individual content path

Soft purging will mark an item as stale rather than deleting it immediately from the cache. It will allow serving a stale copy of the content if the original is unavailable, which can be useful to continue serving content if your origin server is inaccessible.

curl -X POST -H "Quant-Url: /content" -H "Soft-Purge: true" https://api.quantcdn.io/v1/purge

Example: Purge using cache keys

Cache keys (or cache tags) are keys associated with one or more pieces of content when your origin server exposes them via the Cache-Keys response header.

curl -X POST -H "Cache-Keys: azbe5 gormb1" https://api.quantcdn.io/v1/purge