Projects 🔗

Projects represent groups of users that share a common set of datasets. Any user can belong to none or many projects.

They live under /projects/ and will list the projects that the authenticated user is a member or owner of.

Catalog 🔗

The projects catalog will list all the projects the authenticated user is a member of. Here you can create new projects via POST. The catalog will include a body attribute to emulate the body provided by subprojects. The permissions key here indicates whether or not you are able to create projects.

GET 🔗

GET /projects/ HTTP/1.1

{
  "catalogs": {
      "personal": "https://app.crunch.io/api/projects/personal/",
      "shared": "https://app.crunch.io/api/projects/shared/",
  },
  "element": "shoji:catalog",
  "body": {
     "name": "Projects catalog",
     "description": "Displays all the projects you have access to",
     "user_icon": false,
     "owner": "https://app.crunch.io/api/users/a274/",
     "permissions": {
       "edit": true,
       "view": true
     },
     "icon": "",
     "owner_id": "https://app.crunch.io/api/users/a274/"
  },
  "index": {
      "https://app.crunch.io/api/projects/c175/": {
          "description": "Description of Project 2",
          "icon": "",
          "id": "c175",
          "name": "Project 2",
          "account": "https://app.crunch.io/api/accounts/123456/",
          "logo": {
            "small": "<URL>",
            "large": "<URL>",
            "favicon": "<URL>"
          },
          "palette": {},
          "permissions": {
              "edit": true,
              "view": true
          },
          "type": "project"
      },
      "https://app.crunch.io/api/projects/f5c4/": {
          "description": "Description of Project 1",
          "icon": "",
          "id": "f5c4",
          "name": "Project 1",
          "account": "https://app.crunch.io/api/accounts/123456/",
          "logo": {
            "small": "<URL>",
            "large": "<URL>",
            "favicon": "<URL>"
          },
          "palette": {},
          "permissions": {
              "edit": true,
              "view": true
          },
          "type": "project"
      }
  },
  "self": "https://app.crunch.io/api/projects/"
}
Name Type Default Description
name string   Required when creating the project
description string “” Longer description of the project
id string autogenerated The project’s id
icon url “” Url for the icon file for the project. Empty string if not set
permissions object {} permissions possessed by querying user against project
account url “” Url for the account entity that owns the project
palette object {} Contains the three branding-related colors that are used to theme the project
logo object {} Contains the read-only URLs for the branding-related logos for the project

POST 🔗

New projects need a name (no uniqueness enforced) and will make the authenticated user its initial member and editor.

POST /projects/ HTTP/1.1

Payload example:

{
    "element": "shoji:entity",
    "body": {
        "name": "My new project",
        "icon_url": "http://cdn.sample.com/project-icon.png"
    }
}

Creating a project with an icon 🔗

To create one with a starting icon you can POST an icon_url attribute indicating a url where to fetch that icon from (has to be a publicly accessible url).

If the server cannot read that URL the request will return a 409 error.

On success a copy of the file will be stored as the icon to be serve

If the icon_url attribute is not provided the API will pick an available icon from the icons catalog.

Default icon 🔗

The API can provide default icons to be used in new projects. Performing a GET request will return a Shoji:catalog with a list of available icons for the client to pick.

GET /icons/ HTTP/1.1

{
  "element": "shoji:catalog",
  "self": "http://app.crunch.io/api/icons/",
  "index": {
    "http://app.crunch.io/api/icons/01/": {},
    "http://app.crunch.io/api/icons/02/": {},
    "http://app.crunch.io/api/icons/03/": {},
    "http://app.crunch.io/api/icons/04/": {}
  }
}

Personal Project 🔗

All users have a personal project where the datasets they create will reside.

Inside their personal project it is possible to create subprojects via POST using the same creation rules as in the main projects catalog.

The contents (datasets and projects) of the personal project are only visible to their owner, but it is still possible to share the datasets or invite members to any subproject inside your personal project to collaborate with other users.

Note that all the datasets that exist in the personal projects hierarchy will be displayed under the main dataset catalog to the users that have at least view permissions over them.

GET 🔗

GET /projects/personal/ HTTP/1.1

