> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vlm.run/llms.txt
> Use this file to discover all available pages before exploring further.
# Get schema for domain
> Get the JSON schema for a given domain (document.invoice, document.receipt, etc).
```python Python theme={"theme":{"light":"github-light","dark":"dark-plus"}}
!pip install vlmrun
from vlmrun.client import VLMRun
client = VLMRun(api_key="")
response = client.hub.get_schema(domain="document.invoice")
```
```typescript Node.js SDK theme={"theme":{"light":"github-light","dark":"dark-plus"}}
import { VlmRun } from "vlmrun";
const client = new VlmRun({ apiKey: "" });
const response = await client.hub.getSchema({ domain: "document.invoice" });
console.log(response);
```
## Description
This endpoint returns the JSON schema for a given domain, as defined in the [VLM Run Hub](https://github.com/vlm-run/vlmrun-hub).
## OpenAPI
````yaml https://api.vlm.run/openapi.json POST /v1/hub/schema
openapi: 3.1.0
info:
title: VLM Run Unified Server
description: Unified server for VLM Run Agent and API
termsOfService: https://vlm.run/terms-of-service
contact:
name: VLM Run Support Team
url: https://vlm.run/
email: support@vlm.run
version: 2026-05-19.0
servers: []
security: []
paths:
/v1/hub/schema:
post:
tags:
- hub
summary: Get Domain Schema
description: >-
Get the JSON schema for a given domain (document.invoice,
document.receipt, etc).
operationId: get_domain_schema_v1_hub_schema_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/HubSchemaRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/HubSchemaResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
HubSchemaRequest:
properties:
config:
$ref: '#/components/schemas/GenerationConfig'
description: The VLM generation config to be used for //generate.
domain:
type: string
title: Domain
description: The domain to get the schema for (e.g. document.invoice).
type: object
required:
- domain
title: HubSchemaRequest
description: 'Request model for the hub schema: /v1/hub/schema'
HubSchemaResponse:
properties:
domain:
type: string
title: Domain
description: The domain to get the schema for.
description:
type: string
title: Description
description: The description of the domain.
schema_version:
type: string
title: Schema Version
description: The specific version of the schema.
schema_hash:
type: string
title: Schema Hash
description: The sha256 hash of the schema.
gql_stmt:
type: string
title: Gql Stmt
description: The GraphQL statement for the domain.
json_schema:
additionalProperties: true
type: object
title: Json Schema
description: The JSON schema for the domain.
json_sample:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Json Sample
description: A sample JSON object that matches the schema.
type: object
required:
- domain
- description
- schema_version
- schema_hash
- gql_stmt
- json_schema
title: HubSchemaResponse
description: 'Response model for the hub schema: /v1/hub/schema'
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
GenerationConfig:
properties:
prompt:
anyOf:
- type: string
- type: 'null'
title: Prompt
description: >-
Additional user instructions appended to the application or skill
prompt for this request.
detail:
type: string
enum:
- auto
- hi
- lo
title: Detail
description: The detail level to use for processing multimodal data.
default: auto
json_schema:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Json Schema
description: >-
The overridden JSON schema to use for the model. To be used instead
of the response model.
skills:
anyOf:
- items:
$ref: '#/components/schemas/AgentSkill'
type: array
- type: 'null'
title: Skills
description: List of agent skills to enable for this generation request.
gql_stmt:
anyOf:
- type: string
- type: 'null'
title: Gql Stmt
description: >-
The GraphQL statement to use for the application. If provided, the
response model will be generated from the GraphQL statement.
max_retries:
type: integer
title: Max Retries
description: The maximum number of retries to use for the application.
default: 1
max_tokens:
type: integer
title: Max Tokens
description: The maximum number of tokens to use for the application.
default: 65535
temperature:
type: number
title: Temperature
description: The temperature to use for the application.
default: 0
confidence:
type: boolean
title: Confidence
description: >-
Include confidence scores in the response (included in the
`_metadata` field).
default: false
grounding:
type: boolean
title: Grounding
description: >-
Include grounding in the response (included in the `_metadata`
field).
default: false
keyframes:
type: boolean
title: Keyframes
description: Include keyframes in the video transcription response.
default: false
video_segment_duration:
anyOf:
- type: number
minimum: 1
- type: 'null'
title: Video Segment Duration
description: >-
Duration in seconds for each video segment when chunking a video for
transcription. Defaults to 150.0s.
video_frames_per_segment:
anyOf:
- type: integer
minimum: 1
- type: 'null'
title: Video Frames Per Segment
description: >-
Number of frames to sample per video segment for captioning.
Defaults to 8.
video_model:
anyOf:
- type: string
- type: 'null'
title: Video Model
description: >-
Model ID to use for video segment captioning (e.g.
'vlmrun-orion-1:fast'). When omitted, the server default is used.
video_input_mode:
anyOf:
- type: string
enum:
- frames
- native_video
- type: 'null'
title: Video Input Mode
description: >-
How to pass video to the captioning model: 'frames' extracts N JPEG
frames per segment, 'native_video' sends the mp4 clip directly via
video_url for models with native video understanding. Defaults to
'native_video' for Qwen deployment models, 'frames' for others.
video_transcribe_audio:
type: boolean
title: Video Transcribe Audio
description: >-
When True, transcribe the audio track to align segment boundaries.
When False (default), skip ASR and use fixed-duration video segments
only (visual-only captioning).
default: false
chat_context:
anyOf:
- type: string
- type: 'null'
title: Chat Context
description: >-
Plain-text chat transcript (prior turns + current request) used to
ground video captioning / transcription on what the user wants
extracted.
page_indices:
anyOf:
- items:
type: integer
type: array
- type: 'null'
title: Page Indices
description: >-
0-indexed page indices to process for document files. If None, all
pages are processed.
use_context_cache:
type: boolean
title: Use Context Cache
description: >-
Reuse cached representations of document/video content across calls.
When True (default), the file is cached after the first call so
repeated queries against the same file skip re-transmitting its
contents. Set to False to always send the full content.
default: true
service_tier:
anyOf:
- type: string
enum:
- auto
- default
- standard
- flex
- priority
- type: 'null'
title: Service Tier
description: >-
Delivery tier for the request. 'standard'/'default' uses baseline
rates, 'flex' applies a 50% discount with higher latency, 'priority'
applies a 1.8x premium. When omitted (or 'auto'), the server default
('standard') applies. The chosen tier drives both billing and the
latency/availability SLO.
type: object
title: GenerationConfig
description: Request configuration for image/document/video generation.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
AgentSkill:
properties:
type:
type: string
title: Type
description: >-
The type of the skill. Use 'skill_reference' for DB-stored skills
referenced by id/name. Use 'inline' to provide the skill as a
base64-encoded zip bundle.
default: skill_reference
skill_id:
anyOf:
- type: string
- type: 'null'
title: Skill Id
description: >-
The unique identifier of the skill — a UUID or a name string (e.g.,
'pillow', 'batch-processing').
skill_name:
anyOf:
- type: string
- type: 'null'
title: Skill Name
description: >-
Human-readable skill name for lookup (e.g., 'invoice-extraction').
Alternative to skill_id. Deprecated in favour of skill_id.
skill_version:
anyOf:
- type: integer
- type: string
title: Skill Version
description: The version of the skill — an integer (e.g. 2) or 'latest'.
default: latest
version:
anyOf:
- type: integer
- type: string
- type: 'null'
title: Version
description: 'DEPRECATED: Use ''skill_version'' instead. The version of the skill.'
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: >-
Human-readable name for the inline skill (used for discovery and
logging).
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: Short description of what the inline skill does.
source:
anyOf:
- $ref: '#/components/schemas/InlineSkillSource'
- type: 'null'
description: >-
Source payload for inline skills. Contains the base64-encoded zip
bundle with type, media_type, and data fields.
bundle:
anyOf:
- type: string
- type: 'null'
title: Bundle
description: >-
DEPRECATED: Use 'source.data' instead. Base64-encoded zip bundle
containing the skill files (inline skills only).
type: object
title: AgentSkill
description: >-
A modular capability that extends the agent's functionality.
Agent Skills are reusable, filesystem-based resources that provide the
agent
with domain-specific expertise: workflows, context, and best practices.
Each skill packages instructions, metadata, and optional resources
(scripts,
templates, snippets) that the agent uses automatically when relevant.
Two modes are supported:
1. **Referenced skills** (``type="skill_reference"``) – Provide
``skill_id``
(UUID or name) and optionally ``skill_version`` (integer or ``"latest"``).
.. code-block:: json
{"type": "skill_reference", "skill_id": "pillow", "skill_version": "latest"}
2. **Inline skills** (``type="inline"``) – Supply ``name``,
``description``,
and a ``source`` object containing the base64-encoded zip bundle. The zip
must contain exactly one ``SKILL.md`` file. No database lookup is required.
.. code-block:: json
{
"type": "inline",
"name": "csv-insights",
"description": "Summarize CSV files.",
"source": {
"type": "base64",
"media_type": "application/zip",
"data": ""
}
}
Legacy format with flat ``bundle`` field is also accepted for backward
compatibility.
InlineSkillSource:
properties:
type:
type: string
const: base64
title: Type
description: >-
Encoding type for the inline skill data. Currently only 'base64' is
supported.
default: base64
media_type:
type: string
title: Media Type
description: MIME type of the skill bundle. Must be 'application/zip'.
default: application/zip
data:
type: string
title: Data
description: Base64-encoded zip bundle containing the skill files.
type: object
required:
- data
title: InlineSkillSource
description: |-
Source payload for an inline skill bundle.
Follows the OpenAI inline skill format::
{
"type": "base64",
"media_type": "application/zip",
"data": ""
}
````