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

# Sample Groups

## List sample groups

> Returns sample groups for the current user, or team-scoped when \`team\` is set. Personal lists annotate \`sample\_count\` for non-archived samples only.

```json
{"openapi":"3.0.3","info":{"title":"SESAR API","version":"1.0.0"},"security":[{"tokenAuth":[]},{"jwtAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token-based authentication with required prefix \"Token\""},"jwtAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"SampleGroupListSuccessResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SampleGroup"}}},"required":["data"]},"SampleGroup":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"name":{"type":"string","readOnly":true},"description":{"type":"string","readOnly":true,"nullable":true},"group_type":{"type":"string","readOnly":true},"user_owner":{"type":"string","nullable":true,"readOnly":true},"team_owner":{"type":"string","readOnly":true},"created_date":{"type":"string","format":"date-time","readOnly":true},"is_private":{"type":"boolean","readOnly":true},"sample_count":{"type":"integer","readOnly":true},"resolved_image":{"type":"string","readOnly":true}},"required":["created_date","description","group_type","id","is_private","name","resolved_image","sample_count","team_owner","user_owner"]}}},"paths":{"/api/sample-groups/":{"get":{"operationId":"sample_groups_retrieve","description":"Returns sample groups for the current user, or team-scoped when `team` is set. Personal lists annotate `sample_count` for non-archived samples only.","summary":"List sample groups","parameters":[{"in":"query","name":"team","schema":{"type":"string"},"description":"Team name; when set, list groups owned by that team."}],"tags":["Sample groups"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleGroupListSuccessResponse"}}},"description":""}}}}}}
```

## Create sample group

> Creates a sample group. Defaults to personal ownership unless \`team\_owner\` is set (requires create permission on the team).

```json
{"openapi":"3.0.3","info":{"title":"SESAR API","version":"1.0.0"},"security":[{"tokenAuth":[]},{"jwtAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token-based authentication with required prefix \"Token\""},"jwtAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"SampleGroupWrite":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"name":{"type":"string","maxLength":100},"description":{"type":"string","nullable":true},"group_type":{"type":"string"},"user_owner":{"type":"string","nullable":true},"team_owner":{"type":"string","nullable":true},"created_date":{"type":"string","format":"date-time"},"is_private":{"type":"boolean"}},"required":["group_type","id","is_private","name"]},"SampleGroupCreateSuccessResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SampleGroup"}},"required":["data"]},"SampleGroup":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"name":{"type":"string","readOnly":true},"description":{"type":"string","readOnly":true,"nullable":true},"group_type":{"type":"string","readOnly":true},"user_owner":{"type":"string","nullable":true,"readOnly":true},"team_owner":{"type":"string","readOnly":true},"created_date":{"type":"string","format":"date-time","readOnly":true},"is_private":{"type":"boolean","readOnly":true},"sample_count":{"type":"integer","readOnly":true},"resolved_image":{"type":"string","readOnly":true}},"required":["created_date","description","group_type","id","is_private","name","resolved_image","sample_count","team_owner","user_owner"]}}},"paths":{"/api/sample-groups/":{"post":{"operationId":"sample_groups_create","description":"Creates a sample group. Defaults to personal ownership unless `team_owner` is set (requires create permission on the team).","summary":"Create sample group","tags":["Sample groups"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleGroupWrite"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/SampleGroupWrite"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/SampleGroupWrite"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleGroupCreateSuccessResponse"}}},"description":""}}}}}}
```

## Retrieve sample group

> Returns sample group details when the caller may view the group. For private groups the caller cannot access, returns 403 with \`is\_private\` and \`name\`.

```json
{"openapi":"3.0.3","info":{"title":"SESAR API","version":"1.0.0"},"security":[{"tokenAuth":[]},{"jwtAuth":[]},{}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token-based authentication with required prefix \"Token\""},"jwtAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"SampleGroupDetailSuccessResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SampleGroup"}},"required":["data"]},"SampleGroup":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"name":{"type":"string","readOnly":true},"description":{"type":"string","readOnly":true,"nullable":true},"group_type":{"type":"string","readOnly":true},"user_owner":{"type":"string","nullable":true,"readOnly":true},"team_owner":{"type":"string","readOnly":true},"created_date":{"type":"string","format":"date-time","readOnly":true},"is_private":{"type":"boolean","readOnly":true},"sample_count":{"type":"integer","readOnly":true},"resolved_image":{"type":"string","readOnly":true}},"required":["created_date","description","group_type","id","is_private","name","resolved_image","sample_count","team_owner","user_owner"]}}},"paths":{"/api/sample-groups/{id}/":{"get":{"operationId":"sample_groups_retrieve_2","description":"Returns sample group details when the caller may view the group. For private groups the caller cannot access, returns 403 with `is_private` and `name`.","summary":"Retrieve sample group","parameters":[{"in":"path","name":"id","schema":{"type":"integer"},"required":true}],"tags":["Sample groups"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleGroupDetailSuccessResponse"}}},"description":""},"403":{"description":"Private group; body includes `is_private` and `name` (not wrapped in `data`)."}}}}}}
```

## DELETE /api/sample-groups/{id}/

> Delete sample group

```json
{"openapi":"3.0.3","info":{"title":"SESAR API","version":"1.0.0"},"security":[{"tokenAuth":[]},{"jwtAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token-based authentication with required prefix \"Token\""},"jwtAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"SampleGroupDeleteSuccessResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SampleGroupDeleteSuccessData"}},"required":["data"]},"SampleGroupDeleteSuccessData":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}},"paths":{"/api/sample-groups/{id}/":{"delete":{"operationId":"sample_groups_destroy","summary":"Delete sample group","parameters":[{"in":"path","name":"id","schema":{"type":"integer"},"required":true}],"tags":["Sample groups"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleGroupDeleteSuccessResponse"}}},"description":""}}}}}}
```

## PATCH /api/sample-groups/{id}/

> Update sample group

```json
{"openapi":"3.0.3","info":{"title":"SESAR API","version":"1.0.0"},"security":[{"tokenAuth":[]},{"jwtAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token-based authentication with required prefix \"Token\""},"jwtAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"PatchedSampleGroupWrite":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"name":{"type":"string","maxLength":100},"description":{"type":"string","nullable":true},"group_type":{"type":"string"},"user_owner":{"type":"string","nullable":true},"team_owner":{"type":"string","nullable":true},"created_date":{"type":"string","format":"date-time"},"is_private":{"type":"boolean"}}},"SampleGroupUpdateSuccessResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SampleGroup"}},"required":["data"]},"SampleGroup":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"name":{"type":"string","readOnly":true},"description":{"type":"string","readOnly":true,"nullable":true},"group_type":{"type":"string","readOnly":true},"user_owner":{"type":"string","nullable":true,"readOnly":true},"team_owner":{"type":"string","readOnly":true},"created_date":{"type":"string","format":"date-time","readOnly":true},"is_private":{"type":"boolean","readOnly":true},"sample_count":{"type":"integer","readOnly":true},"resolved_image":{"type":"string","readOnly":true}},"required":["created_date","description","group_type","id","is_private","name","resolved_image","sample_count","team_owner","user_owner"]}}},"paths":{"/api/sample-groups/{id}/":{"patch":{"operationId":"sample_groups_partial_update","summary":"Update sample group","parameters":[{"in":"path","name":"id","schema":{"type":"integer"},"required":true}],"tags":["Sample groups"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchedSampleGroupWrite"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/PatchedSampleGroupWrite"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/PatchedSampleGroupWrite"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleGroupUpdateSuccessResponse"}}},"description":""}}}}}}
```

## Add samples to sample group

> Adds samples to a sample group by \`sample\_ids\` or \`select\_all\` with \`filters\`. Private samples are skipped when adding to a public group.

```json
{"openapi":"3.0.3","info":{"title":"SESAR API","version":"1.0.0"},"security":[{"tokenAuth":[]},{"jwtAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token-based authentication with required prefix \"Token\""},"jwtAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"SampleGroupMembershipRequest":{"type":"object","properties":{"sample_ids":{"type":"array","items":{"type":"integer"},"description":"Sample primary keys to add or remove (int or list)."},"select_all":{"type":"boolean","default":false,"description":"When true, apply `filters` instead of `sample_ids`."},"filters":{"type":"object","additionalProperties":{"type":"string"},"description":"Sample list filters when `select_all` is true."}}},"SampleGroupAddMembershipsSuccessResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SampleGroupAddMembershipsSuccessData"}},"required":["data"]},"SampleGroupAddMembershipsSuccessData":{"type":"object","properties":{"added_count":{"type":"integer"},"skipped_existing_count":{"type":"integer"},"skipped_private_sample_count":{"type":"integer"},"total_matched":{"type":"integer"},"sample_added_ids_sample":{"type":"array","items":{"type":"integer"}},"message":{"type":"string"}},"required":["added_count","message","sample_added_ids_sample","skipped_existing_count","skipped_private_sample_count","total_matched"]}}},"paths":{"/api/sample-groups/{id}/add-samples/":{"post":{"operationId":"sample_groups_add_samples_create","description":"Adds samples to a sample group by `sample_ids` or `select_all` with `filters`. Private samples are skipped when adding to a public group.","summary":"Add samples to sample group","parameters":[{"in":"path","name":"id","schema":{"type":"integer"},"required":true},{"in":"path","name":"pk","schema":{"type":"integer"},"description":"Sample group primary key.","required":true}],"tags":["Sample groups"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleGroupMembershipRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/SampleGroupMembershipRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/SampleGroupMembershipRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleGroupAddMembershipsSuccessResponse"}}},"description":""},"400":{"description":"Invalid request body."},"403":{"description":"Insufficient permission on this sample group."},"404":{"description":"Sample group or matching samples not found."}}}}}}
```

## Remove samples from sample group

> Removes samples from a sample group by \`sample\_ids\` or \`select\_all\` with \`filters\` (restricted to memberships already in the group).

```json
{"openapi":"3.0.3","info":{"title":"SESAR API","version":"1.0.0"},"security":[{"tokenAuth":[]},{"jwtAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token-based authentication with required prefix \"Token\""},"jwtAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"SampleGroupMembershipRequest":{"type":"object","properties":{"sample_ids":{"type":"array","items":{"type":"integer"},"description":"Sample primary keys to add or remove (int or list)."},"select_all":{"type":"boolean","default":false,"description":"When true, apply `filters` instead of `sample_ids`."},"filters":{"type":"object","additionalProperties":{"type":"string"},"description":"Sample list filters when `select_all` is true."}}},"SampleGroupRemoveMembershipsSuccessResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SampleGroupRemoveMembershipsSuccessData"}},"required":["data"]},"SampleGroupRemoveMembershipsSuccessData":{"type":"object","properties":{"removed_count":{"type":"integer"},"total_matched":{"type":"integer"},"message":{"type":"string"}},"required":["message","removed_count","total_matched"]}}},"paths":{"/api/sample-groups/{id}/remove-samples/":{"post":{"operationId":"sample_groups_remove_samples_create","description":"Removes samples from a sample group by `sample_ids` or `select_all` with `filters` (restricted to memberships already in the group).","summary":"Remove samples from sample group","parameters":[{"in":"path","name":"id","schema":{"type":"integer"},"required":true},{"in":"path","name":"pk","schema":{"type":"integer"},"description":"Sample group primary key.","required":true}],"tags":["Sample groups"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleGroupMembershipRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/SampleGroupMembershipRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/SampleGroupMembershipRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleGroupRemoveMembershipsSuccessResponse"}}},"description":""},"400":{"description":"Invalid request body."},"403":{"description":"Insufficient permission on this sample group."},"404":{"description":"Sample group or matching samples not found."}}}}}}
```

## List all sample groups for current user

> Returns every sample group the authenticated user can access, grouped by \`personal\` and each team name.

```json
{"openapi":"3.0.3","info":{"title":"SESAR API","version":"1.0.0"},"security":[{"tokenAuth":[]},{"jwtAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token-based authentication with required prefix \"Token\""},"jwtAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"SampleGroupListAllSuccessResponse":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/SampleGroup"}},"description":"Keys are `personal` and team names; values are sample group lists."}},"required":["data"]},"SampleGroup":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"name":{"type":"string","readOnly":true},"description":{"type":"string","readOnly":true,"nullable":true},"group_type":{"type":"string","readOnly":true},"user_owner":{"type":"string","nullable":true,"readOnly":true},"team_owner":{"type":"string","readOnly":true},"created_date":{"type":"string","format":"date-time","readOnly":true},"is_private":{"type":"boolean","readOnly":true},"sample_count":{"type":"integer","readOnly":true},"resolved_image":{"type":"string","readOnly":true}},"required":["created_date","description","group_type","id","is_private","name","resolved_image","sample_count","team_owner","user_owner"]}}},"paths":{"/api/sample-groups/me/":{"get":{"operationId":"sample_groups_me_retrieve","description":"Returns every sample group the authenticated user can access, grouped by `personal` and each team name.","summary":"List all sample groups for current user","tags":["Sample groups"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleGroupListAllSuccessResponse"}}},"description":""}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.geosamples.org/api/sample-groups.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.