---
title: "Get Domain Schema"
method: POST
path: "/v1/hub/schema"
tags: ["hub"]
---

# Get Domain Schema

`POST /v1/hub/schema`

## Request

- Base URL: `https://api.vlm.run` (the document declares no server; this is the origin it was published from)
- URL: `https://api.vlm.run/v1/hub/schema`
- Auth: none declared

Get the JSON schema for a given domain (document.invoice, document.receipt, etc).

## Request body

- HubSchemaRequest: Request model for the hub schema: /v1/hub/schema
  - `config` GenerationConfig: Request configuration for image/document/video generation.
    - `prompt` string, nullable: Additional user instructions appended to the application or skill prompt for this request.
    - `detail` 'auto' | 'hi' | 'lo': The detail level to use for processing multimodal data.
    - `json_schema` object, nullable: The overridden JSON schema to use for the model. To be used instead of the response model.
    - `skills` AgentSkill[], nullable: List of agent skills to enable for this generation request.
      - `type` string: 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.
      - `skill_id` string, nullable: The unique identifier of the skill — a UUID or a name string (e.g., 'pillow', 'batch-processing').
      - `skill_name` string, nullable: Human-readable skill name for lookup (e.g., 'invoice-extraction'). Alternative to skill_id. Deprecated in favour of skill_id.
      - `skill_version` union: The version of the skill — an integer (e.g. 2) or 'latest'.
        - integer
        - string
      - `version` union: DEPRECATED: Use 'skill_version' instead. The version of the skill.
        - integer
        - string
      - `name` string, nullable: Human-readable name for the inline skill (used for discovery and logging).
      - `description` string, nullable: Short description of what the inline skill does.
      - `source` InlineSkillSource: Source payload for an inline skill bundle. Follows the OpenAI inline skill format:: { "type": "base64", "media_type": "application/zip", "data": "<base64-encoded-zip>" }
        - `type` 'base64': Encoding type for the inline skill data. Currently only 'base64' is supported.
        - `media_type` string: MIME type of the skill bundle. Must be 'application/zip'.
        - `data` string, required: Base64-encoded zip bundle containing the skill files.
      - `bundle` string, nullable: DEPRECATED: Use 'source.data' instead. Base64-encoded zip bundle containing the skill files (inline skills only).
    - `gql_stmt` string, nullable: The GraphQL statement to use for the application. If provided, the response model will be generated from the GraphQL statement.
    - `max_retries` integer: The maximum number of retries to use for the application.
    - `max_tokens` integer: The maximum number of tokens to use for the application.
    - `temperature` number: The temperature to use for the application.
    - `confidence` boolean: Include confidence scores in the response (included in the `_metadata` field).
    - `grounding` boolean: Include grounding in the response (included in the `_metadata` field).
    - `keyframes` boolean: Include keyframes in the video transcription response.
    - `video_segment_duration` number, nullable: Duration in seconds for each video segment when chunking a video for transcription. Defaults to 150.0s.
    - `video_frames_per_segment` integer, nullable: Number of frames to sample per video segment for captioning. Defaults to 8.
    - `video_model` string, nullable: Model ID to use for video segment captioning (e.g. 'vlmrun-orion-1:fast'). When omitted, the server default is used.
    - `video_input_mode` 'frames' | 'native_video', nullable: 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` boolean: 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).
    - `chat_context` string, nullable: Plain-text chat transcript (prior turns + current request) used to ground video captioning / transcription on what the user wants extracted.
    - `page_indices` integer[], nullable: 0-indexed page indices to process for document files. If None, all pages are processed.
    - `use_context_cache` boolean: 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.
    - `service_tier` 'auto' | 'default' | 'standard' | 'flex' | 'priority', nullable: 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.
  - `domain` string, required: The domain to get the schema for (e.g. document.invoice).

## Response `200`

Successful Response

- HubSchemaResponse: Response model for the hub schema: /v1/hub/schema
  - `domain` string, required: The domain to get the schema for.
  - `description` string, required: The description of the domain.
  - `schema_version` string, required: The specific version of the schema.
  - `schema_hash` string, required: The sha256 hash of the schema.
  - `gql_stmt` string, required: The GraphQL statement for the domain.
  - `json_schema` object, required: The JSON schema for the domain.
  - `json_sample` object, nullable: A sample JSON object that matches the schema.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/vlm/apis/vlm-run-unified-server.md) · [All operations](https://skmtc.dev/vlm/apis/vlm-run-unified-server/llms.txt) · [OpenAPI document](https://skmtc.dev/vlm/apis/vlm-run-unified-server/revisions/4a68ab36546b?raw)