What is ?

Wiro is an AI model marketplace and API platform that lets you run AI models through a single, unified API. Instead of managing infrastructure for each model provider, you make one API call to Wiro and we handle the rest.

• Unified API — one interface for all models (image generation, LLMs, audio, video, and more)
• Pay-per-use pricing — only pay for what you consume, no upfront commitments
• Real-time WebSocket updates — stream task progress and outputs live
• 9 SDK languages — curl, Python, Node.js, PHP, C#, Swift, Dart, Kotlin, Go

Base URL

All API requests are made to:

https://api.wiro.ai/v1

WebSocket connections use:

wss://socket.wiro.ai/v1

Quick Start

1. Sign up Create an account at wiro.ai
2. Create a project Go to the Dashboard to get your API key
3. Pick a model Browse the marketplace and choose a model
4. Make your first API call See Code Examples for full end-to-end samples

Response Format

Every API response returns JSON with a consistent structure:

{
  "result": true,
  "errors": [],
  "data": { ... }
}

When result is false, the errors array contains human-readable messages describing what went wrong.

Rate Limits & Error Handling

API requests are rate-limited per project. If you exceed the limit, the API returns a 429 Too Many Requests status. Implement exponential backoff in your retry logic.

Common HTTP status codes:

• 200 — Success
• 400 — Bad request (check parameters)
• 401 — Unauthorized (invalid or missing API key)
• 403 — Forbidden (signature mismatch or insufficient permissions)
• 429 — Rate limit exceeded
• 500 — Internal server error

Overview

Wiro supports two authentication methods. You choose the method when creating a project — it cannot be changed afterward.

Comparison

How to Choose

• Building a client-side or mobile app? Use Signature-Based.
• Running a server-side backend with controlled access? API Key Only is simpler.
• Unsure? Default to Signature-Based — it's always the safer option.

What is a Project?

A project is a container that holds your API keys, billing settings, and usage tracking. Each project gets its own API key and secret, letting you separate environments (development, staging, production) or different applications.

• Each project has its own API key and (optionally) API secret
• Usage and billing are tracked per project
• You can create multiple projects under one account

Creating a Project

1. Go to the Dashboard Navigate to wiro.ai/panel
2. Open Projects Go to Projects and click New Project
3. Name your project Enter a descriptive project name
4. Select authentication method Signature-Based — generates API key + secret  |  API Key Only — generates only an API key
5. Create Click Create and copy your credentials immediately

API Credentials

After creating a project, your API key (and secret, if signature-based) are displayed once. Copy and store them securely — you won't be able to view the secret again.

Managing Projects

From the Projects page in your Dashboard, you can:

• Update name — rename your project at any time
• Regenerate keys — invalidates existing keys and generates new ones
• View usage — see API calls, costs, and task history
• Delete project — permanently removes the project and revokes all keys

Regenerating keys immediately invalidates the old ones. Update your application with the new credentials before the old ones stop working.

POST /Tool/List

Returns a paginated list of available models. Filter by categories, search by name, and sort results.

Response

{
  "result": true,
  "errors": [],
  "total": 2,
  "tool": [
    {
      "id": "1611",
      "title": "Virtual Try-on",
      "slugowner": "wiro",
      "slugproject": "Virtual Try-On",
      "cleanslugowner": "wiro",
      "cleanslugproject": "virtual-try-on",
      "description": "Integrate the Wiro Virtual Try-On API...",
      "image": "https://cdn.wiro.ai/uploads/models/...",
      "computingtime": "10 seconds",
      "categories": ["tool", "image-to-image", "image-editing"],
      "tags": [],
      "marketplace": 1,
      "onlymembers": "1",
      "averagepoint": "5.00",
      "commentcount": "1",
      "dynamicprice": "[{\"inputs\":{},\"price\":0.09,\"priceMethod\":\"cpr\"}]",
      "taskstat": {
        "runcount": 672,
        "successcount": "254",
        "errorcount": "198",
        "lastruntime": "1774007585"
      }
    }
  ]
}

POST /Tool/Detail

Returns full details for a specific model, including its input parameters, pricing, categories, and configuration.

Response

{
  "result": true,
  "errors": [],
  "tool": [{
    "id": "1611",
    "title": "Virtual Try-on",
    "slugowner": "wiro",
    "slugproject": "Virtual Try-On",
    "cleanslugowner": "wiro",
    "cleanslugproject": "virtual-try-on",
    "description": "Integrate the Wiro Virtual Try-On API...",
    "image": "https://cdn.wiro.ai/uploads/models/...",
    "computingtime": "10 seconds",
    "readme": "<p>The Wiro Virtual Try-On AI model...</p>",
    "categories": ["tool", "image-to-image", "image-editing"],
    "parameters": null,
    "inspire": [
      {
        "inputImageHuman": "https://cdn.wiro.ai/uploads/sampleinputs/...",
        "inputImageClothes": ["https://cdn.wiro.ai/..."]
      }
    ],
    "samples": ["https://cdn.wiro.ai/uploads/models/..."],
    "tags": [],
    "marketplace": 1,
    "onlymembers": "1",
    "dynamicprice": "[{\"inputs\":{},\"price\":0.09,\"priceMethod\":\"cpr\"}]",
    "averagepoint": "5.00",
    "commentcount": "1",
    "ratedusercount": "3",
    "taskstat": {
      "runcount": 672,
      "successcount": "254",
      "errorcount": "198",
      "lastruntime": "1774007585"
    },
    "seotitle": "AI Virtual Try-On: Integrate Realistic Apparel Fitting",
    "seodescription": "Integrate the Wiro Virtual Try-On API..."
  }]
}

Model Browser

Browse available models interactively. Click on a model to see its details on the model page.

POST /Run/{owner-slug}/{model-slug}

Starts an AI model run. The endpoint accepts model-specific parameters and returns a task ID you can use to track progress via polling, WebSocket, or webhook by providing a callbackUrl parameter — Wiro will POST the result to your URL when the task completes.

Content Types

JSON (application/json)

Use JSON for text-based inputs — prompts, configuration, numeric parameters. This is the default and most common format.

Multipart (multipart/form-data)

Use multipart when the model requires file inputs (images, audio, documents). Include files as form fields and other parameters as text fields.

Request Parameters

Parameters vary by model. Use the /Tool/Detail endpoint to discover which parameters a model accepts. The following optional parameters apply to all runs:

Response

A successful run returns a task ID and a WebSocket access token:

{
  "result": true,
  "errors": [],
  "taskid": "2221",
  "socketaccesstoken": "eDcCm5yyUfIvMFspTwww49OUfgXkQt"
}

Full Flow

The typical workflow after calling the Run endpoint:

1. Run — call POST /Run/{owner-slug}/{model-slug} and receive a task ID
2. Track — connect via WebSocket or poll POST /Task/Detail
3. Receive — get outputs as the model produces them (streaming or final)
4. Complete — task reaches end status with full results

For real-time streaming, use the WebSocket connection with the socketaccesstoken returned in the run response. For simpler integrations, poll the Task Detail endpoint every few seconds.

Discovering Parameters

Every model has its own set of input parameters. Use the /Tool/Detail endpoint to retrieve a model's parameter definitions. The response includes a parameters array where each item describes a parameter group with its items:

{
  "parameters": [
    {
      "title": "Input",
      "items": [
        {
          "id": "prompt",
          "type": "textarea",
          "label": "Prompt",
          "required": true,
          "placeholder": "Describe what you want...",
          "note": "Text description of the desired output"
        },
        {
          "id": "inputImage",
          "type": "fileinput",
          "label": "Input Image",
          "required": true,
          "note": "Upload an image or provide a URL"
        }
      ]
    }
  ]
}

Parameter Types

JSON vs Multipart

The content type of your request depends on whether the model requires file inputs:

File Upload Patterns

Single File (fileinput)

For parameters like inputImage, send either a file or a URL. When using multipart, always include both the {id} and {id}Url fields — leave one empty:

# Option 1: Upload file — send file in {id}, empty {id}Url
curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "inputImage=@/path/to/photo.jpg" \
  -F "inputImageUrl="

# Option 2: Send URL via {id}Url — send empty {id}, URL in {id}Url
curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "inputImage=" \
  -F "inputImageUrl=https://example.com/photo.jpg"

# Option 3: Pass URL directly in {id} (no {id}Url needed)
curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "inputImage=https://example.com/photo.jpg"

Multiple Files (multifileinput)

For parameters like inputDocumentMultiple, upload up to N files, send comma-separated URLs, or mix both:

# Option 1: Upload multiple files — add empty {id}Url
curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "inputDocumentMultipleUrl="

# Option 2: Send URLs (comma-separated in {id}Url) — add empty {id}
curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "inputDocumentMultiple=" \
  -F "inputDocumentMultipleUrl=https://example.com/doc1.pdf,https://example.com/doc2.pdf"

# Option 3: Mixed — files in {id}, URLs in {id}Url
curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "inputDocumentMultipleUrl=https://example.com/doc2.pdf,https://example.com/doc3.pdf"

Combined (combinefileinput)

For parameters like inputImageClothes, files and URLs go directly in the same {id} field — no {id}Url suffix:

# Option 1: Upload files — each as a separate {id} entry
curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "[email protected]"

# Option 2: Send URLs — each directly in {id}
curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "inputImageClothes=https://example.com/shirt.jpg" \
  -F "inputImageClothes=https://example.com/pants.jpg"

# Option 3: Mixed — files and URLs in the same {id} field
curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "inputImageClothes=https://example.com/pants.jpg"

Common Model Patterns

Image Generation (text-to-image)

Models like Stable Diffusion, Flux — JSON body, no file uploads:

{
  "prompt": "A futuristic city at sunset",
  "negative_prompt": "blurry, low quality",
  "width": 1024,
  "height": 1024
}

Image-to-Image (upscaler, style transfer)

Models that take an input image — multipart with file upload:

curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "scale=4"

Virtual Try-On

Multiple image inputs — multipart with multiple files:

curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "[email protected]"

LLM / Document Processing

Text prompt with optional document uploads:

curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "prompt=Extract the candidate name and skills" \
  -F "outputType=json" \
  -F "language=en"

Realtime Voice Conversation

Realtime voice models accept configuration parameters (voice, system instructions, audio format, etc.) as JSON. Parameters vary per model — use /Tool/Detail to discover them. The actual audio interaction happens over Realtime Voice WebSocket after the task starts:

// Example: OpenAI GPT Realtime
{
  "voice": "marin",
  "system_instructions": "You are a helpful voice assistant.",
  "input_audio_format": "audio/pcm",
  "output_audio_format": "audio/pcm",
  "input_audio_rate": "24000",
  "output_audio_rate": "24000"
}

Webhook Callback

All models support an optional callbackUrl parameter. When provided, Wiro will POST the task result to your URL when the task completes — no polling required:

{
  "prompt": "A sunset over mountains",
  "callbackUrl": "https://your-server.com/webhook/wiro"
}

Task Lifecycle

Every model run creates a task that progresses through a defined set of stages:

Task Statuses

Realtime Conversation Only

The following statuses are exclusive to realtime conversation models (e.g. voice AI). They are not emitted for standard model runs.

Determining Success or Failure

Both successful and failed tasks reach task_postprocess_end. The status alone does not tell you whether the task succeeded. Wait for task_postprocess_end and then check pexit or outputs (or both) to determine the actual result:

• pexit — the process exit code. "0" means success, any other value means the model encountered an error. This is the most reliable indicator.
• outputs — the output array. For non-LLM models, this contains CDN file URLs. For LLM models, this contains a structured entry with contenttype: "raw" holding the response text, thinking, and answer arrays. If it's empty or missing, the task likely failed.

// Success (image/audio model): pexit "0", file outputs with CDN URLs
{
  "pexit": "0",
  "outputs": [{
    "name": "0.png",
    "contenttype": "image/png",
    "size": "202472",
    "url": "https://cdn1.wiro.ai/.../0.png"
  }]
}

// Success (LLM model): pexit "0", structured raw content in outputs
{
  "pexit": "0",
  "debugoutput": "Hello! How can I help you today?",
  "outputs": [{
    "contenttype": "raw",
    "content": {
      "prompt": "Say hello",
      "raw": "Hello! How can I help you today?",
      "thinking": [],
      "answer": ["Hello! How can I help you today?"]
    }
  }]
}

// Failure: pexit non-zero
{
  "pexit": "1",
  "outputs": []
}

Billing & Cost

The totalcost field in the Task Detail response shows the actual cost charged for the run. Only successful tasks are billed — if pexit is non-zero (failure), the task is not charged and totalcost will be "0".

Successful run — billed:

{
  "status": "task_postprocess_end",
  "pexit": "0",
  "totalcost": "0.003510000000",
  "elapsedseconds": "6.0000"
}

Failed run — not billed:

{
  "status": "task_postprocess_end",
  "pexit": "1",
  "totalcost": "0",
  "elapsedseconds": "4.0000"
}

Use the totalcost field to track spending per task. For more details on how costs are calculated, see Pricing.

LLM Models

For LLM (Large Language Model) requests, the model's response is available in two places: as merged plain text in debugoutput, and as a structured entry in the outputs array with contenttype: "raw". The structured output includes separate thinking and answer arrays alongside the original prompt and full raw text.

For real-time streaming of LLM responses, use WebSocket instead of polling. Each task_output event delivers a chunk of the response as it's generated, giving your users an instant, token-by-token experience.

POST /Task/Detail

Retrieves the current status and output of a task. You can query by either tasktoken or taskid.

Response

{
  "result": true,
  "errors": [],
  "total": "1",
  "tasklist": [{
    "id": "534574",
    "socketaccesstoken": "eDcCm5yyUfIvMFspTwww49OUfgXkQt",
    "parameters": { "prompt": "Hello, world!" },
    "status": "task_postprocess_end",
    "pexit": "0",
    "debugoutput": "",
    "starttime": "1734513809",
    "endtime": "1734513813",
    "elapsedseconds": "6.0000",
    "totalcost": "0.003510000000",
    "modeldescription": "FLUX.2 [dev] is a 32 billion parameter rectified flow transformer...",
    "modelslugowner": "wiro",
    "modelslugproject": "flux-2-dev",
    "outputs": [{
      "name": "0.png",
      "contenttype": "image/png",
      "size": "202472",
      "url": "https://cdn1.wiro.ai/.../0.png"
    }]
  }]
}

POST /Task/Cancel

Cancels a task that is still in the queue stage. Tasks that have already been assigned to a worker cannot be cancelled — use Kill instead.

POST /Task/Kill

Terminates a task that is currently running (any status after assign). The worker will stop processing and the task will move to cancel status.

POST /Task/InputOutputDelete

Deletes all output files and input files associated with a completed task. Removes files from S3 storage, local filesystem, and the database. Also invalidates CloudFront CDN cache so deleted files stop being served immediately.

The task must be in a terminal state (task_postprocess_end or task_cancel). Only the task owner can delete files. Shared sample input files (/sampleinputs/) are automatically excluded from deletion.

Response

{
  "result": true,
  "errors": []
}

After deletion:

• Output files are removed from S3 and CDN cache
• Input files uploaded by the user are removed from S3 and local storage
• The task's outputfolderid is set to "0" (Task Detail will return empty outputs)
• Task record and parameters are preserved — only the files are deleted
• Calling the endpoint again on the same task returns result: true immediately (idempotent)

Errors

Overview

LLM (Large Language Model) requests on Wiro work differently from standard model runs:

• Responses are available as structured content in the outputs array (contenttype: "raw") and as merged text in debugoutput
• Streaming task_output messages contain structured thinking and answer arrays — not plain strings
• Multi-turn conversations are supported via session_id and user_id parameters
• pexit is the primary success indicator

Available LLM models include:

• openai/gpt-5-2 — GPT-5-2
• openai/gpt-oss-20b — GPT OSS 20B
• qwen/qwen3-5-27b — Qwen 3.5 27B

Session & Chat History

Wiro maintains conversation history per session. By sending a session_id, the model remembers previous messages and can build on the context of the conversation. Combined with user_id, this enables fully stateful chat experiences:

