API v2

Introduction

New in April 2022

With API v2, the CoCalc API is being improved and expanded.

Source code for the API v2 implemention is in the CoCalc public GitHub repository under src/packages/next/pages/api/v2. Each “.ts” file under the v2 directory corresponds to an endpoint in the new API. For example, the “stop” endpoint, which allows you to stop a project, has source code at https://github.com/sagemathinc/…/api/v2/projects/stop.ts and is called with the URL https://cocalc.com/api/v2/projects/stop.

Note

For security reasons, API v2 calls must be made with the POST method. This policy supersedes any comments about the availability of GET that may appear in the source code.

Get an API Key

To get started with API v2, you will need a CoCalc account and an API key for that account. Visit the link Account - API Key under your account settings to create and view your API key. A CoCalc API key will be a text string beginning with the symbols “sk_”

API v2 Examples

stop

Use the stop endpoint to stop a CoCalc project, given its project_id. Note that this endpoint is in the v2/projects/ subdirectory. The user must be signed in and must be an owner or collaborator on the project.

x='sk_xxxxx' # your API key

# project_id of the project you want to stop
p='304506b4-262e-11ed-a279-2f22f36cbe91'

curl -sk \
  -u $x: \
  -d project_id=$p \
  https://cocalc.com/api/v2/projects/stop

### project will be stopped; normal output is a pair of braces
{}

You can learn more about the stop endpoint by viewing the source code at https://github.com/sagemathinc/…/api/v2/projects/stop.ts.

user-query

Use the user-query endpoint to get the email address and account_id for the owner of the API key. A request header is set because the query is a JSON string. The example sends output to the linux command “jq” to format the output nicely.

x='sk_xxxxx' # your API key
q='{"query":{"accounts":{"account_id":null,"email_address":null}}}'

curl -sk \
  -u $x: \
  -d $q \
  -H 'Content-Type: application/json' \
  https://cocalc.com/api/v2/user-query | jq

echo

### sample output (not from a real account):

{
  "query": {
    "accounts": {
      "account_id": "e32a26f8-262c-11ed-8a33-8358017cec89",
      "email_address": "[email protected]"
    }
  }
}

You can learn more about the user-query endpoint by viewing the source code at https://github.com/sagemathinc/…/api/v2/user-query.ts.

latex

Use the latex endpoint to compile a latex document. This endpoint converts a tex file to pdf, and stores the pdf temporarily as a blob in CoCalc’s PostgreSQL database. The tmp files used for compilation are cleaned up. You can specify a project_id in the API call, or leave that off and your most recent project gets used automatically (or a new one created). By default the compilation uses “latexmk” with certain options, but you can specify a custom command parameter to convert the tex to pdf.

x='sk_xxxxx' # your API key

# c is the latex document as a text string
c='\documentclass{article}\begin{document}\section{Main Section}Hello.\end{document}'

curl -sk \
  -u $x: \
  -d path=/tmp/d.tex \
  -d content=$c \
  https://cocalc.com/api/v2/latex | jq '.url'

echo

### sample output is a url
### browse to this link to see the compiled pdf document
"https://cocalc.com/blobs/tmp/d.pdf?uuid=36862b42-2634-11ed-889d-3b8b6aedd65b"

You can learn more about the latex endpoint by viewing the source code at https://github.com/sagemathinc/…/api/v2/latex.ts.