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 returns a complete audio file, realtime TTS streams synthesized speech via WebSocket as it generates — enabling instant playback without waiting for the full audio to be produced.

No microphone is needed — you simply submit text and receive audio.

See the full documentation for complete details, audio format specification, and code examples in JavaScript, Python, and Node.js.

Overview

Realtime STT models transcribe audio in real time. Stream microphone audio via WebSocket and receive progressive text transcription as the user speaks — enabling live dictation, captioning, and transcription applications.

No audio playback is needed — you send microphone audio and receive text.

See the full documentation for complete details, audio format specification, and code examples in JavaScript, Python, and Node.js.

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

"Generate a photorealistic image of a mountain lake at golden hour"

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

Generate a video

"Create a 5-second cinematic video of a drone shot over mountains using Kling V3"

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

Find models

"What models are available for text-to-video?"

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

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 and Agent/Detail are catalog endpoints and do not require authentication. You can browse available agents without an API key.

Authenticated endpoints — All UserAgent/* endpoints (Deploy, MyAgents, Detail, Update, Start, Stop, CreateExtraCreditCheckout, CancelSubscription, UpgradePlan, RenewSubscription) 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), call POST /UserAgent/Update to provide them. 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": [
    {
      "id": 5,
      "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"],
      "pricing": {
        "starter": { "price": 9, "credits": 1000 },
        "pro": { "price": 29, "credits": 5000 }
      },
      "skills": ["post_image", "reply_comment", "schedule_post"],
      "status": 1,
      "createdat": "1711929600",
      "updatedat": "1714521600"
    }
  ]
}

POST /Agent/Detail

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

Response

{
  "result": true,
  "errors": [],
  "agents": [
    {
      "id": 5,
      "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"],
      "pricing": {
        "starter": { "price": 9, "credits": 1000 },
        "pro": { "price": 29, "credits": 5000 }
      },
      "skills": ["post_image", "reply_comment", "schedule_post"],
      "ratelimit": { "actionTypes": { "message": 10, "create": 5 } },
      "configuration": {
        "credentials": {
          "instagram": {
            "_editable": { "authMethod": true },
            "optional": false,
            "authMethod": "",
            "igUsername": "",
            "connectedAt": ""
          }
        }
      },
      "status": 1,
      "createdat": "1711929600",
      "updatedat": "1714521600"
    }
  ]
}

POST /UserAgent/Deploy

Creates a new agent instance from a catalog template. The agent is created with status 6 (Setup Required). After deploying, call UserAgent/Detail to see which credentials are needed, provide them via UserAgent/Update, then call UserAgent/Start to launch the agent. The subscription cost is deducted from your prepaid wallet immediately.

Request

POST /UserAgent/Deploy
{
  "agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "My Instagram Bot",
  "useprepaid": true,
  "plan": "starter"
}

Response

{
  "result": true,
  "errors": [],
  "useragents": [
    {
      "id": 47,
      "guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
      "agentid": 5,
      "title": "My Instagram Bot",
      "status": 6,
      "setuprequired": true,
      "subscription": {
        "plan": "agent-starter",
        "status": "active",
        "amount": 49,
        "currency": "usd",
        "provider": "prepaid"
      },
      "createdat": "1714608000",
      "updatedat": "1714608000"
    }
  ]
}

POST /UserAgent/MyAgents

Lists all agent instances deployed under your account.

Response

{
  "result": true,
  "errors": [],
  "useragents": [
    {
      "id": 47,
      "guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
      "agentid": 5,
      "title": "My Instagram Bot",
      "status": 4,
      "setuprequired": false,
      "subscription": {
        "plan": "agent-instagram-manager-pro",
        "status": "active",
        "amount": 29,
        "currency": "usd",
        "currentperiodend": 1717200000,
        "renewaldate": "2026-06-01T00:00:00.000Z",
        "daysremaining": 62,
        "pendingdowngrade": null,
        "provider": "prepaid"
      },
      "agent": {
        "id": 5,
        "title": "Instagram Manager",
        "slug": "instagram-manager",
        "cover": "https://cdn.wiro.ai/uploads/agents/instagram-manager-cover.webp",
        "categories": ["social-media", "marketing"],
        "pricing": {
          "starter": { "price": 9, "credits": 1000 },
          "pro": { "price": 29, "credits": 5000 }
        }
      },
      "extracredits": 0,
      "extracreditsexpiry": null,
      "createdat": "1714608000",
      "updatedat": "1714694400",
      "startedat": "1714694400",
      "runningat": "1714694410"
    }
  ]
}

POST /UserAgent/Detail

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

Response

{
  "result": true,
  "errors": [],
  "useragents": [
    {
      "id": 47,
      "guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
      "agentid": 5,
      "title": "My Instagram Bot",
      "status": 4,
      "setuprequired": false,
      "configuration": {
        "credentials": {
          "instagram": {
            "_editable": { "authMethod": true },
            "optional": false,
            "authMethod": "wiro",
            "igUsername": "myaccount",
            "connectedAt": "2025-04-01T12:00:00.000Z"
          }
        }
      },
      "subscription": {
        "plan": "agent-instagram-manager-pro",
        "status": "active",
        "amount": 29,
        "currency": "usd",
        "currentperiodend": 1717200000,
        "renewaldate": "2026-06-01T00:00:00.000Z",
        "daysremaining": 62,
        "pendingdowngrade": null,
        "provider": "prepaid"
      },
      "agent": {
        "id": 5,
        "title": "Instagram Manager",
        "slug": "instagram-manager",
        "cover": "https://cdn.wiro.ai/uploads/agents/instagram-manager-cover.webp",
        "pricing": {
          "starter": { "price": 9, "credits": 1000 },
          "pro": { "price": 29, "credits": 5000 }
        }
      },
      "extracredits": 2000,
      "extracreditsexpiry": 1730419200,
      "createdat": "1714608000",
      "updatedat": "1714694400",
      "startedat": "1714694400",
      "runningat": "1714694410"
    }
  ]
}

POST /UserAgent/Update

Updates an agent instance's configuration, title, description, or categories. If the agent is currently starting (status 3) or running (status 4), this triggers an automatic restart to apply the new settings.

Response

Returns the updated agent instance with setuprequired flag and agent summary. Does not include subscription — use UserAgent/Detail for the full view.

POST /UserAgent/Start

Starts a stopped agent instance. The agent is moved to Queued (status 2) and will be picked up by a worker.

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/CreateExtraCreditCheckout

Purchases additional credits for a Pro plan agent. Deducts from your prepaid wallet balance.

Request

POST /UserAgent/CreateExtraCreditCheckout
{
  "useragentGuid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
  "pack": "package2",
  "useprepaid": true
}

Response

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

Credits are added immediately from your wallet balance. url is null for prepaid purchases. Credits expire 6 months after purchase.

POST /UserAgent/CancelSubscription

Cancels a subscription at the end of the current billing period. The agent remains active until the period ends.

Response

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

The cancelsAt field is the Unix timestamp when the subscription will expire. The agent continues running until this date. You can reverse the cancellation by calling RenewSubscription before the period ends.

POST /UserAgent/UpgradePlan

Upgrades a Starter subscription to Pro. The prorated cost for the remaining days is deducted from your wallet.

Response

{
  "result": true,
  "plan": "agent-pro",
  "proratedCharge": 11.33,
  "newMonthlyCredits": 5000,
  "errors": []
}

Downgrades are not supported. To change from Pro to Starter, cancel and re-deploy.

POST /UserAgent/RenewSubscription

Renews an expired subscription or reverses a pending cancellation. The renewal cost is deducted from your wallet.

Response (renewal)

{
  "result": true,
  "action": "renewed",
  "plan": "agent-starter",
  "amount": 49,
  "errors": []
}

Response (undo cancel)

When called on an active subscription with a pending cancellation:

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

After renewal, the agent status is reset to 0 (Stopped). Call Start to launch it again. Monthly credits are refreshed for the new billing period.

Agent Pricing

Agent pricing is subscription-based, billed monthly. Two payment methods are available:

Each agent in the catalog defines its own pricing tiers in the pricing field. Check the Agent/Detail response for exact prices and credit amounts.

Payment Method

All subscriptions use your prepaid wallet balance. The cost is deducted immediately when you deploy or renew. Subscriptions renew automatically if your wallet has sufficient balance; otherwise the subscription expires. Manage subscriptions through the CancelSubscription, UpgradePlan, and RenewSubscription endpoints.

Credits are consumed per message or action, depending on the agent type. When monthly credits run out, the agent cannot be started until credits are renewed (next billing cycle) or extra credits are purchased.

Error Messages

Agent-specific errors you may encounter:

What's Next

• Agent Messaging — Send messages and receive responses from running agents
• Agent Credentials — Configure OAuth and API key credentials for your agent
• Authentication — API key setup and authentication methods
• Pricing — General pricing information

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": "user-uuid-here",
    "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": "{\"thinking\":[],\"answer\":[\"Here are the key AI trends for 2026...\"],\"raw\":\"Here are the key AI trends for 2026...\"}",
    "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",
        "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": "{}",
        "createdat": "1743350400"
      }
    ],
    "count": 1,
    "hasmore": false
  }
}

Pagination

// Page 1: most recent messages
POST /UserAgent/Message/History { "useragentguid": "...", "limit": 50 }

// Page 2: pass the last message's guid as cursor
POST /UserAgent/Message/History { "useragentguid": "...", "limit": 50, "before": "a1b2c3d4-..." }

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 a session and all its messages permanently. This action cannot be undone.

Response

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

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 and all subscribed WebSocket clients receive an agent_cancel event.

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": "...",
  "message": "Hello!",
  "sessionkey": "user-alice"
}

// User B's separate conversation with the same agent
{
  "useragentguid": "...",
  "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.

// Subscribe to agent message updates
{ "type": "agent_info", "agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb" }

// Server confirms subscription with current status
{ "type": "agent_subscribed", "agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb", "status": "agent_queue", "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):

// Webhook payload delivered to your callbackurl
{
  "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", "raw": "...", "thinking": [], "answer": ["..."] },
  "endedat": 1743350408
}

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 and agent events on the same connection.

Connection Flow

1. Connect — open a WebSocket connection to wss://socket.wiro.ai/v1
2. Subscribe — send an agent_info message with your agenttoken
3. Receive — listen for agent_output events as the agent streams its response
4. Complete — the agent_end event fires when the response is finished
5. Close — disconnect after processing the final response

Subscribe message format:

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

Event Types

Message Format

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

{
  "type": "agent_output",
  "agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
  "message": { ... },
  "result": true
}

The type field indicates the event. The message field varies by type — it's an empty string for lifecycle events, a structured progress object for output events, and a string or object for errors.

agent_subscribed

Sent immediately after the server accepts your subscription. The status field reflects where the agent currently is in its lifecycle.

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

agent_start

Signals that the agent has begun generating a response:

{
  "type": "agent_start",
  "agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
  "message": "",
  "result": true
}

agent_output (streaming)

Emitted multiple times as the agent generates its response. Each event contains the full accumulated text up to that point (not just the delta), along with real-time performance metrics:

{
  "type": "agent_output",
  "agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
  "message": {
    "type": "progressGenerate",
    "task": "Generate",
    "speed": "12.5",
    "speedType": "words/s",
    "elapsedTime": "2.4s",
    "tokenCount": 35,
    "wordCount": 28,
    "raw": "Here is the accumulated response text so far...",
    "thinking": [],
    "answer": ["Here is the accumulated response text so far..."],
    "isThinking": false
  },
  "result": true
}

The raw field contains the full response as a single string. The answer array contains the same text split into segments. To display streaming text, replace your UI content with raw (or join answer) on each event.

agent_end

Fires when the agent finishes responding. The structure is identical to agent_output — the message contains the final complete text with total metrics:

{
  "type": "agent_end",
  "agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
  "message": {
    "type": "progressGenerate",
    "task": "Generate",
    "speed": "14.2",
    "speedType": "words/s",
    "elapsedTime": "8.1s",
    "tokenCount": 156,
    "wordCount": 118,
    "raw": "The complete agent response text...",
    "thinking": [],
    "answer": ["The complete agent response text..."],
    "isThinking": false
  },
  "result": true
}

agent_error

An error occurred during processing. The message field can take two forms:

String error — a human-readable error description from exceptions:

{
  "type": "agent_error",
  "agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
  "message": "Could not resolve agent endpoint",
  "result": false
}

Common string errors include "Could not resolve agent endpoint", "OpenClaw returned HTTP 500", and "The operation was aborted.".

Structured error — when the model returns an invalid response (e.g. "..." or "Error: internal error"), the message contains the same progressGenerate object as agent_output:

{
  "type": "agent_error",
  "agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
  "message": {
    "type": "progressGenerate",
    "task": "Generate",
    "raw": "...",
    "thinking": [],
    "answer": ["..."],
    "isThinking": false
  },
  "result": false
}

Always check the type of message — handle both string and object forms in your client.

agent_cancel

Sent when the user cancels a message before the agent completes its response:

{
  "type": "agent_cancel",
  "agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
  "message": "The operation was aborted.",
  "result": false
}

The result Field

Every event includes a result boolean:

Use result to quickly determine whether the event represents a successful state. When result is false, inspect message for error details or cancellation context.

Streaming Metrics

Each agent_output and agent_end event includes real-time performance data in the message object:

These metrics update with every agent_output event, allowing you to display a live speed indicator or progress bar in your UI.

Thinking Model Support

When the agent is backed by a thinking-capable model (e.g. DeepSeek-R1, QwQ), the response may include thinking blocks alongside the answer:

{
  "type": "agent_output",
  "agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
  "message": {
    "type": "progressGenerate",
    "raw": "<think>Let me work through this step by step...</think>Based on my analysis...",
    "thinking": ["Let me work through this step by step..."],
    "answer": ["Based on my analysis..."],
    "isThinking": true
  },
  "result": true
}

Rendering guidance:

• While isThinking is true, show a "Thinking..." indicator or render the thinking text in a collapsible block.
• When isThinking becomes false, the model has finished reasoning and is now producing the answer.
• On agent_end, join the answer array for the final display text.

Full Integration Example

A typical integration follows this pattern: call the REST API to send a message, then subscribe via WebSocket to stream the response.

Step 1 — Send a message via REST:

curl -X POST https://api.wiro.ai/v1/UserAgent/Message/Send \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "useragentguid": "your-useragent-guid",
    "message": "Explain quantum computing in simple terms",
    "sessionkey": "user-42"
  }'

Step 2 — Subscribe via WebSocket:

const ws = new WebSocket('wss://socket.wiro.ai/v1');

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'agent_info',
    agenttoken: 'aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb'
  }));
};

Step 3 — Handle streaming events:

→  agent_subscribed  { status: "agent_queue" }
→  agent_start       { message: "" }
→  agent_output      { message: { raw: "Quantum", wordCount: 1 } }
→  agent_output      { message: { raw: "Quantum computing uses", wordCount: 3 } }
→  agent_output      { message: { raw: "Quantum computing uses qubits...", wordCount: 28 } }
→  agent_end         { message: { raw: "Quantum computing uses qubits that...", wordCount: 118 } }

Each agent_output contains the full accumulated text. Replace (don't append) your display content on each event.

Quick Reference

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

// agent_subscribed
{
  "type": "agent_subscribed",
  "agenttoken": "aB3xK9...",
  "status": "agent_queue",
  "debugoutput": "",
  "result": true
}

// agent_start
{
  "type": "agent_start",
  "agenttoken": "aB3xK9...",
  "message": "",
  "result": true
}

// agent_output (streaming — emitted multiple times)
{
  "type": "agent_output",
  "agenttoken": "aB3xK9...",
  "message": {
    "raw": "Accumulated text so far...",
    "thinking": [],
    "answer": ["Accumulated text so far..."],
    "isThinking": false,
    "speed": "12.5",
    "speedType": "words/s",
    "tokenCount": 35,
    "wordCount": 28
  },
  "result": true
}

// agent_end (final response)
{
  "type": "agent_end",
  "agenttoken": "aB3xK9...",
  "message": {
    "raw": "Complete response text...",
    "thinking": [],
    "answer": ["Complete response text..."],
    "isThinking": false,
    "speed": "14.2",
    "speedType": "words/s",
    "tokenCount": 156,
    "wordCount": 118
  },
  "result": true
}

// agent_error
{
  "type": "agent_error",
  "agenttoken": "aB3xK9...",
  "message": "Bridge timeout",
  "result": false
}

// agent_cancel
{
  "type": "agent_cancel",
  "agenttoken": "aB3xK9...",
  "message": "The operation was aborted.",
  "result": false
}

How It Works

When you send a message to an agent via POST /UserAgent/Message/Send, include a callbackurl parameter. Once the agent finishes processing — whether it completes successfully, encounters an error, or the message is cancelled — Wiro sends a POST request to your URL with the result.

This lets you build fully asynchronous workflows: fire a message and let your backend handle the response whenever it arrives, without polling or maintaining a WebSocket connection.

Setting a Callback URL

Include callbackurl in your message request body:

POST /UserAgent/Message/Send
{
  "useragentguid": "your-useragent-guid",
  "message": "What are today's trending topics?",
  "sessionkey": "user-123",
  "callbackurl": "https://your-server.com/webhooks/agent-response"
}

The callback URL is stored per-message. You can use different URLs for different messages, or omit it entirely if you prefer polling or WebSocket.

Callback Payload

When the agent finishes, Wiro sends a POST request to your callbackurl with Content-Type: application/json. The payload contains the complete message result including structured metadata:

Successful Completion (agent_end)

{
  "messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "status": "agent_end",
  "content": "What are today's trending topics?",
  "response": "Here are today's trending topics in tech...",
  "debugoutput": "Here are today's trending topics in tech...",
  "metadata": {
    "type": "progressGenerate",
    "task": "Generate",
    "speed": "14.2",
    "speedType": "words/s",
    "elapsedTime": "8.1s",
    "tokenCount": 156,
    "wordCount": 118,
    "raw": "Here are today's trending topics in tech...",
    "thinking": [],
    "answer": ["Here are today's trending topics in tech..."],
    "isThinking": false
  },
  "endedat": 1712050004
}

Error (agent_error)

{
  "messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "status": "agent_error",
  "content": "What are today's trending topics?",
  "response": "Could not resolve agent endpoint",
  "debugoutput": "Could not resolve agent endpoint",
  "metadata": {},
  "endedat": 1712050004
}

Cancelled (agent_cancel)

{
  "messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "status": "agent_cancel",
  "content": "What are today's trending topics?",
  "response": "The operation was aborted.",
  "debugoutput": "The operation was aborted.",
  "metadata": {},
  "endedat": 1712050004
}

Field Reference

The metadata Object

On successful completion (agent_end), the metadata object contains the structured response with thinking/answer separation and real-time metrics:

For agent_error and agent_cancel, metadata is an empty object {}. Always check status before accessing metadata fields.

Status Values

Retry Policy

Wiro attempts to deliver each webhook up to 3 times:

• First attempt is immediate when the agent finishes
• 2-second delay between retries
• Your endpoint must return HTTP 200 to acknowledge receipt
• Any non-200 response triggers a retry
• After 3 failed attempts, the webhook is abandoned and the failure is logged server-side

The message result is always persisted in the database regardless of webhook delivery. You can retrieve it at any time via POST /UserAgent/Message/Detail.

Security Considerations

• Webhook calls do not include authentication headers — verify incoming requests by checking the messageguid against your own records
• Always use HTTPS endpoints in production
• Validate the payload structure before processing
• Consider returning 200 immediately and processing the payload asynchronously to avoid timeouts

Code Examples

Below are complete webhook receiver implementations and a sample request with a callback URL. Select your language from the code panel.

Overview

After deploying an agent, call POST /UserAgent/Detail to see its full configuration. The response includes:

• configuration.credentials — which services the agent connects to and which fields are editable (_editable: true)
• configuration.custom_skills — configurable automated tasks the agent can run on a schedule
• setuprequired — whether credentials still need to be filled before the agent can start

Use this response to build your credential form or automate setup. Then update credentials and skills via POST /UserAgent/Update.

Two Types of Credentials

1. API Key credentials — set directly via POST /UserAgent/Update (Telegram, WordPress, Gmail, Brevo, etc.)
2. OAuth credentials — redirect-based authorization flow via POST /UserAgentOAuth/{Provider}Connect (Twitter, Instagram, Facebook, Google Ads, etc.)

Setting Credentials & Skills

Use POST /UserAgent/Update with configuration to set credentials and custom skills. You can update credentials, custom_skills, or both in a single request.

Request Format

POST /UserAgent/Update
{
  "guid": "your-useragent-guid",
  "configuration": {
    "credentials": {
      "<service>": {
        "<field>": "value"
      }
    },
    "custom_skills": [
      { "key": "skill-name", "enabled": true, "interval": "0 9 * * *" }
    ]
  }
}

Credential Configuration by Agent

Each agent requires different credentials. Select your agent below to see exactly which credentials to configure and the complete POST /UserAgent/Update request.

POST /UserAgent/Update
{
  "guid": "your-useragent-guid",
  "configuration": {
    "credentials": {
      "gmail": {
        "account": "[email protected]",
        "appPassword": "xxxx xxxx xxxx xxxx"
      },
      "telegram": {
        "botToken": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
        "allowedUsers": ["761381461"],
        "sessionMode": [
          { "value": "private", "text": "Private — each user has their own conversation", "selected": true },
          { "value": "collaborative", "text": "Collaborative — all users share the same conversation", "selected": false }
        ]
      }
    }
  }
}

POST /UserAgent/Update
{
  "guid": "your-useragent-guid",
  "configuration": {
    "credentials": {
      "wordpress": {
        "url": "https://blog.example.com",
        "user": "WiroBlogAgent",
        "appPassword": "xxxx xxxx xxxx xxxx"
      },
      "gmail": {
        "account": "[email protected]",
        "appPassword": "xxxx xxxx xxxx xxxx"
      },
      "telegram": {
        "botToken": "123456:ABC-DEF1234ghIkl",
        "allowedUsers": ["761381461"],
        "sessionMode": [
          { "value": "private", "text": "Private — each user has their own conversation", "selected": true },
          { "value": "collaborative", "text": "Collaborative — all users share the same conversation", "selected": false }
        ]
      }
    }
  }
}

POST /UserAgent/Update
{
  "guid": "your-useragent-guid",
  "configuration": {
    "credentials": {
      "appstore": {
        "keyId": "ABC1234DEF",
        "issuerId": "12345678-1234-1234-1234-123456789012",
        "privateKeyBase64": "LS0tLS1CRUdJTi...",
        "appIds": ["6479306352"],
        "supportEmail": "[email protected]"
      },
      "googleplay": {
        "serviceAccountJsonBase64": "eyJ0eXBlIjoic2VydmljZV9hY2NvdW50Ii...",
        "packageNames": ["com.example.app"],
        "supportEmail": "[email protected]"
      },
      "telegram": {
        "botToken": "123456:ABC-DEF1234ghIkl",
        "allowedUsers": ["761381461"],
        "sessionMode": [
          { "value": "private", "text": "Private — each user has their own conversation", "selected": true },
          { "value": "collaborative", "text": "Collaborative — all users share the same conversation", "selected": false }
        ]
      }
    }
  }
}

POST /UserAgent/Update
{
  "guid": "your-useragent-guid",
  "configuration": {
    "credentials": {
      "appstore": {
        "keyId": "ABC1234DEF",
        "issuerId": "12345678-1234-1234-1234-123456789012",
        "privateKeyBase64": "LS0tLS1CRUdJTi...",
        "appIds": ["6479306352"]
      },
      "telegram": {
        "botToken": "123456:ABC-DEF1234ghIkl",
        "allowedUsers": ["761381461"],
        "sessionMode": [
          { "value": "private", "text": "Private — each user has their own conversation", "selected": true },
          { "value": "collaborative", "text": "Collaborative — all users share the same conversation", "selected": false }
        ]
      }
    }
  }
}

POST /UserAgent/Update
{
  "guid": "your-useragent-guid",
  "configuration": {
    "credentials": {
      "firebase": {
        "accounts": [{
          "appName": "My App",
          "serviceAccountJsonBase64": "eyJ0eXBlIjoic2VydmljZV9hY2NvdW50Ii...",
          "apps": [
            { "platform": "ios", "id": "6479306352" },
            { "platform": "android", "id": "com.example.app" }
          ],
          "topics": [
            { "topicKey": "locale_en", "topicDesc": "English-speaking users" },
            { "topicKey": "tier_paid", "topicDesc": "Paid subscribers" }
          ]
        }]
      },
      "telegram": {
        "botToken": "123456:ABC-DEF1234ghIkl",
        "allowedUsers": ["761381461"],
        "sessionMode": [
          { "value": "private", "text": "Private — each user has their own conversation", "selected": true },
          { "value": "collaborative", "text": "Collaborative — all users share the same conversation", "selected": false }
        ]
      }
    }
  }
}

POST /UserAgent/Update
{
  "guid": "your-useragent-guid",
  "configuration": {
    "credentials": {
      "brevo": { "apiKey": "xkeysib-abc123..." },
      "sendgrid": { "apiKey": "SG.xxxx..." },
      "newsletter": { "testEmail": "[email protected]" },
      "telegram": {
        "botToken": "123456:ABC-DEF1234ghIkl",
        "allowedUsers": ["761381461"],
        "sessionMode": [
          { "value": "private", "text": "Private — each user has their own conversation", "selected": true },
          { "value": "collaborative", "text": "Collaborative — all users share the same conversation", "selected": false }
        ]
      }
    }
  }
}

POST /UserAgent/Update
{
  "guid": "your-useragent-guid",
  "configuration": {
    "credentials": {
      "apollo": {
        "apiKey": "your-apollo-api-key",
        "masterApiKey": "your-master-key"
      },
      "lemlist": { "apiKey": "your-lemlist-key" },
      "telegram": {
        "botToken": "123456:ABC-DEF1234ghIkl",
        "allowedUsers": ["761381461"],
        "sessionMode": [
          { "value": "private", "text": "Private — each user has their own conversation", "selected": true },
          { "value": "collaborative", "text": "Collaborative — all users share the same conversation", "selected": false }
        ]
      }
    }
  }
}

POST /UserAgent/Update
{
  "guid": "your-useragent-guid",
  "configuration": {
    "credentials": {
      "website": {
        "urls": [{ "websiteName": "Main Site", "url": "https://example.com" }]
      },
      "appstore": {
        "apps": [{ "appName": "My iOS App", "appId": "6479306352" }]
      },
      "googleplay": {
        "apps": [{ "appName": "My Android App", "packageName": "com.example.app" }]
      },
      "telegram": {
        "botToken": "123456:ABC-DEF1234ghIkl",
        "allowedUsers": ["761381461"],
        "sessionMode": [
          { "value": "private", "text": "Private — each user has their own conversation", "selected": true },
          { "value": "collaborative", "text": "Collaborative — all users share the same conversation", "selected": false }
        ]
      }
    }
  }
}

POST /UserAgent/Update
{
  "guid": "your-useragent-guid",
  "configuration": {
    "credentials": {
      "website": {
        "urls": [{ "websiteName": "Landing Page", "url": "https://example.com" }]
      },
      "appstore": {
        "apps": [{ "appName": "My iOS App", "appId": "6479306352" }]
      },
      "googleplay": {
        "apps": [{ "appName": "My Android App", "packageName": "com.example.app" }]
      },
      "telegram": {
        "botToken": "123456:ABC-DEF1234ghIkl",
        "allowedUsers": ["761381461"],
        "sessionMode": [
          { "value": "private", "text": "Private — each user has their own conversation", "selected": true },
          { "value": "collaborative", "text": "Collaborative — all users share the same conversation", "selected": false }
        ]
      }
    }
  }
}

Credential Field Reference

Quick reference for all credential field names across services:

Setup Required State

If an agent has required (non-optional) credentials that haven't been filled in, the agent is in Setup Required state (status 6) and cannot be started. After setting all required credentials via Update, the status automatically changes to 0 (Stopped) and you can call Start.

Check the setuprequired boolean in UserAgent/Detail or UserAgent/MyAgents responses to determine if credentials still need to be configured.

OAuth Authorization Flow

For services that require user authorization (social media accounts, ad platforms, CRMs), Wiro implements a full OAuth flow. The entire process is fully white-label — your end-users interact only with your app and the provider's consent screen. They never see or visit wiro.ai at any point.

Supported OAuth Providers

Flow Diagram

Your App (Frontend)           Your Backend              Wiro API              Provider (e.g. Twitter)
       |                            |                       |                        |
  (1)  | "Connect Twitter" click    |                       |                        |
       |--------------------------->|                       |                        |
       |                            |  POST /XConnect       |                        |
  (2)  |                            |--> { userAgentGuid,   |                        |
       |                            |      redirectUrl,     |                        |
       |                            |      authMethod }     |                        |
       |                            |                       |                        |
  (3)  |                            |<-- { authorizeUrl }   |                        |
       |                            |                       |                        |
  (4)  |<--- redirect to authorizeUrl                       |                        |
       |--------------------------------------------------------> User sees Twitter  |
       |                            |                       |    consent screen      |
  (5)  |                            |                       |<-- User clicks Allow   |
       |                            |                       |                        |
  (6)  |                            |   (invisible callback)|                        |
       |                            |   Wiro exchanges code |<-----------------------|
       |                            |   for tokens, saves   |                        |
       |                            |   them to agent config|                        |
       |                            |                       |                        |
  (7)  |<------- 302 redirect to YOUR redirectUrl ----------------------------------|
       | https://your-app.com/settings?x_connected=true&x_username=johndoe          |
       |                            |                       |                        |

What the User Sees

Your users never visit wiro.ai. The only pages they see are your app and the provider's authorization screen.

Connect Endpoint

POST /UserAgentOAuth/{Provider}Connect

Response

{
  "result": true,
  "authorizeUrl": "https://x.com/i/oauth2/authorize?response_type=code&client_id=...",
  "errors": []
}

Auth Methods — "wiro" vs "own"

Both modes produce the same white-label user experience. The only difference is whose OAuth app credentials are used for the authorization flow:

To use "own" mode, first set your app credentials via POST /UserAgent/Update, then call Connect with authMethod: "own". Each provider requires different credential field names:

"own" Mode Credentials per Provider

"twitter": {
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret"
}

"tiktok": {
  "clientKey": "your-client-key",
  "clientSecret": "your-client-secret"
}

"instagram": {
  "appId": "your-app-id",
  "appSecret": "your-app-secret"
}

"facebook": {
  "appId": "your-app-id",
  "appSecret": "your-app-secret"
}

"linkedin": {
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "organizationId": "your-org-id"
}

"googleads": {
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "developerToken": "your-dev-token",
  "managerCustomerId": "123-456-7890"
}

"metaads": {
  "appId": "your-app-id",
  "appSecret": "your-app-secret"
}

"hubspot": {
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret"
}

"mailchimp": {
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret"
}

"own" Mode Full Flow

// Step 1: Set your app credentials
POST /UserAgent/Update
{
  "guid": "your-useragent-guid",
  "configuration": {
    "credentials": {
      "twitter": {
        "clientId": "your-twitter-client-id",
        "clientSecret": "your-twitter-client-secret"
      }
    }
  }
}

// Step 2: Initiate OAuth with authMethod: "own"
POST /UserAgentOAuth/XConnect
{
  "userAgentGuid": "your-useragent-guid",
  "redirectUrl": "https://your-app.com/callback",
  "authMethod": "own"
}

// Step 3: Redirect user to the returned authorizeUrl
// Step 4: User authorizes → redirected back to your redirectUrl

When using "own" mode, you must register Wiro's callback URL in your OAuth app settings on the provider's developer portal:

https://api.wiro.ai/v1/UserAgentOAuth/{Provider}Callback

Status Check

Check whether a provider is connected for a given agent instance.

POST /UserAgentOAuth/{Provider}Status

Response

{
  "result": true,
  "connected": true,
  "username": "johndoe",
  "connectedAt": "2025-04-01T12:00:00.000Z",
  "tokenExpiresAt": "2025-04-01T14:00:00.000Z",
  "refreshTokenExpiresAt": "2025-10-01T12:00:00.000Z",
  "errors": []
}

Disconnect

Revoke access and remove stored tokens for a provider.

POST /UserAgentOAuth/{Provider}Disconnect

Response

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

Wiro attempts to revoke the token on the provider's side before clearing it from the configuration. The agent restarts automatically if it was running.

Token Refresh

Manually trigger a token refresh for a connected provider.

POST /UserAgentOAuth/TokenRefresh

Response

{
  "result": true,
  "accessToken": "new-access-token...",
  "refreshToken": "new-refresh-token...",
  "errors": []
}

The agent restarts automatically after a token refresh if it was running.

Extra Provider Endpoints

Google Ads — Set Customer ID

After connecting Google Ads via OAuth, you must set the Google Ads customer ID to target:

POST /UserAgentOAuth/GAdsSetCustomerId

Response

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

Meta Ads — Set Ad Account

After connecting Meta Ads via OAuth, set the ad account to manage:

POST /UserAgentOAuth/MetaAdsSetAdAccount

Response

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

Custom Skills

Agents support configurable skills — preferences and scheduled tasks. See the dedicated Agent Skills page for the complete guide with examples.

Security

• Tokens are stored server-side in the agent instance configuration. The TokenRefresh endpoint returns new tokens — all other endpoints (Status, Detail, Update) sanitize token fields before responding.
• The redirectUrl receives only connection status parameters — no tokens, no secrets
• API responses from Status, Detail, and Update endpoints are sanitized: accessToken, refreshToken, clientSecret, and appSecret fields are stripped before returning
• OAuth state parameters use a 15-minute TTL cache to prevent replay attacks
• Redirect URLs must be HTTPS (or localhost for development)

For Third-Party Developers

If you're building a product on top of Wiro agents and need your customers to connect their own accounts (e.g., their Twitter, their Google Ads), here's the recommended flow:

Architecture

1. Deploy an agent instance per customer via POST /UserAgent/Deploy
2. Connect — your backend calls POST /UserAgentOAuth/{Provider}Connect with the customer's userAgentGuid and a redirectUrl pointing back to your app
3. Redirect — send your customer's browser to the returned authorizeUrl
4. Authorize — customer logs in and authorizes on the provider
5. Return — customer lands back on your redirectUrl with success/error query parameters
6. Verify — call POST /UserAgentOAuth/{Provider}Status to confirm connection

Your customers never interact with Wiro directly. The entire flow happens through your app, and Wiro handles token management behind the scenes.

Handling the Redirect in Your App

// Express route handling the OAuth redirect
app.get('/settings/social', (req, res) => {
  const provider = req.query.provider;

  if (req.query.x_connected === 'true') {
    const username = req.query.x_username;
    return res.redirect(`/dashboard?connected=${provider}&username=${username}`);
  }

  if (req.query.x_error) {
    const error = req.query.x_error;
    return res.redirect(`/dashboard?error=${provider}&reason=${error}`);
  }
});

Error Values

OAuth redirect error parameters follow the pattern {provider_prefix}_error. Possible values:

Overview

Every agent has a set of custom skills that define its behavior. Skills come in two types:

Call POST /UserAgent/Detail to discover an agent's skills. They appear in configuration.custom_skills.

Discovering Skills

POST /UserAgent/Detail
{
  "guid": "your-useragent-guid"
}

// Response → configuration.custom_skills:
[
  {
    "key": "content-tone",
    "value": "## Voice\nShort punchy lines, developer-friendly...",
    "description": "Brand voice, hashtags, and posting style",
    "enabled": true,
    "interval": null,
    "_editable": true
  },
  {
    "key": "content-scanner",
    "value": "",
    "description": "What content to find and post about",
    "enabled": true,
    "interval": "0 * * * *",
    "_editable": false
  }
]

Updating Preferences

Preference skills (_editable: true, interval: null) let you customize the agent's behavior by editing its instructions. Every agent has one — it controls tone, style, targeting, and strategy. Select your agent below to see its preference skill and a complete update request.

POST /UserAgent/Update
{
  "guid": "your-social-manager-guid",
  "configuration": {
    "custom_skills": [
      {
        "key": "content-tone",
        "value": "## Voice\nProfessional and informative. No slang.\n\n## Hashtags\nMax 3 per post. Always include #AI and #WiroAI.\n\n## Posting Style\nEvery post must include a link.\nUse bullet points for features.\n\n## Platform Rules\n- Twitter: Thread format for long content\n- Instagram: Carousel with square images only\n- LinkedIn: Professional tone, no emojis\n- TikTok: Short captions, trending sounds"
      }
    ]
  }
}

POST /UserAgent/Update
{
  "guid": "your-blog-editor-guid",
  "configuration": {
    "custom_skills": [
      {
        "key": "content-strategy",
        "value": "## Writing Style\n- Short simple sentences. Max 15-20 words.\n- Use active voice.\n- No filler phrases.\n\n## Topics\n- AI model comparisons\n- Prompt engineering tutorials\n- Industry trend analysis\n\n## Blog Types\nRotate between: Single Review, VS Comparison, Category Roundup, Prompt Showcase\n\n## WordPress Categories\nUse: AI, Tutorial, Comparison, News"
      }
    ]
  }
}

POST /UserAgent/Update
{
  "guid": "your-app-review-guid",
  "configuration": {
    "custom_skills": [
      {
        "key": "review-preferences",
        "value": "## Response Tone\nCasual and natural. Not corporate.\nShow empathy for negative reviews.\n\n## Support Channels\nDirect users to: [email protected]\nFor billing: [email protected]\n\n## Rules\n- Always thank 5-star reviewers\n- For bugs: acknowledge and promise investigation\n- Never argue with users\n- Max response length: 3 sentences"
      }
    ]
  }
}

POST /UserAgent/Update
{
  "guid": "your-app-event-guid",
  "configuration": {
    "custom_skills": [
      {
        "key": "event-preferences",
        "value": "## Target Regions\nUS, TR, DE, GB\n\n## Holiday Priorities\nHigh: New Year, Black Friday, Christmas\nMedium: Valentine's Day, Halloween\nSkip: Regional holidays outside target regions\n\n## Event Style\nShort punchy titles (max 30 chars).\nAction-oriented descriptions.\nAlways tie events to app features."
      }
    ]
  }
}

POST /UserAgent/Update
{
  "guid": "your-push-agent-guid",
  "configuration": {
    "custom_skills": [
      {
        "key": "push-preferences",
        "value": "## Push Tone\nFriendly and casual.\nTurkish for locale_tr users, English for locale_en.\n\n## Emoji Usage\nMax 1 emoji per push.\n\n## Holiday Preferences\nFocus on: New Year, Ramadan, Republic Day\nSkip: Valentine's Day, Halloween\n\n## Targeting\nAlways segment by locale.\nSend paid-tier users a premium version.\nFree users get engagement-focused pushes."
      }
    ]
  }
}

POST /UserAgent/Update
{
  "guid": "your-newsletter-guid",
  "configuration": {
    "custom_skills": [
      {
        "key": "newsletter-strategy",
        "value": "## Topics\nAI industry news, product updates, tutorials.\nPull content from: https://wiro.ai/blog\n\n## Tone\nFriendly and educational.\nUse first person plural (we, our).\n\n## Frequency\nWeekly on Mondays.\n\n## Branding\nSubject line prefix: [Wiro Weekly]\nAlways include unsubscribe link.\nMax 3 sections per newsletter."
      }
    ]
  }
}

POST /UserAgent/Update
{
  "guid": "your-leadgen-guid",
  "configuration": {
    "custom_skills": [
      {
        "key": "lead-strategy",
        "value": "## Our Business\nCompany: Acme Corp\nProduct: AI-powered CRM\nWebsite: https://acme.com\nValue Proposition: 10x faster lead qualification\n\n## Ideal Customer Profile\nIndustry: SaaS, FinTech\nCompany size: 50-500 employees\nJob titles: VP Sales, Head of Growth, CTO\nLocation: US, UK, Germany\n\n## Outreach Tone\nCasual but professional.\nReference their recent LinkedIn posts.\nKeep emails under 100 words.\n\n## Disqualifiers\nCompanies with fewer than 10 employees.\nAgencies and consultancies."
      }
    ]
  }
}

POST /UserAgent/Update
{
  "guid": "your-google-ads-guid",
  "configuration": {
    "custom_skills": [
      {
        "key": "ad-strategy",
        "value": "## Target Audience\nCountries: US, GB, DE\nLanguages: English\nAge range: 25-54\nInterests: Technology, AI, SaaS\n\n## Budget & Goals\nMonthly budget limit: $5,000\nTarget CPA: $25\nTarget ROAS: 4.0\n\n## Creative Preferences\nTone: Professional, benefit-focused\nAlways include pricing in ads\nUse numbers and statistics in headlines\n\n## Negative Keywords\nfree, cheap, tutorial, how to"
      }
    ]
  }
}

POST /UserAgent/Update
{
  "guid": "your-meta-ads-guid",
  "configuration": {
    "custom_skills": [
      {
        "key": "ad-strategy",
        "value": "## Target Audience\nCountries: US, GB, DE\nLanguages: English\nAge range: 25-54\n\n## Budget & Goals\nMonthly budget limit: $5,000\nTarget CPA: $20\n\n## Creative Preferences\nVisual style: Clean, minimal, product-focused\nUse carousel ads for feature showcases\nVideo ads max 15 seconds\n\n## Campaign Types\nConversions: Main budget (70%)\nRetargeting: Website visitors (20%)\nBrand awareness: Lookalike audiences (10%)"
      }
    ]
  }
}

Managing Scheduled Tasks

Scheduled tasks run automatically on a cron schedule. You can enable/disable them and change their frequency.

Example: Change scanner frequency

POST /UserAgent/Update
{
  "guid": "your-useragent-guid",
  "configuration": {
    "custom_skills": [
      { "key": "review-scanner", "enabled": true, "interval": "0 */4 * * *" },
      { "key": "content-scanner", "enabled": false }
    ]
  }
}

