CoCalc - API

CoCalc API

About the 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 PUT 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, 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.

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

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 query request.
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, 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.

List of Endpoints:

change_email_address

change_password

copy_path_between_projects

copy_public_path_between_projects

create_account

create_project

create_support_ticket

delete_account

disconnect_from_project

forgot_password

get_available_upgrades

get_support_tickets

get_usernames

invite_collaborator

invite_noncloud_collaborators

public_get_directory_listing

public_get_text_file

query

read_text_file_from_project

remove_collaborator

reset_forgot_password

write_text_file_to_project

Endpoints:

/api/v1/change_email_address¶

`id`	A unique UUID for the query
`account_id`	account_id for account whose email address is changed (required)
`old_email_address`	ignored -- deprecated (default: "")
`new_email_address`	(required)
`password`	(default: "")

Given the account_id for an account, set a new email address.

Examples:

Successful change of email address.

  curl -u sk_abcdefQWERTY090900000000: \
    -d account_id=99ebde5c-58f8-4e29-b6e4-b55b8fd71a1b \
    -d password=secret_password \
    -d new_email_address=new@email.com \
    https://cocalc.com/api/v1/change_email_address
  ==> {"event":"changed_email_address",
       "id":"8f68f6c4-9851-4b88-bd65-37cb983298e3",
       "error":false}

Fails if new email address is already in use.

  curl -u sk_abcdefQWERTY090900000000: \
    -d account_id=99ebde5c-58f8-4e29-b6e4-b55b8fd71a1b \
    -d password=secret_password \
    -d new_email_address=used@email.com \
    https://cocalc.com/api/v1/change_email_address
  ==> {"event":"changed_email_address",
       "id":"4501f022-a57c-4aaf-9cd8-af0eb05ebfce",
       "error":"email_already_taken"}

Note: account_id and password must match the id of the current login.

/api/v1/change_password¶

`id`	A unique UUID for the query
`account_id`	account id of the account whose password is being changed (required)
`old_password`	(default: "")
`new_password`	must be between 6 and 64 characters in length (required)

Given account_id and old password for an account, set a new password.

Example:

  curl -u sk_abcdefQWERTY090900000000: \
    -d account_id=... \
    -d old_password=... \
    -d new_password=... \
    https://cocalc.com/api/v1/change_password
  ==> {"event":"changed_password","id":"41ff89c3-348e-4361-ad1d-372b55e1544a"}

/api/v1/copy_path_between_projects¶

`id`	A unique UUID for the query
`src_project_id`	id of source project (required)
`src_path`	relative path of directory or file in the source project (required)
`target_project_id`	id of target project (required)
`target_path`	defaults to src_path
`overwrite_newer`	overwrite newer versions of file at destination (destructive) (default: false)
`delete_missing`	delete files in dest that are missing from source (destructive) (default: false)
`backup`	make ~ backup files instead of overwriting changed files (default: false)
`timeout`	seconds to wait before reporting "error" (though copy could still succeed)
`exclude_history`	if true, exclude all files of the form *.sage-history (default: false)

Copy a file or directory from one project to another. User must be owner or collaborator on both projects.

Note: the timeout option is passed to a call to the rsync command. If no data is transferred for the specified number of seconds, then the copy terminates. The default is 0, which means no timeout.

Relative paths (paths not beginning with '/') are relative to the user's home directory in source and target projects.

Example:

Copy file A/doc.txt from source project to target project. Folder A will be created in target project if it does not exist already.

  curl -u sk_abcdefQWERTY090900000000: \
    -d src_project_id=e49e86aa-192f-410b-8269-4b89fd934fba \
    -d src_path=A/doc.txt \
    -d target_project_id=2aae4347-214d-4fd1-809c-b327150442d8 \
    https://cocalc.com/api/v1/copy_path_between_projects
  ==> {"event":"success",
       "id":"45d851ac-5ea0-4aea-9997-99a06c054a60"}

/api/v1/copy_public_path_between_projects¶

`id`	A unique UUID for the query
`src_project_id`	id of source project (required)
`src_path`	relative path of directory or file in the source project (required)
`target_project_id`	id of target project (required)
`target_path`	defaults to src_path
`overwrite_newer`	overwrite newer versions of file at destination (destructive) (default: false)
`delete_missing`	delete files in dest that are missing from source (destructive) (default: false)
`backup`	make ~ backup files instead of overwriting changed files (default: false)
`timeout`	how long to wait for the copy to complete before reporting error (though it could still succeed)
`exclude_history`	if true, exclude all files of the form *.sage-history (default: false)

Copy a file or directory from public project to a project for which the user is owner or collaborator.

Example:

Copy public file PUBLIC/doc.txt from source project to private file A/sample.txt in target project.

  curl -u sk_abcdefQWERTY090900000000: \
    -d src_project_id=e49e86aa-192f-410b-8269-4b89fd934fba \
    -d src_path=PUBLIC/doc.txt \
    -d target_project_id=2aae4347-214d-4fd1-809c-b327150442d8 \
    -d target_path=A/sample.txt \
    https://cocalc.com/api/v1/copy_public_path_between_projects
  ==> {"event":"success",
       "id":"45d851ac-5ea0-4aea-9997-99a06c054a60"}

/api/v1/create_account¶

