VLM – Datasets

Requests Samples Ximilar Platform

This page is part of the Custom Vision Language Models (VLM) API reference. See the overview for task modes, key concepts, the end-to-end workflow and the list of all endpoints.

Dataset Endpoints

A dataset groups the training samples of one mode. Its mode must equal the mode of every task it is connected to and is fixed at creation. What a dataset must contain before it is valid depends on the mode:

Mode	Dataset configuration	Sample content
`instruction`	system prompt, user prompt, result template (every `{{placeholder}}` must exist as a variable and the rendered template must be valid in the chosen `result_format`)	images and/or detection objects, values for all required variables
`agentic`	system prompt (a user prompt on the task is still required for training)	at least one image on the user step, a valid sequence of steps ending with an `answer`
`retrieval`	nothing	at least one anchor and one document item, an edge between every anchor and document

GET/v2/dataset/

List Datasets

List all VLM datasets in your workspace. Returns paginated results.

Required attributes

Name
Authorization
Type
string
Description
Unique API token for authentication.

Optional attributes

Name
mode
Type
string
Description
Filter by mode: instruction, agentic or retrieval.
Name
task
Type
string
Description
Only datasets connected to the given task UUID.
Name
search
Type
string
Description
Search datasets by name.
Name
prompt
Type
string
Description
Only datasets referencing the given prompt UUID.
Name
page_size
Type
integer
Description
Number of results per page.

Request

GET

/v2/dataset/

curl -v -XGET \
     -H 'Authorization: Token __API_TOKEN__' \
     'https://api.ximilar.com/vlm/v2/dataset/?mode=retrieval'

GET/v2/dataset/{dataset_id}/

Get Dataset

Get details of a specific VLM dataset by its ID.

Required attributes

Name
Authorization
Type
string
Description
Unique API token for authentication.
Name
dataset_id
Type
string
Description
UUID of the dataset.

Returns

Name
id
Type
string
Description
UUID of the dataset.
Name
name
Type
string
Description
Name of the dataset.
Name
description
Type
string
Description
Description of the dataset.
Name
mode
Type
string
Description
Dataset mode: instruction, agentic or retrieval. Read-only after creation.
Name
valid
Type
boolean
Description
Whether the dataset configuration is complete for its mode (see Validate Dataset for details).
Name
version
Type
string
Description
Auto-generated version date (updated on each save).
Name
created_date
Type
string
Description
Timestamp when the dataset was created (ISO 8601 format).
Name
result_format
Type
string
Description
Output format json, yaml, xml, csv or null. When a result template prompt with a format is referenced, that format wins.
Name
default_input_meta_data
Type
object
Description
Default input metadata for samples in this dataset. Used to pre-populate the sample's input_meta_data on creation.
Name
meta_data
Type
object
Description
Additional metadata attached to the dataset.
Name
samples_count
Type
integer
Description
Number of samples in this dataset.
Name
variables_count
Type
integer
Description
Number of variables defined for this dataset (instruction mode).
Name
system_prompt_id
Type
string
Description
UUID of the referenced system prompt (overrides the task's prompt for this dataset).
Name
user_prompt_id
Type
string
Description
UUID of the referenced user prompt.
Name
result_template_id
Type
string
Description
UUID of the referenced result template prompt.
Name
system_prompt
Type
string
Description
Resolved system prompt text content (read-only, derived from the referenced prompt).
Name
user_prompt
Type
string
Description
Resolved user prompt text content (read-only, derived from the referenced prompt).
Name
result_template
Type
string
Description
Resolved result template content (read-only, derived from the referenced prompt).

Request

GET

/v2/dataset/{dataset_id}/

curl -v -XGET \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/vlm/v2/dataset/__DATASET_ID__/

Response

{
  "id": "8797c273-b1d3-4e6f-82bb-adfb719415fe",
  "name": "Grading dataset",
  "description": "Training samples for card grading",
  "mode": "instruction",
  "valid": true,
  "version": "2025-12-21",
  "created_date": "2025-12-17T10:30:00.000000Z",
  "result_format": "json",
  "default_input_meta_data": {"category": "sports card"},
  "meta_data": {},
  "samples_count": 150,
  "variables_count": 2,
  "system_prompt_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "user_prompt_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "result_template_id": "05dea907-3a59-4f77-93f0-07a922422bbf",
  "system_prompt": "You are a helpful assistant...",
  "user_prompt": "Analyse the image[s]...",
  "result_template": "{\"grade\": {{grade}}, \"explain\": \"{{explain}}\"}",
  "workspace": "748e50e4-d081-4924-b9e7-f500aac6a71d"
}

POST/v2/dataset/

Create Dataset

Create a new dataset. The mode must match the task you plan to connect it to and cannot be changed later.

Required attributes

Name
Authorization
Type
string
Description
Unique API token for authentication.
Name
name
Type
string
Description
Name of the dataset.
Name
mode
Type
string
Description
Dataset mode: instruction, agentic or retrieval.

Optional attributes

Name
description
Type
string
Description
Human-readable description.
Name
system_prompt_id
Type
string
Description
UUID of a system prompt. Overrides the task's system prompt for samples of this dataset.
Name
user_prompt_id
Type
string
Description
UUID of a user prompt.
Name
result_template_id
Type
string
Description
UUID of a template prompt (instruction mode). Its {{placeholders}} must match the dataset variables.
Name
result_format
Type
string
Description
json, yaml, xml or csv. Ignored when the referenced template prompt defines its own format.
Name
default_input_meta_data
Type
object
Description
Default input_meta_data copied to every new sample. Useful for {{placeholders}} in the user prompt.
Name
meta_data
Type
object
Description
Additional metadata.
Name
workspace
Type
string
Description
UUID of the workspace to create the dataset in.

Request

POST

/v2/dataset/

curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     -H 'Content-Type: application/json' \
     -d '{
       "name": "Grading dataset",
       "mode": "instruction",
       "description": "Sports cards graded 1-10",
       "system_prompt_id": "__SYSTEM_PROMPT_ID__",
       "user_prompt_id": "__USER_PROMPT_ID__",
       "result_template_id": "__TEMPLATE_PROMPT_ID__",
       "result_format": "json",
       "default_input_meta_data": {"category": "sports card"}
     }' \
     https://api.ximilar.com/vlm/v2/dataset/

