API v1

This page is for developers.

Introduction

Use the Overview Application Programming Interface (API) to write scripts and plugins that take advantage of features and data in Overview.

Calling the API

To access the API, your program needs an API Token. That token allows a script to behave like the user who created it, granting permissions on one document set. Keep it secret: anybody who can figure out the token has full read/write access to that document set.

While we work out the kinks, Overview's API is experimental; we've hidden the page that lets you generate an API token for a document set. To find it:

1. Browse to a document set.
2. Add "/api-tokens" to the URL. The URL should look like `http://www.overviewproject.org/documentsets/123/api-tokens".
3. Type in your app name and generate a token.

Now you can test your token. On a command-line:

curl -u 'MYTOKEN:x-auth-token' http://www.overviewproject.org/api/v1/document-sets/123/tags

This API endpoint will list all the tags on the document set.

Rules of API requests

• Requests and responses are always in JSON.
• All requests must be authorized. That means they must have an Authorization header of Basic #{base64encode("MYTOKEN:x-auth-token")}.
• GET and HEAD requests won't modify the document set. POST, PUT, PATCH and DELETE requests will.