API

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 cannnot 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 obtain a key manually, log into CoCalc and click on Settings (gear icon next to user name at upper right), and look under Account Settings. With the API key dialogue, you can create a key, view a previously assigned key, generate a replacement key, and delete your key entirely.

It is also possible to obtain an API key using a javascript-enabled automated web client. This option is useful for applications that embed CoCalc in a custom environment, for example juno.sh, the iOS application for Jupyter notebooks. Visiting the link https://cocalc.com/app?get_api_key=myapp, where “myapp” is an identifier for your application, returns a modified sign-in page with the banner “CoCalc API Key Access for Myapp”. The web client must sign in with credentials for the account in question. Response headers from a successful sign-in will include a url of the form https://authenticated/?api_key=sk_abcdefQWERTY090900000000. The client should intercept this response and capture the string after the equals sign as the API key.

Your API key carries access privileges, just like your login and password. Keep it secret. Do not share your API key with others or post it in publicly accessible forums.

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.

Using the API 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 projects. Kubernetes note: In a kubernetes setup, each project runs in a pod with specific quotas. Collaborators on a project with upgrades or an administrator can set these quotas. If you’re running several jupyter notebooks in the same project, they’re running in the same pod. Depending on your use case, you might want to create a project for each notebook.

  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: https://doc.cocalc.com/api/user_auth.html
    • append the parameter fullscreen=kiosk to remove the UI
    • make an iframe in your website, which points to a project and file, and ends with `?auth_token=...&fullscreen=kiosk`.

    A full example might look like this:

    https://cocalc.com/projects/....-....-....-..../
      files/calculate.ipynb?auth_token=......&fullscreen=kiosk&session=
    

There is work underway to improve kiosk mode. In particular to let the parent website send commands to open more than one file, close them, get status information, etc. The PR is at https://github.com/sagemathinc/cocalc/pull/3985. Once this is merged and working, the implication is that you just have to open cocalc in kiosk mode:

https://cocalc.com/app?auth_token=......&fullscreen=kiosk&session=

and wait until it is ready. Then you can control opening and closing files from your website, e.g. as a result of users clicking on certain buttons that behave just like using the top row of cocalc.


This information is based on 7f29225cba exported at 2019-10-14T06:16:47.563Z.