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.js 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.
This information is based on ffd2559e6e exported at