// First message — start a new session
{
  "prompt": "What is quantum computing?",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

// Follow-up — reuse the same session_id
{
  "prompt": "Can you explain qubits in more detail?",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

Thinking & Answer Phases

Many LLM models separate their output into two phases:

• Thinking — the model's internal reasoning process (chain-of-thought)
• Answer — the final response to the user

When streaming via WebSocket, task_output messages for LLM models contain a structured object (not a plain string):

// LLM task_output message format
{
  "type": "task_output",
  "id": "534574",
  "tasktoken": "eDcCm5yy...",
  "message": {
    "type": "progressGenerate",
    "task": "Generate",
    "speed": "12.4",
    "speedType": "words/s",
    "raw": "<think>Let me analyze...</think>Quantum computing uses qubits...",
    "thinking": ["Let me analyze this step by step...", "The key factors are..."],
    "answer": ["Quantum computing uses qubits that can exist in superposition..."],
    "isThinking": false,
    "elapsedTime": "3s"
  }
}

Both thinking and answer are arrays of strings. A model may alternate between thinking and answering multiple times during a single response. The arrays are indexed in pairs — thinking[0] corresponds to answer[0], thinking[1] to answer[1], and so on:

// Multi-turn thinking/answer cycle
{
  "thinking": [
    "Let me break this into parts...",        // thinking[0]
    "Now let me verify my reasoning..."       // thinking[1]
  ],
  "answer": [
    "Quantum computing uses qubits...",       // answer[0] — response after thinking[0]
    "To summarize: qubits can be 0, 1, or..." // answer[1] — response after thinking[1]
  ]
}

Each task_output event contains the full accumulated arrays up to that point — not just the new chunk. Simply replace your displayed content with the latest arrays. Use isThinking to show a "thinking" indicator in your UI while the model reasons.

Streaming Flow

The complete flow for streaming an LLM response:

1. Run the model with prompt, session_id, and user_id
2. Connect to WebSocket and send task_info
3. Receive task_output messages — each contains the growing thinking and answer arrays
4. Display the latest answer array content to the user (optionally show thinking in a collapsible section)
5. Complete — on task_postprocess_end, check pexit for success

Polling Alternative

If you don't need real-time streaming, you can poll POST /Task/Detail instead. The response includes both debugoutput (merged plain text) and a structured entry in outputs with separate thinking and answer arrays:

{
  "result": true,
  "tasklist": [{
    "status": "task_postprocess_end",
    "pexit": "0",
    "debugoutput": "Quantum computing uses qubits that can exist in superposition...",
    "outputs": [{
      "contenttype": "raw",
      "content": {
        "prompt": "What is quantum computing?",
        "raw": "Quantum computing uses qubits that can exist in superposition...",
        "thinking": [],
        "answer": ["Quantum computing uses qubits that can exist in superposition..."]
      }
    }]
  }]
}

Connection URL

wss://socket.wiro.ai/v1

Connect to this URL after calling the Run endpoint. Use the socketaccesstoken from the run response to register your session.

Connection Flow

1. Connect — open a WebSocket connection to wss://socket.wiro.ai/v1
2. Register — send a task_info message with your tasktoken
3. Receive — listen for messages as the task progresses through its lifecycle
4. Close — disconnect after the task_postprocess_end event (this is the final event with results)

Registration message format:

{
  "type": "task_info",
  "tasktoken": "your-socket-access-token"
}

Message Types

Message Format

Every WebSocket message is a JSON object with this base structure:

{
  "type": "task_accept",
  "id": "534574",
  "tasktoken": "eDcCm5yyUfIvMFspTwww49OUfgXkQt",
  "message": null,
  "result": true
}

The type field indicates the status. The message field varies by type — it's null for lifecycle events, a string or object for output events, and an array for the final result.

Lifecycle Events

These events signal task state changes. The message field is null:

// task_accept, task_preprocess_start, task_preprocess_end,
// task_assign, task_start, task_end, task_postprocess_start
{
  "type": "task_assign",
  "id": "534574",
  "tasktoken": "eDcCm5yy...",
  "message": null,
  "result": true
}

Output Events

Standard models — message is a progress object or plain string:

// Progress output (image generation, video, etc.)
{
  "type": "task_output",
  "id": "534574",
  "tasktoken": "eDcCm5yy...",
  "message": {
    "type": "progressGenerate",
    "task": "Generate",
    "percentage": "60",
    "stepCurrent": "6",
    "stepTotal": "10",
    "speed": "1.2",
    "speedType": "it/s",
    "elapsedTime": "5s",
    "remainingTime": "3s"
  },
  "result": true
}

// Simple string output (when no progress format is detected)
{
  "type": "task_output",
  "id": "534574",
  "tasktoken": "eDcCm5yy...",
  "message": "Processing complete.",
  "result": true
}

LLM models — message is a structured object with thinking/answer arrays. See LLM & Chat Streaming for full details:

{
  "type": "task_output",
  "id": "534574",
  "tasktoken": "eDcCm5yy...",
  "message": {
    "type": "progressGenerate",
    "task": "Generate",
    "speed": "12.4",
    "speedType": "words/s",
    "raw": "Quantum computing uses qubits...",
    "thinking": ["Let me analyze this..."],
    "answer": ["Quantum computing uses qubits..."],
    "isThinking": false,
    "elapsedTime": "3s"
  },
  "result": true
}

Error Events

task_error is an interim stderr log, not a final failure. The message is a string or progress object:

{
  "type": "task_error",
  "id": "534574",
  "tasktoken": "eDcCm5yy...",
  "message": "UserWarning: Some weights were not initialized...",
  "result": true
}

Full Output Events

Sent once after the process exits. Contains the complete accumulated log:

// Standard model
{
  "type": "task_output_full",
  "id": "534574",
  "tasktoken": "eDcCm5yy...",
  "message": {
    "raw": "0%|...| 0/10\n10%|█| 1/10\n...\n100%|██████████| 10/10\nDone."
  },
  "result": true
}

// LLM model — includes thinking/answer separation
{
  "type": "task_output_full",
  "id": "534574",
  "tasktoken": "eDcCm5yy...",
  "message": {
    "raw": "<think>Let me analyze...</think>Quantum computing uses qubits...",
    "thinking": ["Let me analyze this step by step..."],
    "answer": ["Quantum computing uses qubits that can exist in superposition..."]
  },
  "result": true
}

// Stderr log (only sent if stderr is non-empty)
{
  "type": "task_error_full",
  "id": "534574",
  "tasktoken": "eDcCm5yy...",
  "message": {
    "raw": "UserWarning: Some weights were not initialized..."
  },
  "result": true
}

Final Result

task_postprocess_end is the event you should listen for. The message contains the outputs array:

// Standard model — file outputs with CDN URLs
{
  "type": "task_postprocess_end",
  "id": "534574",
  "tasktoken": "eDcCm5yy...",
  "message": [{
    "name": "0.png",
    "contenttype": "image/png",
    "size": "202472",
    "url": "https://cdn1.wiro.ai/.../0.png"
  }],
  "result": true
}

// LLM model — structured raw content
{
  "type": "task_postprocess_end",
  "id": "534574",
  "tasktoken": "eDcCm5yy...",
  "message": [{
    "contenttype": "raw",
    "content": {
      "prompt": "Explain quantum computing",
      "raw": "Quantum computing uses qubits...",
      "thinking": [],
      "answer": ["Quantum computing uses qubits..."]
    }
  }],
  "result": true
}

Realtime Events

These events are exclusive to realtime voice models:

// Session is ready — start sending audio
{
  "type": "task_stream_ready",
  "id": "534574",
  "tasktoken": "eDcCm5yy...",
  "result": true
}

// AI finished speaking for this turn
{
  "type": "task_stream_end",
  "id": "534574",
  "tasktoken": "eDcCm5yy...",
  "result": true
}

// Cost update per turn
{
  "type": "task_cost",
  "id": "534574",
  "tasktoken": "eDcCm5yy...",
  "turnCost": 0.002,
  "cumulativeCost": 0.012,
  "usage": { "input_tokens": 150, "output_tokens": 89 },
  "result": true
}

Binary Frames

For realtime voice models, the WebSocket may send binary frames containing raw audio data. Check if the received message is a Blob (browser) or Buffer (Node.js) before parsing as JSON.

Ending a Session

For realtime/streaming models that maintain a persistent session, send a task_session_end message to gracefully terminate:

{
  "type": "task_session_end",
  "tasktoken": "your-socket-access-token"
}

After sending this, wait for the task_postprocess_end event before closing the connection. This is the final event that contains the complete results.

Overview

Realtime voice models enable two-way audio conversations with AI. Unlike standard model runs that process a single input and return a result, realtime sessions maintain a persistent WebSocket connection where you stream microphone audio and receive AI speech in real time.

The flow is:

1. Run the realtime model via POST /Run to get a socketaccesstoken
2. Connect to the WebSocket and send task_info with your token
3. Wait for task_stream_ready — the model is ready to receive audio
4. Stream microphone audio as binary frames
5. Receive AI audio as binary frames and play them
6. End the session with task_session_end

Run Parameters

Each realtime model has its own set of parameters. Use POST /Tool/Detail to discover the exact parameters for a specific model. See Model Parameters for details on parameter types.

Available realtime conversation models include:

• openai/gpt-realtime-mini — GPT Mini Realtime Voice Assistant
• openai/gpt-realtime — GPT Realtime Voice Assistant
• elevenlabs/realtime-conversational-ai — ElevenLabs Conversational AI

Common parameters across realtime models typically include voice selection, system instructions, and audio format settings. Example run for an OpenAI realtime model:

curl -X POST "https://api.wiro.ai/v1/Run/openai/gpt-realtime-mini" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "voice": "marin",
    "system_instructions": "You are a friendly assistant.",
    "input_audio_format": "audio/pcm",
    "output_audio_format": "audio/pcm",
    "input_audio_rate": "24000",
    "output_audio_rate": "24000"
  }'

Connection & Registration

After running the task, connect to the WebSocket and register with task_info:

var ws = new WebSocket("wss://socket.wiro.ai/v1");

ws.onopen = function() {
  ws.send(JSON.stringify({
    type: "task_info",
    tasktoken: "YOUR_SOCKET_ACCESS_TOKEN"
  }));
};

Realtime Events

During a realtime session, you'll receive these WebSocket events:

Audio Format

Both directions (microphone → server, server → client) use the same format:

Binary Frame Format

Every binary WebSocket frame (in both directions) is structured as:

[tasktoken]|[PCM audio data]

The pipe character | (0x7C) separates the token from the raw audio bytes.

Sending Microphone Audio

Capture microphone at 24 kHz using the Web Audio API with an AudioWorklet. Convert Float32 samples to Int16, prepend your task token, and send as a binary frame.

Key steps:

1. Request microphone with getUserMedia (enable echo cancellation and noise suppression)
2. Create an AudioContext at 24,000 Hz sample rate
3. Use an AudioWorklet to buffer and convert samples to Int16
4. Send each chunk as tasktoken|pcm_data binary frame

Receiving AI Audio

AI responses arrive as binary WebSocket frames in the same PCM Int16 24 kHz format. To play them:

1. Check if the message is a Blob (binary) before parsing as JSON
2. Find the pipe | separator and extract audio data after it
3. Convert Int16 → Float32 and create an AudioBuffer
4. Schedule gapless playback using AudioBufferSourceNode

Transcripts

Both user and AI speech are transcribed automatically. Transcripts arrive as task_output messages with a string prefix:

• TRANSCRIPT_USER: — what the user said
• TRANSCRIPT_AI: — what the AI said

// Example task_output message
{
  "type": "task_output",
  "message": "TRANSCRIPT_USER:What's the weather like today?"
}

{
  "type": "task_output",
  "message": "TRANSCRIPT_AI:I'd be happy to help, but I don't have access to real-time weather data."
}

Ending a Session

To gracefully end a realtime session, send task_session_end:

{
  "type": "task_session_end",
  "tasktoken": "YOUR_SOCKET_ACCESS_TOKEN"
}

After sending this, the server will process any remaining audio, send final cost/transcript events, and then emit task_postprocess_end. Wait for task_postprocess_end before closing the WebSocket.

Overview

Realtime TTS models convert text into streaming audio. Unlike standard TTS that processes a full prompt and returns an audio file, realtime TTS streams AI-generated speech as a continuous PCM audio stream over a WebSocket connection — in real time. The text prompt is submitted via POST /Run, not over the WebSocket. The WebSocket carries only task events (task_info, task_stream_ready, etc.), binary audio frames, and control messages (task_session_end).

No microphone is required. The flow is one-directional: text goes in, audio comes out.

The flow is:

1. Run the realtime TTS model via POST /Run with your text prompt in the parameters
2. Connect to the WebSocket and send task_info with your socketaccesstoken
3. Wait for task_stream_ready — the model has loaded and is generating audio
4. Receive AI audio as binary frames and play them
5. End the session with task_session_end or wait for the stream to finish naturally

How It Differs from Realtime Voice Conversation

Run Parameters

Each realtime TTS model has its own set of parameters. Use POST /Tool/Detail to discover the exact parameters for a specific model. See Model Parameters for parameter types.

Browse available realtime TTS models on the models page (filter by Realtime TTS category). Common parameters typically include the input text, voice selection, and output audio format. Example run:

curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "text": "Hello, this is a realtime text-to-speech demo.",
    "voice": "alloy",
    "output_audio_format": "audio/pcm",
    "output_audio_rate": "24000"
  }'

Connection & Registration

After running the task, connect to the WebSocket and register with task_info:

var ws = new WebSocket("wss://socket.wiro.ai/v1");

ws.onopen = function() {
  ws.send(JSON.stringify({
    type: "task_info",
    tasktoken: "YOUR_SOCKET_ACCESS_TOKEN"
  }));
};

Realtime Events

During a realtime TTS session, you'll receive these WebSocket events:

Event Sequence

A typical TTS session produces events in this order:

task_stream_ready     ← model is ready, audio chunks start arriving
[binary frames]       ← PCM audio data (many frames)
task_stream_end       ← audio generation complete for this segment
task_cost             ← cost for this segment
task_end              ← model process exiting
task_postprocess_end  ← safe to close WebSocket

Audio Format

Audio flows in one direction only: server → client. The client does not send any audio.

Binary Frame Format

Every binary WebSocket frame from the server is structured as:

[tasktoken]|[PCM audio data]

The pipe character | (0x7C) separates the token from the raw audio bytes. To extract the audio:

1. Find the first | byte in the binary frame
2. Everything after it is raw PCM Int16 audio data
3. Convert Int16 samples to your playback format (e.g., Float32 for Web Audio API)

Receiving AI Audio

AI speech arrives as binary WebSocket frames in PCM Int16 24 kHz format. To play them:

1. Check if the incoming message is binary (a Blob in JavaScript, bytes in Python) before attempting JSON parse
2. Find the pipe | separator and extract audio data after it
3. Convert Int16 → Float32 and create an AudioBuffer
4. Schedule gapless playback using AudioBufferSourceNode to avoid clicks between chunks

Gapless Playback

Audio arrives in many small chunks. To play them seamlessly:

• Track a nextPlayTime variable initialized to 0
• For each chunk, schedule it at max(audioContext.currentTime, nextPlayTime)
• Advance nextPlayTime by the chunk's duration
• This ensures chunks play back-to-back with no gaps or overlaps

Ending a Session

To gracefully end a realtime TTS session, send task_session_end:

{
  "type": "task_session_end",
  "tasktoken": "YOUR_SOCKET_ACCESS_TOKEN"
}

After sending this, the server will finish any in-progress generation, send final cost events, and then emit task_postprocess_end. Wait for task_postprocess_end before closing the WebSocket.

For TTS sessions, the stream often ends naturally when the model finishes generating audio for the provided text. In this case, you'll receive task_stream_end followed by task_end without needing to send task_session_end. However, it's good practice to send it explicitly for a clean shutdown, especially if you want to stop playback early.

Overview

Realtime speech-to-text models convert streaming audio into text transcripts as the user speaks. Unlike Realtime Voice Conversation which produces two-way audio, this mode is audio in → text out only. There is no AI audio playback — the server returns transcript strings over the WebSocket.

The flow is:

1. Run the realtime STT model via POST /Run to get a socketaccesstoken
2. Connect to the WebSocket and send task_info with your token
3. Wait for task_stream_ready — the model is ready to receive audio
4. Stream microphone audio as binary frames (client → server)
5. Receive transcript text as task_output messages with TRANSCRIPT_USER: prefix
6. End the session with task_session_end

