> For the complete documentation index, see [llms.txt](https://docs.shortcutco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shortcutco.com/developers/api-reference/reference/teams.md).

# Teams

Crews: the people who work together in the field.

The API calls crews teams, so crew ids appear as `teamId`, `assignedTeamId`, and `effectiveTeamId`.

Fields: [The team object](https://docs.shortcutco.com/developers/reference/objects/team).

## List teams

> Crews with their active members, newest first, or by last change when \`updatedSince\` is set. Archived crews are included with \`archivedAt\` unless \`archived\` filters them out. Membership changes do not change a crew's \`updatedAt\`.\
> \
> Returns a list of \[team objects]\(<https://docs.shortcutco.com/developers/reference/objects/team>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Teams","description":"The API calls crews teams, so crew ids appear as `teamId`, `assignedTeamId`, and `effectiveTeamId`.\n\nFields: [The team object](https://docs.shortcutco.com/developers/reference/objects/team)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["teams:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Team":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The team's id."},"object":{"type":"string","const":"team","description":"Always `team`."},"name":{"type":"string","description":"The crew's name."},"color":{"type":["string","null"],"description":"The crew's color on the schedule, as `#RRGGBB`, or null."},"isDefault":{"type":"boolean","description":"Whether new work goes to this crew when no crew is chosen."},"sortOrder":{"type":"integer","description":"The crew's position in the app's crew lists, lowest first."},"members":{"type":"array","items":{"$ref":"#/components/schemas/TeamMember"},"description":"Active staff on the crew, in crew order."},"archivedAt":{"anyOf":[{"type":"string","format":"date-time","description":"When the crew was archived, ISO 8601 in UTC."},{"type":"null"}],"description":"When the crew was archived, ISO 8601 in UTC."},"createdAt":{"type":"string","format":"date-time","description":"When the crew was created, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When the crew last changed. Membership changes do not change it, ISO 8601 in UTC."}},"required":["id","object","name","color","isDefault","sortOrder","members","archivedAt","createdAt","updatedAt"],"additionalProperties":false,"description":"A team (crew) that does the work."},"TeamMember":{"type":"object","properties":{"userId":{"type":"string","format":"uuid","description":"The staff user's id; see `GET /v1/users/{id}`."},"firstName":{"type":"string","description":"First name."},"lastName":{"type":"string","description":"Last name."}},"required":["userId","firstName","lastName"],"additionalProperties":false,"description":"An active staff member of the crew."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/teams":{"get":{"operationId":"teams.list","tags":["Teams"],"summary":"List teams","description":"Crews with their active members, newest first, or by last change when `updatedSince` is set. Archived crews are included with `archivedAt` unless `archived` filters them out. Membership changes do not change a crew's `updatedAt`.\n\nReturns a list of [team objects](https://docs.shortcutco.com/developers/reference/objects/team).","parameters":[{"name":"limit","in":"query","required":false,"description":"How many items to return, 1-200. Defaults to 50.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The `meta.nextCursor` from the previous page. Omit it for the first page.","schema":{"type":"string","minLength":1,"maxLength":4096}},{"name":"archived","in":"query","required":false,"description":"True for archived crews only, false for current crews only; omit for both.","schema":{"type":"boolean"}},{"name":"updatedSince","in":"query","required":false,"description":"ISO 8601 timestamp. Returns objects changed at or after it, oldest change first. Keep the largest `updatedAt` you have seen, subtract five minutes, and pass it on the next sync; deduplicate by `id`.","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Team"}},"meta":{"type":"object","properties":{"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean","description":"Whether another page exists."}},"required":["nextCursor","hasMore"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Get a team

> One crew with its active members.\
> \
> Returns \[the team object]\(<https://docs.shortcutco.com/developers/reference/objects/team>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Teams","description":"The API calls crews teams, so crew ids appear as `teamId`, `assignedTeamId`, and `effectiveTeamId`.\n\nFields: [The team object](https://docs.shortcutco.com/developers/reference/objects/team)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["teams:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Team":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The team's id."},"object":{"type":"string","const":"team","description":"Always `team`."},"name":{"type":"string","description":"The crew's name."},"color":{"type":["string","null"],"description":"The crew's color on the schedule, as `#RRGGBB`, or null."},"isDefault":{"type":"boolean","description":"Whether new work goes to this crew when no crew is chosen."},"sortOrder":{"type":"integer","description":"The crew's position in the app's crew lists, lowest first."},"members":{"type":"array","items":{"$ref":"#/components/schemas/TeamMember"},"description":"Active staff on the crew, in crew order."},"archivedAt":{"anyOf":[{"type":"string","format":"date-time","description":"When the crew was archived, ISO 8601 in UTC."},{"type":"null"}],"description":"When the crew was archived, ISO 8601 in UTC."},"createdAt":{"type":"string","format":"date-time","description":"When the crew was created, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When the crew last changed. Membership changes do not change it, ISO 8601 in UTC."}},"required":["id","object","name","color","isDefault","sortOrder","members","archivedAt","createdAt","updatedAt"],"additionalProperties":false,"description":"A team (crew) that does the work."},"TeamMember":{"type":"object","properties":{"userId":{"type":"string","format":"uuid","description":"The staff user's id; see `GET /v1/users/{id}`."},"firstName":{"type":"string","description":"First name."},"lastName":{"type":"string","description":"Last name."}},"required":["userId","firstName","lastName"],"additionalProperties":false,"description":"An active staff member of the crew."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/teams/{id}":{"get":{"operationId":"teams.get","tags":["Teams"],"summary":"Get a team","description":"One crew with its active members.\n\nReturns [the team object](https://docs.shortcutco.com/developers/reference/objects/team).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Team"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```