WorkspaceNew - Huddle/huddle-apis GitHub Wiki

Summary

The Membership Workspaces API covers workspace lifecycle and related resources (managers, users, teams, invitations, search).

Examples use the /membership path prefix (typical API gateway mapping). The underlying service may mount the same routes without that prefix.

People exposes read-oriented workspace documents and company workspace lists — see Workspaces. On a People workspace, teams and bulkInvitation links may point at Membership when workspace-invite is enabled; follow each link’s href.

Operations

Method	Path	Purpose	Details
`GET`	`/membership/workspaces/{workspaceId}`	Retrieving a workspace	Jump
`GET`	`/membership/workspaces`	Retrieving user workspaces	Jump
`POST`	`/membership/workspaces`	Create a workspace	Jump
`POST`	`/membership/workspaces`	Create a workspace (Template)	Jump
`POST`	`/membership/workspaces/{workspaceId}/leave`	Leave a workspace	Jump
`GET`	`/membership/workspaces/{workspaceId}/managers`	Retrieving workspace managers	Jump
`POST`	`/membership/workspaces/{workspaceId}/managers`	Add workspace managers	Jump
`DELETE`	`/membership/workspaces/{workspaceId}/managers/{userId}`	Remove workspace managers	Jump
`GET`	`/membership/workspaces/{workspaceId}/users`	Retrieve workspace users	Jump
`GET`	`/membership/workspaces/{workspaceId}/users/{userId}`	Retrieve workspace user	Jump
`GET`	`/membership/workspaces/{workspaceId}/users/{userId}/teams`	Retrieving User Teams	Jump
`POST`	`/membership/workspaces/{workspaceId}/users/{userId}`	Update Workspace User	Jump
`DELETE`	`/membership/workspaces/{workspaceId}/users/{userId}`	Remove a user from a workspace	Jump
`POST`	`/membership/workspaces/{workspaceId}/invitations/bulk`	Bulk invitations to workspaces	Jump

Retrieve a Workspace

You can GET a given Workspace by its ID.

Example

Example request, asking for the Workspace with ID 123:

GET /membership/workspaces/123 HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "parent", "href": "..." },
    { "rel": "leave", "href": "..." },
    { "rel": "teams", "href": "..." },
    { "rel": "managers", "href": "..." }
  ],
  "name": "My Important Workspace",
  "createdDate": "2014-07-04T14:13:57.447Z"
}

Response Properties

Name	Description
name	The name of the workspace
createdDate	The date the workspace was created

Response Link relations

Name	Description	Methods
self	The URI of this Workspace.	GET
parent	The URI of the Account the Workspace belongs to.	GET
leave	The URI to leave this Workspace.	POST
teams	The URI to request the list of Teams for the Workspace.	GET
managers	The URI to request the list of Managers for the Workspace.	GET

Other Responses

Case	Response
Invalid authorization token	401 Unauthorized
Actor is not an authorised user	403 Forbidden
Workspace does not exist	404 Not Found

Retrieve User Workspaces

Gets all workspaces the authorised user has access to.

Example

An example of a request to get all workspaces accessible to an authorised user.

Request

GET /membership/workspaces HTTP/1.1
Accept: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

Request Properties

There is no request body and therefore no request properties for this API endpoint.

Response

HTTP/1.1 200 Ok
Content-Type: application/json

{
    "links": [
        {"rel" : "self", "href" : "..."},
        {"rel" : "parent", "href" : "..."}
    ],
    "workspaces": [
        {
            "links": [
                ...

            ],
            "name": "Workspace 1",
            "createdDate": "2019-12-11T00:00:00.000Z"
        },
        {
            "links": [
                ...

            ],
            "name": "Workspace 2",
            "createdDate": "2019-12-10T00:00:00.000Z"
        }
    ]
}

Response Properties

Name	Description
workspaces	Individual links to each workspace the authorised user has access to

Response Link relations

See Retrieving a workspace

Other Responses

Refer to General HTTP Status Codes.

Below are responses related to this resource

Case	Response
Invalid authorization token	401 Unauthorized

Create a Workspace

Workspaces can be created by account managers - or any account member if the account is configured to allow anyone to create workspaces.

The workspace creator will be added as a workspace manager of the new workspace by default.

Example

Request

POST /membership/accounts/456/workspaces HTTP/1.1
Content-Type: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "name": "My first workspace!",
  "description": "My first workspace description"
}