How It Differs from Realtime Voice Conversation

Run Parameters

Each realtime STT model has its own set of parameters. Use POST /Tool/Detail to discover the exact parameters for a specific model. See Model Parameters for parameter types.

Browse available realtime STT models on the models page (filter by Realtime STT category). Common parameters typically include language hints and audio format settings. Example run:

curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "language": "en",
    "input_audio_format": "audio/pcm",
    "input_audio_rate": "24000"
  }'

Connection & Registration

After running the task, connect to the WebSocket and register with task_info:

var ws = new WebSocket("wss://socket.wiro.ai/v1");

ws.onopen = function() {
  ws.send(JSON.stringify({
    type: "task_info",
    tasktoken: "YOUR_SOCKET_ACCESS_TOKEN"
  }));
};

Realtime Events

During a realtime speech-to-text session, you'll receive these WebSocket events:

Audio Format

Audio flows in one direction only: client → server.

Binary Frame Format

Every binary WebSocket frame sent from the client is structured as:

[tasktoken]|[PCM audio data]

The pipe character | (0x7C) separates the token from the raw audio bytes. There are no binary frames from the server — all responses are JSON text.

Sending Microphone Audio

Capture microphone audio at 24 kHz using the Web Audio API with an AudioWorklet. Convert Float32 samples to Int16, prepend your task token, and send as a binary frame.

Key steps:

1. Request microphone with getUserMedia (enable echo cancellation and noise suppression)
2. Create an AudioContext at 24,000 Hz sample rate
3. Use an AudioWorklet to buffer and convert samples to Int16
4. Send each chunk as tasktoken|pcm_data binary frame
5. Continue sending until you end the session

Transcripts

Transcripts arrive as task_output messages with the TRANSCRIPT_USER: prefix. Each message contains a segment of transcribed speech:

{
  "type": "task_output",
  "message": "TRANSCRIPT_USER:What's the weather like today?"
}

{
  "type": "task_output",
  "message": "TRANSCRIPT_USER:I need to book a flight to New York."
}

Progressive Results

Transcripts arrive progressively as words and phrases are recognized — not just at segment boundaries. The model streams TRANSCRIPT_USER: messages word-by-word as speech is detected, so the client can display live, incremental results. To build a full transcript, concatenate all received messages:

var fullTranscript = [];

// Inside your message handler
if (msg.type === 'task_output' &&
    typeof msg.message === 'string' &&
    msg.message.startsWith('TRANSCRIPT_USER:')) {
  var segment = msg.message.substring(16);
  fullTranscript.push(segment);
  console.log('Segment:', segment);
  console.log('Full:', fullTranscript.join(' '));
}

Ending a Session

To gracefully end a realtime session, send task_session_end:

{
  "type": "task_session_end",
  "tasktoken": "YOUR_SOCKET_ACCESS_TOKEN"
}

After sending this, the server processes any remaining buffered audio, sends final transcript and cost events, and then emits task_postprocess_end. Wait for task_postprocess_end before closing the WebSocket.

Overview

The Files API lets you organize and upload data that can be referenced in model runs. Common use cases include:

• Training data — upload datasets for fine-tuning models
• File inputs — provide images, audio, or documents as model inputs
• Batch processing — store files for repeated use across multiple runs

POST /File/FolderCreate

Creates a new folder to organize your uploaded files.

Response

{
  "result": true,
  "errors": [],
  "list": [{
    "id": "folder-abc123",
    "name": "training-data",
    "parentid": "root-folder-id",
    "size": "0",
    "contenttype": "",
    "addedtime": "1716276543"
  }]
}

POST /File/Upload

Uploads a file using multipart/form-data. You can optionally assign it to a folder.

File size limit: 100 MB per file.

Supported file types: Images (jpg, png, gif, jpeg, webp, heic), video (mp4, webm, mov), audio (mp3, wav, m4a), documents (pdf, csv, docx, xlsx, pptx, txt, md, epub), and ZIP archives (automatically extracted).

Response

{
  "result": true,
  "errors": [],
  "list": [{
    "id": "file-id",
    "name": "dataset.csv",
    "contenttype": "text/csv",
    "size": "1048576",
    "parentid": "folder-id",
    "url": "https://cdn1.wiro.ai/...",
    "addedtime": "1716276727",
    "accesskey": "..."
  }]
}

Using Files in Runs

Once uploaded, reference a file by its URL or ID in your model run parameters. For example, an image upscaler model might accept a imageUrl parameter — pass the URL returned from the upload response.

{
  "imageUrl": "https://files.wiro.ai/...",
  "scale": 4
}

Overview

When you run an AI model through Wiro, you are billed based on the type of work performed. Each model has its own pricing, visible on the model's page in the marketplace and on the pricing page. You pay only for successful runs — server errors are never billed.

Wiro uses a prepaid credit model. You add credits to your account and they are drawn down as you use models. Credits also determine your concurrency limit.

Billing Methods

Every model on Wiro uses one of the following billing methods. The method is set per model and determines how the cost is calculated.

Fixed-Rate Methods

Usage-Based Methods

Special Methods

Dynamic Pricing

Many models have dynamic pricing — the cost varies based on the input parameters you choose. For example, a video generation model might charge different rates depending on the resolution and duration you select.

The pricing is returned in the dynamicprice field of the Tool/List and Tool/Detail API responses as a JSON array:

[
  {
    "inputs": { "resolution": "720p", "duration": "5" },
    "price": 0.13,
    "priceMethod": "cpr"
  },
  {
    "inputs": { "resolution": "1080p", "duration": "5" },
    "price": 0.29,
    "priceMethod": "cpr"
  }
]

How Dynamic Pricing Works

Each entry in the dynamicprice array represents a pricing tier:

When inputs contains specific parameter values (e.g. "resolution": "720p"), that price only applies when you run the model with those exact parameters. When inputs is empty ({}), it's a flat rate that applies regardless of input parameters.

Input matching also supports QUANTITY values (e.g. "QUANTITY:1", "QUANTITY:3") for models where the number of input files affects pricing.

Example: Video Generation Pricing

A video model might have pricing tiers based on resolution and duration:

Example: Simple Flat Pricing

An image generation model with a flat rate:

[{ "inputs": {}, "price": 0.03, "priceMethod": "cpr" }]

This means every run costs $0.03, regardless of parameters.

Fallback Pricing (Per-Second)

When a model does not have dynamicprice set, billing falls back to per-second pricing:

totalcost = elapsed_seconds × cps

Where cps (cost per second) is either the model's own rate or the queue group's default rate. The API also returns an approximatelycost field — an estimate based on the model's average run time:

approximatelycost = average_elapsed_seconds × cps

This gives you a rough idea of the expected cost before running the model.

Checking Prices

Via the API

Pricing information is included in both the Tool/List and Tool/Detail responses in the dynamicprice field. Use POST /Tool/Detail with the model's slugowner and slugproject to get full pricing details.

Via MCP

When using the MCP server, both search_models and get_model_schema tools return pricing information in their responses. Your AI assistant can check the cost before running a model.

Pricing Page

Browse and compare model prices interactively on the pricing page. Select a budget to see how many runs each model can perform.

What You Pay For

You are billed for successfully completed model runs. A run is successful when the task reaches task_postprocess_end status with pexit of "0". The actual cost is recorded in the task's totalcost field, which you can retrieve via Task/Detail.

What You Are Not Charged For

• Server errors — if a run fails due to a server-side error, no charge is incurred.
• Queue time — time spent waiting in the queue before processing starts is free.
• Cancelled tasks — tasks cancelled before processing completes are not billed.

Monitoring Your Spending

• Check the totalcost field in Task/Detail responses to see the cost of individual runs.
• View your overall balance, usage history, and billing details in the Dashboard.
• When using MCP, the get_task tool returns the cost of completed runs.

Overview

Concurrency limits control how many tasks your account can process at the same time. When you reach your limit, the API returns an error response with code 96. You should wait for a running task to complete before submitting a new one, or add funds to increase your limit.

How It Works

Your concurrency limit is determined by your current account balance:

• When your balance is $250 or below, you can run concurrent tasks equal to 10% of your current USD balance (minimum 1).
• When your balance is above $250, there is no concurrency limit.

Examples

The formula: max(1, floor(balance_usd * 0.10)). Once your balance exceeds $250, all limits are removed.

What Counts as Active

Only tasks that are actively being processed count toward your concurrency limit. A task is considered active from task_queue until it reaches a terminal status:

• task_postprocess_end — task completed (success or failure)
• task_cancel — task was cancelled or killed

Once a task reaches either of these statuses, it no longer counts toward your limit.

API Response

When you hit the concurrency limit, the POST /Run endpoint returns an error with code 96:

{
  "result": false,
  "errors": [
    {
      "code": 96,
      "message": "You have reached your concurrent task limit. With your current balance of $50.00, you can run up to 5 tasks at the same time. Add funds to increase your limit."
    }
  ]
}

The error message includes your current balance and the calculated limit, so you know exactly how many concurrent tasks you can run.

Error Codes

Increasing Your Limit

To increase your concurrency limit, simply add credits to your account. Your limit is recalculated automatically based on your current balance at the time of each run request.

For enterprise needs or custom concurrency arrangements, contact support.

Best Practices

• Check error code 96 — if you get this error, wait for a running task to complete before submitting new ones.
• Use WebSocket for monitoring — instead of polling /Task/Detail repeatedly, connect via WebSocket to get real-time updates without extra API calls.
• Use wait=false in MCP — for long-running models (video, 3D), submit with wait=false and check with get_task to avoid holding connections.
• Implement exponential backoff — if polling task status, start at 3 seconds and increase the interval for longer tasks.

Response Format

When an API request fails, the response includes result: false and an errors array:

{
  "result": false,
  "errors": [
    {
      "code": 97,
      "message": "Insufficient balance"
    }
  ]
}

All API responses return HTTP 200 — use the result field and error code to determine success or failure.

Error Codes

Error codes indicate the category of the problem. Use these for conditional logic in your application.

Authentication Errors

Returned when API key or bearer token authentication fails. All return HTTP 401.

Run Errors

Returned by POST /Run/{owner}/{model}.

Balance & Limits

Validation Errors

Model Access Errors

Task Errors

Returned by POST /Task/Detail, POST /Task/Cancel, POST /Task/Kill, and POST /Task/InputOutputDelete.

Error Handling

Always check result first, then inspect the code in the errors array:

const data = await response.json();

if (!data.result) {
  const error = data.errors[0];
  switch (error.code) {
    case 96:
      console.log('Concurrent limit — wait for a task to finish');
      break;
    case 97:
      console.log('Insufficient balance — add funds');
      break;
    case 98:
      console.log('Sign in required');
      break;
    default:
      console.log('Error:', error.message);
  }
}

Retry Strategy

Overview

Each example below demonstrates the full Wiro workflow: authenticate, run a model, poll for task completion, and retrieve the result. Choose your preferred language from the tabs.

• curl — Shell scripting with bash
• Python — Using the requests library
• Node.js — Using axios
• PHP — Using cURL functions
• C# — Using HttpClient (.NET 6+)
• Swift — Using async/await URLSession
• Dart — Using the http package
• Kotlin — Using java.net.http
• Go — Using the standard library net/http

Full Examples

Select a language tab to see the complete example. All examples perform the same steps:

1. Set up authentication headers
2. Run a model (POST /Run/{owner-slug}/{model-slug})
3. Poll the task status (POST /Task/Detail)
4. Print the final output

What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI assistants use external tools directly. With the Wiro MCP server, your AI assistant can search models, run inference, track tasks, and upload files — all without leaving your editor.

The hosted MCP server is available at mcp.wiro.ai/v1 and works with any MCP-compatible client, including Cursor, Claude Code, Claude Desktop, and Windsurf. Every request uses your own API key — nothing is stored on the server.

You need a Wiro API key to use the MCP server. If you don't have one yet, create a project here.

Links

• Model Context Protocol (MCP) — open standard specification
• GitHub: wiroai/Wiro-MCP — source code & self-hosting instructions
• npm: @wiro-ai/wiro-mcp — npm package
• Wiro Model Catalog — browse all available models
• Create API Key — get started in seconds

Setup

Connect your AI assistant to Wiro's MCP server. Pick your client:

Cursor MCP settings JSON config Claude Code One command setup Claude Desktop JSON config setup Windsurf MCP settings config Other Clients Any MCP-compatible tool

claude mcp add --transport http wiro \
  https://mcp.wiro.ai/v1 \
  --header "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET"

{
  "mcpServers": {
    "wiro": {
      "url": "https://mcp.wiro.ai/v1",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY:YOUR_API_SECRET"
      }
    }
  }
}

{
  "mcpServers": {
    "wiro": {
      "serverUrl": "https://mcp.wiro.ai/v1",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY:YOUR_API_SECRET"
      }
    }
  }
}

https://mcp.wiro.ai/v1

Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET

Authentication

The MCP server supports both Wiro authentication types. Your project's auth type determines what credentials you provide.

Signature-Based (Recommended)

More secure. Requires both API key and API secret. Pass them as plain text separated by a colon:

Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET

API Key Only

Simpler. Only requires the API key:

Authorization: Bearer YOUR_API_KEY

No base64 encoding needed. Credentials are sent per-request and are never stored. The server is fully stateless.

Available Tools

The MCP server exposes 11 tools organized in four categories. Your AI assistant picks the right tool automatically.

Model slugs: Use the clean/lowercase format owner/model (e.g. openai/sora-2, wiro/virtual-try-on). These correspond to the cleanslugowner/cleanslugproject values returned by search_models.

Discovery

Execution

Task Management

Utility

Examples

Generate an image

The assistant will use search_models → get_model_schema → run_model and return the image URL.

Generate a video

The assistant will use get_model_schema → run_model (wait=false) → get_task to poll for the result.

Find models

The assistant will call search_models with categories filter.

How It Works

The MCP server is stateless. Each request is fully isolated:

1. Your AI assistant sends a request to mcp.wiro.ai/v1 with your credentials
2. The server calls the Wiro API on your behalf
3. Results are returned to your assistant

All tools are dynamic — they fetch model data at runtime. New models are instantly available via MCP.

Tool Reference

search_models

Search Wiro's model catalog by keyword, category, owner, or any combination. Calls POST /Tool/List on the Wiro API.

Returns a list of models with their cleanslugowner/cleanslugproject (the slug you pass to other tools), title, description, categories, and pricing.

get_model_schema

Get the full parameter schema for a specific model. Calls POST /Tool/Detail on the Wiro API.

Returns the model's parameter groups, each containing items with id, type (text, textarea, select, range, fileinput, etc.), label, required, options, default, and note. Also includes pricing information. Use these to construct the params object for run_model.

recommend_model

Describe what you want to create and get model recommendations ranked by relevance. Calls POST /Tool/List on the Wiro API with relevance sorting.

Returns a list of recommended models with slugs, descriptions, categories, and pricing — sorted by relevance to your task.

explore

Browse curated AI models on Wiro, organized by category. Calls POST /Tool/Explore on the Wiro API. No parameters required.

Returns models grouped into curated sections like "Recently Added", "Image Generation", "Video", etc. Each model includes its slug, description, categories, and rating. Use this to discover what's available without searching.

run_model

Run any AI model on Wiro. Calls POST /Run/{owner}/{model} on the Wiro API.

When wait=true, returns the final task result including pexit (exit code, "0" = success), outputs (CDN URLs for generated files), and debugoutput (LLM text responses).

When wait=false, returns taskid and tasktoken — use get_task to check progress.

get_task

Check task status and get results. Calls POST /Task/Detail on the Wiro API.

Returns the task's current status, pexit (process exit code), outputs (file URLs), debugoutput (LLM responses), elapsedseconds, and totalcost.

Determining success: Check pexit — "0" means success, any other value means failure. For LLM models, the response is available as structured content in outputs (with contenttype: "raw") and as merged text in debugoutput. See Tasks for the full task lifecycle.

get_task_price

Get the cost of a completed task. Calls POST /Task/Detail on the Wiro API and returns billing information.

