REST API
Authentication
curl https://api.ojin.ai/v1/model-configs \
-H "X-API-Key: $OJIN_API_KEY"Model Configurations
API key for authenticated access to the Ojin REST API.
Filter model configurations by the model_variant_id.
Filter model configurations whose model variant contains this tag (e.g. "_agent-tts").
Filter items by ownership source. Use 'org' for items owned by the user's organization, 'template' for items from the template organization. Defaults to 'org'.
orgPossible values: Number of items to return per page.
20Number of items to skip for pagination.
0A paginated list of model configurations.
Invalid request payload or parameters.
Authentication token is missing, invalid, or expired.
Authenticated principal does not have permission.
GET /v1/model-configs HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Accept: */*
{
"data": [
{
"model_config_id": "123e4567-e89b-12d3-a456-426614174000",
"organization_id": "text",
"model_id": "text",
"model_variant_id": "text",
"created_by": "text",
"title": "text",
"model_configurations": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}
],
"pagination": {
"limit": 20,
"offset": 0,
"total_items": 150
}
}API key for authenticated access to the Ojin REST API.
Payload for creating a new Model Configuration.
Model Configuration created.
Represents a specific configuration of a ModelVariant.
Server-generated unique ID.
Owning organization ID (from external IdP).
ID of the parent Model, derived from the Model Variant.
ID of the ModelVariant being configured. NOT NULL.
Creator's user ID (from external IdP), or api_key:<id> when created via an API key.
Title for the configuration. NOT NULL, unique per organization_id.
Timestamp of creation. Defaults to CURRENT_TIMESTAMP.
Timestamp of last update. Auto-updates.
Invalid request payload or parameters.
Authentication token is missing, invalid, or expired.
Authenticated principal does not have permission.
Referenced ModelVariant not found.
POST /v1/model-configs HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 104
{
"title": "text",
"model_variant_id": "text",
"model_configurations": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}{
"model_config_id": "123e4567-e89b-12d3-a456-426614174000",
"organization_id": "text",
"model_id": "text",
"model_variant_id": "text",
"created_by": "text",
"title": "text",
"model_configurations": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}API key for authenticated access to the Ojin REST API.
The unique identifier (UUID) of the Model Configuration.
Model Configuration details.
Represents a specific configuration of a ModelVariant.
Server-generated unique ID.
Owning organization ID (from external IdP).
ID of the parent Model, derived from the Model Variant.
ID of the ModelVariant being configured. NOT NULL.
Creator's user ID (from external IdP), or api_key:<id> when created via an API key.
Title for the configuration. NOT NULL, unique per organization_id.
Timestamp of creation. Defaults to CURRENT_TIMESTAMP.
Timestamp of last update. Auto-updates.
Authentication token is missing, invalid, or expired.
Authenticated principal does not have permission.
The requested resource was not found.
GET /v1/model-configs/{model_config_id} HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Accept: */*
{
"model_config_id": "123e4567-e89b-12d3-a456-426614174000",
"organization_id": "text",
"model_id": "text",
"model_variant_id": "text",
"created_by": "text",
"title": "text",
"model_configurations": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}API key for authenticated access to the Ojin REST API.
The unique identifier (UUID) of the Model Configuration.
Payload for updating a Model Configuration (title and parameters only).
Model Configuration updated.
Represents a specific configuration of a ModelVariant.
Server-generated unique ID.
Owning organization ID (from external IdP).
ID of the parent Model, derived from the Model Variant.
ID of the ModelVariant being configured. NOT NULL.
Creator's user ID (from external IdP), or api_key:<id> when created via an API key.
Title for the configuration. NOT NULL, unique per organization_id.
Timestamp of creation. Defaults to CURRENT_TIMESTAMP.
Timestamp of last update. Auto-updates.
Invalid request payload or parameters.
Authentication token is missing, invalid, or expired.
Authenticated principal does not have permission.
The requested resource was not found.
PUT /v1/model-configs/{model_config_id} HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 78
{
"title": "text",
"model_configurations": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}{
"model_config_id": "123e4567-e89b-12d3-a456-426614174000",
"organization_id": "text",
"model_id": "text",
"model_variant_id": "text",
"created_by": "text",
"title": "text",
"model_configurations": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}API key for authenticated access to the Ojin REST API.
The unique identifier (UUID) of the Model Configuration.
Delete reference to the agent configuration.
Operation successful, no content to return.
No content
Authentication token is missing, invalid, or expired.
Authenticated principal does not have permission.
The requested resource was not found.
Conflict - Cannot delete, referenced by AgentConfig.
DELETE /v1/model-configs/{model_config_id} HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Accept: */*
No content
Model Variants
API key for authenticated access to the Ojin REST API.
Filter model variants by parent model_id.
Filter by status.
Filter model variants by a comma-separated list of tags (AND logic).
Number of items to return per page.
20Number of items to skip for pagination.
0A paginated list of model variants.
Invalid request payload or parameters.
Authentication token is missing, invalid, or expired.
Authenticated principal does not have permission.
GET /v1/model-variants HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Accept: */*
{
"data": [
{
"model_variant_id": "ojin/oris-1.0/standard",
"model_id": "ojin/oris-1.0",
"title": "Standard Quality",
"description": {
"resolution": "1024x1024"
},
"preview_media_url": "https://cdn.ojin.ai/previews/variant.jpg",
"configuration_schema": {
"type": "object",
"properties": {
"param1": {
"type": "string"
}
}
},
"tags": [
"general-purpose",
"real-time"
],
"status": "available",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}
],
"pagination": {
"limit": 20,
"offset": 0,
"total_items": 150
}
}API key for authenticated access to the Ojin REST API.
The unique identifier of the model variant.
Model Variant details.
Represents a specific variant of a Model.
Client-provided unique identifier (e.g., "ojin/oris-v1/standard").
ojin/oris-1.0/standardIdentifier of the parent Model. NOT NULL.
ojin/oris-1.0Display name for the variant. NOT NULL, unique per model_id.
Standard QualityURL for a preview media.
https://cdn.ojin.ai/previews/variant.jpgList of descriptive tags. NOT NULL, defaults to '[]'.
["general-purpose","real-time"]Status (e.g., 'available', 'deprecated'). NOT NULL. List managed in code.
availableTimestamp of creation. Server-generated. Defaults to CURRENT_TIMESTAMP.
Timestamp of last update. Server-generated. Auto-updates.
Authentication token is missing, invalid, or expired.
Authenticated principal does not have permission.
The requested resource was not found.
GET /v1/model-variants/{model_variant_id} HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Accept: */*
{
"model_variant_id": "ojin/oris-1.0/standard",
"model_id": "ojin/oris-1.0",
"title": "Standard Quality",
"description": {
"resolution": "1024x1024"
},
"preview_media_url": "https://cdn.ojin.ai/previews/variant.jpg",
"configuration_schema": {
"type": "object",
"properties": {
"param1": {
"type": "string"
}
}
},
"tags": [
"general-purpose",
"real-time"
],
"status": "available",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}Assets
API key for authenticated access to the Ojin REST API.
Payload to initiate a multipart asset upload.
Original filename of the asset.
conference_highlights.movCategory for the asset (e.g., 'video', 'image').
videoClient-declared MIME type of the file.
video/quicktimeClient-declared file size in bytes.
52428800Multipart upload initiated successfully. Returns asset_id and upload_id.
Response from initiating a multipart asset upload.
A unique ID generated by Core API for this asset transaction.
The multipart upload ID from S3, used to identify this multipart upload session.
The S3 key for this asset.
Invalid request payload or parameters.
Authentication token is missing, invalid, or expired.
Authenticated principal does not have permission.
POST /v1/assets/initiate-upload HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 110
{
"name": "conference_highlights.mov",
"category": "video",
"content_type": "video/quicktime",
"size_bytes": 52428800
}{
"asset_id": "123e4567-e89b-12d3-a456-426614174000",
"upload_id": "text",
"s3_key": "text"
}API key for authenticated access to the Ojin REST API.
Payload to get a pre-signed URL for uploading a specific part of a multipart upload.
The S3 key for this asset.
The asset ID from the initiate upload response.
The multipart upload ID from the initiate upload response.
The part number for this upload part (1-10000).
Pre-signed URL generated successfully for the specified part.
Response containing the pre-signed URL for uploading a specific part.
The pre-signed S3 URL to PUT this specific part to.
The part number this URL is for.
Invalid request payload or parameters.
Authentication token is missing, invalid, or expired.
Authenticated principal does not have permission.
Multipart upload session not found.
POST /v1/assets/sign-part HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 102
{
"s3_key": "text",
"asset_id": "123e4567-e89b-12d3-a456-426614174000",
"upload_id": "text",
"part_number": 1
}{
"upload_url": "text",
"part_number": 1
}API key for authenticated access to the Ojin REST API.
Payload to finalize a multipart asset upload and create the asset metadata record in DB.
The unique ID received from the 'initiate-upload' step.
The multipart upload ID from the 'initiate-upload' step.
The original filename (must be consistent with initiate request).
The asset category (must be consistent with initiate request).
Final confirmed MIME type of the asset.
Final confirmed size of the asset in bytes.
Multipart upload completed successfully and Asset record created in DB.
Represents a digital asset managed by the Core API.
Unique identifier for the Asset, generated during upload initiation.
123e4567-e89b-12d3-a456-426614174000ID of the Organisation (from external IdP) that owns this Asset. Server-set.
org_123abcUser ID of the creator (from external IdP), or api_key:<id> when created via an API key. Server-set.
user_789defThe original file name of the Asset. NOT NULL.
product_promo.mp4Primary category of the Asset (e.g., 'video', 'image', 'weight'). NOT NULL. List of values managed in code.
videoThe MIME type of the asset. NOT NULL.
video/mp4The size of the asset in bytes. NOT NULL.
10485760The ETag of the S3 object, used for integrity checking. NOT NULL.
"d41d8cd98f00b204e9800998ecf8427e"Timestamp of when this Asset record was created (finalized). Server-generated. Defaults to CURRENT_TIMESTAMP.
Timestamp of the last update to this Asset record. Server-generated. Auto-updates on modification.
A temporary, pre-signed URL to download the asset's content. This URL will expire.
https://s3.amazonaws.com/ojin-assets/asset.mp4?X-Amz-Algorithm=...Invalid request payload or parameters.
Authentication token is missing, invalid, or expired.
Authenticated principal does not have permission.
Multipart upload session not found.
Conflict with the current state of the resource.
POST /v1/assets HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 181
{
"asset_id": "123e4567-e89b-12d3-a456-426614174000",
"upload_id": "text",
"name": "text",
"category": "text",
"content_type": "text",
"size_bytes": 1,
"parts": [
{
"part_number": 1,
"etag": "text"
}
]
}{
"asset_id": "123e4567-e89b-12d3-a456-426614174000",
"organization_id": "org_123abc",
"created_by": "user_789def",
"name": "product_promo.mp4",
"category": "video",
"content_type": "video/mp4",
"size_bytes": 10485760,
"etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"asset_url": "https://s3.amazonaws.com/ojin-assets/asset.mp4?X-Amz-Algorithm=..."
}API key for authenticated access to the Ojin REST API.
Filter items by ownership source. Use 'org' for items owned by the user's organization, 'template' for items from the template organization. Defaults to 'org'.
orgPossible values: Filter assets by category.
Filter assets by name (e.g., for partial match - specific behavior TBD by implementation).
Number of items to return per page.
20Number of items to skip for pagination.
0A paginated list of Asset metadata.
Invalid request payload or parameters.
Authentication token is missing, invalid, or expired.
Authenticated principal does not have permission.
GET /v1/assets HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Accept: */*
{
"data": [
{
"asset_id": "123e4567-e89b-12d3-a456-426614174000",
"organization_id": "org_123abc",
"created_by": "user_789def",
"name": "product_promo.mp4",
"category": "video",
"content_type": "video/mp4",
"size_bytes": 10485760,
"etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"asset_url": "https://s3.amazonaws.com/ojin-assets/asset.mp4?X-Amz-Algorithm=..."
}
],
"pagination": {
"limit": 20,
"offset": 0,
"total_items": 150
}
}API key for authenticated access to the Ojin REST API.
The unique identifier (UUID) of the Asset.
Successfully retrieved Asset metadata, including a download URL.
Represents a digital asset managed by the Core API.
Unique identifier for the Asset, generated during upload initiation.
123e4567-e89b-12d3-a456-426614174000ID of the Organisation (from external IdP) that owns this Asset. Server-set.
org_123abcUser ID of the creator (from external IdP), or api_key:<id> when created via an API key. Server-set.
user_789defThe original file name of the Asset. NOT NULL.
product_promo.mp4Primary category of the Asset (e.g., 'video', 'image', 'weight'). NOT NULL. List of values managed in code.
videoThe MIME type of the asset. NOT NULL.
video/mp4The size of the asset in bytes. NOT NULL.
10485760The ETag of the S3 object, used for integrity checking. NOT NULL.
"d41d8cd98f00b204e9800998ecf8427e"Timestamp of when this Asset record was created (finalized). Server-generated. Defaults to CURRENT_TIMESTAMP.
Timestamp of the last update to this Asset record. Server-generated. Auto-updates on modification.
A temporary, pre-signed URL to download the asset's content. This URL will expire.
https://s3.amazonaws.com/ojin-assets/asset.mp4?X-Amz-Algorithm=...Authentication token is missing, invalid, or expired.
Authenticated principal does not have permission.
The requested resource was not found.
GET /v1/assets/{asset_id}/download HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Accept: */*
{
"asset_id": "123e4567-e89b-12d3-a456-426614174000",
"organization_id": "org_123abc",
"created_by": "user_789def",
"name": "product_promo.mp4",
"category": "video",
"content_type": "video/mp4",
"size_bytes": 10485760,
"etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"asset_url": "https://s3.amazonaws.com/ojin-assets/asset.mp4?X-Amz-Algorithm=..."
}API key for authenticated access to the Ojin REST API.
The unique identifier (UUID) of the Asset.
Successfully retrieved Asset metadata.
Represents a digital asset managed by the Core API.
Unique identifier for the Asset, generated during upload initiation.
123e4567-e89b-12d3-a456-426614174000ID of the Organisation (from external IdP) that owns this Asset. Server-set.
org_123abcUser ID of the creator (from external IdP), or api_key:<id> when created via an API key. Server-set.
user_789defThe original file name of the Asset. NOT NULL.
product_promo.mp4Primary category of the Asset (e.g., 'video', 'image', 'weight'). NOT NULL. List of values managed in code.
videoThe MIME type of the asset. NOT NULL.
video/mp4The size of the asset in bytes. NOT NULL.
10485760The ETag of the S3 object, used for integrity checking. NOT NULL.
"d41d8cd98f00b204e9800998ecf8427e"Timestamp of when this Asset record was created (finalized). Server-generated. Defaults to CURRENT_TIMESTAMP.
Timestamp of the last update to this Asset record. Server-generated. Auto-updates on modification.
A temporary, pre-signed URL to download the asset's content. This URL will expire.
https://s3.amazonaws.com/ojin-assets/asset.mp4?X-Amz-Algorithm=...Authentication token is missing, invalid, or expired.
Authenticated principal does not have permission.
The requested resource was not found.
GET /v1/assets/{asset_id} HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Accept: */*
{
"asset_id": "123e4567-e89b-12d3-a456-426614174000",
"organization_id": "org_123abc",
"created_by": "user_789def",
"name": "product_promo.mp4",
"category": "video",
"content_type": "video/mp4",
"size_bytes": 10485760,
"etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"asset_url": "https://s3.amazonaws.com/ojin-assets/asset.mp4?X-Amz-Algorithm=..."
}API key for authenticated access to the Ojin REST API.
The unique identifier (UUID) of the Asset.
Operation successful, no content to return.
No content
Authentication token is missing, invalid, or expired.
Authenticated principal does not have permission.
The requested resource was not found.
DELETE /v1/assets/{asset_id} HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Accept: */*
No content
API key for authenticated access to the Ojin REST API.
Request payload to trigger idle video generation.
The ID of the source image asset to use for generating the idle video.
123e4567-e89b-12d3-a456-426614174000The reference motion template to use (e.g., 'v1', 'v2', 'v3').
v1Possible values: Model variant the generated idle video is intended for (e.g. 'ojin/oris-portrait'). Used only to label the background job so the Recent Generations list names the right model. Optional; callers without a model context omit it and the job uses a default label.
ojin/oris-portraitModel config to assign the generated video to as its active idle preview once the job completes. When set, core-api writes model_configurations.preview server-side on completion, so the assignment lands even if the browser closed, navigated away, or refreshed mid-generation. Must be a config owned by the caller's organization. Optional; omit to only create the video without assigning it.
123e4567-e89b-12d3-a456-426614174000Job accepted and queued for processing.
Response from triggering idle video generation.
Identifier of the background job created for this generation request.
123e4567-e89b-12d3-a456-426614174000Invalid request payload or parameters.
Authentication token is missing, invalid, or expired.
Authenticated principal does not have permission.
Source asset not found.
POST /v1/assets/generate/ojin/oris-1.0-idle-video-generator HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 188
{
"source_asset_id": "123e4567-e89b-12d3-a456-426614174000",
"reference_template": "v1",
"model_variant_id": "ojin/oris-portrait",
"target_model_config_id": "123e4567-e89b-12d3-a456-426614174000"
}{
"job_id": "123e4567-e89b-12d3-a456-426614174000"
}Agents
API key for authenticated access to the Ojin REST API.
Number of items to return per page.
20Number of items to skip for pagination.
0Paginated list of Agents.
Authentication token is missing, invalid, or expired.
GET /v1/agents HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Accept: */*
{
"data": [
{
"agent_id": "123e4567-e89b-12d3-a456-426614174000",
"organization_id": "123e4567-e89b-12d3-a456-426614174000",
"created_by": "text",
"title": "text",
"description": "text",
"mode": "ojin",
"status": "published",
"face_id": "123e4567-e89b-12d3-a456-426614174000",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}
],
"pagination": {
"limit": 1,
"offset": 1,
"total_items": 1
}
}API key for authenticated access to the Ojin REST API.
Payload for creating a new Agent, optionally from a preset.
The operating mode of an agent. Ojin mode uses the built-in pipeline; third_party mode delegates to an external STS provider.
Optional preset to seed the new agent from.
Agent created.
Full Agent detail including configuration, STS credentials flags, LLM tool wiring.
Creator's user ID (from external IdP), or api_key:<id> when the resource was created via an API key.
The operating mode of an agent. Ojin mode uses the built-in pipeline; third_party mode delegates to an external STS provider.
The publication status of an agent. Published agents are available for connections; unpublished agents are not.
Spoken language code for the agent. Drives Deepgram STT language, ElevenLabs voice filtering in the dashboard, and an LLM system-prompt suffix that pins the response language.
True when an encrypted STS API key is persisted for this agent. The raw key is never returned.
A direct URL or a bare asset-ID UUID. The public agent endpoint resolves UUIDs to signed S3 URLs before returning them to clients.
Maximum concurrent sessions. -1 means unbounded (no limit); valid positive values are 1–100.
True when an auth secret is persisted.
Plaintext auth secret. Only returned to the creator immediately after agent creation (one-shot). Subsequent reads return null; use auth_secret_set to detect whether a secret is configured.
Invalid request payload or parameters.
Authentication token is missing, invalid, or expired.
POST /v1/agents HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 81
{
"title": "text",
"mode": "ojin",
"preset_id": "123e4567-e89b-12d3-a456-426614174000"
}{
"agent_id": "123e4567-e89b-12d3-a456-426614174000",
"organization_id": "123e4567-e89b-12d3-a456-426614174000",
"created_by": "text",
"title": "text",
"description": "text",
"mode": "ojin",
"status": "published",
"face_id": "123e4567-e89b-12d3-a456-426614174000",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"language": "en",
"system_prompt": "text",
"tts_provider": "text",
"voice_id": "text",
"behaviour": {
"greeting": "text",
"greeting_reference": "text",
"greeting_mode": "verbatim",
"nudge_message": "text",
"nudge_reference": "text",
"nudge_mode": "verbatim",
"farewell_message": "text",
"farewell_reference": "text",
"farewell_mode": "verbatim",
"max_conversation_duration_seconds": 1,
"inactivity_nudge_seconds": 1,
"allow_interruption": true
},
"advanced": {
"max_video_source_dimension": 1,
"llm_max_tokens": 1
},
"sts_provider": "text",
"sts_config_id": "text",
"sts_api_key_set": true,
"provider_config": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"preview_url": "text",
"starts_conversation": true,
"session_limit_seconds": 1,
"max_concurrency": -1,
"auth_enabled": true,
"auth_secret_set": true,
"auth_secret": "text",
"allowed_hostnames": [
"text"
],
"tools": [
{
"tool_id": "123e4567-e89b-12d3-a456-426614174000",
"enabled": true,
"type": "function",
"function": {
"name": "text",
"description": "text",
"parameters": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
},
"delivery": {
"mode": "client"
}
}
]
}API key for authenticated access to the Ojin REST API.
The unique identifier (UUID) of the Agent.
Agent detail.
Full Agent detail including configuration, STS credentials flags, LLM tool wiring.
Creator's user ID (from external IdP), or api_key:<id> when the resource was created via an API key.
The operating mode of an agent. Ojin mode uses the built-in pipeline; third_party mode delegates to an external STS provider.
The publication status of an agent. Published agents are available for connections; unpublished agents are not.
Spoken language code for the agent. Drives Deepgram STT language, ElevenLabs voice filtering in the dashboard, and an LLM system-prompt suffix that pins the response language.
True when an encrypted STS API key is persisted for this agent. The raw key is never returned.
A direct URL or a bare asset-ID UUID. The public agent endpoint resolves UUIDs to signed S3 URLs before returning them to clients.
Maximum concurrent sessions. -1 means unbounded (no limit); valid positive values are 1–100.
True when an auth secret is persisted.
Plaintext auth secret. Only returned to the creator immediately after agent creation (one-shot). Subsequent reads return null; use auth_secret_set to detect whether a secret is configured.
Authentication token is missing, invalid, or expired.
The requested resource was not found.
GET /v1/agents/{agent_id} HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Accept: */*
{
"agent_id": "123e4567-e89b-12d3-a456-426614174000",
"organization_id": "123e4567-e89b-12d3-a456-426614174000",
"created_by": "text",
"title": "text",
"description": "text",
"mode": "ojin",
"status": "published",
"face_id": "123e4567-e89b-12d3-a456-426614174000",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"language": "en",
"system_prompt": "text",
"tts_provider": "text",
"voice_id": "text",
"behaviour": {
"greeting": "text",
"greeting_reference": "text",
"greeting_mode": "verbatim",
"nudge_message": "text",
"nudge_reference": "text",
"nudge_mode": "verbatim",
"farewell_message": "text",
"farewell_reference": "text",
"farewell_mode": "verbatim",
"max_conversation_duration_seconds": 1,
"inactivity_nudge_seconds": 1,
"allow_interruption": true
},
"advanced": {
"max_video_source_dimension": 1,
"llm_max_tokens": 1
},
"sts_provider": "text",
"sts_config_id": "text",
"sts_api_key_set": true,
"provider_config": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"preview_url": "text",
"starts_conversation": true,
"session_limit_seconds": 1,
"max_concurrency": -1,
"auth_enabled": true,
"auth_secret_set": true,
"auth_secret": "text",
"allowed_hostnames": [
"text"
],
"tools": [
{
"tool_id": "123e4567-e89b-12d3-a456-426614174000",
"enabled": true,
"type": "function",
"function": {
"name": "text",
"description": "text",
"parameters": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
},
"delivery": {
"mode": "client"
}
}
]
}API key for authenticated access to the Ojin REST API.
The unique identifier (UUID) of the Agent.
Payload for updating an Agent (partial update — all fields optional).
The operating mode of an agent. Ojin mode uses the built-in pipeline; third_party mode delegates to an external STS provider.
Spoken language code for the agent. Drives Deepgram STT language, ElevenLabs voice filtering in the dashboard, and an LLM system-prompt suffix that pins the response language.
A direct URL or a bare asset-ID UUID. The public agent endpoint resolves UUIDs to signed S3 URLs before returning them to clients.
Maximum concurrent sessions. -1 means unbounded (no limit); valid positive values are 1–100.
Agent updated.
Full Agent detail including configuration, STS credentials flags, LLM tool wiring.
Creator's user ID (from external IdP), or api_key:<id> when the resource was created via an API key.
The operating mode of an agent. Ojin mode uses the built-in pipeline; third_party mode delegates to an external STS provider.
The publication status of an agent. Published agents are available for connections; unpublished agents are not.
Spoken language code for the agent. Drives Deepgram STT language, ElevenLabs voice filtering in the dashboard, and an LLM system-prompt suffix that pins the response language.
True when an encrypted STS API key is persisted for this agent. The raw key is never returned.
A direct URL or a bare asset-ID UUID. The public agent endpoint resolves UUIDs to signed S3 URLs before returning them to clients.
Maximum concurrent sessions. -1 means unbounded (no limit); valid positive values are 1–100.
True when an auth secret is persisted.
Plaintext auth secret. Only returned to the creator immediately after agent creation (one-shot). Subsequent reads return null; use auth_secret_set to detect whether a secret is configured.
Invalid request payload or parameters.
Authentication token is missing, invalid, or expired.
The requested resource was not found.
PATCH /v1/agents/{agent_id} HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 1071
{
"title": "text",
"description": "text",
"mode": "ojin",
"face_id": "123e4567-e89b-12d3-a456-426614174000",
"language": "en",
"system_prompt": "text",
"tts_provider": "elevenlabs",
"voice_id": "text",
"behaviour": {
"greeting": "text",
"greeting_reference": "text",
"greeting_mode": "verbatim",
"nudge_message": "text",
"nudge_reference": "text",
"nudge_mode": "verbatim",
"farewell_message": "text",
"farewell_reference": "text",
"farewell_mode": "verbatim",
"max_conversation_duration_seconds": 1,
"inactivity_nudge_seconds": 1,
"allow_interruption": true
},
"advanced": {
"max_video_source_dimension": 1,
"llm_max_tokens": 1
},
"sts_provider": "text",
"sts_api_key": "text",
"sts_config_id": "text",
"provider_config": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"preview_url": "text",
"session_limit_seconds": 1,
"max_concurrency": -1,
"starts_conversation": true,
"auth_enabled": true,
"allowed_hostnames": [
"text"
],
"tools": [
{
"tool_id": "123e4567-e89b-12d3-a456-426614174000",
"enabled": true,
"type": "function",
"function": {
"name": "text",
"description": "text",
"parameters": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
},
"delivery": {
"mode": "client"
}
}
]
}{
"agent_id": "123e4567-e89b-12d3-a456-426614174000",
"organization_id": "123e4567-e89b-12d3-a456-426614174000",
"created_by": "text",
"title": "text",
"description": "text",
"mode": "ojin",
"status": "published",
"face_id": "123e4567-e89b-12d3-a456-426614174000",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"language": "en",
"system_prompt": "text",
"tts_provider": "text",
"voice_id": "text",
"behaviour": {
"greeting": "text",
"greeting_reference": "text",
"greeting_mode": "verbatim",
"nudge_message": "text",
"nudge_reference": "text",
"nudge_mode": "verbatim",
"farewell_message": "text",
"farewell_reference": "text",
"farewell_mode": "verbatim",
"max_conversation_duration_seconds": 1,
"inactivity_nudge_seconds": 1,
"allow_interruption": true
},
"advanced": {
"max_video_source_dimension": 1,
"llm_max_tokens": 1
},
"sts_provider": "text",
"sts_config_id": "text",
"sts_api_key_set": true,
"provider_config": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"preview_url": "text",
"starts_conversation": true,
"session_limit_seconds": 1,
"max_concurrency": -1,
"auth_enabled": true,
"auth_secret_set": true,
"auth_secret": "text",
"allowed_hostnames": [
"text"
],
"tools": [
{
"tool_id": "123e4567-e89b-12d3-a456-426614174000",
"enabled": true,
"type": "function",
"function": {
"name": "text",
"description": "text",
"parameters": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
},
"delivery": {
"mode": "client"
}
}
]
}API key for authenticated access to the Ojin REST API.
The unique identifier (UUID) of the Agent.
Operation successful, no content to return.
No content
Authentication token is missing, invalid, or expired.
The requested resource was not found.
Conflict with the current state of the resource.
DELETE /v1/agents/{agent_id} HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Accept: */*
No content
API key for authenticated access to the Ojin REST API.
The unique identifier (UUID) of the Agent.
Payload for toggling Agent publication status.
The publication status of an agent. Published agents are available for connections; unpublished agents are not.
Agent status updated.
Full Agent detail including configuration, STS credentials flags, LLM tool wiring.
Creator's user ID (from external IdP), or api_key:<id> when the resource was created via an API key.
The operating mode of an agent. Ojin mode uses the built-in pipeline; third_party mode delegates to an external STS provider.
The publication status of an agent. Published agents are available for connections; unpublished agents are not.
Spoken language code for the agent. Drives Deepgram STT language, ElevenLabs voice filtering in the dashboard, and an LLM system-prompt suffix that pins the response language.
True when an encrypted STS API key is persisted for this agent. The raw key is never returned.
A direct URL or a bare asset-ID UUID. The public agent endpoint resolves UUIDs to signed S3 URLs before returning them to clients.
Maximum concurrent sessions. -1 means unbounded (no limit); valid positive values are 1–100.
True when an auth secret is persisted.
Plaintext auth secret. Only returned to the creator immediately after agent creation (one-shot). Subsequent reads return null; use auth_secret_set to detect whether a secret is configured.
Invalid request payload or parameters.
Authentication token is missing, invalid, or expired.
The requested resource was not found.
PATCH /v1/agents/{agent_id}/status HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 22
{
"status": "published"
}{
"agent_id": "123e4567-e89b-12d3-a456-426614174000",
"organization_id": "123e4567-e89b-12d3-a456-426614174000",
"created_by": "text",
"title": "text",
"description": "text",
"mode": "ojin",
"status": "published",
"face_id": "123e4567-e89b-12d3-a456-426614174000",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"language": "en",
"system_prompt": "text",
"tts_provider": "text",
"voice_id": "text",
"behaviour": {
"greeting": "text",
"greeting_reference": "text",
"greeting_mode": "verbatim",
"nudge_message": "text",
"nudge_reference": "text",
"nudge_mode": "verbatim",
"farewell_message": "text",
"farewell_reference": "text",
"farewell_mode": "verbatim",
"max_conversation_duration_seconds": 1,
"inactivity_nudge_seconds": 1,
"allow_interruption": true
},
"advanced": {
"max_video_source_dimension": 1,
"llm_max_tokens": 1
},
"sts_provider": "text",
"sts_config_id": "text",
"sts_api_key_set": true,
"provider_config": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"preview_url": "text",
"starts_conversation": true,
"session_limit_seconds": 1,
"max_concurrency": -1,
"auth_enabled": true,
"auth_secret_set": true,
"auth_secret": "text",
"allowed_hostnames": [
"text"
],
"tools": [
{
"tool_id": "123e4567-e89b-12d3-a456-426614174000",
"enabled": true,
"type": "function",
"function": {
"name": "text",
"description": "text",
"parameters": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
},
"delivery": {
"mode": "client"
}
}
]
}API key for authenticated access to the Ojin REST API.
The unique identifier (UUID) of the Agent.
Number of items to return per page.
20Number of items to skip for pagination.
0ISO-8601 date/datetime lower bound on started_at.
ISO-8601 date/datetime upper bound on started_at.
Paginated call history.
Authentication token is missing, invalid, or expired.
The requested resource was not found.
GET /v1/agents/{agent_id}/calls HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Accept: */*
{
"data": [
{
"call_id": "123e4567-e89b-12d3-a456-426614174000",
"agent_id": "123e4567-e89b-12d3-a456-426614174000",
"organization_id": "123e4567-e89b-12d3-a456-426614174000",
"session_id": "123e4567-e89b-12d3-a456-426614174000",
"applied_session_limit_seconds": 1,
"client_user_ref": "text",
"started_at": "2026-01-01T00:00:00.000Z",
"ended_at": "2026-01-01T00:00:00.000Z",
"status": "text",
"termination_reason": "text",
"failure_reason": "text",
"participant_count": 1,
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"pagination": {
"limit": 1,
"offset": 1,
"total_items": 1
}
}API key for authenticated access to the Ojin REST API.
Provider catalogue.
STS provider descriptor (returned by GET /agents/providers).
elevenlabsElevenLabsProvider-specific fields that must be persisted in provider_config.
Provider-specific fields that may be persisted in provider_config.
Provider-specific fields that must be supplied per-session.
availableAuthentication token is missing, invalid, or expired.
GET /v1/agents/providers HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Accept: */*
[
{
"slug": "elevenlabs",
"label": "ElevenLabs",
"required_persisted": [
"text"
],
"optional_persisted": [
"text"
],
"session_fields": [
"text"
],
"status": "available"
}
]API key for authenticated access to the Ojin REST API.
The unique identifier (UUID) of the Agent.
Verification result (may be valid or invalid).
Result of a live credential verification check against a third-party STS provider.
Human-readable reason when valid is false.
Invalid request payload or parameters.
Authentication token is missing, invalid, or expired.
The requested resource was not found.
Upstream service (e.g. WebRTC room provider, agent orchestrator) returned an error or was unreachable.
POST /v1/agents/{agent_id}/verify-provider HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Accept: */*
{
"valid": true,
"provider": "text",
"error": "text"
}Public Widget Endpoints
The unique identifier (UUID) of the Model Configuration.
Model Configuration details (without internal fields).
Public variant of ModelConfig for widget embedding.
Strips internal fields (organization_id, created_by, model_id) — the widget
chains through model_variant_id and calls GET /public/model-variants/{model_variant_id}
when it needs the parent Model reference.
Server-generated unique ID.
ID of the ModelVariant being configured.
Title for the configuration.
Timestamp of creation.
Timestamp of last update.
The requested resource was not found.
GET /v1/public/model-configs/{model_config_id} HTTP/1.1
Host: api.ojin.ai
Accept: */*
{
"model_config_id": "123e4567-e89b-12d3-a456-426614174000",
"model_variant_id": "text",
"title": "text",
"model_configurations": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}The unique identifier (UUID) of the Asset.
Successfully retrieved Asset metadata with download URL (without internal fields).
Public variant of Asset for widget embedding. Strips internal fields (organization_id, created_by) and includes a pre-signed download URL.
Unique identifier for the Asset.
123e4567-e89b-12d3-a456-426614174000The original file name of the Asset.
product_promo.mp4Primary category of the Asset (e.g., 'video', 'image', 'weight').
videoThe MIME type of the asset.
video/mp4The size of the asset in bytes.
10485760The ETag of the S3 object.
"d41d8cd98f00b204e9800998ecf8427e"Timestamp of creation.
Timestamp of last update.
A temporary, pre-signed URL to download the asset's content. This URL will expire.
https://s3.amazonaws.com/ojin-assets/asset.mp4?X-Amz-Algorithm=...The requested resource was not found.
GET /v1/public/assets/{asset_id} HTTP/1.1
Host: api.ojin.ai
Accept: */*
{
"asset_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "product_promo.mp4",
"category": "video",
"content_type": "video/mp4",
"size_bytes": 10485760,
"etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"asset_url": "https://s3.amazonaws.com/ojin-assets/asset.mp4?X-Amz-Algorithm=..."
}Schemas
Last updated
Was this helpful?