TeamsNew - Huddle/huddle-apis GitHub Wiki

Summary

The Membership Teams API manages teams inside a workspace: list teams, get/update/delete a team, and manage team members.

For the read-only teams list on People, see Teams.

Beta warning

The Membership Teams API is in Alpha.

Operations

Method	Path	Purpose	Details
`GET`	`/membership/workspaces/{workspaceId}/teams/`	List teams in workspace	Jump
`GET`	`/membership/teams/{teamId}`	Retrieve a team	Jump
`POST`	`/membership/workspaces/{workspaceId}/teams/`	Create a team	Jump
`PATCH`	`/membership/workspaces/{workspaceId}/teams/{teamId}`	Update a team	Jump
`DELETE`	`/membership/workspaces/{workspaceId}/teams/{teamId}`	Delete a team	Jump
`POST`	`/membership/workspaces/{workspaceId}/teams/{teamId}/members`	Add members to a team	Jump
`GET`	`/membership/workspaces/{workspaceId}/teams/{teamId}/members`	Retrieve team members	Jump
`POST`	`/membership/workspaces/{workspaceId}/teams/{teamId}/members/remove`	Remove members from a team	Jump

List of Teams in Workspace

Example

Request:

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

Request filters

GET /membership/workspaces/123/teams/?name=my&hasUser=123&pagesize=20&skip=0 HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Parameter	Default	Notes
`name`	—	Team names in the workspace that start with this value
`hasUser`	—	When set, each team may include `userIsMember` for that user
`pagesize`	`20`	Page size (allowed range enforced by the service, typically 1–100)
`skip`	`0`	Number of teams to skip

Response

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

{
  "links": [
    { "rel": "parent", "href": "..." },
    { "rel": "self", "href": "..." },
    { "rel": "next", "href": "..." },
    { "rel": "first", "href": "..." },
    { "rel": "previous", "href": "..." },
    { "rel": "create-team", "href": "..." },
    { "rel": "bulkInvitation", "href": "..." }
  ],
  "teams": [
    {
      "links": [
        { "rel": "self", "href": "..." },
        { "rel": "parent", "href": "..." },
        { "rel": "members", "href": "...", "count": 3 },
        { "rel": "add-member", "href": "..." },
        { "rel": "update", "href": "..." },
        { "rel": "delete", "href": "..." },
        { "rel": "remove-members", "href": "..." }
      ],
      "name": "My Team 1",
      "description": "Description of My Team 1",
      "userIsMember": true
    },
    {
      "links": [
        { "rel": "self", "href": "..." },
        { "rel": "parent", "href": "..." }
      ],
      "name": "My Team 2",
      "description": "Description of My Team 2",
      "userIsMember": false
    }
  ]
}

create-team, bulkInvitation, and some team-level links appear only when the caller has the right permissions. userIsMember appears when hasUser is used in the request.

Response link relations

Context	rel	Description	Methods
Collection	`parent`	Workspace	GET
Collection	`self`	This page of teams	GET
Collection	`first` / `previous` / `next`	Paging	GET
Collection	`create-team`	Create a team	POST
Collection	`bulkInvitation`	Bulk invite (may be People URL)	POST
Each team	`self`	Team	GET
Each team	`parent`	Workspace	GET
Each team	`members`	Team members (optional `count`)	GET
Each team	`add-member`	Add members	POST
Each team	`update`	Patch team	PATCH
Each team	`delete`	Delete empty team	DELETE
Each team	`remove-members`	Remove members	POST

Other responses

Case	Response
Invalid authorization	`401 Unauthorized`
Insufficient permissions	`403 Forbidden`
Workspace does not exist	`404 Not Found`

Retrieve a Team

Example

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

Response

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

{
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "parent", "href": "..." },
    { "rel": "members", "href": "...", "count": 3 },
    { "rel": "add-member", "href": "..." },
    { "rel": "update", "href": "..." },
    { "rel": "delete", "href": "..." },
    { "rel": "remove-members", "href": "..." }
  ],
  "name": "My Important team",
  "description": "My team description"
}

Optional links (add-member, update, delete, remove-members) depend on permissions.

Other responses

Case	Response
Invalid authorization	`401 Unauthorized`
Insufficient permissions	`403 Forbidden`
Team or workspace not found	`404 Not Found`

Create a Team

Workspace team names must be unique within the workspace.

Example

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

{
  "name": "My first team!",
  "description": "Description of my first team!"
}

Response

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

{
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "parent", "href": "..." },
    { "rel": "members", "href": "...", "count": 0 },
    { "rel": "add-member", "href": "..." }
  ],
  "name": "My first team!",
  "description": "Description of my first team!"
}