{
  "element": "shoji:catalog",
  "self": "https://app.crunch.io/api/projects/personal/",
  "body": {
     "name": "Personal projects",
     "description": "Aggregates the contents of your personal projects",
     "user_icon": false,
     "owner": "https://app.crunch.io/api/users/b364/",
     "permissions": {
       "edit": true,
       "view": true
     },
     "icon": "",
     "owner_id": "https://app.crunch.io/api/users/b364/"
  },
  "index": {
      "https://app.crunch.io/api/projects/c175/": {
          "description": "Description of my nested project",
          "icon": "",
          "id": "c175",
          "name": "My subproject",
          "account": "https://app.crunch.io/api/accounts/123456/",
          "logo": {
            "small": "<URL>",
            "large": "<URL>",
            "favicon": "<URL>"
          },
          "palette": {},
          "permissions": {
              "edit": true,
              "view": true
          },
          "type": "project"
      },
      "https://app.crunch.io/api/projects/f5c4/": {
          "description": "Description of my other nested project",
          "icon": "",
          "id": "f5c4",
          "name": "My other subproject",
          "account": "https://app.crunch.io/api/accounts/123456/",
          "logo": {
            "small": "<URL>",
            "large": "<URL>",
            "favicon": "<URL>"
          },
          "palette": {},
          "permissions": {
              "edit": true,
              "view": true
          },
          "type": "project"
      }
  }
}

PATCH 🔗

PATCH support on this endpoint only allows moving projects up to the root. It does not allow mass renaming or moving datasets to the root.

To move projects to the personal project it is necessary to PATCH a shoji catalog with the urls of the projects in the index with empty tuples.

PATCH /projects/personal/ HTTP/1.1

{
  "element": "shoji:catalog",
  "index": {
      "https://app.crunch.io/api/projects/abc/": {},
      "https://app.crunch.io/api/projects/def/": {}
  }
}

Entity 🔗

GET 🔗

GET /projects/6c01/ HTTP/1.1

{
  "body": {
      "description": "Description of Project 1",
      "icon": "",
      "id": "f5c4",
      "name": "Project 1",
      "account": "https://app.crunch.io/api/accounts/123456/",
      "owner": "https://app.crunch.io/api/users/00002/",
      "owner_id": "https://app.crunch.io/api/users/00002/",
      "permissions": {
          "edit": true,
          "view": true
      },
      "user_icon": false,
      "logo": {
        "small": "<URL>",
        "large": "<URL>",
        "favicon": "<URL>"
      },
      "palette": {}
  },
  "catalogs": {
      "datasets": "https://app.crunch.io/api/projects/f5c4/datasets/",
      "members": "https://app.crunch.io/api/projects/f5c4/members/",
      "project": "https://app.crunch.io/api/projects/",
      "users": "https://app.crunch.io/api/projects/f5c4/users/",
      "teams": "https://app.crunch.io/api/projects/f5c4/teams/"
  },
  "element": "shoji:entity",
  "index": {},
  "graph": [],
  "orders": {
      "order": "https://app.crunch.io/api/projects/f5c4/datasets/order/"
  },
  "self": "https://app.crunch.io/api/projects/f5c4/",
  "views": {
      "icon": "https://app.crunch.io/api/projects/f5c4/icon/"
  }
}
Name Type Default Description
name string   Required when creating the project
description string “” Longer description of the project
id string autogenerated The project’s id
icon url “” Url for the icon file for the project. Empty string if not set
user_icon boolean autogenerated Will indicate false if the icon used on creation is from the provided catalog
account url “” Url for the account entity that owns the project
palette object {} Contains three colors, primary, secondary and message, under the brand attribute, which are used to theme the project
logo object {} Contains three attributes: large, small and favicon, which are URLs for the different sizes of “branding” logos for the project

Note about the icon attribute that points to the actual image file where the configured icon is. This url does not point to the views.icon Shoji view url.

The views.icon Shoji view endpoint is used to PUT the icon as a file upload for this project.

Branding configuration for the project is exposed here through the palette and logo attributes.

POST 🔗

It is possible to create nested projects within a project using the POST method. The nested projects will be present in the index attribute of the parent project identified by the type: project.

POST /projects/f5c4/ HTTP/1.1

Payload example:

{"element": "shoji:entity", "body": {"name": "Nested Project"}}

