CKAN API: Quickstart Tutorial

A quickstart tutorial for the CKAN API that walks through some of the main features. For full details of the API see CKAN API and its API: Reference section.

The following examples use the demonstration instance at You may obviously replace this with your own site.

Details of tools for accessing the API including client libraries can be found in the main API section here.

Example queries

Get dataset

{"id": "a3dd8f64-9078-4f04-845c-e3f047125028", "name": "osm", "title": "Open Street Map", ...

Create a dataset


You’ll need an api key.

curl -d '{"name":"test", "title":"Test dataset"}' -H "Authorization:your-api-key"

Update a dataset

(Using POST or PUT):

curl -d '{"name":"test", "title":"Changed Test dataset"}' -H "Authorization:your-api-key"

Viewing permissions

To view authorization roles on a dataset:

curl -d '{"domain_object": "freshwateratlasrivers"}'

  "help": "Returns the roles that users (and authorization groups) have on a\n    particular domain_object.\n    \n    If you specify a user (or authorization group) then the resulting roles\n    will be filtered by those of that user (or authorization group).\n\n    domain_object can be a package/group/authorization_group name or id.\n    ",
  "result": {
    "domain_object_id": "9da77628-2ac5-4965-af12-c7c51cc1d99a",
    "domain_object_type": "Package",
    "roles": [
        "authorized_group_id": null,
        "context": "Package",
        "id": "481b6cd8-350b-4599-bd20-5e3c0ed0a8cb",
        "package_id": "9da77628-2ac5-4965-af12-c7c51cc1d99a",
        "role": "editor",
        "user_id": "4229c297-fe28-4597-a191-3ebbbee6c47a",
        "user_object_role_id": "481b6cd8-350b-4599-bd20-5e3c0ed0a8cb"
        "authorized_group_id": null,
        "context": "Package",
        "id": "aba38fa7-2fb4-4f84-98e1-02cb76c5d95a",
        "package_id": "9da77628-2ac5-4965-af12-c7c51cc1d99a",
        "role": "admin",
        "user_id": "e7f30c0d-944b-4a69-84c4-61b08bbf6b98",
        "user_object_role_id": "aba38fa7-2fb4-4f84-98e1-02cb76c5d95a"
        "authorized_group_id": null,
        "context": "Package",
        "id": "e06b1293-86ec-4417-8e28-b9499161348e",
        "package_id": "9da77628-2ac5-4965-af12-c7c51cc1d99a",
        "role": "reader",
        "user_id": "41cb1162-3d61-4b16-a3af-4cae27836ac5",
        "user_object_role_id": "e06b1293-86ec-4417-8e28-b9499161348e"
  "success": true

Looking at the list of “roles” we can see who has what permissions on this dataset. User with id=”4229...” is an “editor”, id=”e7f3...” is an “admin”, “41cb...” is a “reader”. By using the user_show call to reveal the names of the users, we see that “visitor” (i.e. anyone who is not logged in) is the “reader” (no write permission), “logged-in” (any logged-in user) is the “editor” and the admin is “OKFN” who is the user who created this dataset in the first place and can therefore confer permissions to other users.

Adding permissions

To give user “dread” the “admin” authorization role on dataset “freshwateratlasrivers”:

curl -d '{"user": "dread", "domain_object": "freshwateratlasrivers", "roles": ["admin"]}' -H "Authorization:{your-api-key}"

Javascript examples

See (demo search and count widgets)