This changes review-scanner to run every 4 hours and disables content-scanner entirely.

Common Cron Expressions

Full Example: Push Notification Manager

Complete flow — fetch skills, then update preferences and schedules in one request.

Step 1 — Discover skills:

POST /UserAgent/Detail
{
  "guid": "your-push-agent-guid"
}

// Response → configuration.custom_skills:
[
  {
    "key": "push-preferences",
    "value": "## Push Tone\nWrite like a mobile growth expert...",
    "description": "Push notification style, language, and targeting preferences",
    "enabled": true,
    "interval": null,
    "_editable": true
  },
  {
    "key": "push-scanner",
    "value": "",
    "description": "Scan holidays and craft push notification suggestions",
    "enabled": true,
    "interval": "0 9 * * *",
    "_editable": false
  },
  {
    "key": "push-dispatcher",
    "value": "",
    "description": "Send queued push notifications on schedule",
    "enabled": true,
    "interval": "0 * * * *",
    "_editable": false
  }
]

Step 2 — Update everything in one request:

POST /UserAgent/Update
{
  "guid": "your-push-agent-guid",
  "configuration": {
    "custom_skills": [
      {
        "key": "push-preferences",
        "value": "## Push Tone\nFriendly and casual. Turkish for locale_tr, English for locale_en.\n\n## Holiday Preferences\nFocus on: New Year, Ramadan, Republic Day.\nSkip: Valentine's Day, Halloween.\n\n## Targeting\nAlways segment by locale. Premium version for paid users."
      },
      {
        "key": "push-scanner",
        "enabled": true,
        "interval": "0 9 * * 1"
      },
      {
        "key": "push-dispatcher",
        "interval": "0 */2 * * *"
      }
    ]
  }
}