`id`	A unique UUID for the query
`first_name`	undefined (required)
`last_name`	undefined (required)
`email_address`	undefined (required)
`password`	must be between 6 and 64 characters in length (required)
`agreed_to_terms`	must be true for request to succeed (required)
`utm`	UTM parameters
`referrer`	Referrer URL
`token`	account creation token - see src/dev/docker/README.md
`get_api_key`	if set to anything truth-ish, will create (if needed) and return api key with signed_in message
`usage_intent`	response to Cocalc usage intent at sign up

Examples:

Create a new account:

  curl -u sk_abcdefQWERTY090900000000: \
    -d first_name=John00 \
    -d last_name=Doe00 \
    -d email_address=jd@some_email \
    -d password=xyzabc09090 \
    -d agreed_to_terms=true https://cocalc.com/api/v1/create_account

Option agreed_to_terms must be present and specified as true. Account creation fails if there is already an account using the given email address, if email_address is improperly formatted, and if password is fewer than 6 or more than 64 characters.

Attempting to create the same account a second time results in an error:

  curl -u sk_abcdefQWERTY090900000000: \
    -d first_name=John00 \
    -d last_name=Doe00 \
    -d email_address=jd@some_email \
    -d password=xyzabc09090 \
    -d agreed_to_terms=true https://cocalc.com/api/v1/create_account
  ==> {"event":"account_creation_failed",
       "id":"2332be03-aa7d-49a6-933a-cd9824b7331a",
       "reason":{"email_address":"This e-mail address is already taken."}}

/api/v1/create_project¶

`id`	A unique UUID for the query
`title`	project title (default: "")
`description`	project description (default: "")
`start`	start running the moment the project is created -- uses more resources, but possibly better user experience (default: false)

Example:

  curl -u sk_abcdefQWERTY090900000000: \
    -d title='MY NEW PROJECT' \
    -d description='sample project' \
    https://cocalc.com/api/v1/create_project
  == > {"event":"project_created",
        "id":"0b4df293-d518-45d0-8a3c-4281e501b85e",
        "project_id":"07897899-6bbb-4fbc-80a7-3586c43348d1"}

/api/v1/create_support_ticket¶

`id`	A unique UUID for the query
`username`	name on the ticket
`email_address`	if there is no email_address in the account, there cannot be a ticket! (required)
`subject`	like an email subject (required)
`body`	html or md formatted text (required)
`tags`	a list of tags, like ['member']
`account_id`	account_id for the ticket
`location`	from the URL, to know what the requester is talking about
`info`	additional data dict, like browser/OS

Open a CoCalc support ticket.

Notes:

If account_id is not provided, the ticket will be created, but ticket info will not be returned by get_support_tickets.
If username is not provided, email_address is used for the name on the ticket.
location is used to provide a path to a specific project or file, for example