Response

{
  "id": "8797c273-b1d3-4e6f-82bb-adfb719415fe",
  "name": "Grading dataset",
  "description": "Sports cards graded 1-10",
  "mode": "instruction",
  "valid": false,
  "version": "2026-03-02",
  "created_date": "2026-03-02T10:20:03.000000Z",
  "result_format": "json",
  "default_input_meta_data": {"category": "sports card"},
  "meta_data": null,
  "samples_count": 0,
  "variables_count": 0,
  "system_prompt_id": "__SYSTEM_PROMPT_ID__",
  "user_prompt_id": "__USER_PROMPT_ID__",
  "result_template_id": "__TEMPLATE_PROMPT_ID__",
  "system_prompt": "You are a helpful assistant...",
  "user_prompt": "Analyse the image[s]...",
  "result_template": "{\"grade\": {{grade}}, \"explain\": \"{{explain}}\"}",
  "workspace": "748e50e4-d081-4924-b9e7-f500aac6a71d"
}

PATCH/v2/dataset/{dataset_id}/

Update Dataset

Update an existing dataset. Only the provided fields are changed. mode cannot be changed (400 {"mode": ["Mode cannot be changed after creation."]}).

Required attributes

Name
Authorization
Type
string
Description
Unique API token for authentication.
Name
dataset_id
Type
string
Description
UUID of the dataset to update.

Optional attributes

Name
name
Type
string
Description
Updated name.
Name
description
Type
string
Description
Updated description.
Name
system_prompt_id
Type
string
Description
UUID of a system prompt or null.
Name
user_prompt_id
Type
string
Description
UUID of a user prompt or null.
Name
result_template_id
Type
string
Description
UUID of a template prompt or null.
Name
result_format
Type
string
Description
json, yaml, xml, csv or null.
Name
default_input_meta_data
Type
object
Description
Default input metadata for new samples.
Name
meta_data
Type
object
Description
Additional metadata.

Request

PATCH

/v2/dataset/{dataset_id}/

curl -v -XPATCH \
     -H 'Authorization: Token __API_TOKEN__' \
     -H 'Content-Type: application/json' \
     -d '{
       "result_template_id": "__TEMPLATE_PROMPT_ID__",
       "result_format": "json"
     }' \
     https://api.ximilar.com/vlm/v2/dataset/__DATASET_ID__/

DELETE/v2/dataset/{dataset_id}/

Delete Dataset

Delete a dataset together with all of its samples, variables, steps and retrieval items. Images and prompts are kept.

Required attributes

Name
Authorization
Type
string
Description
Unique API token for authentication.
Name
dataset_id
Type
string
Description
UUID of the dataset to delete.

Request

DELETE

/v2/dataset/{dataset_id}/

curl -v -XDELETE \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/vlm/v2/dataset/__DATASET_ID__/

POST/v2/dataset/{dataset_id}/validate/

Validate Dataset

Check the dataset configuration and list the samples that would be skipped during training. Use POST /v2/dataset/validate-batch/ with {"ids": ["__DATASET_ID__", "..."]} to validate several datasets at once (response {"results": {"<dataset_id>": {...}}}).

Required attributes

Name
Authorization
Type
string
Description
Unique API token for authentication.
Name
dataset_id
Type
string
Description
UUID of the dataset.

Returns

