What is ?

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

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

Base URL

All API requests are made to:

https://api.wiro.ai/v1

WebSocket connections use:

wss://socket.wiro.ai/v1

Quick Start

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

Response Format

Every API response returns JSON with a consistent structure:

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

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

Rate Limits & Error Handling

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

Common HTTP status codes:

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

Overview

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

Comparison

How to Choose

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

What is a Project?

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

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

Creating a Project

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

API Credentials

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

Managing Projects

From the Projects page in your Dashboard, you can:

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

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

POST /Tool/List

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

Response

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

POST /Tool/Detail

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

Response

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

Model Browser

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

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

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

Content Types

JSON (application/json)

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

Multipart (multipart/form-data)

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

Request Parameters

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

Response

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

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

Full Flow

The typical workflow after calling the Run endpoint:

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

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

Discovering Parameters

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

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

Parameter Types

JSON vs Multipart

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

File Upload Patterns

Single File (fileinput)

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

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

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

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

Multiple Files (multifileinput)

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

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

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

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

Combined (combinefileinput)

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

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

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

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

Common Model Patterns

Image Generation (text-to-image)

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

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

Image-to-Image (upscaler, style transfer)

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

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

Virtual Try-On

Multiple image inputs — multipart with multiple files:

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

LLM / Document Processing

Text prompt with optional document uploads:

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

Realtime Voice Conversation

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

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

Webhook Callback

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

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

Task Lifecycle

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

Task Statuses

Realtime Conversation Only

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

Determining Success or Failure

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

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

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

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

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

Billing & Cost

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

Successful run — billed:

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

Failed run — not billed:

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

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

LLM Models

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

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

POST /Task/Detail

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

Response

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

POST /Task/Cancel

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

POST /Task/Kill

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

POST /Task/InputOutputDelete

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

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

Response

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

After deletion:

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

Errors

Overview

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

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

Available LLM models include:

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

Session & Chat History

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

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

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

Thinking & Answer Phases

Many LLM models separate their output into two phases:

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

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

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

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

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

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

Streaming Flow

The complete flow for streaming an LLM response:

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

Polling Alternative

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

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

Connection URL

wss://socket.wiro.ai/v1

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

Connection Flow

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

Registration message format:

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

Message Types

Message Format

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

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

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

Lifecycle Events

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

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

Output Events

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

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

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

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

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

Error Events

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

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

Full Output Events

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

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

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

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

Final Result

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

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

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

Realtime Events

These events are exclusive to realtime voice models:

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

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

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

Binary Frames

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

Ending a Session

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

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

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

Overview

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

The flow is:

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

Run Parameters

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

Available realtime conversation models include:

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

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

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

Connection & Registration

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

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

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

Realtime Events

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

Audio Format

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

Binary Frame Format

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

[tasktoken]|[PCM audio data]

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

Sending Microphone Audio

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

Key steps:

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

Receiving AI Audio

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

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

Transcripts

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

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

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

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

Ending a Session

To gracefully end a realtime session, send task_session_end:

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

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

Overview

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

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

The flow is:

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

How It Differs from Realtime Voice Conversation

Run Parameters

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

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

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

Connection & Registration

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

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

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

Realtime Events

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

Event Sequence

A typical TTS session produces events in this order:

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

Audio Format

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

Binary Frame Format

Every binary WebSocket frame from the server is structured as:

[tasktoken]|[PCM audio data]

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

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

Receiving AI Audio

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

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

Gapless Playback

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

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

Ending a Session

To gracefully end a realtime TTS session, send task_session_end:

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

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

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

Overview

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

The flow is:

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

How It Differs from Realtime Voice Conversation

Run Parameters

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

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

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

Connection & Registration

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

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

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

Realtime Events

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

Audio Format

Audio flows in one direction only: client → server.

Binary Frame Format

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

[tasktoken]|[PCM audio data]

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

Sending Microphone Audio

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

Key steps:

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

Transcripts

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

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

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

Progressive Results

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

var fullTranscript = [];

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