/project/a17037cb-a083-4519-b3c1-38512af603a6/files/notebook.ipynb`

If present, the location string will be expanded to a complete URL and appended to the body of the ticket.

The info dict can be used to provide additional metadata, for example

{"user_agent":"Mozilla/5.0 ... Chrome/58.0.3029.96 Safari/537.36"}

If the ticket concerns a CoCalc course, the project id of the course can be included in the info dict, for example,

{"course":"0c7ae00c-ea43-4981-b454-90d4a8b1ac47"}

In that case, the course project_id will be expanded to a URL and appended to the body of the ticket.

If tags or info are provided, options must be sent as a JSON object.

Example:

  curl -u sk_abcdefQWERTY090900000000: -H "Content-Type: application/json" \
    -d '{"email_address":"jd@some_email", \
         "subject":"package xyz", \
         "account_id":"291f43c1-deae-431c-b763-712307fa6859", \
         "body":"please install package xyz for use with Python3", \
         "tags":["member"], \
         "location":"/projects/0010abe1-9283-4b42-b403-fa4fc1e3be57/worksheet.sagews", \
         "info":{"user_agent":"Mozilla/5.0","course":"cc8f1243-d573-4562-9aab-c15a3872d683"}}' \
    https://cocalc.com/api/v1/create_support_ticket
  ==> {"event":"support_ticket_url",
       "id":"abd649bf-ea2d-4952-b925-e44c6903945e",
       "url":"https://sagemathcloud.zendesk.com/requests/0123"}

/api/v1/delete_account¶

`id`	A unique UUID for the query
`account_id`	account_id for account to be deleted (required)

Example:

Delete an existing account:

  curl -u sk_abcdefQWERTY090900000000: \
    -d account_id=99ebde5c-58f8-4e29-b6e4-b55b8fd71a1b \
    https://cocalc.com/api/v1/delete_account
  ==> {"event":"account_deleted","id":"9e8b68ac-08e8-432a-a853-398042fae8c9"}

Event account_deleted is also returned if the account was already deleted before the API call, or if the account never existed.

After successful delete_account, the owner of the deleted account will not be able to login, but will still be listed as collaborator or owner on projects which the user collaborated on or owned respectively.

/api/v1/disconnect_from_project¶

`id`	A unique UUID for the query
`project_id`	id of project to disconnect from (required)

Disconnect the hub that gets this message from the project. This is used entirely for internal debugging and development.

/api/v1/forgot_password¶

`id`	A unique UUID for the query
`email_address`	email address for account requesting password reset (required)

Given the email address of an existing account, send password reset email.

Example:

  curl -u sk_abcdefQWERTY090900000000: \
    -d email_address=... \
    https://cocalc.com/api/v1/forgot_password
  ==> {"event":"forgot_password_response",
       "id":"26ed294b-922b-47e1-8f3f-1e54d8c8e558",
       "error":false}

/api/v1/get_available_upgrades¶

`id`	A unique UUID for the query

This request returns information on project upgrdes for the user whose API key appears in the request. Two objects are returned, total upgrades and available upgrades.

See https://github.com/sagemathinc/cocalc/blob/master/src/smc-util/upgrade-spec.js for units

Example:

  curl -X POST -u sk_abcdefQWERTY090900000000: https://cocalc.com/api/v1/get_available_upgrades
  ==>
  {"id":"57fcfd71-b50f-44ef-ba66-1e37cac858ef",
   "event":"available_upgrades",
   "total":{
     "cores":10,
     "cpu_shares":2048,
     "disk_quota":200000,
     "member_host":80,
     "memory":120000,
     "memory_request":8000,
     "mintime":3456000,
     "network":400},
     "excess":{},
   "available":{
     "cores":6,
     "cpu_shares":512,
     "disk_quota":131000,
     "member_host":51,
     "memory":94000,
     "memory_request":8000,
     "mintime":1733400,
     "network":372}}

/api/v1/get_support_tickets¶

`id`	A unique UUID for the query

Fetch information on support tickets for the user making the request. See the example for details on what is returned.

Notes:

There may be a delay of several minutes between the time a support ticket is created with a given account_id and the time that ticket is available to the account owner via get_support_tickets.
Field account_id is not required because it is implicit from the request.
Archived tickets are not returned.

Example:

curl -u sk_abcdefQWERTY090900000000:  -X POST \
    https://cocalc.com/api/v1/get_support_tickets
  ==> {"event":"support_tickets",
       "id":"58bfd6f4-fd63-4602-82b8-676d92f8b0b8",
       "tickets":[{"id":1234,
                   "subject":"package xyz",
                   "description":"package xyz\n\nhttps://cocalc.com/projects/0010abe1-9283-4b42-b403-fa4fc1e3be57/worksheet.sagews\n\nCourse: https://cocalc.com/projects/cc8f1243-d573-4562-9aab-c15a3872d683",
                   "created_at":"2017-07-05T14:28:38Z",
                   "updated_at":"2017-07-05T14:29:29Z",
                   "status":"open",
                   "url":"https://sagemathcloud.zendesk.com/requests/0123"}]}

/api/v1/get_usernames¶

`id`	A unique UUID for the query
`account_ids`	list of account_ids (required)

Get first and last names for a list of account ids.

Note: Options for the get_usernames API message must be sent as JSON object.

Example:

  curl -u sk_abcdefQWERTY090900000000: -H "Content-Type: application/json" \
    -d '{"account_ids":["cc3cb7f1-14f6-4a18-a803-5034af8c0004","9b896055-920a-413c-9172-dfb4007a8e7f"]}' \
    https://cocalc.com/api/v1/get_usernames
  ==>  {"event":"usernames",
        "id":"32b485a8-f214-4fda-a622-4dbfe0db2b9c",
        "usernames": {
           "cc3cb7f1-14f6-4a18-a803-5034af8c0004":{"first_name":"John","last_name":"Smith"},
           "9b896055-920a-413c-9172-dfb4007a8e7f":{"first_name":"Jane","last_name":"Doe"}}}

/api/v1/invite_collaborator¶

`id`	A unique UUID for the query
`project_id`	project_id of project into which user is invited (required)
`account_id`	account_id of invited user (required)
`title`	Title of the project
`link2proj`	The full URL link to the project
`replyto`	Email address of user who is inviting someone
`replyto_name`	Name of user who is inviting someone
`email`	Body of email user is sending (plain text or HTML)
`subject`	Subject line of invitiation email

Invite a user who already has a CoCalc account to become a collaborator on a project. You must be owner or collaborator on the target project.

Example:

  curl -u sk_abcdefQWERTY090900000000: \
    -d account_id=99ebde5c-58f8-4e29-b6e4-b55b8fd71a1b \
    -d project_id=18955da4-4bfa-4afa-910c-7f2358c05eb8 \
    https://cocalc.com/api/v1/invite_collaborator
  ==> {"event":"success",
       "id":"e80fd64d-fd7e-4cbc-981c-c0e8c843deec"}

/api/v1/invite_noncloud_collaborators¶

`id`	A unique UUID for the query
`project_id`	project_id of project into which users are invited (required)
`to`	comma- or semicolon-delimited string of email addresses (required)
`email`	body of the email to be sent, may include HTML markup (required)
`title`	string that will be used for project title in the email (required)
`link2proj`	URL for the target project (required)
`replyto`	Reply-To email address
`replyto_name`	Reply-To name
`subject`	email Subject

Invite users who do not already have a CoCalc account to join a project. An invitation email is sent to each user in the to option. Invitation is not sent if there is already a CoCalc account with the given email address. You must be owner or collaborator on the target project.

Limitations:

Total length of the request message must be less than or equal to 1024 characters.
Length of each email address must be less than 128 characters.

Example:

  curl -u sk_abcdefQWERTY090900000000: \
    -d project_id=18955da4-4bfa-4afa-910c-7f2358c05eb8 \
    -d to=someone@m.local \
    -d 'email=Please sign up and join this project.' \
    -d 'title=Class Project' \
    -d link2proj=https://cocalc.com/projects/18955da4-4bfa-4afa-910c-7f2358c05eb8 \
    https://cocalc.com/api/v1/invite_noncloud_collaborators
  ==>  {"event":"invite_noncloud_collaborators_resp",
        "id":"39d7203d-89b1-4145-8a7a-59e41d5682a3",
        "mesg":"Invited someone@m.local to collaborate on a project."}

Email sent by the previous example:

To: someone@m.local
From: CoCalc <invites@sagemath.com
Reply-To: help@sagemath.com
Subject: CoCalc Invitation

Please sign up and join this project.<br/><br/>\n<b>
To accept the invitation, please sign up at\n
<a href='https://cocalc.com'>https://cocalc.com</a>\n
using exactly the email address 'someone@m.local'.\n
Then go to <a href='https://cocalc.com/projects/18955da4-4bfa-4afa-910c-7f2358c05eb8'>
the project 'Team Project'</a>.</b><br/>

/api/v1/log_client_error¶

`id`	A unique UUID for the query
`error`	error string (required)

Log an error so that CoCalc support can look at it.

In the following example, an explicit message id is provided for future reference.

  curl -u sk_abcdefQWERTY090900000000: \
    -d id=34a424dc-1731-4b31-ba3d-fc8a484980d9 \
    -d "error=cannot load library xyz" \
    https://cocalc.com/api/v1/log_client_error
  ==> {"event":"success",
       "id":"34a424dc-1731-4b31-ba3d-fc8a484980d9"}

Note: the above API call will create the following record in the client_error_log database table. This table is not readable via the API and is intended for use by CoCalc support only:

[{"id":"34a424dc-1731-4b31-ba3d-fc8a484980d9",
  "event":"error",
  "error":"cannot load library xyz",
  "account_id":"1c87a139-9e13-4cdd-b02c-e7d41dcfe921",
  "time":"2017-07-06T02:32:41.176Z"}]

/api/v1/metrics¶

metrics

object containing the metrics (required)

/api/v1/ping¶

`id`	A unique UUID for the query

Test API connection, return time as ISO string when server responds to ping.

Security key may be blank.

Examples:

Omitting request id:

  curl -X POST -u sk_abcdefQWERTY090900000000: https://cocalc.com/api/v1/ping
  ==> {"event":"pong","id":"c74afb40-d89b-430f-836a-1d889484c794","now":"2017-05-24T13:29:11.742Z"}

Omitting request id and using blank security key:

  curl -X POST -u : https://cocalc.com/api/v1/ping
  ==>  {"event":"pong","id":"d90f529b-e026-4a60-8131-6ce8b6d4adc8","now":"2017-11-05T21:10:46.585Z"}

Using uuid shell command to create a request id:

  uuid
  ==> 553f2815-1508-416d-8e69-2dde5af3aed8
  curl -u sk_abcdefQWERTY090900000000: https://cocalc.com/api/v1/ping -d id=553f2815-1508-416d-8e69-2dde5af3aed8
  ==> {"event":"pong","id":"553f2815-1508-416d-8e69-2dde5af3aed8","now":"2017-05-24T13:47:21.312Z"}

Using JSON format to provide request id:

  curl -u sk_abcdefQWERTY090900000000: -H "Content-Type: application/json" \
    -d '{"id":"8ec4ac73-2595-42d2-ad47-0b9641043b46"}' https://cocalc.com/api/v1/ping
  ==> {"event":"pong","id":"8ec4ac73-2595-42d2-ad47-0b9641043b46","now":"2017-05-24T17:15:59.288Z"}

/api/v1/project_exec¶

`id`	A unique UUID for the query
`project_id`	id of project where command is to be executed (required)
`path`	path of working directory for the command (default: "")
`command`	command to be executed (required)
`args`	command line options for the command (default: [])
`timeout`	maximum allowed time, in seconds (default: 10)
`aggregate`	If there are multiple attempts to run the given command with the same time, they are all aggregated and run only one time by the project; if requests comes in with a greater value (time, sequence number, etc.), they all run in another group after the first one finishes. Meant for compiling code on save.
`max_output`	maximum number of characters in the output
`bash`	if true, args are ignored and command is run as a bash command (default: false)
`err_on_exit`	if exit code is nonzero send error return message instead of the usual output (default: true)

Execute a shell command in a given project.

Examples:

Simple built-in shell command.

  curl -u sk_abcdefQWERTY090900000000: \
    -d command=pwd \
    -d project_id=e49e86aa-192f-410b-8269-4b89fd934fba \
    https://cocalc.com/api/v1/project_exec
  ==> {"event":"project_exec_output",
       "id":"8a78a37d-b2fb-4e29-94ae-d66acdeac949",
       "stdout":"/projects/e49e86aa-192f-410b-8269-4b89fd934fba\n","stderr":"","exit_code":0}

Shell command with different working directory.

  curl -u sk_abcdefQWERTY090900000000: \
    -d command=pwd \
    -d path=Private \
    -d project_id=e49e86aa-192f-410b-8269-4b89fd934fba \
    https://cocalc.com/api/v1/project_exec
  ==> {"event":"project_exec_output",
       "id":"8a78a37d-b2fb-4e29-94ae-d66acdeac949",
       "stdout":"/projects/e49e86aa-192f-410b-8269-4b89fd934fba/Private\n","stderr":"","exit_code":0}

Command line arguments specified by 'args' option. Note JSON format for request parameters.

  curl -u sk_abcdefQWERTY090900000000: \
    -H 'Content-Type: application/json' \
    -d '{"command":"echo","args":["xyz","abc"],"project_id":"e49e86aa-192f-410b-8269-4b89fd934fba"}' \
    https://cocalc.com/api/v1/project_exec
  ==> {"event":"project_exec_output",
       "id":"39289ba7-0333-48ad-984e-b25c8b8ffa0e",
       "stdout":"xyz abc\n",
       "stderr":"",
       "exit_code":0}

Limiting output of the command to 3 characters.

  curl -u sk_abcdefQWERTY090900000000: \
    -H 'Content-Type: application/json' \
    -d '{"command":"echo","args":["xyz","abc"],"max_output":3,"project_id":"e49e86aa-192f-410b-8269-4b89fd934fba"}' \
    https://cocalc.com/api/v1/project_exec
  ==> {"event":"project_exec_output",
       "id":"02feab6c-a743-411a-afca-8a23b58988a9",
       "stdout":"xyz (truncated at 3 characters)",
       "stderr":"",
       "exit_code":0}

Setting a timeout for the command.

  curl -u sk_abcdefQWERTY090900000000: \
    -H 'Content-Type: application/json' \
    -d '{"command":"sleep 5","timeout":2,"project_id":"e49e86aa-192f-410b-8269-4b89fd934fba"}' \
    https://cocalc.com/api/v1/project_exec
  ==>  {"event":"error",
        "id":"86fea3f0-6a90-495b-a541-9c14a25fbe58",
        "error":"Error executing command 'sleep 5' with args '' -- killed command 'bash /tmp/f-11757-1677-8ei2z0.t4fex0qkt9', , "}

Notes:

Argument command may invoke an executable file or a built-in shell command. It may include a path and command line arguments.
If option args is provided, options must be sent as a JSON object.
Argument path is optional. When provided, path is relative to home directory in target project and specifies the working directory in which the command will be run.

/api/v1/public_get_directory_listing¶

`id`	A unique UUID for the query
`project_id`	id of project containing public file to be read (required)
`path`	path of directory in target project (required)
`hidden`	show hidden files (default: false)
`time`	sort by timestamp, with newest first (default: false)
`start`	(default: 0)
`limit`	(default: -1)

Given a project id and relative path (i.e. not beginning with a slash), list all public files and subdirectories under that path. Path is required, but may be the empty string, in which case a public listing of the home directory in the target project is returned.

Examples:

Get public directory listing. Directory "Public" is shared and contains one file "hello.txt" and one subdirectory "p2".

Security key may be blank.

  curl -u : \
    -d path=Public \
    -d project_id=9a19cca3-c53d-4c7c-8c0f-e166aada7bb6 \
    https://cocalc.com/api/v1/public_get_directory_listing
  ==> {"event":"public_directory_listing",
       "id":"3e576b3b-b673-4d5c-9bce-780883f92958",
       "result":{"files":[{"size":41,"name":"hello.txt","mtime":1496430932},
                          {"isdir":true,"name":"p2","mtime":1496461616}]}

/api/v1/public_get_text_file¶

`id`	A unique UUID for the query
`project_id`	id of project containing public file to be read (required)
`path`	path to file to be read in target project (required)

Read a public (shared) text file in the project whose id is supplied. User does not need to be owner or collaborator in the target project and does not need to be logged into CoCalc. Argument path is relative to home directory in target project.

Security key may be blank.

Examples

Read a public file.

  curl -u : \
    -d project_id=e49e86aa-192f-410b-8269-4b89fd934fba \
    -d path=Public/hello.txt
    https://cocalc.com/api/v1/public_get_text_file
  ==> {"event":"public_text_file_contents",
       "id":"2d0e2faa-893a-44c1-9f64-59203bbbb017",
       "data":"hello world\nToday is Friday\n"}

Attempt to read a file which is not public.

  curl -u sk_abcdefQWERTY090900000000: \
    -d project_id=e49e86aa-192f-410b-8269-4b89fd934fba \
    -d path=Private/hello.txt
    https://cocalc.com/api/v1/public_get_text_file
  ==> {"event":"error","id":"0288b7d0-dda9-4895-87ba-aa71929b2bfb",
       "error":"path 'Private/hello.txt' of project with id 'e49e86aa-192f-410b-8269-4b89fd934fba' is not public"}+

/api/v1/query¶

`id`	A unique UUID for the query
`query`	The actual query (required)
`changes`
`multi_response`	(default: false)
`options`

This queries directly the database (sort of Facebook's GraphQL) Options for the 'query' API message must be sent as JSON object. A query is either get (read from database), or set (write to database). A query is get if any query keys are null, otherwise the query is set.

Examples of get query:

Get title and description for a project, given the project id.

  curl -u sk_abcdefQWERTY090900000000: -H "Content-Type: application/json" \
    -d '{"query":{"projects":{"project_id":"29163de6-b5b0-496f-b75d-24be9aa2aa1d","title":null,"description":null}}}' \
    https://cocalc.com/api/v1/query
  ==> {"event":"query",
       "id":"8ec4ac73-2595-42d2-ad47-0b9641043b46",
       "query":{"projects":{"project_id":"29163de6-b5b0-496f-b75d-24be9aa2aa1d",
                            "title":"MY NEW PROJECT 2",
                            "description":"desc 2"}},
       "multi_response":false}

Get info on all projects for the account whose security key is provided. The information returned may be any of the api-accessible fields in the projects table. These fields are listed in CoCalc source file src/smc-util/db-schema.js, under schema.projects.user_query. In this example, project name and description are returned.

Note: to get info only on projects active in the past 3 weeks, use projects instead of projects_all in the query.

  curl -u sk_abcdefQWERTY090900000000: -H "Content-Type: application/json" \
    -d '{"query":{"projects_all":[{"project_id":null,"title":null,"description":null}]}}' \
    https://cocalc.com/api/v1/query
  ==> {"event":"query",
       "id":"8ec4ac73-2595-42d2-ad47-0b9641043b46",
       "multi_response": False,
       "query": {"projects_all": [{"description": "Synthetic Monitoring",
                         "project_id": "1fa1626e-ce25-4871-9b0e-19191cd03325",
                         "title": "SYNTHMON"},
                        {"description": "No Description",
                         "project_id": "639a6b2e-7499-41b5-ac1f-1701809699a7",
                         "title": "TESTPROJECT 99"}]}}

Get project id, given title and description.

  curl -u sk_abcdefQWERTY090900000000: -H "Content-Type: application/json" \
    -d '{"query":{"projects":{"project_id":null,"title":"MY NEW PROJECT 2","description":"desc 2"}}}' \
    https://cocalc.com/api/v1/query
  ==> {"event":"query",
       "query":{"projects":{"project_id":"29163de6-b5b0-496f-b75d-24be9aa2aa1d",
                            "title":"MY NEW PROJECT 2",
                            "description":"desc 2"}},
       "multi_response":false,
       "id":"2be22e08-f00c-4128-b112-fa8581c2d584"}

Get users, given the project id.

  curl -u sk_abcdefQWERTY090900000000: \
    -H "Content-Type: application/json" \
    -d '{"query":{"projects":{"project_id":"29163de6-b5b0-496f-b75d-24be9aa2aa1d","users":null}}}' \
    https://cocalc.com/api/v1/query
  ==> {"event":"query",
       "query":{"projects":{"project_id":"29163de6-b5b0-496f-b75d-24be9aa2aa1d",
                            "users":{"6c28c5f4-3235-46be-b025-166b4dcaac7e":{"group":"owner"},
                                     "111634c0-7048-41e7-b2d0-f87129fd409e":{"group":"collaborator"}}}},
       "multi_response":false,
       "id":"9dd3ef3f-002b-4893-b31f-ff51440c855f"}

Show project upgrades. Like the preceding example, this is a query to get users. In this example, there are no collaborators, but upgrades have been applied to the selected project. Upgrades do not show if none are applied.

The project shows the following upgrades:

cpu cores: 1
memory: 3000 MB
idle timeout: 24 hours (86400 seconds)
internet access: true
cpu shares: 3 (stored in database as 768 = 3 * 256)
disk space: 27000 MB
member hosting: true

  curl -u sk_abcdefQWERTY090900000000: \
    -H "Content-Type: application/json" \
    -d '{"query":{"projects":{"project_id":"29163de6-b5b0-496f-b75d-24be9aa2aa1d","users":null}}}' \
    https://cocalc.com/api/v1/query
  ==> {"event":"query",
       "query":{"projects":{"project_id":"29163de6-b5b0-496f-b75d-24be9aa2aa1d",
                            "users":{"6c28c5f4-3235-46be-b025-166b4dcaac7e":{
                                         "group":"owner",
                                         "upgrades":{"cores":1,
                                                     "memory":3000,
                                                     "mintime":86400,
                                                     "network":1,
                                                     "cpu_shares":768,
                                                     "disk_quota":27000,
                                                     "member_host":1}}}}},
       "multi_response":false,
       "id":"9dd3ef3f-002b-4893-b31f-ff51440c855f"}

Get editor settings for the present user.

  curl -u sk_abcdefQWERTY090900000000: \
    -H "Content-Type: application/json" \
    -d '{"query":{"accounts":{"account_id":"29163de6-b5b0-496f-b75d-24be9aa2aa1d","editor_settings":null}}}' \
    https://cocalc.com/api/v1/query
  ==> {"event":"query",
       "multi_response":false,
       "id":"9dd3ef3f-002b-4893-b31f-ff51440c855f",
       "query": {"accounts": {"account_id": "29163de6-b5b0-496f-b75d-24be9aa2aa1d",
                              "editor_settings": {"auto_close_brackets": True,
                                                  "auto_close_xml_tags": True,
                                                  "bindings": "standard",
                                                  "code_folding": True,
                                                  "electric_chars": True,
                                                  "extra_button_bar": True,
                                                  "first_line_number": 1,
                                                  "indent_unit": 4,
                                                  "jupyter_classic": False,
                                                  "line_numbers": True,
                                                  "line_wrapping": True,
                                                  "match_brackets": True,
                                                  "match_xml_tags": True,
                                                  "multiple_cursors": True,
                                                  "show_trailing_whitespace": True,
                                                  "smart_indent": True,
                                                  "spaces_instead_of_tabs": True,
                                                  "strip_trailing_whitespace": False,
                                                  "tab_size": 4,
                                                  "theme": "default",
                                                  "track_revisions": True,
                                                  "undo_depth": 300}}}}

Examples of set query.

Set title and description for a project, given the project id.

  curl -u sk_abcdefQWERTY090900000000: \
    -H "Content-Type: application/json" \
    -d '{"query":{"projects":{"project_id":"29163de6-b5b0-496f-b75d-24be9aa2aa1d", \
                              "title":"REVISED TITLE", \
                              "description":"REVISED DESC"}}}' \
    https://cocalc.com/api/v1/query
    ==> {"event":"query",
         "query":{},
         "multi_response":false,
         "id":"ad7d6b17-f5a9-4c5c-abc3-3823b1e1773f"}

Make a path public (publish a file).

  curl -u sk_abcdefQWERTY090900000000: \
    -H "Content-Type: application/json" \
    -d '{"query":{"public_paths":{"project_id":"29163de6-b5b0-496f-b75d-24be9aa2aa1d", \
                                  "path":"myfile.txt", \
                                  "description":"a shared text file"}}}' \
    https://cocalc.com/api/v1/query
    ==> {"event":"query",
         "query":{},
         "multi_response":false,
         "id":"ad7d6b17-f5a9-4c5c-abc3-3823b1e1773f"}

Add an upgrade to a project. In the "get" example above showing project upgrades, change cpu upgrades from 3 to 4. The users object is returned as read, with cpu_shares increased to 1024 = 4 * 256. It is not necessary to specify the entire upgrades object if you are only setting the cpu_shares attribute because changes are merged in.

  curl -u sk_abcdefQWERTY090900000000: \
    -H "Content-Type: application/json" \
    -d '{"query":{"projects":{"project_id":"29163de6-b5b0-496f-b75d-24be9aa2aa1d", \
                              "users":{"6c28c5f4-3235-46be-b025-166b4dcaac7e":{ \
                                           "upgrades": {"cpu_shares":1024}}}}}}' \
    https://cocalc.com/api/v1/query
    ==> {"event":"query",
         "query":{},
         "multi_response":false,
         "id":"ec822d6f-f9fe-443d-9845-9cd5f68bac20"}

Set present user to open Jupyter notebooks in "CoCalc Jupyter Notebook" as opposed to "Classical Notebook". This change not usually needed, because accounts default to "CoCalc Jupyter Notebook".

It is not necessary to specify the entire editor_settings object if you are only setting the jupyter_classic attribute because changes are merged in.

  curl -u sk_abcdefQWERTY090900000000: \
    -H "Content-Type: application/json" \
    -d '{"query":{"accounts":{"account_id":"29163de6-b5b0-496f-b75d-24be9aa2aa1d","editor_settings":{"jupyter_classic":false}}}}' \
    https://cocalc.com/api/v1/query
  ==> {"event":"query",
       "multi_response":false,
       "id":"9dd3ef3f-002b-4893-b31f-ff51440c855f",
       "query": {}}

NOTE: Information on which fields are gettable and settable in the database tables via API message is in file 'db-schema.js', in CoCalc sources on GitHub at https://github.com/sagemathinc/cocalc/blob/master/src/smc-util/db-schema.js

Within file 'db-schema.js':

for project fields you can get, see the definition of schema.projects.user_query.get.fields
for project fields you can set, see the definition of schema.projects.user_query.set.fields
for user account fields you can get, see the definition of schema.accounts.user_query.get.fields
for user account fields you can set, see the definition of schema.accounts.user_query.set.fields

/api/v1/read_text_file_from_project¶

`id`	A unique UUID for the query
`project_id`	id of project containing file to be read (required)
`path`	path to file to be read in target project (required)

Read a text file in the project whose id is supplied. User must be owner or collaborator in the target project. Argument 'path' is relative to home directory in target project. Unix user in the target project must have permissions to read file and containing directories if they do not already exist.

Example:

Read a text file.

  curl -u sk_abcdefQWERTY090900000000: \
    -d project_id=e49e86aa-192f-410b-8269-4b89fd934fba \
    -d path=Assignments/A1/h1.txt \
    https://cocalc.com/api/v1/read_text_file_from_project
  ==> {"event":"text_file_read_from_project",
       "id":"481d6055-5609-450f-a229-480e518b2f84",
       "content":"hello"}

/api/v1/remove_collaborator¶

`id`	A unique UUID for the query
`project_id`	project_id of project from which user is removed (required)
`account_id`	account_id of removed user (required)

Remove a user from a CoCalc project. You must be owner or collaborator on the target project. You cannot remove the project owner.

Example:

  curl -u sk_abcdefQWERTY090900000000: \
    -d account_id=99ebde5c-58f8-4e29-b6e4-b55b8fd71a1b \
    -d project_id=18955da4-4bfa-4afa-910c-7f2358c05eb8 \
    https://cocalc.com/api/v1/remove_collaborator
  ==> {"event":"success",
       "id":"e80fd64d-fd7e-4cbc-981c-c0e8c843deec"}

/api/v1/reset_forgot_password¶

`id`	A unique UUID for the query
`reset_code`	id code that was sent in a password reset email (required)
`new_password`	must be between 6 and 64 characters in length (required)

Reset password, given reset code.

Example:

  curl -u sk_abcdefQWERTY090900000000: \
    -d reset_code=35a0eea6-370a-45c3-ab2f-3210df68748f \
    -d new_password=qjqhddfsfj \
    https://cocalc.com/api/v1/reset_forgot_password
  ==> {"event":"reset_forgot_password_response","id":"85bd6027-644d-4859-9e17-5e835bd47570","error":false}

/api/v1/start_metrics¶

interval_s

tells client that it should submit metrics to the hub every interval_s seconds (required)

/api/v1/touch_project¶

`id`	A unique UUID for the query
`project_id`	id of project to touch (required)

Mark this project as being actively used by the user sending this message. This keeps the project from idle timing out, among other things.

/api/v1/unlink_passport¶

`strategy`	passport strategy (required)
`id`	numeric id for user and passport strategy (required)

Unlink a passport auth for the account.

Strategies are defined in the database and may be viewed at /auth/strategies.

Example:

Get passport id for some strategy for current user.

  curl -u sk_abcdefQWERTY090900000000: \
    -H "Content-Type: application/json" \
    -d '{"query":{"accounts":{"account_id":"e6993694-820d-4f78-bcc9-10a8e336a88d","passports":null}}}' \
    https://cocalc.com/api/v1/query
  ==> {"query":{"accounts":{"account_id":"e6993694-820d-4f78-bcc9-10a8e336a88d",
                            "passports":{"facebook-14159265358":{"id":"14159265358",...}}}},
       "multi_response":false,
       "event":"query",
       "id":"a2554ec8-665b-495b-b0e2-8e248b54eb94"}

Unlink passport for that strategy and id.

  curl -u sk_abcdefQWERTY090900000000: \
    -d strategy=facebook \
    -d id=14159265358 \
    https://cocalc.com/api/v1/unlink_passport
  ==> {"event":"success",
       "id":"14159265358"}

Note that success is returned regardless of whether or not passport was linked for the given strategy and id before issuing the API command.

/api/v1/user_auth¶

`id`	A unique UUID for the query
`account_id`	account_id for account to get an auth token for (required)
`password`	password for account to get token for (required)

Example:

Obtain a temporary authentication token for an account, which is a 24 character string. Tokens last for 12 hours. You can only obtain an auth token for accounts that have a password.

  curl -u sk_abcdefQWERTY090900000000: \
    -d account_id=99ebde5c-58f8-4e29-b6e4-b55b8fd71a1b \
    -d password=secret_password \
    https://cocalc.com/api/v1/user_auth
  ==> {"event":"user_auth_token","id":"9e8b68ac-08e8-432a-a853-398042fae8c9","auth_token":"BQokikJOvBiI2HlWgH4olfQ2"}

You can now use the auth token to craft a URL like this:

https://cocalc.com/app?auth_token=BQokikJOvBiI2HlWgH4olfQ2

and provide that to a user. When they visit that URL, they will be temporarily signed in as that user.

/api/v1/user_search¶

`id`	A unique UUID for the query
`query`	comma separated list of email addresses or strings such as 'foo bar' (required)
`admin`	if true and user is an admin, includes email addresses in result, and does more permissive search (default: false)
`active`	only include users active for this interval of time (default: "6 months")
`limit`	maximum number of results returned (default: 20)

There are two possible item types in the query list: email addresses and strings that are not email addresses. An email query item will return account id, first name, last name, and email address for the unique account with that email address, if there is one. A string query item will return account id, first name, and last name for all matching accounts.

We do not reveal email addresses of users queried by name.

String query matches first and last names that start with the given string. If a string query item consists of two strings separated by space, the search will return accounts in which the first name begins with one of the two strings and the last name begins with the other. String and email queries may be mixed in the list for a single user_search call. Searches are case-insensitive.

Security key may be blank.

Note: there is a hard limit of 50 returned items in the results.

Examples:

Search for account by email.

  curl -u : \
    -d query=jd@m.local \
    https://cocalc.com/api/v1/user_search
  ==> {"event":"user_search_results",
       "id":"3818fa50-b892-4167-b9d9-d22d521b36af",
       "results":[{"account_id":"96c523b8-321e-41a3-9523-39fde95dc71d",
                   "first_name":"John",
                   "last_name":"Doe",
                   "email_address":"jd@m.local"}

Search for at most 3 accounts where first and last name begin with 'foo' or 'bar'.

  curl -u sk_abcdefQWERTY090900000000: \
    -d 'query=foo bar'\
    -d limit=3 \
    https://cocalc.com/api/v1/user_search
  ==> {"event":"user_search_results",
       "id":"fd9b025b-25d0-4e27-97f4-2c080bb07155",
       "results":[{"account_id":"1a842a67-eed3-405d-a222-2f23a33f675e",
                   "first_name":"foo",
                   "last_name":"bar"},
                  {"account_id":"0e9418a7-af6a-4004-970a-32fafe733f29",
                   "first_name":"bar123",
                   "last_name":"fooxyz"},
                  {"account_id":"93f8131c-6c21-401a-897d-d4abd9c6c225",
                   "first_name":"Foo",
                   "last_name":"Bar"}]}

The same result as the last example above would be returned with a search string of 'bar foo'. A name of "Xfoo YBar" would not match.

Note that email addresses are not returned for string search items.

Email and string search types may be mixed in a single query:

  curl -u sk_abcdefQWERTY090900000000: \
    -d 'query=foo bar,jd@m.local' \
    -d limit=4 \
    https://cocalc.com/api/v1/user_search

/api/v1/write_text_file_to_project¶

`id`	A unique UUID for the query
`project_id`	id of project where file is created (required)
`path`	path to file, relative to home directory in destination project (required)
`content`	contents of the text file to be written (required)

Create a text file in the target project. User must be owner or collaborator in the target project. Directories containing the file are created if they do not exist already. Unix user in the target project must have permissions to create file and containing directories if they do not already exist. If a file already exists at the destination path, it is overwritten.

Example:

Create a text file.

  curl -u sk_abcdefQWERTY090900000000: \
    -d project_id=e49e86aa-192f-410b-8269-4b89fd934fba \
    -d "content=hello$'\n'world" \
    -d path=Assignments/A1/h1.txt \
    https://cocalc.com/api/v1/write_text_file_to_project