query
id: A unique UUID for the queryquery: 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.
Note: queries with multi_response set to true are not supported.
Examples of a get query
Get title and description for a project
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 directory
src/smc-util/db-schema, 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 a set query
Set title and description for a project
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": {}}
Start and Stop a project
The example starts a project. Use stop instead of start for the action to stop a project.
curl -u sk_abcdefQWERTY090900000000: \
-H "Content-Type: application/json" \
-d '{"query": \
{ "projects": \
{ "project_id":"29163de6-b5b0-496f-b75d-24be9aa2aa1d", \
"action_request":{'action':'start'}}}}' \
https://cocalc.com/api/v1/query
Gettable and settable fields
Information on which fields are gettable and settable is in the CoCalc source code. See the definition of user_query for example in the
accounts.ts
or
projects.ts files.