Ending a Session

To gracefully end a realtime session, send task_session_end:

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

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

Overview

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

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

POST /File/FolderCreate

Creates a new folder to organize your uploaded files.

Response

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

POST /File/Upload

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

File size limit: 100 MB per file.

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

Response

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

Using Files in Runs

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

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

Overview

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

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

Billing Methods

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

Fixed-Rate Methods

Usage-Based Methods

Special Methods

Dynamic Pricing

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

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

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

How Dynamic Pricing Works

Each entry in the dynamicprice array represents a pricing tier:

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

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

Example: Video Generation Pricing

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

Example: Simple Flat Pricing

An image generation model with a flat rate:

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

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

Fallback Pricing (Per-Second)

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

totalcost = elapsed_seconds × cps

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

approximatelycost = average_elapsed_seconds × cps

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

Checking Prices

Via the API

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

Via MCP

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

Pricing Page

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

What You Pay For

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

What You Are Not Charged For

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

Monitoring Your Spending

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

Overview

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

How It Works

Your concurrency limit is determined by your current account balance:

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

Examples

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

What Counts as Active

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

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

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

API Response

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

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

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

Error Codes

Increasing Your Limit

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

For enterprise needs or custom concurrency arrangements, contact support.

Best Practices

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

Response Format

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

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

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

Error Codes

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

Authentication Errors

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

Run Errors

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

Balance & Limits

Validation Errors

Model Access Errors

Task Errors

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

Error Handling

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

const data = await response.json();

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

Retry Strategy

Overview

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

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

Full Examples

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

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

What is MCP?

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

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

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

Links

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

Setup

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

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

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

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

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

https://mcp.wiro.ai/v1

Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET

Authentication

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

Signature-Based (Recommended)

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

Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET

API Key Only

Simpler. Only requires the API key:

Authorization: Bearer YOUR_API_KEY

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

Available Tools

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

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

Discovery

Execution

Task Management

Utility

Examples

Generate an image

"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 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.

Prepaid deploy (useprepaid: true + plan) charges your wallet immediately and creates the instance in status 6 (Setup Required). configuration.credentials and configuration.custom_skills passed in the Deploy body are ignored on prepaid deploy — after deploy, call POST /UserAgent/Update to set credentials and (optionally) customize skill content. Once credentials are complete, status auto-transitions to 0 (Stopped) and you can call UserAgent/Start.

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

Panel/UI note: the non-prepaid Deploy mode (omit useprepaid) exists for the Wiro dashboard's interactive deploy flow where end users pay via Stripe subscription with a browser redirect. That path also accepts configuration.credentials and configuration.custom_skills in the body (merged via mergeUserConfig), but API integrations should always use prepaid deploy and set credentials with a follow-up UserAgent/Update call.

Request