Note that a GET on the parent project now contains the nested project in the index and graph attributes.

{
  "body": {
      "description": "",
      "icon": "",
      "id": "f5c4",
      "name": "Project 1",
      "account": "https://app.crunch.io/api/accounts/123456/",
      "owner": "https://app.crunch.io/api/users/00002/",
      "owner_id": "https://app.crunch.io/api/users/00002/",
      "permissions": {
          "edit": true,
          "view": true
      },
      "user_icon": false,
      "logo": {
        "small": "<URL>",
        "large": "<URL>",
        "favicon": "<URL>"
      },
      "palette": {}
  },
  "catalogs": {
      "datasets": "https://app.crunch.io/api/projects/f5c4/datasets/",
      "members": "https://app.crunch.io/api/projects/f5c4/members/",
      "project": "https://app.crunch.io/api/projects/",
      "users": "https://app.crunch.io/api/projects/f5c4/users/",
      "teams": "https://app.crunch.io/api/projects/f5c4/teams/"
  },
  "element": "shoji:entity",
  "graph": [
      "https://app.crunch.io/api/projects/6ba6/"
  ],
  "index": {
      "https://app.crunch.io/api/projects/6ba6/": {
          "description": "",
          "icon": "",
          "id": "6ba6",
          "name": "Nested Project",
          "account": "https://app.crunch.io/api/accounts/123456/",
          "logo": {
            "small": "<URL>",
            "large": "<URL>",
            "favicon": "<URL>"
          },
          "palette": {},
          "permissions": {
              "edit": true,
              "view": true
          },
          "type": "project"
      }
  },
  "orders": {
      "order": "https://app.crunch.io/api/projects/f5c4/datasets/order/"
  },
  "self": "https://app.crunch.io/api/projects/f5c4/",
  "views": {
      "icon": "https://app.crunch.io/api/projects/f5c4/icon/"
  }
}

PATCH 🔗

The attributes that are allowed to be edited for a project are:

  • name
  • description
  • icon_url
  • index
  • graph

Only project editors can make these changes.

PATCH /projects/f5c4/ HTTP/1.1

Basic Changes 🔗

Payload example:

{"name": "Renamed Project"}

Index Changes 🔗

You can move datasets and projects to a parent project via the index attribute. Note that you cannot remove items via the index. To remove a dataset or project from a parent project, move them to a new project.

Payload example:

{
  "index": {
      "https://app.crunch.io/api/datasets/976d/": {},
      "https://app.crunch.io/api/projects/c175/": {}
  },
  "element": "shoji:entity"
}

Note that a GET on the parent project now contains the nested project and dataset in the index and graph attributes. Datasets in the project index can be distinguished from nested projects by their type attribute. Datasets will have type: dataset, and nested projects will have type: project.