Name
valid
Type
boolean
Description
true when the dataset configuration is complete for its mode.
Name
validation_errors
Type
array
Description
Configuration problems as plain strings, e.g. "Missing system prompt", "Missing result template", "Missing variables: grade, explain", "Result template is not valid JSON".
Name
not_valid_samples
Type
array
Description
Samples that fail validation. Each entry has sample_id, sample_name, dataset_id, dataset_name, step_id, role, type, error_type and reason.
Name
not_valid_samples_truncated
Type
boolean
Description
true when more than 100 sample issues exist and the list was cut.

Request

POST

/v2/dataset/{dataset_id}/validate/

curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/vlm/v2/dataset/__DATASET_ID__/validate/

Response

{
  "valid": true,
  "validation_errors": [],
  "not_valid_samples": [
    {
      "sample_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "sample_name": "Sample 12",
      "dataset_id": "8797c273-b1d3-4e6f-82bb-adfb719415fe",
      "dataset_name": "Grading dataset",
      "step_id": null,
      "role": null,
      "type": null,
      "error_type": "missing_image",
      "reason": "Sample has no image, object, video, or audio media."
    }
  ],
  "not_valid_samples_truncated": false
}

POST/v2/dataset/{dataset_id}/add-samples/

Move or Delete Samples in Bulk

add-samples moves existing samples into this dataset (the samples' current dataset must have the same mode). remove-samples (POST /v2/dataset/{dataset_id}/remove-samples/) deletes the given samples of this dataset.

Required attributes

Name
Authorization
Type
string
Description
Unique API token for authentication.
Name
dataset_id
Type
string
Description
UUID of the dataset.
Name
sample_ids
Type
array
Description
List of sample UUIDs.

Errors

One or more samples not found or not accessible
Sample mode 'instruction' does not match dataset mode 'retrieval'.

Request

POST

/v2/dataset/{dataset_id}/add-samples/

curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     -H 'Content-Type: application/json' \
     -d '{"sample_ids": ["__SAMPLE_ID_1__", "__SAMPLE_ID_2__"]}' \
     https://api.ximilar.com/vlm/v2/dataset/__DATASET_ID__/add-samples/

Response

{
  "added": 2
}

POST/v2/dataset/import/

Import Dataset

Create a whole dataset from a JSON or YAML manifest in one request: prompts, variables, tools, samples and steps. Images can be uploaded together with the manifest (media_file_0, media_file_1, ... plus a media_manifest mapping each field to the path used in the manifest) or referenced by image_ids of images already in your workspace.

Supported for instruction and agentic datasets. Retrieval datasets must be built with the retrieval item and edge endpoints.

Required attributes (multipart/form-data)

Name
Authorization
Type
string
Description
Unique API token for authentication.
Name
name
Type
string
Description
Name for the new dataset.
Name
dataset_file
Type
file
Description
The manifest (.json, .yaml or .yml, max 10 MB).

Optional attributes

Name
mode
Type
string
Description
Expected mode (instruction or agentic). When set, the manifest's mode must match.
Name
description
Type
string
Description
Dataset description.
Name
dry_run
Type
boolean
Description
Validate and report counts without creating anything (returns 200).
Name
force_save
Type
boolean
Description
Create the dataset even if it is not yet trainable (e.g. missing variable values). Manifest shape errors are never bypassed.
Name
task_id
Type
string
Description
UUID of a task to connect the new dataset to.
Name
media_manifest
Type
string
Description
JSON array mapping uploaded files to manifest paths: [{"field": "media_file_0", "path": "images/shoe.jpg"}].

Returns

201 with dataset (id, name, mode, sample_count), summary (counts such as samples_created, variables_created, tools_created, steps_created, sample_images_linked, step_images_linked), validation, warnings, dry_run and force_save.

Request

POST

/v2/dataset/import/

curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     -F 'name=Imported dataset' \
     -F 'mode=instruction' \
     -F 'task_id=__TASK_ID__' \
     -F 'dataset_file=@dataset.json' \
     -F 'media_file_0=@images/shoe.jpg' \
     -F 'media_manifest=[{"field": "media_file_0", "path": "images/shoe.jpg"}]' \
     https://api.ximilar.com/vlm/v2/dataset/import/

Response

{
  "dataset": {
    "id": "8797c273-b1d3-4e6f-82bb-adfb719415fe",
    "name": "Imported dataset",
    "mode": "instruction",
    "sample_count": 1
  },
  "summary": {
    "variables_created": 1,
    "tools_created": 0,
    "samples_created": 1,
    "sample_variables_created": 1,
    "sample_images_linked": 2,
    "sample_detection_objects_linked": 0,
    "steps_created": 0,
    "step_images_linked": 0
  },
  "validation": {"valid": true, "validation_errors_truncated": false, "validation_errors": []},
  "warnings": [],
  "dry_run": false,
  "force_save": false
}