Response

HTTP/1.1 201 Created
Content-Type: application/vnd.huddle.data+json
Location: .../membership/workspaces/12345

{
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "parent", "href": "..." },
    { "rel": "leave", "href": "..." },
    { "rel": "teams", "href": "..." },
    { "rel": "managers", "href": "..." }
  ],
  "name": "My first workspace!",
  "description": "My first workspace description",
  "createdDate": "2019-05-04T14:13:57.447Z"
}

Response Properties

Name	Description
name	The name of the workspace
description	The description of the workspace
createdDate	The date the workspace was created

Other Responses

Refer to General HTTP Status Codes.

Below are responses related to this resource

Case	Response
Invalid authorization token	401 Unauthorized
Account does not exist	404 Not Found
Actor is not an authorised user	403 Forbidden

Create a Workspace Using Another Workspace As a Template

Request

POST /membership/accounts/456/workspaces HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "name": "My first workspace!",
  "description": "My first workspace description",
  "template": {
    "sourceWorkspace": ".../workspaces/12345",
    "copyFolders": true,
    "copyDocuments": true,
    "copyTasks": true,
    "dueDateOfFirstTask": "2019-12-06",
    "copyTeams": true
  }
}

dueDateOfFirstTask accepts date according to ISO 8601 format.

Response

HTTP/1.1 201 Created
Content-Type: application/vnd.huddle.data+json
Location: .../membership/workspaces/12346

{
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "parent", "href": "..." },
    { "rel": "leave", "href": "..." },
    { "rel": "teams", "href": "..." },
    { "rel": "managers", "href": "..." }
  ],
  "name": "My first workspace!",
  "createdDate": "2019-12-06T00:00:00.000Z"
}

Response Properties

Name	Description
name	The name of the workspace
description	The description of the workspace
createdDate	The date the workspace was created

Other Responses

Refer to General HTTP Status Codes.

Below are responses related to this resource

Case	Response
Invalid authorization token	401 Unauthorized
Account does not exist	404 Not Found
Actor is not an authorised user	403 Forbidden

Leave a Workspace

Request

POST /membership/workspaces/123/leave HTTP/1.1
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

HTTP/1.1 202 Accepted

Other Responses

Refer to General HTTP Status Codes.

Below are responses related to this resource

Case	Response
Invalid authorization token	401 Unauthorized
Workspace does not exist	404 Not Found

Retrieve Workspace managers

You can GET all workspace managers and the metadata of the managers in a workspace.

Example

Example request, asking for the Workspace managers from the Workspace with ID 123:

GET /membership/workspaces/123/managers HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
  "links" : [
    { "rel" : "self", "href" : "..." },
    { "rel" : "parent", "href" : "..." },
    { "rel" : "add-managers", "href" : "..." },
    { "rel" : "remove-managers", "href" : "..." },
    { "rel" : "first", "href" : "..." },
    { "rel" : "previous", "href" : "..." },
    { "rel" : "next", "href" : "..." }
  ],
  "managers" : [
    {
      "name" : "Peter Parker",
      "email" : "[email protected]",
      "links" : [
            { "rel" : "self", "href" : "..." },
            { "rel" : "avatar", "href" : "..." },
            { "rel" : "alternate", "href": "..." }
      ]
    },
    ...
  ]
}

Response Properties

Name	Description
managers	The list of managers for the given workspace

Response Link relations

Property	Name	Description	Methods
	self	The URI of the workspace managers collection.	GET
	parent	The URI of the Workspace that the managers belongs to.	GET
	add-managers	The URI to add managers to the Workspace.	POST
	remove-managers	The URI to remove managers from the Workspace.	POST
	first	The URI of the first page of managers.	GET
	previous	The URI of the previous page of managers.	GET
	next	The URI of the next page of managers.	GET
managers	self	The URI of the user	GET
managers	avatar	The URI of the user's avatar	GET
managers	alternate	The URI of the user's profile	GET

Other Responses

Case	Response
Invalid authorization token	401 Unauthorized
Actor is not an authorised user	403 Forbidden
Workspace does not exist	404 Not Found

Filters

Query string parameters are used to filter the managers in a workspace. Returns empty list of managers if no managers were found that match your query.

Request:

GET /membership/workspaces/123/managers?q=jon&pagesize=20&skip=0 HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Parameter	Default value	Additional notes
`q`		Match a workspace manager on `firstname`, `lastname`, `email`
`pagesize`	`20`
`skip`	`0`

Response shape is the same as in Retrieve Workspace Managers

Add Workspace Managers

You can add managers to a workspace.

Example

Example request to add workspace managers for the Workspace with ID 123:

POST /membership/workspaces/123/managers/add HTTP/1.1
Content-Type: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "links" : [
    { "rel" : "manager", "href" : "..." },
    ...
  ]
}

Example response

If successful, this method will return with a 200 OK status code. The response body will be the updated Workspace Manager collection. This response uses the standard error codes and returns standard response headers.

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
Content-Location: /membership/workspaces/123/managers

{
  "links" : [
    { "rel" : "self", "href" : "..." },
    { "rel" : "parent", "href" : "..." },
    { "rel" : "add-managers", "href" : "..." },
    { "rel" : "remove-managers", "href" : "..." },
    { "rel" : "first", "href" : "..." },
    { "rel" : "previous", "href" : "..." },
    { "rel" : "next", "href" : "..." }
  ],
  "managers" : [
    {
      "name" : "Peter Parker",
      "email" : "[email protected]",
      "links" : [
            { "rel" : "self", "href" : "..." },
            { "rel" : "avatar", "href" : "..." },
            { "rel" : "alternate", "href": "..." }
      ]
    },
    ...
  ]
}

Response Properties

Name	Description
rel	The relationship of the resource for the given context
href	The URI of the specified resource

Other Responses

Case	Response
Invalid authorization token	401 Unauthorized
Actor is not an authorised user	403 Forbidden
Workspace does not exist	404 Not Found
User/s manager/s does not exist	404 Not Found

Remove Workspace Managers

You can remove managers from a workspace.

Example

Example request for removing workspace managers from the workspace with ID 123:

POST /membership/workspaces/123/managers/remove HTTP/1.1
Content-Type: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "links" : [
    { "rel" : "manager", "href" : "..." },
    ...
  ]
}

Example response

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
Content-Location: /membership/workspaces/123/managers

{
  "links" : [
    { "rel" : "self", "href" : "..." },
    { "rel" : "parent", "href" : "..." },
    { "rel" : "add-managers", "href" : "..." },
    { "rel" : "remove-managers", "href" : "..." },
    { "rel" : "first", "href" : "..." },
    { "rel" : "previous", "href" : "..." },
    { "rel" : "next", "href" : "..." }
  ],
  "managers" : [
    {
      "name" : "Joseph Alligator",
      "email" : "[email protected]",
      "links" : [
            { "rel" : "self", "href" : "..." },
            { "rel" : "avatar", "href" : "..." },
            { "rel": "alternate", "href": "..." }
      ]
    },
    ...
  ]
}

Response Properties

Name	Description
rel	The relationship of the resource for the given context
href	The URI of the specified resource

Other Responses

Case	Response
Invalid authorization token	401 Unauthorized
Actor is not an authorised user	403 Forbidden
Workspace does not exist	404 Not Found
User/s manager/s does not exist	404 Not Found

Retrieve Workspace users

You can GET all workspace users and their associated metadata.

Example

Example request, asking for the Workspace users from the Workspace with ID 123:

GET /membership/workspaces/123/users HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
  "users" : [
    {
      "name" : "Peter Parker",
      "email" : "[email protected]",
      "lastLogin" : "2020-03-03T00:00:00.000Z",
      "workspaceManager" : true,
      "teamsPreview": [
        {
          "name": "team1",
          "links": [{"rel": "self", "href": "..."}]
        }
      ],
      "links" : [
        { "rel" : "self", "href" : "..." },
        { "rel" : "user", "href" : "..." },
        { "rel" : "avatar", "href" : "..." },
        { "rel" : "alternate", "href": "..." },
        { "rel" : "update", "href": "..." },
        { "rel" : "teams", "href" : "...", "count": "..." },
        { "rel" : "remove-from-workspace", "href": "..." },
        { "rel" : "remove-from-account", "href": "..." }
      ]
    }
  ],
  "links" : [
    { "rel" : "self", "href" : "..." },
    { "rel" : "parent", "href" : "..." },
    { "rel" : "first", "href" : "..." },
    { "rel" : "previous", "href" : "..." },
    { "rel" : "next", "href" : "..." }
  ]
}

