outline/frontend/static/flatpages/api.markdown

Atlas API

Making requests

Atlas' API follows JSON RPC style convention where each API endpoint is a method on https://www.beautifulatlas.com/api/<METHOD>. Each request needs to be made using HTTPS.

Each method can be called with either GET or POST (recommended). For GET requests query string parameters are expected (e.g. /api/document.info?id=...&token=...). When making POST requests, request parameters are parsed depending on Content-Type header. To make a call using JSON payload, one must pass Content-Type: application/json header:

curl 'https://www.beautifulatlas.com/api/documents.info?id=atlas-api-NTpezNwhUP'\
  -H 'authorization: Bearer <API KEY>'\
  -H 'content-type: application/json'\
  -H 'accept: application/json'

Authentication

To access private API endpoints, you must provide a valid API key. You can create new API keys in your account settings. Be careful when handling your keys as they give access to all of your documents.

To authenticate with Atlas API, you can supply the API key as a header (Authorization: Bearer <API KEY>) or as part of the payload using token parameter.

Some API endpoints allow unauhenticated requests for public resources and they can be called without an API key.

Errors

All successful API requests will be returned with 200 status code and ok: true in the response payload. If there's an error while making the request, appropriate status code is returned with the error message:

{
	"ok": false,
    "error: "Not Found"
}

Methods

documents.info - Get a document

This method returns information for a document with a specific ID. Following identifiers are allowed:

• UUID - id field of the document
• URI identifier - Human readable identifier used in Atlas URLs (e.g. atlas-api-i48ZEZc5zjXndcP)

Arguments

https://www.beautifulatlas.com/api/documents.info

Parameter	Description
token	Authentication token
id	Document id or URI identifier

---

documents.search - Search documents

This methods allows you to search all of your documents with keywords.

Arguments

https://www.beautifulatlas.com/api/documents.search

Parameter	Description
token	Authentication token
query	Search query

---

documents.create - Create a new document

This method allows you to publish a new document under an existing collection. If your collection is structured type: atlas collection, you can also create sub-documents for other documents with optional parentDocument parameter.

Arguments

https://www.beautifulatlas.com/api/documents.create

Parameter	Description
token	Authentication token
collection	id of the collection to which the document is created
parentDocument	id of the parent document within the collection
title	Title for the document
text	Content of the document in Markdown

---

user.info - Get current user

This method returns the information for currently logged in user.

Arguments

https://www.beautifulatlas.com/api/user.info

Parameter	Description
token	Authentication token

---

user.s3Upload - Gets S3 upload credentials

You can upload small files and images as part of your documents. All files are stored using Amazon S3. Instead of uploading files to Atlas, you need to upload them directly to S3 with special credentials which can be obtained through this endpoint.

TODO: Add more about restrictions and flow

Arguments

https://www.beautifulatlas.com/api/user.s3Upload

Parameter	Description
token	Authentication token
filename	Filename of the uploaded file
kind	Mimetype of the document
size	Filesize of the document