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 /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/",
          "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/",
          "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

POST 🔗

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

Language-specific info:
HTTP

POST /projects/ HTTP/1.1

Payload example:

Language-specific info:
JSON

{
    "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 🔗

Language-specific info:
HTTP

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/",
          "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/",
          "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.

Language-specific info:
HTTP

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": {},
      "templates": {
        "powerpoint": "<URL>"
      }
  },
  "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	read-only	Contains three colors, `primary`, `secondary` and `message`, under the `brand` attribute, which are used to theme the project’s account
logo	object	{}	Contains three attributes: `large`, `small` and `favicon`, which are URLs for the different sizes of “branding” logos for the project
templates	object	{}	Object that contains the project-specific templates. Template formats are the keys (currently, only `powerpoint` is supported) and the values are URLs to the template files.

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.

Change project logo 🔗

Language-specific info:
HTTP

POST /projects/abc123/logo/

To set/change the project’s logo the client needs to make a multipart/form-data request containing either or all of the large, small and favicon fields with the desired image files to use. Only project admins are authorized to change this resource.

Language-specific info:
HTTP

POST /projects/abc123/logo/ HTTP/1.1
Content-Type: multipart/form-data; boundary=----------123456789
Content-Length: 500326

----------123456789
Content-Disposition: form-data; name="large"; filename="newlogo.jpg"
Content-Type: image/jpeg

xxxxxxxxxx
----------123456789
Content-Disposition: form-data; name="small"; filename="newlogo_small.jpg"
Content-Type: image/jpeg

xxxxxxxxxx
----------123456789--

HTTP/1.1 204

The server will update the images accordingly. The only valid file extensions are GIF, JPEG, PNG and ICO image files.

Remove project logo 🔗

It is possible to remove the logos that have been set up. To do so, PATCH back the contents of the logo/ resource with the specific logos that need to be removed set to the null value.

Language-specific info:
HTTP

PATCH /projects/abc123/logo/

Language-specific info:
JSON

"element": "shoji:view",
"value": {
  "large": null,
  "small": "<image URL>",
  "favicon": null
}

A 204 response will be returned on success. Only project admins are authorized to remove logos this way.

Change project templates 🔗

Language-specific info:
HTTP

POST /projects/abc123/templates/

To set/change the project templates, the client needs to make a multipart/form-data request containing file fields for any of the supported template formats (currently only powerpoint). Only project editors are authorized to change this resource.

Language-specific info:
HTTP

POST /projects/abc123/templates/ HTTP/1.1
Content-Type: multipart/form-data; boundary=----------123456789
Content-Length: 500326

xxxxxxxxxx
----------123456789
Content-Disposition: form-data; name="powerpoint"; filename="template-powerpoint.pptx"
Content-Type: application/vnd.openxmlformats-officedocument.presentationml.presentation

xxxxxxxxxx
----------123456789--

HTTP/1.1 204

The server will update the templates accordingly. Currently, the only valid file extension is “pptx” for PowerPoint templates.

Remove project templates 🔗

It is possible to remove the templates that have been set up. To do so, PATCH back the contents of the template/ resource with the specific templates that need to be removed set to the null value.

Please note that currently only powerpoint templates are supported. Other template formats might be added in the future.

Language-specific info:
HTTP

PATCH /projects/abc123/templates/

Language-specific info:
JSON

"element": "shoji:view",
"value": {
  "powerpoint": null,
}

A 204 response will be returned on success. Only project editors are authorized to remove templates this way.

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.

Language-specific info:
HTTP

POST /projects/f5c4/ HTTP/1.1

Payload example:

Language-specific info:
JSON

{"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.

Language-specific info:
JSON

{
  "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/",
          "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.

Language-specific info:
HTTP

PATCH /projects/f5c4/ HTTP/1.1

Basic Changes 🔗

Payload example:

Language-specific info:
JSON

{"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:

Language-specific info:
JSON

{
  "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.

Language-specific info:
JSON

{
  "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
          },
          "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
          },
          "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:

Language-specific info:
JSON

{
  "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.

Language-specific info:
HTTP

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 🔗

Language-specific info:
HTTP

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

Language-specific info:
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, removes user 00002, and invites a new user to Crunch (user@email.com). Because send_notification was included and set to true, these users will also receive an email notification about any new access they have been granted.

Note that instead of using the URL for the user, you could instead use their email address. This is particularly helpful if you’re trying to add a user that doesn’t yet have a Crunch account.

Language-specific info:
HTTP

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

Language-specific info:
JSON

{
    "element": "shoji:catalog",
    "index": {
        "send_notification": true,
        "https://app.crunch.io/api/users/00005/": {
            "permissions": {
                "edit": false,
                "view": true
            }
        },
        "https://app.crunch.io/api/users/00002/": null,
        "user@email.com": {"permissions": {"view": true}}
    }
}

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 that one of the users to remove or edit has inherited access through a higher project than the current user has access to, a message on each of those users will be included on the error payload indicating to ask an account admin for assistance.

User has access through other project. Ask an account administrator for assistance
User 00002: []

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.

Language-specific info:
JSON

{
    "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 🔗

Language-specific info:
HTTP

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

Language-specific info:
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
            },
            "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 🔗

Language-specific info:
HTTP

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

Language-specific info:
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.

Language-specific info:
HTTP

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

Language-specific info:
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:

Language-specific info:
JSON

{
    "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 🔗

Language-specific info:
HTTP

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

Language-specific info:
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
            },
            "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",
  "index": {
    "send_notification": true,
    "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": {}
  }
}

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.

Language-specific info:
HTTP

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.

Language-specific info:
HTTP

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