api.json

{
  "intro": "## Purpose\n\nThe purpose of the CoCalc API (application programming interface) is to make\nessential operations within the CoCalc platform available to automated\nclients. This allows embedding of CoCalc services within other products\nand customizing the external look and feel of the application.\n\n## Protocol and Data Format\n\nEach API command is invoked using an HTTPS POST request.\nAll commands support request parameters in JSON format, with request header\n`Content-Type: application/json`. Many commands (those that do not\nrequire lists or objects as parameters)\nalso accept request parameters as key-value pairs, i.e.\n`Content-Type: application/x-www-form-urlencoded`.\n\nResponses are formatted as JSON strings.\nNote that it is possible for a request to fail and return\na response code of 200. In that case, the response\nstring may contain helpful information on the nature of\nthe failure. In other cases, if the request cannnot\nbe completed, a response code other than 200 may be\nreturned, and the response body may be a\ngeneric HTML message rather than a JSON string.\n\n## Authentication\n\nA valid API key is required on all API requests.\n\nTo obtain a key manually, log into\nCoCalc and click on Settings (gear icon next to user name at upper\nright), and look under `Account Settings`.\nWith the `API key` dialogue, you can create a key,\nview a previously assigned key, generate a replacement key,\nand delete your key entirely.\n\n.. index:: API; get_api_key\n\nIt is also possible to obtain an API key using a javascript-enabled automated web client.\nThis option is useful for applications that embed CoCalc\nin a custom environment, for example [juno.sh](https://juno.sh),\nthe iOS application for Jupyter notebooks.\nVisiting the link :samp:`https://cocalc.com/app?get_api_key=myapp`,\nwhere \"myapp\" is an identifier for your application,\nreturns a modified sign-in page with the banner\n\"CoCalc API Key Access for Myapp\".\nThe web client must\nsign in with credentials for the account in question.\nResponse headers from a successful sign-in will include a url of the form\n:samp:`https://authenticated/?api_key=sk_abcdefQWERTY090900000000`.\nThe client should intercept this response and capture the string\nafter the equals sign as the API key.\n\nYour API key carries access privileges, just like your login and password.\n__Keep it secret.__\nDo not share your API key with others or post it in publicly accessible forums.\n\n## Additional References\n\n- The [CoCalc API tutorial](https://share.cocalc.com/share/6eec7a75ce704502e2d557f44c316bf75c5c6ce7/Public/?viewer=share) illustrates API calls in Python.\n- The CoCalc PostgreSQL schema definition [src/smc-util/db-schema](https://github.com/sagemathinc/cocalc/blob/master/src/smc-util/db-schema) has information on tables and fields used with the API `query` request.\n- The API test suite [src/smc-hub/test/api/](https://github.com/sagemathinc/cocalc/tree/master/src/smc-hub/test/api) contains mocha unit tests for the API messages.\n- The CoCalc message definition file [src/smc-util/message.js](https://github.com/sagemathinc/cocalc/blob/master/src/smc-util/message.js) contains the source for this guide.\n\n## API Message Reference\n\nThe remainder of this guide explains the individual API endpoints.\nEach API request definition begins with the path of the\nURL used to invoke the request,\nfor example `/api/v1/change_email_address`.\nThe path name ends with the name of the request,\nfor example, `change_email_address`.\nFollowing the path is the list of options.\nAfter options are one or more sample invocations\nillustrating format of the request as made with the `curl`\ncommand, and the format of the response.\n\nThe following two options appear on all API messages\n(request parameters are often referred to\nas 'options' in the guide):\n\n- **event**: the command to be executed, for example \"ping\"\n- **id**: uuid for the API call, returned in response in most cases.\nIf id is not provided in the API message, a random id will be\ngenerated and returned in the response.",
  "events": {
    "get_usernames": {
      "description": "Get first and last names for a list of account ids.\n\nNote: Options for the `get_usernames` API message must be sent as JSON object.\n\nExample:\n```\n  curl -u sk_abcdefQWERTY090900000000: -H \"Content-Type: application/json\" \\\n    -d '{\"account_ids\":[\"cc3cb7f1-14f6-4a18-a803-5034af8c0004\",\"9b896055-920a-413c-9172-dfb4007a8e7f\"]}' \\\n    https://cocalc.com/api/v1/get_usernames\n  ==>  {\"event\":\"usernames\",\n        \"id\":\"32b485a8-f214-4fda-a622-4dbfe0db2b9c\",\n        \"usernames\": {\n           \"cc3cb7f1-14f6-4a18-a803-5034af8c0004\":{\"first_name\":\"John\",\"last_name\":\"Smith\"},\n           \"9b896055-920a-413c-9172-dfb4007a8e7f\":{\"first_name\":\"Jane\",\"last_name\":\"Doe\"}}}\n```",
      "fields": {
        "id": "A unique UUID for the query",
        "account_ids": "list of account_ids (required)"
      }
    },
    "create_account": {
      "description": "Examples:\n\nCreate a new account:\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d first_name=John00 \\\n    -d last_name=Doe00 \\\n    -d email_address=jd@example.com \\\n    -d password=xyzabc09090 \\\n    -d agreed_to_terms=true https://cocalc.com/api/v1/create_account\n```\n\nOption `agreed_to_terms` must be present and specified as true.\nAccount creation fails if there is already an account using the\ngiven email address, if `email_address` is improperly formatted,\nand if password is fewer than 6 or more than 64 characters.\n\nAttempting to create the same account a second time results in an error:\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d first_name=John00 \\\n    -d last_name=Doe00 \\\n    -d email_address=jd@example.com \\\n    -d password=xyzabc09090 \\\n    -d agreed_to_terms=true https://cocalc.com/api/v1/create_account\n  ==> {\"event\":\"account_creation_failed\",\n       \"id\":\"2332be03-aa7d-49a6-933a-cd9824b7331a\",\n       \"reason\":{\"email_address\":\"This e-mail address is already taken.\"}}\n```",
      "fields": {
        "id": "A unique UUID for the query",
        "password": "if given, must be between 6 and 64 characters in length",
        "agreed_to_terms": "must be true or user will get nagged",
        "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"
      }
    },
    "delete_account": {
      "description": "Example:\n\nDelete an existing account:\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d account_id=99ebde5c-58f8-4e29-b6e4-b55b8fd71a1b \\\n    https://cocalc.com/api/v1/delete_account\n  ==> {\"event\":\"account_deleted\",\"id\":\"9e8b68ac-08e8-432a-a853-398042fae8c9\"}\n```\n\nEvent `account_deleted` is also returned if the account was already\ndeleted before the API call, or if the account never existed.\n\nAfter successful `delete_account`, the owner of the deleted account\nwill not be able to login, but will still be listed as collaborator\nor owner on projects which the user collaborated on or owned\nrespectively.",
      "fields": {
        "id": "A unique UUID for the query",
        "account_id": "account_id for account to be deleted (required)"
      }
    },
    "change_password": {
      "description": "Given account_id and old password for an account, set a new password.\n\nExample:\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d account_id=... \\\n    -d old_password=... \\\n    -d new_password=... \\\n    https://cocalc.com/api/v1/change_password\n  ==> {\"event\":\"changed_password\",\"id\":\"41ff89c3-348e-4361-ad1d-372b55e1544a\"}\n```",
      "fields": {
        "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)"
      }
    },
    "forgot_password": {
      "description": "Given the email address of an existing account, send password reset email.\n\nExample:\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d email_address=... \\\n    https://cocalc.com/api/v1/forgot_password\n  ==> {\"event\":\"forgot_password_response\",\n       \"id\":\"26ed294b-922b-47e1-8f3f-1e54d8c8e558\",\n       \"error\":false}\n```",
      "fields": {
        "id": "A unique UUID for the query",
        "email_address": "email address for account requesting password reset (required)"
      }
    },
    "reset_forgot_password": {
      "description": "Reset password, given reset code.\n\nExample:\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d reset_code=35a0eea6-370a-45c3-ab2f-3210df68748f \\\n    -d new_password=qjqhddfsfj \\\n    https://cocalc.com/api/v1/reset_forgot_password\n  ==> {\"event\":\"reset_forgot_password_response\",\"id\":\"85bd6027-644d-4859-9e17-5e835bd47570\",\"error\":false}\n```",
      "fields": {
        "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)"
      }
    },
    "change_email_address": {
      "description": "Given the `account_id` for an account, set a new email address.\n\nExamples:\n\nSuccessful change of email address.\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d account_id=99ebde5c-58f8-4e29-b6e4-b55b8fd71a1b \\\n    -d password=secret_password \\\n    -d new_email_address=new@email.com \\\n    https://cocalc.com/api/v1/change_email_address\n  ==> {\"event\":\"changed_email_address\",\n       \"id\":\"8f68f6c4-9851-4b88-bd65-37cb983298e3\",\n       \"error\":false}\n```\n\nFails if new email address is already in use.\n\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d account_id=99ebde5c-58f8-4e29-b6e4-b55b8fd71a1b \\\n    -d password=secret_password \\\n    -d new_email_address=used@email.com \\\n    https://cocalc.com/api/v1/change_email_address\n  ==> {\"event\":\"changed_email_address\",\n       \"id\":\"4501f022-a57c-4aaf-9cd8-af0eb05ebfce\",\n       \"error\":\"email_already_taken\"}\n```\n\n**Note:** `account_id` and `password` must match the `id` of the current login.",
      "fields": {
        "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: \"\")"
      }
    },
    "unlink_passport": {
      "description": "Unlink a passport auth for the account.\n\nStrategies are defined in the database and may be viewed at [/auth/strategies](https://cocalc.com/auth/strategies).\n\nExample:\n\nGet passport id for some strategy for current user.\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\"query\":{\"accounts\":{\"account_id\":\"e6993694-820d-4f78-bcc9-10a8e336a88d\",\"passports\":null}}}' \\\n    https://cocalc.com/api/v1/query\n  ==> {\"query\":{\"accounts\":{\"account_id\":\"e6993694-820d-4f78-bcc9-10a8e336a88d\",\n                            \"passports\":{\"facebook-14159265358\":{\"id\":\"14159265358\",...}}}},\n       \"multi_response\":false,\n       \"event\":\"query\",\n       \"id\":\"a2554ec8-665b-495b-b0e2-8e248b54eb94\"}\n```\n\nUnlink passport for that strategy and id.\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d strategy=facebook \\\n    -d id=14159265358 \\\n    https://cocalc.com/api/v1/unlink_passport\n  ==> {\"event\":\"success\",\n       \"id\":\"14159265358\"}\n```\n\nNote that success is returned regardless of whether or not passport was linked\nfor the given strategy and id before issuing the API command.",
      "fields": {
        "strategy": "passport strategy (required)",
        "id": "numeric id for user and passport strategy (required)"
      }
    },
    "project_exec": {
      "description": "Execute a shell command in a given project.\n\nExamples:\n\nSimple built-in shell command.\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d command=pwd \\\n    -d project_id=e49e86aa-192f-410b-8269-4b89fd934fba \\\n    https://cocalc.com/api/v1/project_exec\n  ==> {\"event\":\"project_exec_output\",\n       \"id\":\"8a78a37d-b2fb-4e29-94ae-d66acdeac949\",\n       \"stdout\":\"/projects/e49e86aa-192f-410b-8269-4b89fd934fba\\n\",\"stderr\":\"\",\"exit_code\":0}\n```\n\nShell command with different working directory.\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d command=pwd \\\n    -d path=Private \\\n    -d project_id=e49e86aa-192f-410b-8269-4b89fd934fba \\\n    https://cocalc.com/api/v1/project_exec\n  ==> {\"event\":\"project_exec_output\",\n       \"id\":\"8a78a37d-b2fb-4e29-94ae-d66acdeac949\",\n       \"stdout\":\"/projects/e49e86aa-192f-410b-8269-4b89fd934fba/Private\\n\",\"stderr\":\"\",\"exit_code\":0}\n```\n\nCommand line arguments specified by 'args' option. Note JSON format for request parameters.\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -H 'Content-Type: application/json' \\\n    -d '{\"command\":\"echo\",\"args\":[\"xyz\",\"abc\"],\"project_id\":\"e49e86aa-192f-410b-8269-4b89fd934fba\"}' \\\n    https://cocalc.com/api/v1/project_exec\n  ==> {\"event\":\"project_exec_output\",\n       \"id\":\"39289ba7-0333-48ad-984e-b25c8b8ffa0e\",\n       \"stdout\":\"xyz abc\\n\",\n       \"stderr\":\"\",\n       \"exit_code\":0}\n```\n\nLimiting output of the command to 3 characters.\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -H 'Content-Type: application/json' \\\n    -d '{\"command\":\"echo\",\"args\":[\"xyz\",\"abc\"],\"max_output\":3,\"project_id\":\"e49e86aa-192f-410b-8269-4b89fd934fba\"}' \\\n    https://cocalc.com/api/v1/project_exec\n  ==> {\"event\":\"project_exec_output\",\n       \"id\":\"02feab6c-a743-411a-afca-8a23b58988a9\",\n       \"stdout\":\"xyz (truncated at 3 characters)\",\n       \"stderr\":\"\",\n       \"exit_code\":0}\n```\n\nSetting a timeout for the command.\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -H 'Content-Type: application/json' \\\n    -d '{\"command\":\"sleep 5\",\"timeout\":2,\"project_id\":\"e49e86aa-192f-410b-8269-4b89fd934fba\"}' \\\n    https://cocalc.com/api/v1/project_exec\n  ==>  {\"event\":\"error\",\n        \"id\":\"86fea3f0-6a90-495b-a541-9c14a25fbe58\",\n        \"error\":\"Error executing command 'sleep 5' with args '' -- killed command 'bash /tmp/f-11757-1677-8ei2z0.t4fex0qkt9', , \"}\n```\n\nNotes:\n- Argument `command` may invoke an executable file or a built-in shell command. It may include\n  a path and command line arguments.\n- If option `args` is provided, options must be sent as a JSON object.\n- Argument `path` is optional. When provided, `path` is relative to home directory in target project\n  and specifies the working directory in which the command will be run.\n- If the project is stopped or archived, this API call will cause it to be started. Starting the project can take\n  several seconds. In this case, the call may return a timeout error and will need to be repeated. ",
      "fields": {
        "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)"
      }
    },
    "read_text_file_from_project": {
      "description": "Read a text file in the project whose `project_id` is supplied.\n\nArgument `'path'` is relative to home directory in target project.\n\nYou can also read multiple `project_id`/`path`'s at once by\nmaking `project_id` and `path` arrays (of the same length).\nIn that case, the result will be an array\nof `{project_id, path, content}` objects, in some random order.\nIf there is an error reading a particular file,\ninstead `{project_id, path, error}` is included.\n\n**Note:** You need to have read access to the project,\nthe Linux user `user` in the target project must have permissions to read the file\nand containing directories.\n\nExample:\n\nRead a text file.\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d project_id=e49e86aa-192f-410b-8269-4b89fd934fba \\\n    -d path=Assignments/A1/h1.txt \\\n    https://cocalc.com/api/v1/read_text_file_from_project\n  ==> {\"event\":\"text_file_read_from_project\",\n       \"id\":\"481d6055-5609-450f-a229-480e518b2f84\",\n       \"content\":\"hello\"}\n```",
      "fields": {
        "id": "A unique UUID for the query",
        "project_id": "id of project containing file to be read (or array of project_id's) (required)",
        "path": "path to file to be read in target project (or array of paths) (required)"
      }
    },
    "write_text_file_to_project": {
      "description": "Create a text file in the target project with the given `project_id`.\nDirectories containing the file are created if they do not exist already.\nIf a file already exists at the destination path, it is overwritten.\n\n**Note:** You need to have read access to the project.\nThe Linux user `user` in the target project must have permissions to create files\nand containing directories if they do not already exist.\n\nExample:\n\nCreate a text file.\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d project_id=e49e86aa-192f-410b-8269-4b89fd934fba \\\n    -d \"content=hello$'\\n'world\" \\\n    -d path=Assignments/A1/h1.txt \\\n    https://cocalc.com/api/v1/write_text_file_to_project\n```",
      "fields": {
        "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_project": {
      "description": "Example:\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d title='MY NEW PROJECT' \\\n    -d description='sample project' \\\n    https://cocalc.com/api/v1/create_project\n  == > {\"event\":\"project_created\",\n        \"id\":\"0b4df293-d518-45d0-8a3c-4281e501b85e\",\n        \"project_id\":\"07897899-6bbb-4fbc-80a7-3586c43348d1\"}\n```",
      "fields": {
        "id": "A unique UUID for the query",
        "title": "project title (default: \"\")",
        "description": "project description (default: \"\")",
        "image": "(optional) image ID",
        "license": "(optional) license id (or multiple ids separated by commas) -- if given, project will be created with this license",
        "start": "start running the moment the project is created -- uses more resources, but possibly better user experience (default: false)"
      }
    },
    "user_search": {
      "description": "There are two possible item types in the query list: email addresses\nand strings that are not email addresses. An email query item will return\naccount id, first name, last name, and email address for the unique\naccount with that email address, if there is one. A string query item\nwill return account id, first name, and last name for all matching\naccounts.\n\nWe do not reveal email addresses of users queried by name to non admins.\n\nString query matches first and last names that start with the given string.\nIf a string query item consists of two strings separated by space,\nthe search will return accounts in which the first name begins with one\nof the two strings and the last name begins with the other.\nString and email queries may be mixed in the list for a single\nuser_search call. Searches are case-insensitive.\n\nNote: there is a hard limit of 50 returned items in the results.\n\nExamples:\n\nSearch for account by email.\n```\n  curl -u : \\\n    -d query=jd@m.local \\\n    https://cocalc.com/api/v1/user_search\n  ==> {\"event\":\"user_search_results\",\n       \"id\":\"3818fa50-b892-4167-b9d9-d22d521b36af\",\n       \"results\":[{\"account_id\":\"96c523b8-321e-41a3-9523-39fde95dc71d\",\n                   \"first_name\":\"John\",\n                   \"last_name\":\"Doe\",\n                   \"email_address\":\"jd@m.local\"}\n```\n\nSearch for at most 3 accounts where first and last name begin with 'foo' or 'bar'.\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d 'query=foo bar'\\\n    -d limit=3 \\\n    https://cocalc.com/api/v1/user_search\n  ==> {\"event\":\"user_search_results\",\n       \"id\":\"fd9b025b-25d0-4e27-97f4-2c080bb07155\",\n       \"results\":[{\"account_id\":\"1a842a67-eed3-405d-a222-2f23a33f675e\",\n                   \"first_name\":\"foo\",\n                   \"last_name\":\"bar\"},\n                  {\"account_id\":\"0e9418a7-af6a-4004-970a-32fafe733f29\",\n                   \"first_name\":\"bar123\",\n                   \"last_name\":\"fooxyz\"},\n                  {\"account_id\":\"93f8131c-6c21-401a-897d-d4abd9c6c225\",\n                   \"first_name\":\"Foo\",\n                   \"last_name\":\"Bar\"}]}\n```\n\nThe same result as the last example above would be returned with a\nsearch string of 'bar foo'.\nA name of \"Xfoo YBar\" would not match.\n\nNote that email addresses are not returned for string search items.\n\nEmail and string search types may be mixed in a single query:\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d 'query=foo bar,jd@m.local' \\\n    -d limit=4 \\\n    https://cocalc.com/api/v1/user_search\n```",
      "fields": {
        "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: \"\")",
        "limit": "maximum number of results returned (default: 20)"
      }
    },
    "add_license_to_project": {
      "description": "Add a license to a project.\n\nExample:\n```\n   example not available yet\n```",
      "fields": {
        "id": "A unique UUID for the message",
        "project_id": "project_id (required)",
        "license_id": "id of a license (required)"
      }
    },
    "remove_license_from_project": {
      "description": "Remove a license from a project.\n\nExample:\n```\n   example not available yet\n```",
      "fields": {
        "id": "A unique UUID for the message",
        "project_id": "project_id (required)",
        "license_id": "id of a license (required)"
      }
    },
    "invite_collaborator": {
      "description": "Invite a user who already has a CoCalc account to\nbecome a collaborator on a project. You must be owner\nor collaborator on the target project.  The user\nwill receive an email notification.\n\nExample:\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d account_id=99ebde5c-58f8-4e29-b6e4-b55b8fd71a1b \\\n    -d project_id=18955da4-4bfa-4afa-910c-7f2358c05eb8 \\\n    https://cocalc.com/api/v1/invite_collaborator\n  ==> {\"event\":\"success\",\n       \"id\":\"e80fd64d-fd7e-4cbc-981c-c0e8c843deec\"}\n```",
      "fields": {
        "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 invitation email"
      }
    },
    "add_collaborator": {
      "description": "Directly add a user to a CoCalc project.\nYou must be owner or collaborator on the target project or provide,\nan optional valid token_id (the token determines the project).\nThe user is NOT notified via email that they were added, and there\nis no confirmation process.  (Eventually, there will be\nan accept process, or this endpoint will only work\nwith a notion of \"managed accounts\".)\n\nYou can optionally add multiple user to multiple projects by padding\nan array of strings for project_id and account_id.  The arrays\nmust have the same length.\n\nExample:\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d account_id=99ebde5c-58f8-4e29-b6e4-b55b8fd71a1b \\\n    -d project_id=18955da4-4bfa-4afa-910c-7f2358c05eb8 \\\n    https://cocalc.com/api/v1/add_collaborator\n  ==> {\"event\":\"success\",\n       \"id\":\"e80fd64d-fd7e-4cbc-981c-c0e8c843deec\"}\n```",
      "fields": {
        "id": "A unique UUID for the query",
        "project_id": "project_id of project to add user to (can be an array to add multiple users to multiple projects); isn't needed if token_id is specified",
        "account_id": "account_id of user (can be an array to add multiple users to multiple projects) (required)",
        "token_id": "project_invite_token that is needed in case the user **making the request** is not already a project collab"
      }
    },
    "remove_collaborator": {
      "description": "Remove a user from a CoCalc project.\nYou must be owner or collaborator on the target project.\nThe project owner cannot be removed.\nThe user is NOT notified via email that they were removed.\n\nExample:\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d account_id=99ebde5c-58f8-4e29-b6e4-b55b8fd71a1b \\\n    -d project_id=18955da4-4bfa-4afa-910c-7f2358c05eb8 \\\n    https://cocalc.com/api/v1/remove_collaborator\n  ==> {\"event\":\"success\",\n       \"id\":\"e80fd64d-fd7e-4cbc-981c-c0e8c843deec\"}\n```",
      "fields": {
        "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)"
      }
    },
    "invite_noncloud_collaborators": {
      "description": "Invite users who do not already have a CoCalc account\nto join a project.\nAn invitation email is sent to each user in the `to`\noption.\nInvitation is not sent if there is already a CoCalc\naccount with the given email address.\nYou must be owner or collaborator on the target project.\n\nLimitations:\n- Total length of the request message must be less than or equal to 1024 characters.\n- Length of each email address must be less than 128 characters.\n\n\nExample:\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d project_id=18955da4-4bfa-4afa-910c-7f2358c05eb8 \\\n    -d to=someone@m.local \\\n    -d 'email=Please sign up and join this project.' \\\n    -d 'title=Class Project' \\\n    -d link2proj=https://cocalc.com/projects/18955da4-4bfa-4afa-910c-7f2358c05eb8 \\\n    https://cocalc.com/api/v1/invite_noncloud_collaborators\n  ==>  {\"event\":\"invite_noncloud_collaborators_resp\",\n        \"id\":\"39d7203d-89b1-4145-8a7a-59e41d5682a3\",\n        \"mesg\":\"Invited someone@m.local to collaborate on a project.\"}\n```\n\nEmail sent by the previous example:\n\n```\nTo: someone@m.local\nFrom: CoCalc <invites@cocalc.com\nReply-To: help@cocalc.com\nSubject: CoCalc Invitation\n\nPlease sign up and join this project.<br/><br/>\\n<b>\nTo accept the invitation, please sign up at\\n\n<a href='https://cocalc.com'>https://cocalc.com</a>\\n\nusing exactly the email address 'someone@m.local'.\\n\nThen go to <a href='https://cocalc.com/projects/18955da4-4bfa-4afa-910c-7f2358c05eb8'>\nthe project 'Team Project'</a>.</b><br/>\n```",
      "fields": {
        "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"
      }
    },
    "copy_path_between_projects": {
      "description": "Copy a file or directory from one project to another.\n\n**Note:** the `timeout` option is passed to a call to the `rsync` command.\nIf no data is transferred for the specified number of seconds, then\nthe copy terminates. The default is 0, which means no timeout.\n\nRelative paths (paths not beginning with '/') are relative to the user's\nhome directory in source and target projects.\n\n**Note:** You need to have read/write access to the associated src/target project.\n\nFurther options:\n\n- `wait_until_done`: set this to false to immediately retrieve the `copy_path_id`.\n  This is the **recommended way** to use this endpoint,\n  because a blocking request might time out and you'll never learn about outcome of the copy operation.\n  Learn about the status (success or failure, including an error message) via the :doc:`copy_path_status` endpoint.\n- `scheduled`: set this to a date in the future or postpone the copy operation.\n  Suitable timestamps can be created as follows:\n  - Bash: 1 minute in the future `date -d '+1 minute' --utc +'%Y-%m-%dT%H:%M:%S'`\n  - Python using [arrow](https://arrow.readthedocs.io/en/latest/) library:\n    - 1 minute in the future: `arrow.now('UTC').shift(minutes=+1).for_json()`\n    - At a specific time: `arrow.get(\"2019-08-29 22:00\").for_json()`\n  Later, learn about its outcome via :doc:`copy_path_status` as well.\n\nExample:\n\nCopy file `A/doc.txt` from source project to target project.\nFolder `A` will be created in target project if it does not exist already.\n\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d src_project_id=e49e86aa-192f-410b-8269-4b89fd934fba \\\n    -d src_path=A/doc.txt \\\n    -d target_project_id=2aae4347-214d-4fd1-809c-b327150442d8 \\\n    https://cocalc.com/api/v1/copy_path_between_projects\n  ==> {\"event\":\"success\",\n       \"id\":\"45d851ac-5ea0-4aea-9997-99a06c054a60\"}\n```",
      "fields": {
        "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)",
        "wait_until_done": "if false, the operation returns immediately with the copy_path_id for querying copy_path_status (default: true)",
        "scheduled": "if set, the copy operation runs earliest after the given time and wait_until_done is false. Must be a `new Date(...)` parseable string."
      }
    },
    "copy_path_status": {
      "description": "Retrieve status information about copy path operation(s).\n\nThere are two ways to query:\n\n- **single result** for a specific `copy_path_id`,\n  which was returned by `copy_path_between_projects` earlier;\n- **array of results**, for at last one of `src_project_id` or `target_project_id`,\n  and additionally filtered by an optionally given `src_path`.\n\nCheck for the field `\"finished\"`, containing the timestamp when the operation completed.\nThere might also be an `\"error\"`!\n\n**Note:** You need to have read/write access to the associated src/target project.\n",
      "fields": {
        "copy_path_id": "A unique UUID for a copy path operation",
        "src_project_id": "Source of copy operation to filter on",
        "target_project_id": "Target of copy operation to filter on",
        "src_path": "(src/targ only) Source path of copy operation to filter on",
        "limit": "(src/targ only) maximum number of results  (max 1000) (default: 1000)",
        "offset": "(src/targ only) default 0; set this to a multiple of the limit",
        "pending": "(src/targ only) true returns copy ops, which did not finish yet (default: true) (default: true)",
        "failed": "(src/targ only) if true, only show finished and failed copy ops (default: false) (default: false)"
      }
    },
    "copy_path_delete": {
      "description": "Delete a copy_path operation with the given `copy_path_id`.\nYou need to have read/write access to the associated src/target project.\n\n**Note:** This will only remove entries which are *scheduled* and not yet completed.\n",
      "fields": {
        "copy_path_id": "A unique UUID for a scheduled future copy path operation"
      }
    },
    "ping": {
      "description": "Test API connection, return time as ISO string when server responds to ping.\n\nSecurity key may be blank.\n\nExamples:\n\nOmitting request id:\n```\n  curl -X POST -u sk_abcdefQWERTY090900000000: https://cocalc.com/api/v1/ping\n  ==> {\"event\":\"pong\",\"id\":\"c74afb40-d89b-430f-836a-1d889484c794\",\"now\":\"2017-05-24T13:29:11.742Z\"}\n```\n\nOmitting request id and using blank security key:\n```\n  curl -X POST -u : https://cocalc.com/api/v1/ping\n  ==>  {\"event\":\"pong\",\"id\":\"d90f529b-e026-4a60-8131-6ce8b6d4adc8\",\"now\":\"2017-11-05T21:10:46.585Z\"}\n```\n\nUsing `uuid` shell command to create a request id:\n```\n  uuid\n  ==> 553f2815-1508-416d-8e69-2dde5af3aed8\n  curl -u sk_abcdefQWERTY090900000000: https://cocalc.com/api/v1/ping -d id=553f2815-1508-416d-8e69-2dde5af3aed8\n  ==> {\"event\":\"pong\",\"id\":\"553f2815-1508-416d-8e69-2dde5af3aed8\",\"now\":\"2017-05-24T13:47:21.312Z\"}\n```\n\nUsing JSON format to provide request id:\n```\n  curl -u sk_abcdefQWERTY090900000000: -H \"Content-Type: application/json\" \\\n    -d '{\"id\":\"8ec4ac73-2595-42d2-ad47-0b9641043b46\"}' https://cocalc.com/api/v1/ping\n  ==> {\"event\":\"pong\",\"id\":\"8ec4ac73-2595-42d2-ad47-0b9641043b46\",\"now\":\"2017-05-24T17:15:59.288Z\"}\n```",
      "fields": {
        "id": "A unique UUID for the query"
      }
    },
    "public_get_directory_listing": {
      "description": "Given a project id and relative path (i.e. not beginning with a slash),\nlist all public files and subdirectories under that path.\nPath is required, but may be the empty string, in which case\na public listing of the home directory in the target project is\nreturned.\n\nExamples:\n\nGet public directory listing. Directory \"Public\" is shared and\ncontains one file \"hello.txt\" and one subdirectory \"p2\".\n\nSecurity key may be blank.\n\n```\n  curl -u : \\\n    -d path=Public \\\n    -d project_id=9a19cca3-c53d-4c7c-8c0f-e166aada7bb6 \\\n    https://cocalc.com/api/v1/public_get_directory_listing\n  ==> {\"event\":\"public_directory_listing\",\n       \"id\":\"3e576b3b-b673-4d5c-9bce-780883f92958\",\n       \"result\":{\"files\":[{\"size\":41,\"name\":\"hello.txt\",\"mtime\":1496430932},\n                          {\"isdir\":true,\"name\":\"p2\",\"mtime\":1496461616}]}\n```",
      "fields": {
        "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)"
      }
    },
    "public_get_text_file": {
      "description": "Read a public (shared) text file in the project whose id is supplied.\nUser does not need to be owner or collaborator in the target project\nand does not need to be logged into CoCalc.\nArgument `path` is relative to home directory in target project.\n\nSecurity key may be blank.\n\nExamples\n\nRead a public file.\n```\n  curl -u : \\\n    -d project_id=e49e86aa-192f-410b-8269-4b89fd934fba \\\n    -d path=Public/hello.txt\n    https://cocalc.com/api/v1/public_get_text_file\n  ==> {\"event\":\"public_text_file_contents\",\n       \"id\":\"2d0e2faa-893a-44c1-9f64-59203bbbb017\",\n       \"data\":\"hello world\\nToday is Friday\\n\"}\n```\n\nAttempt to read a file which is not public.\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d project_id=e49e86aa-192f-410b-8269-4b89fd934fba \\\n    -d path=Private/hello.txt\n    https://cocalc.com/api/v1/public_get_text_file\n  ==> {\"event\":\"error\",\"id\":\"0288b7d0-dda9-4895-87ba-aa71929b2bfb\",\n       \"error\":\"path 'Private/hello.txt' of project with id 'e49e86aa-192f-410b-8269-4b89fd934fba' is not public\"}\n```",
      "fields": {
        "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)"
      }
    },
    "copy_public_path_between_projects": {
      "description": "Copy a file or directory from a public project to a target project.\n\n**Note:** the `timeout` option is passed to a call to the `rsync` command.\nIf no data is transferred for the specified number of seconds, then\nthe copy terminates. The default is 0, which means no timeout.\n\n**Note:** You need to have write access to the target project.\n\nExample:\n\nCopy public file `PUBLIC/doc.txt` from source project to private file\n`A/sample.txt` in target project.\n\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d src_project_id=e49e86aa-192f-410b-8269-4b89fd934fba \\\n    -d src_path=PUBLIC/doc.txt \\\n    -d target_project_id=2aae4347-214d-4fd1-809c-b327150442d8 \\\n    -d target_path=A/sample.txt \\\n    https://cocalc.com/api/v1/copy_public_path_between_projects\n  ==> {\"event\":\"success\",\n       \"id\":\"45d851ac-5ea0-4aea-9997-99a06c054a60\"}\n```",
      "fields": {
        "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)"
      }
    },
    "log_client_error": {
      "description": "Log an error so that CoCalc support can look at it.\n\nIn the following example, an explicit message id\nis provided for future reference.\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d id=34a424dc-1731-4b31-ba3d-fc8a484980d9 \\\n    -d \"error=cannot load library xyz\" \\\n    https://cocalc.com/api/v1/log_client_error\n  ==> {\"event\":\"success\",\n       \"id\":\"34a424dc-1731-4b31-ba3d-fc8a484980d9\"}\n```\n\nNote: the above API call will create the following record in the\n`client_error_log` database table. This table is not readable\nvia the API and is intended for use by CoCalc support only:\n```\n[{\"id\":\"34a424dc-1731-4b31-ba3d-fc8a484980d9\",\n  \"event\":\"error\",\n  \"error\":\"cannot load library xyz\",\n  \"account_id\":\"1c87a139-9e13-4cdd-b02c-e7d41dcfe921\",\n  \"time\":\"2017-07-06T02:32:41.176Z\"}]\n```",
      "fields": {
        "id": "A unique UUID for the query",
        "error": "error string (required)"
      }
    },
    "create_support_ticket": {
      "description": "Open a CoCalc support ticket.\n\nNotes:\n\n- If `account_id` is not provided, the ticket will be created, but ticket\ninfo will not be returned by `get_support_tickets`.\n\n- If `username` is not provided, `email_address` is used for the name on the ticket.\n\n- `location` is used to provide a path to a specific project or file, for example\n  ```\n  /project/a17037cb-a083-4519-b3c1-38512af603a6/files/notebook.ipynb`\n  ```\n\nIf present, the `location` string will be expanded to a complete URL and\nappended to the body of the ticket.\n\n- The `info` dict can be used to provide additional metadata, for example\n  ```\n  {\"user_agent\":\"Mozilla/5.0 ... Chrome/58.0.3029.96 Safari/537.36\"}\n  ```\n\n- If the ticket concerns a CoCalc course, the project id of the course can be included in the `info` dict, for example,\n  ```\n  {\"course\":\"0c7ae00c-ea43-4981-b454-90d4a8b1ac47\"}\n  ```\n\n  In that case, the course project_id will be expanded to a URL and appended to the body of the ticket.\n\n- If `tags` or `info` are provided, options must be sent as a JSON object.\n\nExample:\n\n```\n  curl -u sk_abcdefQWERTY090900000000: -H \"Content-Type: application/json\" \\\n    -d '{\"email_address\":\"jd@example.com\", \\\n         \"subject\":\"package xyz\", \\\n         \"account_id\":\"291f43c1-deae-431c-b763-712307fa6859\", \\\n         \"body\":\"please install package xyz for use with Python3\", \\\n         \"tags\":[\"member\"], \\\n         \"location\":\"/projects/0010abe1-9283-4b42-b403-fa4fc1e3be57/worksheet.sagews\", \\\n         \"info\":{\"user_agent\":\"Mozilla/5.0\",\"course\":\"cc8f1243-d573-4562-9aab-c15a3872d683\"}}' \\\n    https://cocalc.com/api/v1/create_support_ticket\n  ==> {\"event\":\"support_ticket_url\",\n       \"id\":\"abd649bf-ea2d-4952-b925-e44c6903945e\",\n       \"url\":\"https://sagemathcloud.zendesk.com/requests/0123\"}\n```",
      "fields": {
        "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"
      }
    },
    "get_support_tickets": {
      "description": "Fetch information on support tickets for the user making the request.\nSee the example for details on what is returned.\n\nNotes:\n\n- There may be a delay of several minutes between the time a support ticket\nis created with a given `account_id` and the time that ticket is\navailable to the account owner via `get_support_tickets`.\n- Field `account_id` is not required because it is implicit from the request.\n- Archived tickets are not returned.\n\nExample:\n\n```\ncurl -u sk_abcdefQWERTY090900000000:  -X POST \\\n    https://cocalc.com/api/v1/get_support_tickets\n  ==> {\"event\":\"support_tickets\",\n       \"id\":\"58bfd6f4-fd63-4602-82b8-676d92f8b0b8\",\n       \"tickets\":[{\"id\":1234,\n                   \"subject\":\"package xyz\",\n                   \"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\",\n                   \"created_at\":\"2017-07-05T14:28:38Z\",\n                   \"updated_at\":\"2017-07-05T14:29:29Z\",\n                   \"status\":\"open\",\n                   \"url\":\"https://sagemathcloud.zendesk.com/requests/0123\"}]}\n```",
      "fields": {
        "id": "A unique UUID for the query"
      }
    },
    "query": {
      "description": "This queries directly the database (sort of Facebook's GraphQL)\nOptions for the 'query' API message must be sent as JSON object.\nA query is either _get_ (read from database), or _set_ (write to database).\nA query is _get_ if any query keys are null, otherwise the query is _set_.\n\nNote: queries with `multi_response` set to `true` are not supported.\n\n#### Examples of _get_ query:\n\nGet title and description for a project, given the project id.\n```\n  curl -u sk_abcdefQWERTY090900000000: -H \"Content-Type: application/json\" \\\n    -d '{\"query\":{\"projects\":{\"project_id\":\"29163de6-b5b0-496f-b75d-24be9aa2aa1d\",\"title\":null,\"description\":null}}}' \\\n    https://cocalc.com/api/v1/query\n  ==> {\"event\":\"query\",\n       \"id\":\"8ec4ac73-2595-42d2-ad47-0b9641043b46\",\n       \"query\":{\"projects\":{\"project_id\":\"29163de6-b5b0-496f-b75d-24be9aa2aa1d\",\n                            \"title\":\"MY NEW PROJECT 2\",\n                            \"description\":\"desc 2\"}},\n       \"multi_response\":false}\n```\n\nGet info on all projects for the account whose security key is provided.\nThe information returned may be any of the api-accessible fields in the\n`projects` table. These fields are listed in CoCalc source directory\nsrc/smc-util/db-schema, under `schema.projects.user_query`.\nIn this example, project name and description are returned.\n\nNote: to get info only on projects active in the past 3 weeks, use\n`projects` instead of `projects_all` in the query.\n\n```\n  curl -u sk_abcdefQWERTY090900000000: -H \"Content-Type: application/json\" \\\n    -d '{\"query\":{\"projects_all\":[{\"project_id\":null,\"title\":null,\"description\":null}]}}' \\\n    https://cocalc.com/api/v1/query\n  ==> {\"event\":\"query\",\n       \"id\":\"8ec4ac73-2595-42d2-ad47-0b9641043b46\",\n       \"multi_response\": False,\n       \"query\": {\"projects_all\": [{\"description\": \"Synthetic Monitoring\",\n                         \"project_id\": \"1fa1626e-ce25-4871-9b0e-19191cd03325\",\n                         \"title\": \"SYNTHMON\"},\n                        {\"description\": \"No Description\",\n                         \"project_id\": \"639a6b2e-7499-41b5-ac1f-1701809699a7\",\n                         \"title\": \"TESTPROJECT 99\"}]}}\n```\n\n\nGet project id, given title and description.\n```\n  curl -u sk_abcdefQWERTY090900000000: -H \"Content-Type: application/json\" \\\n    -d '{\"query\":{\"projects\":{\"project_id\":null,\"title\":\"MY NEW PROJECT 2\",\"description\":\"desc 2\"}}}' \\\n    https://cocalc.com/api/v1/query\n  ==> {\"event\":\"query\",\n       \"query\":{\"projects\":{\"project_id\":\"29163de6-b5b0-496f-b75d-24be9aa2aa1d\",\n                            \"title\":\"MY NEW PROJECT 2\",\n                            \"description\":\"desc 2\"}},\n       \"multi_response\":false,\n       \"id\":\"2be22e08-f00c-4128-b112-fa8581c2d584\"}\n```\n\nGet users, given the project id.\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\"query\":{\"projects\":{\"project_id\":\"29163de6-b5b0-496f-b75d-24be9aa2aa1d\",\"users\":null}}}' \\\n    https://cocalc.com/api/v1/query\n  ==> {\"event\":\"query\",\n       \"query\":{\"projects\":{\"project_id\":\"29163de6-b5b0-496f-b75d-24be9aa2aa1d\",\n                            \"users\":{\"6c28c5f4-3235-46be-b025-166b4dcaac7e\":{\"group\":\"owner\"},\n                                     \"111634c0-7048-41e7-b2d0-f87129fd409e\":{\"group\":\"collaborator\"}}}},\n       \"multi_response\":false,\n       \"id\":\"9dd3ef3f-002b-4893-b31f-ff51440c855f\"}\n```\n\n\nShow project upgrades. Like the preceding example, this is a query to get users.\nIn this example, there are no collaborators, but upgrades have been applied to the\nselected project. Upgrades do not show if none are applied.\n\nThe project shows the following upgrades:\n- cpu cores:       1\n- memory:          3000 MB\n- idle timeout:    24 hours (86400 seconds)\n- internet access: true\n- cpu shares:      3 (stored in database as 768 = 3 * 256)\n- disk space:      27000 MB\n- member hosting:  true\n\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\"query\":{\"projects\":{\"project_id\":\"29163de6-b5b0-496f-b75d-24be9aa2aa1d\",\"users\":null}}}' \\\n    https://cocalc.com/api/v1/query\n  ==> {\"event\":\"query\",\n       \"query\":{\"projects\":{\"project_id\":\"29163de6-b5b0-496f-b75d-24be9aa2aa1d\",\n                            \"users\":{\"6c28c5f4-3235-46be-b025-166b4dcaac7e\":{\n                                         \"group\":\"owner\",\n                                         \"upgrades\":{\"cores\":1,\n                                                     \"memory\":3000,\n                                                     \"mintime\":86400,\n                                                     \"network\":1,\n                                                     \"cpu_shares\":768,\n                                                     \"disk_quota\":27000,\n                                                     \"member_host\":1}}}}},\n       \"multi_response\":false,\n       \"id\":\"9dd3ef3f-002b-4893-b31f-ff51440c855f\"}\n```\n\nGet editor settings for the present user.\n\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\"query\":{\"accounts\":{\"account_id\":\"29163de6-b5b0-496f-b75d-24be9aa2aa1d\",\"editor_settings\":null}}}' \\\n    https://cocalc.com/api/v1/query\n  ==> {\"event\":\"query\",\n       \"multi_response\":false,\n       \"id\":\"9dd3ef3f-002b-4893-b31f-ff51440c855f\",\n       \"query\": {\"accounts\": {\"account_id\": \"29163de6-b5b0-496f-b75d-24be9aa2aa1d\",\n                              \"editor_settings\": {\"auto_close_brackets\": True,\n                                                  \"auto_close_xml_tags\": True,\n                                                  \"bindings\": \"standard\",\n                                                  \"code_folding\": True,\n                                                  \"electric_chars\": True,\n                                                  \"extra_button_bar\": True,\n                                                  \"first_line_number\": 1,\n                                                  \"indent_unit\": 4,\n                                                  \"jupyter_classic\": False,\n                                                  \"line_numbers\": True,\n                                                  \"line_wrapping\": True,\n                                                  \"match_brackets\": True,\n                                                  \"match_xml_tags\": True,\n                                                  \"multiple_cursors\": True,\n                                                  \"show_trailing_whitespace\": True,\n                                                  \"smart_indent\": True,\n                                                  \"spaces_instead_of_tabs\": True,\n                                                  \"strip_trailing_whitespace\": False,\n                                                  \"tab_size\": 4,\n                                                  \"theme\": \"default\",\n                                                  \"track_revisions\": True,\n                                                  \"undo_depth\": 300}}}}\n```\n\n#### Examples of _set_ query.\n\nSet title and description for a project, given the project id.\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\"query\":{\"projects\":{\"project_id\":\"29163de6-b5b0-496f-b75d-24be9aa2aa1d\", \\\n                              \"title\":\"REVISED TITLE\", \\\n                              \"description\":\"REVISED DESC\"}}}' \\\n    https://cocalc.com/api/v1/query\n    ==> {\"event\":\"query\",\n         \"query\":{},\n         \"multi_response\":false,\n         \"id\":\"ad7d6b17-f5a9-4c5c-abc3-3823b1e1773f\"}\n```\n\nMake a path public (publish a file).\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\"query\":{\"public_paths\":{\"project_id\":\"29163de6-b5b0-496f-b75d-24be9aa2aa1d\", \\\n                                  \"path\":\"myfile.txt\", \\\n                                  \"description\":\"a shared text file\"}}}' \\\n    https://cocalc.com/api/v1/query\n    ==> {\"event\":\"query\",\n         \"query\":{},\n         \"multi_response\":false,\n         \"id\":\"ad7d6b17-f5a9-4c5c-abc3-3823b1e1773f\"}\n\n```\n\nAdd an upgrade to a project. In the \"get\" example above showing project upgrades,\nchange cpu upgrades from 3 to 4. The `users` object is returned as\nread, with `cpu_shares` increased to 1024 = 4 * 256.\nIt is not necessary to specify the entire `upgrades` object\nif you are only setting the `cpu_shares` attribute because changes are merged in.\n\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\"query\":{\"projects\":{\"project_id\":\"29163de6-b5b0-496f-b75d-24be9aa2aa1d\", \\\n                              \"users\":{\"6c28c5f4-3235-46be-b025-166b4dcaac7e\":{ \\\n                                           \"upgrades\": {\"cpu_shares\":1024}}}}}}' \\\n    https://cocalc.com/api/v1/query\n    ==> {\"event\":\"query\",\n         \"query\":{},\n         \"multi_response\":false,\n         \"id\":\"ec822d6f-f9fe-443d-9845-9cd5f68bac20\"}\n```\n\nSet present user to open Jupyter notebooks in\n\"CoCalc Jupyter Notebook\" as opposed to \"Classical Notebook\".\nThis change not usually needed, because accounts\ndefault to \"CoCalc Jupyter Notebook\".\n\nIt is not necessary to specify the entire `editor_settings` object\nif you are only setting the `jupyter_classic` attribute because changes are merged in.\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\"query\":{\"accounts\":{\"account_id\":\"29163de6-b5b0-496f-b75d-24be9aa2aa1d\",\"editor_settings\":{\"jupyter_classic\":false}}}}' \\\n    https://cocalc.com/api/v1/query\n  ==> {\"event\":\"query\",\n       \"multi_response\":false,\n       \"id\":\"9dd3ef3f-002b-4893-b31f-ff51440c855f\",\n       \"query\": {}}\n```\n\n\n__NOTE:__ Information on which fields are gettable and settable in the database tables\nvia API message is in the directory 'db-schema', in CoCalc sources on GitHub at\nhttps://github.com/sagemathinc/cocalc/blob/master/src/smc-util/db-schema\n\nWithin directory 'db-schema':\n\n- for _project_ fields you can get, see the definition of\n`schema.projects.user_query.get.fields`\n- for _project_ fields you can set, see the definition of\n`schema.projects.user_query.set.fields`\n- for _user account_ fields you can get, see the definition of\n`schema.accounts.user_query.get.fields`\n- for _user account_ fields you can set, see the definition of\n`schema.accounts.user_query.set.fields`",
      "fields": {
        "id": "A unique UUID for the query",
        "query": "The actual query (required)",
        "changes": "",
        "multi_response": " (default: false)",
        "options": ""
      }
    },
    "user_auth": {
      "description": ".. index:: pair: Token; Authentication\nExample:\n\nObtain a temporary authentication token for an account, which\nis a 24 character string. Tokens last for **12 hours**.  You can\nonly obtain an auth token for accounts that have a password.\n\n```\n  curl -u sk_abcdefQWERTY090900000000: \\\n    -d account_id=99ebde5c-58f8-4e29-b6e4-b55b8fd71a1b \\\n    -d password=secret_password \\\n    https://cocalc.com/api/v1/user_auth\n  ==> {\"event\":\"user_auth_token\",\"id\":\"9e8b68ac-08e8-432a-a853-398042fae8c9\",\"auth_token\":\"BQokikJOvBiI2HlWgH4olfQ2\"}\n```\n\nYou can now use the auth token to craft a URL like this:\n\n    https://cocalc.com/app?auth_token=BQokikJOvBiI2HlWgH4olfQ2\n\nand provide that to a user.  When they visit that URL, they will be temporarily signed in as that user.",
      "fields": {
        "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)"
      }
    },
    "metrics": {
      "description": "",
      "fields": {
        "metrics": "object containing the metrics (required)"
      }
    },
    "start_metrics": {
      "description": "",
      "fields": {
        "interval_s": "tells client that it should submit metrics to the hub every interval_s seconds (required)"
      }
    },
    "get_available_upgrades": {
      "description": "This request returns information on project upgrdes for the user\nwhose API key appears in the request.\nTwo objects are returned, total upgrades and available upgrades.\n\nSee https://github.com/sagemathinc/cocalc/blob/master/src/smc-util/upgrade-spec.js for units\n\nExample:\n```\n  curl -X POST -u sk_abcdefQWERTY090900000000: https://cocalc.com/api/v1/get_available_upgrades\n  ==>\n  {\"id\":\"57fcfd71-b50f-44ef-ba66-1e37cac858ef\",\n   \"event\":\"available_upgrades\",\n   \"total\":{\n     \"cores\":10,\n     \"cpu_shares\":2048,\n     \"disk_quota\":200000,\n     \"member_host\":80,\n     \"memory\":120000,\n     \"memory_request\":8000,\n     \"mintime\":3456000,\n     \"network\":400},\n     \"excess\":{},\n   \"available\":{\n     \"cores\":6,\n     \"cpu_shares\":512,\n     \"disk_quota\":131000,\n     \"member_host\":51,\n     \"memory\":94000,\n     \"memory_request\":8000,\n     \"mintime\":1733400,\n     \"network\":372}}\n```",
      "fields": {
        "id": "A unique UUID for the query"
      }
    },
    "touch_project": {
      "description": "Mark this project as being actively used by the user sending this message.  This keeps the project from idle timing out, among other things.",
      "fields": {
        "id": "A unique UUID for the query",
        "project_id": "id of project to touch (required)"
      }
    },
    "disconnect_from_project": {
      "description": "Disconnect the hub that gets this message from the project.   This is used entirely for internal debugging and development.",
      "fields": {
        "id": "A unique UUID for the query",
        "project_id": "id of project to disconnect from (required)"
      }
    }
  },
  "root": "/api/v1/",
  "timestamp": "2020-09-17T03:08:33.230Z",
  "gitrev": "86c0a8a7d15edce662867107332f27b0a2b254eb"
}