Archiving

Keeper is our Archiving product. Architected for the Cloud and built for scale and speed.

Overview

The Keeper API has been developed using open standards and covers the necessary methods for communicating with the Keeper services, and pushing and pulling information, metadata and documents to the Keeper platform.

The base address of the API is https://auth.atkeeper.com. The API provides a set of endpoints, each with its own unique path.

Requests

The keeper API is based on REST principles. Data is accessed via standard HTTP requests in UTF-8 format to an API endpoint. Where possible, the API uses appropriate HTTP verbs for each action:

Responses

The API returns all response data as a JSON object. See the API Object Model for a description of all the retrievable objects.

Timestamps

Timestamps are returned in ISO 8601 format as Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ.

Pagination

Some endpoints support a way of paging the dataset, taking ‘page’ and ‘results_per_page’ as query parameters:

$ curl https://api.atkeeper.com/v1/documents/(docid)/history?page=2results_per_page=5

In this example, in a list of 20 (total) history records assoicated with the specific document: Display page 2, with 5 results per page, i.e. history records 6 to 10, inclusive.

Note: Omitting the page parameter returns the first page, and pages default to 10 results per page. Requests that return an array of items are automatically paginated if the number of items vary.

Conditional Requests

Some API responses contain appropriate cache-control headers set to assist in client-side caching:

• If you have cached a response, do not request it again until the response has expired.
• If the response contains an ETag, set the If-None-Match request header to the ETag value.
• If the response has not changed, the Keeper service responds quickly with 304 Not Modified status, meaning that your cached version is still good and your application should use it.

Response Status Codes

The API uses the following response status codes, as defined in RFC 2616 and RFC 6585:

Error Responses

Apart from the response code, unsuccessful responses return a JSON object containing the following information:

Authentication

