API v1 (deprecated)

Deprecation Notice

This API has been deprecated and is no longer under active development. Please use our v2 API, which features better documentation, developer support, and features.

Documentation for the deprecated API can be found below.

Purpose

The purpose of the CoCalc API (application programming interface) is to make essential operations within the CoCalc platform available to automated clients. This allows embedding of CoCalc services within other products and customizing the external look and feel of the application.

Protocol and Data Format

Each API command is invoked using an HTTPS POST request. All commands support request parameters in JSON format, with request header Content-Type: application/json. Many commands (those that do not require lists or objects as parameters) also accept request parameters as key-value pairs, i.e. Content-Type: application/x-www-form-urlencoded.

Responses are formatted as JSON strings. Note that it is possible for a request to fail and return a response code of 200. In that case, the response string may contain helpful information on the nature of the failure. In other cases, if the request cannot be completed, a response code other than 200 may be returned, and the response body may be a generic HTML message rather than a JSON string.

Authentication

A valid API key is required on all API requests. To learn how to create an API key, see API Keys.

Additional References

API Message Reference

The remainder of this guide explains the individual API endpoints. Each API request definition begins with the path of the URL used to invoke the request, for example /api/v1/change_email_address. The path name ends with the name of the request, for example, change_email_address. Following the path is the list of options. After options are one or more sample invocations illustrating format of the request as made with the curl command, and the format of the response.

The following two options appear on all API messages (request parameters are often referred to as ‘options’ in the guide):

  • event: the command to be executed, for example “ping”

  • id: uuid for the API call, returned in response in most cases. If id is not provided in the API message, a random id will be generated and returned in the response.

API Endpoints

API Examples & Howto

Copy a file between projects

First, save your API key in a file api.key. Then, we use the requests library to issue calls:

key = open('api.key').read().strip()
import requests as r

Copy request:

data = {
    'src_project_id': '...',
    'src_path': 'cocalc-api/api-demo.ipynb',
    'target_project_id': '...',
    'wait_until_done': False
}

req = r.post('https://cocalc.com/api/v1/copy_path_between_projects',
             auth=(key, ''),
             data=data)
res = req.json()
res

response res:

{'event': 'copy_path_between_projects_response',
 'id': '52818dfe-b580-404e-89e6-9845fac7076c',
 'copy_path_id': '65cd2079-098d-4147-bb54-12d44cebb8cb',
 'note': 'Query copy_path_status with the copy_path_id to learn if the copy operation was successful.'
}

Now, we wait a few seconds. Then, we check the status using copy_path_id:

data = {
    'copy_path_id': res['copy_path_id']
}

req = r.post('https://cocalc.com/api/v1/copy_path_status',
             auth=(key, ''),
             data=data)
res = req.json()
res

which gives

{'event': 'copy_path_status_response',
 'id': 'abc3ca91-1388-4208-bdeb-540054e5bcaf',
 'data': {'copy_path_id': 'da3a8eaf-14df-4bf8-9131-13bcb9c7e9e5',
  'time': '2020-11-03T16:20:54.222Z',
  'source_project_id': '...',
  'source_path': 'cocalc-api/api-demo.ipynb',
  'target_project_id': '...',
  'target_path': 'cocalc-api/api-demo.ipynb',
  'overwrite_newer': False,
  'delete_missing': False,
  'backup': False,
  'started': '2020-11-03T16:20:54.234Z',
  'finished': '2020-11-03T16:20:55.177Z'}
}

Note: started and finished being part of the response, signals it did work.

Embedding in an IFrame

Here are notes on integrating CoCalc in an IFrame in a web application using the CoCalc API. You should be able to create a proof of concept using the API introduction above and these notes.

  1. You need an account with an API key. You can get an API key via the UI or here using the create_account API call.

  2. You can create several accounts. If you are running the CoCalc Docker image, you probably want one account to be an admin and then have additional accounts for each actual user of your platform.

  3. You have to create at least one project. Note: The production website runs each project in their own container. This means you might want to create several projects to get proper isolation.

  4. With the API, you can copy files between projects or write to a file. It’s also possible to run arbitrary commands.

  5. To show a notebook to a user (and just the notebook) you need to do this:

    • get a fresh auth token

    • make an IFrame in your website, which points to a project and file, and ends with ?auth_token=...&fullscreen=kiosk. The parameter fullscreen=kiosk removes the UI. A full example might look like this https://cocalc.com/projects/.../files/calculate.ipynb?auth_token=...&fullscreen=kiosk&session=

IFrame communication

This is a communication channel to improve working with an embedded CoCalc instance. It gives the parent page the ability to send command-messages to CoCalc (e.g. opening a specific page, etc.) and receiving responses.

Warning

The IFrame communication might be currently broken. Please check issue #6059 for the current status.

The underlying technology is window.postMessage.

The parent page must be served using https!

Note

This is beta and only available for specific domains. Please contact us if you want to use this.

To get started, you just have to embed the main /app endpoint in an IFrame’s src like that:

Once CoCalc is ready, the loading screen shows a green banner of confirmation.

Sending messages Use postMessage on the contentWindow of CoCalc’s IFrame to send messages. E.g. if your IFrame has the id="cocalc", run cocalc = document.getElementById("cocalc").contentWindow; and then cocalc.postMessage(payload, "https://cocalc.com"). payload is the message, which is explained below.

Receiving message

  1. write a callback function like function replies(mesg) { console.log(mesg.data); }.

  2. Possibly check if mesg.origin is really CoCalc’s domain.

  3. Hook up this callback via window.addEventListener("message", replies, false);.

Messages sent to CoCalc have the following structure. The action field is mandatory.

{
  action: "[command]",
  field1: ...,
  field2: ...
}

Each message has a response, usually containing {status: "ack|done|error", ...}.

In particular, error responses have the structure {status: "error", mesg: "[error message]", ...}.

Available commands and their responses:

  • open – open a specific file in a project.

    • fields:

      • project_id – the UUID of the project

      • path – the location relative to the home directory. e.g. notebook.ipynb or subdir1/file.md.

    • responses:

      1. acknowledgement of command (project will start, file will open): { status: "ack", ... }

      2. file editor is opened and loading of content starts: { status: "done", ... }

  • closeall – this closes all open files

    • response: {status: "done", mesg: "all files are closed"}

  • status – returns a snapshot of CoCalc’s overall status. In particular during starting CoCalc, querying this for a response is useful to know when CoCalc is available and connected to the front-end servers.

    • response:

      • connection – more detailed information about the connection quality, ping time, etc.

      • open_files – mapping of project_id to a list of paths.