{
  "body": {
      "description": "",
      "icon": "",
      "id": "f5c4",
      "name": "Project 1",
      "account": "https://app.crunch.io/api/accounts/123456/",
      "owner": "https://app.crunch.io/api/users/00002/",
      "owner_id": "https://app.crunch.io/api/users/00002/",
      "permissions": {
          "edit": true,
          "view": true
      },
      "user_icon": false,
      "logo": {
        "small": "<URL>",
        "large": "<URL>",
        "favicon": "<URL>"
      },
      "palette": {}
  },
  "catalogs": {
      "datasets": "https://app.crunch.io/api/projects/f5c4/datasets/",
      "members": "https://app.crunch.io/api/projects/f5c4/members/",
      "project": "https://app.crunch.io/api/projects/",
      "users": "https://app.crunch.io/api/projects/f5c4/users/",
      "teams": "https://app.crunch.io/api/projects/f5c4/teams/"
  },
  "element": "shoji:entity",
  "graph": [
      "https://app.crunch.io/api/projects/6ba6/",
      "https://app.crunch.io/api/projects/c175/",
      "https://app.crunch.io/api/datasets/976d/"
  ],
  "index": {
      "https://app.crunch.io/api/datasets/976d/": {
          "access_time": "2018-08-09T19:52:38.816000+00:00",
          "archived": false,
          "creation_time": "2018-08-09T19:52:38.901000+00:00",
          "current_editor": "https://app.crunch.io/api/users/00002/",
          "current_editor_name": "Jean-Luc Picard",
          "description": "",
          "end_date": null,
          "id": "976d",
          "is_published": true,
          "modification_time": "2018-08-09T19:52:38.848000+00:00",
          "name": "Dataset 1",
          "account": "https://app.crunch.io/api/accounts/123456/",
          "owner_id": "https://app.crunch.io/api/projects/f5c4/",
          "owner_name": "Project 1",
          "permissions": {
              "edit": true,
              "view": true
          },
          "size": {
              "columns": 0,
              "rows": 0,
              "unfiltered_rows": 0
          },
          "start_date": null,
          "streaming": "no",
          "type": "dataset"
      },
      "https://app.crunch.io/api/projects/6ba6/": {
          "description": "",
          "icon": "",
          "id": "6ba6",
          "name": "Nested Project",
          "account": "https://app.crunch.io/api/accounts/123456/",
          "permissions": {
              "edit": true,
              "view": true
          },
          "logo": {
            "small": "<URL>",
            "large": "<URL>",
            "favicon": "<URL>"
          },
          "palette": {},
          "type": "project"
      },
      "https://app.crunch.io/api/projects/c175/": {
          "description": "",
          "icon": "",
          "id": "c175",
          "name": "Project 2",
          "account": "https://app.crunch.io/api/accounts/123456/",
          "permissions": {
              "edit": true,
              "view": true
          },
          "logo": {
            "small": "<URL>",
            "large": "<URL>",
            "favicon": "<URL>"
          },
         "palette": {},
          "type": "project"
      }
  },
  "orders": {
      "order": "https://app.crunch.io/api/projects/f5c4/datasets/order/"
  },
  "self": "https://app.crunch.io/api/projects/f5c4/",
  "views": {
      "icon": "https://app.crunch.io/api/projects/f5c4/icon/"
  }
}

Graph Changes 🔗

You can reorder the datasets and nested projects by editing the graph attribute. The graph attribute must contain all items found in the index.

Payload example:

{
  "graph": [
      "https://app.crunch.io/api/datasets/976d/",
      "https://app.crunch.io/api/projects/c175/",
      "https://app.crunch.io/api/projects/6ba6/"
  ],
  "element": "shoji:entity"
}

DELETE 🔗

Deleting a project will NOT delete its datasets. It will change their ownership to the authenticated user. Only the project current owner can delete a project.

DELETE /projects/6c01/ HTTP/1.1

Project Users 🔗

The project users catalog allows you to see which users have access to the contents of a project (including nested projects and datasets).

  • /projects/{project_id}/users/

Users will either have edit, view, or mixed access to a project.

Permission Description
view The user is a member of the project with view permissions, or the user is a member of a team with view access to the project. Note that project permissions are also inherited from parent projects.
edit The user is a member of the project with edit permissions, or the user is a member of a team with edit access to the project. Note that project permissions are also inherited from parent projects.
mixed The user doesn’t have direct access to this project, but has access to a dataset or nested project under this project. This includes nested datasets within this project tree that have been shared directly with a user or a team that the user is a member of.

The project user context allows you to see what access a user has to the contents of a project (projects and datasets).

  • /projects/{project_id}/users/{user_id}/

Users will either have edit, view, mixed or no access to the nested projects, and either edit, view, or no access to the nested datasets.

The following table describes the permission flags that will be returned for each access level.

Permission Flags
view {"view": true, "edit": false, "mixed": false}
edit {"view": true, "edit": true, "mixed": false}
mixed {"view": false, "edit": false, "mixed": true}
no access {"view": false, "edit": false, "mixed": false}

Catalog 🔗

Referred to as the project users catalog.

/projects/{project_id}/users/

GET 🔗

GET /projects/6c01/users/ HTTP/1.1
Host: app.crunch.io
--------
200 OK
Content-Type: application/json