This single request:

1. push-preferences — rewrites targeting rules (editable skill, value updated)
2. push-scanner — changes from daily to Mondays only (interval updated)
3. push-dispatcher — changes from hourly to every 2 hours (interval updated)

Available Skills by Agent

Preferences (Editable Instructions)

Every agent has exactly one editable preference skill that controls its behavior:

Scheduled Tasks

Automated tasks that run on a cron schedule. Toggle enabled and adjust interval:

Update Rules

• Include only the fields you want to change — omitted fields keep their current values
• New skills cannot be added — only existing skills (matched by key) can be updated
• Send empty string "" for interval to clear the schedule (becomes null)
• You can update credentials and skills in the same POST /UserAgent/Update request

Two Deployment Patterns

Every product built on Wiro agents follows one of two patterns. Choosing the right one depends on whether your users need to connect their own third-party accounts.

Pattern 1: Instance Per Customer

Most agents interact with external services — posting to social media, managing ad campaigns, sending emails. These require OAuth tokens or API keys that belong to the end user. Deploy a separate agent instance for each of your customers.

Why: Each customer connects their own accounts. Credentials are bound to the instance, isolated from other customers.

How: Call POST /UserAgent/Deploy once per customer, then use the OAuth flow to connect their accounts.

Real-World Examples