Other responses

See HttpStatusCodes.

Case	Response
Insufficient permissions	`403 Forbidden`
Workspace does not exist	`404 Not Found`
Name already exists	`409 Conflict`

Update a Team

Example

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

{
  "name": "New name for Team 1",
  "description": "New description of Team 1"
}

Response

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

{
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "parent", "href": "..." }
  ],
  "name": "New name for Team 1",
  "description": "New description of Team 1"
}

This response follows ErrorHandling and ResponseHeaders.

Other responses

Case	Response
Invalid authorization	`401 Unauthorized`
Insufficient permissions	`403 Forbidden`
New name conflicts with another team	`409 Conflict`

Delete a Team

Only teams with no members can be deleted.

Example

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

Response

HTTP/1.1 204 No Content

Other responses

Case	Response
Invalid authorization	`401 Unauthorized`
Insufficient permissions	`403 Forbidden`
Workspace does not exist	`404 Not Found`
Team still has members	`409 Conflict`

Add Members to a Team

POST rel: member links pointing at the users to add (typically user self URIs).

Example

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

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

Response

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

{
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "parent", "href": "..." },
    { "rel": "add-member", "href": "..." },
    { "rel": "remove-members", "href": "..." },
    { "rel": "first", "href": "..." },
    { "rel": "next", "href": "..." },
    { "rel": "previous", "href": "..." }
  ],
  "members": [
    {
      "name": "Serious Sam",
      "email": "[email protected]",
      "links": [
        { "rel": "self", "href": "..." },
        { "rel": "avatar", "href": "..." },
        { "rel": "alternate", "href": "..." }
      ]
    }
  ]
}

Other responses

Case	Response
Missing or invalid body / links	`400 Bad Request`
Allow-list / validation failure	`400 Bad Request`
Insufficient permissions	`403 Forbidden`
Team not found	`404 Not Found`

Retrieve Team Members

Example

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

Filters

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

Parameter	Default	Notes
`q`	—	Match first name, last name, or email
`pagesize`	`20`	Page size
`skip`	`0`	Offset

Response

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

{
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "parent", "href": "..." },
    { "rel": "add-member", "href": "..." },
    { "rel": "remove-members", "href": "..." },
    { "rel": "first", "href": "..." },
    { "rel": "next", "href": "..." },
    { "rel": "previous", "href": "..." }
  ],
  "members": [
    {
      "name": "Serious Sam",
      "email": "[email protected]",
      "links": [
        { "rel": "self", "href": "..." },
        { "rel": "avatar", "href": "..." },
        { "rel": "alternate", "href": "..." }
      ]
    }
  ]
}

Response link relations

Context	rel	Description	Methods
Collection	`self`	This members list	GET
Collection	`parent`	Team	GET
Collection	`add-member`	Add members	POST
Collection	`remove-members`	Remove members	POST
Collection	`first` / `next` / `previous`	Paging	GET
Each member	`self`	User	GET
Each member	`avatar`	Avatar	GET
Each member	`alternate`	Web profile	GET

Other responses

Case	Response
Invalid authorization	`401 Unauthorized`
Insufficient permissions	`403 Forbidden`
Team or workspace not found	`404 Not Found`

Remove Members from a Team

Workspace managers can remove members (including themselves) using rel: member links for each user to remove.

Example

POST /membership/workspaces/123/teams/456/members/remove HTTP/1.1
Accept: application/vnd.huddle.data+json
Content-Type: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

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

Response

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

{
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "parent", "href": "..." },
    { "rel": "add-member", "href": "..." },
    { "rel": "remove-members", "href": "..." },
    { "rel": "first", "href": "..." },
    { "rel": "next", "href": "..." },
    { "rel": "previous", "href": "..." }
  ],
  "members": []
}

Other responses

Case	Response
Insufficient permissions	`403 Forbidden`
Team not found	`404 Not Found`

Teams — People API teams list for a workspace
WorkspaceNew — workspace users and membership flows
BulkInvitationsToTeams — bulk invitations to teams

TeamsNew - Huddle/huddle-apis GitHub Wiki

Summary

Beta warning

Operations

List of Teams in Workspace

Example

Request filters

Response

Response link relations

Other responses

Retrieve a Team

Example

Response

Other responses

Create a Team

Example

Response

Other responses

Update a Team

Example

Response

Other responses

Delete a Team

Example

Response

Other responses

Add Members to a Team

Example

Response

Other responses

Retrieve Team Members

Example

Filters

Response

Response link relations

Other responses

Remove Members from a Team

Example

Response

Other responses

Related