All requests to Web API require authentication. This is achieved by sending a valid OAuth access token in the request header. [RFC 6749, Section 4.1] (https://tools.ietf.org/html/rfc6749#section-4.1)

Step 1: The GET request is sent to the authorize endpoint of the Keeper service:

GET https://auth.atkeeper.com/authorize

If the user accepts your request, the response query string contains the following parameters:

When the authorization code has been received, you will need to exchange it with an access token by making a POST request to the Keeper service, this time to its token endpoint: POST https://auth.atkeeper.com/token. The body of this POST request must contain the following parameters encoded in application/x-www-form-urlencoded as defined in the OAuth 2.0 specification.

If the user does not accepted your request or an error has occurred, the response query string contains the following parameters:

Step 2: Request refresh and access tokens

Header

Request Body

An alternative way to send the client id and secret is as request parameters (client_id and client_secret) in the POST body, instead of sending them base64-encoded in the header. On success, the response from the Keeper service has the status code 200 OK in the response header, and the following JSON data in the response body:

Step 3: Use the access token to access the Keeper api (example)

Step 4. Request a refreshed access token

Access tokens are deliberately set to expire after a short time, after which new tokens may be granted by supplying the refresh token originally obtained during the authorization code exchange.

The request is sent to the token endpoint of the Keeper service:

POST https://auth.atkeeper.com/token

The header of this POST request must contain the following parameter:

Header

The body of this POST request must contain the following parameters encoded in application/x-www-form-urlencoded as defined in the OAuth 2.0 specification:

Request Body

Keeper API Object Reference

Overview

The Keeper API has been developed using open standards and covers the necessary methods for communicating with the Keeper services, and pushing and pulling information, metadata and documents to the Keeper platform. The base address of the API is https://api.atkeeper.com. The API provides a set of endpoints, each with its own unique path.

All API endpoints return data using the JSON format.

When a collection of objects is returned and the number of objects is variable, the collection is wrapped in a paging object to simplify retrieval of further objects. The paging object will contain zero to n objects, where n is the number of objects per page.

Requests

Paging Object

The paging object is a container for a set of objects. It contains a key called objects (whose value is an array of the requested objects) along with headers and other keys like link, page and total_pages that can be useful in future calls.

Example Query:

https://api.atkeeper.com/v1/document?q={"filters":[{"name":"fullname","op":"like","val":"%Hall 25%"}]}&results_per_page=5

(The filter params are detailed later in this document.)

Example Response:

HTTP/1.0 200 OK
Content-Type: application/json
Link: <https://api.atkeeper.com/v1/document?page=2&results_per_page=5>; rel="next", <https://api.atkeeper.com/v1/document?page=3&results_per_page=5>; rel="last"

{
  "num_results": 11,
  "objects": [
    {
      "age": 73,
      "attachments": [],
      "created_at": "2018-05-01T06:00:00",
      "datejoin": "2009-07-06",
      "docid": "a75ee551-0e5d-421f-8150-dd591edc15ea",
      "fullname": "Brad Hall 25",
      "history": [],
      "id": 26,
      "membernum": "4053857",
      "notes": []
    },
    {
      "age": 65,
      "attachments": [],
      "created_at": "2018-05-01T06:00:00",
      "datejoin": "2013-10-15",
      "docid": "41d8db5b-a836-43de-ae83-138e5a7b7ab6",
      "fullname": "Brad Hall 250",
      "history": [],
      "id": 251,
      "membernum": "4074113",
      "notes": []
    },
    {
      "age": 68,
      "attachments": [],
      "created_at": "2018-05-01T06:00:00",
      "datejoin": "2013-10-17",
      "docid": "3b4dc20a-e5ee-4eef-94c7-26d00c66373a",
      "fullname": "Brad Hall 251",
      "history": [],
      "id": 252,
      "membernum": "4074160",
      "notes": []
    },
    {
      "age": 59,
      "attachments": [],
      "created_at": "2018-05-01T06:00:00",
      "datejoin": "2013-10-21",
      "docid": "f363a0ce-0062-4f2e-b2dd-7399058042ed",
      "fullname": "Brad Hall 252",
      "history": [],
      "id": 253,
      "membernum": "4074191",
      "notes": []
    },
    {
      "age": 59,
      "attachments": [],
      "created_at": "2018-05-01T06:00:00",
      "datejoin": "2013-10-21",
      "docid": "a2c9b83b-3f24-47b4-bbbb-498adf4ee607",
      "fullname": "Brad Hall 253",
      "history": [],
      "id": 254,
      "membernum": "4074192",
      "notes": [
        {
          "created_at": "2018-05-01T06:00:00",
          "document_id": 254,
          "id": 1,
          "notedata": "This is a test",
          "user_id": "Aaron"
        }
      ]
    }
  ],
  "page": 1,
  "total_pages": 3
}

Document Object

Document Object (example, actual structure is dependent on source)

To turn a docid into actual binary data, use the document endpoint:

https://api.atkeeper.com/v1/bin/(docid)

This endpoint will return a signed URL that links directly to the document, valid for a configurable short period of time (typically minutes)

History Object

Note Object

Example Query:

https://api.atkeeper.com/254/notes

Example Response:

HTTP/1.0 200 OK
Content-Type: application/json

{
  "num_results": 1,
  "objects": [
    {
      "document": {
        "age": 59,
        "created_at": "2018-05-01T06:00:00",
        "datejoin": "2013-10-21",
        "docid": "a2c9b83b-3f24-47b4-bbbb-498adf4ee607",
        "fullname": "Brad Hall 253",
        "id": 254,
        "membernum": "4074192"
      },
      "created_at": "2018-06-01T06:00:00",
      "document_id": 254,
      "id": 1,
      "notedata": "This is a test",
      "user_id": "Aaron"
    }
  ],
  "page": 1,
  "total_pages": 1
}

Attachment Object

To turn an attachmement id into actual binary data, use the attachment endpoint:

https://api.atkeeper.com/v1/bin/(attid)

This endpoint will return a signed URL that links directly to the attachment, valid for a configurable short period of time (typically minutes).

Query Params

Search Params

Filters

Example Query (from earlier in this document): https://api.atkeeper.com/v1/document?q={"filters":[{"name":"fullname","op":"like","val":"%Hall 25%"}]}&results_per_page=5