{
  "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,
      "pinned": false,
      "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-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 — prepaid instance (the API deploy pattern)

{
  "result": true,
  "errors": [],
  "useragents": [
    {
      "id": 47,
      "guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
      "uuid": "your-user-uuid",
      "agentid": 5,
      "teamguid": null,
      "title": "My Instagram Bot",
      "description": null,
      "status": 4,
      "pinned": false,
      "setuprequired": false,
      "configuration": {
        "credentials": {
          "instagram": {
            "_editable": { "authMethod": true },
            "optional": false,
            "authMethod": "wiro",
            "igUsername": "myaccount",
            "connectedAt": "2025-04-01T12:00:00.000Z"
          }
        },
        "custom_skills": [
          {
            "key": "content-tone",
            "description": "Content strategy, brand voice, and posting rules",
            "value": "## Brand Voice\nTone: friendly\nTarget Audience: ...",
            "enabled": true,
            "interval": null,
            "_editable": true
          },
          {
            "key": "cron-content-scanner",
            "description": "Content discovery with rotating strategies",
            "value": "",
            "enabled": true,
            "interval": "0 */4 * * *",
            "_editable": false
          }
        ],
        "skills": { "instagram-post": true, "wiro-generator": true },
        "rateLimit": {
          "monthlyCredits": 5000,
          "extraCredits": 2000,
          "actionTypes": { "message": 10, "create": 60, "modify": 20, "regenerate": 20 }
        }
      },
      "subscription": {
        "plan": "agent-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
    }
  ]
}

Response — Stripe-subscription instance

The Stripe path (panel/UI deploy flow) adds three billing portal URLs; prepaid instances don't have these fields at all.

{
  "result": true,
  "errors": [],
  "useragents": [
    {
      "id": 48,
      "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "agentid": 5,
      "title": "Stripe-subscribed 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"
          }
        },
        "custom_skills": [
          {
            "key": "content-tone",
            "description": "Content strategy, brand voice, and posting rules",
            "value": "## Brand Voice\nTone: friendly\nTarget Audience: ...",
            "enabled": true,
            "interval": null,
            "_editable": true
          },
          {
            "key": "cron-content-scanner",
            "description": "Content discovery with rotating strategies",
            "value": "",
            "enabled": true,
            "interval": "0 */4 * * *",
            "_editable": false
          }
        ],
        "skills": { "instagram-post": true, "wiro-generator": true }
      },
      "subscription": {
        "plan": "agent-pro",
        "status": "active",
        "amount": 29,
        "currency": "usd",
        "currentperiodend": 1717200000,
        "renewaldate": "2026-06-01T00:00:00.000Z",
        "daysremaining": 62,
        "pendingdowngrade": null,
        "provider": "stripe"
      },
      "agent": {
        "id": 5,
        "title": "Instagram Manager",
        "slug": "instagram-manager",
        "pricing": {
          "starter": { "price": 9, "credits": 1000 },
          "pro": { "price": 29, "credits": 5000 }
        }
      },
      "extracredits": 0,
      "extracreditsexpiry": null,
      "stripeportalurl": "https://billing.stripe.com/p/session/xxxxxxxx",
      "stripeupdateurl": "https://billing.stripe.com/p/session/xxxxxxxx/subscriptions/update",
      "stripecancelurl": "https://billing.stripe.com/p/session/xxxxxxxx/subscriptions/cancel",
      "createdat": 1714608000,
      "updatedat": 1714694400
    }
  ]
}

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

{
  "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 by the agent runtime (container) as it processes messages and generates content — not at Message/Send time. Each configuration.rateLimit.actionTypes entry (message, create, modify, regenerate) defines how many credits a specific action costs; the container reports usage back to Wiro asynchronously. The API-side check is gating only: POST /UserAgent/Start refuses to launch if monthlyCredits + extraCredits <= 0. During an active session, monthly credits are deducted first; once they hit zero, extra credits (purchased via CreateExtraCreditCheckout) are used. When both pools are empty, the agent responds [SYSTEM_CREDIT_LIMIT_REACHED] and stops processing further actions. Credits reset on each billing cycle or when extra credits are topped up.

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": {
      "type": "progressGenerate",
      "task": "Generate",
      "speed": "14.2",
      "speedType": "words/s",
      "elapsedTime": "8.1s",
      "tokenCount": 105,
      "wordCount": 118,
      "raw": "Here are the key AI trends for 2026...",
      "thinking": [],
      "answer": ["Here are the key AI trends for 2026..."],
      "isThinking": false
    },
    "attachments": [],
    "deletestatus": 0,
    "createdat": "1743350400",
    "startedat": "1743350401",
    "endedat": "1743350408"
  }
}

POST /UserAgent/Message/History

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

Response