{
    "element": "shoji:catalog",
    "index": {
        "https://app.crunch.io/api/projects/6c01/users/00005/": {
            "access_time": null,
            "collaborator": true,
            "email": "firstofficer@crunch.io",
            "name": "William Riker",
            "permissions": {
                "edit": false,
                "mixed": true,
                "view": false
            },
            "account_permissions": {
                "admin_account": false,
                "create_datasets": false,
            },
            "user": "https://app.crunch.io/api/users/00005/"
        },
        "https://app.crunch.io/api/projects/6c01/users/00002/": {
            "access_time": "2019-05-22T15:37:12.891000+00:00",
            "collaborator": false,
            "email": "captain@crunch.io",
            "name": "Jean-Luc Picard",
            "permissions": {
                "edit": true,
                "mixed": false,
                "view": true
            },
            "account_permissions": {
                "admin_account": false,
                "create_datasets": true,
            },
            "user": "https://app.crunch.io/api/users/00002/"
        }
    },
    "self": "https://app.crunch.io/api/projects/6c01/users/"
}

PATCH 🔗

This endpoint supports PATCH to add or remove users from the project.

To add users, send their user url in the index object containing an object with a permissions object that has the flags. It will grant such access for this user on this project.

To remove a user PATCH its tuple with a null value. It will remove any access that this user has been granted directly on this project, any of the subprojects or any dataset anywhere down this branch of the projects structure.

If the user has access to this project via permissions obtained on a parent project, then the request will fail with a 400 error indicating the parent projects where the access is granted. Clients should retry removing the access from the highest level parent to ensure full access clearing.

On a successful PATCH the server will return a 200 response with a shoji catalog in the body. This shoji catalog will be keyed by each of the users that were deleted on this request and the tuple will contain a teams key pointing to all the teams where each user belongs that has access to some resource down this project branch. Clients should decide if they wish to remove the user from the team or remove the access to the team (affecting all team users).

The following example adds user with id 00005 and remove user 00002.

PATCH /projects/6c01/users/ HTTP/1.1
Host: app.crunch.io
--------
200 OK
Content-Type: application/json

{
    "element": "shoji:catalog",
    "self": "https://app.crunch.io/api/projects/6c01/users/",
    "index": {
        "https://app.crunch.io/api/users/00005/": {
            "permissions": {
                "edit": false,
                "view": true
            }
        },
        "https://app.crunch.io/api/users/00002/": null
    }
}

If user https://app.crunch.io/api/users/00002/ has access through any parent, then the full request would error and no changes would be made, so user https://app.crunch.io/api/users/00005/ wouldn’t be added to the project. The error message would include information about the parent projects:

Cannot delete the following because they have inherited permissions:
User 00002: https://app.crunch.io/api/projects/abcd/

In the case the request finishes successfully, the response’s body will contain the following shoji index indicating the teams through which the removed users still have access to elements down this project branch.

{
    "element": "shoji:catalog",
    "self": "https://app.crunch.io/api/projects/6c01/users/",
    "index": {
        "https://app.crunch.io/api/users/00002/": {
            "teams": ["https://app.crunch.io/api/teams/1234/"]
        }
    }
}

Entity 🔗

Referred to as the the project user context.

/projects/{project_id}/users/{user_id}/

GET 🔗

GET projects/6c01/users/00002/ HTTP/1.1
Host: app.crunch.io
--------
200 OK
Content-Type: application/json

{
    "views": {
        "project": "https://app.crunch.io/api/projects/6c01/",
        "user": "https://app.crunch.io/api/users/00002/"
    },
    "element": "shoji:entity",
    "index": {
        "https://app.crunch.io/api/datasets/abc/": {
            "access_time": "2019-02-28T17:16:05.621000",
            "modification_time": "2019-02-28T17:15:48.910000",
            "permissions": {
                "edit": true,
                "mixed": false,
                "view": true
            },
            "type": "dataset",
            "name": "Dataset ABC"
        },
        "https://app.crunch.io/api/projects/123/": {
            "access_time": "2019-02-28T17:16:11.065000",
            "modification_time": "2019-02-28T17:15:17.825000",
            "permissions": {
                "edit": true,
                "mixed": false,
                "view": true
            },
            "logo": {
              "small": "<URL>",
              "large": "<URL>",
              "favicon": "<URL>"
            },
            "palette": {},
            "type": "project",
            "name": "Project 123"
        },
        "https://app.crunch.io/api/projects/456/": {
            "access_time": "2019-02-28T17:14:33.014000",
            "modification_time": "2019-02-28T17:14:32.044000",
            "permissions": {
                "edit": true,
                "mixed": false,
                "view": true
            },
            "type": "project",
            "name": "Project 456"
        }
    },
    "self": "https://app.crunch.io/api/projects/6c01/users/00002/"
}

