VLM – Prompts

VLM Overview Tasks 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.

Prompt Endpoints

Prompts are reusable named text blocks that can be shared across multiple tasks and datasets. Instead of storing prompt text directly on tasks and datasets, you create prompt objects and reference them by ID. This allows you to update a prompt once and have all referencing tasks and datasets use the updated content.

Prompt Types

Type	Description
`system`	System prompt that sets the AI model's behavior and role
`user`	User prompt (instruction) that tells the model what to do
`template`	Result template that defines the expected output format

Prompt Formats

The format field is optional and indicates the desired output format. When not specified (null), no specific format is enforced.

Format	Description
`json`	JSON output format
`yaml`	YAML output format
`xml`	XML output format
`csv`	CSV output format

GET/v2/prompt/

List Prompts

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

Required attributes

Name
Authorization
Type
string
Description
Unique API token for authentication.

Optional attributes

Name
search
Type
string
Description
Search prompts by name.
Name
type
Type
string
Description
Filter by prompt type (system, user, or template).

Request

GET

/v2/prompt/

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

Response

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Product Analysis System Prompt",
      "description": "System prompt for product image analysis",
      "type": "system",
      "format": null,
      "workspace": "748e50e4-d081-4924-b9e7-f500aac6a71d"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Analyze Image Instruction",
      "description": "User instruction for analyzing images",
      "type": "user",
      "format": null,
      "workspace": "748e50e4-d081-4924-b9e7-f500aac6a71d"
    }
  ]
}

GET/v2/prompt/{prompt_id}/

Get Prompt

Get details of a specific VLM prompt by its ID.

Required attributes

Name
Authorization
Type
string
Description
Unique API token for authentication.
Name
prompt_id
Type
string
Description
UUID of the prompt.

Returns

Name
id
Type
string
Description
UUID of the prompt.
Name
name
Type
string
Description
Name of the prompt.
Name
description
Type
string
Description
Optional description.
Name
content
Type
string
Description
The prompt text content.
Name
type
Type
string
Description
Prompt type: system, user, or template.
Name
format
Type
string
Description
Optional output format: json, yaml, xml, or csv. null when not specified.

Request

GET

/v2/prompt/{prompt_id}/

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

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Product Analysis System Prompt",
  "description": "System prompt for product image analysis",
  "content": "You are a helpful assistant that analyzes product images and provides structured data about them.",
  "type": "system",
  "format": null,
  "workspace": "748e50e4-d081-4924-b9e7-f500aac6a71d"
}

POST/v2/prompt/

Create Prompt

Create a new reusable prompt.

Required attributes

Name
Authorization
Type
string
Description
Unique API token for authentication.
Name
name
Type
string
Description
Name for the prompt.
Name
type
Type
string
Description
Prompt type: system, user, or template.

Optional attributes

Name
description
Type
string
Description
Human-readable description of the prompt.
Name
content
Type
string
Description
The prompt text content.
Name
format
Type
string
Description
Output format: json, yaml, xml, or csv. Optional — omit for no specific format.

Request

POST

/v2/prompt/

curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     -H 'Content-Type: application/json' \
     -d '{
       "name": "Product Analysis System Prompt",
       "type": "system",
       "description": "System prompt for product image analysis",
       "content": "You are a helpful assistant that analyzes product images and provides structured data about them."
     }' \
     https://api.ximilar.com/vlm/v2/prompt/

PATCH/v2/prompt/{prompt_id}/

Update Prompt

Update an existing prompt. All tasks and datasets referencing this prompt will automatically use the updated content.

Required attributes

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

Optional attributes

Name
name
Type
string
Description
Updated name.
Name
description
Type
string
Description
Updated description.
Name
content
Type
string
Description
Updated prompt text content.
Name
format
Type
string
Description
Updated output format.

Request

PATCH

/v2/prompt/{prompt_id}/

curl -v -XPATCH \
     -H 'Authorization: Token __API_TOKEN__' \
     -H 'Content-Type: application/json' \
     -d '{
       "content": "You are a helpful assistant that analyzes product images. Provide structured JSON output."
     }' \
     https://api.ximilar.com/vlm/v2/prompt/__PROMPT_ID__/

DELETE/v2/prompt/{prompt_id}/

Delete Prompt

Delete a prompt. Any tasks or datasets referencing this prompt will have their prompt reference set to null.

Required attributes

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

Request

DELETE

/v2/prompt/{prompt_id}/

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