{
  "result": true,
  "errors": [],
  "data": {
    "messages": [
      {
        "guid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
        "content": "What are the latest trends in AI?",
        "response": "Here are the key AI trends for 2026...",
        "debugoutput": "Here are the key AI trends for 2026...",
        "status": "agent_end",
        "metadata": {
          "type": "progressGenerate",
          "task": "Generate",
          "speed": "14.2",
          "speedType": "words/s",
          "elapsedTime": "8.1s",
          "tokenCount": 105,
          "wordCount": 118,
          "raw": "Here are the key AI trends for 2026...",
          "thinking": [],
          "answer": ["Here are the key AI trends for 2026..."],
          "isThinking": false
        },
        "attachments": [],
        "deletestatus": 0,
        "createdat": "1743350400"
      },
      {
        "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "content": "Tell me more about multimodal models",
        "response": "Multimodal models combine...",
        "debugoutput": "Multimodal models combine...",
        "status": "agent_end",
        "metadata": {},
        "attachments": [],
        "deletestatus": 0,
        "createdat": "1743350300"
      }
    ],
    "count": 2,
    "hasmore": false
  }
}

Pagination

Page 1 — most recent messages:

{
  "useragentguid": "...",
  "limit": 50
}

Page 2 — pass the last message's guid as cursor:

{
  "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 messages in the given session for the calling user. This action cannot be undone.

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

Response

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

POST /UserAgent/Message/Cancel

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

Response

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

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

Behavior depends on when the cancel hits:

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

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

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.

1. Subscribe to agent message updates:

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

2. Server confirms subscription with current status:

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

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

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

4. Final event (agent_end — terminal):

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

2. Polling via Detail

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

3. Webhook Callback

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

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

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

Connection URL

wss://socket.wiro.ai/v1

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

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

Connection Flow

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

1. Welcome frame (server → client)

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

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

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

2. Subscribe frame (client → server)

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

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

3. Subscribe errors

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

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

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

Multi-session subscription

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

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

Typical use cases:

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

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

Event Types

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

Message Format

Every WebSocket frame is a JSON object. All agent lifecycle frames (agent_subscribed / agent_start / agent_output / agent_end / agent_error / agent_cancel) share this base shape:

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

The control frames (connected, error) use a different shape with no agenttoken:

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

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

The agent_subscribed frame additionally carries status (the DB row's current status) and, when the token is known, debugoutput (accumulated text so far). When the token is unknown, status is "unknown" and debugoutput is omitted entirely.

agent_subscribed

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

• If the agenttoken is valid and pending/active (known to the server, not yet finished), debugoutput is always present — an empty string "" if nothing has streamed yet, or the accumulated text so far.
• If the agenttoken is unknown (typo, expired, already cleaned up from the buffer), debugoutput is omitted entirely from the payload (no field at all). Always use "debugoutput" in payload or payload.debugoutput !== undefined to distinguish unknown-token from empty-output, rather than relying on truthiness.

Valid token, queued — debugoutput present and empty:

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

Unknown token — status is "unknown" and no debugoutput field:

{
  "type": "agent_subscribed",
  "agenttoken": "wrongtoken123",
  "status": "unknown",
  "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 — a sanitized string when the stream is aborted by an exception, or a progress object when the stream finished naturally but the model returned a non-response.

Sanitized string error — any exception during streaming (bridge timeout, upstream HTTP 5xx, worker crash, SSE read error, etc.) surfaces as a single user-safe sentence:

{
  "type": "agent_error",
  "agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
  "message": "Agent is temporarily unavailable. Please try again shortly.",
  "result": false
}

The raw runtime error is never broadcast over WebSocket. Strings like "Bridge timeout", "OpenClaw returned HTTP 500", "SSE request timeout (30min)", "Could not resolve agent endpoint" are recorded in the database debugoutput field (retrievable via POST /UserAgent/Message/Detail) but replaced with the generic sentence above before being pushed to subscribed clients. This is intentional so end users never see internal infrastructure errors.

Progress-object error — the SSE stream completes normally but the model returns "..." or "Error: internal error". In that case Wiro flags the message as agent_error and broadcasts the same progressGenerate shape as agent_output / agent_end:

{
  "type": "agent_error",
  "agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
  "message": {
    "type": "progressGenerate",
    "task": "Generate",
    "speed": "2.5",
    "speedType": "words/s",
    "elapsedTime": "1.2s",
    "tokenCount": 3,
    "wordCount": 1,
    "raw": "...",
    "thinking": [],
    "answer": ["..."],
    "isThinking": false
  },
  "result": false
}

Check the runtime type of message to branch:

if (msg.type === 'agent_error') {
  if (typeof msg.message === 'string') showToast(msg.message)
  else renderResponse(msg.message.raw)
}

agent_cancel

Sent when the user cancels a message before the agent completes its response — but only when the abort hits the bridge mid-flight (queued-state cancels do not broadcast this event):

{
  "type": "agent_cancel",
  "agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
  "message": "AbortError",
  "result": false
}

The message field carries the abort reason from the runtime (typically "AbortError" or a short technical string). It is not a fixed user-facing message — do not parse it for exact strings. Use type === "agent_cancel" as the canonical signal. Subscribers that cancel from a queued state receive no event at all (the message is simply marked agent_cancel in the database; check with POST /UserAgent/Message/Detail).

The result Field

Every agent lifecycle 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. The welcome connected frame has no result field — it's a one-shot ack and always implies success (you got the frame, so the upgrade worked).

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:

←  connected         { version: "1.0" }
→  agent_info        { agenttoken: "..." }
←  agent_subscribed  { status: "agent_queue", debugoutput: "" }
←  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 } }

← = server → client, → = client → server. Each agent_output contains the full accumulated text. Replace (don't append) your display content on each event.

Quick Reference

connected — welcome frame (server → client, sent once on upgrade):

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

Subscribe frame (client → server):

{
  "type": "agent_info",
  "agenttoken": "aB3xK9..."
}

error — malformed subscribe (server → client, sent when agent_info is missing agenttoken):

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

agent_subscribed — valid token (empty debugoutput):

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

agent_subscribed — unknown token (status: "unknown", no debugoutput):

{
  "type": "agent_subscribed",
  "agenttoken": "wrongtoken",
  "status": "unknown",
  "result": true
}

agent_start:

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

agent_output — streaming partials, 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 — sanitized string (any exception during streaming):

{
  "type": "agent_error",
  "agenttoken": "aB3xK9...",
  "message": "Agent is temporarily unavailable. Please try again shortly.",
  "result": false
}

agent_cancel — active-processing abort only; queued-state cancels don't broadcast:

{
  "type": "agent_cancel",
  "agenttoken": "aB3xK9...",
  "message": "AbortError",
  "result": false
}

Correlating Events With Your Messages

Every agent lifecycle frame (agent_subscribed / agent_start / agent_output / agent_end / agent_error / agent_cancel) carries agenttoken — this is the only correlation key available on the wire. The wire payload does not include messageguid, sessionkey, or useragentguid. If you need any of those fields to route events back to a specific message in your UI, build the mapping yourself when you call Message/Send.

Why agenttoken is the correlation key

• Message/Send issues exactly one agenttoken per message and returns it alongside messageguid in the HTTP response.
• The bridge stamps the same agenttoken on every event it emits for that message.
• Multiple connections can subscribe to the same agenttoken and each gets the full event stream — so agenttoken is also the fan-out key.
• A single socket can hold subscriptions for many agenttokens at once — the per-event agenttoken lets your handler dispatch into the right UI element.

Recommended client pattern

1. Call POST /UserAgent/Message/Send — you get back { messageguid, agenttoken, status: "agent_queue", ... }.
2. Store the mapping agenttoken → messageguid (or agenttoken → your UI message id).
3. Send { "type": "agent_info", "agenttoken" } on an open socket (new or existing — connections can be reused).
4. In ws.onmessage, read msg.agenttoken on every agent lifecycle frame, look up your stored mapping, and update the matching UI element.
5. When you see a terminal event (agent_end / agent_error / agent_cancel), delete the mapping so it doesn't leak memory across sessions.

const tokenToMessageId = new Map()

async function sendMessage(text, uiMessageId) {
  const resp = await fetch('https://api.wiro.ai/v1/UserAgent/Message/Send', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': 'YOUR_API_KEY' },
    body: JSON.stringify({
      useragentguid: 'your-useragent-guid',
      message: text,
      sessionkey: 'user-42'
    })
  }).then(r => r.json())

  tokenToMessageId.set(resp.agenttoken, uiMessageId)
  ws.send(JSON.stringify({ type: 'agent_info', agenttoken: resp.agenttoken }))
  return { messageguid: resp.messageguid, agenttoken: resp.agenttoken }
}

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data)
  if (!msg.agenttoken) return  // control frames (connected / error) have no token

  const uiMessageId = tokenToMessageId.get(msg.agenttoken)
  if (!uiMessageId) return

  switch (msg.type) {
    case 'agent_output':
      updateUI(uiMessageId, { streaming: msg.message.raw })
      break
    case 'agent_end':
      updateUI(uiMessageId, { final: msg.message.raw, status: 'agent_end' })
      tokenToMessageId.delete(msg.agenttoken)
      break
    case 'agent_error':
    case 'agent_cancel':
      updateUI(uiMessageId, { error: msg.message, status: msg.type })
      tokenToMessageId.delete(msg.agenttoken)
      break
  }
}