Project teams 🔗

The project teams catalog displays all the teams that have access to this project (including nested projects and datasets). This catalog has the same behavior as the project users catalog does for users, but for teams.

  • /projects/{project_id}/teams/

Same as with users on the project admin catalog, teams can have edit, view or mixed access to the project.

Following each of the entities in the catalog for any team, will display the detail of access that the team in question has to any of the particular children of this project.

  • /projects/{project_id}/teams/{team_id}/

Catalog 🔗

Referred to as the project teams catalog.

/projects/{project_id}/teams/

GET 🔗

GET /projects/6c01/teams/ HTTP/1.1
Host: app.crunch.io
--------
200 OK
Content-Type: application/json

{
    "element": "shoji:catalog",
    "index": {
        "https://app.crunch.io/api/projects/6c01/teams/abc123/": {
            "id": "abc123",
            "name": "Team 1",
            "permissions": {
                "edit": false,
                "mixed": true,
                "view": false
            },
            "team": "https://app.crunch.io/api/teams/abc123/"
        },
        "https://app.crunch.io/api/projects/6c01/teams/abc456/": {
            "id": "abc456",
            "name": "Team 2",
            "permissions": {
                "edit": true,
                "mixed": false,
                "view": true
            },
            "team": "https://app.crunch.io/api/teams/00002/"
        }
    },
    "self": "https://app.crunch.io/api/projects/6c01/users/"
}

PATCH 🔗

This endpoint supports PATCH to add or remove teams from the project.

Sames as with project users catalog, to add a new team send its URL to the index with an object containing a permissions object and the needed (edit and view) flags in it to grant such access to such team.

To remove a team, PATCH the same tuple but send null for such team’s value. Will remove this team from this project and any subproject below.

The server will return a 200 response on success with an empty shoji index, the same response from the project users catalog, but this index will always be empty.

The following example adds team with id 00010 and removes team 00020.

PATCH /projects/8df1/teams/ HTTP/1.1
Host: app.crunch.io
--------
200 OK
Content-Type: application/json

{
    "element": "shoji:catalog",
    "self": "https://app.crunch.io/api/projects/8df1/teams/",
    "index": {
        "https://app.crunch.io/api/teams/00010/": {
            "permissions": {
                "edit": false,
                "view": true
            }
        },
        "https://app.crunch.io/api/teams/00020/": null
    }
}

The 200 response will contain the following body:

{
    "element": "shoji:catalog",
    "self": "https://app.crunch.io/api/projects/8df1/teams/",
    "index": {}
}

Entity 🔗

Referred to as the the project team context.

/projects/{project_id}/teams/{team_id}/

GET 🔗

GET projects/6c01/teams/abc123/ HTTP/1.1
Host: app.crunch.io
--------
200 OK
Content-Type: application/json

{
    "views": {
        "project": "https://app.crunch.io/api/projects/6c01/",
        "team": "https://app.crunch.io/api/teams/abc123/"
    },
    "element": "shoji:entity",
    "index": {
        "https://app.crunch.io/api/datasets/abc/": {
            "access_time": "2019-02-28T17:16:05.621000",
            "modification_time": "2019-02-28T17:15:48.910000",
            "permissions": {
                "edit": true,
                "mixed": false,
                "view": true
            },
            "type": "dataset",
            "name": "Dataset ABC"
        },
        "https://app.crunch.io/api/projects/123/": {
            "access_time": "2019-02-28T17:16:11.065000",
            "modification_time": "2019-02-28T17:15:17.825000",
            "permissions": {
                "edit": true,
                "mixed": false,
                "view": true
            },
            "logo": {
              "small": "<URL>",
              "large": "<URL>",
              "favicon": "<URL>"
            },
            "palette": {},
            "type": "project",
            "name": "Project 123"
        },
        "https://app.crunch.io/api/projects/456/": {
            "access_time": "2019-02-28T17:14:33.014000",
            "modification_time": "2019-02-28T17:14:32.044000",
            "permissions": {
                "edit": true,
                "mixed": false,
                "view": true
            },
            "type": "project",
            "name": "Project 456"
        }
    },
    "self": "https://app.crunch.io/api/projects/6c01/teams/abc123/"
}

