Zocomputer AI API
The AI API from Zocomputer — 3 operation(s) for ai.
OpenAPI Specification
openapi: 3.1.0
info:
title: Zo AI API
version: 1.0.0
servers:
- url: https://api.zo.computer
description: Zo API
security:
- bearerAuth: []
tags:
- name: AI
paths:
/zo/ask:
post:
tags:
- AI
summary: Ask Zo
description: 'Send a message to your Zo and get a response. Use `stream: true` for Server-Sent Events streaming.'
operationId: zoAsk
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ZoAskRequest'
required: true
responses:
'200':
description: Success (non-streaming)
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/ZoAskResponseSuccess'
- $ref: '#/components/schemas/ZoAskResponseError'
- $ref: '#/components/schemas/ZoAskResponseSuccess'
- $ref: '#/components/schemas/ZoAskResponseError'
title: Response 200 Zoask
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/models/available:
get:
tags:
- AI
summary: List available models
description: List all available models. When authenticated with an API key, includes BYOK configurations.
operationId: getAvailableModels
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ZoModelsResponse'
/models/catalog:
get:
tags:
- AI
summary: Get the full model catalog
description: Return the full public model catalog — the picker model list plus the scalar globals (default chat model, featured flags/labels, promo end date, deprecation map). This is the runtime, fleet-fresh equivalent of the baked types/generated/models.ts manifest, built from the same source so the two never drift. Public (no auth); host-specific disabled models are filtered separately at request time. Cached for 5 minutes.
operationId: getModelCatalog
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ModelCatalogResponse'
components:
schemas:
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
StructuredOutputFormat:
properties:
type:
type: string
const: object
title: Type
description:
anyOf:
- type: string
- type: 'null'
title: Description
required:
items:
type: string
type: array
title: Required
properties:
additionalProperties:
anyOf:
- $ref: '#/components/schemas/PropertyScalar'
- $ref: '#/components/schemas/PropertyObject'
- $ref: '#/components/schemas/PropertyEnum'
- $ref: '#/components/schemas/PropertyArray'
type: object
title: Properties
type: object
required:
- type
- required
- properties
title: StructuredOutputFormat
description: "Example with the various kind of properties that can be stated:\n{\n \"type\": \"object\",\n \"description\": \"descriptions are optional but helpful, each property can have them\",\n \"properties\": {\n \"names\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"first_name\": {\n \"type\": \"string\"\n },\n \"temperature_degrees\": {\n \"type\": \"number\"\n },\n \"temperature_unit\": {\n \"type\": \"string\",\n \"description\": \"The unit to return the temperature in\",\n \"enum\": [\"F\", \"C\"]\n },\n \"nested_object\": {\n \"type\": \"object\",\n \"description\": \"A nested object\",\n \"properties\": {\n \"nested_object_property\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\"nested_object_property\"]\n }\n },\n \"required\": [\"names\", \"first_name\"]\n}"
PublicModelChoice:
properties:
value:
type: string
title: Value
description: Public model identifier (e.g. 'zo:openai/gpt-5.4')
label:
type: string
title: Label
description: User-friendly model name
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: Plain-language picker description
quality_tier:
anyOf:
- type: integer
enum:
- 1
- 2
- 3
- type: 'null'
title: Quality Tier
description: 1-3 star quality rating; null for hidden/non-rated variants
is_fast:
type: boolean
title: Is Fast
description: Whether to render the speed (zap) badge
default: false
url:
anyOf:
- type: string
- type: 'null'
title: Url
description: Model info URL
release_date:
anyOf:
- type: string
- type: 'null'
title: Release Date
description: Release date (YYYY-MM-DD)
slug:
type: string
title: Slug
description: Model slug
vendor:
type: string
title: Vendor
description: Model provider display name
vendor_slug:
type: string
title: Vendor Slug
description: Model provider slug (drives the vendor icon)
country:
anyOf:
- type: string
- type: 'null'
title: Country
description: ISO 3166-1 alpha-2 country code
type:
type: string
title: Type
description: 'Access tier: ''free'' (available to all) or ''subscribers'' (premium metered)'
meter:
type: string
title: Meter
description: Billing meter event name (e.g. 'chat', 'image')
priority:
anyOf:
- type: number
- type: 'null'
title: Priority
description: Sort priority for pickers; lower values first
knowledge_cutoff_date:
anyOf:
- type: string
- type: 'null'
title: Knowledge Cutoff Date
description: Knowledge cutoff date (chat models only)
context_window:
anyOf:
- type: integer
- type: 'null'
title: Context Window
description: Maximum context length in tokens (chat models only)
supports_images:
type: boolean
title: Supports Images
description: Whether the model accepts image input
default: true
features:
items:
type: string
type: array
title: Features
description: Capability flags (e.g. 'extend_reasoning')
reasoning:
anyOf:
- oneOf:
- $ref: '#/components/schemas/CatalogReasoningLevels'
- $ref: '#/components/schemas/CatalogReasoningRange'
discriminator:
propertyName: kind
mapping:
levels: '#/components/schemas/CatalogReasoningLevels'
range: '#/components/schemas/CatalogReasoningRange'
- type: 'null'
title: Reasoning
description: Reasoning-control UI config, if any
input_tok_price:
anyOf:
- type: string
- type: 'null'
title: Input Tok Price
description: Price per input token (cents)
output_tok_price:
anyOf:
- type: string
- type: 'null'
title: Output Tok Price
description: Price per output token (cents)
cached_read_tok_price:
anyOf:
- type: string
- type: 'null'
title: Cached Read Tok Price
description: Price per cached-read token (cents)
cached_write_tok_price:
anyOf:
- type: string
- type: 'null'
title: Cached Write Tok Price
description: Price per cached-write token (cents)
input_audio_minutes_price:
anyOf:
- type: string
- type: 'null'
title: Input Audio Minutes Price
description: Price per minute of audio input (cents)
output_megapixel_price:
anyOf:
- type: string
- type: 'null'
title: Output Megapixel Price
description: Price per megapixel of image output (cents)
output_video_seconds_price:
anyOf:
- type: string
- type: 'null'
title: Output Video Seconds Price
description: Price per second of video output (cents)
tier_threshold_input_tokens:
anyOf:
- type: integer
- type: 'null'
title: Tier Threshold Input Tokens
description: Input-token threshold above which higher-tier pricing applies
tier_higher_input_tok_price:
anyOf:
- type: string
- type: 'null'
title: Tier Higher Input Tok Price
description: Higher-tier input token price (cents)
tier_higher_output_tok_price:
anyOf:
- type: string
- type: 'null'
title: Tier Higher Output Tok Price
description: Higher-tier output token price (cents)
hide_from_ui:
type: boolean
title: Hide From Ui
description: Whether the model is hidden from UI pickers
default: false
type: object
required:
- value
- label
- slug
- vendor
- vendor_slug
- type
- meter
title: PublicModelChoice
description: 'One model in the public catalog.
Mirrors the public (non-billing) fields of ha-core ``ModelChoice`` — Stripe
meter-item ids and ``deprecated_by`` are stripped. Shape-for-shape with the
baked ``AVAILABLE_MODELS`` manifest in ``types/generated/models.ts`` so the
web app can swap the static import for this runtime payload directly.'
ZoModelInfo:
properties:
model_name:
type: string
title: Model Name
description: Unique public model identifier (e.g., 'zo:openai/gpt-5.4')
label:
type: string
title: Label
description: Human-readable model name
vendor:
type: string
title: Vendor
description: Model provider (e.g., 'Anthropic', 'OpenAI')
type:
anyOf:
- type: string
enum:
- free
- subscribers
- type: 'null'
title: Type
description: 'Access tier: ''free'' (available to all) or ''subscribers'' (premium built-in metered models)'
priority:
anyOf:
- type: number
- type: 'null'
title: Priority
description: Sort priority for UI pickers; lower values appear first
context_window:
anyOf:
- type: integer
- type: 'null'
title: Context Window
description: Maximum context length in tokens
is_byok:
type: boolean
title: Is Byok
description: True if this is a user-configured BYOK model
default: false
type: object
required:
- model_name
- label
- vendor
title: ZoModelInfo
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ModelCatalogResponse:
properties:
models:
items:
$ref: '#/components/schemas/PublicModelChoice'
type: array
title: Models
description: The picker model list, sorted by priority
default_chat_model_id:
type: string
title: Default Chat Model Id
description: Public id of the default chat model
featured_model_ids:
items:
type: string
type: array
title: Featured Model Ids
description: Public ids of featured ('Free' badge) models
featured_models_are_free:
type: boolean
title: Featured Models Are Free
description: When true, the frontend shows a Free badge on featured models
featured_model_labels:
items:
type: string
type: array
title: Featured Model Labels
description: Labels for featured_model_ids, in order
promo_end_date:
anyOf:
- type: string
- type: 'null'
title: Promo End Date
description: Promo end date (YYYY-MM-DD) or null
deprecation_map:
additionalProperties:
type: string
type: object
title: Deprecation Map
description: Map of deprecated public model id → active successor public id
type: object
required:
- models
- default_chat_model_id
- featured_model_ids
- featured_models_are_free
- featured_model_labels
- deprecation_map
title: ModelCatalogResponse
description: 'Full public model catalog served by ``GET /models/catalog``.
Mirrors the baked ``types/generated/models.ts`` manifest (the picker list
plus the scalar globals) so the web app can fetch live catalog data at
runtime and fall back to the baked copy when the fetch is pending or fails.'
CatalogReasoningRange:
properties:
kind:
type: string
const: range
title: Kind
description: 'Discriminator: reasoning is a continuous token budget'
min_tokens:
type: integer
title: Min Tokens
description: Minimum thinking-token budget
max_tokens:
type: integer
title: Max Tokens
description: Maximum thinking-token budget
type: object
required:
- kind
- min_tokens
- max_tokens
title: CatalogReasoningRange
description: Reasoning configured as a continuous thinking-token budget.
CatalogReasoningLevels:
properties:
kind:
type: string
const: levels
title: Kind
description: 'Discriminator: reasoning selected from discrete levels'
levels:
items:
$ref: '#/components/schemas/CatalogReasoningLevel'
type: array
title: Levels
description: Available reasoning levels, lowest first
type: object
required:
- kind
- levels
title: CatalogReasoningLevels
description: Reasoning configured as discrete levels (e.g. low/medium/high).
ZoModelsResponse:
properties:
models:
items:
$ref: '#/components/schemas/ZoModelInfo'
type: array
title: Models
description: List of available AI models
featured_models_are_free:
type: boolean
title: Featured Models Are Free
description: When true, frontend shows Free badge on featured models
type: object
required:
- models
- featured_models_are_free
title: ZoModelsResponse
description: Response from /models/available endpoint.
PropertyScalar:
properties:
type:
type: string
enum:
- string
- number
- boolean
title: Type
description:
anyOf:
- type: string
- type: 'null'
title: Description
type: object
required:
- type
title: PropertyScalar
PropertyArray:
properties:
type:
type: string
const: array
title: Type
description:
anyOf:
- type: string
- type: 'null'
title: Description
items:
anyOf:
- $ref: '#/components/schemas/PropertyScalar'
- $ref: '#/components/schemas/PropertyObject'
- $ref: '#/components/schemas/PropertyEnum'
- $ref: '#/components/schemas/PropertyArray'
title: Items
type: object
required:
- type
- items
title: PropertyArray
PropertyObject:
properties:
type:
type: string
const: object
title: Type
description:
anyOf:
- type: string
- type: 'null'
title: Description
required:
items:
type: string
type: array
title: Required
properties:
additionalProperties:
anyOf:
- $ref: '#/components/schemas/PropertyScalar'
- $ref: '#/components/schemas/PropertyObject'
- $ref: '#/components/schemas/PropertyEnum'
- $ref: '#/components/schemas/PropertyArray'
type: object
title: Properties
type: object
required:
- type
- required
- properties
title: PropertyObject
CatalogReasoningLevel:
properties:
value:
type: integer
title: Value
description: Slider position (0-based) for this reasoning level
label:
type: string
title: Label
description: Human-readable label, e.g. 'High reasoning'
type: object
required:
- value
- label
title: CatalogReasoningLevel
description: One selectable reasoning level in a model's reasoning slider.
PropertyEnum:
properties:
type:
type: string
const: string
title: Type
description:
anyOf:
- type: string
- type: 'null'
title: Description
enum:
items:
type: string
type: array
title: Enum
type: object
required:
- type
- enum
title: PropertyEnum
ZoAskRequest:
properties:
input:
type: string
title: Input
description: Your message to Zo
conversation_id:
anyOf:
- type: string
- type: 'null'
title: Conversation Id
description: Continue an existing conversation
model_name:
anyOf:
- type: string
- type: 'null'
title: Model Name
description: Override the default model (for example, 'zo:openai/gpt-5.4'; use /models/available to list available)
persona_id:
anyOf:
- type: string
- type: 'null'
title: Persona Id
description: Override the active persona (use /personas/available to list available)
output_format:
anyOf:
- $ref: '#/components/schemas/StructuredOutputFormat'
- type: 'null'
description: JSON Schema for structured output
memory_mode:
type: string
enum:
- enabled
- 'off'
title: Memory Mode
description: 'Memory mode for this request: ''enabled'' includes workspace memory, ''off'' disables it.'
default: enabled
stream:
type: boolean
title: Stream
description: Enable streaming mode (returns Server-Sent Events)
default: false
type: object
required:
- input
title: ZoAskRequest
ZoAskResponseError:
properties:
error:
type: string
title: Error
description: Error message
type: object
required:
- error
title: ZoAskResponseError
ZoAskResponseSuccess:
properties:
output:
anyOf:
- type: string
- additionalProperties: true
type: object
title: Output
description: Zo's response (object if output_format was specified)
conversation_id:
anyOf:
- type: string
- type: 'null'
title: Conversation Id
description: ID to continue this conversation
type: object
required:
- output
title: ZoAskResponseSuccess
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Zo API key (zo_sk_...)