Returns the task's billing status, total cost, and duration. Only successful tasks (pexit: "0") are billed — failed tasks show $0 with a clear explanation that they were not charged.

cancel_task

Cancel a task that is still queued (before worker assignment). Calls POST /Task/Cancel on the Wiro API.

Tasks that have already been assigned to a worker cannot be cancelled — use kill_task instead.

kill_task

Kill a task that is currently running (after worker assignment). Calls POST /Task/Kill on the Wiro API.

The worker will stop processing and the task will move to task_cancel status.

upload_file

Upload a file from a URL to Wiro for use as model input. Downloads the file and uploads it via POST /File/Upload.

Returns the uploaded file's Wiro URL, which can be passed to any model parameter that accepts a file.

search_docs

Search the Wiro documentation for guides, API references, and code examples.

Returns relevant documentation sections matching your query.

FAQ

What models can I use?

All models in the Wiro catalog.

Is my API key stored?

No. The server is fully stateless. Credentials are sent per-request and never stored.

Does it cost extra?

No. The MCP server is free. You pay for model runs at standard pricing.

Can I self-host?

Yes. See Self-Hosted MCP for instructions.

Quick Start

Add to your AI assistant's MCP config:

{
  "mcpServers": {
    "wiro": {
      "command": "npx",
      "args": ["-y", "@wiro-ai/wiro-mcp"],
      "env": {
        "WIRO_API_KEY": "your-api-key",
        "WIRO_API_SECRET": "your-api-secret"
      }
    }
  }
}

That's it. Your assistant now has access to all Wiro AI models.

Setup

Add the self-hosted MCP server to your AI assistant:

Cursor MCP settings JSON config Claude Code One command setup Claude Desktop JSON config setup Windsurf MCP settings config Other Clients Any MCP-compatible tool

{
  "mcpServers": {
    "wiro": {
      "command": "npx",
      "args": ["-y", "@wiro-ai/wiro-mcp"],
      "env": {
        "WIRO_API_KEY": "your-api-key",
        "WIRO_API_SECRET": "your-api-secret"
      }
    }
  }
}

claude mcp add wiro -- npx -y @wiro-ai/wiro-mcp

export WIRO_API_KEY="your-api-key"
export WIRO_API_SECRET="your-api-secret"

{
  "mcpServers": {
    "wiro": {
      "command": "npx",
      "args": ["-y", "@wiro-ai/wiro-mcp"],
      "env": {
        "WIRO_API_KEY": "your-api-key",
        "WIRO_API_SECRET": "your-api-secret"
      }
    }
  }
}

{
  "mcpServers": {
    "wiro": {
      "command": "npx",
      "args": ["-y", "@wiro-ai/wiro-mcp"],
      "env": {
        "WIRO_API_KEY": "your-api-key",
        "WIRO_API_SECRET": "your-api-secret"
      }
    }
  }
}

npx -y @wiro-ai/wiro-mcp

Authentication

Signature-Based (Recommended)

Provide both API key and secret:

WIRO_API_KEY=your-api-key
WIRO_API_SECRET=your-api-secret

API Key Only

Omit WIRO_API_SECRET:

WIRO_API_KEY=your-api-key

Available Tools

The self-hosted server provides the same 11 tools as the hosted MCP server. Your AI assistant picks the right tool automatically.

Model slugs: Use the clean/lowercase format owner/model (e.g. openai/sora-2, wiro/virtual-try-on). These correspond to cleanslugowner/cleanslugproject values returned by search_models.

Discovery

Execution

Task Management

Utility

See the Wiro MCP Server page for detailed parameter tables and examples.

Environment Variables

GitHub & npm

• GitHub: github.com/wiroai/Wiro-MCP
• npm: @wiro-ai/wiro-mcp

Using as a Library

import { createMcpServer, WiroClient } from '@wiro-ai/wiro-mcp';

const client = new WiroClient('your-api-key', 'your-api-secret');
const server = createMcpServer(client);

Self-Hosting on Your Server

git clone https://github.com/wiroai/Wiro-MCP.git
cd Wiro-MCP
npm install
npm run build
export WIRO_API_KEY="your-api-key"
export WIRO_API_SECRET="your-api-secret"
node dist/index.js

Requires Node.js 18 or later. Create a project to get API keys.

Overview

The @wiro-ai/wiro-mcp package exports a WiroClient class that you can use as a standalone API client — no MCP setup required. It handles authentication (both signature-based and API key only), model discovery, execution, task polling, and file uploads.

Links

• npm: @wiro-ai/wiro-mcp
• GitHub: wiroai/Wiro-MCP
• Create API Key

Installation

npm install @wiro-ai/wiro-mcp

Requires Node.js 18 or later.

Quick Start

import { WiroClient } from '@wiro-ai/wiro-mcp/client';

const client = new WiroClient('YOUR_API_KEY', 'YOUR_API_SECRET');

// Run an image generation model
const run = await client.runModel('google/nano-banana-pro', {
  prompt: 'A futuristic city at sunset',
  aspectRatio: '16:9',
  resolution: '2K'
});

if (!run.result) {
  console.log('Run failed:', run.errors);
  process.exit(1);
}

// Wait for the result (polls Task/Detail until complete)
const result = await client.waitForTask(run.socketaccesstoken);
const task = result.tasklist[0];

if (task.pexit === '0') {
  console.log('Output:', task.outputs[0].url);
} else {
  console.log('Failed:', task.pexit);
}

Authentication

The client supports both Wiro authentication methods:

Signature-Based (Recommended)

Provide both API key and secret. HMAC-SHA256 signatures are generated automatically per request.

const client = new WiroClient('your-api-key', 'your-api-secret');

API Key Only

Omit the secret for simpler server-side usage.

const client = new WiroClient('your-api-key');

Custom Base URL

Override the API endpoint if needed (third parameter):

const client = new WiroClient('key', 'secret', 'https://custom-api.example.com/v1');

Available Methods

Examples

Search Models

const models = await client.searchModels({
  search: 'image generation',
  categories: ['text-to-image'],
  limit: 5
});

for (const model of models.tool) {
  console.log(`${model.cleanslugowner}/${model.cleanslugproject} — ${model.title}`);
}

Get Model Parameters

const detail = await client.getModelSchema('google/nano-banana-pro');
const model = detail.tool[0];

if (model.parameters) {
  console.log('Parameters:');
  for (const group of model.parameters) {
    for (const param of group.items) {
      console.log(`  ${param.id} (${param.type}) ${param.required ? '— required' : ''}`);
    }
  }
}

Run an LLM

const run = await client.runModel('openai/gpt-5-2', {
  prompt: 'Explain quantum computing in 3 sentences'
});

const result = await client.waitForTask(run.socketaccesstoken);
const task = result.tasklist[0];

if (task.pexit === '0') {
  // Merged text
  console.log(task.debugoutput);

  // Structured thinking/answer
  const output = task.outputs[0];
  if (output.contenttype === 'raw') {
    console.log('Thinking:', output.content.thinking);
    console.log('Answer:', output.content.answer);
  }
}

Upload a File and Use It

// Upload an image
const upload = await client.uploadFile('https://example.com/photo.jpg');
const fileUrl = upload.list[0].url;

// Use it in a model run
const run = await client.runModel('wiro/virtual-try-on', {
  inputImageHuman: fileUrl,
  inputImageClothes: 'https://example.com/shirt.jpg'
});

const result = await client.waitForTask(run.socketaccesstoken);
console.log('Output:', result.tasklist[0].outputs[0].url);

Poll Manually

const run = await client.runModel('klingai/kling-v3', {
  prompt: 'A drone shot over mountains',
  duration: '5',
  aspectRatio: '16:9'
});

// Poll manually instead of using waitForTask
const interval = setInterval(async () => {
  const detail = await client.getTask({ tasktoken: run.socketaccesstoken });
  const task = detail.tasklist[0];
  console.log('Status:', task.status);

  if (task.status === 'task_postprocess_end') {
    clearInterval(interval);
    if (task.pexit === '0') {
      console.log('Video:', task.outputs[0].url);
    }
  }
}, 5000);

TypeScript

All types are exported from the package:

import { WiroClient } from '@wiro-ai/wiro-mcp/client';
import type {
  RunModelResult,
  TaskDetailResponse,
  Task,
  TaskOutput,
  ToolListResponse,
  ToolDetailResponse,
  ToolListItem,
  SearchModelsParams,
} from '@wiro-ai/wiro-mcp/client';

Overview

n8n is a powerful workflow automation platform. The Wiro AI community node gives you access to all Wiro AI models as individual nodes you can drag and drop into any workflow.

Each model is a separate node — so you get dedicated parameters, descriptions, and output handling for every model without any configuration hassle.

Links

• npm: @wiro-ai/n8n-nodes-wiroai
• GitHub: wiroai/n8n-nodes-wiroai
• n8n Community Nodes Installation Guide
• Wiro Model Catalog — browse all available models

Available Model Categories

Installation

Install the community node package in your n8n instance:

Via n8n UI (Recommended)

1. Open your n8n instance Navigate to your self-hosted or cloud n8n dashboard
2. Go to Settings Open Settings → Community Nodes
3. Install the node Click Install a community node and enter: @wiro-ai/n8n-nodes-wiroai
4. Confirm Click Install and wait for completion

Via Command Line

npm install @wiro-ai/n8n-nodes-wiroai

Restart n8n after installation.

Authentication

The node supports both Wiro authentication methods:

1. Add credentials Go to Credentials → Add new → Wiro API in n8n
2. Select auth method Signature-Based — enter API key + secret (recommended)  |  API Key Only — enter API key only
3. Save Click Save to store your credentials

Get your credentials at wiro.ai/panel/project.

Usage

Each Wiro model appears as a separate node in the n8n node picker. Search for "Wiro" or the model name to find it.

Example: Generate a Video with Sora 2

1. Add the Wiro - Sora 2 Pro node to your workflow
2. Connect your Wiro credentials
3. Set the parameters:
   • Prompt: A cat astronaut floating in space
   • Seconds: 8
   • Resolution: 1080p
4. Run the workflow

The node returns the task result with output URLs:

{
  "taskid": "abc123",
  "status": "completed",
  "url": "https://cdn1.wiro.ai/xyz/0.mp4"
}

Example: Transcribe Audio with Whisper

1. Add the Wiro - Whisper Large 3 node
2. Connect an audio file from a previous node or provide a URL
3. Select language and output format
4. Run — get the transcribed text

Example: LLM Chat with GPT-5

1. Add the Wiro - GPT-5 node
2. Set your prompt and system instructions
3. Run — get the AI response

Compatibility

Wiro Agents on the Web

The endpoints below cover the full programmatic surface. If you also want to see the web product alongside what you're building — landing pages, marketing copy, the visual catalog, and the no-code Build Your Own Agent flow — these are the public Wiro pages dedicated to agents:

What are Wiro Agents?

Wiro Agents are autonomous AI assistants that run persistently in isolated containers. Unlike one-shot model runs, agents maintain conversation memory, connect to external services, and use tools to complete tasks on your behalf — all managed through the API.

The system has two layers:

• Agent templates (the catalog) — Pre-built agent definitions published by Wiro. Each template defines the agent's capabilities, required credentials, tools, and pricing. Browse the catalog with POST /Agent/List.
• UserAgent instances (your deployments) — When you deploy an agent template, Wiro creates a personal instance tied to your account. Each instance runs in its own container with its own credentials, configuration, conversation history, and billing.

Every instance is fully isolated. Your credentials, conversations, and data are never shared with other users.

Base URL

https://api.wiro.ai/v1

Authentication

Agents use the same authentication as the rest of the Wiro API. Include your key in every request:

Public endpoints — Agent/List, Agent/Detail, Skills/List, Skills/Detail, Skills/Capabilities, Credentials/List, and Credentials/Detail are catalog endpoints and do not require authentication. You can browse available agents, the skill registry, and the credential schema without an API key.

