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.
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.
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
API key dialogue, you can create a key,
view a previously assigned key, generate a replacement key,
and delete your key entirely.
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
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
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.
- The CoCalc API tutorial illustrates API calls in Python.
- The CoCalc PostgreSQL schema definition src/smc-util/db-schema has information on tables and fields used with the API
- The API test suite src/smc-hub/test/api/ contains mocha unit tests for the API messages.
- The CoCalc message definition file src/smc-util/message.js contains the source for this guide.
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,
The path name ends with the name of the request,
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
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.
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.
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.
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.
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
A full example might look like this:
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:
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