export var api_messages: {};
export namespace documentation {
    export { doc_intro as intro };
    export const events: {};
}
export var examples: {};
declare const doc_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://cocalc.com/share/65f06a34-6690-407d-b95c-f51bbd5ee810/Public/README.md?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.";
export {};