Members 🔗

Use this endpoint to manage the users that have access to this project.

Members permissions 🔗

Members of a project can be wither viewers or editors. By default all members will be viewers and a selected group of them (at least one) will be editor.

These permissions are available on the members catalog under the permissions attribute on each member’s tuple.

The possible permissions are:

  • edit
  • view

That can have boolean values. Those with edit: true are considered project editors.

Project editors have edit privileges on all datasets as well as permissions to make changes on the project itself such as changing its name, icon, members management or change members’ permissions.

GET 🔗

Returns a catalog with all users that have access to this project and their project permissions in the following format:

GET /projects/abcd/members/ HTTP/1.1

{
  "element": "shoji:catalog",
  "self": "http://app.crunch.io/api/projects/6c01/members/",
  "index": {
    "http://app.crunch.io/api/users/00002/": {
      "name": "Jean-Luc Picard",
      "email": "captain@crunch.io",
      "permissions": {
        "edit": true,
        "view": true
      },
      "allowed_dataset_permissions": {
        "edit": true,
        "view": true
      }
    },
    "http://app.crunch.io/api/users/00005/": {
      "name": "William Riker",
      "email": "firstofficer@crunch.io",
      "permissions": {
        "edit": false,
        "view": true
      },
      "allowed_dataset_permissions": {
        "edit": false,
        "view": true
      }
    }
  }
}

The catalog will be indexed by each user’s entity URL and its tuple will contain basic information (name and email) as well as the permissions each user has on the given project.

All project members have read access to this resource, but the allowed_dataset_permissions is only present to project editors. It contains the maximum dataset permissions each user can have. Assigning anything more permissive will not have effect.

PATCH 🔗

Use this method to add or remove members from the project. Only project editors have this capabilities, else you will get a 403 response.

To add a new user, PATCH a catalog keyed by the new user URL and an empty object for its value or a permissions tuple to set specific permissions (only edit allowed at this point).

To remove users, PATCH a catalog keyed by the user you want to remove and null for its value.

Note that you cannot remove yourself from the project, you will get a 400 response.

It is possible to perform many additions/removals in one request, the following example adds users /users/001/ and deletes users /users/002/

It is allowed to invite/add users to the project by email address. If the email is registered on the system the user will be invited to the project. If the email is not part of Crunch.io a new user invitation will be sent to that email with instructions to set up their account. They will be automatically part of this project only.

Attempting to remove users also allows to do so by email. In the case that the email does not exist, the server will return a 400 response.

PATCH /projects/abcd/members/ HTTP/1.1

{
  "element": "shoji:catalog",
  "self": "http://app.crunch.io/api/projects/6c01/members/",
  "index": {
    "http://app.crunch.io/api/users/001/": {},
    "http://app.crunch.io/api/users/002/": {
      "permissions": {
        "edit": true
      }
    },
    "http://app.crunch.io/api/users/003/": null,
    "user@email.com": {},
    "send_notification": true
  }
}

Sending notifications 🔗

The users invited to a project can be both existing Crunch.io users or new users that don’t have a user account associated with the email.

If desired, the API can send automated email notifications to the involved users indicating that they now belong to the project.

It is necessary to add the send_notification boolean key on the index PATCHed to command the API to send these emails. Else, no notification will be sent.

Datasets 🔗

Will list all the datasets that have this project as their owner.

Adding datasets to projects 🔗

The way to add a dataset to a project is by changing the dataset’s owner to the id of the project you want to take ownership.

You must have edit and be current editor on any given dataset to change its owner and you must also have edit permissions on the target project.

PATCH to dataset entity 🔗

Send a PATCH request to the dataset entity that you want to make part of the project.

PATCH /datasets/cc9161/ HTTP/1.1

{"owner":"https://app.crunch.io/api/projects/abcd/"}

GET 🔗

Will show the list of all datasets where this project is their owner, the shape of the dataset tuple will be the same as in other dataset catalogs.

GET /projects/6c01/datasets/ HTTP/1.1

