Sample Groups

List sample groups

get

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

Authorizations

AuthorizationstringRequired

Token-based authentication with required prefix "Token"

Query parameters

teamstringOptional

Team name; when set, list groups owned by that team.

Responses

200Success

application/json

get/api/sample-groups/

GET /api/sample-groups/ HTTP/1.1
Authorization: YOUR_API_KEY
Accept: */*

200Success

{
  "data": [
    {
      "id": 1,
      "name": "text",
      "description": "text",
      "group_type": "text",
      "user_owner": "text",
      "team_owner": "text",
      "created_date": "2026-01-01T00:00:00.000Z",
      "is_private": true,
      "sample_count": 1,
      "resolved_image": "text"
    }
  ]
}

Create sample group

post

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

Authorizations

AuthorizationstringRequired

Token-based authentication with required prefix "Token"

Body

idintegerRead-onlyRequired

namestring · max: 100Required

descriptionstring · nullableOptional

group_typestringRequired

user_ownerstring · nullableOptional

team_ownerstring · nullableOptional

created_datestring · date-timeOptional

is_privatebooleanRequired

Responses

201Success

application/json

post/api/sample-groups/

POST /api/sample-groups/ HTTP/1.1
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 156

{
  "name": "text",
  "description": "text",
  "group_type": "text",
  "user_owner": "text",
  "team_owner": "text",
  "created_date": "2026-01-01T00:00:00.000Z",
  "is_private": true
}

201Success

{
  "data": {
    "id": 1,
    "name": "text",
    "description": "text",
    "group_type": "text",
    "user_owner": "text",
    "team_owner": "text",
    "created_date": "2026-01-01T00:00:00.000Z",
    "is_private": true,
    "sample_count": 1,
    "resolved_image": "text"
  }
}

Retrieve sample group

get

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.

Authorizations

AuthorizationstringOptional

Token-based authentication with required prefix "Token"

Path parameters

idintegerRequired

Responses

200Success

application/json

403

Private group; body includes is_private and name (not wrapped in data).

get/api/sample-groups/{id}/

GET /api/sample-groups/{id}/ HTTP/1.1
Authorization: YOUR_API_KEY
Accept: */*

{
  "data": {
    "id": 1,
    "name": "text",
    "description": "text",
    "group_type": "text",
    "user_owner": "text",
    "team_owner": "text",
    "created_date": "2026-01-01T00:00:00.000Z",
    "is_private": true,
    "sample_count": 1,
    "resolved_image": "text"
  }
}

Delete sample group

delete

Authorizations

AuthorizationstringRequired

Token-based authentication with required prefix "Token"

Path parameters

idintegerRequired

Responses

200Success

application/json

delete/api/sample-groups/{id}/

DELETE /api/sample-groups/{id}/ HTTP/1.1
Authorization: YOUR_API_KEY
Accept: */*

200Success

{
  "data": {
    "success": true
  }
}

Update sample group

patch

Authorizations

AuthorizationstringRequired

Token-based authentication with required prefix "Token"

Path parameters

idintegerRequired

Body

idintegerRead-onlyOptional

namestring · max: 100Optional

descriptionstring · nullableOptional

group_typestringOptional

user_ownerstring · nullableOptional

team_ownerstring · nullableOptional

created_datestring · date-timeOptional

is_privatebooleanOptional

Responses

200Success

application/json

patch/api/sample-groups/{id}/

PATCH /api/sample-groups/{id}/ HTTP/1.1
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 156

{
  "name": "text",
  "description": "text",
  "group_type": "text",
  "user_owner": "text",
  "team_owner": "text",
  "created_date": "2026-01-01T00:00:00.000Z",
  "is_private": true
}

200Success

{
  "data": {
    "id": 1,
    "name": "text",
    "description": "text",
    "group_type": "text",
    "user_owner": "text",
    "team_owner": "text",
    "created_date": "2026-01-01T00:00:00.000Z",
    "is_private": true,
    "sample_count": 1,
    "resolved_image": "text"
  }
}

Add samples to sample group

post

Adds samples to a sample group by sample_ids or select_all with filters. Private samples are skipped when adding to a public group.

Authorizations

AuthorizationstringRequired

Token-based authentication with required prefix "Token"

Path parameters

idintegerRequired

pkintegerRequired

Sample group primary key.

Body

sample_idsinteger[]Optional

Sample primary keys to add or remove (int or list).

select_allbooleanOptional

When true, apply filters instead of sample_ids.

Default: false

Responses

200Success

application/json

400

Invalid request body.

403

Insufficient permission on this sample group.

404

Sample group or matching samples not found.

post/api/sample-groups/{id}/add-samples/

POST /api/sample-groups/{id}/add-samples/ HTTP/1.1
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 82

{
  "sample_ids": [
    1
  ],
  "select_all": false,
  "filters": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

{
  "data": {
    "added_count": 1,
    "skipped_existing_count": 1,
    "skipped_private_sample_count": 1,
    "total_matched": 1,
    "sample_added_ids_sample": [
      1
    ],
    "message": "text"
  }
}

Remove samples from sample group

post

Removes samples from a sample group by sample_ids or select_all with filters (restricted to memberships already in the group).

Authorizations

AuthorizationstringRequired

Token-based authentication with required prefix "Token"

Path parameters

idintegerRequired

pkintegerRequired

Sample group primary key.

Body

sample_idsinteger[]Optional

Sample primary keys to add or remove (int or list).

select_allbooleanOptional

When true, apply filters instead of sample_ids.

Default: false

Responses

200Success

application/json

400

Invalid request body.

403

Insufficient permission on this sample group.

404

Sample group or matching samples not found.

post/api/sample-groups/{id}/remove-samples/

POST /api/sample-groups/{id}/remove-samples/ HTTP/1.1
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 82

{
  "sample_ids": [
    1
  ],
  "select_all": false,
  "filters": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

{
  "data": {
    "removed_count": 1,
    "total_matched": 1,
    "message": "text"
  }
}

List all sample groups for current user

get

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

Authorizations

AuthorizationstringRequired

Token-based authentication with required prefix "Token"

Responses

200Success

application/json

get/api/sample-groups/me/

GET /api/sample-groups/me/ HTTP/1.1
Authorization: YOUR_API_KEY
Accept: */*

200Success

{
  "data": {
    "ANY_ADDITIONAL_PROPERTY": [
      {
        "id": 1,
        "name": "text",
        "description": "text",
        "group_type": "text",
        "user_owner": "text",
        "team_owner": "text",
        "created_date": "2026-01-01T00:00:00.000Z",
        "is_private": true,
        "sample_count": 1,
        "resolved_image": "text"
      }
    ]
  }
}