Concurrency: multiple in-flight messages on one session

Sending two messages back-to-back in the same sessionkey produces two independent agenttokens. Both reach the bridge in queue order; both stream events independently. Your client must:

• Subscribe to both agenttokens (one agent_info frame each — the server de-duplicates automatically).
• Key all UI updates on agenttoken, not on sessionkey (which is shared) or timestamps (which can interleave).

The server never mixes streams — every event is stamped with the originating agenttoken so routing is unambiguous even when chunks from two messages interleave on the wire.

Control frames have no agenttoken

The welcome frame and the subscribe-error frame are connection-level signals, not per-message events. They intentionally omit agenttoken:

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

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

Always null-check msg.agenttoken before looking it up in your mapping — see the if (!msg.agenttoken) return guard in the example above.

Reconnection & Recovery

The agent keeps running server-side regardless of whether any client is subscribed. A disconnected socket never cancels the agent. This means a dropped connection is always recoverable — just reconnect and re-subscribe with the same agenttoken.

Recovery flow

1. Detect disconnect — ws.onclose / stream exception / ping timeout.
2. Reconnect — open a new WebSocket to wss://socket.wiro.ai/v1.
3. Wait for welcome — receive { "type": "connected", "version": "1.0" } (optional but clean).
4. Re-subscribe — send { "type": "agent_info", "agenttoken": "..." } with the same token.
5. Handle agent_subscribed — the server reports the current status. Three cases:
   • status is agent_queue / agent_start / agent_output → stream is still live; accumulated text so far is in debugoutput. Future events will be forwarded normally.
   • status is agent_end → the agent already finished. debugoutput holds the full final response. No further WebSocket events will fire. Fetch POST /UserAgent/Message/Detail for the canonical record (including metadata, attachments, endedat), then close the socket.
   • status is agent_error / agent_cancel → the agent already failed / was cancelled. debugoutput may contain partial output. No further events. Fetch POST /UserAgent/Message/Detail for the persisted error details.

On reconnect you do not receive replays of the past agent_output frames — only events emitted after re-subscribe. Use the debugoutput on agent_subscribed as the snapshot of what you missed.

Retry strategy

• Exponential backoff, capped at 30 seconds. The server is usually responsive, so don't hammer it.
• Stop retrying once you hit a terminal event (agent_end / agent_error / agent_cancel) or an unknown status — the work is either done or the token is gone.
• Idempotent re-subscribe: sending the same agenttoken again on a fresh socket is always safe.
• Fall back to polling if WebSocket is blocked (strict corporate proxies, mobile cellular with long-poll fallbacks). Use POST /UserAgent/Message/Detail at 1–2 second intervals until status is terminal.

Token Lifecycle

An agenttoken is issued per message by POST /UserAgent/Message/Send and stays addressable on the WebSocket for as long as the underlying agentmessages row exists (Wiro does not auto-purge rows on a short timer; tokens remain queryable indefinitely after the run ends).