{
  "element": "shoji:catalog",
  "self": "http://app.crunch.io/api/projects/6c01/datasets/",
  "orders": {
    "order": "http://app.crunch.io/api/projects/6c01/datasets/order/"
  },
  "index": {
    "https://app.crunch.io/api/datasets/cc9161/": {
        "owner_name": "James T. Kirk",
        "name": "The Voyage Home",
        "description": "Stardate 8390",
        "archived": false,
        "account": "https://app.crunch.io/api/accounts/123456/",
        "permissions": {
            "edit": false,
            "view": true
        },
        "size": {
            "rows": 1234,
            "columns": 67
        },
        "id": "cc9161",
        "owner_id": "https://app.crunch.io/api/users/685722/",
        "start_date": "2286",
        "end_date": null,
        "streaming": "no",
        "creation_time": "1986-11-26T12:05:00",
        "modification_time": "1986-11-26T12:05:00",
        "current_editor": "https://app.crunch.io/api/users/ff9443/",
        "current_editor_name": "Leonard Nimoy"
    },
    "https://app.crunch.io/api/datasets/a598c7/": {
        "owner_name": "Spock",
        "name": "The Wrath of Khan",
        "description": "",
        "archived": false,
        "account": "https://app.crunch.io/api/accounts/123456/",
        "permissions": {
            "edit": true,
            "view": true
        },
        "size": {
            "rows": null,
            "columns": null
        },
        "id": "a598c7",
        "owner_id": "https://app.crunch.io/api/users/af432c/",
        "start_date": "2285-10-03",
        "end_date": "2285-10-20",
        "streaming": "no",
        "creation_time": "1982-06-04T09:16:23.231045",
        "modification_time": "1982-06-04T09:16:23.231045",
        "current_editor": null,
        "current_editor_name": null
    }
  }
}

Icon 🔗

The icon endpoint for a project is a ShojiView that allows to change the project’s icon via file upload or URL.

GET 🔗

On GET, it will return a shoji:view with its value containing a url to the icon file or empty string in case there isn’t an icon for this project yet.

By default all new projects have an empty icon URL.

GET /projects/6c01/icon/ HTTP/1.1

{
  "element": "shoji:view",
  "self": "http://app.crunch.io/api/projects/6c01/icon/",
  "value": ""
}

PUT 🔗

PUT to this endpoint to change a project’s icon.

There are two ways to change the icon, either via file upload or via icon URL.

Only the project’s editors can change the project’s icon.

Valid image extensions: ‘png’, ‘gif’, ‘jpg’, ‘jpeg’ - Others will 400

File upload 🔗

The request should have be a standard multipart/form-data file upload with the file field named icon. The file’s contents will be stored and made available under the project’s url. The API will return a 201 response with the stored icon’s URL on its Location header.

PUT /projects/6c01/icon/ HTTP/1.1
Content-Disposition: form-data; name="icon"; filename="newicon.jpg"
Content-Type: image/jpeg

HTTP/1.1 201 Created
Location: https://app.crunch.io/api/datasets/223fd4/

Icon URL 🔗

Expects a Shoji:view request with its value pointing to a publicly accessible image resource that will be used as the project’s icon. This image will be copied to an API local location.

PUT /projects/6c01/datasets/icon/ HTTP/1.1

{
  "element": "shoji:view",
  "self": "http://app.crunch.io/api/projects/6c01/datasets/icon/",
  "value": "http://public.domain.com/icon.png"
}

HTTP/1.1 201 Created
Location: https://app.crunch.io/api/datasets/223fd4/

POST 🔗

Same as PUT

Datasets order 🔗

Contains the shoji:order in which the datasets of this project are to be ordered.

This is endpoint available for all project members but can only be updated by the project’s editors.

GET 🔗

Will return the shoji:order response containing the datasets that belong to the project.

GET /projects/6c01/datasets/order/ HTTP/1.1

{
  "element": "shoji:order",
  "self": "http://app.crunch.io/api/projects/6c01/datasets/order/",
  "graph": [
    "https://app.crunch.io/api/datasets/cc9161/",
    "https://app.crunch.io/api/datasets/a598c7/"
  ]
}

PUT 🔗

Allow to make modifications to the shoji:order for the contained datasets. Only the project’s editors can make these changes.

Trying to include an invalid dataset or an incomplete list will return a 400 response.

PUT /projects/6c01/datasets/order/ HTTP/1.1