Pattern 2: Session Per User

For conversational agents that don't need per-user credentials. One agent instance serves many users, each identified by a unique sessionkey that isolates their conversation history.

Why: No third-party accounts to connect. The agent answers questions using its built-in knowledge or pre-configured data sources.

How: Deploy one instance via POST /UserAgent/Deploy, then send messages with different sessionkey values per user.

Real-World Examples

When to Use Which

Building Your Product

White-Label Chat

Build a fully branded chat experience with no Wiro UI visible to your users.

1. Deploy an agent via POST /UserAgent/Deploy
2. Start the agent with POST /UserAgent/Start
3. Build your own chat UI
4. Send messages via POST /UserAgent/Message/Send
5. Stream responses in real-time via WebSocket using the agenttoken
6. Manage conversation history with POST /UserAgent/Message/History

# Deploy
curl -X POST "https://api.wiro.ai/v1/UserAgent/Deploy" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "agentguid": "agent-template-guid",
    "title": "Customer Support Bot",
    "useprepaid": true,
    "plan": "starter"
  }'

# Send a message
curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/Send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "useragentguid": "deployed-useragent-guid",
    "message": "How do I reset my password?",
    "sessionkey": "user-456"
  }'

Webhook-Driven Pipelines

For backend-to-backend integrations where you don't need real-time streaming.