Response Properties

Name	Description
users	The list of users in the given workspace

Response Link relations

Property	Name	Description	Methods
	self	The URI of the workspace users collection.	GET
	parent	The URI of the Workspace that the users belong to.	GET
	first	The URI of the first page of users.	GET
	previous	The URI of the previous page of users.	GET
	next	The URI of the next page of users.	GET
users	self	The URI of the workspace user	GET
users	user	The URI of the user	GET
users	avatar	The URI of the user's avatar	GET
users	alternate	The URI of the user's profile	GET
users	teams	The number of teams a user belongs to	GET
users	update	The URI to update workspace user	POST
users	remove-from-workspace	The URI to remove the user from this workspace	DELETE
users	remove-from-account	The URI to remove the user from this account	DELETE

Other Responses

Case	Response
Invalid authorization token	401 Unauthorized
Actor is not an authorised user	403 Forbidden
Workspace does not exist	404 Not Found

Filters

Query string parameters are used to filter the users in a workspace. Returns empty list of users if no users were found that match your query.

Request:

GET /membership/workspaces/123/users?q=jon&pagesize=20&skip=0&isWorkspaceManager=true HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Parameter	Default value	Additional notes
`q`		Match a workspace user on `firstname`, `lastname`, `email`
`isWorkspaceManager`	`false`	Match a user if they are also a Workspace Manager
`pagesize`	`20`
`skip`	`0`

Response shape is the same as in Retrieve Workspace Users

Retrieve workspace user

GET /membership/workspaces/123/users/999 HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

HTTP/1.1 200 OK
Content-Type: application/json

{
  "links": [
        { "rel" : "self", "href" : "..." },
        { "rel" : "user", "href" : "..." },
        { "rel" : "avatar", "href" : "..." },
        { "rel" : "alternate", "href": "..." },
        { "rel" : "update", "href" : "..." },
        { "rel" : "teams", "href" : "...", "count": "..." },
        { "rel" : "remove-from-workspace", "href": "..." },
        { "rel" : "remove-from-account", "href": "..." }
    ],
  "name": "Peter Parker",
  "email": "[email protected]",
  "lastLogin": "2020-03-03T00:00:00.000Z",
  "workspaceManager": true,
  "teamsPreview": [
      {
          "name": "team1",
          "links": [
              { "rel": "self", "href": "..." }
          ]
      }
  ]
}

Response Link relations

Name	Description	Methods
self	The URI of the workspace user	GET
user	The URI of the user	GET
avatar	The URI of the user's avatar	GET
alternate	The URI of the user's profile	GET
update	The URI to update workspace user	POST
teams	The number of teams a user belongs to	GET
remove-from-workspace	The URI to remove the user from this workspace	DELETE
remove-from-account	The URI to remove the user from this account	DELETE

Retrieving User Teams

Retrieves a collection of teams the user belongs to in the workspace. For the People teams list resource, see Teams. On Membership, team routes live under /workspaces/{workspaceId}/teams/ (with the /membership prefix in examples below).

Request

Retrieve teams for user 456 in workspace 123.

GET /membership/workspaces/123/users/456/teams HTTP/1.1
Accept: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

Request Filters

Filters are query string parameters that are used to filter the list of teams returned, e.g.

GET /membership/workspaces/123/users/456/teams?pagesize=20&skip=0

Parameter	Default value	Additional Notes
`pagesize`	`20`	The maximum number of elements to return, between 1 - 100.
`skip`	`0`	The number of results to skip

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
  "teams": [
    {
      "links": [
        { "rel": "self", "href": "/membership/workspaces/123/teams/12" },
        { "rel": "parent", "href": "/membership/workspaces/123" }
      ],
      "name": "My Team 1",
      "description": "Description of My Team 1"
    }
  ],
  "links": [
    { "rel": "self", "href": "/membership/workspaces/123/users/456/teams" },
    { "rel": "parent", "href": "/membership/workspaces/123/users/456" },
    { "rel": "first", "href": "..." },
    { "rel": "previous", "href": "..." },
    { "rel": "next", "href": "..." }
  ]
}

Response Properties

Name	Description
teams	The collection of Team resources

Response Link Relations

Name	Description	Methods
self	The URI of this User Teams resource	GET
parent	The URI of the User resource	GET