Authenticated endpoints — All UserAgent/* endpoints require a valid API key.

For full details, see Authentication.

Agent Lifecycle

Deploying and running an agent follows this flow:

1. Browse — call POST /Agent/List to discover available agents in the catalog
2. Deploy — call POST /UserAgent/Deploy with the agent's guid, title, useprepaid: true, and plan ("starter" or "pro"). The subscription cost is deducted from your wallet immediately.
3. Configure — if the agent requires credentials (API keys, OAuth tokens), set them per-provider with POST /UserAgent/CredentialUpsert, or per-skill with POST /UserAgent/CustomSkillUpsert. See Agent Credentials for details
4. Start — call POST /UserAgent/Start to queue the agent for launch
5. Running — the agent's container starts and the agent becomes available for conversation
6. Chat — send messages via POST /UserAgent/Message/Send. See Agent Messaging for the full messaging API

UserAgent Statuses

Every deployed agent instance has a numeric status that reflects its current state:

Automatic Restart (restartafter)

When you update an agent's configuration while it is Running (status 3 or 4), the system automatically triggers a restart cycle: the agent is moved to Stopping (status 1) with restartafter set to true. Once the container fully stops, the system automatically re-queues it, applying the new configuration on startup.

This means you can update credentials or settings on a running agent without manually stopping and starting it.

Endpoints

POST /Agent/List

Lists available agents in the catalog. This is a public endpoint — no authentication required.

Response

{
  "result": true,
  "errors": [],
  "total": 12,
  "agents": [
    {
      "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Instagram Manager",
      "slug": "instagram-manager",
      "headline": "Automate your Instagram presence with AI",
      "description": "An autonomous agent that manages your Instagram account...",
      "cover": "https://cdn.wiro.ai/uploads/agents/instagram-manager-cover.webp",
      "categories": ["social-media", "marketing"],
      "samples": ["https://cdn.wiro.ai/uploads/agents/instagram-manager-sample-1.webp"],
      "tiermultiplier": 3,
      "tiers": {
        "starter": { "priceUsd": 9, "credits": 1000 },
        "pro":     { "priceUsd": 29, "credits": 5000 }
      },
      "status": 1,
      "createdat": "1711929600",
      "updatedat": "1714521600"
    }
  ]
}

POST /Agent/Detail

Retrieves details for a single agent by guid or slug. This is a public endpoint — no authentication required.

Response

{
  "result": true,
  "errors": [],
  "agents": [
    {
      "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Instagram Manager",
      "slug": "instagram-manager",
      "headline": "Automate your Instagram presence with AI",
      "description": "An autonomous agent that manages your Instagram account...",
      "cover": "https://cdn.wiro.ai/uploads/agents/instagram-manager-cover.webp",
      "categories": ["social-media", "marketing"],
      "samples": ["https://cdn.wiro.ai/uploads/agents/instagram-manager-sample-1.webp"],
      "tiermultiplier": 3,
      "tiers": {
        "starter": { "priceUsd": 9, "credits": 1000 },
        "pro":     { "priceUsd": 29, "credits": 5000 }
      },
      "peractioncosts": {
        "message":    10,
        "create":     60,
        "modify":     20,
        "regenerate": 20
      },
      "skills": ["int-instagram-post", "int-wiro-generator"],
      "skillsmeta": [
        { "name": "int-instagram-post",  "title": "Instagram — Post & Stories",      "icon": "https://wiro.ai/images/icons/skills/instagram.svg", "category": "int", "credential_key": "instagram" },
        { "name": "int-wiro-generator",  "title": "Wiro Generator (platform-managed)", "icon": "https://wiro.ai/images/icons/skills/wiro.svg",     "category": "int", "credential_key": "wiro" }
      ],
      "credentials": {
        "instagram": {
          "optional": false,
          "extra": false,
          "_editable": { "appid": true, "appsecret": true, "igusername": false },
          "_schema": {
            "title": "Instagram",
            "icon": "https://wiro.ai/images/icons/skills/instagram.svg",
            "brand_color": "#e4405f",
            "brand_text_color": "#ffffff",
            "brand_logo_filter": "none",
            "docs_url": "integration-instagram-skills",
            "credential_mode": "oauth",
            "connection_modes": ["wiro", "own"],
            "wiro_connect_pending": true,
            "oauth_provider": {
              "auth_method_value": "wiro",
              "connect_endpoint": "/UserAgentOAuth/IGConnect",
              "disconnect_endpoint": "/UserAgentOAuth/IGDisconnect",
              "status_endpoint": "/UserAgentOAuth/IGStatus",
              "connect_button_label": "Connect with Instagram",
              "connect_button_icon": "/images/icons/skills/instagram.svg",
              "connect_button_brand_color": "#e4405f",
              "connect_button_text_color": "#ffffff",
              "connect_button_logo_filter": "none",
              "username_field": "igusername",
              "return_query_param": "ig_connected",
              "return_error_param": "ig_error",
              "return_error_detail_param": "ig_error_detail",
              "account_picker": null,
              "extra_step": null
            },
            "fields": [
              {
                "key": "appid",
                "type": "text",
                "label": "App ID",
                "required": true,
                "pattern": "^[0-9]+$",
                "oauth_managed": true,
                "only_in_modes": ["own"]
              },
              {
                "key": "appsecret",
                "type": "password",
                "label": "App Secret",
                "required": true,
                "show_toggle": true,
                "oauth_managed": true,
                "only_in_modes": ["own"]
              },
              {
                "key": "igusername",
                "type": "text",
                "label": "Connected Account",
                "required": false,
                "auto_filled_by_oauth": true,
                "readonly_when_connected": true
              }
            ]
          }
        }
      },
      "extracreditpacks": [],
      "status": 1,
      "createdat": "1711929600",
      "updatedat": "1714521600"
    }
  ]
}

Credential response flags (UserAgent/Detail / UserAgent/MyAgents)

Every credential object in the top-level credentials tree on the per-instance endpoints carries:

Field redaction in responses

• fieldstatus: "oauth_session" fields (accesstoken, refreshtoken, tokenexpiresat, pageAccessToken, etc.) — always stripped from every response, regardless of caller role.
• fieldstatus: "platform" fields (credentials.wiro.apiKey, credentials.openai.apiKey, credentials.calendarific.apiKey) — stripped for API callers (role = user). Only the agent runtime itself sees them.
• fieldstatus: "oauth_app" fields (clientsecret, appsecret) — visible to anyone who can read the credentials. History writes redact clientsecret to [REDACTED], but the live value is returned. Treat them as privileged values in your own UI layer (do not surface them to non-admin users).
• Sentinel rows _isoptional / _isextra — never appear as fields; they're folded into the optional and extra flags above.

API callers see the non-sensitive fields (public identifiers like clientid, display-only values like igusername, flags like authmethod, and the three status flags above).

POST /UserAgent/Deploy

Creates a new agent instance from a catalog template, or builds a brand-new custom agent (no template).

Prepaid deploy (useprepaid: true + tier) charges your wallet for the chosen tier price immediately and inserts a 30-day subscription row (plan: "agent", provider: "prepaid"). The instance is created in status 6 (Setup Required) when the template has required credentials you didn't pass inline; otherwise it auto-transitions to 0 (Stopped) and is ready for UserAgent/Start.

If you pass credentials, skills, or customskills at the top level of the Deploy body they are applied server-side in the same call (one-shot deploy + initial setup) — note that inline credentials only accept flat string/number fields and can't populate nested arrays (firebase accounts, drive folders, app-store apps); use POST /UserAgent/CredentialUpsert afterwards for those. See Agent Credentials → Prepaid deploy — inline setup supported for the full rules.

Headers: Standard API authentication — x-api-key for key-based projects, or x-nonce + x-signature for signature-based projects (see Authentication). For team-scoped deploys (when an end user deploys via a team project), pass teamGUID: <team-guid> as an additional request header; the API validates the caller is a team admin before writing the instance row.

Request body — template deploy (recommended API pattern)

{
  "agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "My Instagram Bot",
  "useprepaid": true,
  "tier": "starter",
  "pinned": false
}

Request body — custom build (Build Your Own Agent)

{
  "custom": true,
  "title": "My Custom Sales Agent",
  "description": "Watches inbound emails and posts a summary to Slack each morning.",
  "useprepaid": true,
  "tier": "pro",
  "skills": {
    "int-gmail-check": true,
    "int-wordpress-post": true,
    "int-wiro-generator": true
  },
  "credentials": {
    "gmail":    { "account": "[email protected]", "apppassword": "xxxx xxxx xxxx xxxx" },
    "sys-telegram": { "bottoken": "123456:ABC-DEF...", "allowedusers": "[\"761381461\"]", "sessionmode": "private" }
  }
}

Response

{
  "result": true,
  "errors": [],
  "useragents": [
    {
      "guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
      "uuid": "your-user-uuid",
      "agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "teamguid": null,
      "title": "My Instagram Bot",
      "description": null,
      "tier": "starter",
      "tiermultiplier": 3,
      "credentials": {
        "instagram": {
          "_connected": false,
          "optional": false,
          "extra": false,
          "_editable": { "authmethod": true, "igusername": true },
          "_schema": {
            "title": "Instagram",
            "icon": "https://wiro.ai/images/icons/credentials/instagram.svg",
            "brand_color": "#e4405f",
            "brand_text_color": "#ffffff",
            "brand_logo_filter": "brightness(0) invert(1)",
            "docs_url": "integration-instagram-skills",
            "credential_mode": "oauth_or_api_key",
            "connection_modes": ["wiro", "own"],
            "wiro_connect_pending": false,
            "fields": [
              { "key": "authmethod", "label": "Authentication Method", "type": "select", "required": true, "options": [{ "label": "Wiro-managed", "value": "wiro" }, { "label": "Own OAuth app", "value": "own" }], "default": "wiro" },
              { "key": "igusername", "label": "Instagram Username", "type": "text", "required": true, "placeholder": "@yourbusiness" }
            ]
          },
          "_required_missing": true,
          "authmethod": "",
          "igusername": ""
        }
      },
      "customskills": [],
      "scheduledskills": [],
      "skills": [
        { "name": "int-instagram-post", "enabled": true, "_edited": false, "_user_created": false },
        { "name": "int-wiro-generator", "enabled": true, "_edited": false, "_user_created": false }
      ],
      "skillsmeta": {
        "int-instagram-post": {
          "name": "int-instagram-post",
          "title": "Instagram Post",
          "icon": "https://wiro.ai/images/icons/skills/instagram.svg",
          "brand_color": "#e4405f",
          "brand_text_color": "#ffffff",
          "brand_logo_filter": "brightness(0) invert(1)",
          "category": "int",
          "docs_url": "integration-instagram-skills",
          "credential_key": "instagram",
          "additional_credential_keys": [],
          "requires_credentials": true,
          "user_invocable": true,
          "deprecated": false,
          "replacement": null,
          "description": "Post carousel feed and multi-story via Meta Graph API."
        },
        "int-wiro-generator": {
          "name": "int-wiro-generator",
          "title": "Wiro Generator (platform-managed)",
          "icon": "https://wiro.ai/images/icons/skills/wiro.svg",
          "brand_color": "#33f2bc",
          "brand_text_color": "#0f1a24",
          "brand_logo_filter": null,
          "category": "int",
          "docs_url": null,
          "credential_key": "wiro",
          "additional_credential_keys": [],
          "requires_credentials": true,
          "user_invocable": false,
          "deprecated": false,
          "replacement": null,
          "description": "Internal: lets the agent call Wiro's own image / video / LLM generation API. Other skills invoke it; users do not."
        }
      },
      "monthlycredits": 1000,
      "monthlypriceusd": 9,
      "extracredits": 0,
      "usedcredits": 0,
      "remainingcredits": 1000,
      "creditperiod": "2026-05",
      "creditsyncat": null,
      "peractioncosts": {
        "message":    10,
        "create":     60,
        "modify":     20,
        "regenerate": 20
      },
      "teamsessionmode": "",
      "status": 6,
      "setuprequired": true,
      "pinned": false,
      "agent": {
        "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "title": "Instagram Manager",
        "slug": "instagram-manager",
        "cover": "https://cdn.wiro.ai/uploads/agents/instagram-manager-cover.webp",
        "categories": ["social-media", "marketing"],
        "tiermultiplier": 3,
        "tiers": {
          "starter": { "priceUsd": 9, "credits": 1000 },
          "pro":     { "priceUsd": 29, "credits": 5000 }
        },
        "extracreditpacks": [
          { "packkey": "small",  "credits": 5000,  "priceusd": 45,  "enabled": true },
          { "packkey": "medium", "credits": 10000, "priceusd": 80,  "enabled": true },
          { "packkey": "large",  "credits": 20000, "priceusd": 140, "enabled": true }
        ]
      },
      "createdat": 1714608000,
      "updatedat": 1714608000
    }
  ]
}

Status and setuprequired on deploy

The Deploy response reflects the same composed shape you get from UserAgent/Detail. Two status signals matter:

POST /UserAgent/MyAgents

Lists all agent instances deployed under your account.

Response

{
  "result": true,
  "errors": [],
  "useragents": [
    {
      "guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
      "uuid": "ada-uuid",
      "agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "teamguid": null,
      "title": "My Instagram Bot",
      "description": null,
      "cover": null,
      "categories": ["social-media", "marketing"],
      "tier": "pro",
      "tiermultiplier": 3,
      "monthlypriceusd": 29,
      "monthlycredits": 5000,
      "extracredits": 2000,
      "usedcredits": 1450,
      "creditperiod": "2026-05",
      "creditsyncat": 1714694410,
      "status": 4,
      "pinned": true,
      "teamsessionmode": "",
      "setuprequired": false,
      "subscription": {
        "plan": "agent",
        "status": "active",
        "amount": 29,
        "currency": "usd",
        "currentperiodend": 1717200000,
        "renewaldate": "2026-06-01T00:00:00.000Z",
        "daysremaining": 62,
        "pendingdowngrade": null,
        "provider": "prepaid"
      },
      "agent": {
        "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "title": "Instagram Manager",
        "slug": "instagram-manager",
        "description": "An autonomous agent that manages your Instagram Business account.",
        "cover": "https://cdn.wiro.ai/uploads/agents/instagram-manager-cover.webp",
        "categories": ["social-media", "marketing"],
        "tiermultiplier": 3,
        "tiers": {
          "starter": { "priceUsd": 9, "credits": 1000 },
          "pro":     { "priceUsd": 29, "credits": 5000 }
        }
      },
      "extracreditsexpiry": 1730419200,
      "createdat": 1714608000,
      "updatedat": 1714694400,
      "queuedat": 1714694395,
      "startedat": 1714694400,
      "runningat": 1714694410,
      "stoppingat": null,
      "stopdat": null,
      "errordat": null
    }
  ]
}

POST /UserAgent/Detail

Retrieves full details for a single deployed agent instance, including subscription info.

Response

{
  "result": true,
  "errors": [],
  "useragents": [
    {
      "guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
      "uuid": "ada-uuid",
      "agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "teamguid": null,
      "title": "My Instagram Bot",
      "description": null,
      "cover": null,
      "categories": ["social-media", "marketing"],
      "tier": "pro",
      "tiermultiplier": 3,
      "status": 4,
      "pinned": true,
      "setuprequired": false,
      "teamsessionmode": "",
      "credentials": {
        "instagram": {
          "_connected": true,
          "optional": false,
          "extra": false,
          "_editable": {
            "authmethod": true,
            "igusername": true
          },
          "_schema": {
            "title": "Instagram",
            "icon": "https://wiro.ai/images/icons/credentials/instagram.svg",
            "brand_color": "#E4405F",
            "brand_text_color": "#FFFFFF",
            "brand_logo_filter": null,
            "docs_url": "/docs/integration-instagram-skills",
            "credential_mode": "oauth_or_api_key",
            "connection_modes": ["wiro", "own"],
            "wiro_connect_pending": true,
            "oauth_provider": "instagram",
            "fields": [
              { "key": "authmethod", "label": "Authentication Method", "type": "select", "required": true, "options": [{ "label": "Wiro-managed", "value": "wiro" }, { "label": "Own OAuth app", "value": "own" }], "default": "wiro" },
              { "key": "igusername", "label": "Instagram Username",   "type": "text",   "required": true, "placeholder": "@yourbusiness", "help": "Your Instagram Business account username (without the @)." }
            ]
          },
          "_required_missing": false,
          "authmethod": "wiro",
          "igusername": "mybrand",
          "connectedat": "2026-05-01T12:00:00.000Z",
          "tokenexpiresat": null
        },
        "sys-telegram": {
          "_connected": false,
          "optional": true,
          "extra": false,
          "_editable": {
            "bottoken":     true,
            "allowedusers": true,
            "sessionmode":  true
          },
          "_schema": {
            "title": "Telegram Bot",
            "icon": "https://wiro.ai/images/icons/credentials/telegram.svg",
            "brand_color": "#2AABEE",
            "brand_text_color": "#FFFFFF",
            "brand_logo_filter": null,
            "docs_url": "/docs/integration-telegram-skills",
            "credential_mode": "api_key",
            "connection_modes": ["api_key"],
            "wiro_connect_pending": false,
            "oauth_provider": null,
            "fields": [
              { "key": "bottoken",     "label": "Bot Token",                  "type": "password", "required": true,  "placeholder": "123456789:ABC-DEF1234ghIkl-zyx57W2v1u123ew11", "help": "Issued by @BotFather when you create the bot." },
              { "key": "allowedusers", "label": "Allowed Telegram User IDs",  "type": "text",     "required": false, "placeholder": "[\"761381461\", \"823901274\"]", "help": "JSON array of Telegram user / chat IDs that may DM the bot. Empty = open to anyone." },
              { "key": "sessionmode",  "label": "Session Mode",               "type": "select",   "required": true,  "options": [{ "label": "Private (one session per user)", "value": "private" }, { "label": "Group (one session per chat)", "value": "group" }], "default": "private" }
            ]
          },
          "_required_missing": false,
          "bottoken": "",
          "allowedusers": "",
          "sessionmode": "private"
        },
        "wordpress": {
          "_connected": false,
          "optional": false,
          "extra": false,
          "_editable": {
            "siteurl":         true,
            "username":        true,
            "applicationpass": true
          },
          "_schema": {
            "title": "WordPress",
            "icon": "https://wiro.ai/images/icons/credentials/wordpress.svg",
            "brand_color": "#21759B",
            "brand_text_color": "#FFFFFF",
            "brand_logo_filter": null,
            "docs_url": "/docs/integration-wordpress-skills",
            "credential_mode": "api_key",
            "connection_modes": ["api_key"],
            "wiro_connect_pending": false,
            "oauth_provider": null,
            "fields": [
              { "key": "siteurl",         "label": "Site URL",             "type": "text",     "required": true, "placeholder": "https://blog.example.com", "pattern": "^https?://.+" },
              { "key": "username",        "label": "Username",             "type": "text",     "required": true, "placeholder": "wp-editor" },
              { "key": "applicationpass", "label": "Application Password", "type": "password", "required": true, "placeholder": "xxxx xxxx xxxx xxxx xxxx xxxx", "help": "Generate from WP Admin → Users → Profile → Application Passwords." }
            ]
          },
          "_required_missing": true,
          "siteurl": "",
          "username": "",
          "applicationpass": ""
        }
      },
      "customskills": [
        {
          "key": "cs-content-tone",
          "description": "Brand voice + posting rules read by every content-generation skill on this agent.",
          "value": "## Brand Voice\nTone: friendly, casual, never salesy.\nTarget Audience: indie devs and side-project builders.\n\n## Hashtag Strategy\nMax 3 per post. Always include #BuildInPublic and #Indie.\n\n## Platform Rules\n- Instagram: square images only, carousels for tutorials.\n- Twitter: thread format for posts longer than 200 chars.",
          "enabled": true,
          "interval": null,
          "_source": "preset-strategy",
          "_editable": true,
          "_edited": true
        },
        {
          "key": "cs-content-sources",
          "description": "RSS / sitemap URLs the agent should poll for new content ideas.",
          "value": "## Primary Sources\nhttps://blog.example.com/feed.xml\nhttps://news.ycombinator.com/rss\n\n## CTA URL Pattern\nhttps://example.com/posts/{slug}",
          "enabled": true,
          "interval": null,
          "_source": "preset-strategy",
          "_editable": true,
          "_edited": false
        }
      ],
      "scheduledskills": [
        {
          "key": "cs-cron-content-scanner",
          "description": "Polls the content sources every 4 hours and queues fresh ideas for the post generator.",
          "value": "Scan the configured RSS / sitemap sources, dedupe against last 14 days, and queue up to 3 fresh items into the post pipeline.",
          "enabled": true,
          "interval": "0 */4 * * *",
          "_source": "skill-bundle",
          "_editable": true,
          "_edited": false
        },
        {
          "key": "cs-cron-weekly-roundup",
          "description": "User-created weekly summary cron that publishes a Monday recap to WordPress.",
          "value": "Every Monday at 09:00 UTC, summarize last week's published posts (titles + engagement) and publish the recap as a WordPress post.",
          "enabled": true,
          "interval": "0 9 * * 1",
          "_source": "user-created",
          "_editable": true,
          "_edited": false,
          "_user_created": true
        }
      ],
      "skills": [
        { "name": "int-instagram-post", "enabled": true, "_edited": false, "_user_created": false },
        { "name": "int-twitterx-post",  "enabled": true, "_edited": true,  "_user_created": false },
        { "name": "int-wiro-generator", "enabled": true, "_edited": false, "_user_created": false }
      ],
      "skillsmeta": {
        "int-instagram-post": {
          "name": "int-instagram-post",
          "title": "Instagram — Post & Stories",
          "icon": "https://wiro.ai/images/icons/skills/instagram.svg",
          "brand_color": "#E4405F",
          "brand_text_color": "#FFFFFF",
          "brand_logo_filter": null,
          "category": "int",
          "docs_url": "/docs/integration-instagram-skills",
          "credential_key": "instagram",
          "additional_credential_keys": [],
          "requires_credentials": true,
          "user_invocable": true,
          "deprecated": false,
          "replacement": null,
          "description": "Publish single-image, carousel, and story posts to a connected Instagram Business account."
        },
        "int-twitterx-post": {
          "name": "int-twitterx-post",
          "title": "X (Twitter) — Post & Reply",
          "icon": "https://wiro.ai/images/icons/skills/twitterx.svg",
          "brand_color": "#000000",
          "brand_text_color": "#FFFFFF",
          "brand_logo_filter": null,
          "category": "int",
          "docs_url": "/docs/integration-twitter-skills",
          "credential_key": "twitterx",
          "additional_credential_keys": [],
          "requires_credentials": true,
          "user_invocable": true,
          "deprecated": false,
          "replacement": null,
          "description": "Compose tweets, threads, and replies on a connected X (Twitter) account."
        },
        "int-wiro-generator": {
          "name": "int-wiro-generator",
          "title": "Wiro Generator (platform-managed)",
          "icon": "https://wiro.ai/images/icons/skills/wiro.svg",
          "brand_color": "#33F2BC",
          "brand_text_color": "#0F1A24",
          "brand_logo_filter": null,
          "category": "int",
          "docs_url": null,
          "credential_key": "wiro",
          "additional_credential_keys": [],
          "requires_credentials": true,
          "user_invocable": false,
          "deprecated": false,
          "replacement": null,
          "description": "Internal: lets the agent call Wiro's own image / video / LLM generation API. Other skills invoke it; users do not."
        }
      },
      "monthlycredits": 5000,
      "monthlypriceusd": 29,
      "extracredits": 2000,
      "usedcredits": 1450,
      "remainingcredits": 5550,
      "creditperiod": "2026-05",
      "creditsyncat": 1714694410,
      "peractioncosts": {
        "message":    10,
        "create":     60,
        "modify":     20,
        "regenerate": 20
      },
      "subscription": {
        "plan": "agent",
        "status": "active",
        "amount": 29,
        "currency": "usd",
        "currentperiodend": 1717200000,
        "renewaldate": "2026-06-01T00:00:00.000Z",
        "daysremaining": 28,
        "pendingdowngrade": null,
        "provider": "prepaid"
      },
      "agent": {
        "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "title": "Instagram Manager",
        "slug": "instagram-manager",
        "headline": "Automate your Instagram presence with AI",
        "description": "An autonomous agent that manages your Instagram Business account: drafts posts from your RSS feeds, schedules carousels, and replies to DMs.",
        "cover": "https://cdn.wiro.ai/uploads/agents/instagram-manager-cover.webp",
        "icon": "https://cdn.wiro.ai/uploads/agents/instagram-manager-icon.webp",
        "categories": ["social-media", "marketing"],
        "tiermultiplier": 3,
        "tiers": {
          "starter": { "priceUsd": 9,  "credits": 1000 },
          "pro":     { "priceUsd": 29, "credits": 5000 }
        },
        "extracreditpacks": [
          { "packkey": "small",  "credits": 25000,  "priceusd": 130, "enabled": true },
          { "packkey": "medium", "credits": 50000,  "priceusd": 240, "enabled": true },
          { "packkey": "large",  "credits": 100000, "priceusd": 420, "enabled": true }
        ]
      },
      "extracreditsexpiry": 1730419200,
      "createdat": 1714608000,
      "updatedat": 1714694400,
      "queuedat": 1714694395,
      "startedat": 1714694400,
      "runningat": 1714694410,
      "stoppingat": null,
      "stopdat": null,
      "errordat": null
    }
  ]
}