1. Send a message with a callbackurl
2. Continue processing other work
3. Receive the agent's response via HTTP POST to your webhook endpoint
4. Chain the result into your next workflow step

See Agent Webhooks for payload format and retry policy.

Scheduled Automation

Combine agents with cron jobs for recurring tasks.

Cron (every Monday 9am)
  → POST /UserAgent/Message/Send (with callbackurl)
    → Agent processes the task
      → Webhook fires to your server
        → Your server emails the report / posts to Slack / updates dashboard

This pattern works well for weekly social media content planning, daily ad performance reviews, monthly newsletter generation, and automated lead enrichment pipelines.

Multi-Agent Orchestration

Deploy multiple specialized agents and coordinate them from your backend.

Your Backend
  ├── Research Agent → "Find trending topics in AI this week"
  │     ↓ webhook response
  ├── Writing Agent → "Write a blog post about: {research results}"
  │     ↓ webhook response
  └── Publishing Agent → "Publish this post to WordPress and share on social media"

Each agent is an independent instance with its own credentials. Your backend passes output from one agent as input to the next.

Available Agents

Wiro provides pre-built agent templates you can deploy immediately. Each agent specializes in a specific domain and comes with the relevant skills and credential slots pre-configured.

Deploying an Agent

import requests

headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

# List available agents
agents = requests.post(
    "https://api.wiro.ai/v1/Agent/List",
    headers=headers,
    json={}
)
print(agents.json())