Multi-subscriber semantics: multiple WebSocket connections can subscribe to the same agenttoken and all receive the same event stream in parallel. The server does not enforce a subscriber limit per token. This is how the Wiro Dashboard shows the same agent chat on multiple tabs for the same user — each tab opens its own socket and subscribes independently.

Cross-user subscription: the agenttoken alone authenticates subscription — if you leak a token to another user, they can read the stream. Treat tokens like short-lived secrets scoped to the message.

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:

{
  "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": "AbortError",
  "debugoutput": "AbortError",
  "metadata": {},
  "endedat": 1712050004
}

The response and debugoutput fields contain the raw abort reason from the runtime — typically "AbortError" or a short technical string. Do not rely on a specific fixed user-facing message; use status === "agent_cancel" as the signal.

When the cancel webhook fires: agent_cancel is delivered only when the agent bridge catches an AbortError during active processing — i.e. the message had already started on the agent side and was aborted mid-flight (via POST /UserAgent/Message/Cancel or an upstream timeout). For messages cancelled before they reach the bridge (still queued, or an instant Message/Cancel that beats dispatching), the message is marked agent_cancel in the database and returned as such in POST /UserAgent/Message/Detail, but no webhook is fired. Use POST /UserAgent/Message/Detail (checking status === "agent_cancel") as the canonical source of truth for cancellation; WebSocket subscribers receive the agent_cancel event only on active-processing aborts (same condition as the webhook). Treat the webhook as a best-effort "processing was interrupted" signal.

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.

Integration Catalog

OAuth Integrations

• Meta Ads — own mode only (Wiro mode coming soon). End-to-end setup with no App Review required.
• Facebook Page — own mode only (Wiro mode coming soon). Includes multi-page selection via FBSetPage.
• Instagram — own mode only (Wiro mode coming soon). Requires Instagram Business Account linked to a Facebook Page.
• LinkedIn — own mode only (Wiro mode coming soon). Company Page publishing.
• Twitter / X — Wiro mode + own mode. OAuth 2.0 PKCE.
• TikTok — Wiro mode + own mode. Content Posting API.
• Google Ads — Wiro mode + own mode. MCC + customer ID selection.
• HubSpot — Wiro mode + own mode. CRM object management.
• Mailchimp — Wiro mode + own mode + direct API key.
• Google Drive — Wiro mode + own mode. Scoped folder access.

API Key Integrations

• Gmail — App Password via IMAP/SMTP.
• Telegram — Bot Token + allowed users.
• Firebase — FCM service account JSON.
• WordPress — Application Password + REST API.
• App Store Connect — ES256 API key + .p8 private key.
• Google Play — Service account + Play Console permissions.
• Apollo — API key + optional master key.
• Lemlist — API key.
• Brevo — API key.
• SendGrid — API key.

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

{
  "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.

{
  "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
          }
        ]
      }
    }
  }
}

{
  "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
          }
        ]
      }
    }
  }
}

{
  "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
          }
        ]
      }
    }
  }
}

{
  "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
          }
        ]
      }
    }
  }
}

{
  "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
          }
        ]
      }
    }
  }
}

{
  "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
          }
        ]
      }
    }
  }
}

{
  "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
          }
        ]
      }
    }
  }
}

{
  "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
          }
        ]
      }
    }
  }
}

{
  "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:

{
  "guid": "your-useragent-guid",
  "configuration": {
    "credentials": {
      "twitter": {
        "clientId": "your-twitter-client-id",
        "clientSecret": "your-twitter-client-secret"
      }
    }
  }
}

Step 2 — Initiate OAuth with authMethod: "own":

{
  "userAgentGuid": "your-useragent-guid",
  "redirectUrl": "https://your-app.com/callback",
  "authMethod": "own"
}

Step 3 — Redirect the user to the authorizeUrl returned by the Connect endpoint.

Step 4 — The provider sends the user back to your redirectUrl with ?result=true (or ?result=false&error=...) once consent is complete.

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": []
}