POST /UserAgent/Update

Updates an agent instance's scalar fields only (title, description, categories, cover URL). If the agent is currently starting (status 3) or running (status 4), this triggers an automatic restart to apply the new settings (the agent is moved to Stopping with restartafter: true, and re-queued after it fully stops).

Response

{
  "result": true,
  "errors": [],
  "useragents": [
    {
      "guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
      "uuid": "ada-uuid",
      "agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "teamguid": null,
      "title": "My Instagram Bot",
      "description": "Updated description after rename",
      "cover": "https://cdn.wiro.ai/uploads/useragents/f8e7d6c5-cover.webp",
      "categories": ["social-media", "marketing"],
      "tier": "starter",
      "tiermultiplier": 3,
      "monthlypriceusd": 9,
      "monthlycredits": 1000,
      "extracredits": 0,
      "usedcredits": 320,
      "creditperiod": "2026-05",
      "creditsyncat": 1714694400,
      "status": 1,
      "pinned": false,
      "setuprequired": false,
      "teamsessionmode": "",
      "agent": {
        "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "title": "Instagram Manager",
        "slug": "instagram-manager",
        "headline": "Automate your Instagram presence with AI",
        "description": "An autonomous agent that manages your Instagram Business account.",
        "cover": "https://cdn.wiro.ai/uploads/agents/instagram-manager-cover.webp",
        "icon": "https://cdn.wiro.ai/uploads/agents/instagram-manager-icon.webp",
        "categories": ["social-media", "marketing"],
        "tiermultiplier": 3,
        "tiers": {
          "starter": { "priceUsd": 9,  "credits": 1000 },
          "pro":     { "priceUsd": 29, "credits": 5000 }
        },
        "extracreditpacks": []
      },
      "createdat": 1714608000,
      "updatedat": 1714694500,
      "queuedat": 1714694498,
      "startedat": null,
      "runningat": null,
      "stoppingat": 1714694500,
      "stopdat": null,
      "errordat": null
    }
  ]
}

POST /UserAgent/Cover

Uploads a new cover image for the agent instance via multipart. Mirrors the /User/Avatar pattern — accepts jpg, png, gif, jpeg, webp; converts to webp; uploads to S3; writes the resulting CDN URL into useragents.cover.

If you already have a hosted URL, use POST /UserAgent/Update with cover: "<url>" instead.

Multipart fields:

Response

{
  "result": true,
  "errors": [],
  "cover": "https://cdn.wiro.ai/uploads/useragents/f8e7d6c5-b4a3-2190-fedc-ba0987654321-cover.webp",
  "useragents": [
    {
      "guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
      "uuid": "ada-uuid",
      "agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "teamguid": null,
      "title": "My Instagram Bot",
      "description": null,
      "cover": "https://cdn.wiro.ai/uploads/useragents/f8e7d6c5-b4a3-2190-fedc-ba0987654321-cover.webp",
      "categories": ["social-media", "marketing"],
      "tier": "starter",
      "tiermultiplier": 3,
      "monthlypriceusd": 9,
      "monthlycredits": 1000,
      "extracredits": 0,
      "usedcredits": 320,
      "creditperiod": "2026-05",
      "creditsyncat": 1714694400,
      "status": 4,
      "pinned": false,
      "teamsessionmode": "",
      "agent": {
        "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "title": "Instagram Manager",
        "slug": "instagram-manager",
        "headline": "Automate your Instagram presence with AI",
        "description": "An autonomous agent that manages your Instagram Business account.",
        "cover": "https://cdn.wiro.ai/uploads/agents/instagram-manager-cover.webp",
        "icon": "https://cdn.wiro.ai/uploads/agents/instagram-manager-icon.webp",
        "categories": ["social-media", "marketing"],
        "tiermultiplier": 3
      },
      "createdat": 1714608000,
      "updatedat": 1714694500,
      "queuedat": 1714694395,
      "startedat": 1714694400,
      "runningat": 1714694410,
      "stoppingat": null,
      "stopdat": null,
      "errordat": null
    }
  ]
}

POST /UserAgent/CredentialUpsert

For credential field history — see CredentialFieldHistory on the Agent Credentials page.

Writes one or more credential fields for a single or multiple providers in one call.

If the agent is starting or running, completing the upsert triggers an automatic restart (restartafter: true).

Each field row:

Request

curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
    "fields": [
      { "credentialkey": "wordpress", "fieldname": "url",         "fieldvalue": "https://myblog.com" },
      { "credentialkey": "wordpress", "fieldname": "user",        "fieldvalue": "admin" },
      { "credentialkey": "wordpress", "fieldname": "apppassword", "fieldvalue": "abcd efgh ijkl mnop" }
    ]
  }'

Response

{ "result": true, "applied": 3, "errors": [] }

applied is the number of rows actually written. Any row that fails validation (reserved fieldname, invalid fieldstatus for your role) is skipped and reported in errors without rolling back the others.

POST /UserAgent/CustomSkillUpsert

Writes a single custom skill value (strategy text) or cron setting (enabled / interval).

Request

curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillUpsert" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
    "skillkey": "content-tone",
    "value": "## Brand Voice\nTone: friendly\nTarget Audience: teens on Instagram"
  }'

Response

{ "result": true, "errors": [] }

POST /UserAgent/CustomSkillRename

Renames a user-created custom skill, optionally updating its description in the same atomic write. Only rows with usercreated: true can be renamed through this endpoint — preset-owned rows reject with agent-customskill-rename-preset-forbidden (preset renames cascade through the admin /Agent/CustomSkillRename channel instead).

The skillkey flavour is preserved: a cs-cron-* scheduled task stays scheduled, a cs-* strategy stays a strategy. Cross-flavour renames are rejected — delete + re-create via CustomSkillUpsert with the right kind if you need to switch sections.

Version history is migrated under the new key so the full audit chain stays continuous after the rename, and a new rename entry is appended.

Request

curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillRename" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
    "oldskillkey": "cs-my-custom-strategy",
    "newskillkey": "cs-my-renamed-strategy",
    "description": "Updated note shown next to the name"
  }'

Response

{ "result": true, "errors": [], "newskillkey": "cs-my-renamed-strategy" }

Error cases

POST /UserAgent/CustomSkillDelete

Removes a user-created cron skill. Has no effect on preset strategies or bundled crons (those cannot be deleted through the API).

Response

{ "result": true, "errors": [] }

POST /UserAgent/CustomSkillHistory

Returns the version history for one custom skill on a useragent — a per-write audit trail with diff metadata + the resolved actor for each entry. Useful for building audit / change-log views in your dashboard.

Response

{
  "result": true,
  "errors": [],
  "preset_default": {
    "value": "## Brand Voice\nTone: friendly...",
    "intervalexpr": null,
    "enabled": true,
    "description": "How the agent should sound across all generated copy."
  },
  "entries": [
    {
      "guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
      "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
      "skillkey": "cs-content-tone",
      "operation": "upsert",
      "value": "## Brand Voice\nTone: friendly\n...",
      "intervalexpr": null,
      "enabled": true,
      "usercreated": false,
      "prev_value": "## Brand Voice\nTone: professional\n...",
      "prev_interval": null,
      "prev_enabled": true,
      "after_value": "## Brand Voice\nTone: friendly\n...",
      "after_interval": null,
      "after_enabled": true,
      "changed_fields": ["value"],
      "changedby": "ada-uuid",
      "changedby_user": {
        "uuid": "ada-uuid",
        "firstname": "Ada",
        "lastname": "Lovelace",
        "email": "[email protected]",
        "username": "ada",
        "avatar": "https://cdn.wiro.ai/avatars/ada.webp",
        "avatarinitials": "AL"
      },
      "changedat": 1714694410
    }
  ]
}

POST /UserAgent/CustomSkillRevert

Reverts a custom skill to either (a) the agent template's preset default or (b) a specific historical version. Auto-triggers a restart on success unless the action is a no-op.

Response

{
  "result": true,
  "errors": [],
  "action": "reverted",
  "current_value": "## Brand Voice\nTone: ...",
  "current_interval": null,
  "current_enabled": true
}

action is "reverted", "reset-to-preset", "deleted" (preset removed upstream), or "no-op" (already matches target).

POST /UserAgent/CredentialFieldHistory

Returns the per-field write history for one credential group on a useragent. Sensitive values are redacted at read time as a belt-and-suspenders guard:

• oauth_session fields (access / refresh tokens) never appear in history at all — they're stripped before persisting.
• clientsecret and similar oauth_app secret fields are stored as [REDACTED] in history rows (the live row carries the real secret — read it via UserAgent/Detail).
• Platform-only credentials (wiro, calendarific, sys-openai) short-circuit to an empty entries[] (no user-facing history to show).

Response

{
  "result": true,
  "errors": [],
  "entries": [
    {
      "guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
      "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
      "credentialkey": "instagram",
      "fieldname": "igusername",
      "fieldvalue": "myaccount",
      "fieldstatus": "user",
      "parentfield": null,
      "ordinal": 0,
      "operation": "upsert",
      "changedby": "ada-uuid",
      "changedby_user": {
        "uuid": "ada-uuid",
        "firstname": "Ada",
        "lastname": "Lovelace",
        "email": "[email protected]",
        "username": "ada",
        "avatar": "https://cdn.wiro.ai/avatars/ada.webp",
        "avatarinitials": "AL"
      },
      "changedat": 1714694410
    },
    {
      "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
      "credentialkey": "instagram",
      "fieldname": "clientsecret",
      "fieldvalue": "[REDACTED]",
      "fieldstatus": "oauth_app",
      "parentfield": null,
      "ordinal": 0,
      "operation": "upsert",
      "changedby": "ada-uuid",
      "changedby_user": {
        "uuid": "ada-uuid",
        "firstname": "Ada",
        "lastname": "Lovelace",
        "email": "[email protected]",
        "username": "ada",
        "avatar": "https://cdn.wiro.ai/avatars/ada.webp",
        "avatarinitials": "AL"
      },
      "changedat": 1714600000
    }
  ]
}

changedby_user is the resolved actor object (uuid, firstname, lastname, email, username, avatar, avatarinitials). It is null when changedby is "system" (automation / cron) or when the user record has been deleted.

POST /UserAgent/SkillsApply

Applies a batch of skill toggles + an optional tier change in a single transactional unit. This is the only skill-toggle endpoint API consumers should use — even when you're flipping a single skill, send it as a one-entry skills map. The single-skill alternative (SkillToggle) is not part of the public API surface.

Designed for both the Skill Editor modal (multiple toggles in one save) and one-off API mutations:

1. Charges the wallet (or proration) once, not N times.
2. Triggers exactly one container restart after all toggles land.
3. Uses idempotency + a UA-level mutex — concurrent calls or FE retries can't double-apply.
4. Atomic — a payment-side failure rolls back to the pre-call skill set.

Request

curl -X POST "https://api.wiro.ai/v1/UserAgent/SkillsApply" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
    "tier": "pro",
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
    "skills": {
      "int-instagram-post": true,
      "int-twitterx-post":  true,
      "int-wordpress-post":  false
    }
  }'

Response (success)