# Deploy an instance
deploy = requests.post(
    "https://api.wiro.ai/v1/UserAgent/Deploy",
    headers=headers,
    json={
        "agentguid": "social-manager-agent-guid",
        "title": "Acme Corp Social Media",
        "useprepaid": True,
        "plan": "starter"
    }
)
useragent_guid = deploy.json()["useragents"][0]["guid"]

# Connect Twitter via OAuth
connect = requests.post(
    "https://api.wiro.ai/v1/UserAgentOAuth/XConnect",
    headers=headers,
    json={
        "userAgentGuid": useragent_guid,
        "redirectUrl": "https://your-app.com/settings?connected=twitter"
    }
)
authorize_url = connect.json()["authorizeUrl"]

# Start the agent
requests.post(
    "https://api.wiro.ai/v1/UserAgent/Start",
    headers=headers,
    json={"guid": useragent_guid}
)

# Send a message
message = requests.post(
    "https://api.wiro.ai/v1/UserAgent/Message/Send",
    headers=headers,
    json={
        "useragentguid": useragent_guid,
        "message": "Create a thread about our new product launch",
        "sessionkey": "campaign-q2"
    }
)
print(message.json())

Browse available agents and their capabilities at Agent/List or in the Wiro dashboard.

Overview

Wiro supports three workspace contexts for organizing your resources:

• Personal — your default workspace. Projects, agents, and wallet are tied to your individual account.
• Organization — a parent entity that groups one or more teams. The organization owner controls the lifecycle of teams and their members.
• Team — a workspace under an organization with its own wallet, projects, agents, and member permissions. Team members share access to resources deployed within the team.

Personal Account
├── Personal Projects
├── Personal Agents
└── Personal Wallet

Organization (created by you)
├── Team A
│   ├── Team Wallet
│   ├── Team Projects
│   ├── Team Agents
│   └── Members (owner, admins, members)
├── Team B
│   ├── Team Wallet
│   ├── Team Projects
│   ├── Team Agents
│   └── Members
└── ...

Every user always has a personal workspace. Organizations and teams are optional — you can use Wiro entirely in personal mode without ever creating an organization.

Key Concepts

Workspaces and Context

When you make an API request or use the dashboard, you operate in one of two contexts:

Switching context changes which projects, agents, and wallet you interact with. Resources in one context are isolated from the other — personal agents cannot see team projects, and team agents cannot access personal resources.

Resource Isolation

Each workspace is fully isolated:

• Projects belong to either your personal workspace or a specific team. A project's API key automatically resolves the correct context.
• Agents are deployed into a workspace. Team agents are visible to all team members; personal agents are visible only to you.
• Wallet transactions are recorded against the workspace that initiated them. Team tasks deduct from the team wallet; personal tasks deduct from your personal wallet.
• Tasks are tagged with the workspace context and only appear in the matching project usage and statistics views.

Transferring Resources

Projects and agents can be transferred between workspaces:

• Personal → Team — move a project or agent from your personal workspace into a team you have admin access to
• Team → Personal — move a project or agent from a team back to your personal workspace
• Team → Team — move a project or agent between teams you have admin access to

When a resource is transferred, its billing context changes immediately. Future tasks on a transferred project will be billed to the new workspace's wallet.

Important: Agents can only access projects in the same workspace. If you transfer a project out of a team, agents in that team can no longer use it.

Organizations vs Teams

An organization is a management container — it does not hold resources directly. All resources (projects, agents, wallets) live inside teams.