Other Responses

Name	Response
Invalid authorization token	401 Unauthorized
Insufficient permissions to view User	403 Forbidden
User does not exist	404 Not Found

Update Workspace user

If you have permission, you can update a workspace user's workspace manager role and which teams they belong to.

Example

Example request to update the Workspace user. The updates are to; remove them as a workspace manager, add them to a new team and remove them from a team.

POST /membership/workspaces/123/users/999 HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "workspaceManager" : false,
  "addToTeams" : [
    {"rel" : "team", "href" : ".../teams/10"}
  ],
  "removeFromTeams" : [
    {"rel" : "team", "href" : ".../teams/11"}
  ]
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

The response shape and details match Retrieve Workspace Users, except for in the case of partial success.

Other Responses

Name	Response
Operation succeeded, and user is no longer a member of the workspace as a result	204 No Content
Malformed request	400 Bad Request
Invalid authorization token	401 Unauthorized
Insufficient permissions to update user	403 Forbidden
Workspace, user or team does not exist	404 Not Found

NB: In the case of an error code, partial success is possible when using this endpoint. That is, some changes may have been successfully applied.

Remove a user from a workspace

You can get the required URL from Retrieve workspace users response link for remove-from-workspace

Example

Example request, asking to remove a user from a workspace:

DELETE /membership/workspaces/123/users/456 HTTP/1.1
Authorization: Bearer frootymcnooty/vonbootycherooty

Example response:

HTTP/1.1 204 No Content

Other Responses

Case	Response
Invalid authorization token	401 Unauthorized
Actor is not an authorised user	403 Forbidden
Workspace or User does not exist	404 Not Found

Bulk Invitations To Workspaces

Bulk invitations add people to teams in a workspace via Membership. The request must include at least one team link (rel: "parent") that belongs to the target workspace.

Create Invitation(s)

POST emails, team links, a required message (non-null, max 2500 chars), and isDefaultMessage.

Existing users only receive the custom message when isDefaultMessage is false.

Request

POST /membership/workspaces/123/invitations/bulk HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "links": [
    {
      "rel": "parent",
      "href": "..."
    }
  ],
  "emails": ["[email protected]", "[email protected]"],
  "message": "Hello!",
  "isDefaultMessage": false
}

Response

202 Accepted with one result per email.

HTTP/1.1 202 Accepted
Content-Type: application/vnd.huddle.data+json

{
  "invitations": [
    {
      "email": "[email protected]",
      "accepted": false
    },
    {
      "email": "[email protected]",
      "accepted": true,
      "member": {
        "links": [
          { "rel": "self", "href": "..." },
          { "rel": "delete", "href": "..." },
          { "rel": "company", "href": "..." },
          { "rel": "user", "href": "..." },
          { "rel": "avatar", "href": "..." },
          { "rel": "profile", "href": "..." },
          { "rel": "edit", "href": "..." }
        ],
        "displayName": "Existing User",
        "firstName": "Existing",
        "lastName": "User",
        "emailAddress": "[email protected]"
      }
    }
  ]
}

Invalid / non-whitelisted emails

Request

POST /membership/workspaces/123/invitations/bulk HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "links": [
    {
      "rel": "parent",
      "href": "..."
    }
  ],
  "emails": ["invalid.email", "[email protected]", "[email protected]", "[email protected]"],
  "message": "Hello!",
  "isDefaultMessage": true
}

Response

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.huddle.data+json

{
  "links": [
    {
      "rel": "companyManager",
      "href": "..."
    }
  ],
  "emails": [
    { "value": "invalid.email", "reason": "Invalid" },
    { "value": "[email protected]", "reason": "NotInWhitelist" },
    { "value": "[email protected]", "reason": "SelfInvited" }
  ]
}

Other Responses

Case	Response
Any team does not exist	`400 Bad Request`
Teams are not all in the workspace for this URL	`400 Bad Request`
Any email is invalid	`400 Bad Request`
Any email is not on company allowlist / whitelist	`400 Bad Request`
Actor invited themselves	`400 Bad Request`
Missing/null message, no team links, or message over 2500 chars	`400 Bad Request`
Invalid authorization token	`401 Unauthorized`
Actor is not allowed to invite	`403 Forbidden`
Workspace does not exist	`404 Not Found`
Actor not in the same company as the workspace	`404 Not Found`