{
  "result": true,
  "errors": [],
  "tier": "pro",
  "stripeProrationApplied": false,
  "prepaidWalletDelta": 19.99,
  "restartTriggered": true,
  "restartedAt": 1714694520,
  "pricing": {
    "previousPriceUsd": 9,
    "newPriceUsd": 39,
    "deltaUsd": 30,
    "previousMonthlyCredits": 1000,
    "newMonthlyCredits": 6000,
    "deltaCredits": 5000,
    "enabledSkills": ["int-instagram-post", "int-twitterx-post", "int-wiro-generator"],
    "peractioncosts": { "message": 10, "create": 60, "modify": 20, "regenerate": 20 }
  }
}

Common error codes

POST /UserAgent/PricingPreview

Live tier-pricing preview. Drives the Build Your Agent / Skill Editor UI: as the user toggles skills on/off, the frontend POSTs here with skillOverrides to see "if I save this, my new monthly price would be $X with Y monthly credits" without writing any state.

Two body shapes:

A. Draft preview (custom builder, no useragent yet)

{
  "draft": true,
  "tier": "pro",
  "skills": ["int-instagram-post", "int-wiro-generator"]
}

B. Existing useragent preview

{
  "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
  "tier": "pro",
  "skillOverrides": {
    "int-instagram-post": true,
    "int-wordpress-post": false
  }
}

Response

{
  "result": true,
  "errors": [],
  "tier": "pro",
  "tiermultiplier": 3,
  "totalPriceUsd": 14,
  "totalMonthlyCredits": 1500,
  "peractioncosts": { "message": 10, "create": 60, "modify": 20, "regenerate": 20 },
  "skillBreakdown": [
    { "skill": "int-instagram-post", "priceUsd": 5, "credits": 500, "actionCostOverrides": { "create": 60 } },
    { "skill": "int-wiro-generator", "priceUsd": 0, "credits": 0,   "actionCostOverrides": {} }
  ],
  "enabledSkills": ["int-instagram-post", "int-wiro-generator"],
  "directSkills":  ["int-instagram-post"],
  "agentBase": { "priceUsd": 9, "credits": 1000 },
  "tiers": {
    "starter": { "priceUsd": 9,  "credits": 1000 },
    "pro":     { "priceUsd": 14, "credits": 1500 }
  }
}

enabledSkills is the full closure (including transitive depends_on); directSkills is just what the user explicitly toggled.

POST /UserAgent/CreateSubscriptionCheckout

Subscribes a useragent that doesn't yet have an active subscription. Wallet is debited, a prepaid subscription row is inserted, and the agent is auto-queued — same single-call behaviour as Deploy with useprepaid: true. Always pass useprepaid: true from the API.

Response

{
  "result": true,
  "errors": [],
  "subscriptionId": 8421,
  "monthlypriceusd": 29,
  "monthlycredits": 5000
}

If the useragent already has an active subscription, the call rejects with Subscription already active for this useragent. Cancel or modify the existing subscription instead.

POST /UserAgent/Start

Starts a stopped agent instance. The agent is moved to Queued (status 2) and picked up by a worker. Also valid for agents in Error state (5) — Start re-queues them for another launch attempt.

Response

{
  "result": true,
  "errors": []
}

Start will fail with a descriptive error if:

• The agent is already running or queued
• The agent is currently stopping
• Setup is incomplete (status 6)
• No active subscription exists
• No credits remain (monthly or extra)

POST /UserAgent/Stop

Stops a running agent instance. If the agent is Queued (status 2), it is immediately set to Stopped. If it is Starting or Running (status 3/4), it moves to Stopping (status 1) and the container is shut down gracefully.

Response

{
  "result": true,
  "errors": []
}

POST /UserAgent/Pin

Pins or unpins an agent instance from the user's pinned-agents quick list. Pinned agents appear in the global header dropdown (PinnedAgents) and get an unread badge from PinnedUnread.

Response

{ "result": true, "errors": [] }

POST /UserAgent/PinnedAgents

Lists the user's pinned agents. Returns the same composed shape as MyAgents — every field that appears on a MyAgents row appears here, just filtered to pinned: true.

No request body fields are required — the caller's tokenUUID (or active teamGUID header) scopes the response.

Response

{
  "result": true,
  "errors": [],
  "useragents": [
    {
      "guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
      "uuid": "ada-uuid",
      "agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "teamguid": null,
      "title": "My Instagram Bot",
      "description": null,
      "cover": null,
      "categories": ["social-media", "marketing"],
      "tier": "pro",
      "tiermultiplier": 3,
      "monthlypriceusd": 29,
      "monthlycredits": 5000,
      "extracredits": 2000,
      "usedcredits": 1450,
      "creditperiod": "2026-05",
      "creditsyncat": 1714694410,
      "status": 4,
      "pinned": true,
      "teamsessionmode": "",
      "setuprequired": false,
      "subscription": {
        "plan": "agent",
        "status": "active",
        "amount": 29,
        "currency": "usd",
        "currentperiodend": 1717200000,
        "renewaldate": "2026-06-01T00:00:00.000Z",
        "daysremaining": 28,
        "pendingdowngrade": null,
        "provider": "prepaid"
      },
      "agent": {
        "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "title": "Instagram Manager",
        "slug": "instagram-manager",
        "description": "An autonomous agent that manages your Instagram Business account.",
        "cover": "https://cdn.wiro.ai/uploads/agents/instagram-manager-cover.webp",
        "categories": ["social-media", "marketing"],
        "tiermultiplier": 3,
        "tiers": {
          "starter": { "priceUsd": 9,  "credits": 1000 },
          "pro":     { "priceUsd": 29, "credits": 5000 }
        }
      },
      "extracreditsexpiry": 1730419200,
      "createdat": 1714608000,
      "updatedat": 1714694400,
      "queuedat": 1714694395,
      "startedat": 1714694400,
      "runningat": 1714694410,
      "stoppingat": null,
      "stopdat": null,
      "errordat": null
    }
  ]
}

POST /UserAgent/PinnedUnread

Returns the latest message GUID per pinned agent. Compare each lastmessageguid against the last value you saw client-side to draw an unread badge.

Response

{
  "result": true,
  "errors": [],
  "data": [
    { "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "lastmessageguid": "5c41dabf-f2be-4aa8-a5a4-8c9e3d2f3f11" },
    { "useragentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "lastmessageguid": null }
  ]
}

Extra Credit Packs

Pro-tier instances can buy additional credits at any time. Pack catalogs are derived per-useragent (5x / 10x / 20x of the instance's monthly allocation), so the catalog auto-scales when the user upgrades from Starter → Pro or toggles paid skills.

The catalog appears at agent.extracreditpacks on UserAgent/Detail:

"extracreditpacks": [
  { "packkey": "small",  "credits": 25000,  "priceusd": 130, "enabled": true },
  { "packkey": "medium", "credits": 50000,  "priceusd": 240, "enabled": true },
  { "packkey": "large",  "credits": 100000, "priceusd": 420, "enabled": true }
]

POST /UserAgent/CreateExtraCreditCheckout

Purchases additional credits for a useragent. The wallet is debited the pack price and credits are added to the instance immediately.

Request

{
  "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
  "pack": "medium",
  "useprepaid": true
}

Response (prepaid)

{
  "result": true,
  "errors": []
}

The pack price is deducted from your wallet and credits are added to the instance immediately. Credits expire 6 months after purchase. The transaction is appended to the agent ledger (type: "purchase", action: "<pack>", provider: "prepaid") and surfaced on POST /UserAgent/TransactionList.

POST /UserAgent/CancelSubscription

Schedules the subscription to end at the current billing period's expiry — a cancel-at-period-end pattern. The agent keeps running with the full plan allowance until that moment. No wallet refund is issued for the remaining days; you're paying for the full period up front.

Headers: Pass teamGUID: <team-guid> when the target agent belongs to a team project (the endpoint validates team context explicitly for all billing mutations).

Response

{
  "result": true,
  "cancelsAt": 1717200000,
  "errors": []
}

• cancelsAt is the Unix timestamp when the subscription will finish.
• Server-side, subscription.pendingdowngrade is flipped to "cancel" and subscription.status stays "active" until the period end. Subsequent UserAgent/Detail responses reflect this: subscription.pendingdowngrade = "cancel" and the usual currentperiodend.
• To reverse the cancellation before the period ends, call POST /UserAgent/RenewSubscription — it clears the flag without charging the wallet again.
• When the period actually ends, the daily cron marks the subscription "expired" and stops the agent (status: 0). At that point the user must call POST /UserAgent/RenewSubscription to pay for a new billing period (wallet charge), or redeploy from scratch.

Common errors

POST /UserAgent/UpgradeTier

Upgrades the active subscription from Starter → Pro. The capability surface stays the same; the tier change just scales the credit pool and price by tiermultiplier.

Upgrade-only. Pro → Starter downgrades are rejected with an explicit error — cancel and redeploy at the lower tier instead.

Headers: Pass teamGUID: <team-guid> when the target agent belongs to a team project.

When called against a prepaid subscription, the wallet is debited the prorated upgrade fee Math.max(0, ((P_pro − P_starter) / totalDays) × remainingDays) synchronously, the subscription + useragent are updated to Pro pricing / credits, and the agent is restarted to apply the new tier. Existing extra credits and usedcredits are preserved.

Response

{
  "result": true,
  "tier": "pro",
  "previousTier": "starter",
  "newPriceUsd": 29,
  "newMonthlyCredits": 5000,
  "proratedCharge": 11.33,
  "stripeProrationApplied": false,
  "errors": []
}

Common errors

POST /UserAgent/RenewSubscription

Two distinct operations share this endpoint depending on the subscription's current state:

1. Undo-cancel — active subscription with pendingdowngrade: "cancel" → clears the flag, no wallet charge.
2. Renew — subscription in "expired" status → creates a brand-new 30-day subscription, charges the wallet for the full plan price, resets the useragent to status: 0 (Stopped).

The endpoint inspects the current subscription state and picks the right operation; the caller doesn't choose.

Headers: Pass teamGUID: <team-guid> when the target agent belongs to a team project.

Response — undo-cancel

Called while the subscription is still "active" with a pending cancel flag set by CancelSubscription:

{
  "result": true,
  "action": "undo-cancel",
  "errors": []
}

• Clears subscription.pendingdowngrade back to null.
• No wallet charge — you've already paid for the full period.
• Agent status is unchanged (still running / stopped / whatever it was).

Response — renew

Called after the subscription has expired (daily cron flipped it to status: "expired" and stopped the agent). The renewal rolls the existing expired subscription forward into a fresh 30-day active row instead of inserting a new one:

{
  "result": true,
  "action": "renewed",
  "plan": "agent",
  "amount": 9,
  "monthlycredits": 1000,
  "errors": []
}

• Updates the subscriptions row in place: status: "active", type: "renewal", currentperiodstart: now, currentperiodend: now + 30 days, pendingdowngrade: null.
• Debits amount (the snapshot monthlypriceusd) from the wallet (caller's personal wallet, or the agent's team wallet if the agent is team-scoped).
• Zeroes usedcredits and stamps the new creditperiod. Existing extra credits are preserved.
• If the agent was in status: 0 (Stopped) or 5 (Error), it's auto-queued back to 2 (Queued) — the runtime picks it up on the next cycle, no extra Start call needed. Statuses 1/2/3/4 are mid-flight and settle on their own.

Common errors

Full subscription lifecycle (prepaid)

                  Deploy (wallet charged, period starts)
                         │
                         ▼
              ┌────────────────────────┐
              │ status: "active"       │
              │ pendingdowngrade: null │◄──────── RenewSubscription
              └───────────┬────────────┘          (undo-cancel, no charge)
                          │                       ▲
                          │ CancelSubscription    │
                          ▼                       │
              ┌────────────────────────┐          │
              │ status: "active"       │──────────┘
              │ pendingdowngrade:      │
              │   "cancel"             │
              └───────────┬────────────┘
                          │ currentperiodend reached
                          │ (daily cron)
                          ▼
              ┌────────────────────────┐
              │ status: "expired"      │
              │ useragent.status: 0    │◄───┐
              └───────────┬────────────┘    │
                          │                 │
                          │ RenewSubscription (wallet charged,
                          │ new 30-day period, useragent stays 0)
                          ▼                 │
              ┌────────────────────────┐    │
              │ NEW subscription row   │────┘
              │ status: "active"       │
              │ type: "renewal"        │
              └────────────────────────┘

Credit Transactions

Every credit balance change (agent usage, subscription renewal, extra-credit purchase, refund, admin adjustment, cancellation) is appended to an immutable ledger. Full reference + extended examples on the dedicated Agent Transactions page; the endpoint is summarised below for convenience.

POST /UserAgent/TransactionList

Returns the ledger rows for a single useragent sorted newest-first plus a snapshot summary of the current balance.

Response

{
  "result": true,
  "errors": [],
  "total": 128,
  "summary": {
    "monthlycredits": 5000,
    "extracredits": 2000,
    "usedcredits": 1450,
    "remainingcredits": 5550,
    "creditperiod": "2026-05",
    "creditsyncat": 1714694410
  },
  "transactions": [
    {
      "guid": "7f3e8c21-1be1-4f5a-96e8-2b1a9e2a6a01",
      "type": "deduct",
      "action": "message",
      "amount": -10,
      "balanceafter": 5550,
      "description": "Agent action: message",
      "sessionkey": "default",
      "messageguid": "5c41dabf-f2be-4aa8-a5a4-8c9e3d2f3f11",
      "provider": "agent",
      "providerref": null,
      "metadata": null,
      "uuid": "ada-uuid",
      "user": {
        "uuid": "ada-uuid",
        "firstname": "Ada",
        "lastname": "Lovelace",
        "email": "[email protected]",
        "username": "ada",
        "avatar": "https://cdn.wiro.ai/avatars/ada.webp",
        "avatarinitials": "AL"
      },
      "createdat": 1714694400
    },
    {
      "guid": "a40b5473-aedb-47d7-966b-7b038eed30dc",
      "type": "purchase",
      "action": "small",
      "amount": 5000,
      "balanceafter": 5560,
      "description": "Extra credits — small pack",
      "provider": "prepaid",
      "providerref": null,
      "metadata": { "pack": "small", "priceUsd": 45 },
      "uuid": "ada-uuid",
      "user": {
        "uuid": "ada-uuid",
        "firstname": "Ada",
        "lastname": "Lovelace",
        "email": "[email protected]",
        "username": "ada",
        "avatar": "https://cdn.wiro.ai/avatars/ada.webp",
        "avatarinitials": "AL"
      },
      "createdat": 1714692800
    },
    {
      "guid": "312e2a5f-1002-4c9a-af7d-70571e8b1739",
      "type": "renewal",
      "action": "monthly",
      "amount": 5000,
      "balanceafter": 3560,
      "description": "Subscription renewal",
      "provider": "prepaid",
      "providerref": null,
      "metadata": { "period": "2026-05", "priceUsd": 29 },
      "uuid": "system",
      "user": null,
      "createdat": 1714608000
    }
  ]
}

Summary fields mirror the flat useragent balance: monthlycredits, extracredits, usedcredits, remainingcredits = max(0, monthlycredits + extracredits - usedcredits), creditperiod (the 'YYYY-MM' billing window), and creditsyncat (Unix seconds of the last agent → API usage sync, null before the first report).

Transaction fields

Access: owner uuid or any team member of the useragent's team. Admin callers bypass the uuid check. Events are append-only — there is no delete endpoint, and the ledger guid is used server-side to deduplicate retries.

Pricing Summary

Payment Method

All API subscriptions use your prepaid wallet balance. The cost is deducted immediately when you deploy, renew, upgrade, or buy an extra credit pack. Always pass useprepaid: true on Deploy, CreateSubscriptionCheckout, and CreateExtraCreditCheckout — that's the only path designed for API consumers. Make sure your wallet balance covers the upfront tier price before calling these endpoints; otherwise you'll get an Insufficient wallet balance error.

Credit Consumption

Credits are consumed by the agent runtime (container) as it processes messages and generates content — not at Message/Send time. The peractioncosts object on the useragent declares how many credits each action burns; the container reports usage back to Wiro asynchronously through POST /UserAgent/CreditSync (and per-deduction via POST /UserAgent/TransactionInsert), which updates usedcredits and derives the live remainingcredits = max(0, monthlycredits + extracredits - usedcredits).

The API-side check is gating only: POST /UserAgent/Start and POST /UserAgent/Message/Send refuse to launch / accept messages when remainingcredits <= 0. During an active session, monthly credits are consumed first; once usedcredits >= monthlycredits, extra credits (purchased via CreateExtraCreditCheckout) absorb the rest. When both pools are empty, the agent responds [SYSTEM_CREDIT_LIMIT_REACHED] and stops processing further actions.

On each billing cycle (subscription renewal) usedcredits is reset to zero and creditperiod advances to the new 'YYYY-MM' window; extra-credit purchases simply bump extracredits without resetting usage. For the full audit trail (every credit deduct / grant / purchase / renewal / cancel) call POST /UserAgent/TransactionList — see Agent Transactions.

Error Messages

Agent-specific errors you may encounter:

What's Next

• Agent Builder — Build custom agents from scratch (custom: true) with live pricing previews and skill picker
• Agent Skills — Configure preferences, scheduled tasks, and skill toggles. Includes the registry browser endpoints (Skills/List, Skills/Detail, Skills/Capabilities)
• Agent Credentials — Integration catalog hub plus the registry endpoints (Credentials/List, Credentials/Detail)
• Agent Messaging — Send messages and receive responses from running agents
• Agent WebSocket — Real-time response streaming
• Agent Webhooks — Receive agent responses via HTTP callbacks
• Agent Transactions — Per-instance credit ledger (deductions, renewals, purchases, grants, refunds)
• Agent Logs — Per-instance activity feed (tool calls, cron runs, message exchanges)
• Authentication — API key setup and authentication methods

How It Works

Agent messaging follows the same async pattern as model runs:

1. Send a message via REST → get an agenttoken immediately
2. Subscribe to WebSocket with the agenttoken → receive streaming response chunks
3. Or poll via the Detail endpoint to check status and fetch the completed response
4. Or set a callbackurl to receive a webhook notification when the agent finishes

This decoupled design means your application never blocks waiting for the agent to think. Send the message, hand the agenttoken to your frontend, and stream the response as it arrives.

Message Lifecycle

Every agent message progresses through a defined set of stages:

Message Statuses

POST /UserAgent/Message/Send

Sends a user message to a deployed agent. The agent must be in running state (status 4). Returns immediately with an agenttoken that you use to track the response via WebSocket, polling, or webhook.

Response

{
  "result": true,
  "errors": [],
  "messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
  "status": "agent_queue"
}

POST /UserAgent/Message/Detail

Retrieves the current status and content of a single message. You can query by either messageguid or agenttoken.

Response

{
  "result": true,
  "errors": [],
  "data": {
    "guid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "uuid": "ada-uuid",
    "agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
    "user": {
      "uuid": "ada-uuid",
      "firstname": "Ada",
      "lastname": "Lovelace",
      "email": "[email protected]",
      "username": "ada",
      "avatar": "https://cdn.wiro.ai/avatars/ada.webp",
      "avatarinitials": "AL"
    },
    "sessionkey": "default",
    "content": "What are the latest trends in AI?",
    "response": "Here are the key AI trends for 2026...",
    "debugoutput": "Here are the key AI trends for 2026...",
    "status": "agent_end",
    "metadata": {
      "type": "progressGenerate",
      "task": "Generate",
      "speed": "14.2",
      "speedType": "words/s",
      "elapsedTime": "8.1s",
      "tokenCount": 105,
      "wordCount": 118,
      "raw": "Here are the key AI trends for 2026...",
      "thinking": [],
      "answer": ["Here are the key AI trends for 2026..."],
      "isThinking": false
    },
    "attachments": [],
    "deletestatus": 0,
    "createdat": "1743350400",
    "startedat": "1743350401",
    "endedat": "1743350408"
  }
}

POST /UserAgent/Message/History

Retrieves conversation history for a specific agent and session. Messages are returned newest-first with cursor-based pagination.

Response

{
  "result": true,
  "errors": [],
  "data": {
    "messages": [
      {
        "guid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
        "uuid": "ada-uuid",
        "agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
        "user": {
          "uuid": "ada-uuid",
          "firstname": "Ada",
          "lastname": "Lovelace",
          "email": "[email protected]",
          "username": "ada",
          "avatar": "https://cdn.wiro.ai/avatars/ada.webp",
          "avatarinitials": "AL"
        },
        "content": "What are the latest trends in AI?",
        "response": "Here are the key AI trends for 2026...",
        "debugoutput": "Here are the key AI trends for 2026...",
        "status": "agent_end",
        "metadata": {
          "type": "progressGenerate",
          "task": "Generate",
          "speed": "14.2",
          "speedType": "words/s",
          "elapsedTime": "8.1s",
          "tokenCount": 105,
          "wordCount": 118,
          "raw": "Here are the key AI trends for 2026...",
          "thinking": [],
          "answer": ["Here are the key AI trends for 2026..."],
          "isThinking": false
        },
        "attachments": [],
        "deletestatus": 0,
        "createdat": "1743350400"
      },
      {
        "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "uuid": "ada-uuid",
        "agenttoken": "tQ4nL8vY1zMkRpWdH7cXjBg6sFhPmA",
        "user": {
          "uuid": "ada-uuid",
          "firstname": "Ada",
          "lastname": "Lovelace",
          "email": "[email protected]",
          "username": "ada",
          "avatar": "https://cdn.wiro.ai/avatars/ada.webp",
          "avatarinitials": "AL"
        },
        "content": "Tell me more about multimodal models",
        "response": "Multimodal models combine...",
        "debugoutput": "Multimodal models combine...",
        "status": "agent_end",
        "metadata": {},
        "attachments": [],
        "deletestatus": 0,
        "createdat": "1743350300"
      }
    ],
    "count": 2,
    "hasmore": false
  }
}

Pagination

Page 1 — most recent messages:

{
  "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
  "sessionkey": "default",
  "limit": 50
}

Page 2 — pass the last (oldest, smallest createdat) message's guid from page 1 as the before cursor:

{
  "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
  "sessionkey": "default",
  "limit": 50,
  "before": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

POST /UserAgent/Message/Sessions

Lists all conversation sessions for an agent. Returns each session's key, message count, last activity time, and the most recent message content.

Response

{
  "result": true,
  "errors": [],
  "data": {
    "sessions": [
      {
        "sessionkey": "default",
        "messagecount": "24",
        "updatedat": "1743350400",
        "lastmessage": "What are the latest trends in AI?"
      },
      {
        "sessionkey": "user-42-support",
        "messagecount": "8",
        "updatedat": "1743349200",
        "lastmessage": "How do I reset my password?"
      }
    ]
  }
}

POST /UserAgent/Message/DeleteSession

Deletes messages in the given session for the calling user. This action cannot be undone.

Scope: the API matches on useragentguid + sessionkey and the caller's uuid, so only messages the calling user sent/received in this session are removed. In collaborative team mode (teamsessionmode: "collaborative", Telegram group-shared sessions), other team members' messages in the same sessionkey remain intact — each member must call DeleteSession to clear their own share.

Response

{
  "result": true,
  "errors": []
}

POST /UserAgent/Message/Delete

Bulk-deletes one or more messages from a session, with per-side soft-delete semantics. Each item lets you choose whether to hide the user side of the bubble, the agent side, or both — supporting "delete just my message" / "delete only the response" / "delete the whole bubble" UX without losing the underlying record.

Each item:

Request

curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/Delete" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "useragentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "items": [
      { "messageguid": "c3d4e5f6-...", "side": "user" },
      { "messageguid": "d4e5f6a7-...", "side": "agent" },
      { "messageguid": "e5f6a7b8-...", "side": "both" }
    ]
  }'

Response

{ "result": true, "errors": [] }

The endpoint is best-effort across the items array — invalid messageguid rows or invalid side values are silently skipped. The call returns result: true even when zero rows were updated, so callers should refetch Message/History to confirm the new state.

POST /UserAgent/Message/Cancel

Cancels an in-progress message. Only messages in agent_queue, agent_start, or agent_output status can be cancelled. Messages that have already reached agent_end, agent_error, or agent_cancel cannot be cancelled.

Response

{
  "result": true,
  "errors": []
}

On success, the message status changes to agent_cancel in the database.

Behavior depends on when the cancel hits:

• If the message was already being processed by the agent bridge (status agent_start or agent_output), the bridge's abort handler fires: subscribed WebSocket clients receive an agent_cancel event, debugoutput / response are populated with the abort reason (typically "AbortError" or similar technical message — not guaranteed to be a fixed user-facing string), and the callbackurl webhook (if set) is triggered with status: "agent_cancel".
• If the message was still queued (status agent_queue) when cancelled, no processing attempt had started: the row is marked agent_cancel but response and debugoutput remain empty strings, no WebSocket agent_cancel event is broadcast, and no webhook is triggered.

When polling for the final state, check status === "agent_cancel" rather than relying on non-empty response / debugoutput (they may be empty for queued-state cancellations).

POST /UserAgent/Message/SystemInsert

Inserts a finished "system" message into the conversation history without running it through the agent. Used by the agent runtime, scheduled cron skills, and external chat-platform bridges (Telegram bot, Slack relay, push-notification webhooks) to drop a pre-rendered message into a session as if the agent had produced it. The endpoint never triggers a model call — the supplied content is written verbatim to agentmessages.response with status: "agent_end" and metadata: {"type":"system"}.

Response

{
  "result": true,
  "messageguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
  "sessionkey": "default",
  "errors": []
}

• messageguid is the inserted row's guid — use it to address the message later via Message/Detail or to thread replies.
• sessionkey echoes the resolved session (matters when the caller passed "auto" or omitted the field).
• The inserted row carries status: "agent_end" and metadata: {"type":"system"} so the chat UI renders it as a non-interactive system bubble (no retry / cancel affordances).

Session Management

Sessions let you maintain separate conversation threads with the same agent:

• Each sessionkey represents a separate conversation — the agent remembers context within a session
• The default session key is "default" if you don't specify one
• Use unique session keys per end-user for multi-tenant applications (e.g. "user-42", "customer-abc")
• Sessions persist across API calls — send the same sessionkey to continue a conversation
• Delete a session with /UserAgent/Message/DeleteSession to clear history and free resources

User A's conversation:

{
  "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
  "message": "Hello!",
  "sessionkey": "user-alice"
}

User B's separate conversation with the same agent:

{
  "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
  "message": "Hello!",
  "sessionkey": "user-bob"
}

Thinking & Answer Separation

Agent responses may include thinking blocks where the underlying model reasons through the problem before answering. The system automatically parses <think>...</think> tags and separates the output into structured arrays:

{
  "thinking": ["Let me analyze the user's question...", "The key factors are..."],
  "answer": ["Based on my analysis, here are the main points..."],
  "isThinking": false,
  "raw": "<think>Let me analyze the user's question...</think>Based on my analysis, here are the main points..."
}

• thinking — array of reasoning/chain-of-thought blocks. May be empty if the model doesn't use thinking.
• answer — array of response chunks. This is the content to show the user.
• isThinking — true while the model is still in a thinking phase (the <think> tag is open but not yet closed), false during the answer phase.
• raw — the full accumulated raw output text including think tags.

Each agent_output WebSocket event contains the full accumulated arrays up to that point — not just the new chunk. Simply replace your displayed content with the latest arrays. Use isThinking to show a "thinking" indicator in your UI while the model reasons.

Tracking a Message

There are three ways to track message progress after sending:

1. WebSocket (Recommended)

Connect to WebSocket and subscribe with the agenttoken for real-time streaming. Each agent_output event delivers the growing response as it's generated.

1. Subscribe to agent message updates:

{
  "type": "agent_info",
  "agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb"
}

2. Server confirms subscription with current status:

{
  "type": "agent_subscribed",
  "agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
  "status": "agent_queue",
  "result": true
}

3. Streaming output event (emitted multiple times — replace your displayed content with message.answer on each event):

{
  "type": "agent_output",
  "agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
  "message": {
    "type": "progressGenerate",
    "task": "Generate",
    "speed": "12.4",
    "speedType": "words/s",
    "elapsedTime": "3.2s",
    "tokenCount": 156,
    "wordCount": 42,
    "raw": "Here are the key AI trends...",
    "thinking": [],
    "answer": ["Here are the key AI trends..."],
    "isThinking": false
  },
  "result": true
}

4. Final event (agent_end — terminal):

{
  "type": "agent_end",
  "agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
  "message": {
    "type": "progressGenerate",
    "task": "Generate",
    "speed": "14.2",
    "speedType": "words/s",
    "elapsedTime": "8.1s",
    "tokenCount": 412,
    "wordCount": 115,
    "raw": "Here are the key AI trends for 2026...",
    "thinking": [],
    "answer": ["Here are the key AI trends for 2026..."],
    "isThinking": false
  },
  "result": true
}

2. Polling via Detail

If you don't need real-time streaming, poll POST /UserAgent/Message/Detail at regular intervals until the status reaches a terminal state (agent_end, agent_error, or agent_cancel).

3. Webhook Callback

Pass a callbackurl when sending the message. The system will POST the final result to your URL when the agent finishes (up to 3 retry attempts):

{
  "messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "status": "agent_end",
  "content": "What are the latest trends in AI?",
  "response": "Here are the key AI trends for 2026...",
  "debugoutput": "Here are the key AI trends for 2026...",
  "metadata": {
    "type": "progressGenerate",
    "task": "Generate",
    "speed": "14.2",
    "speedType": "words/s",
    "elapsedTime": "8.1s",
    "tokenCount": 105,
    "wordCount": 118,
    "raw": "Here are the key AI trends for 2026...",
    "thinking": [],
    "answer": ["Here are the key AI trends for 2026..."],
    "isThinking": false
  },
  "endedat": 1743350408
}

Payload delivered to your callbackurl. metadata is decoded into a JSON object.

Connection URL

wss://socket.wiro.ai/v1

Connect to this URL after calling the Message / Send endpoint. Use the agenttoken from the send response to subscribe to the agent session. This is the same WebSocket server used for model tasks — you can subscribe to both task events (task_info) and agent events (agent_info) on the same connection.

No API key or auth header is required on the WebSocket itself. Authorization is enforced via the agenttoken, which is issued by POST /UserAgent/Message/Send against your API key and is scoped to a single message run.

Connection Flow

1. Connect — open a WebSocket connection to wss://socket.wiro.ai/v1.
2. Receive welcome — the server pushes a one-shot connected frame confirming the upgrade.
3. Subscribe — send an agent_info frame with your agenttoken.
4. Receive agent_subscribed — the server acknowledges the subscribe and reports the current lifecycle status (plus any already-accumulated debugoutput).
5. Stream — listen for agent_start → many agent_output → agent_end / agent_error / agent_cancel.
6. Close — disconnect after a terminal event, or keep the socket open and subscribe to the next agenttoken.

1. Welcome frame (server → client)

Right after the WebSocket upgrade succeeds, the server sends this frame on its own. You don't request it; it arrives before you send anything.

{
  "type": "connected",
  "version": "1.0"
}

Use it as a signal that the socket is fully ready to receive a subscribe. Most clients can ignore the payload — the version field is informational.

2. Subscribe frame (client → server)

{
  "type": "agent_info",
  "agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb"
}

• type — must be the literal string "agent_info". Other values are ignored (the server routes by type; unknown types are silently dropped).
• agenttoken — the token returned by POST /UserAgent/Message/Send. Required. If missing or empty, the server responds with an error frame (see below).

3. Subscribe errors

If agenttoken is missing or blank, the server replies with:

{
  "type": "error",
  "message": "agenttoken-required",
  "result": false
}

The connection stays open — no disconnect. Fix the payload and resend.

Multi-session subscription

A single WebSocket connection can hold subscriptions to multiple agent sessions simultaneously. Send one agent_info frame per token; the server de-duplicates, so resending the same token is a no-op.

After this, every server-side event for either token is forwarded to this connection. All events carry the agenttoken field, so your handler can route them back to the right UI surface.

Typical use cases:

• Multi-tab chat clients that keep several live conversations.
• Dashboards watching several users' agents in parallel.
• Combining task streaming and agent streaming on the same connection — task_info and agent_info frames both map to the same connection's token list.

There is no unsubscribe frame. Tokens are cleaned up automatically when the connection closes.

Event Types

Frames flow in two directions. ↓ = server → client, ↑ = client → server.