Introduction
Everything you need to get started with the Wiro AI platform.
What is Wiro?
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
- AI Agents: deploy and manage autonomous AI agents that connect to third-party services, maintain conversation memory, and automate workflows via API
- Workflows: chain models into saved workflows and run them with new inputs through the API, or design them by chat with the Workflow Agent
- Studio: ask Studio, Wiro's creative agent, for images, video and audio; it picks and runs the models for you
Base URL
All API requests are made to:
https://api.wiro.ai/v1
WebSocket connections use:
wss://socket.wiro.ai/v1
Quick Start
- Sign up Create an account at wiro.ai
- Create a project Go to the Dashboard to get your API key
- Pick a model Browse the marketplace and choose a model
- Make your first API call See Code Examples for full end-to-end samples
- Deploy an AI Agent Browse the agent catalog, deploy an instance, and interact via the Agent API
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: Success400: Bad request (check parameters)401: Unauthorized (invalid or missing API key)403: Forbidden (signature mismatch or insufficient permissions)429: Rate limit exceeded500: Internal server error
Authentication
Secure your API requests with signature-based or simple key authentication.
Overview
Wiro supports two authentication methods. You choose the method when creating a project and can switch it later in the project's settings on the Projects page. Your API key and secret stay the same, and the change applies right away, so your requests must then use the new method.
Signature-Based Authentication
Uses HMAC-SHA256 to sign every request. The API secret is never sent with your requests, but it is needed to make the signature, so sign requests on your own server. Never put the API secret in browser or mobile app code.
How it works
- Generate a nonce Use a unix timestamp or random integer
-
Concatenate Combine:
API_SECRET + NONCE -
Create HMAC-SHA256 hash Use your
API_KEYas the secret key - Send as headers Include the signature, nonce, and API key in request headers
SIGNATURE = HMAC-SHA256(key=API_KEY, message=API_SECRET + NONCE)
Required Headers
| Parameter | Type | Required | Description |
|---|---|---|---|
x-api-key |
string | Yes | Your project API key |
x-signature |
string | Yes | HMAC-SHA256(API_SECRET + NONCE, API_KEY) |
x-nonce |
string | Yes | Unix timestamp or random integer |
API Key Only Authentication
For server-side applications where you control the environment, you can use the simpler API-key-only method. Just include the x-api-key header. No signature is required.
Required Headers
| Parameter | Type | Required | Description |
|---|---|---|---|
x-api-key |
string | Yes | Your project API key |
Comparison
| Feature | Signature-Based | API Key Only |
|---|---|---|
| Security | High: the secret is never sent over the wire | Moderate: the key is sent with every request |
| Complexity | Requires HMAC computation | Single header |
| Best for | Server-side apps, production backends | Server-side, internal tools |
| Leaked API key | Not enough: the secret is also needed | Enough to call the API |
How to Choose
- Building a browser or mobile app? Have the app call your own backend, and call Wiro from there. Never put your API key or secret in the app.
- Running a server-side backend with controlled access? API Key Only is simpler.
- Unsure? Default to Signature-Based, which is always the safer option.
Using Auth with Agent Endpoints
The same authentication headers work for every UserAgent/* and UserAgentOAuth/* endpoint. Example:
curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/Send" \
-H "Content-Type: application/json" \
-H "x-api-key: ${YOUR_API_KEY}" \
-d '{
"useragentguid": "your-useragent-guid",
"message": "What are the latest campaign insights?"
}'
Signature-based projects add x-nonce and x-signature exactly as shown in the Run example. The signing algorithm is identical. See Agent Overview for the full agent API reference.
Projects
Organize your API access and usage with projects.
What is a Project?
A project is a container that holds your API keys, authentication 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 spending are tracked per project
- A project has no wallet of its own. Its runs are paid from your personal wallet, or from the team wallet for a team project
- You can create multiple projects under one account
Creating a Project
- Go to the Dashboard Navigate to wiro.ai/panel
- Open Projects Go to Projects and click New Project
- Name your project Enter a descriptive project name
- Select authentication method Signature-Based: generates API key + secret | API Key Only: generates only an API key
- Create Click Create and copy your credentials immediately
API Credentials
After creating a project, copy your API key (and secret, if signature-based) and store them securely. You can see them again later on the Projects page after you confirm it's you with your password or a code we email you. In a team, team admins and the organization owner can see every project's key. Other members see the keys of the projects they created, and only a masked form of the rest. Only the owner of a personal project can see its secret again; for a team project, a team admin or the organization owner can.
Important: Treat your API secret like a password. Never commit it to version control or put it in browser or mobile app code. Keep it on your own server.
Managing Projects
From the Projects page in your Dashboard, you can:
- Update name: rename your project at any time
- Change authentication method: switch between Signature-Based and API Key Only; your API key and secret stay the same
- View usage: see API calls, costs, and task history
- Delete project: permanently removes the project and revokes all keys
A project's API key never changes. To replace it, create a new project, move your application to the new key, then delete the old project, which revokes its key at once. Changing a project's IP whitelist gives the project a new API secret.
Models
Browse and discover AI models available on the Wiro platform.
POST /Tool/List
Returns a paginated list of available models. Filter by categories, search by name, and sort results.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
start |
string | No | Offset for pagination (default: "0") |
limit |
string | No | Number of results to return (default: "20") |
search |
string | No | Search query to filter models by name |
sort |
string | No | Sort field: id, relevance |
order |
string | No | Sort direction: ASC or DESC |
categories |
string[] | No | Filter by categories (e.g. image-generation, llm, audio, video) |
tags |
string[] | No | Filter by tags |
slugowner |
string | No | Filter by model owner slug |
hideworkflows |
boolean | No | Hide workflow models from results (recommended: true) |
summary |
boolean | No | Return summarized model data (recommended for listings) |
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.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
slugowner |
string | Yes | Model owner slug (e.g. google) |
slugproject |
string | Yes | Model project slug (e.g. nano-banana) |
summary |
boolean | No | Return summarized data |
Response
{
"result": true,
"errors": [],
"tool": [{
"id": "1562",
"title": "Nano Banana API: Create Mobile & Web Apps with Nano Banana",
"slugowner": "google",
"slugproject": "nano-banana",
"cleanslugowner": "google",
"cleanslugproject": "nano-banana",
"description": "Google's Gemini 2.5 Flash Image Preview, also known as Nano Banana, model for text-to-image and image-to-image generation.",
"image": "https://cdn.wiro.ai/uploads/models/google-nano-banana-cover.webp",
"computingtime": "10 seconds",
"readme": "Google's Gemini 2.5 Flash Image Preview model for text-to-image and image-to-image generation.",
"categories": ["image-to-image", "text-to-image", "image-editing"],
"parameters": [
{
"title": "",
"subtitle": "",
"items": [
{ "id": "inputImage", "type": "combinefileinput", "required": false, "advanced": false },
{ "id": "prompt", "type": "textarea", "required": true, "advanced": false },
{ "id": "temperature", "type": "float", "required": false, "advanced": true },
{ "id": "aspectRatio", "type": "select", "required": false, "advanced": true },
{ "id": "safetySetting", "type": "select", "required": false, "advanced": true }
]
}
],
"inspire": [
{ "prompt": "Create a Spider Man image flying over Warsaw", "inputImage": "" }
],
"samples": ["https://cdn.wiro.ai/uploads/models/google-nano-banana-sample-15.webp"],
"tags": ["google"],
"marketplace": 1,
"onlymembers": "1",
"dynamicprice": [{ "inputs": {}, "price": 0.039, "priceMethod": "cpo" }],
"averagepoint": "4.38",
"commentcount": "10",
"ratedusercount": "8",
"taskstat": {
"runcount": "531554",
"successcount": "510396",
"errorcount": "21240",
"lastruntime": "1789217220"
},
"seotitle": "Nano Banana API: Create Mobile & Web Apps with Nano Banana",
"seodescription": null
}]
}
Model Browser
Browse available models interactively. Click on a model to see its details on the model page.
Run a Model
Execute any AI model with a single API call and get real-time updates.
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, and Wiro will POST the result to your URL when the task completes.
If you want one HTTP request to wait for the finished task, use POST /Run/{owner}/{model}/sync on this same API host. For OpenAI or Anthropic LLM protocols, see the Direct LLM Gateway.
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:
Common Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
callbackUrl |
string | No | URL to receive a POST webhook when the task completes. It must be a public http(s) address: a host that is, or resolves to, a private, loopback or link-local address gets no webhook. The task still runs, and Task/Detail returns its result. Any 2xx answer counts as delivered; see Webhook Callback for retries and redirects. |
projectid |
string | No | Override the default project for billing (if you have multiple projects) |
URL inputs must be public too. When you send a file input as a URL, Wiro downloads the file itself, so the URL must be a public http(s) address, and so must every address it redirects to. A host that is, or resolves to, a private, loopback or link-local address isn't fetched, and the run gets no file for that input.
Response
A successful run returns a task ID and a WebSocket access token:
{
"result": true,
"errors": [],
"taskid": "2221",
"socketaccesstoken": "eDcCm5yyUfIvMFspTwww49OUfgXkQt"
}
Direct LLM turns and tool calls
Models whose Tool Detail response includes the llm-tool-call category accept seven optional ordinary model parameters on both asynchronous Run and /sync: messages, tools, tool_choice, parallel_tool_calls, response_format, previousTaskToken, and toolOutputs. response_format is present only on models that declare it, and it uses the flat shape {"type":"json_object"} or {"type":"json_schema","name":"person","schema":{...}}, not Chat's nested json_schema wrapper. A mode the model does not declare is rejected at $.response_format.type before the task is created. Tool Detail marks them advanced: true only to place them in the Advanced section of catalog-driven UIs; they use the same parameters object and Run transport as every other model parameter. Send JSON values directly, and use exactly one of prompt or non-empty messages on a first turn.
{
"messages": [{
"role": "user",
"content": "What is the weather in Paris?"
}],
"tools": [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Return current weather for a city",
"parameters": {
"type": "object",
"properties": { "city": { "type": "string" } },
"required": ["city"],
"additionalProperties": false
},
"strict": true
}
}],
"tool_choice": "auto",
"parallel_tool_calls": true,
"session_id": "weather-session-1"
}
// Node.js
const response = await fetch(
"https://api.wiro.ai/v1/Run/claude/fable-5/sync",
{
method: "POST",
headers: {
"Content-Type": "application/json",
"x-api-key": process.env.WIRO_API_KEY
},
body: JSON.stringify({
messages: [{
role: "user",
content: "What is the weather in Paris?"
}],
tools: [{
type: "function",
function: {
name: "get_weather",
parameters: {
type: "object",
properties: { city: { type: "string" } },
required: ["city"]
}
}
}],
tool_choice: "auto",
parallel_tool_calls: true,
session_id: "weather-session-1",
})
}
);
Wiro never executes caller-defined tools. A tool request is returned in outputs[].content.segments as its own ordered timeline item. Function calls use arguments, custom grammar/free-form calls use input, and both include stable id, call_id, name, and status fields. Execute a call only when its status is completed and the turn's finishreason is tool_calls; incomplete calls may contain truncated input and must never be executed.
The same structured LLM fields appear in three response locations:
- WebSocket
task_output:message.segmentsis the live cumulative snapshot; final-only metadata may be absent while generation is still running. - WebSocket
task_postprocess_end:message[].contentcontains the persisted final output. - Task Detail and non-streaming
/sync:tasklist[0].outputs[].contentcontains the persisted final output.
Inside that content:
segmentsis the authoritative ordered text/tool-call timeline.finishreasonexplains why generation stopped:stop,tool_calls,length,content_filter, orerror. Handlelength,content_filter, anderroras non-normal model completion.usagecontains normalized token and server-tool counters.input_tokensincludes cache reads and cache writes;output_tokensincludes reasoning; andtotal_tokensis exactlyinput_tokens + output_tokens. Therefore, do not add detail counters to the total. Optionalinput_tokens_detailscan includecached_tokens,cache_write_tokens, five-minute and one-hour cache-write subsets, and text/audio/image/video counters. Optionaloutput_tokens_detailscan include reasoning, text/audio/image/video, and accepted/rejected prediction counters. Optionalserver_tool_usecontains request counts rather than tokens. Providers omit unsupported counters. There is no cached-output counter because prompt caching applies to input context, not previously generated output.usageis informational and is used by protocol-compatible LLM responses; use the task-leveltotalcostfor the actual billed amount.
For a final llm-tool-call result, rely on pexit: "0" and require finishreason. Structured-output validation failures set a non-zero pexit.
{
"segments": [{
"type": "function_call",
"id": "fc_01",
"call_id": "call_01",
"name": "get_weather",
"arguments": "{\"city\":\"Paris\"}",
"status": "completed"
}],
"finishreason": "tool_calls",
"usage": {
"input_tokens": 84,
"input_tokens_details": {
"cached_tokens": 24,
"cache_write_tokens": 8,
"cache_write_5m_tokens": 8,
"text_tokens": 84
},
"output_tokens": 21,
"output_tokens_details": {
"reasoning_tokens": 9,
"text_tokens": 21
},
"total_tokens": 105,
"server_tool_use": {
"web_search_requests": 1
}
}
}
For tool-output continuation, execute the tool in your application and send another Run request with the first request's returned socketaccesstoken as previousTaskToken, the same session_id, and one matching entry in toolOutputs for every executed call. Do not send prompt, messages, tools, tool_choice, parallel_tool_calls, or response_format on this continuation. prompt, messages, tools, tool_choice and response_format are rejected outright; parallel_tool_calls is ignored. The tools, tool choice, and response format stored with the first turn are reapplied automatically, so a JSON contract set on the first turn still holds after the tool round-trip.
{
"previousTaskToken": "task-token",
"toolOutputs": [{
"call_id": "call_01",
"output": {
"temperature_c": 12,
"condition": "rain"
}
}],
"session_id": "weather-session-1"
}
Stateful turn continuation
A chat continues through its session_id. After a turn that ended with an answer, run the same model again with the same session_id and the next prompt. Wiro keeps the earlier turns of the session; some chat models also need the same user_id on every turn (see LLM & Chat Streaming). Send the same session_id on every turn, the first one included, and leave previousTaskToken out.
{
"prompt": "Give me one concrete example.",
"session_id": "weather-session-1"
}
previousTaskToken belongs to the tool-call round trip above: together with toolOutputs, it continues a turn whose finishreason is tool_calls, using the socketaccesstoken of that completed task from the same project, model and session. After a plain prompt turn, a request that sends previousTaskToken with the next prompt is refused with code 122 ("The previous task state for this conversation is no longer available."). Send the same session_id and the next prompt instead.
For OpenAI-compatible clients, previous_response_id remains the preferred public field on /v1/responses; do not send previousTaskToken to that endpoint. Direct asynchronous Run and /sync clients use previousTaskToken.
For cumulative SSE or WebSocket snapshots, replace the previous segments array. Do not append the complete array again. A call can move from in_progress to completed while keeping the same IDs. The final pexit: "0" remains the success indicator.
POST /Run/{owner-slug}/{model-slug}/sync
Wait for any finite model on https://api.wiro.ai/v1. This starts the same billed task as asynchronous Run, then returns final Task Detail JSON or streams generic task events. It is not an OpenAI or Anthropic protocol. Training and realtime models are rejected.
curl -X POST \
"https://api.wiro.ai/v1/Run/claude/fable-5/sync" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"prompt": "Reply with one concise sentence about Türkiye.",
"session_id": "fable-sync-example",
"effort": "medium",
"webSearch": "false",
"maxOutputTokens": 128
}'
Without streaming, the request stays open and returns Task Detail-compatible JSON. Check tasklist[0].pexit; "0" means the model task succeeded. For LLM tasks, outputs contains the structured result and debugoutput contains merged plain text.
{
"result": true,
"total": "1",
"tasklist": [{
"id": "2221",
"status": "task_postprocess_end",
"pexit": "0",
"outputs": []
}],
"errors": []
}
Add ?stream=true or send Accept: text/event-stream for named generic events: start, cumulative task snapshots as task_output, a final done, and periodic : keep-alive comments. Generic SSE does not use [DONE]. LLM task_output events contain one ordered segments array. Text items use thinking or answer; tool items use function_call or custom_tool_call.
event: task_output
data: {
"id": "2221",
"status": "task_output",
"pexit": null,
"segments": [
{ "type": "thinking", "text": "Checking the constraints..." },
{ "type": "answer", "text": "Here is the result." }
]
}
Each LLM segments value is the full accumulated ordered snapshot, not only the latest delta. Replace your previously stored segment list with each event instead of appending the whole array again. While generation is active, the final item's text, arguments, or input grows in place as chunks arrive; render each snapshot immediately instead of waiting for done. A new item is added when the output phase changes. Render thinking items as optional reasoning progress, answer items as the model response, and tool items as application-executed calls. The final done event contains Task Detail-compatible JSON; inspect tasklist[0].pexit to determine success.
curl -N -X POST \
"https://api.wiro.ai/v1/Run/claude/fable-5/sync?stream=true" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-H "Accept: text/event-stream" \
-d '{
"prompt": "Reply with one concise sentence about Türkiye.",
"session_id": "fable-stream-example",
"effort": "medium",
"webSearch": "false",
"maxOutputTokens": 128
}'
Disconnecting or reaching the 40-minute wait timeout ends only the synchronous wait; the task keeps running. A non-streaming timeout returns HTTP 504 with taskid and socketaccesstoken so you can resume tracking it through Task Detail or WebSocket. Only task_postprocess_end and task_cancel close the wait. task_error does not close a task. Errors use Wiro's result/errors envelope. Sync is an additional execution method; asynchronous Run remains unchanged.
/v1/Run/{owner-slug}/{model-slug}/sync?stream=true
OpenAI Chat/Responses, Anthropic Messages, and Cursor clients belong on https://llm.wiro.ai. See the Direct LLM Gateway.
Full Flow
The typical workflow after calling the Run endpoint:
- Run: call
POST /Run/{owner-slug}/{model-slug}and receive a task ID - Track: connect via WebSocket or poll
POST /Task/Detail - Receive: get outputs as the model produces them (streaming or final)
- Complete: task reaches
task_postprocess_end; verifypexit: "0"and read its outputs
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.
Direct LLM Gateway
Use Wiro LLMs through OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages.
https://llm.wiro.ai/v1. Clients that append /v1 themselves, including Anthropic SDKs and Claude Code, use origin https://llm.wiro.ai. Asynchronous Run, Task, and the original Wiro File API remain on https://api.wiro.ai/v1; WebSocket remains on wss://socket.wiro.ai/v1. The Direct LLM Gateway also provides compatible /v1/files routes backed by the same authenticated project storage.
The gateway uses the same Wiro task, project-access, team-policy, and billing system as the Run API. Discover a model before calling it: supported endpoints, parameters, modalities, tools, reasoning, and limits are model-specific.
Direct LLM responses never expose Wiro Run/Sync segments. Each route returns only its selected protocol's native JSON and streaming events: OpenAI Chat chunks, OpenAI Responses events, or Anthropic Messages events. OpenClaw and Hermes receive the native transport they configure.
With stream: true, the stream opens as soon as the request is accepted, so its first events do not mean the model has started writing. Answer text then arrives while the model writes it, in small batches rather than one event per token, and so does reasoning on the routes that return it. Tool calls, the finish reason and usage arrive once the turn is complete. While the model works, a : keep-alive comment arrives every 15 seconds. On Wiro-hosted models, a turn that can call tools or asks for json_object output can arrive in one batch at the end.
Model IDs use lowercase owner/model form. Do not send a provider-only model name: discover the exact ID and protocol capabilities first.
Choose an endpoint
POST /v1/Run/{owner}/{project}remains the asynchronous task-creation endpoint onapi.wiro.ai.POST /v1/Run/{owner}/{project}/syncis the generic finite-model wait onapi.wiro.ai; see Run a Model. It is not a Direct LLM protocol.GET /v1/modelslists verifiedllm-tool-callmodels and needs no API key. The list is not filtered by Model Access rules; they apply when a model runs.GET /v1/chat/modelsis equivalent.GET /v1/models/{owner}/{model}returns one model's contract, also without a key.POST,GET, andDELETE /v1/filescompatibility routes use the authenticated project's existing Wiro file storage.POST /v1/chat/completionsuses OpenAI Chat JSON/SSE.POST /v1/responsesuses OpenAI Responses JSON and named SSE.POST /v1/messagesuses Anthropic Messages JSON/SSE.POST /v1/messages/count_tokensestimates Anthropic input tokens before a run.GET /v1/generation?id=...returns authorized generation metadata.
/sync is a newly added generic wait method on api.wiro.ai; it does not replace asynchronous Run. Direct LLM routes remain separate on llm.wiro.ai.
The asynchronous Run route returns taskid and socketaccesstoken immediately; retrieve its result through Task Detail, WebSocket, or a callback. The generic /sync wait is an additional method on api.wiro.ai; it does not replace asynchronous Run. Direct LLM routes remain separate on llm.wiro.ai.
Training and realtime models are not accepted by /sync or the Direct LLM Gateway. Use their existing training or realtime APIs.
Authentication
Project credentials
Model discovery/detail, the protocol routes, and /generation all use the authenticated project's credentials. Compatible clients should use project Bearer authentication:
- API Key Only:
Authorization: Bearer YOUR_API_KEY - Signature:
Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET, or the base64 encoding of that pair
The same endpoints also accept x-api-key containing either YOUR_API_KEY or YOUR_API_KEY:YOUR_API_SECRET. Direct LLM routes do not accept the Run API's x-nonce/x-signature HMAC trio. If Bearer and x-api-key are sent together, they must contain the same complete project credential. Mismatched keys or secrets and malformed credentials return 401 without cross-project fallback.
Never expose a project key or secret in browser or mobile application code.
Anthropic Messages takes the credential in x-api-key, where Anthropic SDKs send it, or in an Authorization: Bearer header. Send YOUR_API_KEY for an API Key Only project or YOUR_API_KEY:YOUR_API_SECRET for a Signature project. Generic /sync waits stay on api.wiro.ai and use normal Run headers.
Session identifier
session_id is the only public session field. It is optional on Chat Completions and Anthropic Messages, and must contain 1 to 128 letters, digits, ., _, :, or -. Reuse the same value for related turns. Wiro maps it to a project-scoped internal session; it does not replace the protocol's normal client-history requirements. Responses uses previous_response_id instead, and /v1/messages/count_tokens does not accept session_id.
Connect an agent
Point a compatible client at llm.wiro.ai. Use a project Bearer credential: API Key Only projects send YOUR_API_KEY; Signature projects send YOUR_API_KEY:YOUR_API_SECRET. Generic finite-model waits stay on Run a Model /sync.
Every client below needs the exact lowercase owner/model ID. Two places give it to you:
- The catalog, filtered to gateway models: browse them, open one, and copy the ID from its page.
GET /v1/models: the same set as JSON.GET /v1/models/{owner}/{model}then reports that model's routes, modalities, tool support and token limits.
Cursor
Cursor reaches the gateway through its OpenAI base URL override, which it appends /chat/completions to. Point it at the normal /v1 base.
-
Open the model settings Command Palette (
Cmd+Shift+P,Ctrl+Shift+Pon Windows) →Cursor Settings: Models. -
View All Models The settings pane lists only the models Cursor ships with.
View All Models, at the bottom, opens the full list where custom ones live. -
+ Add Custom Model Type the exact lowercase
owner/modelID. These are the same IDs VS Code takes, listed below. Repeat for each model you want. Cursor shows whatever you type in its picker, so a parenthesised label is read and discarded at either end:(Wiro) claude/sonnet-5andclaude/sonnet-5 (Wiro)both resolve toclaude/sonnet-5. Leading keeps every Wiro model together in the picker.
-
OpenAI API Key Put the project credential in the
OpenAI API Keyfield; that is the field Cursor uses for the overridden endpoint.YOUR_API_KEY:YOUR_API_SECRETfor a Signature project,YOUR_API_KEYalone for API Key Only. -
Turn the key on Flip the switch beside the field. It reads
Secret savedonce Cursor has stored the credential. - Override OpenAI Base URL Turn that switch on too. It sits directly under the key.
-
Enter the base URL
https://llm.wiro.ai/v1. Cursor appends/chat/completionsitself, so do not add it. - Disable the built-in models While the override is on, Cursor sends its own model names to your endpoint too, and those do not exist in the Wiro catalog. Leave only the models you added enabled, or every request fails with an unknown model.
-
Verify Press
Verify. A failure here is normally the base URL carrying/chat/completions, or a built-in model still switched on.
Every model the gateway serves today, labelled and ready to paste one at a time; drop the (Wiro) part, or move it to the end, as you prefer. The same set is in the catalog and behind GET /v1/models.
(Wiro) bytedance/seed-v2-1-turbo
(Wiro) bytedance/seed-v2-lite
(Wiro) bytedance/seed-v2-mini
(Wiro) bytedance/seed-v2-pro
(Wiro) claude/fable-5
(Wiro) claude/fable-5-1
(Wiro) claude/fable-5-2
(Wiro) claude/opus-5
(Wiro) claude/opus-5-5
(Wiro) claude/sonnet-5
(Wiro) deepseek/v4-1-flash
(Wiro) deepseek/v4-1-flash-economy
(Wiro) deepseek/v4-flash
(Wiro) deepseek/v4-pro
(Wiro) glm/5-2
(Wiro) glm/5-3
(Wiro) google/gemini-2-5-flash
(Wiro) google/gemini-3-5-flash
(Wiro) google/gemini-3-5-flash-lite
(Wiro) google/gemini-3-6-flash
(Wiro) google/gemini-3-7-flash
(Wiro) google/gemini-3-8-flash
(Wiro) google/gemini-3-flash
(Wiro) google/gemini-3-pro
(Wiro) google/gemini-4-argon
(Wiro) meta-llama/llama-3-2-3b-instruct
(Wiro) mistralai/mistral-7b-instruct-v0-3
(Wiro) mistralai/mistral-nemo-instruct-2407
(Wiro) moonshot/kimi-k3-1-pro
(Wiro) openai/gpt-5-2
(Wiro) openai/gpt-5-4
(Wiro) openai/gpt-5-4-mini
(Wiro) openai/gpt-5-4-nano
(Wiro) openai/gpt-5-5
(Wiro) openai/gpt-5-6-luna
(Wiro) openai/gpt-5-6-sol
(Wiro) openai/gpt-5-6-terra
(Wiro) openai/gpt-5-mini
(Wiro) openai/gpt-5-nano
(Wiro) openai/gpt-6-1-sol
(Wiro) openai/gpt-6-1-terra
(Wiro) openai/gpt-6-astra
(Wiro) openai/gpt-6-luna
(Wiro) openai/gpt-6-sol
(Wiro) qwen/qwen2-5-0-5b-instruct
(Wiro) qwen/qwen2-5-1-5b-instruct
(Wiro) qwen/qwen2-5-14b-instruct
(Wiro) qwen/qwen2-5-32b-instruct
(Wiro) qwen/qwen2-5-3b-instruct
(Wiro) qwen/qwen2-5-7b-instruct
(Wiro) qwen/qwen2-5-coder-32b-instruct
(Wiro) qwen/qwen2-5-coder-7b-instruct
(Wiro) qwen/qwen3-30b-a3b
(Wiro) qwen/qwen3-30b-a3b-thinking-2507
(Wiro) qwen/qwen3-32b
(Wiro) qwen/qwen3-5-27b
(Wiro) qwen/qwen3-5-27b-heretic
(Wiro) qwen/qwen3-5-4b
(Wiro) qwen/qwen3-5-4b-heretic
(Wiro) qwen/qwen3-5-9b
(Wiro) qwen/qwen3-5-9b-heretic
(Wiro) qwen/qwen3-6-27b
(Wiro) qwen/qwen3-8-27b
(Wiro) qwen/qwen3-8-27b-obliterated
(Wiro) qwen/qwen3-8-27b-uncensored
(Wiro) ricursiveai/ripple-65b-preview
(Wiro) xai/grok-4-1-fast
(Wiro) xai/grok-4-20
(Wiro) xai/grok-4-5
The override covers the chat and agent panel. Tab autocomplete and inline edit keep using Cursor's own backend whatever you configure here, so they are unaffected either way.
Claude Code
Claude Code reads the gateway through the Anthropic Messages protocol. This is the terminal Claude Code: the desktop app manages its own provider and cannot be pointed at a gateway, so its model picker keeps listing Anthropic’s models whatever you configure.
-
Install the CLI In a terminal:
npm i -g @anthropic-ai/claude-code -
Write the settings file Two places take it, and the file is the same in both. Pick by how widely you want the gateway used.
Every folder on this machine (
~/.claude/settings.json):{ "env": { "ANTHROPIC_BASE_URL": "https://llm.wiro.ai", "ANTHROPIC_API_KEY": "YOUR_API_KEY:YOUR_API_SECRET", "ANTHROPIC_MODEL": "(Wiro) openai/gpt-5-6-sol", "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1", "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "1050000" } }One project only:
<project>/.claude/settings.json, in the folder you will open Claude Code in. Your other projects keep whatever they were using. If that folder is a git repository, put it in.claude/settings.local.jsoninstead, which is not committed. The credential should not reach the shared file:{ "env": { "ANTHROPIC_BASE_URL": "https://llm.wiro.ai", "ANTHROPIC_API_KEY": "YOUR_API_KEY:YOUR_API_SECRET", "ANTHROPIC_MODEL": "(Wiro) openai/gpt-5-6-sol", "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1", "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "1050000" } }ANTHROPIC_BASE_URLcarries no/v1here: Anthropic clients append the path themselves.ANTHROPIC_API_KEYtakesYOUR_API_KEY:YOUR_API_SECRETfor a Signature project, orYOUR_API_KEYalone for API Key Only.ANTHROPIC_MODELis the model the session opens with, and is any ID from the list below, not only theclaude/ones; the(Wiro)prefix is optional and the gateway strips it, but Claude Code prints whatever you write in its session header.CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERYadds gateway models to the/modelpicker, but Claude Code keeps only IDs containingclaudeoranthropic, so the picker gains theclaude/models alone; open any other model withANTHROPIC_MODELor--model.CLAUDE_CODE_MAX_CONTEXT_TOKENSmust match the context window of the model you set. Claude Code does not recognise these names, so it otherwise assumes 200k and discards history long before it needs to. -
Open Claude Code in that folder
cd /path/to/your/project && claude -
Answer the first-run prompts A new install asks three things in a row: a colour theme, its security notes (
Press Enter to continue), and whether to applyClaude Code’s terminal setup. Answer them once. -
Allow the project’s MCP servers, if it has any A folder that declares MCP servers gets
New MCP server found in this projectbefore the session opens. Nothing here concerns the gateway; choose whatever you would normally choose. -
Answer the key prompt
Do you want to use this API key?→No. It asks about a key exported in your shell, not the one you just put in the settings file. -
Check the header, then start It names the model you configured:
(Wiro) openai/gpt-5-6-sol · API Usage Billing. Your Claude subscription is not used while a gateway credential is set. -
Switching models Open on another model for one session:
Or changecd /path/to/your/project && claude --model "(Wiro) xai/grok-4-1-fast" cd /path/to/your/project && claude --model "(Wiro) bytedance/seed-v2-pro" cd /path/to/your/project && claude --model "(Wiro) openai/gpt-5-nano"ANTHROPIC_MODELin the settings file, which every session in that scope then opens on. MoveCLAUDE_CODE_MAX_CONTEXT_TOKENSwith it, since Grok 4.1 Fast holds 2M where GPT 5.6 Sol holds 1.05M:{ "env": { "ANTHROPIC_BASE_URL": "https://llm.wiro.ai", "ANTHROPIC_API_KEY": "YOUR_API_KEY:YOUR_API_SECRET", "ANTHROPIC_MODEL": "(Wiro) xai/grok-4-1-fast", "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1", "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "2000000" } }
Every model the gateway serves today, with the context window for CLAUDE_CODE_MAX_CONTEXT_TOKENS. The same values come from GET /v1/models as max_input_tokens. For a Wiro-hosted model that number is the prompt the GPU it runs on actually has room for, measured on the fleet. It is usually well below the window its checkpoint was built for, and below what its model card advertises. Set the variable to the number the catalog reports, not the card’s.
Model ID Context
----------------------------------------------------
(Wiro) bytedance/seed-v2-1-turbo 256000
(Wiro) bytedance/seed-v2-lite 256000
(Wiro) bytedance/seed-v2-mini 256000
(Wiro) bytedance/seed-v2-pro 256000
(Wiro) claude/fable-5 1000000
(Wiro) claude/fable-5-1 1000000
(Wiro) claude/fable-5-2 1000000
(Wiro) claude/opus-5 1000000
(Wiro) claude/opus-5-5 1000000
(Wiro) claude/sonnet-5 1000000
(Wiro) deepseek/v4-1-flash 1000000
(Wiro) deepseek/v4-1-flash-economy 1000000
(Wiro) deepseek/v4-flash 1048576
(Wiro) deepseek/v4-pro 1048576
(Wiro) glm/5-2 1048576
(Wiro) glm/5-3 1000000
(Wiro) google/gemini-2-5-flash 1048576
(Wiro) google/gemini-3-5-flash 1048576
(Wiro) google/gemini-3-5-flash-lite 1048576
(Wiro) google/gemini-3-6-flash 1048576
(Wiro) google/gemini-3-7-flash 1048576
(Wiro) google/gemini-3-8-flash 1048576
(Wiro) google/gemini-3-flash 1048576
(Wiro) google/gemini-3-pro 1048576
(Wiro) google/gemini-4-argon 1048576
(Wiro) meta-llama/llama-3-2-3b-instruct 51200
(Wiro) mistralai/mistral-7b-instruct-v0-3 17408
(Wiro) mistralai/mistral-nemo-instruct-2407 35840
(Wiro) moonshot/kimi-k3-1-pro 1048576
(Wiro) openai/gpt-5-2 272000
(Wiro) openai/gpt-5-4 1050000
(Wiro) openai/gpt-5-4-mini 272000
(Wiro) openai/gpt-5-4-nano 272000
(Wiro) openai/gpt-5-5 1050000
(Wiro) openai/gpt-5-6-luna 1050000
(Wiro) openai/gpt-5-6-sol 1050000
(Wiro) openai/gpt-5-6-terra 1050000
(Wiro) openai/gpt-5-mini 272000
(Wiro) openai/gpt-5-nano 272000
(Wiro) openai/gpt-6-1-sol 1050000
(Wiro) openai/gpt-6-1-terra 1050000
(Wiro) openai/gpt-6-astra 1050000
(Wiro) openai/gpt-6-luna 1050000
(Wiro) openai/gpt-6-sol 1050000
(Wiro) qwen/qwen2-5-0-5b-instruct 32768
(Wiro) qwen/qwen2-5-1-5b-instruct 32768
(Wiro) qwen/qwen2-5-14b-instruct 29696
(Wiro) qwen/qwen2-5-32b-instruct 17408
(Wiro) qwen/qwen2-5-3b-instruct 32768
(Wiro) qwen/qwen2-5-7b-instruct 32768
(Wiro) qwen/qwen2-5-coder-32b-instruct 17408
(Wiro) qwen/qwen2-5-coder-7b-instruct 32768
(Wiro) qwen/qwen3-30b-a3b 7168
(Wiro) qwen/qwen3-30b-a3b-thinking-2507 7168
(Wiro) qwen/qwen3-32b 17408
(Wiro) qwen/qwen3-5-27b 25600
(Wiro) qwen/qwen3-5-27b-heretic 25600
(Wiro) qwen/qwen3-5-4b 72704
(Wiro) qwen/qwen3-5-4b-heretic 72704
(Wiro) qwen/qwen3-5-9b 25600
(Wiro) qwen/qwen3-5-9b-heretic 25600
(Wiro) qwen/qwen3-6-27b 25600
(Wiro) qwen/qwen3-8-27b 25600
(Wiro) qwen/qwen3-8-27b-obliterated 25600
(Wiro) qwen/qwen3-8-27b-uncensored 126976
(Wiro) ricursiveai/ripple-65b-preview 15360
(Wiro) xai/grok-4-1-fast 2000000
(Wiro) xai/grok-4-20 2000000
(Wiro) xai/grok-4-5 500000
If Claude Code opens to the login screen instead of a session, the settings file was not read in time: a project .claude/settings.json applies only after the first-run prompts and the folder trust prompt above. Answer those once and reopen, or put the same env block in ~/.claude/settings.json, which is read before them and applies to every folder.
VS Code
VS Code Chat reaches the gateway through its own built-in custom endpoint, no extension required.
-
Open the model manager Command Palette (
Cmd+Shift+P,Ctrl+Shift+Pon Windows) →Chat: Manage Language Models. -
Add a provider
+ Add Modelsopens a provider list: Anthropic, Azure, Google, OpenAI, OpenRouter, xAI, Ollama. PickCustom Endpoint, last, below the separator. -
Group Name Arrives pre-filled with “Custom Endpoint”; replace it with
Wiro AI. It is a label: it titles the next two prompts and groups the models in the picker. -
API Key
YOUR_API_KEY:YOUR_API_SECRETfor a Signature project,YOUR_API_KEYalone for API Key Only. VS Code keeps it in its secret store; the file holds only a${input:…}reference. -
API Type Choose
Chat Completions. Responses and Messages change the request shape VS Code sends. -
Describe the models VS Code opens
chatLanguageModels.jsonwith one empty model. Leavename,vendor,apiKeyandapiTypeas generated and fill themodelsarray. Below is every model the gateway serves today, ready to paste; the same set is in the catalog and behindGET /v1/models.
[
{
"name": "Wiro AI",
"vendor": "customendpoint",
"apiKey": "${input:chat.lm.secret.xxxxxxxx}",
"apiType": "chat-completions",
"models": [
{
"id": "bytedance/seed-v2-1-turbo",
"name": "(Wiro) Seed V2.1 Turbo",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 256000,
"maxOutputTokens": 65536
},
{
"id": "bytedance/seed-v2-lite",
"name": "(Wiro) Seed V2 Lite",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 256000,
"maxOutputTokens": 65536
},
{
"id": "bytedance/seed-v2-mini",
"name": "(Wiro) Seed V2 Mini",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 256000,
"maxOutputTokens": 65536
},
{
"id": "bytedance/seed-v2-pro",
"name": "(Wiro) Seed V2 Pro",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 256000,
"maxOutputTokens": 65536
},
{
"id": "claude/fable-5",
"name": "(Wiro) Fable 5",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1000000,
"maxOutputTokens": 128000
},
{
"id": "claude/fable-5-1",
"name": "(Wiro) Fable 5.1",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1000000,
"maxOutputTokens": 128000
},
{
"id": "claude/fable-5-2",
"name": "(Wiro) Fable 5.2",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1000000,
"maxOutputTokens": 128000
},
{
"id": "claude/opus-5",
"name": "(Wiro) Opus 5",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1000000,
"maxOutputTokens": 128000
},
{
"id": "claude/opus-5-5",
"name": "(Wiro) Opus 5.5",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1000000,
"maxOutputTokens": 128000
},
{
"id": "claude/sonnet-5",
"name": "(Wiro) Sonnet 5",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1000000,
"maxOutputTokens": 128000
},
{
"id": "deepseek/v4-1-flash",
"name": "(Wiro) DeepSeek V4.1 Flash",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1000000,
"maxOutputTokens": 384000
},
{
"id": "deepseek/v4-1-flash-economy",
"name": "(Wiro) DeepSeek V4.1 Flash Economy",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1000000,
"maxOutputTokens": 384000
},
{
"id": "deepseek/v4-flash",
"name": "(Wiro) DeepSeek V4 Flash",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 1048576,
"maxOutputTokens": 384000
},
{
"id": "deepseek/v4-pro",
"name": "(Wiro) DeepSeek V4 Pro",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 1048576,
"maxOutputTokens": 384000
},
{
"id": "glm/5-2",
"name": "(Wiro) GLM 5.2",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 1048576,
"maxOutputTokens": 128000
},
{
"id": "glm/5-3",
"name": "(Wiro) GLM 5.3",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1000000,
"maxOutputTokens": 128000
},
{
"id": "google/gemini-2-5-flash",
"name": "(Wiro) Gemini 2.5 Flash",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1048576,
"maxOutputTokens": 65536
},
{
"id": "google/gemini-3-5-flash",
"name": "(Wiro) Gemini 3.5 Flash",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1048576,
"maxOutputTokens": 65536
},
{
"id": "google/gemini-3-5-flash-lite",
"name": "(Wiro) Gemini 3.5 Flash-Lite",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1048576,
"maxOutputTokens": 65536
},
{
"id": "google/gemini-3-6-flash",
"name": "(Wiro) Gemini 3.6 Flash",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1048576,
"maxOutputTokens": 65536
},
{
"id": "google/gemini-3-7-flash",
"name": "(Wiro) Gemini 3.7 Flash",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1048576,
"maxOutputTokens": 65536
},
{
"id": "google/gemini-3-8-flash",
"name": "(Wiro) Gemini 3.8 Flash",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1048576,
"maxOutputTokens": 65536
},
{
"id": "google/gemini-3-flash",
"name": "(Wiro) Gemini 3 Flash",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1048576,
"maxOutputTokens": 65536
},
{
"id": "google/gemini-3-pro",
"name": "(Wiro) Gemini 3 Pro",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1048576,
"maxOutputTokens": 65536
},
{
"id": "google/gemini-4-argon",
"name": "(Wiro) Gemini 4 Argon",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1048576,
"maxOutputTokens": 65536
},
{
"id": "meta-llama/llama-3-2-3b-instruct",
"name": "(Wiro) Llama 3.2 3B Instruct",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 51200,
"maxOutputTokens": 2048
},
{
"id": "mistralai/mistral-7b-instruct-v0-3",
"name": "(Wiro) Mistral 7B Instruct v0.3",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 17408,
"maxOutputTokens": 2048
},
{
"id": "mistralai/mistral-nemo-instruct-2407",
"name": "(Wiro) Mistral Nemo Instruct",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 35840,
"maxOutputTokens": 2048
},
{
"id": "moonshot/kimi-k3-1-pro",
"name": "(Wiro) Kimi K3.1 Pro",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1048576,
"maxOutputTokens": 1048576
},
{
"id": "openai/gpt-5-2",
"name": "(Wiro) GPT-5.2",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 272000,
"maxOutputTokens": 65536
},
{
"id": "openai/gpt-5-4",
"name": "(Wiro) GPT-5.4",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1050000,
"maxOutputTokens": 65536
},
{
"id": "openai/gpt-5-4-mini",
"name": "(Wiro) GPT-5.4 Mini",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 272000,
"maxOutputTokens": 65536
},
{
"id": "openai/gpt-5-4-nano",
"name": "(Wiro) GPT-5.4 Nano",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 272000,
"maxOutputTokens": 65536
},
{
"id": "openai/gpt-5-5",
"name": "(Wiro) GPT-5.5",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1050000,
"maxOutputTokens": 65536
},
{
"id": "openai/gpt-5-6-luna",
"name": "(Wiro) GPT-5.6 Luna",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1050000,
"maxOutputTokens": 65536
},
{
"id": "openai/gpt-5-6-sol",
"name": "(Wiro) GPT-5.6 Sol",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1050000,
"maxOutputTokens": 65536
},
{
"id": "openai/gpt-5-6-terra",
"name": "(Wiro) GPT-5.6 Terra",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1050000,
"maxOutputTokens": 65536
},
{
"id": "openai/gpt-5-mini",
"name": "(Wiro) GPT-5 Mini",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 272000,
"maxOutputTokens": 65536
},
{
"id": "openai/gpt-5-nano",
"name": "(Wiro) GPT-5 Nano",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 272000,
"maxOutputTokens": 65536
},
{
"id": "openai/gpt-6-1-sol",
"name": "(Wiro) GPT-6.1 Sol",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1050000,
"maxOutputTokens": 128000
},
{
"id": "openai/gpt-6-1-terra",
"name": "(Wiro) GPT-6.1 Terra",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1050000,
"maxOutputTokens": 128000
},
{
"id": "openai/gpt-6-astra",
"name": "(Wiro) GPT-6 Astra",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1050000,
"maxOutputTokens": 128000
},
{
"id": "openai/gpt-6-luna",
"name": "(Wiro) GPT-6 Luna",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1050000,
"maxOutputTokens": 128000
},
{
"id": "openai/gpt-6-sol",
"name": "(Wiro) GPT-6 Sol",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 1050000,
"maxOutputTokens": 128000
},
{
"id": "qwen/qwen2-5-0-5b-instruct",
"name": "(Wiro) Qwen2.5 0.5B Instruct",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 32768,
"maxOutputTokens": 2048
},
{
"id": "qwen/qwen2-5-1-5b-instruct",
"name": "(Wiro) Qwen2.5 1.5B Instruct",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 32768,
"maxOutputTokens": 2048
},
{
"id": "qwen/qwen2-5-14b-instruct",
"name": "(Wiro) Qwen2.5 14B Instruct",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 29696,
"maxOutputTokens": 2048
},
{
"id": "qwen/qwen2-5-32b-instruct",
"name": "(Wiro) Qwen2.5 32B Instruct",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 17408,
"maxOutputTokens": 2048
},
{
"id": "qwen/qwen2-5-3b-instruct",
"name": "(Wiro) Qwen2.5 3B Instruct",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 32768,
"maxOutputTokens": 2048
},
{
"id": "qwen/qwen2-5-7b-instruct",
"name": "(Wiro) Qwen2.5 7B Instruct",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 32768,
"maxOutputTokens": 2048
},
{
"id": "qwen/qwen2-5-coder-32b-instruct",
"name": "(Wiro) Qwen2.5 Coder 32B Instruct",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 17408,
"maxOutputTokens": 2048
},
{
"id": "qwen/qwen2-5-coder-7b-instruct",
"name": "(Wiro) Qwen2.5 Coder 7B Instruct",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 32768,
"maxOutputTokens": 2048
},
{
"id": "qwen/qwen3-30b-a3b",
"name": "(Wiro) Qwen3 30B A3B",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 7168,
"maxOutputTokens": 4096
},
{
"id": "qwen/qwen3-30b-a3b-thinking-2507",
"name": "(Wiro) Qwen3 30B A3B Thinking",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 7168,
"maxOutputTokens": 4096
},
{
"id": "qwen/qwen3-32b",
"name": "(Wiro) Qwen3 32B",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 17408,
"maxOutputTokens": 4096
},
{
"id": "qwen/qwen3-5-27b",
"name": "(Wiro) Qwen3.5 27B",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 25600,
"maxOutputTokens": 16384
},
{
"id": "qwen/qwen3-5-27b-heretic",
"name": "(Wiro) Qwen3.5 27B Heretic",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 25600,
"maxOutputTokens": 16384
},
{
"id": "qwen/qwen3-5-4b",
"name": "(Wiro) Qwen3.5 4B",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 72704,
"maxOutputTokens": 16384
},
{
"id": "qwen/qwen3-5-4b-heretic",
"name": "(Wiro) Qwen3.5 4B Heretic",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 72704,
"maxOutputTokens": 16384
},
{
"id": "qwen/qwen3-5-9b",
"name": "(Wiro) Qwen3.5 9B",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 25600,
"maxOutputTokens": 16384
},
{
"id": "qwen/qwen3-5-9b-heretic",
"name": "(Wiro) Qwen3.5 9B Heretic",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 25600,
"maxOutputTokens": 16384
},
{
"id": "qwen/qwen3-6-27b",
"name": "(Wiro) Qwen3.6 27B",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 25600,
"maxOutputTokens": 16384
},
{
"id": "qwen/qwen3-8-27b",
"name": "(Wiro) Qwen3.8 27B",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 25600,
"maxOutputTokens": 16384
},
{
"id": "qwen/qwen3-8-27b-obliterated",
"name": "(Wiro) Qwen3.8 27B Obliterated",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 25600,
"maxOutputTokens": 16384
},
{
"id": "qwen/qwen3-8-27b-uncensored",
"name": "(Wiro) Qwen3.8 27B Uncensored",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 126976,
"maxOutputTokens": 16384
},
{
"id": "ricursiveai/ripple-65b-preview",
"name": "(Wiro) Ripple-65B Preview",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 15360,
"maxOutputTokens": 8192
},
{
"id": "xai/grok-4-1-fast",
"name": "(Wiro) Grok 4.1 Fast",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 2000000,
"maxOutputTokens": 65536
},
{
"id": "xai/grok-4-20",
"name": "(Wiro) Grok 4.20",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 2000000,
"maxOutputTokens": 65536
},
{
"id": "xai/grok-4-5",
"name": "(Wiro) Grok 4.5",
"url": "https://llm.wiro.ai/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 500000,
"maxOutputTokens": 65536
}
]
}
]
id: the lowercaseowner/modelfromGET /v1/models.name: a free label, shown in the picker.url: the full endpoint, not the base URL. Every model repeats it.toolCalling,vision,maxInputTokens,maxOutputTokenscome fromGET /v1/models/{owner}/{model}:capabilities.function_tools,capabilities.input_modalities,max_input_tokens,max_tokens. Do not guess.maxInputTokensis not optional. VS Code sizes every conversation against it and answers “Could not compact conversation” on each turn when a model omits it, before any request reaches the gateway. Take the number frommax_input_tokens; every catalog model reports one. For a Wiro-hosted model the number is the input that deployment actually admits, measured on the running fleet, not the model family’s advertised maximum, and not the window of the checkpoint either. Qwen2.5 7B reports 32,768, which is what its shipped configuration sets although its card says 131,072; Qwen3.8 27B reports 25,600 even though the checkpoint it runs was built for 262,144, because that is roughly how much prompt fits beside the model on the GPUs that serve it. It is the lowest limit measured across them: most requests get somewhat more in and an occasional one slightly less, so leave some headroom. Send a Wiro-hosted model more than fits and the input is trimmed before the model sees it: the oldest history messages are dropped first, and if it still does not fit, the end of the latest user message is cut off. On a turn that returns tool results, nothing from the latest user message onward is cut; if dropping older history is not enough, the request is rejected withcontext_length_exceeded. Tool definitions are never trimmed, and neither is the system message, except on the two Mistral models: their chat format has no system role, so the system text travels with the oldest message and is dropped with it. Both count toward the limit. If even the question would be cut away entirely, the request is rejected withcontext_length_exceededand nothing is charged. In a long prompt, put the question at the start, so a cut takes the material after it rather than the question itself.
Save the file and reopen the model picker; the models appear under Wiro AI. Any other VS Code extension that takes a custom OpenAI base URL (Cline, Roo Code, Continue) works the same way: point it at https://llm.wiro.ai/v1 with the same credential and a model ID from the catalog.
Windsurf
Windsurf now ships as Devin Desktop; the application is Devin.app and its docs redirect to docs.devin.ai. Cascade, its own agent, has no setting for an external provider: there is no base URL to override and no custom model to register, so it cannot be pointed at this gateway. What does work is running a different agent inside the same editor. The steps below use Cline, which is free and Apache-2.0; Roo Code and Continue configure the same way.
-
Open the extension marketplace Command Palette (
Cmd+Shift+P,Ctrl+Shift+Pon Windows) →Extensions: Install Extensions. The menu bar gets you to the same place:Devin → Preferences → Extensions. -
Install Cline Search
clineand install the one published bysaoudrizwan. Devin resolves extensions through the Open VSX mirror, so this is the same build VS Code carries. -
Open the panel Command Palette (
Cmd+Shift+P,Ctrl+Shift+Pon Windows) →Cline: Focus on View. -
Bring my own API key Cline asks how you will use it. Pick the fourth option,
Bring my own API key, thenContinue. The other three are Cline's own billing;Login to Clineis not needed. -
API Provider Choose
OpenAI Compatible, notOpenAI; that one goes to the official OpenAI API. -
Base URL
https://llm.wiro.ai/v1. Cline appends the route itself. -
OpenAI Compatible API Key
YOUR_API_KEY:YOUR_API_SECRETfor a Signature project,YOUR_API_KEYalone for API Key Only. Cline keeps it locally. -
Model ID One ID from the list below; Cline holds a single model per configuration rather than a list. The
(Wiro)prefix is optional and the gateway strips it; it earns its place here by showing up in the status bar, asopenai-compat: (Wiro) openai/gpt-5-6-sol. -
Open
MODEL CONFIGURATIONand set the context window This one matters. Cline does not know a custom model, so it assumes128Kand starts dropping history long before it needs to. Put the real number from the list below intoContext Window size, and tickComputer Useso tool calling is enabled. Without it the agent cannot run tools.Max Output Tokensand the price fields are in the same section. -
Continue, and send a message The status bar names the model you configured.
PlanandActcan each hold a different model, and saved API configuration profiles let you keep one per model and switch between them.
Every model the gateway serves today, with the context window Cline needs. The same numbers come from GET /v1/models as max_input_tokens and max_tokens.
Model ID Context Max Output
----------------------------------------------------------------
(Wiro) bytedance/seed-v2-1-turbo 256000 65536
(Wiro) bytedance/seed-v2-lite 256000 65536
(Wiro) bytedance/seed-v2-mini 256000 65536
(Wiro) bytedance/seed-v2-pro 256000 65536
(Wiro) claude/fable-5 1000000 128000
(Wiro) claude/fable-5-1 1000000 128000
(Wiro) claude/fable-5-2 1000000 128000
(Wiro) claude/opus-5 1000000 128000
(Wiro) claude/opus-5-5 1000000 128000
(Wiro) claude/sonnet-5 1000000 128000
(Wiro) deepseek/v4-1-flash 1000000 384000
(Wiro) deepseek/v4-1-flash-economy 1000000 384000
(Wiro) deepseek/v4-flash 1048576 384000
(Wiro) deepseek/v4-pro 1048576 384000
(Wiro) glm/5-2 1048576 128000
(Wiro) glm/5-3 1000000 128000
(Wiro) google/gemini-2-5-flash 1048576 65536
(Wiro) google/gemini-3-5-flash 1048576 65536
(Wiro) google/gemini-3-5-flash-lite 1048576 65536
(Wiro) google/gemini-3-6-flash 1048576 65536
(Wiro) google/gemini-3-7-flash 1048576 65536
(Wiro) google/gemini-3-8-flash 1048576 65536
(Wiro) google/gemini-3-flash 1048576 65536
(Wiro) google/gemini-3-pro 1048576 65536
(Wiro) google/gemini-4-argon 1048576 65536
(Wiro) meta-llama/llama-3-2-3b-instruct 51200 2048
(Wiro) mistralai/mistral-7b-instruct-v0-3 17408 2048
(Wiro) mistralai/mistral-nemo-instruct-2407 35840 2048
(Wiro) moonshot/kimi-k3-1-pro 1048576 1048576
(Wiro) openai/gpt-5-2 272000 65536
(Wiro) openai/gpt-5-4 1050000 65536
(Wiro) openai/gpt-5-4-mini 272000 65536
(Wiro) openai/gpt-5-4-nano 272000 65536
(Wiro) openai/gpt-5-5 1050000 65536
(Wiro) openai/gpt-5-6-luna 1050000 65536
(Wiro) openai/gpt-5-6-sol 1050000 65536
(Wiro) openai/gpt-5-6-terra 1050000 65536
(Wiro) openai/gpt-5-mini 272000 65536
(Wiro) openai/gpt-5-nano 272000 65536
(Wiro) openai/gpt-6-1-sol 1050000 128000
(Wiro) openai/gpt-6-1-terra 1050000 128000
(Wiro) openai/gpt-6-astra 1050000 128000
(Wiro) openai/gpt-6-luna 1050000 128000
(Wiro) openai/gpt-6-sol 1050000 128000
(Wiro) qwen/qwen2-5-0-5b-instruct 32768 2048
(Wiro) qwen/qwen2-5-1-5b-instruct 32768 2048
(Wiro) qwen/qwen2-5-14b-instruct 29696 2048
(Wiro) qwen/qwen2-5-32b-instruct 17408 2048
(Wiro) qwen/qwen2-5-3b-instruct 32768 2048
(Wiro) qwen/qwen2-5-7b-instruct 32768 2048
(Wiro) qwen/qwen2-5-coder-32b-instruct 17408 2048
(Wiro) qwen/qwen2-5-coder-7b-instruct 32768 2048
(Wiro) qwen/qwen3-30b-a3b 7168 4096
(Wiro) qwen/qwen3-30b-a3b-thinking-2507 7168 4096
(Wiro) qwen/qwen3-32b 17408 4096
(Wiro) qwen/qwen3-5-27b 25600 16384
(Wiro) qwen/qwen3-5-27b-heretic 25600 16384
(Wiro) qwen/qwen3-5-4b 72704 16384
(Wiro) qwen/qwen3-5-4b-heretic 72704 16384
(Wiro) qwen/qwen3-5-9b 25600 16384
(Wiro) qwen/qwen3-5-9b-heretic 25600 16384
(Wiro) qwen/qwen3-6-27b 25600 16384
(Wiro) qwen/qwen3-8-27b 25600 16384
(Wiro) qwen/qwen3-8-27b-obliterated 25600 16384
(Wiro) qwen/qwen3-8-27b-uncensored 126976 16384
(Wiro) ricursiveai/ripple-65b-preview 15360 8192
(Wiro) xai/grok-4-1-fast 2000000 65536
(Wiro) xai/grok-4-20 2000000 65536
(Wiro) xai/grok-4-5 500000 65536
None of this touches Cascade, which keeps using Windsurf's own models. The editor is Devin, the agent is Cline, and the models are Wiro's.
OpenClaw
OpenClaw registers the gateway as a custom provider in its own config file. Everything below lives in one file:
~/.openclaw/openclaw.json macOS, Linux
%USERPROFILE%\.openclaw\openclaw.json Windows
Set OPENCLAW_CONFIG_PATH to put it elsewhere, or run openclaw --profile <name> to keep a separate one under ~/.openclaw-<name>.
-
Install
npm i -g openclaw. -
Name the provider The key under
providers,wirobelow, becomes the prefix you select a model with, aswiro/<id>. Pick any name; the rest of this page assumeswiro. -
Match
apito the model transport Read it fromGET /v1/models/{owner}/{model}.openai-completionsandopenai-responsestake the/v1base;anthropic-messagestakes the origin,https://llm.wiro.ai, with no/v1. One provider block per transport if you mix them. -
Fill
apiKeyYOUR_API_KEY:YOUR_API_SECRETfor a Signature project,YOUR_API_KEYalone for API Key Only. -
List the models Each entry takes an
idand a displayname. Theidis what reaches the gateway, so the(Wiro)label is optional there and stripped on arrival; thenameis only ever shown to you. Both carry it below so the CLI and the picker read the same. -
Run a turn
openclaw agent --local --model "wiro/(Wiro) xai/grok-4-1-fast" -m "your prompt".--localruns the embedded agent against these credentials; without it the turn goes through an OpenClaw gateway instead.
Every model the gateway serves today, ready to paste as the whole models array. The same set is in the catalog and behind GET /v1/models.
{
"models": {
"providers": {
"wiro": {
"baseUrl": "https://llm.wiro.ai/v1",
"apiKey": "YOUR_API_KEY:YOUR_API_SECRET",
"api": "openai-completions",
"models": [
{ "id": "(Wiro) bytedance/seed-v2-1-turbo", "name": "(Wiro) Seed V2.1 Turbo" },
{ "id": "(Wiro) bytedance/seed-v2-lite", "name": "(Wiro) Seed V2 Lite" },
{ "id": "(Wiro) bytedance/seed-v2-mini", "name": "(Wiro) Seed V2 Mini" },
{ "id": "(Wiro) bytedance/seed-v2-pro", "name": "(Wiro) Seed V2 Pro" },
{ "id": "(Wiro) claude/fable-5", "name": "(Wiro) Fable 5" },
{ "id": "(Wiro) claude/fable-5-1", "name": "(Wiro) Fable 5.1" },
{ "id": "(Wiro) claude/fable-5-2", "name": "(Wiro) Fable 5.2" },
{ "id": "(Wiro) claude/opus-5", "name": "(Wiro) Opus 5" },
{ "id": "(Wiro) claude/opus-5-5", "name": "(Wiro) Opus 5.5" },
{ "id": "(Wiro) claude/sonnet-5", "name": "(Wiro) Sonnet 5" },
{ "id": "(Wiro) deepseek/v4-1-flash", "name": "(Wiro) DeepSeek V4.1 Flash" },
{ "id": "(Wiro) deepseek/v4-1-flash-economy", "name": "(Wiro) DeepSeek V4.1 Flash Economy" },
{ "id": "(Wiro) deepseek/v4-flash", "name": "(Wiro) DeepSeek V4 Flash" },
{ "id": "(Wiro) deepseek/v4-pro", "name": "(Wiro) DeepSeek V4 Pro" },
{ "id": "(Wiro) glm/5-2", "name": "(Wiro) GLM 5.2" },
{ "id": "(Wiro) glm/5-3", "name": "(Wiro) GLM 5.3" },
{ "id": "(Wiro) google/gemini-2-5-flash", "name": "(Wiro) Gemini 2.5 Flash" },
{ "id": "(Wiro) google/gemini-3-5-flash", "name": "(Wiro) Gemini 3.5 Flash" },
{ "id": "(Wiro) google/gemini-3-5-flash-lite", "name": "(Wiro) Gemini 3.5 Flash-Lite" },
{ "id": "(Wiro) google/gemini-3-6-flash", "name": "(Wiro) Gemini 3.6 Flash" },
{ "id": "(Wiro) google/gemini-3-7-flash", "name": "(Wiro) Gemini 3.7 Flash" },
{ "id": "(Wiro) google/gemini-3-8-flash", "name": "(Wiro) Gemini 3.8 Flash" },
{ "id": "(Wiro) google/gemini-3-flash", "name": "(Wiro) Gemini 3 Flash" },
{ "id": "(Wiro) google/gemini-3-pro", "name": "(Wiro) Gemini 3 Pro" },
{ "id": "(Wiro) google/gemini-4-argon", "name": "(Wiro) Gemini 4 Argon" },
{ "id": "(Wiro) meta-llama/llama-3-2-3b-instruct", "name": "(Wiro) Llama 3.2 3B Instruct" },
{ "id": "(Wiro) mistralai/mistral-7b-instruct-v0-3", "name": "(Wiro) Mistral 7B Instruct v0.3" },
{ "id": "(Wiro) mistralai/mistral-nemo-instruct-2407", "name": "(Wiro) Mistral Nemo Instruct" },
{ "id": "(Wiro) moonshot/kimi-k3-1-pro", "name": "(Wiro) Kimi K3.1 Pro" },
{ "id": "(Wiro) openai/gpt-5-2", "name": "(Wiro) GPT-5.2" },
{ "id": "(Wiro) openai/gpt-5-4", "name": "(Wiro) GPT-5.4" },
{ "id": "(Wiro) openai/gpt-5-4-mini", "name": "(Wiro) GPT-5.4 Mini" },
{ "id": "(Wiro) openai/gpt-5-4-nano", "name": "(Wiro) GPT-5.4 Nano" },
{ "id": "(Wiro) openai/gpt-5-5", "name": "(Wiro) GPT-5.5" },
{ "id": "(Wiro) openai/gpt-5-6-luna", "name": "(Wiro) GPT-5.6 Luna" },
{ "id": "(Wiro) openai/gpt-5-6-sol", "name": "(Wiro) GPT-5.6 Sol" },
{ "id": "(Wiro) openai/gpt-5-6-terra", "name": "(Wiro) GPT-5.6 Terra" },
{ "id": "(Wiro) openai/gpt-5-mini", "name": "(Wiro) GPT-5 Mini" },
{ "id": "(Wiro) openai/gpt-5-nano", "name": "(Wiro) GPT-5 Nano" },
{ "id": "(Wiro) openai/gpt-6-1-sol", "name": "(Wiro) GPT-6.1 Sol" },
{ "id": "(Wiro) openai/gpt-6-1-terra", "name": "(Wiro) GPT-6.1 Terra" },
{ "id": "(Wiro) openai/gpt-6-astra", "name": "(Wiro) GPT-6 Astra" },
{ "id": "(Wiro) openai/gpt-6-luna", "name": "(Wiro) GPT-6 Luna" },
{ "id": "(Wiro) openai/gpt-6-sol", "name": "(Wiro) GPT-6 Sol" },
{ "id": "(Wiro) qwen/qwen2-5-0-5b-instruct", "name": "(Wiro) Qwen2.5 0.5B Instruct" },
{ "id": "(Wiro) qwen/qwen2-5-1-5b-instruct", "name": "(Wiro) Qwen2.5 1.5B Instruct" },
{ "id": "(Wiro) qwen/qwen2-5-14b-instruct", "name": "(Wiro) Qwen2.5 14B Instruct" },
{ "id": "(Wiro) qwen/qwen2-5-32b-instruct", "name": "(Wiro) Qwen2.5 32B Instruct" },
{ "id": "(Wiro) qwen/qwen2-5-3b-instruct", "name": "(Wiro) Qwen2.5 3B Instruct" },
{ "id": "(Wiro) qwen/qwen2-5-7b-instruct", "name": "(Wiro) Qwen2.5 7B Instruct" },
{ "id": "(Wiro) qwen/qwen2-5-coder-32b-instruct", "name": "(Wiro) Qwen2.5 Coder 32B Instruct" },
{ "id": "(Wiro) qwen/qwen2-5-coder-7b-instruct", "name": "(Wiro) Qwen2.5 Coder 7B Instruct" },
{ "id": "(Wiro) qwen/qwen3-30b-a3b", "name": "(Wiro) Qwen3 30B A3B" },
{ "id": "(Wiro) qwen/qwen3-30b-a3b-thinking-2507", "name": "(Wiro) Qwen3 30B A3B Thinking" },
{ "id": "(Wiro) qwen/qwen3-32b", "name": "(Wiro) Qwen3 32B" },
{ "id": "(Wiro) qwen/qwen3-5-27b", "name": "(Wiro) Qwen3.5 27B" },
{ "id": "(Wiro) qwen/qwen3-5-27b-heretic", "name": "(Wiro) Qwen3.5 27B Heretic" },
{ "id": "(Wiro) qwen/qwen3-5-4b", "name": "(Wiro) Qwen3.5 4B" },
{ "id": "(Wiro) qwen/qwen3-5-4b-heretic", "name": "(Wiro) Qwen3.5 4B Heretic" },
{ "id": "(Wiro) qwen/qwen3-5-9b", "name": "(Wiro) Qwen3.5 9B" },
{ "id": "(Wiro) qwen/qwen3-5-9b-heretic", "name": "(Wiro) Qwen3.5 9B Heretic" },
{ "id": "(Wiro) qwen/qwen3-6-27b", "name": "(Wiro) Qwen3.6 27B" },
{ "id": "(Wiro) qwen/qwen3-8-27b", "name": "(Wiro) Qwen3.8 27B" },
{ "id": "(Wiro) qwen/qwen3-8-27b-obliterated", "name": "(Wiro) Qwen3.8 27B Obliterated" },
{ "id": "(Wiro) qwen/qwen3-8-27b-uncensored", "name": "(Wiro) Qwen3.8 27B Uncensored" },
{ "id": "(Wiro) ricursiveai/ripple-65b-preview", "name": "(Wiro) Ripple-65B Preview" },
{ "id": "(Wiro) xai/grok-4-1-fast", "name": "(Wiro) Grok 4.1 Fast" },
{ "id": "(Wiro) xai/grok-4-20", "name": "(Wiro) Grok 4.20" },
{ "id": "(Wiro) xai/grok-4-5", "name": "(Wiro) Grok 4.5" }
]
}
}
}
}
Tool calling works through the gateway, so the agent can run its own tools across as many turns as the task needs.
Hermes
Install the Wiro AI plugin
On Hermes 0.22.6 or later, the wiro plugin adds the gateway as a model provider. Install it, set your key and pick a model:
hermes plugins install wiro
hermes config set WIRO_API_KEY YOUR_API_KEY:YOUR_API_SECRET
hermes model
Use YOUR_API_KEY alone for API Key Only. In hermes model, select Wiro AI; the list comes from GET /v1/models. For one run, hermes chat --provider wiro -m claude/sonnet-5. The wiro-media plugin in the same repository adds image, video, speech, music, transcription and 3D tools with the same key.
Or set it up as a custom provider
Hermes Agent, from Nous Research, reaches the gateway as a custom provider. Its whole configuration is one file:
~/.hermes/config.yaml
Set HERMES_HOME to put it elsewhere; the project’s own Docker image already points it at /opt/data. The file the repository ships as cli-config.yaml.example is read under the name config.yaml.
-
Install
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bashon macOS, Linux and WSL2;iex (irm https://hermes-agent.nousresearch.com/install.ps1)in PowerShell. The repository also carries aDockerfileand adocker-compose.yml. -
Choose the custom provider
provider: "custom"is Hermes’ name for any OpenAI-compatible endpoint;ollama,vllmandllamacppare aliases of it. With it,base_urlis what decides where the request goes. -
Fill
api_keyYOUR_API_KEY:YOUR_API_SECRETfor a Signature project,YOUR_API_KEYalone for API Key Only. -
Name the model
model.defaulttakes one ID from the list below. Hermes holds a single default rather than a list, so the(Wiro)label is there for your own benefit; the gateway strips it either way. -
Run a turn
hermes -z "your prompt"for one shot,hermes chatfor a session. Add--yolowhen you want the agent to use its tools without stopping for approval. -
Switch models
hermes -m "(Wiro) xai/grok-4-1-fast" -z "your prompt"overrides the default for one run;hermes modelchanges it for good.
model:
default: "(Wiro) openai/gpt-5-6-sol"
provider: "custom"
base_url: "https://llm.wiro.ai/v1"
api_key: "YOUR_API_KEY:YOUR_API_SECRET"
Every model the gateway serves today. The same set is in the catalog and behind GET /v1/models.
(Wiro) bytedance/seed-v2-1-turbo
(Wiro) bytedance/seed-v2-lite
(Wiro) bytedance/seed-v2-mini
(Wiro) bytedance/seed-v2-pro
(Wiro) claude/fable-5
(Wiro) claude/fable-5-1
(Wiro) claude/fable-5-2
(Wiro) claude/opus-5
(Wiro) claude/opus-5-5
(Wiro) claude/sonnet-5
(Wiro) deepseek/v4-1-flash
(Wiro) deepseek/v4-1-flash-economy
(Wiro) deepseek/v4-flash
(Wiro) deepseek/v4-pro
(Wiro) glm/5-2
(Wiro) glm/5-3
(Wiro) google/gemini-2-5-flash
(Wiro) google/gemini-3-5-flash
(Wiro) google/gemini-3-5-flash-lite
(Wiro) google/gemini-3-6-flash
(Wiro) google/gemini-3-7-flash
(Wiro) google/gemini-3-8-flash
(Wiro) google/gemini-3-flash
(Wiro) google/gemini-3-pro
(Wiro) google/gemini-4-argon
(Wiro) meta-llama/llama-3-2-3b-instruct
(Wiro) mistralai/mistral-7b-instruct-v0-3
(Wiro) mistralai/mistral-nemo-instruct-2407
(Wiro) moonshot/kimi-k3-1-pro
(Wiro) openai/gpt-5-2
(Wiro) openai/gpt-5-4
(Wiro) openai/gpt-5-4-mini
(Wiro) openai/gpt-5-4-nano
(Wiro) openai/gpt-5-5
(Wiro) openai/gpt-5-6-luna
(Wiro) openai/gpt-5-6-sol
(Wiro) openai/gpt-5-6-terra
(Wiro) openai/gpt-5-mini
(Wiro) openai/gpt-5-nano
(Wiro) openai/gpt-6-1-sol
(Wiro) openai/gpt-6-1-terra
(Wiro) openai/gpt-6-astra
(Wiro) openai/gpt-6-luna
(Wiro) openai/gpt-6-sol
(Wiro) qwen/qwen2-5-0-5b-instruct
(Wiro) qwen/qwen2-5-1-5b-instruct
(Wiro) qwen/qwen2-5-14b-instruct
(Wiro) qwen/qwen2-5-32b-instruct
(Wiro) qwen/qwen2-5-3b-instruct
(Wiro) qwen/qwen2-5-7b-instruct
(Wiro) qwen/qwen2-5-coder-32b-instruct
(Wiro) qwen/qwen2-5-coder-7b-instruct
(Wiro) qwen/qwen3-30b-a3b
(Wiro) qwen/qwen3-30b-a3b-thinking-2507
(Wiro) qwen/qwen3-32b
(Wiro) qwen/qwen3-5-27b
(Wiro) qwen/qwen3-5-27b-heretic
(Wiro) qwen/qwen3-5-4b
(Wiro) qwen/qwen3-5-4b-heretic
(Wiro) qwen/qwen3-5-9b
(Wiro) qwen/qwen3-5-9b-heretic
(Wiro) qwen/qwen3-6-27b
(Wiro) qwen/qwen3-8-27b
(Wiro) qwen/qwen3-8-27b-obliterated
(Wiro) qwen/qwen3-8-27b-uncensored
(Wiro) ricursiveai/ripple-65b-preview
(Wiro) xai/grok-4-1-fast
(Wiro) xai/grok-4-20
(Wiro) xai/grok-4-5
Tool calling works through the gateway, so the agent can run its own tools across as many turns as the task needs.
goose
goose reaches the gateway as a custom provider. The whole definition is one JSON file in its custom_providers folder:
~/.config/goose/custom_providers/wiro.json
That path is for macOS and Linux. On Windows the folder is %APPDATA%\Block\goose\config\custom_providers.
-
Save the file Paste the JSON below into
wiro.jsonin that folder. goose Desktop and the goose CLI read the same file, and Wiro AI then shows up in the provider list. -
Set the key
WIRO_API_KEYtakesYOUR_API_KEY:YOUR_API_SECRETfor a Signature project,YOUR_API_KEYalone for API Key Only. Export it in your shell, or enter it once under Settings > Models > Configure providers > Wiro AI in goose Desktop (goose configure> Configure Providers in the CLI) to keep it in the keychain. -
Pick a model With
dynamic_modelson, goose readsGET /v1/modelswhen you configure the provider, so every gateway model is selectable. Themodelsarray is the fallback list, with each model's context window. -
Run a turn
goose run --provider wiro --model claude/opus-5-5 -t "your prompt"for one shot, orgoose sessionafter choosing Wiro AI as the provider.
{
"name": "wiro",
"engine": "openai",
"display_name": "Wiro AI",
"description": "Hosted OpenAI-compatible gateway for Claude, GPT, Gemini, Grok, DeepSeek, Kimi, GLM and more, billed per call from a prepaid Wiro wallet.",
"api_key_env": "WIRO_API_KEY",
"base_url": "https://llm.wiro.ai/v1",
"dynamic_models": true,
"models": [
{ "name": "claude/opus-5-5", "context_limit": 1000000 },
{ "name": "claude/sonnet-5", "context_limit": 1000000 },
{ "name": "claude/fable-5-2", "context_limit": 1000000 },
{ "name": "openai/gpt-6-1-sol", "context_limit": 1050000 },
{ "name": "openai/gpt-5-5", "context_limit": 1050000 },
{ "name": "google/gemini-4-argon", "context_limit": 1048576 },
{ "name": "google/gemini-3-8-flash", "context_limit": 1048576 },
{ "name": "xai/grok-4-5", "context_limit": 500000 },
{ "name": "xai/grok-4-1-fast", "context_limit": 2000000 },
{ "name": "deepseek/v4-pro", "context_limit": 1048576 },
{ "name": "moonshot/kimi-k3-1-pro", "context_limit": 1048576 },
{ "name": "glm/5-3", "context_limit": 1000000 }
],
"supports_streaming": true,
"requires_auth": true,
"model_doc_link": "https://wiro.ai/models?categories=llm-tool-call",
"setup_steps": [
"Create a project at https://wiro.ai/panel/project/new and copy its API key",
"For a Signature project, enter YOUR_API_KEY:YOUR_API_SECRET; for API Key Only, the key alone",
"Paste it above as WIRO_API_KEY"
]
}
Tool calling works through the gateway, so goose can run its extensions across as many turns as the task needs.
OpenAI SDK
The official openai package talks to the gateway unchanged. Only baseURL moves. Everything below was run against every model the gateway serves.
-
Install
npm i openai. The Python package works the same way withbase_url. -
Point the client at the gateway
baseURLishttps://llm.wiro.ai/v1.apiKeytakesYOUR_API_KEY:YOUR_API_SECRETfor a Signature project,YOUR_API_KEYalone for API Key Only. -
Name a model Any ID from the list below. The
(Wiro)label is optional and stripped on arrival, soopenai/gpt-5-6-solworks just as well. -
Give reasoning models room
max_completion_tokenscovers reasoning as well as the answer. Too small a budget returnsfinish_reason: "length"with empty content. That is not an error, just a spent budget. A model that reasons by default can use several hundred tokens before it starts the answer, so raise the budget or lowerreasoning_effortwhen that happens.
import OpenAI from "openai";
const client = new OpenAI({
apiKey: "YOUR_API_KEY:YOUR_API_SECRET",
baseURL: "https://llm.wiro.ai/v1",
});
const completion = await client.chat.completions.create({
model: "(Wiro) openai/gpt-5-6-sol",
max_completion_tokens: 512,
messages: [{ role: "user", content: "Hello" }],
});
console.log(completion.choices[0].message.content);
client.models.list() returns the same catalog, and client.responses.create() reaches the Responses route. Streaming works on both.
Tool calling runs the whole loop (the call, the result, and further turns after it):
const tools = [{
type: "function",
function: {
name: "get_weather",
description: "Get weather",
parameters: {
type: "object",
properties: { city: { type: "string" } },
required: ["city"],
},
},
}];
const messages = [{ role: "user", content: "Weather in Istanbul?" }];
const first = await client.chat.completions.create({
model: "(Wiro) openai/gpt-5-6-sol", max_completion_tokens: 512, tools, messages,
});
const call = first.choices[0].message.tool_calls[0];
messages.push(first.choices[0].message, {
role: "tool",
tool_call_id: call.id,
content: JSON.stringify({ temperature_c: 21 }),
});
const second = await client.chat.completions.create({
model: "(Wiro) openai/gpt-5-6-sol", max_completion_tokens: 512, tools, messages,
});
Every model the gateway serves today. The same set is in the catalog and behind GET /v1/models.
(Wiro) bytedance/seed-v2-1-turbo
(Wiro) bytedance/seed-v2-lite
(Wiro) bytedance/seed-v2-mini
(Wiro) bytedance/seed-v2-pro
(Wiro) claude/fable-5
(Wiro) claude/fable-5-1
(Wiro) claude/fable-5-2
(Wiro) claude/opus-5
(Wiro) claude/opus-5-5
(Wiro) claude/sonnet-5
(Wiro) deepseek/v4-1-flash
(Wiro) deepseek/v4-1-flash-economy
(Wiro) deepseek/v4-flash
(Wiro) deepseek/v4-pro
(Wiro) glm/5-2
(Wiro) glm/5-3
(Wiro) google/gemini-2-5-flash
(Wiro) google/gemini-3-5-flash
(Wiro) google/gemini-3-5-flash-lite
(Wiro) google/gemini-3-6-flash
(Wiro) google/gemini-3-7-flash
(Wiro) google/gemini-3-8-flash
(Wiro) google/gemini-3-flash
(Wiro) google/gemini-3-pro
(Wiro) google/gemini-4-argon
(Wiro) meta-llama/llama-3-2-3b-instruct
(Wiro) mistralai/mistral-7b-instruct-v0-3
(Wiro) mistralai/mistral-nemo-instruct-2407
(Wiro) moonshot/kimi-k3-1-pro
(Wiro) openai/gpt-5-2
(Wiro) openai/gpt-5-4
(Wiro) openai/gpt-5-4-mini
(Wiro) openai/gpt-5-4-nano
(Wiro) openai/gpt-5-5
(Wiro) openai/gpt-5-6-luna
(Wiro) openai/gpt-5-6-sol
(Wiro) openai/gpt-5-6-terra
(Wiro) openai/gpt-5-mini
(Wiro) openai/gpt-5-nano
(Wiro) openai/gpt-6-1-sol
(Wiro) openai/gpt-6-1-terra
(Wiro) openai/gpt-6-astra
(Wiro) openai/gpt-6-luna
(Wiro) openai/gpt-6-sol
(Wiro) qwen/qwen2-5-0-5b-instruct
(Wiro) qwen/qwen2-5-1-5b-instruct
(Wiro) qwen/qwen2-5-14b-instruct
(Wiro) qwen/qwen2-5-32b-instruct
(Wiro) qwen/qwen2-5-3b-instruct
(Wiro) qwen/qwen2-5-7b-instruct
(Wiro) qwen/qwen2-5-coder-32b-instruct
(Wiro) qwen/qwen2-5-coder-7b-instruct
(Wiro) qwen/qwen3-30b-a3b
(Wiro) qwen/qwen3-30b-a3b-thinking-2507
(Wiro) qwen/qwen3-32b
(Wiro) qwen/qwen3-5-27b
(Wiro) qwen/qwen3-5-27b-heretic
(Wiro) qwen/qwen3-5-4b
(Wiro) qwen/qwen3-5-4b-heretic
(Wiro) qwen/qwen3-5-9b
(Wiro) qwen/qwen3-5-9b-heretic
(Wiro) qwen/qwen3-6-27b
(Wiro) qwen/qwen3-8-27b
(Wiro) qwen/qwen3-8-27b-obliterated
(Wiro) qwen/qwen3-8-27b-uncensored
(Wiro) ricursiveai/ripple-65b-preview
(Wiro) xai/grok-4-1-fast
(Wiro) xai/grok-4-20
(Wiro) xai/grok-4-5
Vercel AI SDK
@wiro-ai/wiro-llm is Wiro's provider for the AI SDK from Vercel. Its chat models use this gateway, and its image, speech, transcription and video models use the Run API, with the same key. It reads the key from WIRO_API_KEY, reports token usage on streamed calls, sends an Output.object schema as json_schema, and returns the cost of each call in providerMetadata.wiro. The examples below were tested with @wiro-ai/wiro-llm 0.2.0, ai 7.0.170 and zod 4.6.7.
-
Install
npm i @wiro-ai/wiro-llm ai zod. The package needs Node.js 22 or later, like AI SDK 7.zodis only needed for tools and structured output. -
Keep the key on the server Put the project credential in
WIRO_API_KEY:YOUR_API_KEYfor an API Key Only project,YOUR_API_KEY:YOUR_API_SECRETfor a Signature project. Image, speech, transcription and video calls sign every request of a Signature project with the secret, and the secret itself is never sent. Call Wiro from server code so the key never reaches a browser. -
Name a model Chat models take any ID from the catalog or
GET /v1/models, such asopenai/gpt-5-4-nanoordeepseek/v4-1-flash. Image, speech, transcription and video models take theowner/modelID of a model in the model catalog, such aspruna/p-image.
import { wiro } from "@wiro-ai/wiro-llm";
import { generateText } from "ai";
const { text, providerMetadata } = await generateText({
model: wiro("openai/gpt-5-4-nano"),
prompt: "Explain what an API gateway does in one sentence.",
});
console.log(text);
console.log(providerMetadata?.wiro?.cost);
wiro reads WIRO_API_KEY when it sends a request. createWiro builds a provider with your own apiKey, baseURL, runBaseURL, poll, headers or fetch:
import { createWiro } from "@wiro-ai/wiro-llm";
const wiro = createWiro({ apiKey: process.env.MY_WIRO_KEY });
streamText streams the answer. When a model thinks before it answers, its reasoning comes separately in reasoningText, and the token counts and the cost arrive at the end:
import { streamText } from "ai";
const result = streamText({
model: wiro("deepseek/v4-1-flash"),
prompt: "Write a two-line poem about routing requests.",
});
for await (const part of result.textStream) {
process.stdout.write(part);
}
console.log(await result.usage);
console.log((await result.providerMetadata)?.wiro?.cost);
Tools run as a loop: the model calls the tool, the SDK runs execute and sends the result back, and the model writes the answer. stopWhen caps the number of steps. Each step is a separate request, and each entry in steps carries its own providerMetadata.wiro.cost:
import { generateText, isStepCount, tool } from "ai";
import { z } from "zod";
const { text } = await generateText({
model: wiro("openai/gpt-5-4-nano"),
tools: {
getWeather: tool({
description: "Get the current weather for a city",
inputSchema: z.object({ city: z.string() }),
execute: async ({ city }) => ({ city, temperatureC: 21 }),
}),
},
stopWhen: isStepCount(3),
prompt: "What is the weather in Istanbul right now?",
});
Structured output needs a model whose structured_output_modes include json_schema:
import { generateText, Output } from "ai";
import { z } from "zod";
const { output } = await generateText({
model: wiro("openai/gpt-5-4-nano"),
output: Output.object({
schema: z.object({ name: z.string(), country: z.string(), population: z.number() }),
}),
prompt: "Give me the largest city in Turkey.",
});
On reasoning models, providerOptions: { wiro: { reasoningEffort: "low" } } sends reasoning_effort. Use it only on models that list reasoning_effort in supported_parameters.
Its chat models are built on the AI SDK's OpenAI Compatible provider, which also works on its own: createOpenAICompatible from @ai-sdk/openai-compatible with base URL https://llm.wiro.ai/v1, includeUsage: true and supportsStructuredOutputs: true.
The gateway's other two routes work with the AI SDK's own providers: @ai-sdk/openai reaches Responses and @ai-sdk/anthropic reaches Anthropic Messages. Both take the same /v1 base URL. Unlike the Anthropic SDK, @ai-sdk/anthropic expects the /v1 in it. It caps output at 4,096 tokens for model IDs it does not know, so pass maxOutputTokens for longer answers.
import { createAnthropic } from "@ai-sdk/anthropic";
import { createOpenAI } from "@ai-sdk/openai";
const openai = createOpenAI({
baseURL: "https://llm.wiro.ai/v1",
apiKey: process.env.WIRO_API_KEY,
});
const anthropic = createAnthropic({
baseURL: "https://llm.wiro.ai/v1",
apiKey: process.env.WIRO_API_KEY,
});
const viaResponses = openai.responses("openai/gpt-5-4-nano");
const viaMessages = anthropic("claude/sonnet-5");
Images
wiro.image creates an image model for generateImage. n, size, aspectRatio and seed go to the model's own settings, whatever the model calls them, and a value the model does not offer comes back in warnings:
import { writeFile } from "node:fs/promises";
import { generateImage } from "ai";
const { image, providerMetadata } = await generateImage({
model: wiro.image("pruna/p-image"),
prompt: "A red lighthouse on a rocky coast at dusk, warm light in the windows",
aspectRatio: "16:9",
seed: 42,
});
await writeFile("lighthouse.jpg", image.uint8Array);
console.log(providerMetadata.wiro.images[0]); // { taskId, cost, url, mediaType }
To edit an image, pass it in prompt.images to a model that takes input images, such as google/nano-banana, openai/gpt-image-2 or wiro/flux-2-dev. Images can be bytes, base64 strings or public URLs, and prompt.mask goes to models that take a mask:
import { readFile } from "node:fs/promises";
import { generateImage } from "ai";
const { image } = await generateImage({
model: wiro.image("google/nano-banana"),
prompt: {
text: "Turn this photo into a soft watercolor painting",
images: [await readFile("photo.jpg")],
},
});
Each model's own settings, listed on its catalog page, go in providerOptions.wiro as they are, for example providerOptions: { wiro: { quality: "high" } } on openai/gpt-image-2. Required settings you leave out get the model's default.
Speech
wiro.speech creates a text-to-speech model for generateSpeech. voice matches the model's voices by ID or by name, language takes ISO 639-1 codes such as en or tr, and outputFormat, instructions and speed go to models that have them:
import { writeFile } from "node:fs/promises";
import { generateSpeech } from "ai";
const { audio, providerMetadata } = await generateSpeech({
model: wiro.speech("elevenlabs/eleven-v4-turbo"),
text: "Hello from Wiro AI. This sentence was turned into speech.",
voice: "alice",
language: "en",
outputFormat: "mp3",
});
await writeFile("hello.mp3", audio.uint8Array);
console.log(providerMetadata.wiro); // { taskId, cost, elapsedSeconds, url, mediaType }
Transcription
wiro.transcription creates a speech-to-text model for transcribe. Audio can be bytes, base64 or a URL; a public URL such as new URL("https://example.com/talk.mp3") goes to Wiro as it is, so the file never passes through your server. segments holds the timings a model writes:
import { readFile } from "node:fs/promises";
import { transcribe } from "ai";
const { text, segments } = await transcribe({
model: wiro.transcription("openai/whisper-large-v3"),
audio: await readFile("hello.mp3"),
});
console.log(text);
console.log(segments); // [{ text, startSecond, endSecond }]
Video
wiro.video creates a video model for experimental_generateVideo. A start image goes in prompt: { image, text }, and aspectRatio, resolution, duration, fps, seed and generateAudio go to the model's matching settings:
import { writeFile } from "node:fs/promises";
import { experimental_generateVideo as generateVideo } from "ai";
const { video, providerMetadata } = await generateVideo({
model: wiro.video("bytedance/seedance-v1-pro-fast"),
prompt: "A paper boat drifting on a calm pond, soft morning light",
resolution: "864x480",
duration: 5,
});
await writeFile("boat.mp4", video.uint8Array);
console.log(providerMetadata.wiro.videos[0]); // { taskId, cost, url, mediaType }
Video calls use the AI SDK's start and status flow, so the poll and webhook options, experimental_startVideo and experimental_getVideoStatus work with them.
Tasks and cost
Image, speech, transcription and video calls run as Wiro tasks: the provider starts the run, waits for the task and downloads the result. The task ID and what it cost, in USD, are in providerMetadata.wiro: for each image and video under images and videos, and at the top level for speech and transcription. Image, speech and transcription calls wait up to 10 minutes; createWiro({ poll: { timeoutMs } }) changes that. A task that ends without a result throws a WiroTaskError with its taskId and a reason.
Start from a Next.js app
Wiro-Next-Starter is a Next.js app built on this provider: a Playground for any model in the catalog, image, video and audio tools, chat with the gateway’s models and a run history. Deploy it on Vercel or Railway with your WIRO_API_KEY.
Discover models and capabilities
GET /v1/models
curl "https://llm.wiro.ai/v1/models?search=openai%2Fgpt-5-6-sol&limit=1"
Model discovery needs no API key. A request that sends a key is still checked, so a wrong key returns 401 as on every other route. GET /v1/chat/models returns the same list. The gateway catalog is separate from the full catalog at POST /v1/Tool/List.
{
"object": "list",
"data": [
{
"id": "openai/gpt-5-6-sol",
"canonical_slug": "openai/gpt-5-6-sol",
"name": "(Wiro) GPT 5.6 Sol by OpenAI (Vision)",
"description": "OpenAI’s GPT 5.6 Sol is a flagship reasoning model that can analyze images and produce detailed text answers for coding, research, and visual Q&A.",
"context_length": 1050000,
"architecture": {
"modality": "text+image+file->text",
"input_modalities": ["text", "image", "file"],
"output_modalities": ["text"]
},
"pricing": {
"prompt": "0.000005",
"completion": "0.00003"
},
"top_provider": {
"context_length": 1050000,
"max_completion_tokens": 65536,
"min_completion_tokens": 16
},
"supported_parameters": [
"max_completion_tokens",
"max_tokens",
"parallel_tool_calls",
"reasoning_effort",
"response_format",
"structured_outputs",
"tool_choice",
"tools"
],
"default_parameters": {
"reasoning_effort": "medium"
},
"object": "model",
"type": "model",
"created": 1783670833,
"created_at": "2026-07-10T08:07:13.000Z",
"owned_by": "openai",
"display_name": "(Wiro) GPT 5.6 Sol by OpenAI (Vision)",
"max_input_tokens": 1050000,
"max_tokens": 65536,
"min_tokens": 16,
"capabilities": {
"endpoints": ["anthropic", "chat", "responses"],
"input_modalities": ["text", "image", "document"],
"output": ["text", "function_calls", "custom_tool_calls"],
"function_tools": true,
"custom_tools": true,
"structured_outputs": true,
"structured_output_modes": ["json_object", "json_schema"],
"strict_json_schema": true,
"generation_controls": ["max_output_tokens", "reasoning_effort", "verbosity"]
},
"x_wiro": {
"pricing_source": {
"name": "wiro-pricing-catalog",
"schema_version": 1,
"revision": "0123456789abcdef0123456789abcdef01234567",
"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"source_model": "openai/gpt-5.6-sol",
"basis": "local-rate"
},
"pricing_tiers": null
}
}
],
"total_count": 1,
"links": {
"next": null
},
"has_more": false,
"first_id": "openai/gpt-5-6-sol",
"last_id": "openai/gpt-5-6-sol"
}
The example is intentionally explicit about nullable values that have a Wiro source. Context, modalities, and pricing come from Wiro's model catalog; live Run parameters and capability flags come from the selected model's current Tool/Detail contract. Fields Wiro does not publish are omitted. pricing.prompt and pricing.completion are USD-per-token strings. Models with tiered rates expose those exact bands in x_wiro.pricing_tiers. Pricing and context fields can be null when the catalog has no value for them. pricing is null for models that are not billed at a fixed token rate: Wiro-hosted models are billed by processing time, and models whose x_wiro.pricing_source.basis is provider-reported-usd-ticks are billed at the cost the provider reports for each call. Every response still carries its billed amount in usage.cost.
top_provider.min_completion_tokens and min_tokens are the smallest output cap the model runs with, beside the largest in max_completion_tokens and max_tokens. A smaller cap is raised to that value (see OpenAI Chat Completions below), and both are null when the model takes no output cap. On models with an effort setting, default_parameters.reasoning_effort is the effort a request runs at when it sends none.
The list accepts:
search(at most 256 bytes),order=asc|desc, andlimit=1..1000after/after_idorbefore/before_idcursors
The default order is ascending and the default limit is 1000. total_count counts the filtered catalog. links.next is a relative next-page URL or null.
The discovery list contains the models verified with the llm-tool-call category. It is not filtered by Model Access rules: a model a rule blocks is still listed, but calling it fails. Other LLMs are not advertised by this endpoint; when you already know an exact owner/model ID, you can still submit it to a compatible Direct LLM route or use the normal Run API.
Before each request:
- Confirm
anthropic,chat, orresponsesincapabilities.endpoints. - Use
supported_parametersto gate optional public request controls. Required protocol fields such asmodel,input,messages, or Anthropicmax_tokensare not repeated there. - Check
capabilities.input_modalitiesfor canonicaltext,image, ordocument. OpenRouter-stylearchitecture.input_modalitiesrepresents documents asfile. - Check
capabilities.output,function_tools,custom_tools,structured_outputs,structured_output_modes,strict_json_schema, andgeneration_controls. - Treat
context_length,max_input_tokens,max_tokens, pricing, and usage as model-specific. A nullable field is not permission to infer a value from another model.
Every discoverable model currently publishes the same endpoint labels. Capability differences are expressed through modalities, supported parameters, tool flags, structured-output flags, reasoning controls, and limits.
Structured-output support is per model, not per family: read structured_output_modes and strict_json_schema on the model you are about to call. Some models declare both json_object and json_schema, some declare only one of them, and some declare no structured output at all. A model whose runtime cannot constrain decoding can promise a valid JSON document but nothing about the schema, so it declares json_object alone. strict_json_schema is separate again: a model can accept json_schema and still refuse "strict": true.
GET /v1/models/{owner}/{model}
curl "https://llm.wiro.ai/v1/models/openai/gpt-5-6-sol"
The detail route returns the same complete model object as the matching list entry. Query parameters are rejected on detail routes. An unavailable or non-gateway model returns model_not_found. Model Access rules are checked when the model runs, not on this route.
Generic finite task completion
POST /v1/Run/{owner}/{project}/sync lives on https://api.wiro.ai/v1, not this gateway. See Run a Model for JSON wait, SSE, and timeout recovery. Direct LLM clients should use Chat, Responses, or Messages below.
Usage contract
When the upstream model reports usage, Wiro returns normalized counters in the selected protocol's native shape:
- Chat uses
prompt_tokens, optionalprompt_tokens_details,completion_tokens, optionalcompletion_tokens_details, andtotal_tokens. - Responses uses
input_tokens,input_tokens_details,output_tokens,output_tokens_details, andtotal_tokens. - Anthropic Messages uses cache-exclusive
input_tokens,output_tokens, optionalcache_read_input_tokens, optionalcache_creation_input_tokens, and optional five-minute/one-hourcache_creationdetail.
For Chat and Responses, input/prompt totals are cache-inclusive. Their input detail objects (optional on Chat, always present on Responses) can identify cached_tokens, cache_write_tokens, cache_write_5m_tokens, cache_write_1h_tokens, and reported text/audio/image/video tokens. Output/completion totals are reasoning-inclusive; the corresponding output detail can identify reasoning_tokens, reported text/audio/image/video tokens, and accepted/rejected prediction tokens. Cache TTL values are subsets of cache_write_tokens, and all detail counters are already included in their parent total. Never add them to total_tokens.
There is intentionally no cached_output_tokens field. Provider prompt caches reuse input context; they do not report previously generated output as cached output usage.
Optional server_tool_use values count requests, not tokens. Providers omit unsupported counters, so clients must not require every detail key. Chat, Responses and Anthropic Messages expose Wiro's billed amount as usage.cost. Anthropic Messages also keeps the same value under usage.cost_usd, and a streamed Messages call carries both on its final message_delta. The asynchronous Run/Task contract keeps the billed amount at task-level totalcost.
Files compatibility
The gateway's Files routes are a compatibility view over the authenticated Wiro project's existing upload folder. Uploads, lists, retrieval, and deletion use the same storage as File/Upload, File/List, and File/Delete on api.wiro.ai.
The supported routes are:
| Method | Route | Behavior |
|---|---|---|
| POST | /v1/files |
Uploads one multipart field named file |
| GET | /v1/files |
Lists files in the authenticated project's upload folder |
| GET | /v1/files/{file_id} |
Returns file metadata |
| GET | /v1/files/{file_id}/content |
Checks ownership, then redirects with 307 to the validated public CDN URL |
| DELETE | /v1/files/{file_id} |
Deletes the project file |
File IDs use file-... form and are valid only inside the project whose credentials created or listed them. A missing, deleted, or foreign ID returns file_not_found; the gateway never falls back to another project.
OpenAI Files
OpenAI clients use Bearer authentication. The only supported OpenAI purpose is assistants:
import fs from 'node:fs';
import OpenAI from 'openai';
const client = new OpenAI({
apiKey: process.env.WIRO_BEARER_CREDENTIAL,
baseURL: 'https://llm.wiro.ai/v1',
});
const file = await client.files.create({
file: fs.createReadStream('input.png'),
purpose: 'assistants',
});
const page = await client.files.list({ limit: 20, order: 'desc' });
const metadata = await client.files.retrieve(file.id);
const content = await client.files.content(file.id);
await client.files.delete(file.id);
OpenAI list queries accept after/after_id, before/before_id, limit=1..1000, order=asc|desc, and purpose=assistants. The default limit is 20 and the default order is descending. File metadata uses OpenAI's object: "file", bytes, Unix created_at, filename, purpose, status, and status_details fields.
Anthropic Files
Anthropic SDKs use origin https://llm.wiro.ai and send the required anthropic-version header (2023-06-01 or 2026-10-21); that header selects the Anthropic file metadata shape:
import fs from 'node:fs';
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({
baseURL: 'https://llm.wiro.ai',
apiKey: process.env.WIRO_API_KEY,
authToken: null,
});
const file = await client.files.upload({
file: fs.createReadStream('context.pdf'),
});
const page = await client.files.list({ limit: 20 });
const metadata = await client.files.retrieveMetadata(file.id);
const content = await client.files.download(file.id);
await client.files.delete(file.id);
Anthropic list queries accept page, legacy after_id/before_id, and limit=1..1000. The response includes next_page, has_more, first_id, and last_id. Metadata uses ISO created_at, filename, mime_type, size_bytes, type: "file", downloadable, and expires_at. Wiro-backed files do not expire, so expires_at is null.
Limits and model input
Gateway uploads are limited to 50 MiB per file. Empty files, multiple file parts, unknown multipart fields, and filenames over 1024 bytes are rejected. ZIP uploads are rejected because Wiro's standard File API extracts archives, which cannot represent the one-upload/one-file contract expected by these SDKs. The compatibility catalog reads at most 10,000 project files; that safety bound is not a storage quota. The original Wiro File API has its own documented limits.
Use the returned ID only where the selected protocol accepts file references. For example, OpenAI Responses image input can use { "type": "input_image", "file_id": "file-..." }, while Anthropic document input uses { "type": "file", "file_id": "file-..." } inside its source object. Before Run, the gateway verifies project ownership and MIME type, then replaces the Wiro file ID with its existing public URL. Image references accept GIF, JPEG, PNG, or WebP; document references accept PDF or plain text. Invalid MIME combinations return invalid_media_type before model execution.
Public HTTPS URLs and validated data/base64 content remain available when the model advertises the corresponding modality. A Wiro file-... ID is not a provider file ID and is never forwarded to OpenAI, Anthropic, xAI, or another provider.
OpenAI Chat Completions
POST /v1/chat/completions
Use a model that includes chat in capabilities.endpoints.
curl -X POST "https://llm.wiro.ai/v1/chat/completions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-5-6-sol",
"messages": [
{ "role": "system", "content": "You are a concise assistant." },
{ "role": "user", "content": "What is SSE?" }
],
"stream": false
}'
The endpoint accepts system, developer, user, and assistant messages, plus tool results for preceding assistant tool calls. Each request is client-history: send the required conversation history in messages. Calls do not create a saved Wiro Chat session.
Text is always available. OpenAI-style image and document content parts are accepted only when the selected model advertises those input modalities. Gateway output is text; this route is not an image, audio, or video generation API. Remote media must use a public HTTPS URL or a validated data/base64 source; supported Wiro gateway file IDs may also be used. Private-network and non-HTTP fetch targets are rejected. Provider-native file IDs are not accepted as Wiro file IDs.
Generation fields such as temperature, top_p, max_tokens, max_completion_tokens, penalties, seed, stop, reasoning, and response_format are capability-gated. n must be 1, logprobs must be false, and stop accepts at most four non-empty values without semicolons. Use capabilities.structured_outputs before requesting a non-text response_format, then match the exact mode: json_object and json_schema are declared independently in capabilities.structured_output_modes, and "strict": true inside a json_schema request additionally requires capabilities.strict_json_schema. A mode the model does not declare is refused with HTTP 400, code unsupported_capability and param: "response_format", before any task is created or billed.
A sampling control the selected model does not declare, such as temperature, top_p, seed, or stop, is left out of the run rather than refused, and the response names it in the x-wiro-dropped-parameters header. On every route the same goes for a request field the gateway has no use for, such as a client's own metadata field or an option written for another provider: it is left out and named in that header, so clients that add fields of their own work unchanged. An empty stop list is read as no stop sequence. A control that reached the model with a different value, such as an effort the model does not offer moved to one it does, is listed in x-wiro-adjusted-parameters as name=applied entries, for example reasoning.effort=low. Responses and Anthropic Messages send the same two headers.
An output cap below the model's min_tokens is raised to that value rather than refused. A cap the gateway changed is listed in x-wiro-adjusted-parameters under the field you sent, for example max_tokens=128 or max_completion_tokens=128, and max_output_tokens=128 on Responses. On some models that always think first, such as Kimi K3.1 Pro and most Gemini models, min_tokens leaves room for that thinking at the default effort plus a short answer, so raise the cap when you ask for more effort. On other reasoning models, min_tokens is only the smallest cap the model accepts, so leave room for the reasoning as well as the answer.
Structured output uses OpenAI's two response_format shapes. json_object asks only for a valid JSON document:
{ "response_format": { "type": "json_object" } }
json_schema is nested: the definition sits under a json_schema key rather than beside type.
{
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "person",
"schema": {
"type": "object",
"properties": { "full_name": { "type": "string" } },
"required": ["full_name"],
"additionalProperties": false
},
"strict": true
}
}
}
The definition accepts name, schema, description, and strict, and rejects any other key. name is required and must match ^[A-Za-z0-9_-]{1,64}$; a missing or invalid name returns invalid_schema. schema must have an object root, may reference only local # fragments, and may nest at most 24 levels. json_object guarantees parseable JSON but guarantees nothing about which keys appear, so use json_schema when the key names matter.
Standard function tools use tools, tool_choice, and parallel_tool_calls. Returned function calls use { "id": "...", "type": "function", "function": { "name": "...", "arguments": "..." } } entries in message.tool_calls. Execute calls only when finish_reason is tool_calls; length and content_filter turns can contain partial tool data that must not be executed. Preserve the returned assistant message unchanged, then append matching role: "tool" results with tool_call_id. Wiro does not execute tools on the caller's behalf.
When the model advertises custom_tools, Chat also accepts the nested custom tool shape:
{
"type": "custom",
"custom": {
"name": "airport_code",
"format": {
"type": "grammar",
"syntax": "regex",
"definition": "[A-Z]{3}"
}
}
}
Use a matching nested custom tool_choice. Returned custom calls use { "id": "...", "type": "custom", "custom": { "name": "...", "input": "..." } } entries in message.tool_calls. Execute them client-side and append role: "tool" results with the same tool_call_id, just as for function calls.
Reasoning is model-specific. Public model reasoning can appear in message.reasoning and message.reasoning_details; use the advertised reasoning controls and supported efforts. Tool/reasoning combinations are also model-specific, so do not infer support from another model.
Final responses use chat.completion. Native usage is conditional: a successful completion is still returned when usage counters remain unavailable.
For streaming, set body-level "stream": true. Text arrives in choices[0].delta.content, reasoning in delta.reasoning and reasoning_details, and function calls in delta.tool_calls. Concatenate tool argument fragments by call index. The stream terminates with data: [DONE]. With stream_options.include_usage: true, Wiro emits a final empty-choices usage chunk before [DONE] only when native counters are available.
If a failure happens after Chat SSE has started, Wiro emits an OpenAI error object in a data: frame, then data: [DONE], and closes the connection.
The official openai package reaches this route with nothing changed but baseURL; the full setup, with tool calling and the model list, is under OpenAI SDK above.
OpenAI Responses
POST /v1/responses
Use a model that includes responses in capabilities.endpoints. input can be a string or Responses items; instructions, tools, text.format structured output, multimodal input, reasoning, and generation controls are capability-gated. Remote media follows the same public-HTTPS/data/base64/Wiro-file-ID restrictions as Chat.
curl -X POST "https://llm.wiro.ai/v1/responses" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-5-6-sol",
"instructions": "Answer in one paragraph.",
"input": "Explain server-sent events.",
"store": true,
"stream": false
}'
Structured output on this route is text.format, and it uses the flat shape rather than Chat's nested one: name, schema, and strict sit beside type.
{
"text": {
"format": {
"type": "json_schema",
"name": "person",
"schema": {
"type": "object",
"properties": { "full_name": { "type": "string" } },
"required": ["full_name"],
"additionalProperties": false
},
"strict": true
}
}
}
{ "text": { "format": { "type": "json_object" } } } is also accepted. The same capabilities.structured_output_modes and capabilities.strict_json_schema gates apply; the responses endpoint label does not by itself mean structured output is available. A top-level response_format is accepted as an alternative to text.format, but sending both returns HTTP 400 with param: "text".
Final responses use the official response object with an opaque ID such as resp_... and an output item array. Items can include messages, public reasoning, function calls, and custom tool calls. Execute only tool items with status: "completed" from a completed response; never execute tool items from an incomplete response. Native usage can be absent.
Stored response continuation
store defaults to true for OpenAI compatibility. Set store: false for a one-off response that will not be used as previous_response_id.
Use the ID of a stored completed or incomplete response as previous_response_id. Never execute partial tool calls from an incomplete parent:
{
"model": "openai/gpt-5-6-sol",
"previous_response_id": "resp_2221",
"input": [{
"type": "message",
"role": "user",
"content": [{
"type": "input_text",
"text": "Give me one concrete example."
}]
}],
"store": true
}
previous_response_id is the public continuation field for this gateway route. Do not send previousTaskToken to /v1/responses. Direct Run clients use previousTaskToken as described in Run a Model. session_id is not accepted by Responses; use stored previous_response_id continuation instead.
A stored response can be continued for up to 30 days by the same authenticated user, project, team, and model. Expired, unstored, unavailable, or mismatched responses return response_not_found; failed and cancelled responses are not continuable. Chains are limited to 32 responses, and the conversation plus requested output must fit the selected model's context window.
store is not accepted on /v1/chat/completions; these persistence rules apply specifically to /v1/responses.
Stored response retrieval and deletion
Retrieve a stored response with GET /v1/responses/{response_id}. Delete it with DELETE /v1/responses/{response_id}; a successful deletion returns HTTP 204 with an empty body. POST /v1/responses/{response_id}/cancel is not supported and returns response_cancel_not_supported.
Function and custom grammar tools
Responses function tools use the standard top-level name, description, parameters, and optional strict shape. When a function call is returned, submit its result in the next request as a function_call_output input item with the same call_id.
Models with capabilities.custom_tools: true also accept free-form or grammar-constrained tools:
{
"type": "custom",
"name": "sql_query",
"description": "Produce one read-only SQL query.",
"format": {
"type": "grammar",
"syntax": "regex",
"definition": "^SELECT .+;$"
}
}
Grammar syntax is regex or lark. Use format: { "type": "text" } for a free-form custom tool. When a custom_tool_call is returned, submit its result in the next request as a custom_tool_call_output input item with the matching call_id. function_call_output and custom_tool_call_output are next-request input types, distinct from the returned function_call and custom_tool_call output items. Tool execution always remains in your application.
Responses SSE
Set "stream": true for official named Responses events, including response.created, response.in_progress, output-item/content-part events, text and reasoning deltas, response.function_call_arguments.delta/.done, and response.custom_tool_call_input.delta/.done. Every response.* payload carries a monotonically increasing sequence_number, starting at 0. Ignore : keep-alive comments.
The terminal event is response.completed or response.incomplete. A midstream failure emits response.failed. Wiro then emits data: [DONE] and closes the Responses stream; the official SDK consumes that sentinel.
Anthropic Messages
POST /v1/messages
Use a model that includes anthropic in capabilities.endpoints.
Anthropic SDKs normally send:
x-api-key: YOUR_API_KEYfor an API Key Only project, orx-api-key: YOUR_API_KEY:YOUR_API_SECRETfor a Signature projectanthropic-version: 2023-06-01oranthropic-version: 2026-10-21- Optional
anthropic-betalabels, comma-separated or repeated
anthropic-version is required, and both versions are answered the same way. The credential can arrive in x-api-key or in an Authorization: Bearer header; when both are sent, they must resolve to the same complete credential. Beta headers identify requested compatibility features; they do not override model capabilities. ?beta=true is also accepted as a beta-route marker.
curl -X POST "https://llm.wiro.ai/v1/messages" \
-H "x-api-key: YOUR_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude/sonnet-5",
"max_tokens": 1024,
"system": "Be concise.",
"messages": [{
"role": "user",
"content": "What is SSE?"
}],
"stream": false
}'
max_tokens is required and positive. Messages use Anthropic user and assistant roles; system instructions belong in the top-level system field. Content can include text, model-advertised image or document input, tool_use, tool_result, and supported thinking blocks. Remote media uses validated public HTTPS, data/base64, or Wiro gateway file references.
Messages is client-history: resend the prior user/assistant content and tool blocks required for each turn. It does not use Responses storage or previous_response_id.
Anthropic function tools use name, description, and input_schema. tool_choice supports Anthropic auto, any, tool, and none choices. Anthropic's optional type: "custom" still denotes an ordinary client function tool with input_schema; it is not OpenAI's free-form custom grammar shape. Tool calls are returned as tool_use; your application executes them and sends tool_result. Provider-hosted tools, hosted containers, and remote MCP servers are rejected by this release. Execute tool_use blocks only when stop_reason is tool_use; do not execute tool data from max_tokens or refusal turns.
Structured output uses output_config, not response_format. This route accepts json_schema only, and always requests it strictly:
curl -X POST "https://llm.wiro.ai/v1/messages" \
-H "x-api-key: YOUR_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude/sonnet-5",
"max_tokens": 1024,
"messages": [{
"role": "user",
"content": "Who wrote Dune, and in what year?"
}],
"output_config": {
"format": {
"type": "json_schema",
"schema": {
"type": "object",
"properties": {
"author": { "type": "string" },
"year": { "type": "integer" }
},
"required": ["author", "year"],
"additionalProperties": false
}
}
}
}'
output_config.format takes exactly type and schema. Both are required, and any other key is rejected, including OpenAI's name and strict. The gateway applies strict JSON Schema output on this route unconditionally, so the model must declare capabilities.strict_json_schema as well as json_schema in capabilities.structured_output_modes. {"type": "json_object"} is refused here for every model. output_config.effort is the separate reasoning control and can be sent alongside format. A top-level response_format is not a Messages field and is rejected as an unsupported parameter. Anthropic error bodies carry only type and message, so a capability refusal arrives here without the code and param fields the OpenAI routes return.
Thinking controls use:
{ "thinking": { "type": "enabled", "budget_tokens": 2048 } }
type can be enabled, adaptive, or disabled. thinking and output_config.effort are this route's names for the model's own reasoning control, which capabilities.generation_controls lists as reasoning_effort, reasoning_enabled, or reasoning_max_tokens. supported_parameters uses the OpenAI Chat names, so it never lists thinking. Without a reasoning_max_tokens control, budget_tokens becomes an effort where the model has one (up to 4,096 tokens is low, up to 16,384 is medium, above that high) and is left out otherwise; the response names both changes in x-wiro-adjusted-parameters and x-wiro-dropped-parameters. disabled is refused with unsupported_capability on a model that cannot turn reasoning off. Check capabilities.output for reasoning output. Do not fabricate or alter signature or redacted-thinking blocks returned by the model.
Final responses use the Anthropic message object with opaque msg_... request IDs; they are not Wiro task IDs. Public output content contains text and tool_use blocks. Internal model reasoning is not projected as Anthropic thinking or redacted_thinking output. Usage is included only when native counters are available.
For streaming, set "stream": true. The SSE sequence uses Anthropic events such as message_start, content_block_start, content_block_delta, content_block_stop, message_delta, and message_stop, with : keep-alive comments while the model works. A midstream failure emits Anthropic's native error event and closes the connection. A successful stream ends with message_stop and connection close; it does not emit [DONE]. Text blocks use text_delta, and tool_use blocks use input_json_delta. The gateway does not emit thinking_delta.
Anthropic SDKs and Claude Code
The official Node and Python SDKs must use origin https://llm.wiro.ai, not the OpenAI /v1 base:
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({
baseURL: 'https://llm.wiro.ai',
apiKey: process.env.WIRO_API_KEY,
authToken: null,
});
const message = await client.messages.create({
model: 'claude/sonnet-5',
max_tokens: 1024,
messages: [{ role: 'user', content: 'Hello' }],
});
WIRO_API_KEY is YOUR_API_KEY for an API Key Only project or YOUR_API_KEY:YOUR_API_SECRET for a Signature project. authToken: null keeps an ANTHROPIC_AUTH_TOKEN set in the environment out of the request: some SDK versions send it as a Bearer token beside the key, and two different credentials return 401. Python uses the equivalent base_url and api_key options; leave ANTHROPIC_AUTH_TOKEN unset in the process that creates the client.
For Claude Code with a Signature project:
ANTHROPIC_BASE_URL="https://llm.wiro.ai" \
ANTHROPIC_API_KEY="YOUR_API_KEY:YOUR_API_SECRET" \
ANTHROPIC_MODEL="claude/sonnet-5" \
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 \
claude
For an API Key Only project, set ANTHROPIC_API_KEY to YOUR_API_KEY. Model discovery uses Wiro's /v1/models route with limit=1000. Claude Code adds only discovered IDs containing claude or anthropic to its picker; set ANTHROPIC_MODEL explicitly for any other compatible ID. Native Messages, client tools, streaming, beta headers, thinking continuation, and token-counting calls remain subject to the selected model's advertised capabilities. Provider-hosted tools remain outside this release even when a client beta can describe them.
POST /v1/messages/count_tokens
curl -X POST "https://llm.wiro.ai/v1/messages/count_tokens" \
-H "x-api-key: YOUR_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude/sonnet-5",
"system": "Be concise.",
"messages": [{ "role": "user", "content": "Hello" }]
}'
{ "input_tokens": 141 }
This is a local preflight estimate over the submitted Anthropic payload, not authoritative billing or provider-native usage. It is computed from the size of the request and errs high, so use it to check that a request fits the model's context window; the billed input_tokens of the same request are usually lower. The response says so in x-wiro-token-count-mode: conservative-estimate-v1. The estimate endpoint is part of the Anthropic compatibility route; the model catalog does not label it as native token counting.
Generation metadata
GET /v1/generation?id=
Look up terminal metadata using the exact public ID emitted by the protocol route: the response id for Chat or Responses, and the request-id response header for Messages. The equivalent path form is GET /v1/generation/{public-id}.
curl "https://llm.wiro.ai/v1/generation?id=resp_01HZX7Y8Q9" \
-H "Authorization: Bearer YOUR_API_KEY"
{
"data": {
"id": "resp_01HZX7Y8Q9",
"model": "openai/gpt-5-6-sol",
"protocol": "responses",
"status": "completed",
"created_at": "2026-08-21T12:00:00.000Z",
"completed_at": "2026-08-21T12:00:03.000Z",
"usage": {
"input_tokens": 20,
"input_tokens_details": {
"cached_tokens": 0,
"cache_write_tokens": 0
},
"output_tokens": 12,
"output_tokens_details": {
"reasoning_tokens": 4
},
"total_tokens": 32
},
"upstream_metered_cost": 0.0021,
"upstream_elapsed_seconds": 3
}
}
protocol is chat, messages, or responses. status is completed, failed, or incomplete. created_at and completed_at are ISO 8601 strings.
When token counters are available, usage follows the selected protocol:
responses:input_tokens,input_tokens_detailswithcached_tokensandcache_write_tokens,output_tokens,output_tokens_details.reasoning_tokens, andtotal_tokens.chat:prompt_tokens, optionalprompt_tokens_details,completion_tokens, optionalcompletion_tokens_details, andtotal_tokens.messages:input_tokens,output_tokens, and nullablecache_creation_input_tokensandcache_read_input_tokens. This shape does not addtotal_tokens.
usage is null when no valid counters were recorded. upstream_metered_cost and upstream_elapsed_seconds are finite upstream task counters when available, otherwise null; cost is not duplicated inside metadata usage.
Only the owning authenticated project can read a generation. Missing, expired, and foreign IDs all return generation_not_found. This endpoint is terminal observability metadata, not task output: it does not return a Wiro task ID, generated content, or continuation state. Read generated content from the original protocol JSON or SSE response.
Deliberate boundaries
The Direct LLM Gateway does not currently provide:
- Provider-hosted web search, file search, code interpreter, computer-use, or remote MCP tool execution; Wiro returns tool calls for your client to run
- A native Gemini
generateContentprotocol - Embeddings or reranking
- Automatic model routing or fallback routing
- Bring-your-own-provider-key (BYOK) execution
- Dedicated image, audio, or video generation through the Chat, Responses, or Messages routes
- The legacy
/v1/completionsendpoint
Use Wiro's normal Run or /sync APIs for supported finite media-generation models. Image and document input to an LLM is distinct from media generation and remains available when the selected model advertises it.
Remote media fetches must use public HTTPS; validated data/base64 sources and Wiro gateway file IDs are accepted only where the selected protocol/model supports them. Provider-native file IDs are not interchangeable.
Errors
Error responses preserve the selected public protocol:
- Chat, Responses, model, and generation errors use the OpenAI-style
{ "error": { "message", "type", "param", "code" } }shape. - Anthropic routes use
{ "type": "error", "error": { "type", "message" } }.
Generic /sync waits on api.wiro.ai use the normal Wiro result/errors envelope.
After a stream starts, inspect SSE events rather than the HTTP status: Chat emits an error data: frame followed by [DONE], Responses emits response.failed, and Anthropic emits error.
A model that a Model Access rule of the key's workspace blocks (Wiro error code 92) is refused before it runs with HTTP 403 and Wiro's message, which names the rule. Chat and Responses return type permission_error, code model_not_allowed and param model; Anthropic routes return type permission_error. Nothing runs and nothing is charged, and sending the request again does not help: use a model the rules allow, or ask someone who manages the rule to change it. A streamed Responses request ends with response.failed carrying code model_not_allowed instead, like other errors that happen when the run is submitted.
{
"error": {
"message": "The LLM gateway can only use selected models, and openai/gpt-6-2-astra is not one of them. Model Access rules decide which models can run.",
"type": "permission_error",
"code": "model_not_allowed",
"param": "model"
}
}
A run refused by a spend limit of the key's workspace (Wiro error code 93) gets HTTP 402 with Wiro's message, which names the limit and when it resets. Chat and Responses return type insufficient_quota, code spend_limit_reached and param null; Anthropic routes return type billing_error. Nothing runs and nothing is charged, and SDKs do not retry it: send the request again only after the limit resets or is raised. A streamed Responses request ends with response.failed carrying code spend_limit_reached instead, like other errors that happen when the run is submitted.
{
"error": {
"message": "This API key's monthly spend limit is reached ($50.20 of $50.00). It resets on December 1, 2026 at 00:00 UTC.",
"type": "insufficient_quota",
"code": "spend_limit_reached",
"param": null
}
}
Common codes include invalid_model, model_not_found, unsupported_model_type, unsupported_parameter, response_not_found, response_chain_too_deep, invalid_generation_id, generation_not_found, completion_timeout, model_execution_failed, task_cancelled, and unsupported_capability. Files routes can also return file_not_found, file_too_large, invalid_multipart, missing_file, invalid_filename, invalid_media_type, invalid_pagination, invalid_query, file_catalog_too_large, file_content_unavailable, file_api_unavailable, and invalid_file_response.
completion_timeout means the model was still running when the gateway's 40-minute limit ran out; the limit applies to streamed requests too. The run is stopped and is not billed. A streamed request ends with the error event above, and Anthropic routes report type timeout_error. When an answer can take longer, ask for a shorter one with a lower max_tokens, max_completion_tokens or max_output_tokens, or split the work across requests.
A non-streamed request that is still running after 60 seconds gets its HTTP 200 headers early, then a newline every 15 seconds, so proxies do not close the quiet connection. The JSON body follows the newlines and parses as usual. A failure after that point, completion_timeout included, arrives as the error object in that 200 body, whatever status it would otherwise have had, and SDKs neither raise nor retry it. Check the body for error before reading the result, and decide retries from error.code. Streaming reports failures as events instead.
Anthropic-route error bodies, streamed or not, carry no code; key on error.type there. overloaded_error is provider_overloaded and timeout_error is completion_timeout, while gateway_shutting_down, provider_unavailable and authentication_service_unavailable read api_error, like other server failures.
gateway_shutting_down (HTTP 503, or in the 200 body of a non-streamed response that has started) means the gateway was restarting. A request that arrived during the restart did not run, and one that was already running was stopped. Neither is billed; send the same request again.
unsupported_capability means the model does not declare something the request asked for. A structured-output mode missing from capabilities.structured_output_modes carries param: "response_format" and the message Model '<id>' does not support json_object structured output; "strict": true on a model without capabilities.strict_json_schema uses the same code with does not support strict JSON Schema output; tool controls on a model that declares neither function_tools nor custom_tools carry param: "tool_choice". The request is refused during validation, so no task is created and nothing is billed. Anthropic routes report the same refusal in the Anthropic error shape, which carries only type and message.
Gateway-origin and upstream execution failures use HTTP 500 with their specific error code; the public protocol does not return HTTP 502. Other statuses carry their code the same way: completion_timeout is 504; provider_overloaded is 503 (529 on Anthropic routes); and provider_unavailable, authentication_service_unavailable and gateway_shutting_down are 503. The 503 and 529 errors can be retried. Once a non-streamed response has started, every failure arrives in its 200 body instead. Responses under /v1 include ratelimit-limit, ratelimit-remaining, ratelimit-reset, request-id, and x-request-id. A request over that rate limit gets HTTP 429 with code rate_limit_exceeded and a retry-after header. A run refused at your Wiro concurrency limit (error code 96) also arrives as HTTP 429, with error type rate_limit_error, Wiro's message and retry-after; a streamed Responses request ends with response.failed carrying code rate_limit_exceeded instead, like other errors that happen when the run is submitted. See Concurrency Limits.
concurrent_execution_limit (HTTP 429, type rate_limit_error) means too many requests were already running when this one arrived, usually from the same API key. The request is refused before the model runs, on every route and with or without streaming, so no task is created and nothing is billed. The response has no retry-after header: send the request again after a short wait that grows with each attempt, for example 1, 2, 4 and 8 seconds, or run fewer requests at once.
Protocol execution POST bodies must be JSON and are limited to 40 MiB. The messages, tools and tool outputs in one request are limited to 32 MiB together; some models take less, and the error message names the limit. One text block, text document or tool output is limited to 16 MiB. A request over the body or conversation limit gets HTTP 400 with code context_length_exceeded (on Anthropic routes, a message that starts with prompt is too long), so an agent can compact its history and send it again. A single block over 16 MiB gets HTTP 400 with code payload_too_large. Files uploads are multipart and use the separate 50 MiB file limit.
Unsupported fields that could change execution fail instead of being silently accepted. A model task can also fail after HTTP validation; preserve the protocol error and status rather than treating every 2xx task creation as a successful model answer.
Model Parameters
Understand parameter types, content types, and how to send inputs to any model.
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
| Type | Description | Example Parameters |
|---|---|---|
text |
Single-line text input | URLs, names, short strings |
textarea |
Multi-line text input | prompt, negative_prompt, descriptions |
select |
Dropdown with predefined options | outputType, language, style |
range |
Numeric value (slider) | width, height, scale, strength |
fileinput |
Single file upload (1 file or 1 URL) | inputImage, inputAudio |
multifileinput |
Multiple files (up to N files/URLs) | inputDocumentMultiple |
combinefileinput |
Up to N entries (files, URLs, or mixed) | inputImageClothes |
JSON vs Multipart
The content type of your request depends on whether the model requires file inputs:
| Condition | Content-Type | When to Use |
|---|---|---|
| No file parameters | application/json |
Text-only models (LLMs, image generation from prompt) |
| Has file parameters | multipart/form-data |
Models that accept image, audio, video, or document uploads |
Tip: For fileinput parameters, use the {id}Url suffix to send a URL (e.g., inputImageUrl). For multifileinput, send comma-separated URLs in the field that puts Url before Multiple (e.g., inputDocumentUrlMultiple for inputDocumentMultiple). For combinefileinput, pass URLs directly in the original parameter. No suffix is needed. A fileinput or multifileinput with no URL field takes the URL, or the comma-separated list, in the parameter itself. Every URL must be a public http(s) address, and so must any address it redirects to: Wiro doesn't fetch a URL whose host is, or resolves to, a private, loopback or link-local address.
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 and 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"
Multiple Files (multifileinput)
For parameters like inputDocumentMultiple, send either up to N files or a comma-separated list of URLs. The URL list goes in the field that puts Url before Multiple: inputDocumentUrlMultiple. When using multipart, include both fields and leave one empty:
# Option 1: Upload files in {id}, leave inputDocumentUrlMultiple empty
curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
-H "x-api-key: YOUR_API_KEY" \
-F "inputDocumentMultiple=@doc1.pdf" \
-F "inputDocumentMultiple=@doc2.pdf" \
-F "inputDocumentUrlMultiple="
# Option 2: Send comma-separated URLs in inputDocumentUrlMultiple, leave {id} empty
curl -X POST "https://api.wiro.ai/v1/Run/{owner-slug}/{model-slug}" \
-H "x-api-key: YOUR_API_KEY" \
-F "inputDocumentMultiple=" \
-F "inputDocumentUrlMultiple=https://example.com/doc1.pdf,https://example.com/doc2.pdf"
Combined (combinefileinput)
For parameters like inputImageClothes, files and URLs go directly in the same {id} field, with 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 "inputImageClothes=@shirt.jpg" \
-F "inputImageClothes=@pants.jpg"
# 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 "inputImageClothes=@shirt.jpg" \
-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 "inputImage=@photo.jpg" \
-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 "inputImageHuman=@person.jpg" \
-F "inputImageClothes=@shirt.jpg"
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 "inputDocumentMultiple=@resume.pdf" \
-F "prompt=Extract the candidate name and skills" \
-F "outputType=json" \
-F "language=en"
Note: LLM responses are available as structured content in outputs (with contenttype: "raw" containing prompt, raw, thinking, and answer fields) and as merged plain text in debugoutput. See Tasks for details.
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:
Available realtime models include:
// 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"
}
Realtime Text to Speech
Realtime TTS models stream synthesized audio back over WebSocket as binary frames. Text is required. Reference audio is optional for voice cloning.
Available realtime TTS models include:
{
"text": "Hello, this is a test of real-time text to speech.",
"inputAudio": "",
"temperature": 0.8,
"topP": 0.6,
"topK": 30,
"repetitionPenalty": 1.1,
"repetitionWindow": 50,
"maxLength": 3000
}
Realtime Speech to Text
Realtime STT models transcribe audio streamed from the microphone over WebSocket. No text input is needed: audio is streamed from the microphone. The transcriptionDelay controls the speed vs accuracy trade-off.
Available realtime STT models include:
{
"transcriptionDelay": "balanced"
}
Webhook Callback
All models support an optional callbackUrl parameter. When provided, Wiro will POST the task result to your URL when the task completes, so you do not need to poll:
{
"prompt": "A sunset over mountains",
"callbackUrl": "https://your-server.com/webhook/wiro"
}
Wiro sends a POST request with a JSON body (Content-Type: application/json) once the task has finished, whether it succeeded or failed: check pexit in the body. The body is the task, including its parameters and outputs.
- Any 2xx answer counts as delivered. Answer with a 2xx as soon as the request arrives, and do slower work after that.
- Up to 3 tries. When your endpoint answers with anything other than a 2xx, or cannot be reached, Wiro tries again 2 seconds later, up to 3 tries in all.
- Redirects are not followed. A 3xx answer counts as not delivered, so pass the final address.
- No authorization header. To check that a webhook comes from your own run, match its task ID with your records.
The callbackUrl must be a public http(s) address. A host that is, or resolves to, a private, loopback or link-local address gets no webhook; the task still runs. When a webhook does not arrive, poll Task/Detail with the task ID to get the result.
Tasks
Track, monitor, and control your AI model runs.
Task Lifecycle
Every model run creates a task that progresses through a defined set of stages:
Task Statuses
| Status | Description |
|---|---|
task_queue |
The task is queued and waiting to be picked up by an available worker. Emitted once when the task enters the queue. |
task_accept |
A worker has accepted the task. The task is no longer in the general queue and is being prepared for execution. |
task_preprocess_start |
Optional preprocessing has started. This includes operations like downloading input files from URLs, converting file types, and validating/formatting parameters before the model runs. Not all models require preprocessing. |
task_preprocess_end |
Preprocessing completed. All inputs are ready for GPU assignment. |
task_assign |
The task has been assigned to a specific GPU. The model is being loaded into memory. This may take a few seconds depending on the model size. |
task_start |
The model command has started executing. Inference is now running on the GPU. |
task_output |
The model is producing output. This event is emitted multiple times: each time the model writes to stdout, a new task_output message is sent via WebSocket. For LLM models, each task_output event carries the latest cumulative snapshot of the output, so render the newest one instead of appending. |
task_error |
As a live WebSocket event, this means the model wrote to stderr and is an interim log, not necessarily a failure. As the persisted status returned by Task/Detail, it marks a pre-execution failure awaiting recovery or requeue; it does not close the task. |
task_output_full |
Signals that process stdout collection ended. Raw accumulated stdout is not exposed on the public socket. |
task_error_full |
Signals that process stderr collection ended. Raw accumulated stderr is not exposed on the public socket. |
task_end |
The model process has exited. Emitted once. This fires before post-processing, so do not use this event to determine success. Wait for task_postprocess_end instead. |
task_postprocess_start |
Post-processing has started. The system is preparing the output files: encoding, uploading to CDN, and generating access URLs. |
task_postprocess_end |
Post-processing completed. On the public WebSocket, check success and exitCode (0 = success); the message array contains sanitized outputs. Task/Detail continues to use pexit as its primary success indicator. This is the event you should listen for to get final results. |
task_cancel |
The task was cancelled (if queued) or killed (if running) by the user. |
Realtime Sessions
The following statuses are exclusive to realtime models (voice conversation, text-to-speech, and speech-to-text). They are not emitted for standard model runs.
| Status | Description |
|---|---|
task_stream_ready |
Realtime model is ready to receive audio/text input, so you can start sending data |
task_stream_end |
Realtime session has ended: the model finished speaking or the session was closed |
task_cost |
Real-time cost update emitted during execution: shows the running cost of the task |
task_session_stopped |
The server is ending the session after the turn that reached a spend limit (reason spend_limit, code 93) or used up the balance (reason balance, code 97). It is not a failure: the usual closing events follow (see Realtime Voice) |
Determining Success or Failure
Normal model executions, both successful and failed, reach task_postprocess_end. Check pexit or outputs (or both) to determine the result. A setup failure may temporarily set persisted status: "task_error" with a debugerror, but clients must keep waiting until task_postprocess_end or task_cancel.
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 withcontenttype: "raw"and orderedcontent.segments. If it's empty or missing, the task likely failed.
Note: For LLM models, outputs contains a structured entry with contenttype: "raw" and ordered content.segments. The merged plain text is also available in debugoutput. Always use pexit as the primary success check.
// 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?",
"segments": [
{
"type": "answer",
"text": "Hello! How can I help you today?"
}
],
"finishreason": "stop",
"usage": {
"input_tokens": 12,
"input_tokens_details": {
"cached_tokens": 4,
"cache_write_tokens": 2
},
"output_tokens": 9,
"output_tokens_details": {
"reasoning_tokens": 2
},
"total_tokens": 21
}
}
}]
}
// Failure: pexit non-zero
{
"pexit": "1",
"outputs": []
}
Important: Do not confuse the live task_error WebSocket log event with persisted status: "task_error" in Task/Detail. Both are non-terminal; only task_postprocess_end and task_cancel close the task.
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 requests, outputs contains a structured entry with contenttype: "raw" and ordered content.segments; debugoutput contains the merged plain text. Use the representation that matches your UI.
For real-time streaming, use WebSocket. Each LLM task_output event contains the latest cumulative message.segments snapshot; replace your previous snapshot instead of appending it.
Structured LLM content fields
Task Detail returns these fields under tasklist[0].outputs[].content. The final WebSocket task_postprocess_end event returns the same content under message[].content.
| Field | When you need it | Description |
|---|---|---|
raw |
Optional | Merged public model text. debugoutput provides the same compatibility view at task level. |
thinking / answer |
Optional | Convenience arrays split from text output. Use segments when exact ordering or tools matter. |
segments |
All structured/tool integrations | Authoritative cumulative ordered timeline. Text entries are thinking or answer; tool entries are function_call or custom_tool_call. |
finishreason |
Completion and tool handling | stop, tool_calls, length, content_filter, or error. Execute completed tool entries only when this is tool_calls. |
usage |
Token reporting | Normalized token and server-tool counters. It may be omitted when the provider does not report usage. It is not the billed amount. |
Within usage, input_tokens already includes cache-read and cache-write tokens, output_tokens already includes reasoning tokens, and total_tokens equals input_tokens + output_tokens. Never add detail counters to the total. Known optional counters are:
input_tokens_details:cached_tokens,cache_write_tokens,cache_write_5m_tokens,cache_write_1h_tokens,text_tokens,audio_tokens,image_tokens, andvideo_tokens.output_tokens_details:reasoning_tokens,text_tokens,audio_tokens,image_tokens,video_tokens,accepted_prediction_tokens, andrejected_prediction_tokens.server_tool_use:web_search_requests,web_fetch_requests,file_search_requests,image_generation_requests,code_execution_requests,bash_code_execution_requests,text_editor_code_execution_requests, andcomputer_use_requests.
The five-minute and one-hour cache-write counters are subsets of cache_write_tokens. Server-tool values count requests, not tokens. Providers omit counters they do not support. There is no cached-output counter because prompt caching applies to input context. Use task-level totalcost for the amount charged.
Plain-text integrations can use debugoutput. Tool integrations must inspect segments, finishreason, and pexit. A final structured validation failure produces a non-zero pexit.
POST /Task/Detail
Retrieves the current status and output of a task. You can query by either tasktoken or taskid.
| Parameter | Type | Required | Description |
|---|---|---|---|
tasktoken |
string | No | The task token returned from the Run endpoint |
taskid |
string | No | The task ID (alternative to tasktoken) |
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"
}]
}]
}
| Field | Type | Description |
|---|---|---|
id |
string |
Task ID. |
socketaccesstoken |
string |
Token to connect via WebSocket. |
parameters |
object |
The input parameters sent in the run request. |
status |
string |
Current task status (see Task Lifecycle). |
pexit |
string |
Process exit code. "0" = success. |
debugoutput |
string |
Accumulated text output. For LLM models, contains the merged response text. |
debugerror |
string |
Accumulated error text or a fatal pre-execution error message. |
starttime |
string |
Unix timestamp when execution started. |
endtime |
string |
Unix timestamp when execution ended. |
elapsedseconds |
string |
Total execution time in seconds. |
totalcost |
string |
Actual cost charged for the run in USD. |
modeldescription |
string |
Description of the model that was executed. |
modelslugowner |
string |
Model owner slug (e.g. "google", "wiro"). |
modelslugproject |
string |
Model project slug (e.g. "nano-banana-pro"). |
outputs |
array |
Output files (CDN URLs) or structured LLM content (contenttype: "raw"). |
POST /Task/Cancel
Cancels a task that is still in the queue stage. Use Kill for a running task.
| Parameter | Type | Required | Description |
|---|---|---|---|
taskid |
string | Yes | The numeric task ID returned by the Run endpoint |
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
taskid |
string | No | The numeric task ID |
socketaccesstoken |
string | No | The task token returned by the Run endpoint (alternative to taskid) |
Provide either taskid or socketaccesstoken.
POST /Task/InputOutputDelete
Deletes the task's input and output files. Their URLs stop working right away.
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 are kept.
| Parameter | Type | Required | Description |
|---|---|---|---|
tasktoken |
string | Yes | The task token (socketaccesstoken) |
Response
{
"result": true,
"errors": []
}
After deletion:
- Output files and the input files you uploaded are deleted, and their URLs stop working
- Task Detail then returns no outputs
- Task record and parameters are preserved. Only the files are deleted
- Calling the endpoint again on the same task returns
result: trueimmediately (idempotent)
Errors
| Error | When |
|---|---|
There is no task yet. |
Invalid tasktoken or unauthorized |
Task must be completed or cancelled before deleting files |
Task is still running |
LLM & Chat Streaming
Stream LLM responses in real time with ordered output segments, session history, and multi-turn conversations.
Overview
LLM (Large Language Model) requests on Wiro work differently from standard model runs:
- Responses are available as structured content in the
outputsarray (contenttype: "raw") and as merged text indebugoutput - Streaming
task_outputmessages contain ordered text/tool-callsegments, not plain strings - Multi-turn conversations are supported via
session_idanduser_idparameters pexitis the primary success indicator- The Direct LLM Gateway offers OpenAI Chat/Responses and Anthropic Messages on
llm.wiro.ai. Generic/syncwaits stay on Run a Model.
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. Send the same session_id together with user_id on every message of a conversation (some chat models keep history only when both are present), and the model builds on the earlier messages:
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id |
string | No* | Non-empty conversation identifier (up to 256 UTF-8 bytes). Reuse the same ID for follow-up messages. |
user_id |
string | No | UUID identifying the user. |
prompt |
string | Yes | The user's message or question. |
// 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"
}
session_id is optional on a first turn but required when continuing with previousTaskToken. Reuse the same session_id value on continuation. The value may contain up to 256 UTF-8 bytes; a UUID is allowed but not required.
Ordered Output Segments
LLM output is an ordered timeline with up to four segment types:
- Thinking: reasoning text exposed by the selected model
- Answer: the final response to the user
- Function call: JSON arguments for an application-defined function
- Custom tool call: grammar-constrained or free-form tool input
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",
"message": {
"type": "progressGenerate",
"task": "Generate",
"speed": "12.4",
"speedType": "words/s",
"segments": [
{ "type": "thinking", "text": "Let me analyze this step by step..." },
{ "type": "answer", "text": "Quantum computing uses qubits that can exist in superposition..." }
],
"finishreason": "stop",
"usage": {
"input_tokens": 18,
"input_tokens_details": { "cached_tokens": 6 },
"output_tokens": 11,
"output_tokens_details": { "reasoning_tokens": 4 },
"total_tokens": 29
},
"isThinking": false,
"elapsedTime": "3s"
}
}
A model may alternate between thinking and answering multiple times during one response. The segments array preserves the exact order, including consecutive items of the same type:
// Ordered output segments
{
"segments": [
{ "type": "thinking", "text": "Let me break this into parts..." },
{ "type": "thinking", "text": "Now let me verify my reasoning..." },
{ "type": "answer", "text": "Quantum computing uses qubits..." },
{ "type": "thinking", "text": "I should clarify one detail..." },
{ "type": "answer", "text": "To summarize: qubits can be 0, 1, or..." }
]
}
Each task_output event contains the full accumulated segment snapshot, not only the latest delta. Replace your stored segment list with the newest array; do not append the complete array again. The active final item's text grows in place as chunks arrive, so render every snapshot before the response completes. A new item is appended only when the output phase changes. Render items in array order and use isThinking to show an active reasoning indicator.
| Field | Type | Description |
|---|---|---|
message.type |
string |
Progress payload type; currently "progressGenerate". |
message.segments |
array |
Full ordered text/tool-call snapshot. Replace the prior array rather than appending it. |
message.finishreason |
string |
Final reason: stop, tool_calls, length, content_filter, or error. Usually absent until the turn finishes. |
message.usage |
object |
Final normalized token/server-tool counters. Detail counters are already included in input/output totals. |
message.isThinking |
boolean |
Whether the model is currently in a thinking phase. |
message.speed |
string |
Generation speed (e.g. "12.4"). |
message.speedType |
string |
Speed unit (e.g. "words/s"). |
message.elapsedTime |
string |
Elapsed time since generation started (e.g. "3s", "1m 5s"). |
Note: Standard models may send message as a progress object or plain string. For LLM rendering, first verify that message.segments is an array.
Tool entries carry stable id, call_id, name, and status. function_call uses a JSON arguments string; custom_tool_call uses input. Execute only a completed call from a final turn whose finishreason is tool_calls. Earlier snapshots may contain in_progress or incomplete calls and must not trigger execution.
Streaming Flow
The complete flow for streaming an LLM response:
- Run the model with
prompt,session_id, anduser_id - Connect to WebSocket and send
task_info - Receive
task_outputmessages containing cumulative orderedsegments - Replace your stored snapshot and render
answeritems; optionally showthinkingitems and collect tool calls - Complete: on
task_postprocess_end, checkexitCodeon WebSocket orpexitin Task Detail, then inspectfinishreason
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 ordered segments in the structured outputs entry:
{
"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...",
"segments": [
{
"type": "answer",
"text": "Quantum computing uses qubits that can exist in superposition..."
}
],
"finishreason": "stop",
"usage": {
"input_tokens": 18,
"output_tokens": 11,
"total_tokens": 29
}
}
}]
}]
}
Note: Read outputs[].content.segments for structured output. debugoutput contains merged plain text. For real-time delivery, use WebSocket instead.
Completions Alternative
For a single HTTP connection instead of manual Run plus WebSocket setup:
- Use
POST /v1/Run/{owner}/{project}/sync?stream=trueonhttps://api.wiro.ai/v1for generic task-event SSE. See Run a Model. - Use the Direct LLM Gateway on
https://llm.wiro.aifor OpenAI Chat chunks ending in[DONE], Responses named events, or Anthropic events ending inmessage_stop.
WebSocket
Receive real-time task updates via a persistent WebSocket connection.
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
- Connect: open a WebSocket connection to
wss://socket.wiro.ai/v1 - Register: send a
task_infomessage with yourtasktoken - Receive: listen for messages as the task progresses through its lifecycle
- Close: disconnect after the
task_postprocess_endevent (this is the final event with results)
Registration message format:
{
"type": "task_info",
"tasktoken": "your-socket-access-token"
}
Message Types
| Message Type | Description |
|---|---|
task_queue |
The task is queued and waiting to start. |
task_accept |
The task was accepted and is preparing for execution. |
task_preprocess_start |
Optional input preparation has started. |
task_preprocess_end |
Input preparation completed. |
task_assign |
Execution capacity was assigned and the model is preparing to start. |
task_start |
Model execution started. |
task_output |
The model is producing output. Emitted multiple times; LLM events carry the latest cumulative ordered message.segments snapshot. |
task_error |
An interim diagnostic event. It is not terminal; continue listening for completion. |
task_output_full |
Signals that output collection ended. Treat it as a lifecycle event. |
task_error_full |
Signals that error-output collection ended. Treat it as a lifecycle event. |
task_end |
Model execution ended. This is not the final success signal; wait for task_postprocess_end. |
task_postprocess_start |
Final output preparation started. |
task_postprocess_end |
Post-processing completed. Check success and exitCode (0 = success). The message array contains final outputs. This is the event to listen for. |
task_cancel |
The task was cancelled (if queued) or killed (if running) by the user. |
Message Format
Every WebSocket message is a JSON object with this base structure:
{
"type": "task_accept",
"id": "534574",
"message": null,
"result": true,
"success": null,
"terminal": false,
"exitCode": null
}
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.
Use the top-level id to correlate server events with the submitted task.
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",
"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",
"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",
"message": "Processing complete.",
"result": true
}
LLM models: message.segments is the cumulative ordered output snapshot. Replace it on every event. The final active item's text grows as chunks arrive, so render it before completion; a new item appears when the output phase changes. See LLM & Chat Streaming for full details:
{
"type": "task_output",
"id": "534574",
"message": {
"type": "progressGenerate",
"task": "Generate",
"speed": "12.4",
"speedType": "words/s",
"segments": [
{ "type": "thinking", "text": "Let me analyze this..." },
{ "type": "answer", "text": "Quantum computing uses qubits..." }
],
"finishreason": "stop",
"usage": {
"input_tokens": 18,
"input_tokens_details": { "cached_tokens": 6 },
"output_tokens": 11,
"output_tokens_details": { "reasoning_tokens": 4 },
"total_tokens": 29
},
"isThinking": false,
"elapsedTime": "3s"
},
"result": true
}
message.segments is always the full accumulated snapshot. Text entries use thinking or answer. Tool-capable models can also emit function_call entries with arguments, or custom_tool_call entries with input; both include id, call_id, name, and status.
message.finishreason and message.usage are final-turn metadata and can be absent from earlier task_output snapshots:
finishreasonisstop,tool_calls,length,content_filter, orerror. Execute a tool only when its segment status iscompletedand the finish reason istool_calls.usagecontains normalized token and server-tool counters. Input totals already include cache reads/writes; output totals already include reasoning. Do not add details tototal_tokens, and use Task Detailtotalcostfor the billed amount.
Inspect finishreason after completion so truncation and content filtering are not mistaken for a normal stop.
Error Events
task_error is an interim diagnostic event, not a failure. It arrives while the task keeps running, usually because the model wrote to stderr. The stderr text is never exposed: message is an empty string, success stays null, and there is no error field. task_error_full has the same shape. Only task_postprocess_end reports the outcome:
{
"type": "task_error",
"id": "534574",
"message": "",
"result": true,
"success": null,
"terminal": false,
"exitCode": null
}
Full Output Events
task_output_full and task_error_full are lifecycle signals. Continue listening for task_postprocess_end, or use authenticated POST /Task/Detail to retrieve the persisted task.
{
"type": "task_output_full",
"id": "534574",
"message": "",
"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",
"message": [{
"name": "0.png",
"contenttype": "image/png",
"size": "202472",
"url": "https://cdn1.wiro.ai/.../0.png"
}],
"result": true,
"success": true,
"terminal": true,
"exitCode": 0
}
// LLM model — structured raw content
{
"type": "task_postprocess_end",
"id": "534574",
"message": [{
"contenttype": "raw",
"content": {
"prompt": "Explain quantum computing",
"segments": [
{ "type": "answer", "text": "Quantum computing uses qubits..." }
],
"finishreason": "stop",
"usage": {
"input_tokens": 18,
"output_tokens": 11,
"total_tokens": 29
}
}
}],
"result": true,
"success": true,
"terminal": true,
"exitCode": 0
}
Realtime Events
These events are exclusive to realtime models (voice conversation, text-to-speech, and speech-to-text):
// Session is ready — start sending audio (voice conversation, speech-to-text)
{
"type": "task_stream_ready",
"id": "534574",
"result": true
}
// The model finished producing output for this turn
{
"type": "task_stream_end",
"id": "534574",
"result": true
}
// Cost update per turn
{
"type": "task_cost",
"id": "534574",
"turnCost": 0.002,
"cumulativeCost": 0.012,
"usage": { "input_tokens": 150, "output_tokens": 89 },
"result": true
}
// The session is ending: a spend limit was reached or the balance ran out
{
"type": "task_session_stopped",
"id": "534574",
"reason": "spend_limit",
"code": 93,
"message": "This team's monthly spend limit is reached ($50.00 of $50.00). It resets on December 1, 2026 at 00:00 UTC.",
"result": true,
"success": null,
"terminal": false,
"exitCode": null
}
task_cost.usage is the provider-specific realtime usage payload for that turn. It is separate from the normalized structured finite-LLM message.usage contract described above and can omit total_tokens or detail objects.
task_session_stopped comes once, right after the task_cost of the turn that reached a spend limit (reason spend_limit, code 93) or used up the balance (reason balance, code 97). It is not a failure: the session then closes with the usual events. See Realtime Voice.
Binary Frames
For realtime models that return audio (voice conversation and text-to-speech), 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 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.
Agent WebSocket Events
The same WebSocket connection also supports AI Agent real-time streaming. Instead of task_info, register with agent_info and an agenttoken to receive agent response events.
For full documentation on agent events (agent_subscribed, agent_output, agent_end, and more), see Agent WebSocket.
Realtime Voice
Build interactive voice conversation apps with realtime AI models.
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:
- Run the realtime model via POST /Run to get a
socketaccesstoken - Connect to the WebSocket and send
task_infowith your token - Wait for
task_stream_ready: the model is ready to receive audio - Stream microphone audio as binary frames
- Receive AI audio as binary frames and play them
- 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"
}'
Important: Parameters vary per model. Always check the model's detail page or use /Tool/Detail to get the exact parameter list before integrating.
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"
}));
};
Note: Both standard and realtime models use type: "task_info" with tasktoken to register on the WebSocket.
Realtime Events
During a realtime session, you'll receive these WebSocket events:
| Event | Direction | Description |
|---|---|---|
task_stream_ready |
server → client | Session is ready: start sending microphone audio |
task_stream_end |
server → client | AI finished speaking for this turn: you can speak again |
task_cost |
server → client | Cost update per turn: includes turnCost, cumulativeCost, and usage (raw cost breakdown from the model provider). On models priced by tokens a turn is one reply; on models priced by time it is the time since the previous update. |
task_output |
server → client | Transcript messages prefixed with TRANSCRIPT_USER: or TRANSCRIPT_AI: |
task_session_stopped |
server → client | The server is ending the session after the turn that reached a spend limit or used up the balance: reason is spend_limit or balance, with code and message. The closing events follow (see Ending a Session) |
task_end |
server → client | The model process has exited. Post-processing follows. Wait for task_postprocess_end to close the connection. |
task_postprocess_end |
server → client | Post-processing complete: safe to close the WebSocket connection |
task_session_end |
client → server | Gracefully end the session |
task_session_interrupt |
client → server | Stop the current reply on Wiro-hosted models such as PersonaPlex (see Interrupting AI Speech) |
Audio Format
Both directions (microphone → server, server → client) use the same format:
| Property | Value |
|---|---|
| Format | PCM (raw, uncompressed) |
| Bit depth | 16-bit signed integer (Int16) |
| Sample rate | 24,000 Hz (24 kHz) |
| Channels | Mono (1 channel) |
| Byte order | Little-endian |
| Chunk size | Any size. The examples on this page send 4,800 samples (200 ms) = 9,600 bytes. |
The server passes each microphone frame to the model as it arrives. Smaller chunks, such as 20 ms (480 samples, 960 bytes), reach the model sooner, so it notices sooner when the user starts talking.
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:
- Request microphone with
getUserMedia(enable echo cancellation and noise suppression) - Create an
AudioContextat 24,000 Hz sample rate - Use an AudioWorklet to buffer and convert samples to Int16
- Send each chunk as
tasktoken|pcm_databinary frame
Receiving AI Audio
AI responses arrive as binary WebSocket frames in the same PCM Int16 24 kHz format. To play them:
- Check if the message is a
Blob(binary) before parsing as JSON - Find the pipe
|separator and extract audio data after it - Convert Int16 → Float32 and create an
AudioBuffer - 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:for what the user saidTRANSCRIPT_AI:for 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."
}
Each message is final: a later message never repeats or corrects an earlier one. A user message usually holds one turn of speech, and an AI message the reply for that turn, so show each message as a new line.
Interrupting AI Speech
The user can talk over the AI to take over the conversation. How the reply stops depends on the model:
- Models with their own barge-in (the OpenAI realtime family, Gemini Live and ElevenLabs) stop the reply on their own when they hear the user. Keep streaming microphone audio while the AI talks. No message is needed.
- Wiro-hosted realtime models such as PersonaPlex stop the reply when you send
task_session_interrupt.
{
"type": "task_session_interrupt",
"tasktoken": "YOUR_SOCKET_ACCESS_TOKEN"
}
When a Wiro-hosted model receives this:
- The AI immediately stops generating audio
- A final
task_stream_endis sent for the interrupted turn - The session continues: the user can speak and the AI will respond to the next input
With either kind of model, stop your own audio playback as soon as the user starts talking. Audio that has already reached the client keeps playing until you stop it.
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.
The server can also end a session on its own: after a period without speech, or after the turn that uses up your balance or reaches a spend limit (see below). It then sends the same closing events, ending with task_postprocess_end. The server never sends task_session_end; that message only goes from the client to the server.
When a spend limit or the balance ends the session, the server first sends task_session_stopped, right after that turn's task_cost:
{
"type": "task_session_stopped",
"id": "534574",
"reason": "spend_limit",
"code": 93,
"message": "This team's monthly spend limit is reached ($50.00 of $50.00). It resets on December 1, 2026 at 00:00 UTC.",
"result": true,
"success": null,
"terminal": false,
"exitCode": null
}
reason is spend_limit, with code 93, or balance, with code 97. For a spend limit, message is the refusal /Run would give for that limit, which names it and says when it resets. For the balance it is The balance ran out, so the session ended. The event is not a failure: the usual closing events follow, and task_postprocess_end reports success. When it arrives, stop sending microphone audio, show message and keep listening until task_postprocess_end. You don't need to send task_session_end. The event can also come after you sent task_session_end, when that last turn uses up the limit or the balance; the session ends either way. No task_session_stopped is sent when a session ends for any other reason.
Safety: If the client disconnects without sending task_session_end, the server automatically terminates the session to prevent the pipeline from running indefinitely (and the provider from continuing to charge). Always send task_session_end explicitly for a clean shutdown.
Insufficient balance: The session is charged turn by turn as it runs. When a charged turn uses up your available balance (the team wallet's balance when you use a team project's API key), the server stops the session right after that turn. That turn is charged in full, and so is any final usage reported while the session closes, so your balance can end slightly below zero. You still receive the final task_cost and task_end events, and task_session_stopped with reason balance and code 97 says why the session ended.
Realtime Text to Speech
Build streaming text-to-speech apps with realtime AI models.
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:
- Run the realtime TTS model via POST /Run with your text prompt in the parameters
- Connect to the WebSocket and send
task_infowith yoursocketaccesstoken - Wait for
task_stream_ready: the model has loaded and is generating audio - Receive AI audio as binary frames and play them
- End the session with
task_session_endor wait for the stream to finish naturally
How It Differs from Realtime Voice Conversation
| Realtime Voice Conversation | Realtime Text to Speech | |
|---|---|---|
| Input | Microphone audio (streamed) | Text (sent with the run request) |
| Output | AI audio + transcripts | AI audio only |
| Direction | Bidirectional (client ↔ server) | Server → client only |
| Microphone | Required | Not required |
| Transcripts | TRANSCRIPT_USER: / TRANSCRIPT_AI: via task_output |
None |
| Use case | Interactive voice chat | Narration, voiceover, assistants |
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 and an optional reference audio clip for voice cloning. Example run for MOSS-TTS-Realtime:
curl -X POST "https://api.wiro.ai/v1/Run/openmoss/moss-tts-realtime" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"text": "Hello, this is a realtime text-to-speech demo."
}'
Important: Parameters vary per model. Always check the model's detail page or use /Tool/Detail to get the exact parameter list before integrating. The run response returns a socketaccesstoken used to subscribe to the WebSocket.
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"
}));
};
Note: Both standard and realtime models use type: "task_info" with tasktoken to register on the WebSocket. The registration flow is identical to Realtime Voice Conversation.
Realtime Events
During a realtime TTS session, you'll receive these WebSocket events:
| Event | Description |
|---|---|
task_stream_ready |
Session is ready: the model is generating audio and will begin sending chunks |
task_stream_end |
The model finished generating audio for the current segment |
task_cost |
Cost update: includes turnCost, cumulativeCost, and usage (raw cost breakdown from the model provider) |
task_session_stopped |
The server is ending the session after the turn that reached a spend limit or used up the balance: reason is spend_limit or balance, with code and message. The closing events follow (see Ending a Session) |
task_end |
The model process has exited. Post-processing follows. Wait for task_postprocess_end to close the connection. |
task_postprocess_end |
Post-processing is complete. Safe to close the WebSocket connection. |
No task_output events. Unlike voice conversation, TTS sessions do not produce transcript events. The input text is already known (you provided it), and the AI output is audio, not text.
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.
| Property | Value |
|---|---|
| Format | PCM (raw, uncompressed) |
| Bit depth | 16-bit signed integer (Int16) |
| Sample rate | 24,000 Hz (24 kHz) |
| Channels | Mono (1 channel) |
| Byte order | Little-endian |
| Chunk size | Variable (typically 200 ms = 4,800 samples = 9,600 bytes) |
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:
- Find the first
|byte in the binary frame - Everything after it is raw PCM Int16 audio data
- Convert Int16 samples to your playback format (e.g., Float32 for Web Audio API)
Client → server: In TTS mode, you do not send binary audio frames. The only messages you send are task_info (to register) and task_session_end (to end the session).
Receiving AI Audio
AI speech arrives as binary WebSocket frames in PCM Int16 24 kHz format. To play them:
- Check if the incoming message is binary (a
Blobin JavaScript,bytesin Python) before attempting JSON parse - Find the pipe
|separator and extract audio data after it - Convert Int16 → Float32 and create an
AudioBuffer - Schedule gapless playback using
AudioBufferSourceNodeto avoid clicks between chunks
Gapless Playback
Audio arrives in many small chunks. To play them seamlessly:
- Track a
nextPlayTimevariable initialized to0 - For each chunk, schedule it at
max(audioContext.currentTime, nextPlayTime) - Advance
nextPlayTimeby 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.
The server can also end a session on its own, after the turn that uses up your balance or reaches a spend limit. It then sends the same closing events, ending with task_postprocess_end.
When a spend limit or the balance ends the session, the server first sends task_session_stopped, right after that turn's task_cost:
{
"type": "task_session_stopped",
"id": "534574",
"reason": "spend_limit",
"code": 93,
"message": "This team's monthly spend limit is reached ($50.00 of $50.00). It resets on December 1, 2026 at 00:00 UTC.",
"result": true,
"success": null,
"terminal": false,
"exitCode": null
}
reason is spend_limit, with code 93, or balance, with code 97. For a spend limit, message is the refusal /Run would give for that limit, which names it and says when it resets. For the balance it is The balance ran out, so the session ended. The event is not a failure: the usual closing events follow, and task_postprocess_end reports success. When it arrives, let the audio you already have finish playing, show message and keep listening until task_postprocess_end. You don't need to send task_session_end. The event can also come after you sent task_session_end, when that last turn uses up the limit or the balance; the session ends either way. No task_session_stopped is sent when a session ends for any other reason.
Safety: If the client disconnects without sending task_session_end, the server automatically terminates the session to prevent the pipeline from running indefinitely (and the provider from continuing to charge). Always send task_session_end explicitly for a clean shutdown.
Insufficient balance: The session is charged turn by turn as it runs. When a charged turn uses up your available balance (the team wallet's balance when you use a team project's API key), the server stops the session right after that turn. That turn is charged in full, and so is any final usage reported while the session closes, so your balance can end slightly below zero. You still receive the final task_cost and task_end events, and task_session_stopped with reason balance and code 97 says why the session ended.
Realtime Speech to Text
Transcribe live microphone audio into text in real time using streaming ASR models.
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:
- Run the realtime STT model via POST /Run to get a
socketaccesstoken - Connect to the WebSocket and send
task_infowith your token - Wait for
task_stream_ready: the model is ready to receive audio - Stream microphone audio as binary frames (client → server)
- Receive transcript text as
task_outputmessages withTRANSCRIPT_USER:prefix - End the session with
task_session_end
Key difference from Voice Conversation: No binary audio is sent back from the server. All server → client messages are JSON text events.
How It Differs from Realtime Voice Conversation
| Realtime Voice Conversation | Realtime Speech to Text | |
|---|---|---|
| Input | Microphone audio (streamed) | Microphone audio (streamed) |
| Output | AI audio + transcripts | Transcript text only |
| Direction | Bidirectional (client ↔ server) | Client → server audio, server → client text |
| Binary frames from server | Yes (AI audio) | No (all server messages are JSON) |
| Transcripts | TRANSCRIPT_USER: and TRANSCRIPT_AI: |
TRANSCRIPT_USER: only |
| Use case | Interactive voice chat | Live dictation, captioning, meeting transcription |
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 a transcription delay setting that trades speed for accuracy; some models also take a language. Example run for Voxtral Mini 4B Realtime:
curl -X POST "https://api.wiro.ai/v1/Run/mistralai/voxtral-mini-4b-realtime-2602" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"transcriptionDelay": "balanced"
}'
Important: Parameters vary per model. Always check the model's detail page or use /Tool/Detail to get the exact parameter list before integrating. The run response returns a socketaccesstoken used to subscribe to the WebSocket.
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"
}));
};
Note: Both standard and realtime models use type: "task_info" with tasktoken to register on the WebSocket.
Realtime Events
During a realtime speech-to-text session, you'll receive these WebSocket events:
| Event | Direction | Description |
|---|---|---|
task_stream_ready |
server → client | Session is ready: start sending microphone audio |
task_output |
server → client | Transcript text prefixed with TRANSCRIPT_USER: |
task_stream_end |
server → client | Transcription stream has ended: no more transcripts will arrive |
task_cost |
server → client | Cost update: includes turnCost, cumulativeCost, and usage breakdown. On models priced by time, each update covers the time since the previous one. |
task_session_stopped |
server → client | The server is ending the session after the turn that reached a spend limit or used up the balance: reason is spend_limit or balance, with code and message. The closing events follow (see Ending a Session) |
task_end |
server → client | The model process has exited. Post-processing follows. Wait for task_postprocess_end before closing. |
task_postprocess_end |
server → client | Post-processing complete: safe to close the WebSocket now. |
Unlike voice conversation, there are no binary audio frames from the server. Every server message is a JSON text event.
Audio Format
Audio flows in one direction only: client → server.
| Property | Value |
|---|---|
| Format | PCM (raw, uncompressed) |
| Bit depth | 16-bit signed integer (Int16) |
| Sample rate | 24,000 Hz (24 kHz) |
| Channels | Mono (1 channel) |
| Byte order | Little-endian |
| Chunk size | Any size. The examples on this page send 4,800 samples (200 ms) = 9,600 bytes. |
The server passes each frame to the model as it arrives. Smaller chunks, such as 20 ms (480 samples, 960 bytes), reach the model sooner.
The server internally resamples to the model's native rate (e.g. 16 kHz for Voxtral). Always send at 24 kHz. The server handles conversion.
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:
- Request microphone with
getUserMedia(enable echo cancellation and noise suppression) - Create an
AudioContextat 24,000 Hz sample rate - Use an AudioWorklet to buffer and convert samples to Int16
- Send each chunk as
tasktoken|pcm_databinary frame - Continue sending until you end the session
Tip: You can send audio continuously. The model handles silence detection and only returns transcripts when speech is detected.
Transcripts
Transcripts arrive as task_output messages with the TRANSCRIPT_USER: prefix. Each message carries the next piece of transcribed speech, usually a word or a short phrase:
{
"type": "task_output",
"message": "TRANSCRIPT_USER:What's"
}
{
"type": "task_output",
"message": "TRANSCRIPT_USER:the"
}
{
"type": "task_output",
"message": "TRANSCRIPT_USER:weather"
}
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. A message never repeats or corrects earlier text, so add each one to what you have instead of replacing it. To build a full transcript, concatenate all received messages with spaces:
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(' '));
}
Note: Unlike voice conversation, there is no TRANSCRIPT_AI: prefix. All transcripts are user speech.
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.
The server can also end a session on its own: after a period without speech, or after the turn that uses up your balance or reaches a spend limit (see below). It then sends the same closing events, ending with task_postprocess_end. The server never sends task_session_end; that message only goes from the client to the server.
When a spend limit or the balance ends the session, the server first sends task_session_stopped, right after that turn's task_cost:
{
"type": "task_session_stopped",
"id": "534574",
"reason": "spend_limit",
"code": 93,
"message": "This team's monthly spend limit is reached ($50.00 of $50.00). It resets on December 1, 2026 at 00:00 UTC.",
"result": true,
"success": null,
"terminal": false,
"exitCode": null
}
reason is spend_limit, with code 93, or balance, with code 97. For a spend limit, message is the refusal /Run would give for that limit, which names it and says when it resets. For the balance it is The balance ran out, so the session ended. The event is not a failure: the usual closing events follow, and task_postprocess_end reports success. When it arrives, stop sending microphone audio, show message and keep listening until task_postprocess_end. You don't need to send task_session_end. The event can also come after you sent task_session_end, when that last turn uses up the limit or the balance; the session ends either way. No task_session_stopped is sent when a session ends for any other reason.
Safety: If the client disconnects without sending task_session_end, the server automatically terminates the session to prevent the pipeline from running indefinitely (and the provider from continuing to charge). Always send task_session_end explicitly for a clean shutdown.
Insufficient balance: The session is charged turn by turn as it runs. When a charged turn uses up your available balance (the team wallet's balance when you use a team project's API key), the server stops the session right after that turn. That turn is charged in full, and so is any final usage reported while the session closes, so your balance can end slightly below zero. You still receive the final task_cost and task_end events, and task_session_stopped with reason balance and code 97 says why the session ended.
Files
Manage folders and upload files for use with AI models.
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
Authentication and Public File URLs
All file-management endpoints, including FolderCreate, Upload, List, Edit, Delete, CheckDisk, and Unzip, require normal Wiro project or Bearer authentication.
- API Key Only projects: send
x-api-key. - Signature projects: send
x-api-key,x-nonce, andx-signature. See Authentication. - Dashboard requests: use the signed-in user's Bearer token.
The returned GET /File/:accessKey/:fileName URL intentionally remains public so browsers, AI model workers, and external clients can display the file without account credentials. Possession of the generated access key grants read access only; it does not grant file-management permission.
Code examples: The examples on this page show API Key Only authentication. Signature-authenticated projects must include the nonce and signature headers, as in this example:
NONCE="$(date +%s)"
SIGNATURE="$(printf '%s' "${YOUR_API_SECRET}${NONCE}" \
| openssl dgst -sha256 -hmac "${YOUR_API_KEY}" \
| awk '{print $NF}')"
curl -X POST "https://api.wiro.ai/v1/File/FolderCreate" \
-H "Content-Type: application/json" \
-H "x-api-key: ${YOUR_API_KEY}" \
-H "x-nonce: ${NONCE}" \
-H "x-signature: ${SIGNATURE}" \
-d '{"name":"training-data"}'
POST /File/FolderCreate
Creates a new folder to organize your uploaded files.
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Folder name |
parentid |
string | No | Parent folder ID for nested structure (omit for root) |
Note: Folder names only allow letters, numbers, hyphens, and underscores (A-Z a-z 0-9 _ -).
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
file |
file | Yes | The file to upload (multipart form field) |
folderid |
string | No | Target folder ID (uploads to user's default folder if omitted) |
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 an
inputImageUrl parameter. Pass the URL returned from the upload response.
You don't always need to upload files first. Most models take a public URL in place of an upload, and the parameter's type decides where it goes: a combinefileinput takes it in the field itself (for example inputImage on most image models), a fileinput takes it in its {id}Url field (for example inputImageUrl), and a multifileinput takes a list in the field that puts Url before Multiple (for example inputDocumentUrlMultiple). See Model Parameters for each pattern.
{
"inputImageUrl": "https://cdn1.wiro.ai/...",
"scale": 4
}
Pricing
Understand how billing works for AI model runs on Wiro.
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
| Billing Method | Code | How it works |
|---|---|---|
| Per Request | cpr |
Fixed cost per run, regardless of output. Most common for image generation, image editing, and simple models. |
| Per Second | cps |
Cost per second of processing time. When no dynamic pricing is set, this is the default: cost = elapsed seconds × cps rate. |
| Per Output | cpo |
Cost per output item generated. Multiple files = pay per file. No output = base price charged once. |
| Per Token | cpt |
Cost per token used. Total tokens (input + output) extracted from model's usage metadata. Used for LLM models. |
Usage-Based Methods
| Billing Method | Code | How it works |
|---|---|---|
| Per Pixel | cp-pixel |
Cost based on output resolution. Each 1,048,576 pixels (1024×1024) = one tier. Can include per-input-image costs (priceInput). |
| Per Audio Second | cp-audiosecondslength |
Cost per second of input audio duration. |
| Per Character | cp-promptlength |
Cost per character in the input prompt. Total = prompt length × price. |
| Per Video Second | cp-outputVideoLength |
Cost per second of generated output video. |
Special Methods
| Billing Method | Code | How it works |
|---|---|---|
| Per Realtime Turn | cp-realtimeturn |
For realtime voice models. Billing per conversation turn, deducted in real time during the session. |
| Model-Reported | cp-readoutput |
The model reports its cost when the run ends. |
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:
| Field | Type | Description |
|---|---|---|
inputs |
object | The input parameter combination this price applies to. Empty {} means the price applies to all configurations. |
price |
number | The cost in USD for this configuration. |
priceMethod |
string | The billing method code (see tables above). |
priceExtra |
number (optional) | Extra cost per additional tier. Used by cp-pixel: each additional 1MP tier costs this amount. |
priceInput |
number (optional) | Per-input cost. Used by cp-pixel: each input image incurs this cost per 1MP 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:
| Resolution | Duration | Price |
|---|---|---|
| 480p | 5 seconds | $0.06 |
| 720p | 5 seconds | $0.13 |
| 1080p | 5 seconds | $0.29 |
| 480p | 10 seconds | $0.12 |
| 720p | 10 seconds | $0.26 |
| 1080p | 10 seconds | $0.58 |
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 the model's own rate or Wiro's default per-second 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
Via the API
Check the totalcost field in Task/Detail responses to see the cost of individual runs:
{
"tasklist": [{
"status": "task_postprocess_end",
"pexit": "0",
"totalcost": "0.003510000000",
"elapsedseconds": "6.0000"
}]
}
Via MCP
The MCP server provides three ways to check costs:
get_task: returns full task details includingtotalcostget_task_price: dedicated tool that returns just the cost, billing status, and duration. Clearly indicates whether the task was billed or not.get_account: withrecent_transactions, lists the wallet's latest transactions, newest first, with what each one was for. Use it to check that a charge landed.
Dashboard
View your overall balance, usage history, and billing details in the Dashboard.
Spend Limits
To cap what you spend, set monthly or daily spend limits under Controls > Spend Limits in the dashboard or with the /SpendLimit endpoints: for the whole wallet, one API key, one team member, one way in such as the API or the LLM gateway, or one agent. Once a limit is reached, new work it covers is refused with error code 93, and an alert email can warn you before that. See Spend Limits.
Concurrency Limits
Understand and manage how many requests you can run simultaneously on Wiro.
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, your limit is one unfinished task for each full $10 of balance, never less than 1. So $20 allows 2, $55 allows 5 and $250 allows 25.
- When your balance is above $250, there is no concurrency limit.
The balance is the credit that can pay for the model you run. Coupon credit that only works on other models is left out, so for those runs the limit can be lower than your wallet total would give.
For a team project's API key (or the team workspace in the dashboard), the limit uses the team wallet's balance, and every unfinished team task counts toward it, whichever member started it. Personal tasks count only against your personal balance. See Team Billing & Spending.
Examples
| Account Balance | Concurrent Task Limit |
|---|---|
| $10 | 1 concurrent task (minimum) |
| $50 | 5 concurrent tasks |
| $100 | 10 concurrent tasks |
| $150 | 15 concurrent tasks |
| $250 | 25 concurrent tasks |
| Above $250 | Unlimited (no limit applied) |
The formula: max(1, floor(balance_usd * 0.10)) while the balance is $250 or less. Above $250 there is no concurrency limit.
What Counts as Active
Every unfinished task counts toward your concurrency limit, from task_queue until it reaches one of these statuses:
task_postprocess_end: task completed (success or failure)task_cancel: task was cancelled or killed
Until then the task counts, including while it waits in the queue and while it is in task_error, which does not close a task. Once it 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
| Code | Meaning | Action |
|---|---|---|
96 |
Concurrent task limit reached | Wait for a running task to finish, or add funds |
97 |
Insufficient balance | Add funds to your account |
Handling Code 96
A refused request returns HTTP 200 with "result": false and an error with code 96. No task is created and nothing is charged. Handle it in one of these ways:
- Wait and retry: send the same request again after a growing wait, for example 2, 4, then 8 seconds, up to a minute. The code examples on this page do this: they look for the number
96inerrors[].code, retry only that code, treat"result": trueas success and stop after 8 attempts. - Queue on your side: keep at most as many unfinished tasks as your limit allows, and send the next request when a task reaches
task_postprocess_endortask_cancel(Task/Detail or the WebSocket). Tasks started on the website, by agents and by workflows, and in a team by other members, use the same slots. - Direct LLM Gateway: through the Direct LLM Gateway the refusal arrives as HTTP
429with error typerate_limit_errorand aretry-afterheader; wait that many seconds before you retry. A streamed Responses request has already answered200, so it ends withresponse.failedcarrying coderate_limit_exceededand has no such header; use a growing wait there. - Wiro MCP server: through the Wiro MCP server,
run_modelreturns the same message as its tool error.
Increasing Your Limit
To increase your concurrency limit, add credits to your account. Your limit is recalculated automatically based on your current balance at the time of each run request.
Best Practices
-
Check error code
96: if you get this error, wait for a running task to complete before submitting new ones. See Handling Code 96. -
Use WebSocket for monitoring: instead of polling
/Task/Detailrepeatedly, connect via WebSocket to get real-time updates without extra API calls. -
Use bounded MCP waits:
run_modelwaits up to 45 seconds by default and returns a recoverable token when the task is still active. Continue withwait_for_task; do not callrun_modelagain for the same request. Usewait=falseonly when you need the token immediately, andget_taskfor a one-time status check. - Implement exponential backoff: if polling task status, start at 3 seconds and increase the interval for longer tasks.
Spend Limits
Cap what a personal account or a team can spend in a month or a day: the whole wallet, one team member, one API key, a surface such as the LLM gateway, or one agent.
How Spend Limits Work
A spend limit caps what a wallet can spend in a month or a day. Limits work the same way for a personal account's wallet and for a team's wallet. The limits of the workspace a call runs in apply: a team project's API key runs in its team, a personal project's key in your personal account, and the dashboard in the workspace you have selected.
Manage limits in the dashboard under Controls > Spend Limits, for your personal account or for the team workspace you have selected, or with the /SpendLimit endpoints below. Team and member limits set before this system were moved into it as monthly limits of the same amount.
What a Limit Caps
Each limit caps one scope of the wallet's spending:
| Scope | target |
What it caps |
|---|---|---|
account |
None | The whole wallet. In a team, the whole team's spending |
member |
The member's useruuid from /Team/Member/List |
One team member's spending in the team (team wallets only). A member's spending includes their dashboard runs in the team workspace and every run made with the API key of a team project they created |
project |
The project's id from /Project/List |
One API key: what is spent with that project's key |
surface |
web, api, mcp, llm-gateway, extension or agent |
One way in (see Surfaces below) |
agent |
The agent's guid (its useragentguid) |
One deployed agent: what the agent itself spends, its own model runs and the credits its replies use (100 credits = $1). Its plan, upgrades and credit packs count toward the wallet's other limits, not this one |
Surfaces
| Surface | Label | Covers |
|---|---|---|
web |
the dashboard | The Wiro dashboard, including Studio and the Workflow Agent used there |
api |
the API | Calls with an API key, including /sync and the Wiro MCP package when you run it yourself |
mcp |
MCP | The hosted Wiro MCP server at mcp.wiro.ai |
llm-gateway |
the LLM gateway | The OpenAI and Anthropic compatible LLM gateway at llm.wiro.ai |
extension |
the browser extensions | Only the Wiro browser extensions |
agent |
agents | Your deployed agents' own runs |
Studio and Workflow Agent messages count on the surface they were sent from. Refusal messages and /SpendLimit/Usage name a surface by its label.
Periods and Amounts
A limit's period is month (the default), which resets on the 1st of each month at 00:00 UTC, or day, which resets every day at 00:00 UTC. A scope and target can have one monthly limit and one daily limit.
amountusd is the limit in USD, rounded to cents. Once rounded, it must be at least 0.01. A limit counts everything spent in its current period, also what was spent before the limit was added, so a new limit below that amount is used up at once.
What Counts
Every charge to the wallet for usage counts: model runs, workflow runs, realtime sessions, Studio, the Workflow Agent, agent plans, upgrades and credit packs. Deposits are not spending.
The models Studio runs for you are checked and counted like the runs you start yourself: against the account's or the team's limits, your member limit in a team, the limit of the API key you sent the message with and the limit of the surface you sent it from. What the chat of Studio and the Workflow Agent costs counts toward your limits too.
When Limits Are Checked
Limits are checked before work starts:
- Model runs, workflow runs and workflow resumes, and each step of a workflow run before the step starts
- Studio and Workflow Agent messages, and the models Studio runs for you
- An agent deploy, upgrade, renewal or credit pack purchase that a person starts
- Messages to an agent, against that agent's own limit
When the price of the work is known before it starts, as for fixed-price models, workflow runs and agent purchases, the work is refused if spending so far, plus what work in progress holds, plus that price would go over the limit. Otherwise it is refused once the limit has no room left.
Work that is already running finishes and is charged, with two exceptions. A realtime session ends after the turn that uses up a limit, the same way it ends when the balance runs out: its WebSocket clients get a task_session_stopped event with reason spend_limit, code 93 and the refusal /Run would give (see Realtime Voice). An agent's voice call is a realtime session too and ends the same way: a web voice call then gets session_end with reason spend_limit (see Web Voice), and a caller on the phone hears a short notice before the call ends. An agent whose own limit is used up pauses at its next model call, even in the middle of a reply (see below).
Automatic monthly renewals of running agents are never refused by a limit. They count toward the account's limit and, in a team, toward the limit of the member who started the plan, never toward a surface, API key or agent limit.
Work in Progress
A run that starts holds its expected price against every limit that covers it, until it is charged or ends. The next check counts what is held, so runs started at the same time can pass a limit by one run at most. A run whose price is not known before it starts goes ahead while the limit has room. Refusal messages show what is held, and so does heldusd on the limits of /SpendLimit/List and in /SpendLimit/Usage.
When a Limit Is Reached
New work the limit covers is refused with HTTP 200, result: false and error code 93. The message names the limit and says when it resets:
{
"result": false,
"errors": [
{
"code": 93,
"message": "This API key's monthly spend limit is reached ($50.20 of $50.00). It resets on December 1, 2026 at 00:00 UTC."
}
]
}
When the price of the work is known before it starts, the message says what is left instead, for example This team's monthly spend limit has $3.10 left of $500.00, and this run costs $4.00. It resets on December 1, 2026 at 00:00 UTC. A daily limit says daily instead of monthly, and its message ends with It resets at 00:00 UTC. When work in progress holds part of the limit, the message also says how much.
| Limit | The message starts with |
|---|---|
A personal account's account limit |
Your monthly spend limit |
A team's account limit |
This team's monthly spend limit |
member |
Your monthly spend limit in this team |
project |
This API key's monthly spend limit |
surface |
The monthly spend limit for and the surface's label, for example The monthly spend limit for the LLM gateway |
agent |
This agent's monthly spend limit |
Nothing runs and nothing is charged. Retrying does not help until the limit resets or someone who manages it raises it. Through the LLM gateway the refusal is an HTTP 402 error with code spend_limit_reached, and the MCP server returns it as a tool error.
When an agent's own limit is used up, the agent pauses. A turn that is running stops at its next model call (see Failed turns), new messages to the agent are refused, and its Scheduled Tasks are paused rather than failed. In Telegram, Slack and Discord it tells people so in a plain sentence, with the time the limit resets when that is known. Once the limit resets, is raised or is removed, the agent answers again and each Scheduled Task runs at its next scheduled time, with no restart.
Alert Emails
A limit sends an alert email when spending reaches its alertpct: 50, 80 (the default) or 90 percent of the limit, or null for no alert email. It sends a used-up email when the limit is reached. Each email goes out once per limit and period, and changing the limit re-arms both for the current period. The emails link to the Spend Limits page of the workspace the limit belongs to.
A personal account's limits email the account. A team's limits email the team's admins and the organization owner, and also the member a member limit is for, the person who created the API key a key limit is for, and the owner of the agent an agent limit is for.
Who Can Change Limits
- Personal account: its owner
- Team: a team admin or the organization owner. The person who created the team is one of its admins
Every team member can read the team's limits and spending with /SpendLimit/List and /SpendLimit/Usage. A member who is not an admin can't change any limit: not their own member limit, and not the limits of the API keys they created or the agents they deployed. A deployed agent's own calls to the /SpendLimit endpoints are refused with HTTP 403, reads included.
Changing Limits With the API
/SpendLimit/Set, /SpendLimit/Remove and /SpendLimit/Preview work in the dashboard, with a signed-in user's Bearer token and with an API key:
- With an API key, the call acts as the person who created the key's project, in that project's workspace: the creator's personal account for a personal project, the team for a team project. The key follows its creator's current role: while the creator is a team member who is not an admin, the key can read limits but not change them.
- With a Bearer token, the call acts as you, in your personal account. To work in a team, send the team's guid in the
x-team-guidheader. A call whosex-team-guidnames a team you are not a member of, and whose organization you don't own, is refused withYou are not a member of this team.Calls with an API key ignore this header.
/SpendLimit/List and /SpendLimit/Preview return the workspace they work in, so you can check where a change lands before you make it. Changes made with API keys are limited to 60 per workspace in any hour, counting spend limits and Model Access rules together. Preview does not count. Each change is recorded with who made it and how.
POST /SpendLimit/List
Returns the spend limits of the call's workspace, each with what has been spent in its current period, and how the call itself counts. A team project's API key reads its team, a personal project's key your personal account, and the dashboard the workspace you have selected (see Changing Limits With the API). Any team member can call it, and it works with an API key. Send an empty body: {}.
Response
{
"result": true,
"errors": [],
"workspace": {
"type": "team",
"teamguid": "0d9aade4-d31b-4b97-88f3-a90482f080ea",
"canmanage": false
},
"caller": {
"surface": "api",
"projectid": "48211"
},
"limits": [
{
"guid": "e93fc393-aedd-4828-a6be-fbc2853d3202",
"scope": "account",
"target": "",
"targetlabel": null,
"period": "month",
"amountusd": 500,
"alertpct": 90,
"periodstart": 1793491200,
"resetsat": 1796083200,
"createdat": 1793805600,
"updatedat": 1793805600,
"updatedby": { "useruuid": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "label": "the organization owner" },
"spentusd": 248.7,
"heldusd": 3.5
},
{
"guid": "f4134ddb-e837-44a9-9b36-0af44241f3ef",
"scope": "member",
"target": "3f5a9c20-6d41-4b8e-a1c7-5e9d0f2b4c61",
"targetlabel": "Jane Doe",
"period": "month",
"amountusd": 150,
"alertpct": 80,
"periodstart": 1793491200,
"resetsat": 1796083200,
"createdat": 1793805600,
"updatedat": 1793805600,
"updatedby": null,
"spentusd": 120.5
},
{
"guid": "15be7fb3-c602-4ff1-a3f1-3afaa3996974",
"scope": "project",
"target": "48211",
"targetlabel": "Production",
"period": "month",
"amountusd": 100,
"alertpct": 80,
"periodstart": 1793491200,
"resetsat": 1796083200,
"createdat": 1794474300,
"updatedat": 1794474300,
"updatedby": { "useruuid": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "label": "John Doe" },
"spentusd": 88.2
}
]
}
| Field | Description |
|---|---|
workspace.type |
team or personal |
workspace.teamguid |
The team's guid, or null for a personal account |
workspace.canmanage |
Whether the caller can change limits in this workspace: true for a personal account's owner, a team admin and the organization owner, also with the API key of a project they created; false for other team members and their keys |
caller.surface |
The surface this call counts on, such as api for a call with an API key (see Surfaces) |
caller.projectid |
The project id of the API key the call used, or null without a key |
limits[].guid |
The limit's guid, for /SpendLimit/Remove |
limits[].scope |
account, member, project, surface or agent |
limits[].target |
The member's useruuid, the project id, the surface or the agent's guid; "" for account |
limits[].targetlabel |
The member's name, the project's name, the agent's title or the surface's label; null for account |
limits[].period |
month or day |
limits[].amountusd |
The limit in USD |
limits[].alertpct |
50, 80 or 90, or null for no alert email |
limits[].periodstart |
Start of the current period, in Unix seconds |
limits[].resetsat |
When the current period ends and the limit resets, in Unix seconds |
limits[].createdat, limits[].updatedat |
When the limit was added and last changed, in Unix seconds |
limits[].updatedby |
Who changed the limit last: useruuid and label, the person's name, or their email when they have no name. In a team, the owner of its organization who is not a member of the team is labeled the organization owner, and someone who has left the team has a null label. A change made with an API key names the person who created the key's project. updatedby is null when Wiro changed the limit last, as for the team and member limits moved into this system |
limits[].spentusd |
What has been spent in the current period, in USD |
limits[].heldusd |
When work in progress holds part of the limit: how much it holds, in USD (see Work in Progress) |
POST /SpendLimit/Set
Adds a spend limit to the call's workspace, or changes the existing limit with the same scope, target and period. Changing a limit re-arms its emails for the current period. Only the people who can change limits can call it (see Who Can Change Limits), in the dashboard, with a Bearer token or with an API key. To check a change first, send the same body to /SpendLimit/Preview.
| Parameter | Type | Required | Description |
|---|---|---|---|
scope |
string | Yes | "account", "member", "project", "surface" or "agent". See Spend Limits |
target |
string | For every scope but account |
The member's useruuid, the project's id, the surface (web, api, mcp, llm-gateway, extension or agent) or the agent's guid. Leave it out for account |
period |
string | No | "month" or "day". Default: "month" |
amountusd |
number | Yes | The limit in USD, rounded to cents. Once rounded, it must be at least 0.01 |
alertpct |
number | No | When the alert email goes out: 50, 80 or 90 percent of the limit, or null for no alert email. Default: 80 |
Examples
Cap the whole wallet at $500 a month, with the alert at 90%:
{
"scope": "account",
"amountusd": 500,
"alertpct": 90
}
Cap one API key at $100 a month:
{
"scope": "project",
"target": "48211",
"period": "month",
"amountusd": 100
}
Cap the LLM gateway at $25 a day, with no alert email:
{
"scope": "surface",
"target": "llm-gateway",
"period": "day",
"amountusd": 25,
"alertpct": null
}
Response
limit is the limit as saved, shaped like a row of /SpendLimit/List:
{
"result": true,
"errors": [],
"limit": {
"guid": "15be7fb3-c602-4ff1-a3f1-3afaa3996974",
"scope": "project",
"target": "48211",
"targetlabel": "Production",
"period": "month",
"amountusd": 100,
"alertpct": 80,
"periodstart": 1793491200,
"resetsat": 1796083200,
"createdat": 1794474300,
"updatedat": 1794474300,
"updatedby": { "useruuid": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "label": "John Doe" },
"spentusd": 61.4
}
}
Errors
| Error | Cause |
|---|---|
scope must be one of account, member, project, surface, agent. |
scope is missing or not one of the five scopes |
Member limits exist only in a team workspace. |
A member limit in a personal account |
target is required for this scope. |
No target for a member, project, surface or agent limit |
A surface is one of web, api, mcp, llm-gateway, extension, agent. |
A surface limit with another target |
target must be a project id. |
A project limit whose target is not a project id |
period must be month or day. |
Another period |
amountusd must be a positive number. |
amountusd is missing, zero or negative |
amountusd is too large. |
amountusd is over 10,000,000 |
amountusd must be at least 0.01. |
amountusd is above zero but rounds to less than one cent |
alertpct must be 50, 80 or 90, or null for no alert. |
Another alertpct |
You are not a member of this team. |
With a Bearer token, x-team-guid names a team you are not a member of, and whose organization you don't own |
Only a team admin or the organization owner can change this limit. |
In a team, a signed-in caller is not a team admin or the organization owner |
This API key acts as the person who created it, who is a member of this team. Only a team admin or the organization owner can change this limit. |
With an API key, the person who created the key's project is a team member who is not an admin |
That person is not an active member of this team. |
A member limit for someone who is not an active member of the team |
That API key's project is not in this workspace. |
A project limit for a project of another workspace |
That agent is not in this workspace. |
An agent limit for an agent of another workspace |
Too many changes to Spend Limits and Model Access in the last hour. Try again later. |
With API keys, this workspace's spend limits and Model Access rules have been changed 60 times in the last hour |
POST /SpendLimit/Preview
Shows what /SpendLimit/Set would do, and changes nothing. It takes the same body as /SpendLimit/Set and checks it the same way, so only the people who can change limits can call it. Use it to see which workspace a change lands in, the limit as it would be saved and the limit it would replace.
Example
Raise the Production API key's monthly limit to $150:
{
"scope": "project",
"target": "48211",
"period": "month",
"amountusd": 150
}
Response
{
"result": true,
"errors": [],
"preview": true,
"workspace": {
"type": "team",
"teamguid": "0d9aade4-d31b-4b97-88f3-a90482f080ea",
"canmanage": true
},
"limit": {
"guid": "15be7fb3-c602-4ff1-a3f1-3afaa3996974",
"scope": "project",
"target": "48211",
"targetlabel": "Production",
"period": "month",
"amountusd": 150,
"alertpct": 80,
"periodstart": 1793491200,
"resetsat": 1796083200,
"createdat": 1794474300,
"updatedat": null,
"updatedby": null,
"spentusd": 88.2
},
"existing": {
"guid": "15be7fb3-c602-4ff1-a3f1-3afaa3996974",
"scope": "project",
"target": "48211",
"targetlabel": "Production",
"period": "month",
"amountusd": 100,
"alertpct": 80,
"periodstart": 1793491200,
"resetsat": 1796083200,
"createdat": 1794474300,
"updatedat": 1794474300,
"updatedby": { "useruuid": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "label": "John Doe" },
"spentusd": 88.2
}
}
| Field | Description |
|---|---|
preview |
Always true: nothing was changed |
workspace |
The workspace the change would be made in, as in /SpendLimit/List: type, teamguid and canmanage, which is always true here |
limit |
The limit as /SpendLimit/Set would save it, shaped like a row of /SpendLimit/List, with what has been spent in its current period. Its guid and createdat are those of the limit it would replace, or null for a new limit, and its updatedat and updatedby are null |
existing |
The current limit with the same scope, target and period, which the change would replace, or null when there is none |
When limit.spentusd is already at or above the new amount, the limit is used up as soon as it is saved. The errors are those of /SpendLimit/Set, except that Preview does not count toward the hourly cap on changes made with API keys.
POST /SpendLimit/Remove
Removes a spend limit from the call's workspace. The people who can change limits can remove one, in the dashboard, with a Bearer token or with an API key.
| Parameter | Type | Required | Description |
|---|---|---|---|
guid |
string | Yes | The limit's guid from /SpendLimit/List |
Response
{
"result": true,
"errors": []
}
| Error | Cause |
|---|---|
guid is required. |
No guid was sent |
Limit not found in this workspace. |
The guid is not a limit of the call's workspace, or it was already removed |
You are not a member of this team. |
With a Bearer token, x-team-guid names a team you are not a member of, and whose organization you don't own |
Only a team admin or the organization owner can change this limit. |
In a team, a signed-in caller is not a team admin or the organization owner |
This API key acts as the person who created it, who is a member of this team. Only a team admin or the organization owner can change this limit. |
With an API key, the person who created the key's project is a team member who is not an admin |
Too many changes to Spend Limits and Model Access in the last hour. Try again later. |
With API keys, this workspace's spend limits and Model Access rules have been changed 60 times in the last hour |
POST /SpendLimit/Usage
Returns what the call's workspace has spent this month or today, in total and by surface, member, API key and agent. A team project's API key reads its team, a personal project's key your personal account, and the dashboard the workspace you have selected. Any team member can call it, and it works with an API key.
| Parameter | Type | Required | Description |
|---|---|---|---|
period |
string | No | "month" or "day". Default: "month" |
Response
{
"result": true,
"errors": [],
"usage": {
"period": "month",
"periodstart": 1793491200,
"resetsat": 1796083200,
"totalusd": 248.7,
"heldusd": 3.5,
"surfaces": [
{ "surface": "web", "label": "the dashboard", "spentusd": 40.1 },
{ "surface": "api", "label": "the API", "spentusd": 168.2, "heldusd": 3.5 },
{ "surface": "mcp", "label": "MCP", "spentusd": 12.5 },
{ "surface": "llm-gateway", "label": "the LLM gateway", "spentusd": 7.9 },
{ "surface": "extension", "label": "the browser extensions", "spentusd": 0 },
{ "surface": "agent", "label": "agents", "spentusd": 20 }
],
"members": [
{ "useruuid": "3f5a9c20-6d41-4b8e-a1c7-5e9d0f2b4c61", "label": "Jane Doe", "spentusd": 120.5 },
{ "useruuid": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "label": "John Doe", "spentusd": 108.2, "heldusd": 3.5 }
],
"projects": [
{ "projectid": "48211", "label": "Production", "spentusd": 88.2 },
{ "projectid": "48377", "label": "Staging", "spentusd": 80, "heldusd": 3.5 }
],
"agents": [
{ "useragentguid": "6e4bbd6f-6b73-4421-adae-e9599ba2e317", "label": "Support Agent", "spentusd": 20 }
]
}
}
| Field | Description |
|---|---|
usage.period |
month or day |
usage.periodstart, usage.resetsat |
Start and end of the period, in Unix seconds |
usage.totalusd |
What the wallet has spent in the period, in USD |
usage.heldusd |
What work in progress holds, in USD. Present only when it holds something (see Work in Progress) |
usage.surfaces |
One row per surface, always in the order web, api, mcp, llm-gateway, extension, agent, with its label |
usage.members |
Spending per team member, with the member's name as label. Empty for a personal account |
usage.projects |
Spending per API key, with the project's name as label |
usage.agents |
Spending per deployed agent, with the agent's title as label |
heldusd in a row of usage.surfaces, usage.members, usage.projects or usage.agents |
What work in progress holds for that row, present only when it holds something. A member, API key or agent whose only spending so far is held work is listed with spentusd 0 |
An agent plan's automatic renewal counts in totalusd and, in a team, in the row of the member who started the plan, but in no row of usage.surfaces, usage.projects or usage.agents, so those rows can add up to less than totalusd.
For other breakdowns, /Project/UsageSummary gives usage per project and /Task/Stat gives time-series task execution data. Both filter by the active workspace.
Model Access
Choose which models a personal account or a team can run: allow or block single models and whole categories, for the whole wallet, one team member, one API key, a surface such as the LLM gateway, or one agent.
How Model Access Works
A Model Access rule decides which models a wallet's work can run. Rules work the same way for a personal account's wallet and for a team's wallet. The rules of the workspace a call runs in apply: a team project's API key runs in its team, a personal project's key in your personal account, and the dashboard in the workspace you have selected.
Manage rules in the dashboard under Controls > Model Access, for your personal account or for the team workspace you have selected, or with the /ModelAccess endpoints below. A workspace without rules can run every model. Team allowlists and blocklists set before this system were moved into it as rules for the whole team.
What a Rule Covers
Each rule covers one scope of the wallet's work, the same scopes as spend limits. A scope and target can have one rule:
| Scope | target |
What it covers |
|---|---|---|
account |
None | Everything the wallet runs. In a team, every run in the team |
member |
The member's useruuid from /Team/Member/List |
One team member's runs in the team (team wallets only): their dashboard runs in the team workspace and every run made with the API key of a team project they created |
project |
The project's id from /Project/List |
One API key: the runs made with that project's key |
surface |
web, api, mcp, llm-gateway, extension or agent |
One way in (see Surfaces below) |
agent |
The agent's guid (its useragentguid) |
One deployed agent: the models it runs through Wiro, the chat models it answers with and its built-in voice |
Surfaces
| Surface | Covers |
|---|---|
web |
The Wiro dashboard, including Studio and the Workflow Agent used there |
api |
Calls with an API key, including /sync and the Wiro MCP package when you run it yourself |
mcp |
The hosted Wiro MCP server at mcp.wiro.ai |
llm-gateway |
The OpenAI and Anthropic compatible LLM gateway at llm.wiro.ai |
extension |
Only the Wiro browser extensions |
agent |
Your deployed agents' own runs |
Everything Else
Every rule has an Everything Else setting, access. It decides the models the rule names neither one by one nor by category:
allow(the default): every model can run except the ones the rule blocksblock: only the models and categories the rule allows can run
Categories
A rule can allow or block whole categories of models. Each category groups catalog categories, the values models carry in their categories field on /Tool/List and /Tool/Detail. A category also covers the models added to it later.
category |
Label | Catalog categories |
|---|---|---|
image |
Image Generation | text-to-image, image-to-image, image-editing, image-to-text |
video |
Video Generation | text-to-video, image-to-video, video-to-video, speech-to-video, talking-head, video-to-text, reference-to-video, audio-to-video, lip-sync |
audio |
Audio & Speech | text-to-speech, speech-to-text, speech-to-speech, video-to-music, voice-clone, text-to-audio, image-to-audio, realtime-conversation, realtime-tts, realtime-stt |
music |
Music Generation | music-generation, text-to-song, text-to-music, image-to-song, image-to-music |
3d |
3D Generation | 3d-generation, text-to-3d, image-to-3d |
llm |
LLM & Chat | chat, llm, partner-llm, rag, llm-reasoning |
utilities |
Utilities | utils |
A model is in every category that one of its catalog categories belongs to, so it can be in more than one. A model whose catalog categories belong to none of them is decided by its own entry or by Everything Else. /ModelAccess/List returns this list, and /ModelAccess/Check shows the categories of one model.
Single Models
A rule can also allow or block single models, named by their owner/slug, such as openai/gpt-6-2-astra, or by their id. A model's own entry comes before its categories, so a rule can block a category and still allow one model in it. A rule can name up to 500 models, and each must be a model listed on Wiro.
How One Rule Decides
A rule decides a model in this order:
- The model: when the rule names the model, that entry decides
- Its categories: otherwise, when the rule names one or more of the model's categories, they decide. If one of them is blocked, the model is blocked, even when another one is allowed
- Everything Else: otherwise the rule's
accessdecides
For example, a rule with Everything Else set to allow, Video Generation blocked and bytedance/seedance-v2-5-flash allowed lets every model run except video models, and Seedance v2.5 Flash is the one video model it lets run.
When Several Rules Apply
A run can meet several rules of its wallet: the whole account's, the member's in a team, the API key's, the surface's and the agent's. It goes ahead only when every rule that applies allows the model. A narrower rule can't open what a wider one blocks: when the account's rule blocks a model, an API key's rule that allows it does not let it run.
When more than one rule blocks the model, the refusal names the first of them in the order account, member, API key, surface, agent. /ModelAccess/Check shows how each rule decides a model.
Where Rules Apply
Rules are checked before work starts:
- Model runs:
/Runand its/syncwait, realtime sessions, the LLM gateway, the MCP server, the browser extensions and the dashboard - Workflow runs and resumes: every model step that will run must be allowed. Steps that will not run, such as the steps after a breakpoint, are not checked
- Studio and the Workflow Agent: the models Studio runs for you, and the chat model of each message you send to Studio or the Workflow Agent, follow your own rules like the runs you start yourself: the account's or the team's rule, your member rule in a team, the rule of the API key you sent the message with and the rule of the surface you sent it from. A message whose chat model a rule blocks, the
modelit names or the default chat model when it names none, is refused with code92before anything runs. Chat models are LLM & Chat models: a rule that blocks LLM & Chat blocks them unless it allows the chat model by name, and a rule that lets only selected models run blocks them unless it allows LLM & Chat or the chat model. The Workflow Agent runs nothing but its chat model./Studio/Statusand/StudioWorkflow/Statuslist the chat models your rules block - The models your deployed agents run through Wiro
- An agent's chat model: choosing one in the agent's settings, or sending
modelwithMessage/Send, follows that agent's own rule. If its rule blocks the model the agent already uses, its model calls are refused and the turn ends with[MODEL_NOT_ALLOWED]. A Scheduled Task whose model the rule blocks is paused rather than failed, and runs again at its next scheduled time once the model is allowed or another one is chosen - An agent's built-in voice: transcription of the voice notes people send the agent, and the voice replies it sends, follow that agent's own rule as Audio & Speech models. A rule that blocks Audio & Speech, or that lets only selected models run without allowing Audio & Speech, blocks them, even when it allows LLM & Chat. Voice notes are then not transcribed, and the agent replies in text. An agent that chats on a Gemini model has its voice notes transcribed by
google/gemini-3-flash, so a rule that names that model decides them too. A rule that does not name that model blocks those voice notes unless it lets both Audio & Speech and LLM & Chat models run
A change applies to work that starts after it. Work that is already running is not stopped, and a deployed agent's chat model and voice follow a change within about a minute. Browsing models is not affected: /Tool/List, /Tool/Detail and the LLM gateway's model list show the same models whatever the rules.
When a Model Is Blocked
A run of a model that a rule blocks is refused with HTTP 200, result: false and error code 92, even when the wallet has money. The message names the rule:
{
"result": false,
"errors": [
{
"code": 92,
"message": "This API key can only use selected models, and openai/gpt-6-2-astra is not one of them. Model Access rules decide which models can run."
}
]
}
The message also says what blocked the model:
| Blocked by | Example message |
|---|---|
| Everything Else | This API key can only use selected models, and openai/gpt-6-2-astra is not one of them. Model Access rules decide which models can run. |
| The model's own entry | This API key can't use openai/gpt-6-2-astra. Model Access rules decide which models can run. |
| One of the model's categories | MCP can't use Video Generation models, and bytedance/seedance-v2-5-flash is one of them. Model Access rules decide which models can run. |
| Rule | The message starts with |
|---|---|
A personal account's account rule |
Your account |
A team's account rule |
This team |
member |
You, with in this team after the model or category, for example You can't use openai/gpt-6-2-astra in this team. |
project |
This API key |
surface |
The surface's name: The dashboard, The API, MCP, The LLM gateway, The browser extensions or Agents |
agent |
This agent |
Nothing runs and nothing is charged. Retrying does not help: run a model the rules allow, or ask someone who manages the rule to change it. Through the LLM gateway the refusal is an HTTP 403 error with code model_not_allowed, and the MCP server returns it as a tool error.
Who Can Change Rules
- Personal account: its owner
- Team: a team admin or the organization owner. The person who created the team is one of its admins
Every team member can read the team's rules with /ModelAccess/List and /ModelAccess/Check. A member who is not an admin can't change any rule: not their own member rule, and not the rules of the API keys they created or the agents they deployed. A deployed agent's own calls to the /ModelAccess endpoints are refused with HTTP 403, reads included.
Changing Rules With the API
/ModelAccess/Set, /ModelAccess/Remove and /ModelAccess/Preview work in the dashboard, with a signed-in user's Bearer token and with an API key:
- With an API key, the call acts as the person who created the key's project, in that project's workspace: the creator's personal account for a personal project, the team for a team project. The key follows its creator's current role: while the creator is a team member who is not an admin, the key can read rules but not change them.
- With a Bearer token, the call acts as you, in your personal account. To work in a team, send the team's guid in the
x-team-guidheader. A call whosex-team-guidnames a team you are not a member of, and whose organization you don't own, is refused withYou are not a member of this team.Calls with an API key ignore this header.
/ModelAccess/List and /ModelAccess/Preview return the workspace they work in, so you can check where a change lands before you make it. Changes made with API keys are limited to 60 per workspace in any hour, counting spend limits and Model Access rules together. Preview does not count. Each change is recorded with who made it and how.
POST /ModelAccess/List
Returns the Model Access rules of the call's workspace, the categories a rule can name, and how the call itself counts. A team project's API key reads its team, a personal project's key your personal account, and the dashboard the workspace you have selected (see Changing Rules With the API). Any team member can call it, and it works with an API key. Send an empty body: {}.
Response
{
"result": true,
"errors": [],
"workspace": {
"type": "team",
"teamguid": "0d9aade4-d31b-4b97-88f3-a90482f080ea",
"canmanage": false
},
"caller": {
"surface": "api",
"projectid": "48211"
},
"rules": [
{
"guid": "a642eda4-68ef-4fa9-af15-7024f28b0332",
"scope": "account",
"target": "",
"targetlabel": null,
"access": "allow",
"categories": [
{ "category": "video", "label": "Video Generation", "access": "block" }
],
"models": [
{ "id": "2062", "model": "bytedance/seedance-v2-5-flash", "title": "Seedance v2.5 Flash Video Generator", "access": "allow" }
],
"createdat": 1795180800,
"updatedat": 1795180800,
"updatedby": { "useruuid": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "label": "the organization owner" }
},
{
"guid": "a4308936-5441-4012-96ee-f2b32ad3fd40",
"scope": "project",
"target": "48211",
"targetlabel": "Production",
"access": "block",
"categories": [
{ "category": "image", "label": "Image Generation", "access": "allow" }
],
"models": [],
"createdat": 1795184400,
"updatedat": 1795188000,
"updatedby": { "useruuid": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "label": "John Doe" }
},
{
"guid": "9f12fb7e-16f0-4208-83b6-c333b83192d7",
"scope": "surface",
"target": "mcp",
"targetlabel": "MCP",
"access": "allow",
"categories": [
{ "category": "video", "label": "Video Generation", "access": "block" }
],
"models": [],
"createdat": 1795191600,
"updatedat": 1795191600,
"updatedby": { "useruuid": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "label": "John Doe" }
}
],
"categories": [
{ "category": "image", "label": "Image Generation", "values": ["text-to-image", "image-to-image", "image-editing", "image-to-text"] },
{ "category": "video", "label": "Video Generation", "values": ["text-to-video", "image-to-video", "video-to-video", "speech-to-video", "talking-head", "video-to-text", "reference-to-video", "audio-to-video", "lip-sync"] },
{ "category": "audio", "label": "Audio & Speech", "values": ["text-to-speech", "speech-to-text", "speech-to-speech", "video-to-music", "voice-clone", "text-to-audio", "image-to-audio", "realtime-conversation", "realtime-tts", "realtime-stt"] },
{ "category": "music", "label": "Music Generation", "values": ["music-generation", "text-to-song", "text-to-music", "image-to-song", "image-to-music"] },
{ "category": "3d", "label": "3D Generation", "values": ["3d-generation", "text-to-3d", "image-to-3d"] },
{ "category": "llm", "label": "LLM & Chat", "values": ["chat", "llm", "partner-llm", "rag", "llm-reasoning"] },
{ "category": "utilities", "label": "Utilities", "values": ["utils"] }
]
}
| Field | Description |
|---|---|
workspace.type |
team or personal |
workspace.teamguid |
The team's guid, or null for a personal account |
workspace.canmanage |
Whether the caller can change rules in this workspace: true for a personal account's owner, a team admin and the organization owner, also with the API key of a project they created; false for other team members and their keys |
caller.surface |
The surface this call counts on, such as api for a call with an API key (see Surfaces) |
caller.projectid |
The project id of the API key the call used, or null without a key |
rules[].guid |
The rule's guid, for /ModelAccess/Remove |
rules[].scope |
account, member, project, surface or agent |
rules[].target |
The member's useruuid, the project id, the surface or the agent's guid; "" for account |
rules[].targetlabel |
The member's name, the project's name, the agent's title or the surface's label; null for account |
rules[].access |
Everything Else: allow or block |
rules[].categories |
The categories the rule names, each with its label and access, in the order of categories below |
rules[].models |
The models the rule names, in id order: id (a string), model (owner/slug), title and access. model and title are null for a model that is no longer on Wiro |
rules[].createdat, rules[].updatedat |
When the rule was added and last changed, in Unix seconds |
rules[].updatedby |
Who changed the rule last: useruuid and label, the person's name, or their email when they have no name. In a team, the owner of its organization who is not a member of the team is labeled the organization owner, and someone who has left the team has a null label. A change made with an API key names the person who created the key's project. updatedby is null when Wiro changed the rule last, as for the team allowlists and blocklists moved into this system |
categories |
The seven categories a rule can name: category (the key a rule uses), label and values (the catalog categories it covers) |
POST /ModelAccess/Set
Adds a rule to the call's workspace, or replaces the rule with the same scope and target. The rule you send replaces the old one as a whole, so a category or model you leave out is no longer named. Only the people who can change rules can call it (see Who Can Change Rules), in the dashboard, with a Bearer token or with an API key. To check a change first, send the same body to /ModelAccess/Preview.
| Parameter | Type | Required | Description |
|---|---|---|---|
scope |
string | Yes | "account", "member", "project", "surface" or "agent". See What a Rule Covers |
target |
string | For every scope but account |
The member's useruuid, the project's id, the surface (web, api, mcp, llm-gateway, extension or agent) or the agent's guid. Leave it out for account |
access |
string | No | Everything Else: "allow" or "block". Default: "allow" |
categories |
array or object | No | The categories the rule allows or blocks, as [{ "category": "video", "access": "block" }] or as { "video": "block" }. A category is image, video, audio, music, 3d, llm or utilities |
models |
array or object | No | The single models the rule allows or blocks, as [{ "model": "openai/gpt-6-2-astra", "access": "block" }] or as { "openai/gpt-6-2-astra": "block" }. Name a model by its owner/slug or its id. At most 500 models |
Examples
Block video models for the whole account, except one:
{
"scope": "account",
"access": "allow",
"categories": [
{ "category": "video", "access": "block" }
],
"models": [
{ "model": "bytedance/seedance-v2-5-flash", "access": "allow" }
]
}
Let one API key run only image models:
{
"scope": "project",
"target": "48211",
"access": "block",
"categories": [
{ "category": "image", "access": "allow" }
]
}
Keep video models out of MCP:
{
"scope": "surface",
"target": "mcp",
"categories": { "video": "block" }
}
Block one model for one agent:
{
"scope": "agent",
"target": "6e4bbd6f-6b73-4421-adae-e9599ba2e317",
"models": { "openai/gpt-6-2-astra": "block" }
}
Response
rule is the rule as saved, shaped like a row of /ModelAccess/List:
{
"result": true,
"errors": [],
"rule": {
"guid": "a4308936-5441-4012-96ee-f2b32ad3fd40",
"scope": "project",
"target": "48211",
"targetlabel": "Production",
"access": "block",
"categories": [
{ "category": "image", "label": "Image Generation", "access": "allow" }
],
"models": [],
"createdat": 1795184400,
"updatedat": 1795188000,
"updatedby": { "useruuid": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "label": "John Doe" }
}
}
Errors
| Error | Cause |
|---|---|
scope must be one of account, member, project, surface, agent. |
scope is missing or not one of the five scopes |
Member rules exist only in a team workspace. |
A member rule in a personal account |
target is required for this scope. |
No target for a member, project, surface or agent rule |
A surface is one of web, api, mcp, llm-gateway, extension, agent. |
A surface rule with another target |
target must be a project id. |
A project rule whose target is not a project id |
access must be allow or block. |
Another access |
categories must be a list of { category, access }. |
categories is neither a list nor an object |
A category is one of image, video, audio, music, 3d, llm, utilities. |
A category that is not one of the seven |
A category's access must be allow or block. |
A category with another access |
models must be a list of { model, access }. |
models is neither a list nor an object |
A rule can name at most 500 models. |
More than 500 models |
Each model needs its owner/slug or id. |
A model entry with no model |
A model's access must be allow or block. |
A model with another access |
<model> is not a model's owner/slug or id. |
A model named neither by owner/slug nor by a number |
<model> is not a model on Wiro. |
No model listed on Wiro has that owner/slug or id |
<model> is named twice. |
models names a model twice: by the same name, or by its id and its owner/slug with a different access |
You are not a member of this team. |
With a Bearer token, x-team-guid names a team you are not a member of, and whose organization you don't own |
Only a team admin or the organization owner can change this rule. |
In a team, a signed-in caller is not a team admin or the organization owner |
This API key acts as the person who created it, who is a member of this team. Only a team admin or the organization owner can change this rule. |
With an API key, the person who created the key's project is a team member who is not an admin |
That person is not an active member of this team. |
A member rule for someone who is not an active member of the team |
That API key's project is not in this workspace. |
A project rule for a project of another workspace |
That agent is not in this workspace. |
An agent rule for an agent of another workspace |
Too many changes to Spend Limits and Model Access in the last hour. Try again later. |
With API keys, this workspace's spend limits and Model Access rules have been changed 60 times in the last hour |
POST /ModelAccess/Preview
Shows what /ModelAccess/Set would do, and changes nothing. It takes the same body as /ModelAccess/Set and checks it the same way, so only the people who can change rules can call it. Use it to see which workspace a change lands in, the rule as it would be saved and the rule it would replace. For an agent rule, it also says whether the rule would block the chat model the agent answers with.
Example
Let the Support Agent run only image models:
{
"scope": "agent",
"target": "6e4bbd6f-6b73-4421-adae-e9599ba2e317",
"access": "block",
"categories": [
{ "category": "image", "access": "allow" }
]
}
Response
{
"result": true,
"errors": [],
"preview": true,
"workspace": {
"type": "team",
"teamguid": "0d9aade4-d31b-4b97-88f3-a90482f080ea",
"canmanage": true
},
"rule": {
"guid": "c2f0a9d4-5b7e-4c1a-8e36-9d4b2a7f1e05",
"scope": "agent",
"target": "6e4bbd6f-6b73-4421-adae-e9599ba2e317",
"targetlabel": "Support Agent",
"access": "block",
"categories": [
{ "category": "image", "label": "Image Generation", "access": "allow" }
],
"models": [],
"createdat": 1795195200,
"updatedat": null,
"updatedby": null
},
"existing": {
"guid": "c2f0a9d4-5b7e-4c1a-8e36-9d4b2a7f1e05",
"scope": "agent",
"target": "6e4bbd6f-6b73-4421-adae-e9599ba2e317",
"targetlabel": "Support Agent",
"access": "allow",
"categories": [
{ "category": "video", "label": "Video Generation", "access": "block" }
],
"models": [],
"createdat": 1795195200,
"updatedat": 1795195200,
"updatedby": { "useruuid": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "label": "John Doe" }
},
"agentchatmodel": {
"ref": "openai/gpt-5.6-sol",
"model": "openai/gpt-5-6-sol",
"blocked": true
}
}
| Field | Description |
|---|---|
preview |
Always true: nothing was changed |
workspace |
The workspace the change would be made in, as in /ModelAccess/List: type, teamguid and canmanage, which is always true here |
rule |
The rule as /ModelAccess/Set would save it, shaped like a row of /ModelAccess/List. Its guid and createdat are those of the rule it would replace, or null for a new rule, and its updatedat and updatedby are null |
existing |
The current rule with the same scope and target, which the change would replace, or null when there is none |
agentchatmodel |
For an agent rule only: the chat model the agent answers with, as its settings name it (ref) and by its owner/slug on Wiro (model), and whether the rule would block it (blocked) |
When agentchatmodel.blocked is true, the agent stops answering within about a minute of the rule being saved: its turns end with [MODEL_NOT_ALLOWED]. Allow its chat model in the rule too, or allow LLM & Chat. The errors are those of /ModelAccess/Set, except that Preview does not count toward the hourly cap on changes made with API keys.
POST /ModelAccess/Remove
Removes a rule from the call's workspace. The people who can change rules can remove one, in the dashboard, with a Bearer token or with an API key.
| Parameter | Type | Required | Description |
|---|---|---|---|
guid |
string | Yes | The rule's guid from /ModelAccess/List |
Response
{
"result": true,
"errors": []
}
| Error | Cause |
|---|---|
guid is required. |
No guid was sent |
Rule not found in this workspace. |
The guid is not a rule of the call's workspace, or it was already removed |
You are not a member of this team. |
With a Bearer token, x-team-guid names a team you are not a member of, and whose organization you don't own |
Only a team admin or the organization owner can change this rule. |
In a team, a signed-in caller is not a team admin or the organization owner |
This API key acts as the person who created it, who is a member of this team. Only a team admin or the organization owner can change this rule. |
With an API key, the person who created the key's project is a team member who is not an admin |
Too many changes to Spend Limits and Model Access in the last hour. Try again later. |
With API keys, this workspace's spend limits and Model Access rules have been changed 60 times in the last hour |
POST /ModelAccess/Check
Shows how the rules of the call's workspace decide one model for one run: which rules apply, what each one decides and why, and the refusal the run would get. Nothing runs. A team project's API key reads its team, a personal project's key your personal account, and the dashboard the workspace you have selected. Any team member can call it, and it works with an API key. With only model, it checks a dashboard run of yours. To check another run, name it with member, project, agent or surface. check.context in the response says which run was checked.
| Parameter | Type | Required | Description |
|---|---|---|---|
model |
string | Yes | The model's owner/slug or id |
member |
string | No | In a team, the useruuid of the member whose dashboard run to check. Default: you (with an API key, the person who created its project). With project or agent, the run is checked as the person who created that API key, and member is not used |
project |
string | No | A project's id, to check a run made with that project's API key, as the person who created the project. The surface is then api unless you name another one, and web is refused: a run made with an API key never counts as the dashboard |
surface |
string | No | Where the run comes from: web, api, mcp, llm-gateway, extension or agent. Default: web, a dashboard run. With project the default is api, and with agent the surface is always agent. The agent surface needs an agent: send its guid in agent |
agent |
string | No | An agent's guid, to check a model run that agent makes: with the API key it runs models with, as the person who created that key, on the agent surface. project is not used then |
Example
Can the Production API key run openai/gpt-6-2-astra?
{
"model": "openai/gpt-6-2-astra",
"project": "48211",
"surface": "api"
}
Response
Each applicable rule comes back shaped like a row of /ModelAccess/List, with what it decides. This workspace is a team, so check.context shows the key's run checked as Jane Doe, who created the Production project:
{
"result": true,
"errors": [],
"check": {
"model": "openai/gpt-6-2-astra",
"categories": ["llm"],
"allowed": false,
"message": "This API key can only use selected models, and openai/gpt-6-2-astra is not one of them. Model Access rules decide which models can run.",
"rules": [
{
"rule": {
"guid": "a642eda4-68ef-4fa9-af15-7024f28b0332",
"scope": "account",
"target": "",
"targetlabel": null,
"access": "allow",
"categories": [
{ "category": "video", "label": "Video Generation", "access": "block" }
],
"models": [
{ "id": "2062", "model": "bytedance/seedance-v2-5-flash", "title": "Seedance v2.5 Flash Video Generator", "access": "allow" }
],
"createdat": 1795180800,
"updatedat": 1795180800,
"updatedby": { "useruuid": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "label": "the organization owner" }
},
"access": "allow",
"by": "default",
"category": null
},
{
"rule": {
"guid": "a4308936-5441-4012-96ee-f2b32ad3fd40",
"scope": "project",
"target": "48211",
"targetlabel": "Production",
"access": "block",
"categories": [
{ "category": "image", "label": "Image Generation", "access": "allow" }
],
"models": [],
"createdat": 1795184400,
"updatedat": 1795188000,
"updatedby": { "useruuid": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "label": "John Doe" }
},
"access": "block",
"by": "default",
"category": null
}
],
"context": {
"surface": "api",
"member": { "useruuid": "3f5a9c20-6d41-4b8e-a1c7-5e9d0f2b4c61", "label": "Jane Doe" },
"project": { "projectid": "48211", "label": "Production" },
"agent": null
}
}
}
| Field | Description |
|---|---|
check.model |
The model as owner/slug |
check.categories |
The categories the model is in, such as ["llm"]. Empty when it is in none |
check.allowed |
Whether every rule that applies allows the model |
check.message |
The refusal a run would get with code 92, or null when the model is allowed |
check.rules |
The rules that apply, in the order account, member, API key, surface, agent. Empty when none applies |
check.rules[].rule |
The rule, shaped like a row of /ModelAccess/List |
check.rules[].access |
What this rule decides: allow or block |
check.rules[].by |
What decided it: model (the model's own entry), category (one of its categories) or default (Everything Else) |
check.rules[].category |
The category that decided it when by is category, else null |
check.context |
Which run was checked: surface, member, project and agent |
check.context.surface |
The surface the run was checked on: the surface you sent, else api with project and web without it. Always agent with agent |
check.context.member |
In a team, the member the run was checked as: useruuid, and the member's name as label. That is the member you sent, else you, and with project or agent the person who created that API key. null in a personal account |
check.context.project |
The project whose API key the run was checked with: projectid, and the project's name as label. That is the project you sent, or for an agent the Wiro project it runs models with. null without project or agent |
check.context.agent |
The agent whose run was checked: useragentguid, and the agent's title as label. null without agent |
| Error | Cause |
|---|---|
model is required. |
No model was sent |
<model> is not a model's owner/slug or id. |
model is neither an owner/slug nor a number |
<model> is not a model on Wiro. |
No model listed on Wiro has that owner/slug or id |
A surface is one of web, api, mcp, llm-gateway, extension, agent. |
Another surface |
Name the agent to check its runs. |
surface is agent and no agent was sent |
That API key's project is not in this workspace. |
project is not the id of a project of this workspace |
A run made with an API key never counts as the dashboard. Leave surface out or pick another one. |
project with surface web |
That agent is not in this workspace. |
agent is not the guid of an agent of this workspace |
That agent has no API key to run models with yet. |
The agent has no Wiro project to run models with yet: connect one with /UserAgent/CredentialProjectBind |
That agent runs models with an API key of another workspace, so that workspace's rules decide them. |
The Wiro project the agent runs models with is in another workspace |
Error Reference
Understand API error responses, error codes, and how to handle them.
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.
| Code | Category | Description |
|---|---|---|
0 |
General | Server-side errors, validation failures, missing parameters |
1 |
Not Found / Client | Resource not found or not accessible |
92 |
Model Access | A Model Access rule of the workspace blocks the model. See Model Access |
93 |
Spend Limit | A spend limit of the workspace is reached. See Spend Limits |
96 |
Concurrency Limit | Too many concurrent tasks for your balance. See Concurrency Limits |
97 |
Insufficient Balance | Not enough funds to run the model |
98 |
Authentication Required | Sign in required to access this model |
99 |
Token Invalid | Bearer token missing, invalid, or expired |
Authentication Errors
Returned when API key or bearer token authentication fails. All return HTTP 401.
| Error | Code | Message |
|---|---|---|
| API key not found | 0 |
Project authorization is not founded. |
| Signature required | 0 |
Project requires signature authentication. x-signature and x-nonce headers are required. |
| Invalid signature | 0 |
Project authorization is not valid. |
| IP not allowed | 0 |
Requested ip {ip} is not allowed. |
| Key creator left the team | 0 |
The person who created this API key is no longer in its team. Ask a team admin for a new key. |
| Team change with an API key | 0 |
API keys can't manage teams or organizations. Sign in and try again. |
| Bearer token missing | 99 |
Authorization bearer token is not founded in headers. |
| Bearer token invalid | 99 |
Authorization bearer token is invalid. |
| Bearer token expired | 99 |
Authorization bearer token expired. |
| Endpoint not found | 0 |
Parsing url error. (HTTP 404) |
Signature Auth Errors
If your project uses signature-based authentication, ensure all three headers are present and the signature is computed correctly:
x-api-key: YOUR_API_KEY
x-signature: HMAC-SHA256(key=API_KEY, message=API_SECRET + NONCE)
x-nonce: Unix timestamp or random integer
See Authentication for details.
IP Whitelist Errors
If your project has an IP whitelist configured, requests from unlisted IPs will be rejected. Use * in the whitelist to allow all IPs.
Team API Key Errors
A team project's API key works only while the user who created the project is an active member of the team or the organization owner. Once they leave the team, requests with the key fail with "The person who created this API key is no longer in its team." Public endpoints such as Tool/List and Agent/List still answer, as if the request had no key. Switch to a key from a project that an active member created.
Creating, changing, deleting or restoring organizations and teams, managing members and invitations, and moving projects, agents or credit need a signed-in user, in the dashboard or with a Bearer token. With an API key, these calls fail with "API keys can't manage teams or organizations." See Team API Access.
Studio and the Workflow Agent are stricter: the user who created the key's project must be an active member of the team, and being the organization owner is not enough. When that user is the organization owner but not a member of the team, requests to them fail with HTTP 403:
| Error | Code | Message |
|---|---|---|
| Not a team member | 0 |
You must be a member of this team to perform this action |
Run Errors
Returned by POST /Run/{owner}/{model}.
Balance & Limits
| Error | Code | Message | Action |
|---|---|---|---|
| Insufficient balance | 97 |
Insufficient balance | Add funds: minimum $0.50 required ($10 for training) |
| Model blocked | 92 |
This API key can only use selected models, and openai/gpt-6-2-astra is not one of them. Model Access rules decide which models can run. | Run a model the rules allow, or ask someone who manages the rule to change it under Controls > Model Access. The message names the rule. See Model Access |
| Spend limit reached | 93 |
This API key's monthly spend limit is reached ($50.20 of $50.00). It resets on December 1, 2026 at 00:00 UTC. | Wait for the limit to reset, or have someone who manages it raise it under Controls > Spend Limits. The message names the limit. See Spend Limits |
| Concurrent task limit | 96 |
You have reached your concurrent task limit. With your current balance of ${balance}, you can run up to {maxConcurrent} tasks at the same time. Add funds to increase your limit. | Wait for a task to finish, or add funds. See Concurrency Limits |
| Sign in required | 98 |
sign in to run this model | Model requires a registered account |
Validation Errors
| Error | Code | Message |
|---|---|---|
| Missing parameter | 0 |
Request parameter [{name}] required |
| Invalid number | 0 |
Request parameter [{name}] must be integer or float |
| Out of range | 0 |
Request parameter [{name}] must be between {min} and {max} |
| File required | 0 |
Request files [{name}] required |
| Invalid request body | 0 |
Request parameters are invalid. |
Model Access Errors
| Error | Code | Message |
|---|---|---|
| Model not accessible | 1 |
tool-not-accessible |
| Model not found | 1 |
slug-owner-project-not-exist |
| Account suspended | 0 |
Your account has been suspended. Please contact support if you believe this is a mistake. |
| Permission denied | 0 |
You don't have any permission for this action. |
| Model blocked by a Model Access rule | 92 |
This API key can't use openai/gpt-6-2-astra. Model Access rules decide which models can run. |
Training Model Errors
| Error | Code | Message |
|---|---|---|
| Invalid model name | 0 |
Your model name should be contain (A-Z) (0-9) (-) (_) (.) |
| Reserved name | 0 |
This name is not allowed |
| Name taken | 0 |
This model name is already in use |
Task Errors
Returned by POST /Task/Detail, POST /Task/Cancel, POST /Task/Kill, and POST /Task/InputOutputDelete.
| Error | Code | Message | Endpoint |
|---|---|---|---|
| Task not found | 0 |
task-not-founded | Detail |
| Task not found | 1 |
There is no task yet. | Cancel |
| Task not found | 0 |
There is no task yet. | Kill, InputOutputDelete |
| Missing identifier | 0 |
Request parameter [taskid or tasktoken] required | Detail |
| Missing identifier | 0 |
taskid or socketaccesstoken is required | Kill |
| Not cancellable | 1 |
Task is not in a cancellable state. | Cancel |
| Kill failed | 1 |
Task could not be killed: {reason} | Kill |
| Task not completed | 0 |
Task must be completed or cancelled before deleting files | InputOutputDelete |
| Permission denied | 0 |
You don't have any permission for this action. | Detail, Cancel |
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 92:
console.log('Model blocked by a Model Access rule: run a model the rules allow');
break;
case 93:
console.log('Spend limit reached: wait for the reset or raise the limit');
break;
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
| Code | Retryable | Strategy |
|---|---|---|
0 (validation) |
No | Fix the request parameters |
0 (server) |
Yes | Retry with exponential backoff |
1 |
No | Check model slug or task token |
92 |
No | Run a model the rules allow, or ask someone who manages the rule to change it |
93 |
No | Wait until the limit resets or someone who manages it raises it |
96 |
Yes | Wait for a running task to complete |
97 |
No | Add funds, then retry |
98 |
No | Sign in or use authenticated credentials |
99 |
No | Check your API key or bearer token |
FAQ
Common questions about using the Wiro API. If you can't find the answer here, contact support.
Sign up at wiro.ai, then create a project at wiro.ai/panel/project. Copy your API key (and secret, if signature-based) and store them securely. You can see them again on the Projects page after you confirm it's you.
Signature-Based is recommended. It uses HMAC-SHA256 so your API secret never leaves your environment. API Key Only is simpler and fine for server-side applications where you control the environment. Use either method only from your own server, never in browser or mobile app code. See Authentication for details.
Yes. Every account has a concurrency limit that controls how many tasks can run at the same time. The limit scales automatically based on your account balance. See Concurrency Limits for the full table.
No. If a task fails (non-zero pexit), you are not charged. Only successfully completed tasks are billed.
Use the POST /Tool/Detail endpoint. The response includes the model's pricing information. If you're using the MCP server, the search_models and get_model_schema tools also return pricing.
Output files are stored on Wiro's CDN and available for a limited time. Download and store any files you need to keep long-term. See Files for details on file management.
Yes. Output URLs returned by Wiro are publicly accessible. Anyone with the URL can access the file. If you need private storage, download the files to your own infrastructure.
Your account is closed right away and its API keys stop working. Its subscriptions stop renewing and end with their current billing period, without a refund. A renewal invoice that is still unpaid is cancelled. Its automatic top-ups stop. 30 days later, or later if something still needs it, such as an active subscription, we permanently delete its data, including your files, tasks, projects and API keys. Until then, write to [email protected] if you want it restored. We keep records the law requires, such as payment and invoice records. See Data Deletion for details.
Connect to the WebSocket at wss://socket.wiro.ai/v1 and register with the socketaccesstoken from your run response. You'll receive events as the task progresses. For simpler integrations, you can poll the Task Detail endpoint.
LLM models return their response in two places: as merged text in debugoutput, and as a structured entry in the outputs array with contenttype: "raw" containing prompt, raw, and separate thinking and answer arrays. For streaming, each task_output WebSocket event carries the latest cumulative snapshot of the output. See LLM & Chat Streaming for details.
Yes. For fileinput parameters, use the {id}Url suffix (e.g., inputImageUrl). For multifileinput, send comma-separated URLs in the field that puts Url before Multiple (e.g., inputDocumentUrlMultiple). For combinefileinput, pass URLs directly in the original parameter. A fileinput or multifileinput with no URL field takes them in the parameter itself. The URL must be a public http(s) address. See Model Parameters.
pexit is the process exit code: "0" means success, any other value means failure. It's the most reliable way to determine if a task succeeded. Always check pexit in the task_postprocess_end event or Task Detail response. See Tasks.
No. The Wiro MCP server is free. You pay the normal prices for the work its tools start: model runs, the model steps of workflow runs, Studio and Workflow Agent turns, and agent plans and credits.
Yes. Install the Wiro AI community node (@wiro-ai/n8n-nodes-wiro) in your n8n instance to run any Wiro model from your workflows. Pick the model in the node and its inputs load with their defaults. The node is verified by n8n, so an instance owner can also install it from the nodes panel, on n8n Cloud too.
Wiro AI has open-source add-ons for these apps. Each repository has the install steps:
- ComfyUI: nodes that run image, video, audio, 3D and LLM models inside your graphs, also on the Comfy Registry
- Dify: the LLM gateway and voice models as a model provider, plus tools for images, video, speech, music and 3D in workflows and agents
- WordPress: featured images, image edits, alt text, narration and SEO suggestions in the block editor, from the WordPress plugin directory
- Obsidian: images, video, speech, music, transcription and text tools, saved into your notes, from Obsidian community plugins
- Figma: images, SVG vectors, image edits, background removal and text rewriting or translation on the canvas
- Blender: text to 3D, image to 3D and textures, with any model in the catalog
- Raycast: image and video generation, LLM chat and model search from your launcher
- Zed: the Wiro MCP server in Zed's Agent Panel
- GitHub Actions: run models, workflows and LLM prompts from a workflow step
- Hermes Agent: media tools, plus the LLM gateway as a model provider
- Coding agents: agent skills for images, image edits, video, music, speech, transcripts, 3D and model search in Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot and OpenClaw
- Vercel AI SDK: chat, image, speech, transcription and video models, with a Next.js starter for Vercel and Railway
- Chrome, Edge, Opera and Brave, Firefox and Safari: right-click an image, video, audio clip, text or page to run a model. Install it from the Chrome Web Store, Microsoft Edge Add-ons, Firefox Add-ons or the Naver Whale Store
AI assistants such as Claude, ChatGPT, Cursor and VS Code connect through the Wiro MCP server.
Yes. All models support an optional callbackUrl parameter. When provided, Wiro will POST the task result to your URL when the task completes. It must be a public http(s) address. See Webhook Callback in Model Parameters.
Wiro Agents are autonomous AI assistants that you deploy and manage via the API. Unlike single model runs, agents can connect to third-party services (Twitter, Google Ads, HubSpot, etc.), maintain conversation memory across sessions, and run scheduled tasks automatically. See the Agent Overview for details.
Pick a template in the agent catalog or build your own, then call POST /UserAgent/Deploy with useprepaid: true and a plan in tier: starter ($5 a month, 500 credits), pro ($30, 3,000) or max ($100, 10,000). Your wallet pays the plan, and Wiro queues the agent to start on its own. Then connect the services it uses. Every plan includes every skill and connector. See Agent Overview for the full lifecycle.
Each agent runs on one of three monthly plans: Starter ($5 a month with 500 credits), Pro ($30 with 3,000) or Max ($100 with 10,000). Every plan includes every skill and connector, so turning one on or off costs nothing. Each turn the agent runs uses credits by the tokens its model uses, and extra credit packs add 1,000 credits for $10, 5,000 for $50 or 20,000 for $200. A higher plan starts at once; a lower plan starts at the next renewal. See Pricing Model.
Starter gives an agent 250 MB, Pro 500 MB and Max 1 GB for its files: the workspace, generated media and temporary files. Chat history and system files don't count. Downloads and temporary files outside the workspace are cleared when the agent restarts, and when they pass 1 GB. When the disk is full, the agent can't save new files until some are deleted or it moves to a bigger plan. UserAgent/Detail shows the usage in disk. See Disk Space.
Yes. Use the Agent Messaging API to send messages programmatically, receive streaming responses via WebSocket, and get async notifications via webhooks. You can build white-label chat interfaces, webhook-driven pipelines, and multi-agent workflows. See Agent Use Cases. For a chat in your own product, with setup from chat, follow Agent Chat Integration.
Yes. In the Wiro panel, the people who manage an agent can open its Screen beside the chat and watch its computer live (on a team agent, while its Chat Mode is Collaborative). The owner of a personal agent that has never been in a team, or whose browser was reset after it last left one, can also take control and use the keyboard and mouse, for example to sign in to a site for the agent. Products built on the API can show the same Screen, and Take Control, in their own app and decide which of their users see it; the agent's screen setting turns it off for everyone. See Screen and Take Control and Screen and Take Control in Your App.
Agents connect to services like Twitter, Instagram, Google Ads, and HubSpot via OAuth or API keys. Use POST /UserAgentOAuth/OAuthConnect with the provider's credentialkey to initiate OAuth flows, or set API keys via /UserAgent/CredentialUpsert. See Agent Credentials & OAuth. You can also ask the agent in its chat: it proposes a setup card, and an agent admin approves it and gives the key, which the agent never sees. See Setup From Chat.
Code Examples
Complete end-to-end examples in all 9 supported languages.
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
requestslibrary - Node.js: Using
axios - PHP: Using cURL functions
- C#: Using
HttpClient(.NET 6+) - Swift: Using async/await
URLSession - Dart: Using the
httppackage - 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:
- Set up authentication headers
- Run a model (
POST /Run/{owner-slug}/{model-slug}) - Poll the task status (
POST /Task/Detail) - Print the final output
Wiro MCP Server
Connect AI assistants to Wiro's models, workflows, Studio and agents through the Model Context Protocol.
Connect with a browser sign-in
No API key to copy. Add this URL as a remote MCP server in your app, then sign in with your Wiro account when the app asks:
https://mcp.wiro.ai/v1- ChatGPT
- Claude
- Claude Code
- Cursor
- VS Code
- Gemini CLI
- Codex
- Devin
- Kiro
- goose
- Grok
- Add the serverIn your app, add a remote MCP server with the URL above. Leave the
Authorizationheader out. - Sign in to WiroThe app opens wiro.ai in your browser. Sign in, or create an account.
- Pick a project and how longRuns are paid from the project's workspace wallet. The app stays connected for 90 days unless you pick another length, from 7 days to unlimited.
- Click AllowYour browser goes back to the app, and the Wiro tools are ready to use.
Claude, ChatGPT and Devin have no one-click link yet. Open the app's connector settings and paste the URL above:
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 find and run models, build and run workflows, create media with Studio, deploy and talk to your own agents, and check or change your spend limits and Model Access rules, all without leaving your editor or chat app.
The hosted MCP server is available at mcp.wiro.ai/v1. Most apps connect with the browser sign-in above. Clients that send custom request headers, including Cursor, Claude Code, Windsurf, Kiro, goose, OpenClaw, and Hermes, can use your API key instead. An API key sent in a header is never stored on the hosted server.
You need a Wiro account. With a browser sign-in you pick a project while connecting. For the API key method, 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
Browser sign-in details
ChatGPT, Claude (claude.ai, Claude Desktop and Claude Code), Cursor, VS Code, Gemini CLI, Codex, Zed, Devin, Kiro, goose, Grok, Grok Bot, Cline and MCP Inspector connect this way, and so does any app on your computer that follows the MCP authorization spec. An app that signs in through its own website needs its callback address on Wiro's list: write to [email protected] to add one.
Projects and billing
- Each connection uses one project. A personal project bills your personal wallet, a team project the team's wallet.
- In a team, members can connect the projects they created. Team admins and the organization owner can connect any project of the team.
- The connection acts as the person who created the project. Its Controls tools change spend limits and Model Access rules only when that person can: a personal account's owner, or in a team a team admin or the organization owner.
- A project with an IP whitelist only accepts calls from the addresses on it. ChatGPT and Claude call from their own servers, so pick a project open to all addresses for them. Apps on your computer, such as Claude Code, Cursor and VS Code, call from your own address.
How long it stays connected
You pick it on the sign-in page: 7 days, 30 days, 90 days (the default), 180 days, 1 year, or unlimited. When the time is up, the app asks you to sign in again. An unlimited connection lasts until you disconnect it.
A connection also ends when its project is removed, or when you leave the team or lose the role that allowed it. The same happens once the project's API key stops working, for example when the person who created a team project leaves the team; the sign-in page then no longer offers that project. Access tokens last one hour and renew on their own, so there is nothing to copy or rotate.
See, change and disconnect apps
Every app you connected is listed under Projects, Connected Apps in the panel, with its project, when it was last used and when it ends. Pick a new length there to extend or shorten it; it counts from that day. Disconnect ends its access within a minute, and the app asks you to sign in again the next time.
For MCP client developers
| Item | Value |
|---|---|
| Protected resource metadata | https://mcp.wiro.ai/.well-known/oauth-protected-resource/v1 |
| Authorization server metadata | https://mcp.wiro.ai/.well-known/oauth-authorization-server |
| Authorize, token, revoke | https://mcp.wiro.ai/authorize, /token, /revoke |
| Client registration | A Client ID Metadata Document, or dynamic client registration at https://mcp.wiro.ai/register |
| Resource and scope | https://mcp.wiro.ai/v1, scope mcp |
Use the authorization code flow with PKCE (S256). Authorization responses carry iss. Sign-in returns only to the callbacks of known apps and to loopback addresses on your own computer (any port). To add your app's callback, write to [email protected].
Setup
Connect your AI assistant to Wiro's MCP server. Pick your client:
Cursor
Sign in with your browser
Click Add to Cursor, or add the server to your mcp.json with only its URL:
{
"mcpServers": {
"wiro": {
"url": "https://mcp.wiro.ai/v1"
}
}
}
Cursor asks you to sign in to Wiro the first time it connects.
Or use your API key
- Open MCP Settings: Use
Cmd+Shift+P(Ctrl+Shift+Pon Windows) and search for "Open MCP settings". -
Add the Wiro server to your
mcp.jsonfile:Signature Auth (if your project uses signature-based authentication):
{ "mcpServers": { "wiro": { "url": "https://mcp.wiro.ai/v1", "headers": { "Authorization": "Bearer YOUR_API_KEY:YOUR_API_SECRET" } } } }API Key Only Auth (if your project uses API Key Only authentication):
{ "mcpServers": { "wiro": { "url": "https://mcp.wiro.ai/v1", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } - Restart Cursor: Save the file and restart Cursor to activate the connection.
Claude Code
Sign in with your browser
Run this command in your terminal:
claude mcp add --transport http wiro https://mcp.wiro.ai/v1
Then run /mcp inside Claude Code, pick wiro and sign in to Wiro in your browser.
Or install as a plugin
Run these two commands inside Claude Code:
/plugin marketplace add wiroai/Wiro-Plugin
/plugin install wiro-ai@wiro
Then open /mcp, pick the Wiro server and choose Authenticate to sign in to Wiro in your browser. The plugin comes from the wiroai/Wiro-Plugin repository.
The plugin also adds slash commands, such as /wiro-ai:image, /wiro-ai:video and /wiro-ai:speech, and five agent skills. Each command picks a model from the catalog, shows the price and waits for your yes before a paid run and can save the results into your project.
Or add the server with your API key
Run this command in your terminal:
claude mcp add --transport http wiro \
https://mcp.wiro.ai/v1 \
--header "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET"
For an API Key Only project, use Bearer YOUR_API_KEY without the colon or secret. Verify the connection with claude mcp get wiro, or run /mcp inside Claude Code.
Claude Desktop
The quickest way is a custom connector: open Connectors in Claude, click Add custom connector, enter the URL https://mcp.wiro.ai/v1 and sign in with your Wiro account when Claude asks. See Connect with a browser sign-in. The same connector works on claude.ai.
You can also run the official local package. It provides the same Wiro tools through Claude Desktop's stdio MCP support.
Install Node.js 20 or later, then add the following to your claude_desktop_config.json:
{
"mcpServers": {
"wiro": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@wiro-ai/wiro-mcp@latest"],
"env": {
"WIRO_API_KEY": "YOUR_API_KEY",
"WIRO_API_SECRET": "YOUR_API_SECRET"
}
}
}
}
For API Key Only authentication, keep WIRO_API_KEY and remove the WIRO_API_SECRET entry completely. Save the file, fully quit Claude Desktop, and reopen it.
Keep @latest in args: npx then looks up the newest version on npm each time the client starts the server. Without it, npx can keep running an older cached build after a package update.
This setup runs the open-source @wiro-ai/wiro-mcp bridge on your machine and calls Wiro with your project credentials. See Self-Hosted MCP for the complete local package guide.
Claude connection and timeout troubleshooting
- "Not valid MCP server configurations": ensure the entry contains
"type": "stdio",command,args, andenvexactly as shown above. - The Wiro tools do not appear: confirm
node --versionreports 20 or later, then fully quit and reopen Claude Desktop. - Tools appear but every call fails immediately: use
@wiro-ai/wiro-mcp@latestas shown above sonpxdoes not reuse an older cached package, then fully quit and reopen Claude Desktop. - A generation reaches Claude's tool timeout: Wiro waits for at most 45 seconds per call. If the task is still running, Claude should execute the returned
nextAction.tool: "wait_for_task"until completion and must not callrun_modelagain. - Do not add a
timeoutfield toclaude_desktop_config.json; Claude Desktop versions with a fixed client-side tool timeout may ignore it. Wiro's bounded wait flow is designed to remain below that boundary.
ChatGPT
In ChatGPT, open Plugins, click +, choose Add custom MCP server, enter https://mcp.wiro.ai/v1 and create the plugin. ChatGPT opens wiro.ai, where you sign in and pick a project.
ChatGPT calls Wiro from its own servers, so pick a project that is open to all IP addresses.
VS Code
Click Install in VS Code, or add the server to your mcp.json:
{
"servers": {
"wiro": {
"type": "http",
"url": "https://mcp.wiro.ai/v1"
}
}
}
VS Code asks you to sign in to Wiro when it starts the server. From a terminal, code --add-mcp '{"name":"wiro","type":"http","url":"https://mcp.wiro.ai/v1"}' adds the same entry.
Gemini CLI
Sign in with your browser
Run this command in your terminal:
gemini mcp add --transport http wiro https://mcp.wiro.ai/v1
Then run /mcp auth wiro inside Gemini CLI and sign in to Wiro in your browser.
Or install the extension
Install Wiro as a Gemini CLI extension from the wiroai/Wiro-Plugin repository. Run this in your terminal:
gemini extensions install https://github.com/wiroai/Wiro-Plugin
Then run /mcp auth wiro inside Gemini CLI and sign in to Wiro in your browser.
The extension also adds slash commands such as /wiro:image and /wiro:video, and five agent skills.
Codex
Sign in with your browser
Run this command in your terminal:
codex mcp add wiro --url https://mcp.wiro.ai/v1
Codex adds the server and opens the Wiro sign-in page in your browser. To sign in again later, run codex mcp login wiro.
Or install as a plugin
Run these two commands in your terminal:
codex plugin marketplace add wiroai/Wiro-Plugin
codex plugin add wiro-ai@wiro
Then run codex mcp login wiro to sign in to Wiro in your browser. The plugin comes from the wiroai/Wiro-Plugin repository.
The plugin also adds commands you call with $, such as $wiro-ai:image, $wiro-ai:video and $wiro-ai:speech, and five agent skills. Each command picks a model from the catalog, shows the price and waits for your yes before a paid run and can save the results into your project.
Or add the server with your API key
Keep the key in an environment variable and point Codex at it:
export WIRO_API_KEY="YOUR_API_KEY:YOUR_API_SECRET"
codex mcp add wiro --url https://mcp.wiro.ai/v1 --bearer-token-env-var WIRO_API_KEY
Codex sends the variable as Authorization: Bearer, so keep it in your shell profile. For an API Key Only project, set it to YOUR_API_KEY without the colon or secret. Verify the connection with codex mcp list.
Devin
Install Wiro as a Devin plugin from the wiroai/Wiro-Plugin repository. With the Devin CLI, run:
devin plugins install wiroai/Wiro-Plugin
In the Devin web app, go to Customize > Plugins > Add plugin > From repository and enter wiroai/Wiro-Plugin. Devin opens Wiro's sign-in page in your browser the first time it connects.
The plugin also adds commands you call by name, such as /wiro-ai:image and /wiro-ai:video, plus five agent skills.
In the Devin web app you can also skip the plugin: open Customize, MCPs, add a custom MCP server with the URL https://mcp.wiro.ai/v1 and sign in to Wiro in your browser.
Kiro
Sign in with your browser
Click Add to Kiro, or add the server with only its URL to ~/.kiro/settings/mcp.json (every workspace) or .kiro/settings/mcp.json (this workspace):
{
"mcpServers": {
"wiro": {
"url": "https://mcp.wiro.ai/v1"
}
}
}
Kiro opens Wiro's sign-in page in your browser the first time it connects.
Or use your API key
Send the key in an Authorization header instead:
{
"mcpServers": {
"wiro": {
"url": "https://mcp.wiro.ai/v1",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
Use YOUR_API_KEY:YOUR_API_SECRET (both values joined with a colon) if the project uses signature-based auth.
goose
Sign in with your browser
Click Add to goose. To add it by hand in goose Desktop, open Extensions > Add custom extension, choose the Streamable HTTP type and enter https://mcp.wiro.ai/v1. In the goose CLI, run goose configure, pick Add Extension > Remote Extension (Streamable HTTP) and enter the same URL.
goose opens Wiro's sign-in page in your browser the first time it connects.
Or use your API key
Add Wiro to ~/.config/goose/config.yaml with an Authorization header:
extensions:
wiro:
name: Wiro AI
type: streamable_http
uri: https://mcp.wiro.ai/v1
headers:
Authorization: Bearer YOUR_API_KEY
enabled: true
timeout: 300
Use YOUR_API_KEY:YOUR_API_SECRET (both values joined with a colon) if the project uses signature-based auth.
Grok
On grok.com
Open grok.com/connectors, click New Connector, choose Custom and enter https://mcp.wiro.ai/v1. Grok opens Wiro's sign-in page in your browser: sign in, pick the project whose wallet pays for runs and click Allow.
In Grok Bot
Ask your Bot to add the MCP server https://mcp.wiro.ai/v1. Grok Bot opens Wiro's sign-in page in your browser the first time it connects.
Windsurf
Open Settings → MCP and add a new server:
{
"mcpServers": {
"wiro": {
"serverUrl": "https://mcp.wiro.ai/v1",
"headers": {
"Authorization": "Bearer YOUR_API_KEY:YOUR_API_SECRET"
}
}
}
}
OpenClaw
Set WIRO_MCP_AUTH in the environment that starts OpenClaw. Use YOUR_API_KEY:YOUR_API_SECRET for signature auth or only YOUR_API_KEY for API Key Only auth. Then add this server under mcp.servers in your OpenClaw config:
{
"mcp": {
"servers": {
"wiro": {
"url": "https://mcp.wiro.ai/v1",
"transport": "streamable-http",
"connectionTimeoutMs": 10000,
"headers": {
"Authorization": "Bearer ${WIRO_MCP_AUTH}"
}
}
}
}
}
Verify the saved definition, the connection and the advertised tools:
openclaw mcp doctor wiro --probe
On older OpenClaw releases without that command, use openclaw mcp show wiro, restart OpenClaw, and run /tools verbose.
Wiro's default bounded wait is 45 seconds; if your client has a configurable tool-call timeout, keep it above that value.
Hermes
Add WIRO_MCP_AUTH=YOUR_API_KEY:YOUR_API_SECRET to ~/.hermes/.env, then add this to ~/.hermes/config.yaml:
mcp_servers:
wiro:
url: "https://mcp.wiro.ai/v1"
headers:
Authorization: "Bearer ${WIRO_MCP_AUTH}"
timeout: 60
connect_timeout: 10
Use only the API key in WIRO_MCP_AUTH for API Key Only auth. Run /reload-mcp and then /tools inside Hermes.
Other MCP Clients
The Wiro MCP server uses the Streamable HTTP transport at:
https://mcp.wiro.ai/v1
A client that supports MCP sign-in needs only this URL: it opens a Wiro sign-in in your browser (see Connect with a browser sign-in). Any other client sends your API key in the Authorization header:
Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET
Or for API Key Only auth: Bearer YOUR_API_KEY
Credentials are sent as plain text. No base64 encoding is needed. Clients must support Streamable HTTP, and for the header method a custom Authorization header.
Authentication
Apps that support MCP sign-in need no credentials here: see Connect with a browser sign-in. With an API key in the header, 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.
Authentication errors
A failed tool call comes back as a normal tool result with isError: true. Its text starts with Wiro API error and the HTTP status, then a message that says what to fix. For example, when a project uses signature-based auth and only its API key was sent:
{
"isError": true,
"content": [{
"type": "text",
"text": "## Error\n\nWiro API error 401: This project uses signature-based auth. Enter API_KEY:API_SECRET (the key and secret joined with a colon) as the API key."
}]
}
Messages you may see while connecting:
| Message | What to do |
|---|---|
This project uses signature-based auth. Enter API_KEY:API_SECRET (the key and secret joined with a colon) as the API key. |
Only the API key was sent, but the project uses signature-based auth. Enter API_KEY:API_SECRET in the plugin's key field, or send Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET. |
Project authorization is not founded. |
No project has this API key. Copy the key again from your project page. |
Project authorization is not valid. |
The API secret does not match the API key. Check that both come from the same project. |
Requested ip {ip} is not allowed. |
The project has an IP whitelist, and the address in the message is not on it. Check the whitelist in your project settings. |
The person who created this API key is no longer in its team. Ask a team admin for a new key. |
The user who created this team project has left the team, so its key no longer works. Use a key from another project, or sign in again and pick another project. |
A request without an Authorization header never reaches a tool. The MCP endpoint answers HTTP 401 with Missing or invalid Authorization header in the body and a WWW-Authenticate header that points apps to the sign-in. An expired or disconnected sign-in gets the same answer with error="invalid_token", and the app asks you to sign in again. See Error Reference for every Wiro API error.
Available Tools
The MCP server has 54 tools. Most of them belong to one of four groups, Models, Workflows, Agents and Controls, and three tools for your account, the playbooks and the docs are always available. Your AI assistant picks the right tool for each request, and for longer jobs it reads a playbook first.
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.
Models
| Tool | Description |
|---|---|
search_models |
Search and browse AI models by keyword, category, or owner |
get_model_schema |
Get the full parameter schema and pricing for any model, or the parameters and output ports of a workflow utility |
recommend_model |
Find models for a goal from two or three key words, best matches first |
explore |
Browse curated models grouped by category, no parameters needed |
run_model |
Run any model, waiting up to 45 seconds by default before it returns a recoverable task token |
wait_for_task |
Continue waiting for an existing task without submitting or billing a duplicate run |
get_task |
Check task status immediately or wait up to 45 seconds with wait_seconds |
list_tasks |
Browse authenticated task history across conversations, then continue with get_task |
get_task_price |
Get the cost of a completed task |
cancel_task |
Cancel a queued task |
kill_task |
Stop a queued or running task |
upload_file |
Upload a file from a public http(s) URL (up to about 100 MB) for use as model input |
For long generations, run_model returns the existing task ID and token when its wait ends. The assistant continues with wait_for_task; calling run_model again would start a separate billable task.
Workflows
A workflow chains models and built-in utility steps into one graph with its own inputs and outputs. Every model step is charged like a normal model run when it finishes. Wiro fills a model input you leave out with the model's default, so the save result lists what it filled, and a graph can be at most 40 KB of JSON. The API behind these tools is described on the Workflows page.
| Tool | Description |
|---|---|
list_workflows |
List the workflows in your workspace, or search the public gallery by text, tag or model |
get_workflow |
Read a workflow's inputs, outputs and step graph |
create_workflow |
Save a new workflow from a step graph. Wiro checks it against the live model catalog and returns every problem it finds at once |
update_workflow |
Edit a workflow's title, description, tags or graph without overwriting newer changes; a new graph is saved only after you confirm a summary of the change |
clone_workflow |
Copy a public workflow into your workspace |
delete_workflow |
Delete a workflow, after your confirmation |
run_workflow |
Run a workflow and wait for its outputs; can stop after a chosen step to test the first steps |
wait_for_workflow_run |
Keep waiting on a run, read its outputs, or see why a step failed |
resume_workflow_run |
Continue a failed or stopped run without paying again for finished steps |
list_workflow_runs |
Browse past and current runs, including runs started on wiro.ai |
save_workflow_from_agent |
Save a workflow the Workflow Agent proposed, as a new workflow, or onto an existing one after you confirm a summary of the change |
The Workflow Agent designs workflows with you in plain language: talk to it with send_agent_message and agent: "workflow-agent", attach an existing workflow to edit, then save its proposal with save_workflow_from_agent. Conversations started through the MCP server belong to the connected project and are separate from your Workflow Agent chats on wiro.ai. See Workflow Agent.
Agents
One set of tools talks to every Wiro agent. agent is "studio", "workflow-agent" or the guid of one of your own agents. Session names use letters, digits, dots, dashes, underscores and colons, up to 128 characters (100 for the Workflow Agent), and can't end in -r followed by a number, such as -r2. Studio refuses a message under any other name, and nothing is sent. A Studio session that already has another name can still be read and deleted; to go on with it, start a new session.
| Tool | Description |
|---|---|
send_agent_message |
Send a message and wait for the reply, with any media, workflows or model runs it produced |
get_agent_message |
Keep waiting on a reply, or read one again |
get_agent_conversation |
List conversations, or read one conversation's history |
cancel_agent_message |
Stop a reply that is still being written |
delete_agent_session |
Delete a conversation and the agent's memory of it, after your confirmation |
list_studio_results |
List the images, videos and other results Studio generated for you |
Studio is Wiro's creative agent: it picks and runs models for you and charges your wallet after each reply (see Studio). Your own agents run on a monthly plan with credits (see Agent Overview).
| Tool | Description |
|---|---|
list_agent_templates |
Browse ready-made agent templates and the three monthly plans |
get_agent_template |
Read a template's skills, plans, and the accounts and keys it needs |
list_agent_skills |
Browse the skills an agent can have, and what each one needs to work |
deploy_agent |
Deploy an agent from a template or build one from skills, on the Starter, Pro or Max plan; shows the plan's price, the wallet it charges and the other plans' prices, and asks before charging |
list_my_agents |
List your agents with their status, plan and credits |
get_my_agent |
Read one agent's setup, plan and credits; can wait until it is running |
control_agent |
Start, stop or restart an agent |
update_agent |
Change an agent's name, description, time zone, models, chat commands and setup from chat |
apply_agent_skills |
Turn skills on or off; every plan includes every skill, so a change costs nothing |
set_agent_credentials |
Save the keys, tokens and settings an agent's skills and channels need, such as a Telegram bot token or a Gmail app password |
connect_agent_oauth |
Connect sign-in accounts such as HubSpot or X for the services an agent's skills use; you approve the connection in your browser. Some services need your own app keys or a token first |
disconnect_agent_oauth |
Disconnect a connected account, after your confirmation |
list_projects |
List the projects of the connected project's workspace, to pick one for an agent; no keys are shown |
bind_agent_project |
Connect an agent to a Wiro project so it can run models, with no key in the chat; shows the project first, then asks for your confirmation |
manage_agent_custom_skill |
Add, edit, schedule, restore or remove an agent's own instructions and scheduled tasks; turning off its approval policy or changing its rules needs your confirmation |
manage_agent_billing |
Subscribe, move to another plan, cancel, renew or buy extra credits from your wallet, after your confirmation |
get_agent_activity |
Read an agent's credit usage and activity logs, including who changed what on it |
delete_agent |
Delete an agent, after your confirmation |
Setup changes from chat. A reply from one of your agents can propose a change to its own setup, such as connecting a service, adding a connector or skill, or creating a scheduled task (see Setup From Chat). The assistant shows you the proposal and never approves it on its own. When you agree, it sends your yes as the next message: Wiro answers the first yes with the exact change, and your next yes (or yes 2 for the second of several changes) applies it. Keys never go in a chat message: the assistant saves them with set_agent_credentials. When the change adds a connector that takes a key, the assistant asks for the key together with your yes and saves it right after the change is applied, so one restart loads both. This works while the agent's setup from chat is all, the default, which deploy_agent and update_agent set with chat_setup. With webchat, apply the change in the agent's chat on wiro.ai; with off, the agent asks for it on the agent page.
Controls
These tools read and change the workspace's spend limits and Model Access rules. Reading them is free. They change limits and rules only when the person who created the connected project can change them: a personal account's owner, or in a team a team admin or the organization owner. Other members' connections can read them.
| Tool | Description |
|---|---|
get_controls |
Read the workspace's spend limits, with what each has used and when it resets, its Model Access rules, and whether this connection can change them; on request, also this month's or today's spending by surface, member, API key and agent |
check_model_access |
Explain whether a model may run here and why, rule by rule. Nothing runs and nothing is charged |
manage_spend_limit |
Set or remove a spend limit, after your confirmation |
manage_model_access |
Update, replace or remove a Model Access rule, after your confirmation |
The two manage tools always show a change summary first: what the change covers, the old and new values and, for a limit, what was spent this period. Nothing changes until you confirm. If the limit or rule changed in the meantime, nothing is saved and you get a new summary.
Account and guides
These three tools are always available, whichever groups are loaded.
| Tool | Description |
|---|---|
get_account |
Show which workspace the connected project belongs to, its wallet balance, its spend limits and, when you ask, the wallet's recent transactions |
get_playbook |
Step-by-step guides: getting started, models, workflows, workflow graphs, the Workflow Agent, Studio, agents, billing and Controls |
search_docs |
Search the Wiro documentation for guides and API references |
Playbooks
A tool description is too short to carry the order of calls, the money rules and the formats of a multi-step job, so the server keeps them in playbooks. The server tells the assistant to read the matching playbook with get_playbook before a multi-step job.
| Topic | What it covers |
|---|---|
getting-started |
Which route fits a request, what costs money, keys and workspaces, errors, long waits and the money rules |
models |
Finding and comparing models, schemas and file fields, running, batches, waiting and stopping, prices and limits, earlier tasks and LLM chats |
workflows |
Finding and running workflows, costs, breakpoints, failed runs, editing, cloning and deleting |
workflow-graph |
The graph create_workflow and update_workflow take: steps, Start fields, references, utilities and examples |
workflow-agent |
Briefing the Workflow Agent, editing a workflow by chat, pricing and saving its proposals, sessions |
studio |
When to use Studio, what a turn costs, the brief, collecting the results and slow turns |
agents |
Templates and plans, deploying, statuses, setup and sign-ins, an agent that does not answer, messages, plan changes and credits, skills and schedules, removal |
billing |
Which wallet pays, what is charged and when, minimums and limits, teams, estimates and where to see past spending |
controls |
Spend limits and Model Access: who can change them, scopes and surfaces, periods, how rules combine, recipes, and the refusals with codes 92 and 93 |
Prompts
The server also offers prompts for common jobs. Clients that support MCP prompts show them as ready-made commands. Each prompt sends the assistant to the matching playbook first.
| Prompt | What it does |
|---|---|
build_workflow |
Plan, save and test a multi-step workflow for a goal, confirming costs before any run |
deploy_agent |
Choose a template or skills, quote and deploy an agent, then set it up and test it |
create_with_studio |
Ask Studio to create images, video or audio, after showing what a turn can cost and getting your yes |
talk_to_my_agent |
Find one of your agents, make sure it is running, send it a message and show the reply |
Paid and irreversible actions
Running a model or a workflow, sending a message to Studio or the Workflow Agent, and messages to your own agents (which use the agent's credits) cost money. Before a run or a Studio or Workflow Agent turn, the assistant tells you the expected cost in one line and waits for your yes. A message to your own agent goes out once the assistant has said that it uses the agent's credits.
Agent plans, moves to a larger plan and credit packs are charged to your wallet, so deploy_agent and manage_agent_billing first return the price (for a move inside a billing period, the amount Wiro works out for the time left). They act only when they are called again with confirm: true and confirm_charge_usd, the approved amount, after you agree. If the price changed in between, nothing is charged and you get a new quote. Turning an agent's skills on or off with apply_agent_skills costs nothing, since every plan includes every skill, and a move to a smaller plan starts with the next renewal, with nothing charged or refunded.
Deleting a workflow, an agent, a conversation or an account connection also waits for confirm: true, and so do connecting an agent to a Wiro project with bind_agent_project and replacing a workflow's steps with update_workflow or save_workflow_from_agent: you see a summary of the change first, with the old and new value of each step input that changes. Changing a spend limit or a Model Access rule with manage_spend_limit or manage_model_access also waits for confirm: true: you see the old and new values first and, for a limit, what was spent this period. No tool adds funds or takes a card payment. Funds are added in the Wiro dashboard, and an agent plan paid by card moves to a larger plan or is topped up there.
The connected project decides the workspace: a personal project uses your personal wallet, a team project uses the team wallet. get_account shows which one, its balance and its spend limits, and get_controls its spend limits and Model Access rules in full.
Calls through the hosted MCP server count toward the workspace's spend limits on the mcp surface, and calls from the Wiro browser extensions on the extension surface. The self-hosted package's calls count on the api surface, as calls with its API key. When a limit refuses work (error code 93), the tool returns an error with Wiro's message and a note: nothing ran and nothing was charged, and the work should not be tried again until the limit resets or someone who manages it raises it. get_controls shows the limit and when it resets, and manage_spend_limit changes it after a change summary. Limits are also managed under Controls > Spend Limits.
The workspace's Model Access rules apply to these calls too, on the same surfaces. A model a rule blocks is refused before anything runs (error code 92), and the tool returns an error with Wiro's message, which names the rule. A message to Studio or the Workflow Agent is refused the same way when a rule blocks its chat model, the one it names or the default. Nothing ran and nothing was charged. check_model_access shows why the model is blocked, and manage_model_access changes the rule after a change summary. Rules are also managed under Controls > Model Access.
MCP Request and Response Contract
Every tool advertises typed MCP inputSchema and outputSchema values. Successful calls return structuredContent for reliable LLM tool chaining, concise text content for compatibility, and MCP resource links for generated media.
Every tool that takes arguments refuses an argument it does not know, and nothing is run. The answer lists the arguments the tool takes and names the right one where it can, such as taskid for task_id; run_model adds that model parameters go inside params, and run_workflow that input values go inside input. The one exception is a call that carries toolCallId, a key some clients add on their own: the tool then reads only the arguments it takes.
When a task completes with media, Wiro also returns an assistant-audience delivery instruction. MCP clients do not all preview resource_link blocks inside tool cards, so the assistant is explicitly told to render image URLs and preserve clickable video, audio, and file links in its user-facing response. The standard resource link and full-resolution URL remain available without embedding a large base64 payload.
In the text of a result, an agent's reply, the file and link addresses taken from it and a model's answer sit in fenced blocks under fixed labels. The server's own guidance, its Next: lines and notes, stays outside them, so the assistant can treat that text as content and act only on the guidance and nextAction. A workflow run's text outputs and step errors show the same way. A saved workflow's title, description and input list are shown as data too, in every result, since an agent or another person can have written them. structuredContent keeps each text unchanged in its own field.
For example, an LLM submits one generation:
{
"name": "run_model",
"arguments": {
"model": "owner/model",
"params": { "prompt": "A mountain lake at sunset" },
"wait": true,
"timeout_seconds": 45
}
}
If the generation outlives the bounded wait, the same tool returns the existing task and an executable next action:
{
"state": "running",
"task": {
"id": "123",
"token": "task-token",
"status": "task_start"
},
"outputs": [],
"nextAction": {
"tool": "wait_for_task",
"arguments": { "tasktoken": "task-token" },
"reason": "Continue this exact task. Do not call run_model again."
}
}
Task states are submitted, running, completed, failed, or cancelled. The LLM should execute nextAction when present. A two- or three-minute video can therefore use several bounded wait_for_task calls without creating another billable generation.
Workflow runs, agent replies and agent start-up follow the same pattern: when a wait ends before the job does, the result names the tool and arguments that keep waiting on that same job, such as wait_for_workflow_run or get_agent_message.
An LLM model can continue a chat only when its schema lists session_id. Send the same session_id on every turn, the first one included, with the next prompt. A turn that ended with tool calls is continued with previousTaskToken, that turn's task token, and toolOutputs, as the turn's nextAction template shows.
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, then continue with wait_for_task using the returned token if the generation is still running.
Find models
"What models are available for text-to-video?"
The assistant will call search_models with categories filter.
Check task status
"Check the status of my last task"
The assistant will call get_task with the task token from the previous run.
Resume a previous production
"Show my latest productions and open the newest result"
The assistant will call list_tasks, select the matching task, and call get_task. History is scoped from the authenticated project; the LLM never sends a user UUID.
Build and run a workflow
"Build a workflow that turns a product photo into a short ad video, then run it on this photo"
The assistant reads the workflows and workflow-graph playbooks, picks a model for each step with search_models and get_model_schema, and saves the graph with create_workflow. It tells you the expected cost and waits for your yes, then calls run_workflow and follows wait_for_workflow_run until the video is ready.
Edit a workflow with the Workflow Agent
"Ask the Workflow Agent to add an upscale step to my product ad workflow and save it"
The assistant finds the workflow with list_workflows and sends your request with send_agent_message (agent: "workflow-agent") with the workflow attached. It shows you the proposal and the models it uses, and saves it with save_workflow_from_agent once you agree to the change.
Fix a failed run
"Why did my last workflow run fail? Resume it if it can be resumed"
The assistant calls list_workflow_runs with status failed, reads the failed step with wait_for_workflow_run, and continues the run with resume_workflow_run. Steps that already finished are not charged again.
Create with Studio
"Ask Studio for three logo ideas for a coffee shop"
The assistant checks the balance with get_account, tells you what a Studio turn costs, sends the brief with send_agent_message (agent: "studio") and shows the images from the reply.
Deploy an agent
"Deploy an agent that posts to our Instagram account and tell me what it still needs"
The assistant compares templates with list_agent_templates and get_agent_template, gets the price from deploy_agent, and deploys only after you confirm the amount. Then it lists the missing setup with get_my_agent and connects the account with connect_agent_oauth. If the agent runs Wiro models, it connects a Wiro project with bind_agent_project once you agree to the project it shows.
Talk to your agent
"Tell my support agent to summarise today's tickets"
The assistant finds the agent with list_my_agents, checks that it is running with get_my_agent, and sends the message with send_agent_message. The message uses the agent's credits. If the reply proposes a setup change, the assistant shows it and sends your yes only after you agree.
Cap your spending
"Cap this team's spending at $200 a month"
The assistant calls manage_spend_limit to set a $200 monthly limit on the whole team (scope: "account"). Nothing changes yet: it shows you the change summary, with what was already spent this month, and saves the limit with confirm: true once you agree.
Find out why a model is blocked
"Why can't I run this video model here?"
The assistant calls check_model_access with the model and shows each rule that applies and the one that blocks it. It changes a rule with manage_model_access only when you ask, after you agree to the change summary.
How It Works
The MCP server is stateless. Each request is fully isolated:
- Your AI assistant sends a request to
mcp.wiro.ai/v1with your credentials - The server calls the Wiro API on your behalf
- 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
The model tools are described one by one below. The workflow, conversation, agent and Controls tools follow in tables of their main arguments.
search_models
Search Wiro's model catalog by keyword, category, owner, or any combination. Calls POST /Tool/List on the Wiro API.
| Parameter | Type | Description |
|---|---|---|
search |
string (optional) | Free-text search, e.g. "flux", "video generation" |
categories |
string[] (optional) | Filter by category: text-to-image, text-to-video, image-to-video, llm, text-to-speech, image-editing, etc. |
slugowner |
string (optional) | Filter by model owner slug, e.g. "openai", "google", "klingai" |
sort |
string (optional) | Sort by: relevance, time, ratedusercount, commentcount, averagepoint |
start |
number (optional) | Pagination offset (default 0) |
limit |
number (optional) | Max results (default 20, max 100) |
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.
| Parameter | Type | Description |
|---|---|---|
model |
string | Model slug using clean/lowercase format: "owner/model". Use cleanslugowner/cleanslugproject from search_models. Examples: "openai/sora-2", "black-forest-labs/flux-2-pro", "wiro/virtual-try-on" |
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.
| Parameter | Type | Description |
|---|---|---|
task |
string | What you want to do, e.g. "generate a photorealistic portrait", "upscale an image to 4K", "transcribe audio to text" |
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.
| Parameter | Type | Description |
|---|---|---|
model |
string | Model slug in clean/lowercase format. Same as get_model_schema. Examples: "openai/sora-2", "klingai/kling-v3" |
params |
object | Model-specific parameters as key-value pairs. Use get_model_schema to discover accepted fields. Common: prompt, negativePrompt, width, height, aspectRatio |
wait |
boolean (optional) | If true (default), polls POST /Task/Detail until the task completes or the wait budget expires. If false, returns the task token immediately for wait_for_task or one-time get_task checks. |
timeout_seconds |
number (optional) | Max seconds to wait, counted from the start of the call (default 45, max 3600). Only applies when wait=true. The default suits clients with a 60-second tool timeout; wait longer, such as 300 seconds for a video, when the client allows longer tool calls. |
When wait=true, returns the final task result including pexit (exit code, "0" = success), clickable outputs, and debugoutput (LLM text responses).
If the wait budget expires, the tool returns a normal Task Still Running result with taskid, tasktoken, and the last status. The generation continues. Call wait_for_task; do not call run_model again, because that creates a second billable task.
When wait=false, returns taskid and tasktoken immediately. Use wait_for_task to wait or get_task for a one-time status check.
wait_for_task
Wait for an existing task without submitting another model run. Calls POST /Task/Detail repeatedly for a bounded interval.
| Parameter | Type | Description |
|---|---|---|
tasktoken |
string (optional) | The task token returned from run_model |
taskid |
string (optional) | The task ID (alternative to tasktoken) |
timeout_seconds |
number (optional) | Max seconds for this wait window (default 45, max 3600) |
If the task completes, this tool returns the final text and file outputs. If it is still active, call wait_for_task again with the same identifier. This does not create or bill another model run.
get_task
Check task status and get results. It performs one immediate check by default, or a short bounded wait when wait_seconds is set. Calls POST /Task/Detail on the Wiro API.
| Parameter | Type | Description |
|---|---|---|
tasktoken |
string (optional) | The task token returned from run_model |
taskid |
string (optional) | The task ID (alternative to tasktoken) |
wait_seconds |
number (optional) | Short bounded wait before returning (default 0, max 45). Use wait_for_task for resumable long generations. |
Returns the task's current status, pexit (process exit code), outputs (file URLs), debugoutput (LLM responses), elapsedseconds, and totalcost.
Determining success: Check pexit, where "0" means success and 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.
A live WebSocket task_error event is an interim stderr log, while persisted status: "task_error" returned by Task/Detail marks a pre-execution recovery state. Neither closes the task; wait_for_task continues until task_postprocess_end or task_cancel.
list_tasks
List recent model-generation tasks owned by the authenticated project. Calls POST /Task/List without a uuid; Wiro derives the owner from the API credential.
| Parameter | Type | Description |
|---|---|---|
start |
number (optional) | Pagination offset (default 0) |
limit |
number (optional) | Maximum tasks to return (default 20, max 100) |
model |
string (optional) | Model slug or partial model-name filter |
Returns newest-first task summaries with stable state, model, task ID, timestamps, duration, cost, and limited output links. Call get_task with a returned taskid for the complete result.
get_task_price
Get the cost of a completed task. Calls POST /Task/Detail on the Wiro API and returns billing information.
| Parameter | Type | Description |
|---|---|---|
tasktoken |
string (optional) | The task token returned from run_model |
taskid |
string (optional) | The task ID (alternative to tasktoken) |
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.
| Parameter | Type | Description |
|---|---|---|
tasktoken |
string (optional) | The task token returned from run_model |
taskid |
string (optional) | The task ID (alternative to tasktoken) |
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.
| Parameter | Type | Description |
|---|---|---|
tasktoken |
string (optional) | The task token returned from run_model |
taskid |
string (optional) | The task ID (alternative to tasktoken) |
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.
Tip: Most models take a public URL instead of an upload, so you don't need to upload first: in the field itself for a combinefileinput (e.g. inputImage on most image models), or in the {id}Url / UrlMultiple field for a fileinput or multifileinput (e.g. inputImageUrl). get_model_schema shows each parameter's type. Use upload_file when you need to reuse the same file across multiple runs or when the model specifically requires a Wiro-hosted file. See Model Parameters for details.
| Parameter | Type | Description |
|---|---|---|
url |
string | URL of the file to upload (image, audio, video, document) |
file_name |
string (optional) | Custom filename. If not provided, derived from the URL. |
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.
| Parameter | Type | Description |
|---|---|---|
query |
string | What you're looking for, e.g. "how to upload a file", "websocket", "authentication", "LLM streaming" |
Returns relevant documentation sections matching your query.
get_account and get_playbook
get_account names the workspace of the connected project, personal or a team, and shows that wallet's balance. It is also the call that proves the connection works, since model search, schema reads and search_docs answer without credentials. Without arguments it reads the balance and the workspace's spend limits, each with what it has used this period and whether it is used up. A used-up limit refuses new work with error code 93 even when the wallet has money. With recent_transactions (1 to 50) it also lists that many of the wallet's latest transactions, newest first, as the Transactions page of the Wiro dashboard shows them: each row's time, type, whether it adds to the wallet or takes from it, the amount in USD and what it was for, such as a model run, a store item or an agent. That is how to check that a charge or a credit landed. In a team the wallet is shared, so the list holds the whole team's activity. transactions_start pages back: pass the nextStart of the last answer. get_playbook takes topics, one or more of the playbook topics listed under Available Tools, such as ["workflows"] or ["agents", "billing"].
Workflow tools
The workflow, conversation, agent and Controls tools publish their full input schemas, which your MCP client reads, so the tables below list only their main arguments. A workflow is named by its full slug, such as product-shots-a1B2c, and a run by its run token. The Workflows page describes the API behind these tools.
| Tool | Main arguments |
|---|---|
list_workflows |
scope (mine or public), search, tags, model, sort, start, limit |
get_workflow |
slug, include_graph |
create_workflow |
title, contents (the graph), description, tags |
update_workflow |
slug, loaded_updatetime, title, description, tags, contents, confirm |
clone_workflow |
slug |
delete_workflow |
slug, confirm |
run_workflow |
slug, input (values keyed by the workflow's input names), breakpoint_node_id, wait_seconds |
wait_for_workflow_run |
workflowtoken, wait_seconds, debug_node_id (shows what a step's model received) |
resume_workflow_run |
workflowtoken, breakpoint_node_id, wait_seconds |
list_workflow_runs |
status, search, start, limit |
save_workflow_from_agent |
message_id, session, artifact_hash (which proposal), workflow and loaded_updatetime to save onto an existing workflow, confirm |
Conversation tools
These tools work the same for Studio, the Workflow Agent and your own agents. agent is "studio", "workflow-agent" or the guid of one of your agents, and session names the conversation, following the session name rule under Available Tools. See Studio, Workflow Agent and Agent Messaging.
| Tool | Main arguments |
|---|---|
send_agent_message |
agent, message, session, model (Studio and the Workflow Agent), attachment_urls, workflow (the workflow to edit, Workflow Agent only), wait_seconds |
get_agent_message |
agent, message_id, session, wait_seconds |
get_agent_conversation |
agent, session (leave it out to list the conversations, newest first), limit, before (older messages: pass nextBefore), start (older conversations: pass nextStart; a list longer than one page also returns total) |
cancel_agent_message |
agent, message_id, session |
delete_agent_session |
agent, session, confirm |
list_studio_results |
limit (up to 100 recent runs), state, since |
Agent tools
An agent is named by its guid, which list_my_agents returns. See Agent Overview, Agent Builder, Agent Credentials & OAuth and Agent Skills for the API behind these tools.
| Tool | Main arguments |
|---|---|
list_agent_templates |
search, category, sort (newest, popular or title), start, limit |
get_agent_template |
template, include_tasks |
list_agent_skills |
name, category, capability |
deploy_agent |
template, or custom: true with skills; tier (starter, pro or max), title, credentials, chat_setup (all, webchat or off), confirm, confirm_charge_usd |
list_my_agents |
sort, start, limit |
get_my_agent |
agent_guid, wait_seconds (wait until it is running) |
control_agent |
agent_guid, action (start, stop or restart) |
update_agent |
agent_guid, title, description, timezone, team_session_mode, chat_model, cron_model, enabled_commands, chat_setup (all, webchat or off; null goes back to all) |
apply_agent_skills |
agent_guid, skills, add_dependencies, idempotency_key (only to repeat a change whose answer did not arrive) |
set_agent_credentials |
agent_guid, credential, fields |
connect_agent_oauth |
agent_guid, credential, action (connect, status or select_accounts), mode (wiro, own or api_key), confirm |
disconnect_agent_oauth |
agent_guid, credential, confirm |
list_projects |
agent_guid (optional: also says which listed project that agent uses) |
bind_agent_project |
agent_guid, project_id (from list_projects; leave it out for the connection's own project), confirm |
manage_agent_custom_skill |
agent_guid, action (upsert, rename, delete, history or revert), key, kind, value, interval, enabled, confirm |
manage_agent_billing |
agent_guid, action (subscribe, change_plan, cancel, renew or buy_credits), plan (starter, pro or max, for subscribe and change_plan), pack, confirm, confirm_charge_usd |
get_agent_activity |
agent_guid, kind (usage, logs or log_dates), date |
delete_agent |
agent_guid, confirm |
list_projects lists the projects of the connected project's workspace by id and name. It marks the connection's own project, the projects this connection can connect to an agent (the ones you created, or any project of a team you are an admin of) and the projects with an IP whitelist, and it shows no keys. bind_agent_project connects the Wiro project an agent runs models with. Called without confirm, it changes nothing: it shows the project, the one it replaces, whether a running agent restarts and which wallet pays for the agent's model runs (the wallet of the workspace that owns the project). After you agree, the assistant repeats the call with confirm: true, as its nextAction shows. Connecting the project an agent already has changes nothing and restarts nothing. On a team agent, a team admin can connect any project of the team, and the person who deployed the agent the projects they created. The API behind it is POST /UserAgent/CredentialProjectBind.
Controls tools
A limit or a rule is for one scope: account, member (a team member, by e-mail or user uuid), project (an API key, by its project's id or name; left out, the key of this connection), surface or agent (by guid or name). See Spend Limits and Model Access for the API behind these tools.
| Tool | Main arguments |
|---|---|
get_controls |
usage (month or day: also that period's spending by surface, member, API key and agent) |
check_model_access |
model (owner/slug or id), member, project, surface, agent |
manage_spend_limit |
action (set or remove), scope and its target (member, project, surface or agent), period (month or day), amount_usd, alert_percent (50, 80, 90 or null), limit_guid (to remove), confirm |
manage_model_access |
action (update, replace or remove), scope and its target, everything_else (allow or block), categories, models, rule_guid (to remove), confirm |
Called without confirm, the two manage tools change nothing: they return the change summary. After you agree, the assistant repeats the call with confirm: true, as its nextAction shows. update keeps the entries of a rule that you don't name, and replace writes the whole rule again.
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 or logged.
Does it cost extra?
No. The MCP server itself is free. You pay the normal prices for the work the tools start: model runs, the model steps of workflow runs, Studio and Workflow Agent turns, and agent plans and credits.
What about rate limits?
The hosted MCP endpoint counts requests for each Bearer token, or for each caller IP when a request has none, in a fixed 60-second window. Each window allows 60 tool calls and prompt reads, where every message of a batch counts, and 300 other requests, such as initialize, notifications, listings and ping. Responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds) for the 60-call budget.
A request over the limit gets HTTP 429 with Retry-After, the same RateLimit headers for the limit it hit, and a JSON-RPC error (code -32000) that says it was not run and when to try again. A batch larger than one window allows gets HTTP 400 (code -32600): it was not run, and it has to be split. These limits come on top of Wiro API project limits. Long generations do not require rapid polling: follow the returned bounded wait_for_task action.
Can I self-host?
Yes. See Self-Hosted MCP for instructions.
Self-Hosted MCP
Run the Wiro MCP server locally on your own machine using npx.
Quick Start
Add to your AI assistant's MCP config:
{
"mcpServers": {
"wiro": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@wiro-ai/wiro-mcp@latest"],
"env": {
"WIRO_API_KEY": "your-api-key",
"WIRO_API_SECRET": "your-api-secret"
}
}
}
}
That's it. Your assistant can now run Wiro models, build and run workflows, and work with Studio and your own agents. The @latest in args makes npx look up the newest version on npm each time the client starts the server, so it never reuses an older cached build.
Setup
Add the self-hosted MCP server to your AI assistant:
Cursor
Open MCP settings (Cmd+Shift+P → "Open MCP settings") and add:
{
"mcpServers": {
"wiro": {
"command": "npx",
"args": ["-y", "@wiro-ai/wiro-mcp@latest"],
"env": {
"WIRO_API_KEY": "your-api-key",
"WIRO_API_SECRET": "your-api-secret"
}
}
}
}
Claude Code
claude mcp add wiro -- npx -y @wiro-ai/wiro-mcp@latest
Then set environment variables:
export WIRO_API_KEY="your-api-key"
export WIRO_API_SECRET="your-api-secret"
Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"wiro": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@wiro-ai/wiro-mcp@latest"],
"env": {
"WIRO_API_KEY": "your-api-key",
"WIRO_API_SECRET": "your-api-secret"
}
}
}
}
Windsurf
Add to your MCP settings:
{
"mcpServers": {
"wiro": {
"command": "npx",
"args": ["-y", "@wiro-ai/wiro-mcp@latest"],
"env": {
"WIRO_API_KEY": "your-api-key",
"WIRO_API_SECRET": "your-api-secret"
}
}
}
}
Kiro
Add to ~/.kiro/settings/mcp.json (every workspace) or .kiro/settings/mcp.json (this workspace):
{
"mcpServers": {
"wiro": {
"command": "npx",
"args": ["-y", "@wiro-ai/wiro-mcp@latest"],
"env": {
"WIRO_API_KEY": "your-api-key",
"WIRO_API_SECRET": "your-api-secret"
}
}
}
}
goose
In the goose CLI, run goose configure, pick Add Extension > Command-line Extension, enter npx -y @wiro-ai/wiro-mcp@latest as the command and add WIRO_API_KEY and WIRO_API_SECRET as environment variables. goose Desktop takes the same command and variables under Extensions > Add custom extension. Or add Wiro to ~/.config/goose/config.yaml:
extensions:
wiro:
name: Wiro AI
type: stdio
cmd: npx
args: ["-y", "@wiro-ai/wiro-mcp@latest"]
envs:
WIRO_API_KEY: your-api-key
WIRO_API_SECRET: your-api-secret
enabled: true
timeout: 300
Other Clients
Any MCP client that supports the stdio transport can connect. The command is:
npx -y @wiro-ai/wiro-mcp@latest
Set WIRO_API_KEY and WIRO_API_SECRET as environment variables in your client's MCP configuration.
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
Authentication errors
If the project uses signature-based auth and WIRO_API_SECRET is not set, tool calls fail with:
Wiro API error 401: This project uses signature-based auth. Set WIRO_API_SECRET to the project's API secret in your MCP server config.
Add WIRO_API_SECRET to the env block of your MCP config and restart the client. The other messages are the same as on the hosted server: see Authentication errors.
Available Tools
The self-hosted server provides the same 54 typed tools, playbooks and prompts as the hosted MCP server. Successful calls include structuredContent for LLM chaining plus text content for compatibility. Completed media calls return standard MCP resource links and an assistant-audience delivery instruction so the assistant can present image previews and clickable media links in its user-facing response even when the client does not render media inside its tool card.
All four tool groups load by default. To load fewer tools, set WIRO_TOOLSETS (see Environment Variables). get_account, get_playbook and search_docs are always available.
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.
Models
| Tool | Wiro API | Description |
|---|---|---|
search_models |
POST /Tool/List |
Search and browse AI models by keyword, category, or owner. Returns model slugs, titles, descriptions, categories, and pricing. |
get_model_schema |
POST /Tool/Detail, POST /Workflow/UtilityDetail |
Get full parameter schema and pricing for any model: parameter names, types, options, defaults, and required fields. For a workflow utility, its parameters and output ports. |
recommend_model |
POST /Tool/List |
Find models for a goal from two or three key words, best matches first. |
explore |
POST /Tool/Explore |
Browse curated AI models organized by category. No parameters needed. |
run_model |
POST /Run/{owner}/{model} |
Run any model with parameters. Waits up to 45 seconds by default; if still active, returns a recoverable token for wait_for_task. |
wait_for_task |
POST /Task/Detail |
Continue waiting for an existing task in bounded windows without creating a duplicate model run. |
get_task |
POST /Task/Detail |
Check task status immediately, or wait up to 45 seconds with wait_seconds. Returns pexit, outputs, logs, elapsed time, and cost. |
list_tasks |
POST /Task/List |
Browse authenticated generation history across conversations and continue with get_task. |
get_task_price |
POST /Task/Detail |
Get the cost of a completed task. Shows whether it was billed and the total charge. Only successful tasks (pexit: "0") are billed. |
cancel_task |
POST /Task/Cancel |
Cancel a task still in queue (before worker assignment). |
kill_task |
POST /Task/Kill |
Stop a queued or running task. Task moves to task_cancel status. |
upload_file |
POST /File/Upload |
Upload a file from a public http(s) URL (up to about 100 MB). Most models also take a public URL directly, without uploading first. |
Workflows
| Tool | Wiro API | Description |
|---|---|---|
list_workflows |
POST /Workflow/List |
List the workflows in your workspace, or search the public gallery by text, tag or model. |
get_workflow |
POST /Workflow/Detail |
Read a workflow's inputs, outputs and step graph. |
create_workflow |
POST /Workflow/Prepare, POST /Workflow/Add |
Save a new workflow from a step graph. Wiro checks it against the live model catalog and returns every problem it finds at once. |
update_workflow |
POST /Workflow/Prepare, POST /Workflow/Update |
Edit a workflow's title, description, tags or graph without overwriting newer changes; a new graph is saved only after you confirm a summary of the change. |
clone_workflow |
POST /Workflow/Clone |
Copy a public workflow into your workspace. |
delete_workflow |
POST /Workflow/Delete |
Delete a workflow, after your confirmation. |
run_workflow |
POST /Workflow/Run |
Run a workflow and wait for its outputs; can stop after a chosen step to test the first steps. |
wait_for_workflow_run |
POST /Workflow/RunDetail, POST /Workflow/RunNodeDetail |
Keep waiting on a run, read its outputs, or see why a step failed. |
resume_workflow_run |
POST /Workflow/RunResume |
Continue a failed or stopped run without paying again for finished steps. |
list_workflow_runs |
POST /Workflow/RunHistory |
Browse past and current runs, including runs started on wiro.ai. |
save_workflow_from_agent |
POST /StudioWorkflow/Message/Detail, then /Workflow/Add or /Workflow/Update |
Save a workflow the Workflow Agent proposed, as a new workflow, or onto an existing one after you confirm a summary of the change. |
Agents
The conversation tools call the matching Message/* route of Studio (/Studio/), the Workflow Agent (/StudioWorkflow/) or a deployed agent (/UserAgent/), chosen by their agent argument.
| Tool | Wiro API | Description |
|---|---|---|
send_agent_message |
Message/Send, or Message/SendForm with attachments |
Send a message and wait for the reply, with any media, workflows or model runs it produced. |
get_agent_message |
Message/Detail |
Keep waiting on a reply, or read one again. |
get_agent_conversation |
Message/Sessions, Message/History |
List conversations, or read one conversation's history. |
cancel_agent_message |
Message/Cancel |
Stop a reply that is still being written. |
delete_agent_session |
Message/ClearSession (Studio), Message/DeleteSession |
Delete a conversation and the agent's memory of it, after your confirmation. |
list_studio_results |
POST /Studio/Tasks |
List the images, videos and other results Studio generated for you. |
list_agent_templates |
POST /Agent/List |
Browse ready-made agent templates and the three monthly plans. |
get_agent_template |
POST /Agent/Detail |
Read a template's skills, plans, and the accounts and keys it needs. |
list_agent_skills |
POST /Skills/List, /Skills/Detail, /Skills/Capabilities |
Browse the skills an agent can have, and what each one needs to work. |
deploy_agent |
POST /UserAgent/PricingPreview, /UserAgent/Deploy |
Deploy an agent from a template or build one from skills, on the Starter, Pro or Max plan; shows the plan's price, the wallet it charges and the other plans' prices, and asks before charging. |
list_my_agents |
POST /UserAgent/MyAgents |
List your agents with their status, plan and credits. |
get_my_agent |
POST /UserAgent/Detail |
Read one agent's setup, plan and credits; can wait until it is running. |
control_agent |
POST /UserAgent/Start, /UserAgent/Stop, /UserAgent/Update (restart) |
Start, stop or restart an agent. |
update_agent |
POST /UserAgent/Update, /UserAgent/UpdateSettings |
Change an agent's name, description, time zone, models, chat commands and setup from chat. |
apply_agent_skills |
POST /UserAgent/PricingPreview, /UserAgent/SkillsApply |
Turn skills on or off; every plan includes every skill, so a change costs nothing. |
set_agent_credentials |
POST /UserAgent/CredentialUpsert, /UserAgent/CredentialFileUpload |
Save the keys, tokens and settings an agent's skills and channels need, such as a Telegram bot token or a Gmail app password. |
connect_agent_oauth |
POST /UserAgentOAuth/OAuthConnect, /UserAgentOAuth/OAuthStatus, /UserAgentOAuth/SetPickerAccounts |
Connect sign-in accounts such as HubSpot or X for the services an agent's skills use; you approve the connection in your browser. Some services need your own app keys or a token first. |
disconnect_agent_oauth |
POST /UserAgentOAuth/OAuthDisconnect |
Disconnect a connected account, after your confirmation. |
list_projects |
POST /Project/List, /UserAgent/Detail (with agent_guid) |
List the projects of the connected project's workspace, to pick one for an agent; no keys are shown. |
bind_agent_project |
POST /UserAgent/Detail, /Project/List, then /UserAgent/CredentialProjectBind |
Connect an agent to a Wiro project so it can run models, with no key in the chat; shows the project first, then asks for your confirmation. |
manage_agent_custom_skill |
POST /UserAgent/CustomSkillUpsert, CustomSkillRename, CustomSkillDelete, CustomSkillHistory, CustomSkillRevert |
Add, edit, schedule, restore or remove an agent's own instructions and scheduled tasks; turning off its approval policy or changing its rules needs your confirmation. |
manage_agent_billing |
POST /UserAgent/CreateSubscriptionCheckout, UpgradeTier, CancelSubscription, RenewSubscription, CreateExtraCreditCheckout |
Subscribe, move to another plan, cancel, renew or buy extra credits from your wallet, after your confirmation. |
get_agent_activity |
POST /UserAgent/TransactionList, /UserAgent/LogsList, /UserAgent/Logs |
Read an agent's credit usage and activity logs, including who changed what on it. |
delete_agent |
POST /UserAgent/Delete |
Delete an agent, after your confirmation. |
Controls
These tools read and change the workspace's spend limits and Model Access rules. They come with @wiro-ai/wiro-mcp 1.9.0 and later. The self-hosted server's calls count on the api surface, as calls with its API key. Its Controls tools change limits and rules only when the person who created the key's project can change them: a personal account's owner, or in a team a team admin or the organization owner.
| Tool | Wiro API | Description |
|---|---|---|
get_controls |
POST /SpendLimit/List, /ModelAccess/List, /SpendLimit/Usage |
Read the workspace's spend limits, with what each has used and when it resets, its Model Access rules, and whether this connection can change them; on request, also this month's or today's spending by surface, member, API key and agent. |
check_model_access |
POST /ModelAccess/Check |
Explain whether a model may run here and why, rule by rule. Nothing runs and nothing is charged. |
manage_spend_limit |
POST /SpendLimit/List, /SpendLimit/Preview, /SpendLimit/Set, /SpendLimit/Remove |
Set or remove a spend limit. It shows a change summary first and changes nothing until you confirm. |
manage_model_access |
POST /ModelAccess/List, /ModelAccess/Preview, /ModelAccess/Set, /ModelAccess/Remove |
Update, replace or remove a Model Access rule. It shows a change summary first and changes nothing until you confirm. |
Account and guides
| Tool | Wiro API | Description |
|---|---|---|
get_account |
POST /Wallet/List, /SpendLimit/List, /Wallet/TransactionList |
Show which workspace the connected project belongs to, its wallet balance, its spend limits and, when you ask, the wallet's recent transactions. |
get_playbook |
Built into the server | Step-by-step guides: getting started, models, workflows, workflow graphs, the Workflow Agent, Studio, agents, billing and Controls. |
search_docs |
Wiro Docs | Search the Wiro documentation for guides, API references, and examples. |
See the Wiro MCP Server page for the playbook topics, the prompts, the rules for paid and irreversible actions, and the tool arguments.
Environment Variables
| Variable | Required | Description |
|---|---|---|
WIRO_API_KEY |
Yes | Your Wiro project API key |
WIRO_API_SECRET |
No | API secret (for signature auth) |
WIRO_API_BASE_URL |
No | Override API URL (default: https://api.wiro.ai/v1) |
WIRO_TOOLSETS |
No | Comma-separated tool groups to load: models, workflows, agents, controls (default: all) |
Choosing tool groups
Some clients work best with fewer tools. Set WIRO_TOOLSETS to load only the groups you need:
"env": {
"WIRO_API_KEY": "your-api-key",
"WIRO_TOOLSETS": "models,workflows"
}
get_account, get_playbook and search_docs are always available, and workflows also brings the model search tools it needs. controls loads the four Controls tools. The conversation tools for Studio and the Workflow Agent, with save_workflow_from_agent, come with either workflows or agents, and each prompt appears only when its tools are loaded. If a job needs a tool from a group that is not loaded, the server instructions tell the assistant to say so.
GitHub & npm
- GitHub: github.com/wiroai/Wiro-MCP
- npm: @wiro-ai/wiro-mcp
Using as a Library
import { WiroClient } from '@wiro-ai/wiro-mcp/client';
import { createMcpServer } from '@wiro-ai/wiro-mcp/server';
const client = new WiroClient('your-api-key', 'your-api-secret');
const server = createMcpServer(client);
// Only the model and workflow tools
const modelsAndWorkflows = createMcpServer(client, { toolsets: ['models', 'workflows'] });
| Export | Description |
|---|---|
createMcpServer(client, options?) |
Creates an McpServer with the tools, prompts and server instructions registered. options.toolsets picks tool groups and the prompts that use them; options.instructions replaces the instructions; options.wrapTool(tool, handler) returns the handler to register for each tool, for your own logging or permission checks; options.maxToolInputElements caps the array elements and object members one tool call may carry (default 10000, Infinity turns the check off) |
WiroClient |
API client supporting both auth types (signature + apikey-only); post(path, body) calls any Wiro API endpoint with the same credentials, and isOwnApiKey(value) says whether a value is this client's API key. Its requestHeaders option sends headers of your own with every request (see Node.js Library) and replaces the trustedProxy option, which was removed in 1.5.0 |
registerTools(server, client, options?) |
Registers the tools on an McpServer you already have, with the same toolsets and wrapTool options. That server then lists every tool schema, its own tools included, as JSON Schema 2020-12 |
advertiseJsonSchema2020_12(server) |
Makes an McpServer list its tool schemas as JSON Schema 2020-12. Call it when you register single tools from @wiro-ai/wiro-mcp/tools instead of using registerTools |
withJsonSchema2020_12(transport) |
The same for one transport: await server.connect(withJsonSchema2020_12(transport)) |
parseToolsets(value) |
Parse a WIRO_TOOLSETS-style list such as "models,agents" |
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 20 or later. Create a project to get API keys.
Node.js Library
Use Wiro AI models directly in your Node.js or TypeScript projects with a simple API client.
Overview
The @wiro-ai/wiro-mcp package exports a WiroClient class that you can use as a standalone API client, with no MCP setup required. It handles authentication (both signature-based and API key only), model discovery, execution, task polling, and file uploads.
Links
Installation
npm install @wiro-ai/wiro-mcp
Requires Node.js 20 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');
Your Own Request Headers
To send headers of your own with every API request, pass requestHeaders in the options (fourth parameter):
const client = new WiroClient('your-api-key', 'your-api-secret', undefined, {
requestHeaders: () => ({ 'x-app-name': 'my-app' })
});
The function runs for every request the client sends, JSON and multipart, and gets one object, { pathname, apiKey }, where pathname includes the base path, such as /v1/Tool/List. It returns a plain object of string values, and those headers are sent after the client's own. It cannot set x-api-key, x-signature, x-nonce or Content-Type, in any letter case: such a request fails before it is sent. Type it with RequestHeadersHook. This option replaces trustedProxy, which was removed in 1.5.0: a client created with trustedProxy throws.
Available Methods
| Method | Description |
|---|---|
searchModels(params?) |
Search and browse models by keyword, category, or owner. |
getModelSchema(model) |
Get full parameter schema and pricing for a model. |
explore() |
Browse curated models organized by category. |
runModel(model, params, signal?) |
Run a model. Returns task ID and socket access token. |
waitForTask(tasktokenOrReference, timeoutMs?, options?) |
Poll until completion. Default timeout: 120 seconds. Supports AbortSignal, stepped polling, progress callbacks, and transient retries. |
getTask({ tasktoken?, taskid? }, signal?) |
Get current task status and outputs. |
cancelTask(tasktokenOrReference, signal?) |
Cancel a queued task. Resolves a token to the task ID required by the API. |
killTask(tasktokenOrReference, signal?) |
Kill a running task using its socket access token or task ID. |
listTasks(params?, signal?) |
List the tasks of the key's workspace, newest first. |
uploadFile(url, fileName?) |
Upload a file from a URL for use as model input. |
post(path, body?, signal?) |
Call any other Wiro API endpoint with the same credentials, for example post('/Workflow/List', { scope: 'my' }). Wiro reports each outcome in the response body, so check result on the returned body. |
postForm(path, form, signal?) |
Same as post, for endpoints that take multipart/form-data. |
isOwnApiKey(value) |
Says whether a value is this client's API key, without handing the key out. |
If waitForTask exceeds its timeout, it throws TaskWaitTimeoutError and preserves lastDetail. Call it again with the same token or task ID; do not call runModel again for the same generation.
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
Tip: Most models take a public URL instead of an upload. For most image and video inputs you pass it in the field itself, such as inputImage: 'https://example.com/photo.jpg'; a fileinput takes it in its {id}Url field (such as inputImageUrl), so check the model's parameter types. Use uploadFile() when you need to reuse files across multiple runs.
// 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,
TaskReference,
WaitForTaskOptions,
RequestHeadersHook,
} from '@wiro-ai/wiro-mcp/client';
import {
TaskPollingError,
TaskWaitTimeoutError,
} from '@wiro-ai/wiro-mcp/client';
| Type | Description |
|---|---|
RunModelResult |
Response from runModel(): taskid, socketaccesstoken. |
TaskDetailResponse |
Response from getTask() / waitForTask(): contains tasklist array. |
Task |
Individual task object: status, pexit, outputs, debugoutput, etc. |
TaskOutput |
Output entry: file (name, url) or LLM (contenttype: "raw", content). |
ToolListResponse |
Response from searchModels(): contains tool array. |
ToolDetailResponse |
Response from getModelSchema(): contains model with parameters. |
SearchModelsParams |
Search parameters: search, categories, slugowner, limit, etc. |
TaskReference |
Existing task identifier: tasktoken or taskid. |
WaitForTaskOptions |
Polling options: signal, onPoll, pollIntervalMs, and retry limit. |
RequestHeadersHook |
The requestHeaders option: gets { pathname, apiKey } and returns the headers to add. |
TaskWaitTimeoutError |
Bounded wait expired; carries the last Task/Detail response. |
TaskPollingError |
Repeated or permanent status lookup failure; also carries the last response. |
n8n Wiro Integration
Run any Wiro AI model from your n8n workflows: video, image, audio, LLM, 3D, and more.
Overview
n8n is a powerful workflow automation platform. The Wiro AI community node, published on npm as @wiro-ai/n8n-nodes-wiro, runs any model in the Wiro AI catalog from a single node.
Pick a model from a searchable list and its inputs load into the node with their default values. The node starts a task on Wiro, waits for it to finish and returns the output files, or the reply of a text model. It also works as a tool for an n8n AI Agent.
Links
Available Model Categories
| Category | Models | Examples |
|---|---|---|
| Video Generation | Text-to-video, image-to-video | Veo 3.1, Kling V3, Seedance, Hailuo, PixVerse, Runway |
| Image Generation | Text-to-image, style transfer | GPT Image 2, Flux 2 Pro, Seedream, Nano Banana, Qwen Image |
| Image Editing | Try-on, face swap, background removal | Virtual Try-On, Face Swap, Prompt-based Editing, Style Transfer |
| Audio & Speech | TTS, STT, voice clone, music | ElevenLabs TTS, Gemini TTS, Whisper STT, Voice Clone |
| LLM Chat | Chat completion, RAG | GPT-5.2, GPT-5 Mini, Gemini 3, Claude Fable 5.2, RAG Chat |
| 3D Generation | Image/text to 3D | Trellis 2, Hunyuan3D 2.1 |
| Translation | Multi-language with image support | Gemma-based (4B, 12B, 27B) |
| E-Commerce | Product photos, ads, templates | Product Photoshoot, Shopify Templates, UGC Creator |
| HR Tools | CV analysis, job descriptions | CV Evaluator, Resume Parser, Culture Fit |
Wiro AI Node
| Resource | Operation | What it does |
|---|---|---|
| Model | Run | Runs a model with your inputs and returns its outputs |
| Task | Get | Reads a task by its ID, with its status and outputs |
| Task | Wait | Waits until a task finishes, then returns its outputs |
- Model: pick the model from the searchable list, paste its wiro.ai link, or type it as
owner/model, such aspruna/p-image. - Inputs: the inputs of the model you picked load into the node with their default values. Required inputs are always shown; add advanced ones with Add input to send. Fill them in or map them from the incoming item. File inputs take public URLs; separate several URLs with commas.
- Wait for Completion is on by default, and the node waits up to 20 minutes (change it with Max Wait Time). Turn it off to get the task ID at once, then read the task later with Task > Get or Task > Wait.
The node returns the task with its output files and cost:
{
"taskId": "5986221",
"status": "completed",
"model": "pruna/p-image",
"url": "https://cdn1.wiro.ai/xyz/0.png",
"urls": ["https://cdn1.wiro.ai/xyz/0.png"],
"costUsd": 0.005,
"elapsedSeconds": 3
}
| Field | What it holds |
|---|---|
taskId | The ID of the Wiro task |
status | queued, running, completed, failed or cancelled |
model | The model, as owner/model |
url | The first output file |
urls | Every output file |
text | The reply of a text model |
costUsd | What the task cost, in US dollars |
elapsedSeconds | How long the task ran |
A task that fails or is cancelled stops the node with an error. To handle it in its own branch, set the node's On Error setting to Continue (using error output). A task still running when the wait ends comes back with status: "running": read it later with Task > Wait and the same task ID instead of starting it again.
Installation
Install the community node package in your n8n instance:
From the nodes panel
The Wiro AI node is verified by n8n. An instance owner can search for Wiro AI in the nodes panel of the workflow editor and install it, on n8n Cloud and on self-hosted instances that show verified community nodes. After that, everyone on the instance can add it to their workflows.
Via n8n UI (Recommended)
- Open your n8n instance Navigate to your self-hosted or cloud n8n dashboard
- Go to Settings Open Settings → Community Nodes
-
Install the node Click Install a community node and enter:
@wiro-ai/n8n-nodes-wiro - Confirm Click Install and wait for completion
Via Command Line
npm install @wiro-ai/n8n-nodes-wiro
Run it in ~/.n8n/nodes, then restart n8n.
Authentication
The node supports both Wiro authentication methods:
- Add credentials Go to Credentials → Add new → Wiro AI API in n8n
- Enter your keys Paste the project's API Key. If the project uses signature authentication, also paste its API Secret: the node then signs every request with HMAC-SHA256 and never sends the secret.
- Save Click Save, and n8n checks the key
Get your credentials at wiro.ai/panel/project. Runs are billed to the wallet of the project's workspace.
Usage
Search the node picker for "Wiro AI" and add the node with the Run a model action, then pick the model.
Example: Generate an Image with P-Image
- Add the Wiro AI node with the Run a model action
- In Model, search for
p-imageand pickpruna/p-image - Under Inputs, set Prompt to
A red bicycle on a sunny street - Run the workflow:
urlin the output links to the image
Example: Generate a Video with Kling V3
- Add the Wiro AI node and pick
klingai/kling-v3in Model - Set Prompt to
A cat astronaut floating in space, and leave Duration and Ratio at their defaults or pick others - Run the workflow:
urlin the output links to the video
Example: Turn an LLM Reply into an Image
- Add a Wiro AI node with
openai/gpt-5-miniand a Prompt that asks for one image prompt. Its reply is intext - Add a second Wiro AI node with
pruna/p-imageand map its Prompt to{{ $json.text }} - Run the workflow:
urlin the second node's output links to the image
The package README has this workflow as JSON that you can paste into n8n.
Compatibility
| Requirement | Version |
|---|---|
| n8n | v1.85.0+ |
| Package | @wiro-ai/n8n-nodes-wiro@latest |
Workflows
Chain models and built-in steps into one graph, save it, and run it again with new inputs.
Overview
A workflow is a saved chain of steps. Each step runs one Wiro model or one built-in utility. The Start node holds the inputs people fill in, and the End node lists the results. A saved workflow runs each time someone starts it, on wiro.ai/workflows or through the API.
The /Workflow/* endpoints list and read workflows, save new ones from a graph, edit, clone and delete them, run them and follow their runs. To design a workflow in plain language, use the Workflow Agent. The Wiro MCP Server offers these endpoints as tools for AI assistants.
Authentication
Every /Workflow/* route on this page takes a project API key: x-api-key, plus x-nonce and x-signature for a project that uses signature authentication (see Authentication). A key acts as the person who created its project, in that project's workspace.
Workspaces and the gallery
- A workflow belongs to the workspace it was created in: personal, or a team. Another workspace cannot read, run or change it, unless it is published in the public gallery: anyone can read and run a published workflow.
- A protected workflow hides its steps from people outside its owner's workspace. They can still see its inputs and outputs and run it.
- Workflows saved through the API are private. Publishing to the gallery happens on wiro.ai, and a published workflow goes through review again after its title, description, tags or steps change.
Slugs
A workflow is named by its full slug: its slug, a dash and its 5-character slugid, such as product-shots-a1B2c. Every endpoint that takes a workflow takes the full slug as slug. The workflow's page is https://wiro.ai/workflows/<full slug>.
The Workflow Graph
A workflow's definition is one JSON object, its contents. It holds the steps, the Start fields people fill in and the End node that lists the results. Before you save a graph you wrote yourself, prepare it with Workflow/Prepare: it checks the graph against the live model catalog and fills in what the Wiro editor would.
| Field | Type | Description |
|---|---|---|
version |
string | Always "1". |
nodes |
object | The steps, keyed by step id, plus the End node under the key output. The Start node is not in nodes. |
schema.input |
object | The Start fields, keyed by the input names a run takes. |
schema.output |
object | Always {}. |
output |
object | A copy of the End node's fields. |
metadata.input.position |
object | Where the Start node sits on the canvas, such as { "x": 0, "y": 0 }. |
metadata.input.values |
object | Optional saved values for the Start fields. A run uses them for the fields it leaves out. |
Workflow/Prepare accepts a graph of at most 40 KB of JSON (40,960 bytes), and counts it again after it fills each step's defaults.
Steps
Each step is "node-<id>": { "id", "type", "tool", "depends", "input", "metadata" }.
- The key is
node-followed by 1 to 64 letters, digits,-or_.idrepeats the key exactly, andtypeis"run". toolis a model slug (owner/model) or a built-in utility:workflow-utilities/output-filter,workflow-utilities/merge-textorworkflow-utilities/split-text.inputmaps the tool's parameter ids, from Tool/Detail, to values: fixed values, or references to Start fields and earlier steps.dependslists every source the step reads:"input"when it uses a Start field, and the id of each step it references. No duplicates, never the step itself, never"output".metadata.positionis{ "x": number, "y": number }and only places the step on the canvas.
Start fields
Each key in schema.input is that input's name at run time. Give each field label, type, defaultValue and ui (an object); Workflow/Prepare fills in the rest the way the editor does. wiro.ai titles each field with its key in the run form, so use a short readable key such as product_photo.
- Text:
"type": "string"with"ui": { "field": "textarea" }. - Choice list:
"type": "string"with"ui": { "field": "select", "options": [{ "value": "16:9", "text": "Wide" }] }. - Number:
"type": "number"(whole) or"float"(decimal). Yes or no:"type": "boolean". Both with"ui": {}. - File:
"type": "string"with"ui": { "field": "image" }, or"audio","video"or"pdf". The value is a public URL.
A Start field that the End node or a step leading to it uses, with no saved value and no default, must get a value when the workflow runs. Workflow/Detail names these fields in requiredinputs.
References
$input.<key>is the value of a Start field.$node-<id>.outputsis everything a model step produced: its files, or an LLM step's reply.$node-<id>.resultis the result ofoutput-filterormerge-text.$node-<id>.text1to.textNare the parts produced bysplit-text.
A reference must be the whole string value, or one whole item of an array. It is never filled in inside longer text, and a fixed value that starts with $ is read as a reference. To put a Start field or an LLM answer inside a prompt, join the parts with merge-text, such as "texts": ["Write a caption for:", "$input.name"], and reference its result.
When a model step's outputs feed another model, a single file parameter takes the first file, a combined file parameter (combinefileinput) takes all of the files, and a text parameter takes the first file URL or the LLM's answer.
The End node
It is "output": { "id": "output", "type": "display", "depends", "input": {}, "fields", "metadata" }.
fieldsmaps each result name to one reference. Give each result its own source.dependslists the steps the fields read from. It cannot be empty: a workflow with nothing wired to its End node cannot run.- The top-level
outputmust equalfields. Steps that do not lead to the End node never run.
Built-in utilities
Utilities are free and finish at once. Workflow/UtilityDetail returns their parameters and output ports.
output-filterpicks items from a model step. Itsoutputsparameter must be a$node-<id>.outputsreference. Withmode"file"it keeps the files that matchcontenttype(such as"image","audio/*"or"mp3") andname, up tocountitems (default 1). Withmode"llm"it takesfield("answer","thinking","raw"or"prompt") from an LLM step. Port:result.merge-textjoinstexts(an array of references or fixed strings) withseparator(default a space), skipping empty items unlessskipEmptyisfalse. Port:result.split-textsplitstextbyseparator(default a new line) intocountparts, 2 to 10 (default 5).countmust be a fixed value. Ports:text1totextN.
Other operations, such as joining videos or adding a voice track to a video, are ordinary models in the catalog.
Model steps
- Use only parameter ids from the model's Tool/Detail.
- Set every parameter you care about. A parameter you leave out takes the model's default from Tool/Detail. To leave a file parameter empty, set it to
[], or""for a single file. - A single file parameter takes one URL string. A combined file parameter (
combinefileinput) takes an array, even for one file. A multi-file parameter (multifileinput) takes its URLs comma-separated in its matching...UrlMultiplefield. - Take each value, such as a duration, a size or an option, from the model's schema in Tool/Detail.
- Training models cannot be used in workflows.
A minimal workflow
One text input, one image model and one result. Replace owner/model with a real model and prompt with that model's text parameter id.
{
"version": "1",
"nodes": {
"node-image": {
"id": "node-image", "type": "run", "tool": "owner/model", "depends": ["input"],
"input": { "prompt": "$input.prompt" },
"metadata": { "position": { "x": 350, "y": 0 } }
},
"output": {
"id": "output", "type": "display", "depends": ["node-image"], "input": {},
"fields": { "image": "$node-image.outputs" },
"metadata": { "position": { "x": 700, "y": 0 } }
}
},
"output": { "image": "$node-image.outputs" },
"schema": {
"input": {
"prompt": { "label": "Prompt", "type": "string", "defaultValue": "", "ui": { "field": "textarea" } }
},
"output": {}
},
"metadata": { "input": { "position": { "x": 0, "y": 0 } } }
}
To turn that image into a video, add a second model step that reads the first step's file and a motion Start field:
"node-video": {
"id": "node-video", "type": "run", "tool": "owner/video-model",
"depends": ["input", "node-image"],
"input": { "inputImage": "$node-image.outputs", "prompt": "$input.motion" },
"metadata": { "position": { "x": 700, "y": 0 } }
}
Then set the End node's "depends": ["node-video"] and "fields": { "video": "$node-video.outputs" }, copy those fields to the top-level output, and move the End node to "x": 1050. inputImage stands for the video model's image parameter: check its real id in the model's schema.
How a Run Works
Workflow/Run answers at once with a run token, the workflowtoken; the steps run after that. Read the run with Workflow/RunDetail until its status is final.
- Only the steps that lead to the End node run. Steps run in layers: a step that depends on no other step is in the first layer, and any other step is one layer after the latest of the steps it depends on. The steps of a layer start together, and the next layer starts once every step of the current one has finished.
- When a step fails, every step in a later layer is skipped, on every branch, and the run ends as
failed. - Check the expected cost (see Costs) before you start a run.
- The run belongs to the caller's workspace and is paid from that workspace's wallet, also when the workflow is a public one from another workspace.
Run statuses
| Status | Meaning |
|---|---|
running |
Steps are queued or running. |
completed |
Every step finished. The End node's fields hold the results. |
failed |
A step failed, and the steps after it were skipped. |
stopped |
The run reached its breakpoint. Continue it with RunResume. |
cancelled |
One of the run's steps was cancelled. |
A step is pending, running, completed, failed, cancelled or aborted (skipped because an earlier step failed). A failed step's cause is tool-error (the model refused its inputs or the task failed; error says why), poll-timeout (the step ran past 4 hours and was not charged), spend-limit-reached (a spend limit refused the step before it started; error holds the limit's message), or another short code.
Breakpoints
To test the first steps, start the run with breakpointNodeId. The run executes every layer up to and including the one that holds that step, then ends as stopped, and the steps after it stay pending. The breakpoint must be a step the run executes and cannot be in the last layer. Only people who can edit the workflow can set one. Check the outputs, then continue with RunResume, to the end or to a later breakpoint.
Resuming
RunResume continues a failed or stopped run on the same workflowtoken. Completed steps keep their outputs and are not charged again. Failed, skipped and not yet run steps run again as new tasks, billed to the wallet that paid for the run.
A resume runs the remaining steps exactly as the run started them, with the same inputs and settings: changes saved to the workflow since then apply to new runs only. So resume after a temporary failure, such as a timeout or a model that asked to try again later. An error about a parameter value, a file or a limit such as duration or size comes from the inputs or the settings: fix them and start a new run.
Costs
- Saving, reading, preparing, cloning and deleting workflows is free.
- Nothing is charged when a run starts. Each model step is a normal model task, billed when it finishes successfully at that model's price. Failed steps are not charged, and utility steps are free.
- To start, the wallet must hold $0.50 for each model step the run will execute (up to the breakpoint, when one is set). Otherwise the run is refused with code
97,Insufficient balance. The concurrency limit also applies (code96). - The expected cost of a run is the sum of the model prices for the settings each step uses, from Tool/Detail. A run's
totalcostshows the list price of the steps finished so far, and once the run has endedchargedcostanddiscountamountshow what the wallet paid.chargedcostisnullwhile a step's charge is still settling. - The workspace's spend limits apply when a run starts or resumes, and again before each step starts. A run is refused with code
93when its known price would go over a limit that covers it, or once that limit has no room left. Each step is checked the same way with its own price, and holds that price until it is charged. A step a limit refuses fails with causespend-limit-reached, and the run ends asfailed: resume it with RunResume once the limit allows. - The workspace's Model Access rules apply when a run starts or resumes: when a rule blocks the model of a step that will run, the run is refused with code
92before anything runs, and the message names that model. When the workflow's steps are hidden from you, as on a protected workflow from another workspace, the message names your rule but not the model, for exampleYour account can't use one of the models this workflow runs. Model Access rules decide which models can run.Steps that will not run, such as the steps after a breakpoint, are not checked.
POST /Workflow/List
Lists the workflows of the key's workspace, or searches the public gallery.
| Parameter | Type | Required | Description |
|---|---|---|---|
scope |
string | No | "my" (default) for the key's workspace, "public" for the public gallery. |
search |
string | No | Text to look for in the slug, title, description or tags. |
sort |
string | No | my: createtime (default), updatetime or title. public: createtime (default), runcount, likecount, clonecount or ratingscore. |
order |
string | No | DESC (default) or ASC. |
start |
number | No | Offset for paging. Default 0. |
limit |
number | No | Rows per page. my: default 20, maximum 1000. public: default 50, maximum 200. |
ispublic |
string | No | my only: "0" for private workflows, "1" for workflows submitted to the gallery. |
tags |
array | No | public only: workflows with any of these tags, up to 20. |
model |
string | No | public only: workflows that use this model, as "owner/model". |
onlyfavorites |
string | No | public only: "1" for the workflows you liked. |
toolpreview |
string | No | public only: "1" adds toolitems, the models each workflow uses with their titles and covers. |
The response is { "result": true, "errors": [], "workflow": [...], "total": 1 }. In your workspace (my), a personal key lists your own workflows and a team key lists every workflow of the team.
| Field | Description |
|---|---|
id |
The workflow's numeric id. |
slug, slugid |
The full slug is <slug>-<slugid>. |
title, description, tags, cover |
The workflow's details. |
ispublic |
1 when the workflow was submitted to the gallery. |
status |
null when never published, 1 waiting for review, 2 listed in the gallery, 3 rejected. |
isprotected |
1 when the steps are hidden from people outside the owner's workspace. |
clonedfromid |
On a clone, the id of the workflow it was copied from. |
stepcount, toolcount, utilitycount |
The number of steps, model steps and utility steps. |
teamname |
The team the workflow belongs to, if any. |
runcount, likecount, clonecount, ratingaverage, ratingcount, commentcount |
Gallery counters. runcount counts runs while the workflow is listed. |
createtime, updatetime |
Unix seconds. Pass updatetime to Update as loadedUpdatetime. |
Gallery rows (public) also carry tools (the models the workflow uses; null on a protected workflow) and user (username, avatar) for the creator.
Response
{
"result": true,
"errors": [],
"workflow": [
{
"id": 1842,
"slug": "product-ad",
"slugid": "a1B2c",
"title": "Product ad",
"description": "Turns a product photo into a short ad video",
"tags": ["ads", "video"],
"cover": null,
"ispublic": 0,
"status": null,
"isprotected": 0,
"clonedfromid": null,
"stepcount": 2,
"toolcount": 2,
"utilitycount": 0,
"teamname": null,
"runcount": 0,
"likecount": 0,
"clonecount": 0,
"ratingaverage": null,
"ratingcount": 0,
"commentcount": 0,
"createtime": "1761901200",
"updatetime": "1761901200"
}
],
"total": 1
}
POST /Workflow/Detail
Returns one workflow with its graph.
| Parameter | Type | Required | Description |
|---|---|---|---|
slug |
string | Yes | The full slug, such as product-ad-a1B2c. |
The response is { "result": true, "errors": [], "workflow": [ { ... } ] }: the fields of List plus contents, the graph as an object (see The Workflow Graph). Its schema.input lists the inputs a run takes, and metadata.input.values the saved values.
requiredinputslists the Start fields a run must be given: the ones used by the End node or by a step leading to it that have no saved value and no default. An empty array means a run needs no input. Read this list to decide what to ask for; a field'srequiredflag inschema.inputdoesn't decide it. On a protected workflow from another workspace, a run doesn't use the creator's saved values, so only a default takes a field off the list.- A workflow from your workspace, or one published in the gallery, can be read. A private workflow of another workspace answers
This workflow does not belong to your current workspace.orYou don't have any permission for this action., and a clone can only be read by its owner's workspace. - A protected workflow read from outside its owner's workspace comes back with its steps removed:
contentskeeps only the Start fields and the End node, andestimatedcostgives an estimate of one run,{ "type": "estimated", "value": 0.42 }("unavailable"withvalue: nullwhen it cannot be estimated). rejectreasonis present only for the workflow's own workspace: on a rejected workflow it says why.- A deleted or unknown workflow answers
Workflow not found.
Saved Start values are part of the workflow: everyone who can read it sees them, the gallery too once it is published, and clones keep them. Never save a key, token or password there. Model steps are billed to the Wiro wallet and need no key from the model's provider.
POST /Workflow/Prepare
Prepares a graph you wrote for saving, the way the Wiro editor does: it checks every step against the live model catalog, fills each model parameter you left out with its default, completes the Start fields and the End node, and lays the steps out. It writes and charges nothing. Prepare the graph, then save the prepared contents with Add or Update.
| Parameter | Type | Required | Description |
|---|---|---|---|
contents |
object | Yes | The graph, as an object or a JSON string. |
mode |
string | No | "create" (default) lays every step out again, for a new workflow. "apply" keeps the positions you sent, for a change to an existing workflow; every step then needs a numeric position. |
anchorNodeIds |
array | No | apply only: step ids ("input" for Start, "output" for End) that keep their exact positions; the other steps move down until nothing overlaps. |
On success, contents is the prepared graph. On failure, result is false and issues lists every problem at once, each { code, message, nodeId, input }: nodeId is the step ("input" for a Start field, "output" for an End field) and input the parameter or field. warnings can come back either way; required-input-missing means a Start field a step uses has no default, so every run must send a value for it.
{
"result": false,
"errors": [{ "code": 0, "message": "...", "time": 1761901200 }],
"issues": [
{ "code": "unknown-input", "message": "...", "nodeId": "node-image", "input": "promt" },
{ "code": "contents-too-large", "message": "Workflow JSON exceeds the 40960-byte limit.", "bytes": 52114, "limit": 40960 }
],
"warnings": []
}
Common issue codes: tool-not-found and tool-not-marketplace (the model does not exist or is not public), unknown-input (a parameter id the model does not have), unknown-input-reference, unknown-node-reference and reference-missing-dependency (a reference to a missing Start field or step, or one not listed in depends), embedded-workflow-reference (a reference inside longer text), file-input-not-array and single-file-only (one file where an array is needed, or the reverse), request-parameter-required (a required model parameter has no value), param-out-of-bounds, cycle-detected, workflow-has-no-reachable-nodes, duplicate-end-reference, and contents-too-large or prepared-contents-too-large with bytes and limit.
Prepare fills every model parameter you leave out with the model's default: compare the prepared step inputs with what you sent, and set or empty the ones you did not mean to keep.
POST /Workflow/Add
Saves a new, private workflow in the key's workspace.
| Parameter | Type | Required | Description |
|---|---|---|---|
title |
string | Yes | The workflow's title. If the workspace already has a workflow with this title, a number is added, such as Product ad-2. |
slug |
string | Yes | The title part of the slug: lowercase letters, digits and dashes, such as product-ad. Wiro adds the 5-character slugid. |
contents |
string | Yes | The prepared graph as a JSON string. |
description |
string | No | What the workflow does and what people should put in its inputs. |
tags |
string | No | A JSON string of an array of tags, such as "[\"ads\",\"video\"]". Tags that start with wiro- are reserved. |
The response is { "result": true, "errors": [], "workflow": [ { ... } ] } with the saved workflow, including its slugid and updatetime. Add checks that every model and utility exists; run the graph through Prepare first, which checks the references, the inputs and everything else a run needs.
POST /Workflow/Update
Changes a workflow of the key's workspace.
| Parameter | Type | Required | Description |
|---|---|---|---|
slug |
string | Yes | The full slug. |
title |
string | No | A new title. |
description |
string | No | A new description. |
tags |
string | No | A JSON string of the new tag array. Keep any wiro- tags the workflow already has. |
contents |
string | No | A new graph as a JSON string, prepared with mode: "apply". It replaces the old one. |
loadedUpdatetime |
string | No | The updatetime you read. If someone saved the workflow since then, nothing is written. |
force |
boolean | No | true saves even when loadedUpdatetime no longer matches. |
input |
object | No | Protected clones only: new saved values for the Start fields, by key. |
Title and description are changed only when you send a non-empty value. The response holds the workflow after the change, with its new updatetime.
- Concurrent edits. When
loadedUpdatetimeno longer matches, the update is refused withThis workflow was modified by another user. Reload to see latest changes or save to overwrite.and the response carriescurrentUpdatetime. Read the workflow again and redo the change on top, or sendforce: trueto overwrite. - Published workflows. Changing the title, description, tags or graph of a workflow in the gallery sends it back to review, and it leaves the gallery until it is approved again.
- Clones. A clone of a protected workflow keeps its steps hidden: you can change its title, description and tags, and its saved Start values with
input, but not itscontents. - When a new graph stops using files that were uploaded into the workflow in the wiro.ai editor, those files are deleted, unless a past run or a clone still uses them.
POST /Workflow/Clone
Copies a workflow from the public gallery into the key's workspace.
| Parameter | Type | Required | Description |
|---|---|---|---|
slug |
string | Yes | The full slug of a workflow listed in the gallery. |
The copy is private and free. It keeps the graph and the saved Start values; a taken title becomes Title-Clone. The response holds the new workflow, without contents: read it with Detail. Each call makes another copy.
- Only a workflow listed in the gallery can be cloned (
This workflow cannot be cloned), and not into the workspace it already belongs to (This workflow already belongs to this workspace). - A clone can never be published or cloned again, and only its own workspace can read it.
- A clone of a protected workflow keeps its steps hidden from everyone, its owner included. It can still be run.
POST /Workflow/Delete
Deletes a workflow of the key's workspace. It leaves every list and the gallery and can no longer be run or read. Runs already started finish, and clones keep working.
| Parameter | Type | Required | Description |
|---|---|---|---|
slug |
string | Yes | The full slug. |
The response is { "result": true, "errors": [], "workflow": [] }. There is no undo.
POST /Workflow/Run
Starts a run and answers at once with its token.
| Parameter | Type | Required | Description |
|---|---|---|---|
slug |
string | Yes | The full slug. |
input |
object | No | Values for the Start fields, keyed as in schema.input: strings, numbers, booleans or arrays. Files are public URLs. A field you leave out uses its saved value, then its default. |
breakpointNodeId |
string | No | A step id to stop after (see Breakpoints). |
{
"result": true,
"errors": [],
"workflowtoken": "Lk3vQ9xT2mWc7Rp4Yh8Nd1Fs6Gb0Zj"
}
- Your own workspace's workflows and the workflows listed in the gallery can be run. On a protected gallery workflow from another workspace, a field you leave out uses its default, not the creator's saved value.
- An unknown input key is refused with
Unknown input field(s): <keys>. Check your workflow's Start Node schema for valid field names., and a Start field that a step needs and that has no value is refused withA required input value is missing: <key>. - Missing inputs and broken references are all returned at once, and nothing is charged for a refused run.
- File inputs are fetched from public http(s) URLs, up to about 100 MB each.
POST /Workflow/RunDetail
Returns a run and its steps. Call it until status is completed, failed, stopped or cancelled.
| Parameter | Type | Required | Description |
|---|---|---|---|
workflowtoken |
string | Yes | The run token. |
The response has workflowrun and workflowrunnodes. Runs are private: the person who started a run can read it, and in a team workspace every member of the team can.
workflowrun field |
Description |
|---|---|
workflowtoken, workflowslug |
The run token and the workflow's full slug. |
status |
running, completed, failed, stopped or cancelled. |
outcome |
The final status, once the run has ended. |
canresume |
true when you can continue this run with RunResume. |
breakpointnodeid |
The breakpoint in effect, or null. |
contents |
The graph as this run started it, with the Start values it used. |
totalcost |
The list price of the steps finished so far, in USD. |
chargedcost, discountamount |
Once the run has ended: what the wallet paid and the discount. null while a charge is still settling. |
startedAt |
Start time in milliseconds. resumedAt is added when the run was resumed. |
elapsedseconds |
Running time, summed over resumes. |
failedNodeCount, abortedNodeCount, cancelledNodeCount |
Step counts. |
workflowrunnodes field |
Description |
|---|---|
nodeId, tool, kind |
The step id, its model or utility, and tool or utility. |
layerIdx |
The step's layer, from 0. |
status |
pending, running, completed, failed, cancelled or aborted. |
cause, error |
Why the step did not complete. |
tasktoken |
For a model step that started a task. Pass it to RunNodeDetail. |
outputs |
A model step's results: files with url, name, contenttype and size, or an LLM's reply as { "contenttype": "raw", "content": { "answer": [...] } }. A utility step's ports, such as { "result": [...] }. A file entry carries no path or mntpath: use its url. |
elapsedseconds |
How long the step ran. |
To find a run's results, read the End node's fields in contents and take the outputs of the steps they reference.
When the workflow's steps are hidden from you, as on a protected workflow from another workspace, the run comes back with graphmasked: true: contents shows only the Start fields and the End node, and workflowrunnodes holds only the steps the End node shows, with their status and outputs.
Response
{
"result": true,
"errors": [],
"workflowrun": {
"workflowtoken": "Lk3vQ9xT2mWc7Rp4Yh8Nd1Fs6Gb0Zj",
"workflowslug": "product-ad-a1B2c",
"status": "completed",
"outcome": "completed",
"breakpointnodeid": null,
"startedAt": 1761902400000,
"elapsedseconds": 74,
"totalcost": "0.84",
"chargedcost": "0.84",
"discountamount": "0",
"failedNodeCount": 0,
"abortedNodeCount": 0,
"cancelledNodeCount": 0,
"contents": { "...": "..." }
},
"workflowrunnodes": [
{
"nodeId": "node-image",
"tool": "google/nano-banana-pro",
"kind": "tool",
"layerIdx": 0,
"status": "completed",
"cause": null,
"error": null,
"tasktoken": "Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op",
"outputs": [
{
"url": "https://cdn1.wiro.ai/5e8d7a1c/product.png",
"name": "product.png",
"contenttype": "image/png",
"size": "1843212"
}
],
"elapsedseconds": 31
},
{
"nodeId": "node-video",
"tool": "klingai/kling-v3",
"kind": "tool",
"layerIdx": 1,
"status": "completed",
"cause": null,
"error": null,
"tasktoken": "Qr56St78Uv90Wx12Yz34Ab56Cd78Ef",
"outputs": [
{
"url": "https://cdn1.wiro.ai/9b2f4e6a/ad.mp4",
"name": "ad.mp4",
"contenttype": "video/mp4",
"size": "6200412"
}
],
"elapsedseconds": 43
}
]
}
POST /Workflow/RunNodeDetail
Shows what one model step received and returned, to debug a failed step.
| Parameter | Type | Required | Description |
|---|---|---|---|
tasktoken |
string | Yes | The step's tasktoken from RunDetail. |
The response's workflowrunnode has the step's RunDetail fields plus taskDetail: the parameters the model received, its debugoutput, taskStatus, and modelslugowner and modelslugproject. Utility steps have no task to read. When the workflow's steps are hidden from you, it answers You don't have any permission for this action.
POST /Workflow/RunHistory
Lists runs, newest first. A personal key lists your own runs; a team key lists the runs of every member of the team. Runs started on wiro.ai are included.
| Parameter | Type | Required | Description |
|---|---|---|---|
start |
number | No | Offset. Default 0. |
limit |
number | No | Default 20, maximum 1000. |
status |
string | No | running, completed, failed, stopped or cancelled. |
search |
string | No | Text in the workflow's title, or its slug without the 5-character id: product-ad finds the runs of product-ad-a1B2c. |
workflowid |
number | No | Only the runs of this workflow id. |
sort |
string | No | id (default), starttime, status or totalcost. |
order |
string | No | DESC (default) or ASC. |
The response is { "result": true, "errors": [], "workflowruns": [...], "total": 12 }. Each row has the workflowrun fields of RunDetail without contents, plus workflowid, workflowtitle, teamname and nodes, each step's { nodeId, tool, kind, layerIdx, status }. To read a run's outputs, call RunDetail with its token.
POST /Workflow/RunResume
Continues a failed or stopped run on the same token. See Resuming.
| Parameter | Type | Required | Description |
|---|---|---|---|
workflowtoken |
string | Yes | The run token. |
breakpointNodeId |
string | No | A new breakpoint. Send null to run to the end. Leave the field out and a failed run keeps the breakpoint it started with, while a stopped run runs to the end. |
The response is { "result": true, "errors": [], "workflowtoken": "..." }; follow the run with RunDetail again.
- The person who started the run can resume it after a failure. Continuing a stopped run, and setting a breakpoint, needs someone who can edit the workflow; in a team workspace any such member can.
- The balance check runs again for the steps that will run.
This run is already resuming or still wrapping up. Try again in a momentandA step of this run is still finishing. Try again in a few minutesmean an earlier step is still settling: wait a few minutes and try once more.- Any other status is refused with
Only a failed or stopped run can be resumed.
POST /Workflow/UtilityDetail
Returns a built-in utility's parameters and output ports, in the same shape as a model's parameters in Tool/Detail.
| Parameter | Type | Required | Description |
|---|---|---|---|
slug |
string | Yes | workflow-utilities/output-filter, workflow-utilities/merge-text or workflow-utilities/split-text. |
The response's utility holds one entry with slug, title, description, parameters (groups of parameter definitions with id, type, label, defaultvalue, options, minvalue and maxvalue) and outputs, the ports, each { id, label, type }.
Errors
Business errors come back with HTTP 200, result: false and an errors array, as everywhere in the Wiro API. The ones you will see most:
| Message | Code | When |
|---|---|---|
Workflow not found |
0 | An unknown or deleted workflow. |
This workflow does not belong to your current workspace. |
0 | A private workflow of another workspace. Use a key from a project in the workflow's workspace. |
You don't have any permission for this action. |
0 | The key's project creator has no rights on this workflow or run. |
You must be a member of this team to perform this action |
0 | A team project's key whose creator is no longer a member of the team. |
slug has invalid format |
0 | Not a full slug ending in a dash and a 5-character id. |
invalid json for contents param. |
0 | Add or Update with contents that is not a JSON string. |
Contents do not match the expected workflow structure. |
0 | A graph without the required shape (see The Workflow Graph). |
This tool in the workflow was not found: <slug> |
0 | A step's model does not exist. |
Tags that start with wiro- are reserved for Wiro |
0 | Add or Update with a wiro- tag. |
This workflow was modified by another user. Reload to see latest changes or save to overwrite. |
0 | Update with an outdated loadedUpdatetime; the response adds currentUpdatetime. |
This workflow cannot be cloned |
0 | Clone of a workflow that is not listed in the gallery. |
Unknown input field(s): <keys>. Check your workflow's Start Node schema for valid field names. |
0 | Run with an input key the workflow does not have. |
A required input value is missing: <key>. |
0 | Run without a value for a Start field a step needs. |
Workflows cannot include train tools as they take days to complete |
0 | A step uses a training model. |
Insufficient balance |
97 | The wallet holds less than $0.50 per model step that will run. |
You have reached your concurrent task limit... |
96 | See Concurrency Limits. |
Only people who can edit this workflow can stop a run at a step |
0 | breakpointNodeId from someone who cannot edit the workflow. |
There is no workflow run yet. |
0 | An unknown run token. |
Only a failed or stopped run can be resumed |
0 | RunResume on a run that is running or completed. |
Authentication errors are listed in the Error Reference.
Workflow Agent
Design and edit Wiro workflows by chat: describe the job, read the agent's proposals and save the one you want.
Overview
The Workflow Agent is a Wiro chat agent that designs and edits workflows. It looks up current models and utilities in the Wiro catalog and replies with an explanation and zero or more proposed workflows. It never saves, changes or runs anything itself: your application saves a proposal with the Workflows endpoints and runs it there.
The Workflow Agent runs on one setup shared by everyone who uses it, so it never changes that setup: it proposes no setup cards, and its connectors, skills and scheduled tasks are fixed. Asked for a standing rule or a recurring job, it helps with the request once, as a one-time task.
The Workflow Agent API uses the message protocol of Agent Messaging on its own routes under /StudioWorkflow/:
- Send a brief with Message/Send. Attach a workflow in
workflowContextto have it edited. - Follow the turn on the Agent WebSocket with the
agenttoken, or poll Message/Detail until it ends. - Read the proposals from the reply (see Proposals) and save the one you want with Workflow/Add, or onto the attached workflow with Workflow/Update.
A question the catalog answers, such as which model is cheapest for a job, needs no turn: Tool/List and Tool/Detail answer it for free. When you already know the graph, write it yourself and save it with Workflow/Add.
Authentication
Every /StudioWorkflow/* route takes a project API key: x-api-key, plus x-nonce and x-signature for a project that uses signature authentication (see Authentication). A key acts as the person who created its project, in that project's workspace. For a team project, that person must still be a member of the team; otherwise every route answers HTTP 403 with You must be a member of this team to perform this action.
Sessions
A session is one conversation with its own memory. sessionkey names it, and "default" is used when you leave it out.
- Sessions started with an API key belong to that key's project. Everyone who uses the key shares them, and they are separate from the Workflow Agent chats on wiro.ai and from other projects' sessions. Each project has its own
"default"session. - A session name uses letters, digits,
.,_,:and-, without:cron:, up to 100 characters. Any other name is refused withsessionkey has invalid format. - Use one session per task and keep using it to refine its proposals; start a new one for an unrelated task.
- The turns of one session run one at a time. A project can have at most 2 turns queued or running at once through its API key; a third message is refused with
This project already has 2 Workflow Agent replies in progress. Wait for one to finish before sending another message.
Costs
- $10 to start a turn. Send and SendForm need at least $10 spendable in the wallet of the key's workspace. Below that, the message is refused with code
97(Insufficient balance), withwalletUsdandminTopupin the response, and nothing is charged. - Chat. Each turn is charged after it ends for the tokens it used, at the chat model's rates in StudioWorkflow/Status (credits per 1M tokens; 1 credit is $0.01). The reply's
tokencostshows the charge in credits:tokencost / 100is the amount in USD. - Spend limits and Model Access. The chat counts toward your workspace's spend limits, and its chat model follows your Model Access rules: the account's or the team's, your own in a team, and those of the API key and the surface you sent the message with. A message whose chat model a rule blocks is refused with code
92before anything runs. - The agent only reads the catalog, so its turns start no model runs. Saving a proposal is free, and running the saved workflow is billed like any workflow run.
- StudioWorkflow/Transactions lists the charges.
POST /StudioWorkflow/Status
Returns the wallet check and the chat models the agent can use, after settling your pending Workflow Agent charges. It takes no request fields, and its fields are the same as Studio/Status: walletUsd, needsTopup, minTopup (10), tokenRates, agentModel.chatModel, blockedModels, agentModelBlocked and agentModelMessage. title is "Workflow Agent".
POST /StudioWorkflow/Message/Send
Sends a message to the Workflow Agent and returns at once with the turn's messageguid and agenttoken.
| Parameter | Type | Required | Description |
|---|---|---|---|
message |
string | Yes | The brief, at most 16 KB (UTF-8). Say what the workflow should do, what people will give it as input and which results they want back. Pass on limits such as budget, speed, quality or a model. |
sessionkey |
string | No | The session. Defaults to "default", the project's main session. |
model |
string | No | The chat model for this turn: a slug whose selectable is true in StudioWorkflow/Status. Leave it out to use the default chat model, agentModel.chatModel. A chat model your Model Access rules block is refused with code 92, the default included. |
workflowContext |
object | No | A workflow for the agent to edit, at most 40 KB of JSON. See Editing a workflow. |
Response
{
"result": true,
"errors": [],
"messageguid": "0b7f2c1e-5d4a-4c3b-9a8f-1e2d3c4b5a69",
"agenttoken": "Qm7Tz2LpX9vKc4RwN8yHa3JdF6sGb1",
"status": "agent_queue"
}
If a request times out, check Message/History before you send it again: each accepted message starts a paid turn.
POST /StudioWorkflow/Message/SendForm
The same as Send, as multipart/form-data, to attach files such as a sample image or a brief as a PDF.
| Parameter | Type | Required | Description |
|---|---|---|---|
message |
string | Conditional | The brief, at most 16 KB. Required unless a file is attached. |
sessionkey |
string | No | The session. |
model |
string | No | As in Send. |
workflowContext |
string | No | The same object as in Send, as a JSON string. |
attachments |
file | No | Repeat the attachments field once per file; a single file can also be sent as attachment. |
Up to 8 files per message, each up to 50 MB (File too large (max 50MB): <name>). The accepted types are the same as for Studio.
POST /StudioWorkflow/Message/Detail
Returns one message and its reply.
| Parameter | Type | Required | Description |
|---|---|---|---|
messageguid |
string | Conditional | The message id. Required unless agenttoken is given. |
agenttoken |
string | Conditional | The turn token. |
sessionkey |
string | No | The message's session. Defaults to "default". A message from another session or another project is Message not found. |
The reply fields are those of Studio's Message/Detail: status, content, response, debugoutput, timeline, attachments, model, the token counts, tokencost, createdat, startedat and endedat, plus sessionkey. The proposals are in response once status is agent_end.
POST /StudioWorkflow/Message/History
Returns the messages of one session, newest first: sessionkey, limit (default 50, maximum 200) and before (a message guid, for the next page). The response is { "data": { "messages": [...], "count": 2, "hasmore": false } }. A proposal in an earlier reply can still be saved later.
POST /StudioWorkflow/Message/Sessions
Lists the sessions of the key's project, most recent first, each with sessionkey, messagecount, updatedat, lastmessage and an optional name. "default" is always listed. It takes no request fields.
POST /StudioWorkflow/Message/Cancel
Stops a turn that is queued or running (messageguid or agenttoken, and sessionkey). Only a message in agent_queue, agent_start or agent_output can be cancelled. Tokens the turn already used are charged.
POST /StudioWorkflow/Message/ClearSession
Deletes the session's messages and starts the agent's memory of it fresh. The session keeps its display name. It works on "default" too.
| Parameter | Type | Required | Description |
|---|---|---|---|
sessionkey |
string | No | The session. Defaults to "default". |
POST /StudioWorkflow/Message/DeleteSession
Deletes a session: its messages, its display name and the agent's memory of it. Send the sessionkey of the session to delete; "default" cannot be deleted (The main session cannot be deleted.), so clear it with ClearSession. Workflows you saved are not affected.
POST /StudioWorkflow/Message/RenameSession
Sets a session's display name: name (required, up to 40 characters) and sessionkey.
POST /StudioWorkflow/Transactions
Lists your Workflow Agent charges in the key's workspace, newest first (limit, default 50, maximum 200). Each row has guid, type, amount, description, modelid, taskid, confirmed and time; a chat charge is described as Workflow Agent LLM <model> (...) with its token counts.
Editing a workflow
To have the agent change a workflow, read it with Workflow/Detail and send it with the message as workflowContext:
{
"message": "Add an upscale step after the image and return both images",
"sessionkey": "product-ad-edit",
"workflowContext": {
"protocolVersion": 1,
"source": {
"slug": "product-ad",
"slugid": "a1B2c",
"fullSlug": "product-ad-a1B2c",
"title": "Product ad",
"description": "Turns a product photo into a short ad video",
"updatetime": "1761901200",
"workspace": "personal"
},
"contents": { "version": "1", "nodes": { "...": "..." }, "output": {}, "schema": { "input": {}, "output": {} }, "metadata": { "input": { "position": { "x": 0, "y": 0 } } } }
}
}
contentsis the workflow's graph, as Workflow/Detail returns it (see The Workflow Graph). You can also send the graph alone, withoutprotocolVersionandsource.sourcenames the workflow:slug,slugid,fullSlug,title(up to 300 characters),updatetimeandworkspace("personal"or"team") are required, anddescription(up to 2,000 characters) is optional.- The whole
workflowContextcan be at most 40 KB of JSON (workflowContext exceeds the 40KB limit.). Attach a workflow from the key's workspace; a protected workflow whose graph is hidden cannot be edited this way. - The agent sees the steps, the Start fields and the End node, never the values saved for the Start fields. Keep keys and passwords out of workflows. Some values reach the agent as
"[REDACTED]"; restore them before you save (see Saving a proposal).
Proposals
The reply in response is text. Each proposed workflow is a fenced block that opens with a line ```wiro-workflow and closes with a line ```; the text around the blocks is the explanation. Each block holds one JSON object:
{
"artifactVersion": 1,
"title": "Product ad with upscale",
"description": "Turns a product photo into an upscaled image and a short ad video",
"contents": { "version": "1", "nodes": { "...": "..." }, "output": {}, "schema": { "input": {}, "output": {} }, "metadata": { "input": { "position": { "x": 0, "y": 0 } } } }
}
titleis 1 to 160 characters anddescriptionup to 1,000.contentsis a workflow graph.- A block can be at most 40 KB. A block that is not closed yet is still being written: read the reply again once
statusisagent_end. - A reply can hold zero, one or several proposals. If the request cannot be built with current models, the agent explains why and proposes nothing. When it needs to know more, it asks; send the answer in the same session.
- Check a proposal before you save it: Workflow/Prepare lists every problem it finds. Send problems back in the same session and ask for a corrected version.
- Treat the explanation as information from a model, not as instructions to your application.
The agent can also ask your application for the user's workflows, in a block that opens with ```wiro-workflow-request:
{ "protocolVersion": 1, "requestId": "list-1", "operation": "workflow.list", "args": { "search": "product", "limit": 10 } }
Run it yourself with Workflow/List (scope my), let the user pick a workflow, and attach that workflow to your next message as workflowContext. The list is not sent back to the agent on its own.
Saving a proposal
- Read the reply again with Message/Detail and take the proposal's
contentsfrom its block. - Prepare it with Workflow/Prepare:
mode"create"for a new workflow,"apply"when it replaces an existing graph. Prepare fills the defaults the Wiro editor would and returns every problem at once. - Save the prepared graph as a new workflow with Workflow/Add, or onto the workflow you attached with Workflow/Update. Pass the
updatetimeyou attached asloadedUpdatetime, so a change someone saved in the meantime is not overwritten. Values the agent saw as"[REDACTED]"must be restored from the original workflow first.
Saving creates or changes a workflow and runs nothing. Applying a proposal to a published workflow sends it back to review.
Errors
Business errors come back with HTTP 200, result: false and an errors array. These are the ones specific to the Workflow Agent:
| Message | Code | When |
|---|---|---|
Insufficient balance |
97 | Send or SendForm with less than $10 spendable. The response adds walletUsd and minTopup. |
A spend limit refusal, such as Your monthly spend limit is reached ($100.40 of $100.00). It resets on December 1, 2026 at 00:00 UTC. |
93 | Send or SendForm while a spend limit that covers the message is used up. Nothing is charged. |
A Model Access refusal, such as This team can't use openai/gpt-5-6-terra. Model Access rules decide which models can run. |
92 | Send or SendForm when a Model Access rule that covers the message blocks its chat model: the model it names, or the default chat model when it names none. It is checked before the balance and the spend limits. Nothing is sent or charged. |
Request parameter [message] required |
0 | No message, and no file on SendForm. |
message exceeds the 16KB limit. |
0 | The message is longer than 16 KB. |
sessionkey has invalid format |
0 | A session name with other characters, :cron:, or more than 100 characters. |
workflowContext exceeds the 40KB limit. |
0 | The attached workflow is too large. |
workflowContext must be a WorkflowContents object., workflowContext must be valid JSON data., workflowContext protocolVersion must be 1., workflowContext source has an invalid shape., workflowContext has an invalid WorkflowContents shape. |
0 | The workflowContext does not have the shape described above. |
This project already has 2 Workflow Agent replies in progress. Wait for one to finish before sending another message. |
0 | A third turn while two of the project's turns are queued or running. |
Invalid model: <model> is not in the selectable model allowlist. |
0 | model is not one of the chat models the Workflow Agent offers. A model your Model Access rules block gets code 92 instead. |
Too many files (max 8), File too large (max 50MB): <name> |
0 | SendForm attachment limits. |
Message not found |
0 | Detail or Cancel with an unknown message, or one from another session or project. |
The main session cannot be deleted. |
0 | DeleteSession on "default". |
Agent is temporarily unavailable. Please try again shortly. |
0 | Try again shortly. |
You must be a member of this team to perform this action |
HTTP 403 | A team project's key whose creator is no longer a member of the team. |
Authentication errors are listed in the Error Reference.
Studio
Ask Wiro's creative agent for images, video, audio and more through the API, then collect every result it made.
Overview
Studio is Wiro's creative agent. You describe what you want, such as a product shot, a short video, a voice-over or a set of ad banners, and Studio picks suitable models from the Wiro catalog, runs them and replies with the results. It is the same Studio you use on wiro.ai.
The Studio API uses the message protocol of Agent Messaging on its own routes under /Studio/:
- Send a message with Message/Send and get its
messageguidandagenttokenback at once. - Follow the turn on the Agent WebSocket with the
agenttoken, or poll Message/Detail until the turn ends. - Collect the files. The reply lists them, and Studio/Tasks returns every model run Studio started for you, with its outputs and cost.
There is no agent guid to pass: every route talks to Studio. Studio is paid from your Wiro wallet, as described under Costs.
Studio runs on one setup shared by everyone who uses it, so it never changes that setup: it proposes no setup cards, and its connectors, skills and scheduled tasks are fixed. Asked to remember a rule or to repeat a job on a schedule, it helps with the request once, as a one-time task.
Authentication
Every /Studio/* route takes a project API key: x-api-key, plus x-nonce and x-signature for a project that uses signature authentication (see Authentication). A key acts as the person who created its project, in that project's workspace: a personal project works in the personal workspace and pays from the personal wallet, a team project works in the team and pays from the team wallet. For a team project, that person must still be a member of the team; otherwise every route answers HTTP 403 with You must be a member of this team to perform this action.
Sessions
A session is one conversation with its own memory. sessionkey names it, and "default" is used when you leave it out.
- Studio conversations belong to the person who created the key's project.
"default"is their main Studio chat on wiro.ai, and sessions started with a key appear in their Studio on wiro.ai, in the same workspace. Everyone who uses the same key shares these sessions. - Use a new session name for each piece of work, such as
"bakery-banners", and keep using it for follow-ups such as "make it brighter": Studio remembers the conversation. - A name uses letters, digits,
.,_,:and-, up to 128 characters, and can't end in-rfollowed by a number, such as-r2. Names that contain:cron:are reserved. - Capitals are fine and are kept, but a new name that differs only in capitals from one of your sessions is refused: use its exact name, or another name.
- Message/Send and Message/SendForm check the name first, so a refused message runs nothing and costs nothing. Reading, renaming and deleting a session work with whatever name it already has.
- The turns of one session run one at a time, in order: a second message waits in
agent_queueuntil the turn before it ends. Different sessions run in parallel.
Costs
- $10 to start a turn. Message/Send and Message/SendForm need at least $10 spendable in the wallet of the key's workspace. Below that, the message is refused with code
97(Insufficient balance), and the response carrieswalletUsd, the balance, andminTopup, the minimum. Nothing is charged for a refused message. Reading messages, sessions and results is free. - What a turn costs. A turn's cost depends on the models Studio runs for it, and can be more than $10.
- Chat. Each turn is charged for the tokens it used, at the chat model's rates in Studio/Status (credits per 1M tokens; 1 credit is $0.01). The reply shows the chat charge in
tokencost, in credits:tokencost / 100is the amount in USD. - Model runs. Each model run Studio starts is charged at that model's price when it succeeds. Failed and cancelled runs are not charged. Studio/Tasks shows each run's
totalcost. - Spend limits and Model Access. The models Studio runs for you follow your workspace's spend limits and Model Access rules, the same as the runs you start yourself: the account's or the team's, your own in a team, and those of the API key and the surface you sent the message with. So does the chat: what it costs counts toward spend limits, and a message whose chat model a Model Access rule blocks is refused with code
92before anything runs. - Charges are made within about a minute of the work finishing. Studio/Transactions lists them, and they also appear in the wallet's transactions.
POST /Studio/Status
Returns the wallet check and the chat models Studio can use. It settles your pending Studio charges first, so walletUsd is current. It takes no request fields.
| Field | Type | Description |
|---|---|---|
walletUsd |
number | Spendable balance of the workspace wallet in USD. |
needsTopup |
boolean | true when walletUsd is below minTopup. |
minTopup |
number | The balance a turn needs to start: 10. |
tokenRates |
object | Chat model rates. default_model is the default chat model, and models is keyed by model slug: each entry has input_per_1m and output_per_1m (credits per 1M tokens), optional cached-input, cache-write and long-context rates, a label, and selectable: true when you can pick it with model. A model you could pick that your Model Access rules block reads selectable: false and blocked: true. |
agentModel.chatModel |
string | The chat model a turn uses when you leave model out. |
blockedModels |
string[] | The chat models you could pick that your Model Access rules block. [] when none is blocked. |
agentModelBlocked |
boolean | true when your rules block agentModel.chatModel: a message that leaves model out is then refused with code 92. |
agentModelMessage |
string | null | The refusal such a message gets when agentModelBlocked is true, else null. |
title |
string | The agent's name. |
status |
number | Always 4. |
The response also carries fields that Wiro's own apps use. Ignore the ones not listed here.
Response
{
"result": true,
"errors": [],
"title": "Generative Media Agent",
"status": 4,
"walletUsd": 42.5,
"needsTopup": false,
"minTopup": 10,
"tokenRates": {
"default_model": "openai/gpt-5.6-sol",
"models": {
"openai/gpt-5.6-sol": {
"input_per_1m": 625,
"output_per_1m": 3750,
"cached_input_per_1m": 62.5,
"selectable": true,
"label": "GPT-5.6 Sol"
},
"openai/gpt-5.4-mini": {
"input_per_1m": 93.75,
"output_per_1m": 562.5,
"cached_input_per_1m": 9.375,
"selectable": true,
"label": "GPT-5.4 Mini"
}
}
},
"agentModel": {
"chatModel": "openai/gpt-5.6-sol"
},
"blockedModels": [],
"agentModelBlocked": false,
"agentModelMessage": null
}
When a rule blocks a chat model, Status says so. With a team rule that blocks openai/gpt-5-6-sol, Studio's default chat model, these fields read:
{
"tokenRates": {
"default_model": "openai/gpt-5.6-sol",
"models": {
"openai/gpt-5.6-sol": {
"input_per_1m": 625,
"output_per_1m": 3750,
"cached_input_per_1m": 62.5,
"selectable": false,
"label": "GPT-5.6 Sol",
"blocked": true
},
"openai/gpt-5.4-mini": {
"input_per_1m": 93.75,
"output_per_1m": 562.5,
"cached_input_per_1m": 9.375,
"selectable": true,
"label": "GPT-5.4 Mini"
}
}
},
"agentModel": {
"chatModel": "openai/gpt-5.6-sol"
},
"blockedModels": ["openai/gpt-5.6-sol"],
"agentModelBlocked": true,
"agentModelMessage": "This team can't use openai/gpt-5-6-sol. Model Access rules decide which models can run."
}
A message that leaves model out is then refused with agentModelMessage. Send a model that is still selectable, such as openai/gpt-5.4-mini.
POST /Studio/Message/Send
Sends a message to Studio. It returns at once with the turn's messageguid and agenttoken; the reply arrives on the WebSocket and in Message/Detail.
| Parameter | Type | Required | Description |
|---|---|---|---|
message |
string | Yes | Your request, as you would type it in Studio. Say what the result is for, the look (subject, style, format or aspect ratio, length for video and audio) and how many results you want. Quote any exact text that must appear in an image or be spoken. |
sessionkey |
string | No | The session to send to. Defaults to "default", the main Studio chat. |
model |
string | No | The chat model for this turn: a slug whose selectable is true in Studio/Status. Leave it out to use Studio's default chat model, agentModel.chatModel. A chat model your Model Access rules block is refused with code 92, the default included. Use the same model on every turn of a session; when it differs from the previous turn, the response includes modelChangeMarker, as in Agent Messaging. |
To attach files, use Message/SendForm.
Response
{
"result": true,
"errors": [],
"messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
"status": "agent_queue"
}
A wallet below the minimum gets:
{
"result": false,
"errors": [{ "code": 97, "message": "Insufficient balance", "time": 1761902400 }],
"walletUsd": 6.4,
"minTopup": 10
}
A message whose chat model a Model Access rule blocks gets code 92, and nothing is sent or charged:
{
"result": false,
"errors": [{ "code": 92, "message": "This team can't use openai/gpt-5-6-terra. Model Access rules decide which models can run.", "time": 1761902400 }]
}
If a request times out, check Message/History before you send it again: each accepted message starts a paid turn.
POST /Studio/Message/SendForm
The same as Message/Send, as multipart/form-data, so you can attach files such as a product photo or a logo.
| Parameter | Type | Required | Description |
|---|---|---|---|
message |
string | Conditional | Your request. Required unless at least one file is attached. |
sessionkey |
string | No | The session to send to. Defaults to "default". |
model |
string | No | As in Send. |
attachments |
file | No | The files. Repeat the attachments field once per file; a single file can also be sent as attachment. |
- Up to 8 files per message, each up to about 100 MB. A larger file is refused with HTTP 413.
- Accepted: images (jpg, jpeg, png, gif, webp, heic, svg), video (mp4, webm, mov), audio (mp3, wav, m4a, webm) and documents (pdf, txt, md, csv, doc, docx, xls, xlsx, ppt, pptx, epub). The file name needs its extension. Other files are refused with
Uploaded file format invalid. Supported: .... - The message's
attachmentsthen lists each file withordinal,mentionLabel,url,name,typeandsize.
The response is the same as Send's.
POST /Studio/Message/Detail
Returns one message and its reply. Poll it until status is agent_end, agent_error or agent_cancel, or follow the turn on the Agent WebSocket.
| Parameter | Type | Required | Description |
|---|---|---|---|
messageguid |
string | Conditional | The message id from Send. Required unless agenttoken is given. |
agenttoken |
string | Conditional | The turn token from Send. |
sessionkey |
string | No | The message's session. Defaults to "default". A message from another session is Message not found. |
Reply fields
| Field | Description |
|---|---|
status |
agent_queue, agent_start, agent_output, then agent_end; or agent_error or agent_cancel. |
content |
Your message. |
response |
The final reply, set when the turn ends. Each file Studio made is on its own line as a public URL. After agent_error or agent_cancel it holds a coded failure message, such as [AGENT_UNAVAILABLE] Agent is temporarily unavailable. Please try again shortly. (see Failed turns). |
debugoutput |
The reply text so far while the turn runs, the final text after. |
timeline |
The ordered reasoning, answer and tool blocks of the turn, as described in Agent Messaging. Tool labels are display names: show them, but do not parse them. |
attachments |
The files you attached. |
model |
The chat model that ran the turn. |
inputtokens, outputtokens, cachereadtokens, cachewritetokens, totaltokens |
The turn's token use. |
tokencost |
The chat charge in credits; tokencost / 100 is the amount in USD. Model runs are charged separately (see Studio/Tasks). |
createdat, startedat, endedat |
Unix seconds. |
Response
{
"result": true,
"errors": [],
"data": {
"guid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
"content": "Two square banner images for my bakery's weekend sale, warm colors",
"response": "Here are your two banners.\nhttps://cdn1.wiro.ai/7f3a9c2e/banner-1.png\nhttps://cdn1.wiro.ai/7f3a9c2e/banner-2.png",
"debugoutput": "Here are your two banners.\nhttps://cdn1.wiro.ai/7f3a9c2e/banner-1.png\nhttps://cdn1.wiro.ai/7f3a9c2e/banner-2.png",
"status": "agent_end",
"metadata": {},
"createdat": "1761902400",
"startedat": "1761902401",
"endedat": "1761902466",
"attachments": [],
"timeline": [],
"model": "openai/gpt-5.6-sol",
"inputtokens": 6400,
"outputtokens": 610,
"cachereadtokens": 0,
"cachewritetokens": 0,
"totaltokens": 7010,
"tokencost": 7
}
}
In this example the chat part cost 7 credits ($0.07). The two images are charged separately, as the model runs Studio started.
POST /Studio/Message/History
Returns the messages of one session, newest first.
| Parameter | Type | Required | Description |
|---|---|---|---|
sessionkey |
string | No | The session. Defaults to "default". |
limit |
number | No | Messages per page. Default 50, maximum 200. |
before |
string | No | A message guid: returns the messages older than it, for the next page. |
The response is { "result": true, "errors": [], "data": { "messages": [...], "count": 2, "hasmore": false } }. Each message has the reply fields of Message/Detail except startedat and endedat.
When a turn hands work to the background, its reply says so and ends early. The result arrives later as a new message in the same session, already finished: status is agent_end, content is empty and the text is in response. Read it with History, and find the files in Studio/Tasks.
POST /Studio/Message/Sessions
Lists your Studio sessions in the key's workspace, most recent first, including those started on wiro.ai. It takes no request fields.
{
"result": true,
"errors": [],
"data": {
"sessions": [
{
"sessionkey": "bakery-banners",
"messagecount": 3,
"updatedat": 1761902466,
"lastmessage": "Make the second one brighter",
"name": "Bakery banners"
},
{
"sessionkey": "default",
"messagecount": 0,
"updatedat": null,
"lastmessage": ""
}
]
}
}
messagecount counts turns, lastmessage is the last message (up to 500 characters), and name is the display name set with Message/RenameSession. "default" is always listed.
POST /Studio/Message/Cancel
Stops a turn that is queued or running.
| Parameter | Type | Required | Description |
|---|---|---|---|
messageguid |
string | Conditional | The message id. Required unless agenttoken is given. |
agenttoken |
string | Conditional | The turn token. |
sessionkey |
string | No | The message's session. Defaults to "default". |
Only a message in agent_queue, agent_start or agent_output can be cancelled; any other is refused with Message cannot be cancelled (status: <status>). Cancelling stops the reply, and the message moves to agent_cancel. Tokens already used are charged, and model runs that already started are billed when they succeed.
POST /Studio/Message/ClearSession
Deletes your messages in a session and starts Studio's memory of it fresh. The session keeps its display name.
| Parameter | Type | Required | Description |
|---|---|---|---|
sessionkey |
string | No | The session. Defaults to "default", the main Studio chat. |
Pending charges are settled first. Deleted messages cannot be restored, and they disappear from Studio on wiro.ai too. Files Studio made are not deleted.
POST /Studio/Message/DeleteSession
Deletes a session's messages and its display name.
| Parameter | Type | Required | Description |
|---|---|---|---|
sessionkey |
string | No | The session. Defaults to "default". |
To start a session over with a fresh memory, use Message/ClearSession.
POST /Studio/Message/RenameSession
Sets a session's display name, the name shown in the session list on wiro.ai.
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | The display name, up to 40 characters. |
sessionkey |
string | No | The session. Defaults to "default". |
POST /Studio/Tasks
Lists the model runs Studio started for you in the key's workspace, newest first, across all your Studio sessions, including those on wiro.ai.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit |
number | No | How many recent runs to return. Default 30, maximum 100. |
| Field | Description |
|---|---|
id |
The run's id. |
status |
The task status, such as task_queue, task_start, task_postprocess_end or task_cancel (see Tasks). |
success |
true for a run that finished successfully, false for a failed or cancelled run, null while it runs. |
terminal |
true once the run has finished. |
model |
{ title, slugowner, slugproject }. |
categories |
The model's categories. llm marks a text run. |
parameters |
The inputs the run used, such as its prompt. |
outputs |
The result files, each with name, contenttype, size and url. An LLM run returns its text as { "contenttype": "raw", "content": { "answer": [...] } }. |
totalcost |
The run's price in USD, charged when it succeeds. |
socketaccesstoken |
While the run is active, a token for the task WebSocket; empty once it finished. |
createtime, starttime, endtime |
Unix seconds. |
elapsedseconds |
How long the run took. |
Response
{
"result": true,
"errors": [],
"tasks": [
{
"id": "48211907",
"status": "task_postprocess_end",
"success": true,
"terminal": true,
"model": {
"title": "Nano Banana Pro API: Create Mobile & Web Apps with Nano Banana",
"slugowner": "google",
"slugproject": "nano-banana-pro"
},
"categories": ["text-to-image", "image-to-image", "image-editing"],
"parameters": { "prompt": "Square banner for a bakery weekend sale, warm colors", "resolution": "2K" },
"outputs": [
{
"name": "banner-1.png",
"contenttype": "image/png",
"size": "1843212",
"url": "https://cdn1.wiro.ai/7f3a9c2e/banner-1.png"
}
],
"totalcost": 0.14,
"socketaccesstoken": "",
"createtime": "1761902420",
"starttime": "1761902421",
"endtime": "1761902452",
"elapsedseconds": 31
}
]
}
Delete a finished run's files with Studio/Task/DeleteOutput.
POST /Studio/Transactions
Lists the wallet charges for your Studio use in the key's workspace, newest first.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit |
number | No | Default 50, maximum 200. |
Each row has guid, type, amount, description, modelid, taskid, confirmed and time. A chat charge is described as Generative Media Agent LLM <model> (...) with its token counts, and a model run as Generative Media Agent media run.
POST /Studio/Task/DeleteOutput
Deletes the output and input files of one of your Studio runs once it has finished or was cancelled.
| Parameter | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | The run's id from Studio/Tasks. |
A run that is not yours answers There is no task yet., and a run that has not finished answers Task must be completed or cancelled before deleting files.
Errors
Business errors come back with HTTP 200, result: false and an errors array, as everywhere in the Wiro API. These are the ones specific to Studio:
| Message | Code | When |
|---|---|---|
Insufficient balance |
97 | Send or SendForm with less than $10 spendable. The response adds walletUsd and minTopup. |
A spend limit refusal, such as Your monthly spend limit is reached ($100.40 of $100.00). It resets on December 1, 2026 at 00:00 UTC. |
93 | Send or SendForm while a spend limit that covers the message is used up. Nothing is charged. |
A Model Access refusal, such as This team can't use openai/gpt-5-6-terra. Model Access rules decide which models can run. |
92 | Send or SendForm when a Model Access rule that covers the message blocks its chat model: the model it names, or the default chat model when it names none. It is checked before the balance and the spend limits. Nothing is sent or charged. |
Request parameter [message] required |
0 | Send without a message, or SendForm with neither a message nor a file. |
Invalid model: <model> is not in the selectable model allowlist. |
0 | model is not one of the chat models Studio offers. A model your Model Access rules block gets code 92 instead. |
A Studio session name may contain only letters, digits, ".", "_", ":" and "-", at most 128 characters, and cannot end in "-r" followed by a number. Nothing was sent or charged. |
0 | Send or SendForm with a session name outside that rule. |
You already have a Studio session with this name in different capitals. Use its exact name, or another name. Nothing was sent or charged. |
0 | Send or SendForm with a new session name that differs only in capitals from one of your sessions. |
Reserved sessionkey |
0 | The session name contains :cron:. |
Too many files (max 8) |
0 | SendForm with more than 8 files. |
Uploaded file format invalid. Supported: ... |
0 | An attachment type that is not accepted. |
Message not found |
0 | Detail or Cancel with an unknown message, or one from another session. |
Message cannot be cancelled (status: <status>) |
0 | Cancel on a turn that has already ended. |
Agent is temporarily unavailable. Please try again shortly. |
0 | Try again shortly. |
You must be a member of this team to perform this action |
HTTP 403 | A team project's key whose creator is no longer a member of the team. |
Authentication errors are listed in the Error Reference.
Agent Overview
Deploy and manage autonomous AI agents through a single API.
Wiro Agents on the Web
The endpoints below cover the full programmatic surface. If you also want to see the web product alongside what you're building (landing pages, marketing copy, the visual catalog, and the no-code Build Your Own Agent flow), these are the public Wiro pages dedicated to agents:
| Page | URL | What it covers |
|---|---|---|
| AI Agents Home | wiro.ai/agents | Top-level landing: what Wiro Agents are, how they compare to traditional setups, and a featured selection from the marketplace. |
| Learn About Agents | wiro.ai/agents/learn | Concept primer: security model, deployment lifecycle, and the difference between marketplace templates and custom builds. |
| Anatomy of an Agent | wiro.ai/agents/anatomy | Fullscreen interactive walkthrough of the pieces that make a Wiro agent reason: system prompt, knowledge, skills, memory, guardrails, model, tools, scheduling, and observability. |
| Build Your Own Agent | wiro.ai/agents/build | The web wizard for the same custom-build flow exposed by POST /UserAgent/Deploy with custom: true. Useful for previewing the skill picker and the three plans before scripting it. |
| Browse Agents | wiro.ai/agents/browse | Full marketplace catalog with categories, descriptions and screenshots, the visual mirror of POST /Agent/List. Each row links to a dedicated agent page at /agents/{slug}. |
| Use Case Showcases | wiro.ai/agents/usecase/... | Seven fullscreen, auto-looping product stories that show real businesses operated end-to-end by a Wiro agent. See Agent Use Cases for the full list. |
All pages are public: no Wiro account required to browse. Sign-in becomes mandatory only when you click "Deploy" on a specific agent (which then drops you into the Wiro dashboard at wiro.ai/panel/agents).
What are Wiro Agents?
Wiro Agents are autonomous AI assistants that keep running on Wiro. 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 default skill set and required credentials, and runs on any of the three plans. Browse the catalog with
POST /Agent/List. - UserAgent instances (your deployments): When you deploy an agent template (or build a custom one), Wiro creates a personal instance tied to your account. Each instance runs in its own isolated environment with its own credentials, configuration, conversation history, billing, and per-model token-rate profile, and its own computer in the cloud with a web browser the agent works in. The people who manage the agent can watch that computer from the Wiro panel, and an app built on the API can show it to its own users (see Screen and Take Control).
Every instance is fully isolated. Your credentials, conversations, and data are never shared with other users.
Two deploy paths. You can deploy a marketplace template by passing
agentguid, or build a custom agent from scratch withcustom: true(no template: you pick the skill set yourself). Both flows are documented underPOST /UserAgent/Deploy. The custom builder is detailed in Agent Builder.
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:
| Method | Header |
|---|---|
| API Key | x-api-key: YOUR_API_KEY |
| Bearer Token | Authorization: Bearer YOUR_API_KEY |
Public endpoints: Agent/List, Agent/Detail, Skills/List, Skills/Detail, Skills/Capabilities, Credentials/List, and Credentials/Detail are catalog endpoints and do not require authentication. You can browse available agents, the skill registry, and the credential schema without an API key.
Authenticated endpoints: All UserAgent/* endpoints require a valid API key.
For full details, see Authentication.
Pricing Model: Plans, Credits & Token Billing
Every agent runs on one of three monthly plans, and the plan alone sets its price, its monthly credits and its disk space. Templates and custom builds use the same plans, and the skills an agent has never change the price. Each turn the agent runs then spends credits by the tokens its model uses.
Plans
| Plan | tier |
Price | Monthly credits | Disk |
|---|---|---|---|---|
| Starter | "starter" |
$5 a month | 500 | 250 MB |
| Pro | "pro" |
$30 a month | 3,000 | 500 MB |
| Max | "max" |
$100 a month | 10,000 | 1 GB |
Every plan carries 100 credits per dollar (1 credit = $0.01). A plan is bought per agent: pass tier to Deploy or CreateSubscriptionCheckout. Catalog and instance responses list the three plans under tiers:
"tiers": {
"starter": { "priceUsd": 5, "credits": 500 },
"pro": { "priceUsd": 30, "credits": 3000 },
"max": { "priceUsd": 100, "credits": 10000 }
}
Instance responses (agent.plans) and PricingPreview (plans) also list them with their names, as { key, title, priceUsd, monthlyCredits, diskMb }, where diskMb is the plan's disk space in MB (250, 500 or 1024, which is 1 GB; see Disk Space).
A wallet plan renews every 30 days, and a plan paid by card in the Wiro dashboard renews on its monthly card cycle. Every renewal grants the plan's credits in full. Credits a period leaves unused don't carry over; credits from extra credit packs keep their own 6-month expiry.
What a Plan Includes
Every skill and connector works on every plan. Turning a skill on or off with SkillsApply is free: the plan's price and credits stay as they are. The work a skill does still uses credits, since its replies and scheduled tasks are agent turns billed by tokens like any other. A skill that runs Wiro models, such as int-wiro-aimodels or util-video-creator, pays for those runs from the wallet of the Wiro project you connect to the agent.
Disk Space
Each plan gives the agent disk space for its files: 250 MB on Starter, 500 MB on Pro and 1 GB on Max. What counts is the agent's workspace, the media it generates and its temporary files. Chat history and the agent's system files don't count.
Downloads and temporary files outside the workspace are cleared when the agent restarts. They are also cleared when they pass 1 GB, on every plan: the agent then restarts on its own, which takes about a minute, and the files in its workspace stay.
When the agent's files reach the plan's size, the disk is full: the agent can't save new files until some are deleted or the agent moves to a bigger plan. A full disk deletes nothing. A move to a higher plan with UpgradeTier gives the agent the bigger disk as soon as the new plan starts. A move to a lower plan brings its smaller disk at the renewal where that plan starts: if the agent's files are bigger than that, they all stay, and the disk reads full until some are deleted.
UserAgent/Detail shows the agent's usage in disk (see Disk object): its state reads "almost_full" from 80% of the plan's size and "full" from 100%. The agent's activity log gets an AGENT_DISK_ALMOST_FULL row when its files pass 80%, an AGENT_DISK_FULL row when they reach the plan's size, and an AGENT_DISK_TEMP_CLEARED row when a restart clears temporary files that passed 1 GB (see Who-did-what rows).
Changing Plans
POST /UserAgent/UpgradeTier moves an agent to another plan:
- A higher plan starts now. On a wallet plan, the wallet pays the monthly difference for the time left in the period, by the second, rounded up to the cent and at least one day's worth, and the period gains the difference in credits for that same time. Every renewal after that grants the new plan in full. Example: a Pro agent moving to Max with 15 days left of 30 pays $35.00 and gains 3,500 credits now, then renews at $100 with 10,000 credits.
- A lower plan starts at the next renewal. Ask for it with
allowDowngrade: true: without it, a lower plan is refused and nothing changes. Nothing is charged or refunded. The agent keeps its current plan, price and credits until the period ends, and itsnextplanfield names the plan it will renew on. - Asking for the agent's current plan cancels a scheduled move to a lower plan.
Moving to a higher plan while a lower one is scheduled cancels the scheduled move first, and cancelling the subscription clears it too. On a plan paid by card, a higher plan goes through a card checkout: nothing changes until it is paid, and then a new full period starts with the plan's full credits. A lower plan on a card plan applies from the next card renewal.
Extra Credits
An agent with an active plan can buy extra credits at any time, on every plan. The packs are the same for every agent:
| Pack | Credits | Price |
|---|---|---|
small |
1,000 | $10 |
medium |
5,000 | $50 |
large |
20,000 | $200 |
Pack credits are spent after the month's plan credits and expire 6 months after purchase. See Extra Credit Packs.
Token Billing
The monthly plan buys a credit pool; each turn the agent runs (a chat reply, a scheduled cron tick, or a voice-prep turn) deducts credits from that pool, metered by the tokens its model consumes. There are no flat per-action costs: what a turn costs depends on the model and how many input / output / cached tokens it used.
Per-model rates live in the tokenRates object, present on Agent/Detail, UserAgent/Detail, MyAgents, PinnedAgents, and PricingPreview. The marketplace catalog (Agent/Detail) and PricingPreview return only the selectable models; a deployed instance's UserAgent/Detail / MyAgents / PinnedAgents return the full model map (so historical model-change markers and token-usage tooltips can still resolve a model that was later marked non-selectable). Internal metadata ($-prefixed keys) is stripped from every response:
"tokenRates": {
"default_model": "openai/gpt-5.6-sol",
"fallback_rate": { "input_per_1m": 625, "output_per_1m": 3750, "cached_input_per_1m": 62.5, "cache_write_per_1m": 781.25 },
"models": {
"openai/gpt-5.6-sol": { "input_per_1m": 625, "output_per_1m": 3750, "cached_input_per_1m": 62.5, "cache_write_per_1m": 781.25, "selectable": true, "label": "GPT-5.6 Sol", "tier": "premium" },
"openai/gpt-5.6-terra": { "input_per_1m": 250, "output_per_1m": 1500, "cached_input_per_1m": 25, "cache_write_per_1m": 312.5, "selectable": true, "label": "GPT-5.6 Terra", "tier": "balanced" },
"openai/gpt-5.6-luna": { "input_per_1m": 25, "output_per_1m": 150, "cached_input_per_1m": 2.5, "cache_write_per_1m": 31.25, "selectable": true, "label": "GPT-5.6 Luna", "tier": "cheap" }
}
}
Rates are quoted in credits per 1,000,000 tokens, and 1 credit = $0.01 (100 credits = $1). Wiro prices every LLM call against the model that actually served that call, sums each token category across the turn, and rounds the four aggregate categories up independently:
tokencost = ceil(Σ call_input_cost)
+ ceil(Σ call_output_cost)
+ ceil(Σ call_cache_read_cost)
+ ceil(Σ call_cache_write_cost)
Cache-read and cache-write categories are charged only when the selected model rate defines them. inputtokens contains only uncached input; totaltokens is always the exact sum of input, output, cache-read, and cache-write tokens. For models with long_context_threshold_tokens, Wiro selects the long-context rate per LLM call using input + cacheRead + cacheWrite. You don't send anything. Each billed turn appears once as a ledger row with action: "tokens" (see POST /UserAgent/TransactionList). Per-turn token counts and cost also ride on each assistant message (inputtokens / outputtokens / cachereadtokens / cachewritetokens / totaltokens / tokencost / model, see Agent Messaging).
When the credit pool is exhausted, POST /UserAgent/Message/Send and POST /UserAgent/Start refuse with an Agent has no remaining credits… error plus an agentbalance snapshot; renew the subscription or buy an extra credit pack to continue.
Voice realtime audio is billed separately. Live voice-call audio (for
util-voice-receptionistagents) is not charged to the platform credit pool. It is billed to the operator's own Wiro wallet through theint-wiro-aimodelsskill, the Wiro AI Models connector (you bring your own Wiro API key). The voice-prep turn before the call and the post-call text turn are billed as normal token deducts.
Live Pricing Preview
Before you deploy, change the plan or change skills, call POST /UserAgent/PricingPreview. It writes nothing and returns the three plans under tiers, the tokenRates, and enabledSkills with every transitive depends_on resolved. For an agent with an active plan it also returns planChange: what a different tier would charge now and when it starts. A skill change has no price, so its planChange shows no charge and no credit change.
Agent Lifecycle
Deploying and running an agent follows this flow:
- Browse: call
POST /Agent/Listto discover available agents in the catalog - Deploy: call
POST /UserAgent/Deploywithuseprepaid: trueandtier("starter","pro"or"max"). The plan's price is debited from your prepaid wallet immediately and a 30-day subscription row is created. - Configure: set integration and optional Telegram, Slack, or Discord credentials with
POST /UserAgent/CredentialUpsertor the OAuth flow, connect the Wiro project the agent runs models with usingPOST /UserAgent/CredentialProjectBind, and set preferences withPOST /UserAgent/CustomSkillUpsert. An agent admin can also approve the setup cards the agent proposes in its chat (see Setup From Chat). See Agent Credentials for details - Start: the prepaid Deploy already queued the agent, and Wiro starts it. Call
POST /UserAgent/Startonly for a stopped (status0) or errored (status5) agent - Running: the agent starts and becomes available for conversation
- 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:
| Status | Name | Description |
|---|---|---|
0 |
Stopped | Agent is not running. Call Start to launch it. |
1 |
Stopping | Agent is shutting down. After a stop, wait for it to reach Stopped before taking action. During a restart, it goes on to Queued and Starting by itself. |
2 |
Queued | Agent is queued and waiting to start. |
3 |
Starting | The agent is starting up. |
4 |
Running | Agent is live and ready to receive messages. |
5 |
Error | Agent encountered an error during execution. Call Start to retry. |
6 |
Setup Required | Agent needs credentials or configuration before it can start. Provide them via CredentialUpsert / CredentialProjectBind / CustomSkillUpsert / SkillsApply, then call POST /UserAgent/Update. |
Automatic Restart
When you mutate an agent's configuration while it is starting (status 3) or running (status 4), the system automatically triggers a restart cycle: the agent is moved to Stopping (status 1) and flagged to restart. Once the agent fully stops, the system automatically re-queues it, applying the new configuration on startup.
This means you can update credentials, toggle skills, or change a custom skill on a running agent without manually stopping and starting it.
These calls restart a starting or running agent when they change something: CredentialUpsert (except the sign-in case below), CredentialFileUpload, CredentialProjectBind (when the project changes), an OAuth sign-in, direct OAuthConnect probe or SetPickerAccounts save that completes a connection, OAuthDisconnect (when it removes a token or the connection was complete), SkillsApply, SkillToggle, CustomSkillUpsert (a new custom skill or scheduled task, a new interval, an enabled change, or a change to cs-approval-policy), CustomSkillRename, CustomSkillDelete, CustomSkillRevert, UpdateSettings (a new time zone, Chat Mode, model, slash-command list or Wiro API path list, or turning chatsetup on or off), Update (a changed title, or a body that names no field), and a setup card applied from chat (see Setup From Chat). ResetBrowser restarts a starting or running agent every time: the browser is reset as the agent starts again. A restart takes about a minute. A change saved while a restart is still stopping or queued loads with that restart instead of starting another one.
Sign-in connectors restart the agent once, when the connection is complete. A connection is complete when its mode has a token and, for a credential with an account picker, at least one account is saved. Saving own-mode app keys, a System User token or authmethod with CredentialUpsert for a sign-in credential (one with an oauth_provider) that isn't connected before or after the save restarts nothing. A first sign-in or token check that leaves accounts to pick restarts nothing, and the SetPickerAccounts save restarts the agent once. One with nothing to pick (X, TikTok, LinkedIn, HubSpot, Mailchimp, Reddit, Shopify, an Instagram Login, or a Google account with a single YouTube channel) restarts it when it finishes. A reconnect that keeps the saved accounts restarts it at the sign-in, so the agent loads the new token. Saving the same accounts again restarts nothing, and a failed token check restarts the agent only when it cleared a connection that was complete. While nothing that is on uses the credential, a connection restarts nothing: turning on the connector that uses it restarts the agent once, with the connection. A direct OAuthConnect and SetPickerAccounts answer restart ("scheduled" or "none"), and flow.restart in OAuthStatus says what the sign-in did.
A change to only the text or description of an existing custom skill or scheduled task, through CustomSkillUpsert or a setup card, reaches a running agent right away, without a restart. These never restart a running agent: a plan change, a credit pack, a renewal or a cancellation, moving chatsetup between "all" and "webchat", a screen change through UpdateSettings, and a description, categories or cover edit through Update.
Screen and Take Control
Every agent has its own computer in the cloud: a 1920 x 1080 desktop that holds the agent's web browser, where its browser and desktop tools do their work. In the Wiro panel, the people who manage an agent can open its Screen beside the chat and watch that computer live while the agent works. The owner of a personal agent that has never been in a team, or whose browser was reset after it last left one, can also press Take Control and use the keyboard and mouse there, for example to sign in to a site for the agent or to finish a step by hand.
The Screen opens in the Wiro panel at wiro.ai/panel/agents for people signed in there, and in your own product through the API: your backend asks for it with your project API key through ScreenInfo and ScreenStart, and your page shows it, Take Control included (see Screen in Your Own App). Chats in Telegram, Slack and Discord never show it. The screen setting on UpdateSettings and Detail turns it off or on for an agent, and the agent's activity log records who watched and who took control. ResetBrowser signs the agent's browser out of every site, which is also how an agent that was in a team gets Take Control back (see Resetting the Browser).
Who Can Watch
| Agent | Who can open its Screen |
|---|---|
| Personal agent | Its owner, the person who deployed it. |
Team agent whose Chat Mode is "collaborative" |
The agent's owner, while they are in the team, and the team's admins. The organization owner is an admin of every team they create. Other members can't open it. |
Team agent whose Chat Mode is "private" |
Nobody. One computer shows the work of every chat, so the Screen stays closed to the whole team. |
| Any of these, through a project API key | The key's owner, the person who created the key's project, on the agents that person can open above. A team project's key opens only that team's agents. Your backend decides which of your users see it: see Screen in Your Own App. |
In the Wiro panel, the Screen button sits in the agent's chat header. It shows only for these people, only while the agent is running (status 4) and only while its screen setting is "on". When the agent stops or restarts, an open Screen closes, and the button comes back once the agent runs again. Through the API, ScreenInfo answers available: true under the same conditions.
Screen in Your Own App
A product built on the API can show an agent's Screen in its own app, Take Control included. Your backend asks ScreenInfo whether the Screen can open, gets a one-time ticket from ScreenStart with your project API key, and hands the ticket to your page, which opens the screen over a WebSocket and draws it with noVNC. Screen and Take Control in Your App walks through every step, with a complete example.
A call made with your API key acts as the key's owner, the person who created its project, under the rules above: it watches the agents that person can watch, and takes control only where that person can, on a personal agent they deployed that has never been in a team, or whose browser was reset after it last left one. A team project's key opens only that team's agents. Your key speaks for your whole product: Wiro gives it a ticket whichever of your users it is for, so what they see is up to you:
- You decide who sees it. Ask for a ticket only for the users you allow to watch that agent, and ask for Take Control (
control: true) only for the users you allow to use its keyboard and mouse. - One computer shows every chat. An agent has one computer and one browser for all of its chats. Its Screen shows what the agent is doing at that moment in any of them: each of your users' chats, its Telegram, Slack and Discord chats and its Scheduled Tasks, and the agent brings the tab it is working in to the front. On an agent several of your users share, whoever watches can see the others' work.
- Take Control reaches every sign-in. The person in control works in the agent's own browser, signed in wherever any of its chats signed in. What they sign in to there stays in that browser afterwards, where every chat of the agent can use it, your other users' chats included. While they have control, the agent's browser and desktop tools pause for every chat of the agent, not only theirs. Its other tools keep working, and a paused task goes on with that chat's next message or the task's next scheduled run (see While You Have Control).
- One agent per user keeps each screen to that user. When each of your customers has an agent of their own, its Screen shows only that customer's work. On an agent many of your users talk to, show the Screen only to people who may see all of their work, or turn it off.
- The
screensetting is the switch.screen: "off"onUpdateSettings, sent with the same API key by the agent's owner or a team admin, closes the Screen for everyone, your users and the Wiro panel alike, and ends open screens within about half a minute."on"opens it again (see Turning the Screen Off). - Keep your own record. The activity log names your key's owner for every screen your key opens, never your users (see Screen in the Activity Log), so note in your own product which of your users got each ticket.
Watching the Screen
- On the agent's page, Screen opens the screen beside the chat when your browser window is wide, and inside the expanded chat when it is narrower. On a phone, tap Open Agent Chat, then Screen in the Chat / Screen switch.
- A pinned agent's chat window in the dock has the same button, which opens the screen in a mini window.
- Pop Out moves the screen into a mini window that floats over the page; drag it by its header. Put Back returns it beside the chat. Expand Screen makes it fill the expanded chat, with the chat in a mini window of its own, and Collapse Screen undoes that. Close ends the session.
- Leaving the agent's Chat tab moves an open screen into its mini window, so the session goes on.
- A browser tab holds one Screen per agent: opening the same agent's screen somewhere else in the tab, such as on its page and in its dock window, closes the first one. Other tabs and devices open screens of their own.
The screen opens in View Only: "View only. Your clicks and keys are not sent." Everyone watching sees the same screen at the same moment, including what a person in control does. While someone watches and nobody has control, the browser tab the agent just used comes to the front, so you see the page it is working on.
Zoom. Zooming changes only your view; the agent's screen stays 1920 x 1080. The bar under the screen ends with Zoom Out, the zoom level (Fit or a percentage) and Zoom In, in every view but the mini window, which always fits. Zoom In and Zoom Out step between Fit and the levels above it among 50%, 75%, 100%, 150% and 200%; when Fit is already 100% or more, the top level is twice Fit. At 100% one pixel of the agent's screen is one pixel of yours. The level button switches between Fit and 100%, or between Fit and twice Fit when Fit is already 100% or more. You can also zoom these ways:
- Ctrl or Cmd with the scroll wheel, or a pinch on a trackpad, zooms at the pointer. This works in control too, outside the mini window, and none of it reaches the agent.
- A double-click does what the level button does, at the pointer: in View Only, and in control while Move View is on.
- In View Only, click the screen or Tab to it, then press
+or=to zoom in,-to zoom out, and0or Esc to fit. - On a touch screen in View Only, pinch with two fingers, or double tap to do what the level button does, at that spot.
Moving around. A zoomed screen shows scrollbars, which move the view in every mode. In View Only you can also drag it, turn the scroll wheel, press the arrow keys or move it with one finger; at Fit the wheel and your finger scroll the page instead. In control, use Move View (see Take Control). Each view keeps its own zoom through Take Control, Hand Back and reconnects, and goes back to Fit when you close the screen or open another agent.
Take Control
Only the owner of a personal agent that has never been in a team, or whose browser was reset after it last left one, can take control of its computer: in the Wiro panel, or in your own app with an API key of one of their personal projects (see Screen in Your Own App). It works at any screen size, phones included. Everyone else who can watch keeps View Only, and the Take Control button doesn't show for them.
- Team agents. Nobody can take control of a team agent, its owner and the team's admins included: its one browser is shared by the whole team, signed in wherever the members' chats signed in. They can still watch while its Chat Mode is
"collaborative". - Agents that have been in a team. An agent that was in a team doesn't get Take Control after it moves back to a personal workspace or returns there because its team or organization was deleted: its browser may still hold team members' sign-ins. Its owner can still watch, and gets Take Control back by resetting the agent's browser once it is personal (see Resetting the Browser).
To take control:
- With the screen Live, press Take Control. The panel asks first: "Take control of the agent's computer?", followed by "Control lasts up to 15 minutes. The agent's browser and desktop tools pause until you hand back. The session is noted in the agent's activity log." Press Take Control again to go ahead, or Cancel.
- The screen switches to control. It gets an amber frame, its header shows You Have Control when there is room, and the bar under it shows how long you have had control against the limit, such as
4:10 / 15:00. - Your clicks, keys, scrolling and touches now reach the agent's computer.
- Press Hand Back when you're done. The agent's browser and desktop tools work again at once, and the screen goes back to View Only. Closing the screen or the browser tab ends control too.
Keyboard. In control every key goes to the agent's screen, Tab and Esc included. Press Esc twice quickly to move keyboard focus out of the screen, onto Hand Back; the first Esc still reaches the agent. On a phone, or a tablet without a mouse, Keyboard in the bar under the screen brings up the device's keyboard. What you type there goes to the agent's screen, and text you paste into it is typed in.
Touch. In control, with Move View off, a tap clicks, a two-finger tap or a long press right-clicks, a three-finger tap middle-clicks, a one-finger drag drags, a two-finger drag scrolls, and a pinch zooms the page on the agent's screen. Use the zoom buttons to zoom your own view.
Move View. When you zoom in during control, Move View appears next to the zoom buttons. While it is on, dragging, the wheel, a finger or a pinch moves or zooms your view and none of it reaches the agent; keys still do. It turns itself off at Fit and when control ends.
One session at a time. Taking control in another tab or on another device moves control there, and the first screen goes back to watching with "Control was taken somewhere else. You're watching again." Everyone else watching keeps View Only.
Not during a capture. Take Control doesn't start while the agent is capturing its screen or a browser tab, for example to take a screenshot. Watching is not affected.
When Take Control can't start, the screen stays as it was and a notice under its header says why:
| Notice | Why |
|---|---|
| "Take Control can be started 6 times an hour on this agent. Try again in 12 minutes." | The hourly start limit (see Screen Limits). The wait is the time until the oldest of the 6 starts is an hour old. |
| "The agent is capturing its screen right now. Try again in a minute." | The agent is taking a screenshot or otherwise capturing its screen or a tab. |
| "The agent's screen is not answering right now. Try again in a minute." | The agent's computer didn't answer in time. |
| "The agent's screen could not be checked. Try again in a moment." or "Take Control could not start just now. Try again in a minute." | A check before control could not finish. Try again. |
| "You can't take control right now." | The panel got no answer, for example because your connection dropped. Try again. |
| "Too many screen sessions started. Try again in a few minutes." | You started 30 screen sessions in 10 minutes. |
| "Take Control is off for team agents: their browser is shared by the whole team." | The agent is in a team. |
| "Take Control is off for an agent that was used in a team, because its browser may still hold team members' sign-ins." | The agent has been in a team, and its browser hasn't been reset since it left. Reset its browser to get Take Control back (see Resetting the Browser). |
| "Take Control is not available for this agent right now." | Take Control can't be used on this agent at the moment. Watching still works. |
While You Have Control
- From the moment control starts until it ends, the agent's browser and desktop tools pause: the agent starts no new browser or desktop step. The rest of the agent keeps running: it answers chats in every channel, its Scheduled Tasks run, and its other tools and Connectors work.
- The agent isn't interrupted when you take control. If it reaches for its browser or desktop meanwhile, the call is refused with a message that a person has control of the computer, which asks the agent not to retry in that turn and to tell whoever it is talking to that it will continue once control is handed back. The message names no one and doesn't mention Wiro, so the agent can pass it on in any channel.
- When control ends and no other session holds it, each chat whose browser or desktop call was refused gets one note: control is back and the tools work again. The agent reads it at the start of that chat's next turn, when the chat's next message comes in, and can pick up the paused task then. In the Wiro web chat and in chats through your own app, the note waits up to 6 hours. The note starts no turn of its own, so it spends no credits by itself; that next turn is billed as usual. A chat that didn't reach for those tools gets no note. Neither does a Scheduled Task run: a run whose browser or desktop call was refused ends without that step, and the task runs again at its next scheduled time.
- You work in the agent's own browser, the one all of its chats use, signed in wherever they signed in. What you sign in to or change there stays in the agent's browser after you hand back, and the agent can use it.
The agent's browser. For safety, it saves no passwords and fills in no addresses or payment cards, the browser itself can't be signed in to an account or synced, and its settings pages, developer tools and local files stay closed. Signing in to websites works as usual. The desktop holds only the browser; if you close its last window, it opens again by itself within about 15 seconds. Your clipboard stays on your device, and on a phone or tablet, text you paste into Keyboard is typed in.
When Control Ends
Control ends when you press Hand Back or close the screen, and on its own in the cases below. The agent's browser and desktop tools work again at once, unless control moved to another tab or device: then they stay paused until that session ends too.
| Why control ended | What you see |
|---|---|
| 15 minutes in control | "This session reached its time limit" with Reconnect. Reconnect opens View Only; take control again to go on. |
| 2 minutes without keyboard or mouse input | View Only, with "Control was handed back after a while without keyboard or mouse input." |
| Someone took control in another tab or on another device | View Only, with "Control was taken somewhere else. You're watching again." |
| Input arrived faster than a person types or moves the mouse | View Only, with "Too much keyboard and mouse input arrived at once." |
| The browser sent input the agent's screen doesn't accept | View Only, with "The browser sent input the screen does not accept." |
| Take Control stopped applying to you on this agent | View Only, with "You can no longer control this agent's computer." Take Control stays hidden. |
| A capture began just as control was starting | View Only, with "The agent is capturing its screen right now. Try again in a minute." |
| The agent stopped or restarted, a settings change that restarts it included | The screen closes and the Screen button hides until the agent runs again. |
| Screen was turned off in the agent's settings | The screen closes and the Screen button hides. |
| Your connection dropped | The panel tries once more by itself, in control again, then offers Reconnect, which opens View Only. |
| The agent's computer closed the connection | "The agent's desktop closed the connection" with Reconnect. |
Idle end. Control counts as idle while no key press, click, touch or mouse movement reaches the agent. Moving the mouse over the screen counts, and so does any key; changes on the screen itself don't. With Move View on, your mouse and fingers don't reach the agent, so only keys keep control. For the last 30 seconds the bar under the screen counts down: "Control hands back in 0:30 without input. Move the mouse, tap or type to keep it." With Move View on it reads "Control hands back in 0:30 without input. Press a key or turn Move View off to keep it." Any input that reaches the agent clears it.
Screen Limits
| Limit | Value |
|---|---|
| Screens open on one agent at once, watching and control together; each browser tab or device counts, and so does each screen an app opens with an API key | 4 |
| One watching session | 30 minutes |
| One Take Control session, from when control starts | 15 minutes |
| Control without keyboard or mouse input | 2 minutes, counted down for the last 30 seconds |
| Take Control starts on one agent | 6 in any hour |
| Screen sessions one person starts, on all agents together | 30 in 10 minutes |
| Screen sessions started on one agent with API keys of one owner, for all of an app's users together | 30 in 10 minutes |
- When 4 screens are open on an agent, another one is refused with "4 people are watching this agent's screen. Try again in a minute."
- After 30 minutes a watching session ends with "This session reached its time limit"; Reconnect starts a new one.
- The 6 Take Control starts are counted per agent over a rolling hour. Watching doesn't count, and neither does a start refused with one of the notices above. A reconnect isn't counted either: a start while your control session on the agent is still open in another tab, or within 2 minutes after your control session's connection dropped because the browser tab closed or reloaded, the network went away, or the agent's computer closed the connection or didn't answer. That covers the panel's own retry after a dropped connection. A start within 2 minutes after a control start that was closed before the agent's screen answered, with Hand Back or by the panel giving up after 20 seconds, is a reconnect too, since you never had control. After any other end, such as Hand Back, closing the screen, the idle end or the time limit, your next start counts, even within 2 minutes of an earlier dropped connection. A start that ends at once because a capture began just then (see When Control Ends) is counted, and so is the next one. The seventh start in an hour is refused with the hourly notice above, which says how long to wait.
- Every screen the panel starts counts toward a person's 30 in 10 minutes: opening the Screen, Reconnect, each Take Control (also one refused for a capture or the hourly limit), the panel's own retry after a dropped connection, and the View Only screen it opens when control ends. Past that, a new one is refused until the 10 minutes are over.
- With a project API key, every
ScreenStartyour backend makes on an agent counts toward the 30 in 10 minutes that your key owner's API keys share on that agent, whichever of your users a screen is for: each ticket, and each start refused for too many viewers, a capture, a computer that doesn't answer or the hourly limit. Those keys also have their own reconnect window, which works as above and is kept apart from the owner's sessions in the Wiro panel. All of your users share it: one of them taking control while another one's control session from those keys is still open, or within 2 minutes after its connection dropped, is a reconnect. A control session the owner has open in the Wiro panel doesn't make it one.
Screen in the Activity Log
Three who-did-what rows in the agent's activity log record the Screen:
kind |
title |
When |
|---|---|---|
AGENT_SCREEN_VIEWED |
Watched the agent's screen |
Someone opened the Screen. At most one row per person and agent an hour. |
AGENT_SCREEN_CONTROLLED |
Took control of the agent's screen |
Someone took control. At most one row per person and agent every 10 minutes. |
AGENT_SCREEN_CONTROL_ENDED |
Control of the agent's screen ended after 4 minutes 10 seconds: handed back |
A Take Control session ended. One row for every session. |
userUuid and user name the person. The first two rows carry no summary, unless an API key opened the screen (see below). AGENT_SCREEN_CONTROL_ENDED carries summary: { seconds, reason }: how long control lasted, in seconds from when it started, and why it ended:
reason |
The title ends with | When |
|---|---|---|
hand_back |
handed back |
Hand Back, or the screen was closed in the panel. |
time_limit |
the time limit was reached |
15 minutes in control. |
idle |
no keyboard or mouse input for a while |
2 minutes without input. |
disconnect |
the connection closed |
The tab closed, the connection dropped, or the agent's computer closed the connection. |
taken_over |
control was taken in another session |
Someone took control in another tab or on another device. |
access_lost |
access to the agent's screen ended |
Screen was turned off in the agent's settings, or Take Control stopped applying to the person. |
agent_stopped |
the agent stopped |
The agent stopped or restarted. |
input_refused |
the screen refused the browser's input |
Input arrived too fast, or the screen didn't accept it. |
{
"ts": "2026-11-19T18:24:10.000Z",
"kind": "AGENT_SCREEN_CONTROL_ENDED",
"title": "Control of the agent's screen ended after 4 minutes 10 seconds: handed back",
"ok": true,
"summary": { "seconds": 250, "reason": "hand_back" },
"userUuid": "ada-uuid",
"user": {
"uuid": "ada-uuid",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"username": "ada",
"avatar": "https://cdn.wiro.ai/avatars/ada.webp",
"avatarinitials": "AL"
}
}
Read the rows in the panel under the agent's Logs, which its owner and the team's admins can open, or with POST /UserAgent/Logs and LogsFile, which also take an API key (LogsList lists the days that have rows). The owner's Account Activity page at wiro.ai/panel/account/activity lists them too, by kind. A change to the screen setting writes an AGENT_SETTINGS_UPDATED row: Agent settings updated: screen off or screen on. A browser reset writes an AGENT_BROWSER_RESET row: Agent browser reset (see Resetting the Browser).
With a project API key. A screen your app opens with a key adds the same rows, named after the key's owner, the person who created its project, whichever of your users it was for. All of your users count as one: on each agent, a project's key writes at most one Watched the agent's screen row an hour and one Took control of the agent's screen row every 10 minutes, apart from the rows the owner's own sessions in the Wiro panel write. Those two titles end with (API key "<project name>") and carry summary: { "project": "<project name>" }, or end with (via API key) for a personal project's key on a team agent. AGENT_SCREEN_CONTROL_ENDED names the key's owner too: its title ends with (via API key), never with the project name, and its summary stays { seconds, reason }. Keep your own record of which of your users got each ticket (see Screen in Your Own App).
Turning the Screen Off
The Screen is on for every agent by default. The agent's owner or a team admin turns it off with the Screen switch on the agent's Settings tab, or by sending screen: "off" to UpdateSettings with a signed-in session or a project API key. Off closes the Screen for everyone, in the Wiro panel and in every app that shows it: nobody can watch or take control, the Screen button hides, ScreenInfo answers reason: "setting_off", ScreenStart is refused with code 94, and screens that are open, a Take Control session included, close within about half a minute. Turning it back on brings the button back. A change never restarts the agent, and null goes back to "on". Read the value as screen on Detail.
On a team agent whose Chat Mode is "private", the Screen stays closed to the team whatever screen says, and the Settings tab says so.
Resetting the Browser
The agent's browser keeps every sign-in made there, by the agent's chats and by people in control. Reset Browser signs it out of every site: the agent's whole browser profile is deleted, with its sign-ins, cookies, history and saved site data, and the agent restarts with a fresh browser. Its files, memory and Connectors stay as they are.
The agent's owner or a team admin resets it with Reset Browser in the Browser row of the agent's Settings tab, under Screen, or with ResetBrowser. The button works while the agent is starting or running; otherwise the row says "Start the agent to reset its browser." The panel asks first: "Reset this agent's browser?", followed by "The browser is signed out of every site, and its history and saved site data are cleared. The agent restarts. Connectors stay connected." Press Reset Browser there to go ahead. The panel then shows "Browser reset. Agent restarting…", and the agent runs again in about a minute. Each reset adds an AGENT_BROWSER_RESET row, Agent browser reset, to the agent's activity log, with who did it.
Getting Take Control back. A reset is how an agent that was in a team gets Take Control back. Reset its browser once the agent is in its owner's personal workspace; when it runs again, its owner can take control. A reset made while the agent was still in a team doesn't count once it leaves, and moving it into a team again turns Take Control off until the next reset.
Endpoints
Browse the Catalog
POST /Agent/List
Lists available agents in the catalog. This is a public endpoint, so no authentication is required.
| Parameter | Type | Required | Description |
|---|---|---|---|
search |
string | No | Full-text search across agent titles and descriptions |
category |
string | No | Filter by category (e.g. "productivity", "social-media") |
sort |
string | No | Sort column: id, title, slug, status, createdat, updatedat. Default: id |
order |
string | No | Sort direction: ASC or DESC. Default: DESC |
limit |
number | No | Results per page (max 1000). Default: 20 |
start |
number | No | Offset for pagination. Default: 0 |
Response
{
"result": true,
"errors": [],
"total": 12,
"agents": [
{
"guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": "Instagram Manager",
"slug": "instagram-manager",
"headline": "Automate your Instagram presence with AI",
"description": "An autonomous agent that manages your Instagram account...",
"cover": "https://cdn.wiro.ai/uploads/agents/instagram-manager-cover.webp",
"categories": ["social-media", "marketing"],
"samples": ["https://cdn.wiro.ai/uploads/agents/instagram-manager-sample-1.webp"],
"tiers": {
"starter": { "priceUsd": 5, "credits": 500 },
"pro": { "priceUsd": 30, "credits": 3000 },
"max": { "priceUsd": 100, "credits": 10000 }
},
"status": 1,
"createdat": "1711929600",
"updatedat": "1714521600"
}
],
"plans": [
{ "key": "starter", "title": "Starter", "priceUsd": 5, "monthlyCredits": 500, "diskMb": 250 },
{ "key": "pro", "title": "Pro", "priceUsd": 30, "monthlyCredits": 3000, "diskMb": 500 },
{ "key": "max", "title": "Max", "priceUsd": 100, "monthlyCredits": 10000, "diskMb": 1024 }
]
}
Agent/Listreturns the catalog fields plus inlinedtiers, so a catalog card can show the price without a per-rowAgent/Detailcall. The top-levelplanslists the three plans in order with their names (key,title,priceUsd,monthlyCredits,diskMb), the same for every agent. CallPOST /Agent/Detailwithtype: "full"when you need the full template (skills map, credential schema, custom skills, scheduled tasks).
POST /Agent/Detail
Retrieves details for a single agent by guid or slug. This is a public endpoint, so no authentication is required.
| Parameter | Type | Required | Description |
|---|---|---|---|
guid |
string | No* | Agent guid. |
slug |
string | No* | Agent slug (e.g. "instagram-manager"). |
type |
string | No | Pass "full" to also include customskills (the template's strategies a deployer can edit) and scheduledskills (every scheduled task) in the response. Without type: "full", the response carries the catalog header + tiers + plans + tokenRates + credentials + skills + skillsmeta + communicationChannels + extracreditpacks only. |
Note: You must provide either
guidorslug. If both are provided,slugtakes priority. Passtype: "full"when you need to preview custom skill keys and scheduled task cron expressions before deploying; omit it for a lightweight catalog detail call.
Response
{
"result": true,
"errors": [],
"agents": [
{
"guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": "Instagram Manager",
"slug": "instagram-manager",
"headline": "Automate your Instagram presence with AI",
"description": "An autonomous agent that manages your Instagram account...",
"cover": "https://cdn.wiro.ai/uploads/agents/instagram-manager-cover.webp",
"categories": ["social-media", "marketing"],
"samples": ["https://cdn.wiro.ai/uploads/agents/instagram-manager-sample-1.webp"],
"tiers": {
"starter": { "priceUsd": 5, "credits": 500 },
"pro": { "priceUsd": 30, "credits": 3000 },
"max": { "priceUsd": 100, "credits": 10000 }
},
"plans": [
{ "key": "starter", "title": "Starter", "priceUsd": 5, "monthlyCredits": 500, "diskMb": 250 },
{ "key": "pro", "title": "Pro", "priceUsd": 30, "monthlyCredits": 3000, "diskMb": 500 },
{ "key": "max", "title": "Max", "priceUsd": 100, "monthlyCredits": 10000, "diskMb": 1024 }
],
"tokenRates": {
"default_model": "openai/gpt-5.6-sol",
"fallback_rate": { "input_per_1m": 625, "output_per_1m": 3750, "cached_input_per_1m": 62.5, "cache_write_per_1m": 781.25 },
"models": {
"openai/gpt-5.6-sol": { "input_per_1m": 625, "output_per_1m": 3750, "cached_input_per_1m": 62.5, "cache_write_per_1m": 781.25, "selectable": true, "label": "GPT-5.6 Sol", "tier": "premium" },
"openai/gpt-5.6-terra": { "input_per_1m": 250, "output_per_1m": 1500, "cached_input_per_1m": 25, "cache_write_per_1m": 312.5, "selectable": true, "label": "GPT-5.6 Terra", "tier": "balanced" },
"openai/gpt-5.6-luna": { "input_per_1m": 25, "output_per_1m": 150, "cached_input_per_1m": 2.5, "cache_write_per_1m": 31.25, "selectable": true, "label": "GPT-5.6 Luna", "tier": "cheap" }
}
},
"skills": ["int-instagram-post", "int-wiro-aimodels"],
"skillsmeta": {
"int-instagram-post": {
"name": "int-instagram-post",
"title": "Instagram Post",
"icon": "https://wiro.ai/images/icons/skills/instagram.svg",
"brand_color": "#e4405f",
"brand_text_color": "#ffffff",
"brand_logo_filter": "brightness(0) invert(1)",
"category": "int",
"docs_url": "integration-instagram-skills",
"credential_key": "instagram",
"requires_credentials": true,
"user_invocable": true,
"deprecated": false,
"replacement": null,
"description": "Post carousel feed and multi-story via Meta Graph API."
},
"int-wiro-aimodels": {
"name": "int-wiro-aimodels",
"title": "Wiro AI Models",
"icon": "https://wiro.ai/images/icons/skills/wiro.svg",
"brand_color": "#00d9a3",
"brand_text_color": "#ffffff",
"brand_logo_filter": "brightness(0) invert(1)",
"category": "int",
"docs_url": "",
"credential_key": "wiro",
"requires_credentials": true,
"user_invocable": true,
"deprecated": false,
"replacement": null,
"description": "Universal access to every AI model on Wiro: text-to-image, text-to-video, image-to-image, image-to-video, audio/voice generation, realtime conversational AI, vision LLMs and more."
}
},
"credentials": {
"instagram": {
"optional": false,
"extra": false,
"_editable": { "appid": true, "appsecret": true, "systemusertoken": true, "accountId": false, "igusername": false },
"_schema": {
"title": "Instagram",
"icon": "https://wiro.ai/images/icons/skills/instagram.svg",
"brand_color": "#e4405f",
"brand_text_color": "#ffffff",
"brand_logo_filter": "none",
"docs_url": "integration-instagram-skills",
"credential_mode": "hybrid",
"connection_modes": ["api_key", "own", "wiro"],
"default_connection_mode": "api_key",
"mode_badges": { "api_key": "Recommended", "own": "Advanced" },
"wiro_connect_pending": true,
"channel": null,
"oauth_provider": {
"auth_method_value": "wiro",
"connect_endpoint": "/UserAgentOAuth/OAuthConnect",
"disconnect_endpoint": "/UserAgentOAuth/OAuthDisconnect",
"status_endpoint": "/UserAgentOAuth/OAuthStatus",
"username_field": "igusername",
"direct_probe": {
"mode": "api_key",
"token_field": "systemusertoken",
"public_account_fields": ["id", "name"]
},
"account_picker": {
"enabled": true,
"multi_select": true,
"set_endpoint": "/UserAgentOAuth/SetPickerAccounts",
"item_value_field": "accountId",
"item_label_field": "igusername"
}
},
"fields": [
{ "key": "appid", "label": "App ID", "type": "text", "required": true, "only_in_modes": ["own"], "pattern": "^[0-9]+$", "oauth_managed": true },
{ "key": "appsecret", "label": "App Secret", "type": "password", "required": true, "show_toggle": true, "only_in_modes": ["own"], "oauth_managed": true },
{ "key": "systemusertoken", "label": "System User Token", "type": "password", "required": true, "show_toggle": true, "only_in_modes": ["api_key"] },
{ "key": "accountId", "label": "Instagram Account ID", "type": "text", "required": true, "readonly_when_connected": true, "pattern": "^[0-9]+$", "auto_filled_by_oauth": true },
{ "key": "igusername", "label": "Connected Account", "type": "text", "required": false, "readonly_when_connected": true, "auto_filled_by_oauth": true }
]
}
}
},
"extracreditpacks": [
{ "packkey": "small", "credits": 1000, "priceusd": 10, "enabled": true },
{ "packkey": "medium", "credits": 5000, "priceusd": 50, "enabled": true },
{ "packkey": "large", "credits": 20000, "priceusd": 200, "enabled": true }
],
"status": 1,
"createdat": "1711929600",
"updatedat": "1714521600"
}
]
}
Agent/Detaildescribes the template, so itscredentialsblock only carries theoptional/extrameta flags (when the template sets them) plus the registry-driven_schema(field labels / types) and_editablemap. It holds no saved values, whoever calls it and whatevertypeis sent. The_connectedflag is per-instance and appears onUserAgent/Detailand theDeployandUpdateresponses, not on the catalog endpoint.planslists the three plans with their names, andextracreditpacksthe three extra credit packs every plan can buy, so a visitor sees both before deploying. A deployed agent'sUserAgent/Detailcarries the same lists underagent(see Extra Credit Packs).
Credential response flags (on UserAgent/Detail and the Deploy and Update responses): every credential object in the top-level credentials tree on the per-instance endpoints carries:
| Flag | Type | Meaning |
|---|---|---|
_connected |
boolean | Connection readiness indicator. true when Wiro has a validated OAuth or hybrid direct connection and every required picker field (customerid, merchantid, channelid, ad-account, page ID, Instagram account ID, etc.) is populated. Plain API-key and service-account providers that do not write connectedat can remain false; use setuprequired to determine overall setup readiness. |
optional |
boolean | true when the template marks this credential as not required for the agent to run. Agents can start even if optional: true credentials are empty. On a custom build, each skill's own connector reads false, and a connector it lists in additional_credential_keys reads true, unless another skill on the agent has that connector as its own. A credential nothing on the agent asks for, such as one whose app keys or token were saved before its connector was added, or that stayed after its connector was removed, reads true, with extra: false. |
extra |
boolean | true when the template groups the credential under "extra integrations" in the UI (disabled by default until the user opts into the skill). |
_editable |
object | Map of fieldname → true|false over the registry schema: false for a field the caller can't write (filled by the connection flow, platform-managed, or computed). |
_schema |
object | Inlined registry descriptor: { title, icon, brand_color, brand_text_color, brand_logo_filter, docs_url, credential_mode, connection_modes[], default_connection_mode, mode_badges, wiro_connect_pending, channel, oauth_provider, fields[] }, where channel describes a communication channel's connector and is null on any other. Lets a UI render the form without a separate Credentials/Detail round-trip. |
Field redaction in responses:
- Saved secrets read as a mask. A field of type
passwordorfileinput-base64(an API key, token or password, or an uploaded key file or service account JSON) reads"••••••••", eight•characters, once a value is saved on the agent, and""while none is. So does such a key in a list's entries, such asfirebase.accounts[].serviceaccountjsonandadjust.apps[].apptoken. This holds for every caller, the agent's owner and team admins included. A saved secret can't be read back with an API key, only replaced: send its new value withCredentialUpsert. A write that sends the mask back keeps the saved value (see Field-level write rules)._connected,_filledand_required_missingstill count what is saved, and the agent receives the values as before. Other values, such as IDs, names, URLs and selections, show as saved, and so doescredentials.wiro.apikey, the agent's project key. For a saved Google service account file, the agent's owner and team admins also get_service_account_emailin the connector's group, which names the account by its email (see Credential object shape). fieldstatus: "oauth_session"fields (accesstoken,refreshtoken,tokenexpiresat,pageAccessToken, etc.) are always stripped from every response.- Schema fields marked
runtime_excluded: true, such as the Instagram and Facebook Pagessystemusertoken, never reach the agent. A saved one reads as the mask, like every saved secret. fieldstatus: "platform"fields (Wiro-managed fields, such as Reddit's three approval flagsdeveloperprofileverified,dataapiaccessapprovedandcommercialwrittenapproval) are stripped from every API response.credentials.wiro.apikeyandcredentials.calendarific.apikeyare operator-supplied user-input fields and appear in the response withfieldstatus: "user"like any other API-key credential:calendarific.apikeyreads as the mask once saved, andwiro.apikeyshows as saved.fieldstatus: "oauth_app"fields (clientid/clientsecret,appid/appsecret) are stripped from Detail responses, even after an own-mode OAuth setup writes them. History writes redactclientsecretto[REDACTED].- A value the agent template holds on a secret field (one Wiro stores encrypted, such as a key, token, password or service account, or an
oauth_managedOAuth app key) is not returned: the field reads empty, and a list entry keeps its place with an empty value, until you save your own. The agent still runs with the template's value, and the card's_filledand_required_missingcount it. Values you save yourself come back to the agent's owner and team admins, each secret as the mask. - Sentinel rows
_isoptional/_isextra: never appear as fields; they're folded into theoptionalandextraflags above.
A plain member of the agent's team gets the same answer with each saved value replaced by [present] and each saved secret by the mask, apart from display-only values such as igusername and the authmethod switch, which show as saved.
Communication channel fields are returned separately from skill and integration credentials:
| Field | Type | Meaning |
|---|---|---|
communicationChannels | array | Full external-channel catalog for this instance. Each row includes id, title, credentialkey, required_fields, capabilities, schema, enabled, configured, and missingfields. Use schema.fields to render the setup form. UserAgent/Detail, UserAgent/Update and UserAgent/Deploy all carry it; Agent/Detail lists the same channels without enabled, configured and missingfields. |
enabledChannels | string[] | External channel IDs whose registry-declared activation credentials are complete. Current values are telegram, slack, and discord. Web chat is always available and is not included. |
teamsessionmode | string | The unified Chat Mode. "private" isolates team members' Wiro web-chat histories and agent memory plus approved external-channel DM operators; "collaborative" shares those histories and runtime contexts. Web and external-channel message lists remain separate transports. Room and thread conversations remain room-scoped. |
The catalog is registry-driven, so all agent templates and existing useragents can discover new channels without adding template-specific rows. Availability does not mean activation: an external channel turns on automatically only when all of its required_fields, including immutable operator IDs, are complete. Existing agents use the normal CredentialUpsert flow; there is no separate channel switch.
Deploy & Manage
All endpoints below require authentication.
POST /UserAgent/Deploy
Creates a new agent instance from a catalog template, or builds a brand-new custom agent (no template).
API agent deployment is prepaid-only. Pass
useprepaid: true+tier. The subscription cost is deducted from your prepaid wallet immediately and the instance is created server-side in one call. There is no API path that accepts a credit card directly; subscriptions from a card can only be created through the Wiro dashboard at wiro.ai/panel/agents. Top up your wallet on wiro.ai/panel/billing before calling Deploy.
Prepaid deploy (useprepaid: true + tier) charges your wallet for the chosen plan's price immediately and inserts a 30-day subscription row (plan: "agent", provider: "prepaid"). Every fresh Deploy lands at status: 6 first. The row is then auto-queued to status: 2 (Queued) once the prepaid subscription is provisioned. No manual UserAgent/Start is needed for prepaid deploys; Wiro starts the agent from the queue.
If you pass credentials, skills, or customskills at the top level of the Deploy body they are applied server-side in the same call. Chat Mode is not a Builder/Deploy input: team deploys start collaborative and personal deploys start private, then owners can change the value with UpdateSettings. Complete channel credential groups activate automatically. Arrays such as allowedusers, Telegram groups, Slack channels, and Discord guilds are validated against the public registry schema. See Agent Credentials → Communication Channels for the channel contract.
| Parameter | Type | Required | Description |
|---|---|---|---|
agentguid |
string | Conditional | The guid of the agent template from the catalog. Required unless custom: true. |
custom |
boolean | Conditional | Pass true to deploy a custom-built agent (no marketplace template). Mutually exclusive with agentguid. See Agent Builder for the full builder flow. |
title |
string | Yes | Display name for your instance. |
description |
string | No | Optional description (custom builds: free-text describing what the agent does). |
cover |
string | No | Optional cover image URL. Custom builds only. Template deploys clone the agent's cover automatically. |
useprepaid |
boolean | Yes | Must be true for API deploys. Pays the plan's price from your wallet balance in a single server-side call. |
tier |
string | No | The plan: "starter" (default, $5 a month with 500 credits), "pro" ($30 with 3,000) or "max" ($100 with 10,000). It sets the price debited from your wallet at deploy time and the monthly credits. The param name is tier. Leave it out for Starter. Any other value is refused with tier must be starter, pro or max, and nothing is created or charged. |
credentials |
object | No | Inline credential groups. If a communication-channel group is included, its matching credentials[credential_key] object must contain all channel required_fields; completeness activates that channel automatically. |
skills |
object | No | Inline skill toggles { "skillname": true | false }. For custom builds this seeds the initial skill set; for template deploys it overlays the template defaults. |
customskills |
array | No | Inline custom skill rows. Each entry: { key, value?, interval?, enabled?, description?, _user_created? }. A scheduled task's interval must be a schedule the agent can run, as in CustomSkillUpsert, and "manual" means no schedule. Otherwise Deploy fails before anything is created or charged, and the error starts with the skill's key. Up to 50 entries; add more with CustomSkillUpsert once the agent is deployed. |
wiroapiallowedpaths |
string[] | No | The Wiro API endpoints this agent may call with its own Wiro project key, as rules in the format described under UpdateSettings. The list is saved before the agent first starts, so it applies from the first turn. An invalid list is rejected with invalid-wiro-api-path-rule and no agent is created. If the list can't be saved, no agent is created either and the call returns Failed to save wiroapiallowedpaths; deploy again. Omit it, or send null, for the default list described under UpdateSettings. |
chatsetup |
string | No | Setup From Chat: where people can change this agent's setup by approving setup cards in chat. "all" (the default) allows the Wiro web chat and messages sent with a project API key, "webchat" only the Wiro web chat, and "off" neither. Omit it, or send null, for "all". Deploying an agent that people who must not change it will talk to, such as your customers' own users? Send "webchat" or "off". Keep "all" when the people in your chats may change the agent, and decide in your own product who may approve: see Agent Chat Integration. See Setup From Chat. |
Headers: Standard API authentication, with x-api-key for key-based projects, or x-nonce + x-signature for signature-based projects (see Authentication). To deploy into a team, use the credentials of a project that belongs to that team: the agent is created in the project's team, and the project's owner must be an admin of that team (otherwise code 97). No extra header is needed.
Team agents: every call runs in the workspace of the project behind your credentials; workspace headers sent with the request are ignored.
Endpoint Team agents UserAgent/DeployA team project's credentials deploy into that team; the project's owner must be a team admin UserAgent/Message/Send,Message/History,Message/Sessions,Message/DeleteSession,Message/RenameSessionThe project's workspace must match the agent's workspace UserAgent/Message/DeleteFor team agents, the project's workspace must match the agent's workspace; it only hides messages sent by the project's owner UserAgent/CancelSubscription,UserAgent/CreateExtraCreditCheckout,UserAgent/UpgradeTier,UserAgent/RenewSubscription,UserAgent/CreateSubscriptionCheckout,UserAgent/PricingPreview,UserAgent/SkillsApply,UserAgent/SkillToggle,UserAgent/CredentialProjectBindThe project's workspace must match the agent's workspace UserAgent/Message/Detail,Message/CancelNo workspace match; they only return or cancel messages sent by the project's owner UserAgent/DetailNo workspace match; the project's owner must own the agent or be a member of its team UserAgent/Update,UserAgent/Start,UserAgent/StopNo workspace match; the project's owner must own the agent or be an admin of its team (plain members get code 97)UserAgent/Realtime/WebStartThe project's owner must have deployed the agent. For a team agent, use that team's project key, or a key whose owner is still a member of the team UserAgent/Realtime/ScreenInfo,UserAgent/Realtime/ScreenStartThe project's owner must have deployed the agent or be an admin of its team. A team project's key opens only that team's agents, and a personal project's key a team agent only while its owner is still a member of the team; a team project's key for a personal agent or another team's agent is refused with code 96UserAgent/MyAgentsLists only the agents in the project's workspace A mismatch returns
"This agent belongs to a team. Switch to the team context to access it.","This agent is in your personal workspace. Switch to personal context to access it."or"This agent belongs to a different team."Use a team project's key for team agents and a personal project's key for personal agents.
Request body: template deploy (recommended API pattern)
{
"agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": "My Instagram Bot",
"useprepaid": true,
"tier": "starter"
}
Request body: custom build (Build Your Own Agent)
{
"custom": true,
"title": "My Custom Sales Agent",
"description": "Watches inbound emails and posts a summary to Slack each morning.",
"useprepaid": true,
"tier": "pro",
"skills": {
"int-gmail-check": true,
"int-wiro-aimodels": true
},
"credentials": {
"gmail": { "account": "agent@company.com", "apppassword": "xxxx xxxx xxxx xxxx" },
"telegram": { "bottoken": "123456:ABC-DEF...", "allowedusers": ["123456789"] }
}
}
Custom builds use the same plans. There is no marketplace template behind a custom agent, and the skills you pick don't change the price: a custom build pays the plan you pass in
tier, like a template deploy.POST /UserAgent/PricingPreviewwithdraft: trueresolves the skill set (withdepends_on) and lists the plans before you call Deploy. Full walkthrough: Agent Builder.
Template deploy vs custom build: what differs server-side
Both paths hit the same endpoint, but a few server-side behaviours diverge:
| Aspect | Template deploy (agentguid) |
Custom build (custom: true) |
|---|---|---|
| Linked marketplace template | Snapshotted from the resolved template | None: no template back-reference |
categories |
Cloned from the agent template | null (custom agents have no marketplace categories) |
cover |
Cloned from agent.cover automatically |
Optional: pass cover in the body if you want one |
| Bundled scheduled tasks | Cloned from the template's preset custom skills | Materialized from the standalone cron registry based on the enabled skill set |
| Onboarding placeholders | None: the template ships its own preset strategies | One invocation-only cs-my-custom-strategy and one scheduled cs-cron-my-scheduled-task are seeded so the panel always has something to render under "Custom Skills" / "Scheduled Tasks" |
| Platform-managed credentials | Set up by Wiro | Set up by Wiro |
| Marketplace run counter | Bumped by 1 | Not touched (custom agents have no template to count against) |
Response
{
"result": true,
"errors": [],
"useragents": [
{
"guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"uuid": "your-user-uuid",
"agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"teamguid": null,
"title": "My Instagram Bot",
"description": null,
"tier": "starter",
"credentials": {
"instagram": {
"_connected": false,
"optional": false,
"extra": false,
"_editable": { "appid": true, "appsecret": true, "systemusertoken": true, "accountId": false, "igusername": false },
"_schema": { "title": "Instagram", "credential_mode": "hybrid", "connection_modes": ["api_key", "own", "wiro"], "default_connection_mode": "api_key", "fields": [ "..." ] },
"authmethod": "",
"igusername": "",
"connectedat": ""
}
},
"skills": ["int-instagram-post", "int-wiro-aimodels"],
"customskills": [],
"scheduledskills": [],
"monthlycredits": 500,
"monthlypriceusd": 5,
"extracredits": 0,
"usedcredits": 0,
"remainingcredits": 500,
"renewalcredits": 500,
"creditperiod": "2026-05",
"creditsyncat": null,
"tokenRates": {
"default_model": "openai/gpt-5.6-sol",
"fallback_rate": { "input_per_1m": 625, "output_per_1m": 3750, "cached_input_per_1m": 62.5, "cache_write_per_1m": 781.25 },
"models": {
"openai/gpt-5.6-sol": { "input_per_1m": 625, "output_per_1m": 3750, "cached_input_per_1m": 62.5, "cache_write_per_1m": 781.25, "selectable": true, "label": "GPT-5.6 Sol", "tier": "premium" },
"openai/gpt-5.6-terra": { "input_per_1m": 250, "output_per_1m": 1500, "cached_input_per_1m": 25, "cache_write_per_1m": 312.5, "selectable": true, "label": "GPT-5.6 Terra", "tier": "balanced" },
"openai/gpt-5.6-luna": { "input_per_1m": 25, "output_per_1m": 150, "cached_input_per_1m": 2.5, "cache_write_per_1m": 31.25, "selectable": true, "label": "GPT-5.6 Luna", "tier": "cheap" }
}
},
"agentModel": {
"chatModel": "openai/gpt-5.6-sol",
"cronModel": "openai/gpt-5.4-mini",
"voicePrepModel": "openai/gpt-5.4-mini",
"voicePostcallModel": "openai/gpt-5.4"
},
"communicationChannels": [
{ "id": "telegram", "credentialkey": "telegram", "title": "Telegram", "required_fields": ["bottoken", "allowedusers"], "capabilities": { "direct": true, "rooms": true, "threads": true, "roles": false, "command_menu": true }, "schema": { "title": "Telegram", "fields": [ "..." ] }, "enabled": false, "configured": false, "missingfields": ["bottoken", "allowedusers"] }
],
"enabledChannels": [],
"teamsessionmode": "private",
"status": 6,
"setuprequired": true,
"pinned": false,
"agent": {
"guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": "Instagram Manager",
"slug": "instagram-manager",
"cover": "https://cdn.wiro.ai/uploads/agents/instagram-manager-cover.webp",
"categories": ["social-media", "marketing"],
"tiers": {
"starter": { "priceUsd": 5, "credits": 500 },
"pro": { "priceUsd": 30, "credits": 3000 },
"max": { "priceUsd": 100, "credits": 10000 }
},
"plans": [
{ "key": "starter", "title": "Starter", "priceUsd": 5, "monthlyCredits": 500, "diskMb": 250 },
{ "key": "pro", "title": "Pro", "priceUsd": 30, "monthlyCredits": 3000, "diskMb": 500 },
{ "key": "max", "title": "Max", "priceUsd": 100, "monthlyCredits": 10000, "diskMb": 1024 }
],
"extracreditpacks": [
{ "packkey": "small", "credits": 1000, "priceusd": 10, "enabled": true },
{ "packkey": "medium", "credits": 5000, "priceusd": 50, "enabled": true },
{ "packkey": "large", "credits": 20000, "priceusd": 200, "enabled": true }
]
},
"createdat": 1714608000,
"updatedat": 1714608000
}
]
}
Status and setuprequired on deploy
The Deploy response reflects the same composed shape you get from UserAgent/Detail, communicationChannels and enabledChannels included. Every fresh Deploy starts at status: 6 (Setup Required). From there, the prepaid path auto-queues the row to status: 2 after subscription provisioning:
| Field | Meaning |
|---|---|
status: 6 |
Setup Required: initial state for every fresh Deploy. With useprepaid: true, auto-queues to status: 2 as soon as the subscription is provisioned, regardless of credential completeness. The agent then starts even if a connector is still missing, and UserAgent/Detail reads setuprequired: true until it is filled. Fill a missing connector with POST /UserAgent/CredentialUpsert or POST /UserAgent/CredentialProjectBind: a running agent restarts to pick it up. A row still at status: 6 needs POST /UserAgent/Update first (any scalar body, even just { "guid": "<useragent-guid>" }) to flip it to status: 0 (Stopped): Update is the endpoint that performs the setuprequired re-check and the 6 → 0 transition. |
status: 2 |
Queued: useprepaid: true charged the wallet, the subscription was provisioned, and Wiro will start the agent. No manual UserAgent/Start is required. |
setuprequired: true |
A non-optional connector is missing, or the row is still at status: 6. At status: 6, Start rejects with Agent setup is not complete. |
setuprequired: false |
All non-optional connectors are set up and the row has left status: 6. A row sitting at Setup Required reads true until a POST /UserAgent/Update call flips it 6 → 0; Start then launches it normally. |
Subscription on deploy: the
subscriptionobject is not included in the Deploy response. A prepaid subscription (plan: "agent", providerprepaid,tiermatches what you passed) is created server-side during the Deploy call. CallPOST /UserAgent/Detailwith the returnedguidto read the subscription object back.
Next steps for the API integration flow:
- Inspect
credentialsin the Deploy response (or callPOST /UserAgent/Detail) to see each provider's fields, theoptional/extraflags, the registry-driven_schema, and the_connectedOAuth status. - Call
POST /UserAgent/CredentialUpsertper provider (or in bulk via thefields[]array) to write API keys, bot tokens, WordPress credentials, etc. For OAuth providers (Meta, Google Ads, HubSpot, …) use the unified/UserAgentOAuth/OAuthConnectflow withcredentialkey(see Agent Credentials & OAuth). To connect the Wiro project the agent runs models with, callPOST /UserAgent/CredentialProjectBind. - Call
POST /UserAgent/CustomSkillUpsertper skill to customize strategy text or cron intervals, if the template exposes any. - Once every non-optional connector is set up,
setuprequiredreadsfalse. The start doesn't wait for it: the prepaid Deploy already queued the agent, Wiro starts it from the queue (2→3(Starting) →4(Running)), and a running agent restarts to pick up each connector you save. - If you want to re-launch a stopped agent (status
0) or recover an errored one (status5), callPOST /UserAgent/Startexplicitly.
Idempotency: duplicate Deploy guard
Deploy rejects a second call from the same caller for the same template and team within a 10-second window. Custom builds (no template) are matched on caller, title and team instead. The rejection carries a top-level existingUserAgentGuid field so callers can adopt the agent that already won the race instead of retrying:
{
"result": false,
"errors": [
{
"code": 99,
"message": "Duplicate deploy: an identical agent (\"My Instagram Bot\") was already deployed 4s ago. Use the existing one, or wait a few seconds and retry."
}
],
"existingUserAgentGuid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321"
}
This prevents a duplicate subscription when a request is retried. existingUserAgentGuid is the only top-level field added on this error. The errors[] array always carries code: 99 for the dedup hit.
Tip: keep your dashboard clean. Deployed instances always land pinned in your account. To unpin programmatically (e.g. after bulk-provisioning one instance per customer) call
POST /UserAgent/Pinwith{ "useragentguid": "...", "pinned": false }immediately after the Deploy call resolves.
POST /UserAgent/MyAgents
Lists all agent instances deployed under your account.
| Parameter | Type | Required | Description |
|---|---|---|---|
sort |
string | No | Sort column: id, title, status, createdat, updatedat, startedat, runningat, stopdat. Default: id |
order |
string | No | Sort direction: ASC or DESC. Default: DESC |
limit |
number | No | Results per page (max 1000). Default: 20 |
start |
number | No | Offset for pagination. Default: 0 |
category |
string | No | Filter by category (comma-separated for multiple) |
Pagination: the response does not include a
totalcount. To know if there are more pages, call withlimit: 20and inspect the returned array length. If it equals yourlimit, paginate further by incrementingstart(e.g.start: 20, 40, 60, ...) until you get fewer rows than yourlimit.
Response
{
"result": true,
"errors": [],
"useragents": [
{
"guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"uuid": "ada-uuid",
"agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"teamguid": null,
"title": "My Instagram Bot",
"description": null,
"cover": null,
"categories": ["social-media", "marketing"],
"tier": "pro",
"nextplan": null,
"monthlypriceusd": 30,
"monthlycredits": 3000,
"extracredits": 5000,
"usedcredits": 1450,
"remainingcredits": 6550,
"renewalcredits": 3000,
"creditperiod": "2026-05",
"creditsyncat": 1714694410,
"status": 4,
"pinned": true,
"teamsessionmode": "private",
"setuprequired": false,
"subscription": {
"plan": "agent",
"status": "active",
"amount": 30,
"currency": "usd",
"currentperiodend": 1717200000,
"renewaldate": "2026-06-01T00:00:00.000Z",
"daysremaining": 62,
"pendingdowngrade": null,
"provider": "prepaid"
},
"agent": {
"guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": "Instagram Manager",
"slug": "instagram-manager",
"description": "An autonomous agent that manages your Instagram Business account.",
"cover": "https://cdn.wiro.ai/uploads/agents/instagram-manager-cover.webp",
"categories": ["social-media", "marketing"],
"tiers": {
"starter": { "priceUsd": 5, "credits": 500 },
"pro": { "priceUsd": 30, "credits": 3000 },
"max": { "priceUsd": 100, "credits": 10000 }
}
},
"enabledSkills": ["int-instagram-post", "int-twitterx-post", "int-wiro-aimodels"],
"tokenRates": {
"default_model": "openai/gpt-5.6-sol",
"fallback_rate": { "input_per_1m": 625, "output_per_1m": 3750, "cached_input_per_1m": 62.5, "cache_write_per_1m": 781.25 },
"models": {
"openai/gpt-5.6-sol": { "input_per_1m": 625, "output_per_1m": 3750, "cached_input_per_1m": 62.5, "cache_write_per_1m": 781.25, "selectable": true, "label": "GPT-5.6 Sol", "tier": "premium" },
"openai/gpt-5.6-terra": { "input_per_1m": 250, "output_per_1m": 1500, "cached_input_per_1m": 25, "cache_write_per_1m": 312.5, "selectable": true, "label": "GPT-5.6 Terra", "tier": "balanced" },
"openai/gpt-5.6-luna": { "input_per_1m": 25, "output_per_1m": 150, "cached_input_per_1m": 2.5, "cache_write_per_1m": 31.25, "selectable": true, "label": "GPT-5.6 Luna", "tier": "cheap" }
}
},
"agentModel": {
"chatModel": "openai/gpt-5.6-sol",
"cronModel": "openai/gpt-5.4-mini",
"voicePrepModel": "openai/gpt-5.4-mini",
"voicePostcallModel": "openai/gpt-5.4"
},
"extracreditsexpiry": 1730419200,
"lastactivityat": 1714698000,
"createdat": 1714608000,
"updatedat": 1714694400,
"queuedat": 1714694395,
"startedat": 1714694400,
"runningat": 1714694410,
"stoppingat": null,
"stopdat": null,
"errordat": null
}
]
}
MyAgentsreturns one row per useragent with its scalar fields, the trimmedagenttemplate summary (noextracreditpacks),subscription,setuprequired(status-based check only),extracredits/remainingcredits/renewalcredits/extracreditsexpiry,lastactivityat, the resolvedenabledSkills(template defaults ∪ user overrides, including transitivedepends_onclosure),tokenRates(per-model token rates, the same map asUserAgent/Detail.tokenRates),agentModel(the resolved chat / cron / voice-prep / voice-postcall model slugs), andenabledCommands(the slash-command allowlist,nullwhen uncustomized). Heavier composed children (credentials,customskills,scheduledskills,skills,skillsmeta,communicationChannels,enabledChannels) are not included. CallUserAgent/Detailon a single guid for the full composed shape.
enabledSkills,tokenRates, andagentModelride on each list row so a chat or pinned-agents UI can decide whether to show the realtime voice-call button (enabledSkillsincludesutil-web-channel) and render the model picker + live token-rate card without round-trippingUserAgent/Detailper row.
POST /UserAgent/Detail
Retrieves full details for a single deployed agent instance, including subscription info, the per-instance credit ledger summary, the resolved per-model token-rate table (tokenRates) plus model selection (agentModel), and the extracreditpacks catalog.
| Parameter | Type | Required | Description |
|---|---|---|---|
guid |
string | Yes | Your UserAgent instance guid |
Response: prepaid instance (the API deploy pattern)
{
"result": true,
"errors": [],
"useragents": [
{
"guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"uuid": "your-user-uuid",
"agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"teamguid": null,
"title": "My Instagram Bot",
"description": null,
"categories": ["social-media", "marketing"],
"cover": "https://cdn.wiro.ai/uploads/agents/instagram-manager-cover.webp",
"tier": "pro",
"nextplan": null,
"status": 4,
"pinned": true,
"setuprequired": true,
"communicationChannels": [
{ "id": "telegram", "credentialkey": "telegram", "title": "Telegram", "required_fields": ["bottoken", "allowedusers"], "capabilities": { "direct": true, "rooms": true, "threads": true, "roles": false, "command_menu": true }, "schema": { "title": "Telegram", "fields": [ "..." ] }, "enabled": false, "configured": false, "missingfields": ["bottoken", "allowedusers"] }
],
"enabledChannels": [],
"teamsessionmode": "private",
"credentials": {
"instagram": {
"_connected": true,
"optional": false,
"extra": false,
"_editable": {
"appid": true,
"appsecret": true,
"systemusertoken": true,
"accountId": false,
"igusername": false
},
"_schema": {
"title": "Instagram",
"icon": "https://wiro.ai/images/icons/skills/instagram.svg",
"brand_color": "#e4405f",
"brand_text_color": "#ffffff",
"brand_logo_filter": "none",
"docs_url": "integration-instagram-skills",
"credential_mode": "hybrid",
"connection_modes": ["api_key", "own", "wiro"],
"default_connection_mode": "api_key",
"mode_badges": {
"api_key": "Recommended",
"own": "Advanced"
},
"wiro_connect_pending": true,
"channel": null,
"oauth_provider": {
"auth_method_value": "wiro",
"connect_endpoint": "/UserAgentOAuth/OAuthConnect",
"disconnect_endpoint": "/UserAgentOAuth/OAuthDisconnect",
"status_endpoint": "/UserAgentOAuth/OAuthStatus",
"direct_probe": {
"mode": "api_key",
"token_field": "systemusertoken",
"public_account_fields": ["id", "name"]
},
"account_picker": {
"enabled": true,
"multi_select": true,
"set_endpoint": "/UserAgentOAuth/SetPickerAccounts",
"item_value_field": "accountId",
"item_label_field": "igusername"
}
},
"fields": [
{
"key": "appid",
"label": "App ID",
"type": "text",
"required": true,
"only_in_modes": ["own"],
"pattern": "^[0-9]+$",
"oauth_managed": true
},
{
"key": "appsecret",
"label": "App Secret",
"type": "password",
"required": true,
"show_toggle": true,
"only_in_modes": ["own"],
"oauth_managed": true
},
{
"key": "systemusertoken",
"label": "System User Token",
"type": "password",
"required": true,
"show_toggle": true,
"only_in_modes": ["api_key"]
},
{
"key": "accountId",
"label": "Instagram Account ID",
"type": "text",
"required": true,
"readonly_when_connected": true,
"pattern": "^[0-9]+$",
"auto_filled_by_oauth": true
},
{
"key": "igusername",
"label": "Connected Account",
"type": "text",
"required": false,
"readonly_when_connected": true,
"auto_filled_by_oauth": true
}
]
},
"_required_missing": false,
"_filled": true,
"authmethod": "api_key",
"systemusertoken": "••••••••",
"accountId": "17841400000000000",
"igusername": "mybrand",
"connectedat": "2026-05-01T12:00:00.000Z",
"tokenexpiresat": ""
},
"telegram": {
"_connected": false,
"optional": true,
"extra": false,
"_editable": {
"bottoken": true,
"allowedusers": true,
"groups": true
},
"_schema": {
"title": "Telegram",
"icon": "https://wiro.ai/images/icons/skills/telegram.svg",
"brand_color": "#24a1de",
"brand_text_color": "#ffffff",
"brand_logo_filter": "brightness(0) invert(1)",
"docs_url": "integration-telegram-skills",
"credential_mode": "api_key",
"connection_modes": [],
"default_connection_mode": null,
"mode_badges": {},
"wiro_connect_pending": false,
"channel": {
"id": "telegram",
"plugin": "telegram",
"required_fields": ["bottoken", "allowedusers"],
"capabilities": { "direct": true, "rooms": true, "threads": true, "roles": false, "command_menu": true }
},
"oauth_provider": null,
"fields": [
{
"key": "bottoken",
"label": "Telegram Bot Token",
"type": "password",
"required": true,
"show_toggle": true
},
{
"key": "allowedusers",
"label": "Allowed Telegram DM User IDs",
"type": "string-array",
"required": true,
"depends_on_field": { "field": "bottoken", "value": "", "operator": "ne" },
"pattern": "^\\d{5,}$"
},
{
"key": "groups",
"label": "Allowed Telegram Groups",
"type": "object-array",
"required": false,
"depends_on_field": { "field": "bottoken", "value": "", "operator": "ne" },
"item_schema": [
{ "key": "chatid", "label": "Group Chat ID", "type": "text", "required": true, "placeholder": "-1001234567890", "pattern": "^-\\d{5,}$" },
{ "key": "allowedusers", "label": "Allowed User IDs", "type": "string-array", "required": true, "pattern": "^\\d{5,}$" }
]
}
]
},
"_required_missing": false,
"_filled": false,
"bottoken": "",
"allowedusers": [],
"groups": []
},
"wordpress": {
"_connected": false,
"optional": false,
"extra": false,
"_editable": {
"url": true,
"user": true,
"apppassword": true
},
"_schema": {
"title": "WordPress",
"icon": "https://wiro.ai/images/icons/skills/wordpress.svg",
"brand_color": "#21759b",
"brand_text_color": "#ffffff",
"brand_logo_filter": "brightness(0) invert(1)",
"docs_url": "integration-wordpress-skills",
"credential_mode": "api_key",
"connection_modes": [],
"default_connection_mode": null,
"mode_badges": {},
"wiro_connect_pending": false,
"channel": null,
"oauth_provider": null,
"fields": [
{
"key": "url",
"label": "WordPress URL",
"type": "url",
"required": true,
"placeholder": "https://yourdomain.com"
},
{
"key": "user",
"label": "Username",
"type": "text",
"required": true
},
{
"key": "apppassword",
"label": "App Password",
"type": "password",
"required": true,
"show_toggle": true
}
]
},
"_required_missing": true,
"_filled": false,
"url": "",
"user": "",
"apppassword": ""
}
},
"customskills": [
{
"key": "cs-content-tone",
"description": "Brand voice + posting rules read by every content-generation skill on this agent.",
"value": "## Brand Voice\nTone: friendly, casual, never salesy.\nTarget Audience: indie devs and side-project builders.\n\n## Hashtag Strategy\nMax 3 per post. Always include #BuildInPublic and #Indie.\n\n## Platform Rules\n- Instagram: square images only, carousels for tutorials.\n- Twitter: thread format for posts longer than 200 chars.",
"enabled": true,
"interval": null,
"_source": "preset-strategy",
"_editable": true,
"_edited": true
},
{
"key": "cs-content-sources",
"description": "RSS / sitemap URLs the agent should poll for new content ideas.",
"value": "## Primary Sources\nhttps://blog.example.com/feed.xml\nhttps://news.ycombinator.com/rss\n\n## CTA URL Pattern\nhttps://example.com/posts/{slug}",
"enabled": true,
"interval": null,
"_source": "preset-strategy",
"_editable": true,
"_edited": false
}
],
"scheduledskills": [
{
"key": "cs-cron-social-content-scanner",
"description": "Polls the content sources every 4 hours and queues fresh ideas for the post generator.",
"value": "Scan the configured RSS / sitemap sources, dedupe against last 14 days, and queue up to 3 fresh items into the post pipeline.",
"enabled": true,
"interval": "0 */4 * * *",
"_source": "skill-bundle",
"_editable": true,
"_edited": false
},
{
"key": "cs-cron-weekly-roundup",
"description": "User-created weekly summary cron that posts a Monday recap to Telegram.",
"value": "Every Monday at 09:00 UTC, summarize last week's published posts (titles + engagement) and post the recap to Telegram.",
"enabled": true,
"interval": "0 9 * * 1",
"_source": "user-created",
"_editable": true,
"_edited": false,
"_user_created": true
}
],
"skills": [
{ "name": "int-instagram-post", "enabled": true, "_edited": false, "_user_created": false },
{ "name": "int-twitterx-post", "enabled": true, "_edited": true, "_user_created": false },
{ "name": "int-wiro-aimodels", "enabled": true, "_edited": false, "_user_created": false }
],
"skillsmeta": {
"int-instagram-post": {
"name": "int-instagram-post",
"title": "Instagram Post",
"icon": "https://wiro.ai/images/icons/skills/instagram.svg",
"brand_color": "#e4405f",
"brand_text_color": "#ffffff",
"brand_logo_filter": "brightness(0) invert(1)",
"category": "int",
"docs_url": "integration-instagram-skills",
"credential_key": "instagram",
"requires_credentials": true,
"user_invocable": true,
"deprecated": false,
"replacement": null,
"description": "Post carousel feed and multi-story via Meta Graph API."
},
"int-twitterx-post": {
"name": "int-twitterx-post",
"title": "Twitter / X Post",
"icon": "https://wiro.ai/images/icons/skills/twitterx.svg",
"brand_color": "#000000",
"brand_text_color": "#ffffff",
"brand_logo_filter": "brightness(0) invert(1)",
"category": "int",
"docs_url": "integration-twitter-skills",
"credential_key": "twitter",
"requires_credentials": true,
"user_invocable": true,
"deprecated": false,
"replacement": null,
"description": "Post single tweets or threads with mixed media via TwitterX API v2."
},
"int-wiro-aimodels": {
"name": "int-wiro-aimodels",
"title": "Wiro AI Models",
"icon": "https://wiro.ai/images/icons/skills/wiro.svg",
"brand_color": "#00d9a3",
"brand_text_color": "#ffffff",
"brand_logo_filter": "brightness(0) invert(1)",
"category": "int",
"docs_url": "",
"credential_key": "wiro",
"requires_credentials": true,
"user_invocable": true,
"deprecated": false,
"replacement": null,
"description": "Universal access to every AI model on Wiro: text-to-image, text-to-video, image-to-image, image-to-video, audio/voice generation, realtime conversational AI, vision LLMs and more."
}
},
"monthlycredits": 3000,
"monthlypriceusd": 30,
"extracredits": 5000,
"usedcredits": 1450,
"remainingcredits": 6550,
"renewalcredits": 3000,
"creditperiod": "2026-05",
"creditsyncat": 1714694410,
"tokenRates": {
"default_model": "openai/gpt-5.6-sol",
"fallback_rate": { "input_per_1m": 625, "output_per_1m": 3750, "cached_input_per_1m": 62.5, "cache_write_per_1m": 781.25 },
"models": {
"openai/gpt-5.6-sol": { "input_per_1m": 625, "output_per_1m": 3750, "cached_input_per_1m": 62.5, "cache_write_per_1m": 781.25, "selectable": true, "label": "GPT-5.6 Sol", "tier": "premium" },
"openai/gpt-5.6-terra": { "input_per_1m": 250, "output_per_1m": 1500, "cached_input_per_1m": 25, "cache_write_per_1m": 312.5, "selectable": true, "label": "GPT-5.6 Terra", "tier": "balanced" },
"openai/gpt-5.6-luna": { "input_per_1m": 25, "output_per_1m": 150, "cached_input_per_1m": 2.5, "cache_write_per_1m": 31.25, "selectable": true, "label": "GPT-5.6 Luna", "tier": "cheap" }
}
},
"agentModel": {
"chatModel": "openai/gpt-5.6-sol",
"cronModel": "openai/gpt-5.4-mini",
"voicePrepModel": "openai/gpt-5.4-mini",
"voicePostcallModel": "openai/gpt-5.4"
},
"chatSetup": "all",
"screen": "on",
"disk": {
"limitMb": 500,
"limitBytes": 524288000,
"usedBytes": 103809024,
"state": "ok",
"measuredAt": "2026-05-03T00:45:00.000Z"
},
"subscription": {
"plan": "agent",
"status": "active",
"amount": 30,
"currency": "usd",
"currentperiodend": 1717200000,
"renewaldate": "2026-06-01T00:00:00.000Z",
"daysremaining": 28,
"pendingdowngrade": null,
"provider": "prepaid"
},
"agent": {
"guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": "Instagram Manager",
"slug": "instagram-manager",
"headline": "Automate your Instagram presence with AI",
"description": "An autonomous agent that manages your Instagram Business account: drafts posts from your RSS feeds, schedules carousels, and replies to DMs.",
"cover": "https://cdn.wiro.ai/uploads/agents/instagram-manager-cover.webp",
"icon": "https://cdn.wiro.ai/uploads/agents/instagram-manager-icon.webp",
"categories": ["social-media", "marketing"],
"tiers": {
"starter": { "priceUsd": 5, "credits": 500 },
"pro": { "priceUsd": 30, "credits": 3000 },
"max": { "priceUsd": 100, "credits": 10000 }
},
"plans": [
{ "key": "starter", "title": "Starter", "priceUsd": 5, "monthlyCredits": 500, "diskMb": 250 },
{ "key": "pro", "title": "Pro", "priceUsd": 30, "monthlyCredits": 3000, "diskMb": 500 },
{ "key": "max", "title": "Max", "priceUsd": 100, "monthlyCredits": 10000, "diskMb": 1024 }
],
"extracreditpacks": [
{ "packkey": "small", "credits": 1000, "priceusd": 10, "enabled": true },
{ "packkey": "medium", "credits": 5000, "priceusd": 50, "enabled": true },
{ "packkey": "large", "credits": 20000, "priceusd": 200, "enabled": true }
]
},
"extracreditsexpiry": 1730419200,
"lastactivityat": 1714698000,
"createdat": 1714608000,
"updatedat": 1714694400,
"queuedat": 1714694395,
"startedat": 1714694400,
"runningat": 1714694410,
"stoppingat": null,
"stopdat": null,
"errordat": null
}
]
}
Field reference
Identity & profile
| Field | Type | Description |
|---|---|---|
guid |
string |
Unique identifier for this agent instance. |
uuid |
string |
Owner account UUID (the user who deployed). |
agentguid |
string|null |
Catalog template GUID this instance was deployed from. null for custom builds (always check agent.custom === true to detect those). |
teamguid |
string|null |
Team GUID when the agent is team-scoped. null for personal agents. |
title |
string |
Display name you gave this instance at deploy. |
description |
string|null |
Long-form description shown on the agent card. |
cover |
string|null |
Per-instance cover URL. Falls back to agent.cover for template deploys; null for custom builds without an uploaded cover. |
categories |
array<string> |
Inherited from the template at deploy; editable via Update. |
pinned |
boolean |
true when the user pinned this instance to the global header dropdown. Mutate via Pin. |
Plan & credits
| Field | Type | Description |
|---|---|---|
tier |
string |
The agent's plan: "starter", "pro" or "max". |
nextplan |
string|null |
The plan the agent moves to at its next renewal, set by a move to a lower plan with UpgradeTier. An agent subscribed before the three plans also shows here the plan it renews on. null when no change is scheduled. Also on MyAgents and PinnedAgents rows. |
monthlypriceusd |
number |
The monthly USD price the agent pays, set at deploy, at a plan change and at renewal. Mirrors subscription.amount. Once a wallet plan has ended, it shows the price the plan renews at, with that plan in tier: RenewSubscription never charges more. |
monthlycredits |
number |
The credits this period grants. After a move to a higher plan inside a period it reads below renewalcredits until the next renewal: the difference in credits comes only for the time left. |
renewalcredits |
number |
The credits a renewal grants on the agent's current plan. When nextplan is set, the next renewal grants that plan's credits instead, as planChange.creditsFromRenewal on PricingPreview shows. |
extracredits |
number |
Active extra-credit balance (sum of non-expired packs from CreateExtraCreditCheckout). |
extracreditsexpiry |
number|null |
Unix timestamp when the earliest extra credit pack expires. null when no extras are active. |
usedcredits |
number |
Credits consumed during the current billing period, reported by the agent runtime. |
remainingcredits |
number |
Computed: max(0, monthlycredits + extracredits - usedcredits). |
creditperiod |
string |
'YYYY-MM' tag of the current billing window. Rolls over on subscription renewal. |
creditsyncat |
number|null |
Unix seconds of the last monthly usage reset, which starts the current credit period (null until the first reset). |
tokenRates |
object|null |
Per-model token-billing rates (credits per 1,000,000 tokens). Shape: { default_model, fallback_rate, models: { "<slug>": { input_per_1m, output_per_1m, cached_input_per_1m?, cache_write_per_1m?, selectable?, label?, tier? } } }. Each turn's cost is metered from these rates (1 credit = $0.01). See Token Billing. null only on registry-read failure. |
agentModel |
object |
The resolved model slugs this instance runs: { chatModel, cronModel, voicePrepModel, voicePostcallModel } (camelCase). Each falls back to the platform default when the operator hasn't overridden it. Change them via POST /UserAgent/UpdateSettings using the lowercase keys chatmodel / cronmodel / voiceprepmodel / voicepostcallmodel. |
enabledCommands |
array<string>|null |
The in-chat slash-command allowlist (camelCase read). null = the operator never customized it, so all slash commands are available. An array (including []) is an explicit allowlist of command keys (no leading slash); [] hides the slash-command menu. Write it via POST /UserAgent/UpdateSettings with the lowercase enabledcommands key. Also present on MyAgents / PinnedAgents rows. |
wiroApiAllowedPaths |
array<string> |
The Wiro API endpoints the agent may call with its own Wiro project key (camelCase read), for example ["POST /v1/Run/*/*", "POST /v1/Task/Detail"]. Always the list that applies: the agent's own list or, when it has none, the default list described under UpdateSettings. [] blocks all of them. Write it via POST /UserAgent/UpdateSettings or at Deploy with the lowercase wiroapiallowedpaths key. Also on the Deploy and Update responses; not on MyAgents / PinnedAgents rows. |
chatSetup |
string|null |
Setup From Chat as it applies to this agent (camelCase read): "all", "webchat" or "off". Write it via POST /UserAgent/UpdateSettings or at Deploy with the lowercase chatsetup key. See Setup From Chat. null when it could not be read. |
screen |
string|null |
The agent's Screen setting: "on" or "off". When it is on, the people who manage the agent can watch its computer live, in the Wiro panel or in your own app with a project API key, and the owner of a personal agent that has never been in a team, or whose browser was reset after it last left one, can take control of it; "off" closes both, everywhere. On a team agent whose Chat Mode (teamsessionmode) is "private", the Screen stays closed to the team even while this reads "on". See Screen and Take Control. Write it via POST /UserAgent/UpdateSettings. null when it could not be read. |
disk |
object |
The agent's disk space and how much of it its files use: { limitMb, limitBytes, usedBytes, state, measuredAt } (see "Disk object" below). The limit follows the agent's tier. See Disk Space. |
Lifecycle
| Field | Type | Description |
|---|---|---|
status |
number |
Current status code (see UserAgent Statuses). |
setuprequired |
boolean |
true if any required credential is missing or incomplete. Mirrors status: 6 plus a fresh check against the live credential rows. |
createdat / updatedat / queuedat / startedat / runningat / stoppingat / stopdat / errordat |
number|null |
Unix seconds for each lifecycle transition. null until the corresponding state is reached. |
lastactivityat |
number|null |
Unix seconds of the agent's last activity: the later of its newest message that isn't deleted and its newest token charge in the credit ledger. null when it has neither yet. Also on MyAgents rows; not on PinnedAgents rows. |
Composed children
| Field | Type | Description |
|---|---|---|
credentials |
object |
Per-provider credential map keyed by credential name (instagram, telegram, wordpress, …). Each provider object carries its saved field values, every saved secret read as the mask "••••••••", plus a fixed metadata header (see "Credential object shape" below). |
customskills |
array |
Composed list of preset strategies and non-cron custom skills (writable instructions). Each entry: { key, description, value, enabled, interval: null, _source, _editable, _edited, _user_created? }. _source ∈ "preset-strategy" | "user-created". |
scheduledskills |
array |
Composed list of cron skills (cs-cron-*). Same shape as customskills plus interval (cron expression). _source ∈ "skill-bundle" (preset cron) | "user-created". |
skills |
array<object> |
Currently-enabled integration skills. Each entry: { name, enabled: true, _edited, _user_created }. Toggle via SkillsApply (single-skill or batch). Note: object array (not string array). |
skillsmeta |
object |
Inline registry snapshot keyed by skill name: title, icon, brand_color, category, docs_url, credential_key, requires_credentials, user_invocable, description. Lets the panel render skill chips without a Skills/List round-trip. |
communicationChannels |
array |
Every external channel with this agent's state: id, title, credentialkey, required_fields, capabilities, schema, enabled, configured and missingfields. Also on the Deploy and Update responses; not on MyAgents / PinnedAgents rows. |
enabledChannels |
array<string> |
The ids of the channels in communicationChannels that are enabled. Same endpoints. |
teamsessionmode |
string |
The unified Chat Mode: "collaborative" or "private" for every agent. For team agents it drives Message/History, Sessions, and native web-chat memory scope; for all agents it also drives Telegram, Slack, and Discord DM scope. Team deployments/transfers default collaborative; personal deployments/team detachments default private. Write with POST /UserAgent/UpdateSettings (team admins / owner only). On a team agent, "private" also keeps the agent's Screen closed to the team (see Who Can Watch). |
timezone |
string|null |
Operator-selected IANA timezone (e.g. "Europe/Istanbul", "America/New_York"). null means UTC. The agent uses this zone for its scheduled tasks, for the times it gives on voice calls and for business hours. Write with POST /UserAgent/UpdateSettings. |
Subscription & template
| Field | Type | Description |
|---|---|---|
subscription |
object|null |
Active subscription info (see "Subscription object" below), or null when the agent has no active subscription. For API-deployed instances this is always provider: "prepaid", plan: "agent". |
agent |
object |
Parent template summary: { guid, title, slug, headline, description, cover, icon, categories, tiers, plans, extracreditpacks }. For custom builds (agent.custom: true) it's a synthesized placeholder instead: { custom: true, slug, cover: null, icon: null, tiers, plans, extracreditpacks }, with no guid, title, headline, description or categories. Read the agent's title and cover from the useragent itself. |
Credential object shape
Every provider entry under credentials.<key> carries:
| Sub-field | Type | Description |
|---|---|---|
_connected |
boolean |
Connection-readiness flag. true when Wiro has a validated OAuth or hybrid direct credential and every required picker field is populated. Plain API-key and service-account providers can remain false; for those use _required_missing or inspect the field values directly. |
optional |
boolean |
true when the agent template marks this credential as optional (the agent can run without it; the dependent skill just won't fire). false for required credentials. On a custom build, each skill's own connector reads false, and a connector it lists in additional_credential_keys reads true, unless another skill on the agent has that connector as its own. A credential nothing on the agent asks for, such as one whose app keys or token were saved before its connector was added, or that stayed after its connector was removed, reads true, with extra: false. |
extra |
boolean |
true when this credential surfaces in the "alternative" / secondary group on the panel (rare; most credentials are primary). |
_editable |
object |
Per-field edit map: { fieldname: true|false }. false means the field is read-only (managed by OAuth, platform-managed, or computed). The frontend uses this to disable inputs. |
_schema |
object |
Inline registry descriptor: title, icon, brand_color, docs_url, credential_mode (oauth, api_key, hybrid, etc.), connection_modes, default_connection_mode, mode_badges, channel (a communication channel's connector; null on any other), oauth_provider, plus a fields[] array describing every input the form should render. Lets the panel build connector cards without a separate Credentials/Detail round-trip. |
_required_missing |
boolean |
true when this connector is required (optional: false) and a required field you fill in is still empty. Drives the "needs attention" bullet on each connector card and the aggregate count badge on the Connectors tab. Always false on an optional connector. A list field counts as empty while its rows hold nothing but a choice or a switch, such as a default platform on an otherwise blank row. A value the agent template holds counts as filled, even on a secret field that reads empty here. |
_filled |
boolean |
true when the connector holds what the agent needs: its OAuth connection is made, or at least one field holds a value and no required field you fill in is empty. A value the agent template holds counts, even on a secret field that reads empty here. For setuprequired, an API-key connector counts only the values saved on this agent; see Setup Required. |
connectedat |
string|null |
OAuth and hybrid providers: ISO timestamp of the last successful connection. |
tokenexpiresat |
string|null |
ISO timestamp when the current token expires, or an empty value when the provider reports no fixed expiry. |
_service_account_email |
object |
Only on a connector with a Google service account file (google-drive, google-play, google-calendar and firebase), and only for the agent's owner and team admins. The file itself reads as the mask, so this names the service account it belongs to: its email, the address a Drive folder, the Play Console or a calendar is shared with. { "serviceaccountjson": "agent@acme-project.iam.gserviceaccount.com" } for a file of the connector itself, and for Firebase { "accounts": [{ "serviceaccountjson": "push@acme-project.iam.gserviceaccount.com" }] }, one item per entry of accounts, in its order. A value is "" when nothing is saved or the file doesn't read as a service account key. Nothing else of the file is returned. It can't be written: leave it out of what you send back, since a field name that starts with _ is refused. |
<fieldname> |
string|number|boolean|array |
The field value as you (or the OAuth callback) saved it, returned to the agent's owner and team admins. A saved secret (a password or fileinput-base64 field, or such a key in a list's entries) reads "••••••••" instead, for every caller, and one with nothing saved reads "". Field types match _schema.fields[].type. Never returned: OAuth tokens (oauth_session), OAuth app keys (clientid / clientsecret, appid / appsecret), Wiro-managed fields, and a value the agent template holds on a field Wiro stores encrypted or on an oauth_managed field: such a field reads empty until you save your own. |
Subscription object
| Sub-field | Type | Description |
|---|---|---|
plan |
string |
Always "agent". The plan (Starter, Pro or Max) is the useragent's tier field, not the subscription's. |
status |
string |
"active", "expired", "cancelled", or "refunded". |
amount |
number |
The monthly USD price actually being charged. Mirrors useragent.monthlypriceusd. |
currency |
string |
Always "usd". |
currentperiodend |
number|null |
Unix seconds when the current billing period ends. |
renewaldate |
string|null |
ISO-8601 string of the same period-end timestamp (convenience for display). |
daysremaining |
number |
Days until currentperiodend. |
pendingdowngrade |
string|null |
"cancel" after CancelSubscription; null for normal active subs. A move to a lower plan shows in the agent's nextplan, not here. |
provider |
string |
"prepaid" for every API-deployed subscription. |
Disk object
| Sub-field | Type | Description |
|---|---|---|
limitMb |
number |
The plan's disk space in MB: 250 on Starter, 500 on Pro, 1024 (1 GB) on Max. It follows the agent's tier, so a move to a higher plan raises it as soon as the new plan starts. |
limitBytes |
number |
The same limit in bytes: limitMb × 1024², for example 262144000 for 250 MB. |
usedBytes |
number|null |
The size of the agent's files at the last measurement: its workspace, the media it generated and its temporary files. Chat history and system files don't count. null before the first measurement. |
state |
string|null |
"ok" below 80% of the limit, "almost_full" from 80% and "full" from 100%. While it is "full", the agent can't save new files until some are deleted or the agent moves to a bigger plan. null before the first measurement. |
measuredAt |
string|null |
ISO-8601 time of the last measurement. The files are measured about every 15 minutes while the agent runs. null before the first measurement. |
POST /UserAgent/Update
Updates an agent instance's scalar fields only (title, description, categories, cover URL). A starting (status 3) or running (status 4) agent restarts in two cases: the call changes its title, or the body names none of those four fields, which is how you ask for a restart ({ "guid": "<useragent-guid>" }). The agent is moved to Stopping and re-queued after it fully stops. A description, categories or cover edit, or a title equal to the saved one, doesn't restart it. restarting in the response says which happened.
| Parameter | Type | Required | Description |
|---|---|---|---|
guid |
string | Yes | Your UserAgent instance guid |
title |
string | No | New display name |
description |
string | No | New description (set to empty string or null to clear) |
categories |
array | No | Updated categories. Cannot be empty if provided. |
cover |
string | No | New cover image URL (set to empty string or null to clear). For multipart upload, use POST /UserAgent/Cover instead. |
Scalar-only. Credentials, custom skills, skill toggles, and plan changes use dedicated endpoints:
What you want to change Use Provider credentials (API keys, OAuth settings) POST /UserAgent/CredentialUpsertThe Wiro project the agent runs models with POST /UserAgent/CredentialProjectBindUpload a credential fileinputfield (multipart, e.g. Twilio voice MP3)POST /UserAgent/CredentialFileUploadCustom skill values (strategy text, cron intervals, enabled flag) POST /UserAgent/CustomSkillUpsertRename a user-created custom skill (key + optional description) POST /UserAgent/CustomSkillRenameBrowse alternative templates for a custom skill POST /UserAgent/CustomSkillAlternativesDelete a user-created scheduled task POST /UserAgent/CustomSkillDeleteToggle one or more integration skills on/off POST /UserAgent/SkillsApplyChange the plan (Starter, Pro or Max) POST /UserAgent/UpgradeTierUpload a cover image (multipart) POST /UserAgent/CoverPer-agent settings: time zone, Chat Mode, models, slash commands, Wiro API paths, Setup From Chat and Screen POST /UserAgent/UpdateSettingsSign the agent's browser out of every site (the agent restarts) POST /UserAgent/ResetBrowserView / download / delete activity logs POST /UserAgent/Logs·LogsList·LogsFile·LogsDeleteFollow Scheduled Tasks, background runs and model runs live POST /UserAgent/RunStreamTokenShow the agent's live Screen, and Take Control, in your own app POST /UserAgent/Realtime/ScreenInfo·ScreenStartSoft-delete a useragent POST /UserAgent/DeleteNote:
CredentialUpsertandCredentialProjectBindsave connector fields but do not transitionstatus: 6on their own. After setting up the missing connectors, callPOST /UserAgent/Updateonce (any scalar body works, even just{ "guid": "<useragent-guid>" }) to trigger thesetuprequiredre-check; that's the call that flipsstatus: 6 → 0(Stopped) so the nextStartsucceeds.
Response
A changed title on a running agent:
{
"result": true,
"errors": [],
"restarting": true,
"useragents": [
{
"guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"uuid": "ada-uuid",
"agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"teamguid": null,
"title": "My Instagram Bot",
"description": "Updated description after rename",
"cover": "https://cdn.wiro.ai/uploads/useragents/f8e7d6c5-cover.webp",
"categories": ["social-media", "marketing"],
"tier": "starter",
"monthlypriceusd": 5,
"monthlycredits": 500,
"extracredits": 0,
"usedcredits": 80,
"remainingcredits": 420,
"renewalcredits": 500,
"creditperiod": "2026-05",
"creditsyncat": 1714694400,
"status": 1,
"pinned": false,
"setuprequired": false,
"teamsessionmode": "private",
"timezone": null,
"agent": {
"guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": "Instagram Manager",
"slug": "instagram-manager",
"headline": "Automate your Instagram presence with AI",
"description": "An autonomous agent that manages your Instagram Business account.",
"cover": "https://cdn.wiro.ai/uploads/agents/instagram-manager-cover.webp",
"icon": "https://cdn.wiro.ai/uploads/agents/instagram-manager-icon.webp",
"categories": ["social-media", "marketing"],
"tiers": {
"starter": { "priceUsd": 5, "credits": 500 },
"pro": { "priceUsd": 30, "credits": 3000 },
"max": { "priceUsd": 100, "credits": 10000 }
},
"plans": [
{ "key": "starter", "title": "Starter", "priceUsd": 5, "monthlyCredits": 500, "diskMb": 250 },
{ "key": "pro", "title": "Pro", "priceUsd": 30, "monthlyCredits": 3000, "diskMb": 500 },
{ "key": "max", "title": "Max", "priceUsd": 100, "monthlyCredits": 10000, "diskMb": 1024 }
],
"extracreditpacks": [
{ "packkey": "small", "credits": 1000, "priceusd": 10, "enabled": true },
{ "packkey": "medium", "credits": 5000, "priceusd": 50, "enabled": true },
{ "packkey": "large", "credits": 20000, "priceusd": 200, "enabled": true }
]
},
"createdat": 1714608000,
"updatedat": 1714694500,
"queuedat": 1714694395,
"startedat": 1714694400,
"runningat": 1714694410,
"stoppingat": 1714694500,
"stopdat": null,
"errordat": null
}
]
}
Updatereturns the full composed useragent shape: same composition path asUserAgent/Detail, socredentials,customskills,scheduledskills,skills,skillsmeta,tokenRates,agentModel,communicationChannels,enabledChannels, and theagenttemplate summary (withtiers,plansandextracreditpacks) are all included. The fieldsUpdatecannot safely populate without an extra round-trip (subscription,extracreditsexpiry,lastactivityat) stay omitted. CallUserAgent/Detailnext if you need them. Otherwise the response is suitable for an in-place panel re-render without a follow-up call.
restarting.truewhen this call restarts the agent,falseotherwise. Withtrue, the row shows the transition mid-flight:status: 1(Stopping) with a freshstoppingattimestamp. Wiro re-queues the agent once it has stopped, so it comes back with the new title. A restart request that can't be carried out answersFailed to restart user agent; try again.
POST /UserAgent/UpdateSettings
Writes per-agent preference toggles that are not credentials and not skill rows. Exposes timezone (operator-selected IANA zone the agent uses for scheduled tasks and voice calls), teamsessionmode (the one Chat Mode for team web-chat history and external-channel DMs), the four model overrides (chatmodel, cronmodel, voiceprepmodel, voicepostcallmodel) that choose which LLM the agent uses for chat replies, scheduled (cron) turns, voice-call prep, and the post-call summary turn, enabledcommands (the in-chat slash-command allowlist), wiroapiallowedpaths (the Wiro API endpoints the agent may call with its own Wiro project key), chatsetup (where people can change the agent's setup from chat), and screen (whether the agent's Screen opens, in the Wiro panel and in your own app, for watching its computer live and for Take Control). Submit any subset in the same call: partial updates are supported and untouched fields keep their current value.
Permission: owner or team admin only, as for /UserAgent/Update. Team members cannot change these settings.
Restart: if the agent is starting (status 3) or running (status 4) and the call changes a setting, the agent restarts so it applies: a new time zone, Chat Mode (teamsessionmode), model, slash-command list (enabledcommands) or Wiro API path list (wiroapiallowedpaths), or turning chatsetup on or off. Moving chatsetup between "all" and "webchat" doesn't restart it: Wiro checks that difference on each message. Changing screen never restarts it. A call that changes nothing restarts nothing. For agents in status 0/1/2/5/6 the change applies on the next start.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Your UserAgent instance guid. |
timezone |
string|null | No | IANA timezone identifier (e.g. "Europe/Istanbul", "America/New_York", "Asia/Tokyo"). Pass null, "", or the literal "UTC" to clear the override; the agent then uses UTC. Unknown zones are rejected with invalid-timezone. |
teamsessionmode |
string | No | Unified Chat Mode: "private" isolates each team member's Wiro web-chat history and native agent memory plus each approved external-channel DM operator; "collaborative" shares both runtime contexts. Personal agents can set it because external-channel DMs can have multiple operators. Web and external-channel message lists remain separate transports; room/thread sessions remain room-scoped. Channel activation remains credential-derived. On a team agent, "private" also keeps the agent's Screen closed to the team (see Who Can Watch). |
chatmodel |
string|null | No | Canonical model slug for chat replies (e.g. "openai/gpt-5.6-sol"). Must be a selectable model, i.e. tokenRates.models[<slug>].selectable === true; an unknown / non-selectable slug is rejected with invalid-model-selection. A model that the agent's own Model Access rule blocks is refused with code 92. Pass null or "" to clear the override and fall back to the platform default. |
cronmodel |
string|null | No | Same rules as chatmodel, applied to scheduled (cron) turns. |
voiceprepmodel |
string|null | No | Same rules as chatmodel, applied to the voice-call prep turn (context assembled before a realtime call). |
voicepostcallmodel |
string|null | No | Same rules as chatmodel, applied to the post-call summary turn after a realtime voice call ends. |
enabledcommands |
string[] | No | Allowlist of in-chat slash commands the agent exposes, as an array of command keys without the leading slash (e.g. ["agent_help", "new_session", "agent_status"]). Validated against the command catalog: an unknown key is rejected with invalid-command-selection, a non-array value with invalid-command-list. Order is preserved and duplicates are removed. An empty array [] is valid and hides the slash-command menu entirely. Omit the field to leave the current allowlist untouched. |
wiroapiallowedpaths |
string[]|null | No | Limits the agent's own calls to the Wiro API, the ones it makes with its Wiro project key (for example through int-wiro-aimodels), to the endpoints you list. Each rule is a method in capitals (GET, POST, PUT, PATCH, DELETE or HEAD), one space and a /v1 path, such as "POST /v1/Task/Detail". A * stands for exactly one whole path segment: "POST /v1/Run/*/*" allows every model run, while "POST /v1/Run/x*" is invalid. Up to 64 rules of at most 200 characters each; duplicates are removed and the order is kept. Calls to endpoints that no rule matches are refused. [] refuses every call, model runs included; null removes your list, and the agent goes back to the default list. An invalid rule, or a value that isn't an array, is rejected with invalid-wiro-api-path-rule, and nothing in the request is saved. Omit the field to keep the current list. An agent with no list of its own uses the default list: POST /v1/Run/*/*, POST /v1/Task/Detail, POST /v1/Tool/List, POST /v1/Tool/Detail, POST /v1/Tool/UploadModelPostImage, POST /v1/Tool/GenerateModelPostImage, GET /v1/Tool/GenerateModelPostImage and POST /v1/UserAgent/Message/UploadAsset. If a custom skill of yours calls another endpoint, send a list that includes it. |
chatsetup |
string|null | No | Setup From Chat: where people can change the agent's setup by approving setup cards in chat. "all" (the default): in the Wiro web chat and in messages sent with a project API key, such as from your backend or an MCP client. "webchat": only in the Wiro web chat on wiro.ai. "off": never from chat; the agent says that an agent admin makes the change in the agent's settings. null goes back to "all", and any other value is rejected with chatsetup must be off, webchat or all. Agents that your customers or many people talk to usually choose "webchat" or "off"; see Setup From Chat. Read it back as chatSetup on UserAgent/Detail. |
screen |
string|null | No | Screen: whether the agent's Screen opens, in the Wiro panel and in your own app through ScreenStart with a project API key. The people who manage the agent (its owner and the team's admins) watch its computer live, and the owner of a personal agent that has never been in a team, or whose browser was reset after it last left one, can take control of it. "on" (the default) or "off". "off" closes it for everyone, watching and Take Control alike, in the panel and in your app, and also closes screens that are open, a Take Control session included, within about half a minute. On a team agent whose Chat Mode is "private" the screen stays closed to the team whatever this says. null goes back to "on", and any other value is rejected with screen must be on or off. It never restarts the agent. Read it back as screen on UserAgent/Detail. |
Slash-command catalog. Valid
enabledcommandskeys are:agent_help,new_session,agent_status,agent_limits,last_scan,last_heartbeat,agent_restart,clear_all_sessions,clear_history. Read the agent's current allowlist from theenabledCommandsfield (camelCase) onUserAgent/Detail/MyAgents/PinnedAgents, wherenullmeans the operator never customized it (all commands available) and an array (including[]) is an explicit allowlist.Omitted fields are preserved. The handler distinguishes between "field not in the body" and "field present with
null/""/value", so a POST that carries onlytimezonedoes not touchteamsessionmodeor any model field, and vice versa. Sending an empty body (none of the recognised fields) is rejected withnothing-to-updateto avoid charging a no-op restart.Read vs write casing. You read the current selection from the
agentModelobject onUserAgent/Detail/MyAgents/PinnedAgentsin camelCase (chatModel,cronModel,voicePrepModel,voicePostcallModel); you write it here in lowercase (chatmodel,cronmodel,voiceprepmodel,voicepostcallmodel). The selectable set is exactly the models thattokenRates.modelsmarksselectable: true. There is no separate "list models" endpoint, so readtokenRatesto populate a picker.An agent never manages an account. Calls the agent makes itself to account, agent, team and billing endpoints, such as
/UserAgent/*,/Project/*,/Team/*and/Wallet/*, are refused with HTTP403whateverwiroapiallowedpathsallows:An agent can't call this endpoint. An agent admin changes the agent's setup in its settings or with a setup card in chat.POST /v1/UserAgent/Message/UploadAssetstays open. An agent changes its own setup only through setup cards that an agent admin approves.
Request
# Set IANA timezone only
curl -X POST "https://api.wiro.ai/v1/UserAgent/UpdateSettings" \
-H "Authorization: Bearer $WIRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"timezone": "Europe/Istanbul"
}'
# Clear timezone (back to system default UTC)
curl -X POST "https://api.wiro.ai/v1/UserAgent/UpdateSettings" \
-H "Authorization: Bearer $WIRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"timezone": null
}'
# Change the one Chat Mode for team web chat and external-channel DMs
curl -X POST "https://api.wiro.ai/v1/UserAgent/UpdateSettings" \
-H "Authorization: Bearer $WIRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"teamsessionmode": "collaborative"
}'
# Switch the chat + cron model (each must be selectable; "" / null resets to default)
curl -X POST "https://api.wiro.ai/v1/UserAgent/UpdateSettings" \
-H "Authorization: Bearer $WIRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"chatmodel": "openai/gpt-5.5",
"cronmodel": "openai/gpt-5.4-mini"
}'
# Restrict the in-chat slash-command menu (empty array hides it entirely)
curl -X POST "https://api.wiro.ai/v1/UserAgent/UpdateSettings" \
-H "Authorization: Bearer $WIRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"enabledcommands": ["agent_help", "new_session", "agent_status"]
}'
# Limit the agent's own Wiro API calls to model lookups, model runs and task reads
curl -X POST "https://api.wiro.ai/v1/UserAgent/UpdateSettings" \
-H "Authorization: Bearer $WIRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"wiroapiallowedpaths": ["POST /v1/Tool/List", "POST /v1/Tool/Detail", "POST /v1/Run/*/*", "POST /v1/Task/Detail"]
}'
# Let setup changes from chat come only from the Wiro web chat
curl -X POST "https://api.wiro.ai/v1/UserAgent/UpdateSettings" \
-H "Authorization: Bearer $WIRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"chatsetup": "webchat"
}'
# Keep this agent's Screen closed: nobody can watch it or take control
curl -X POST "https://api.wiro.ai/v1/UserAgent/UpdateSettings" \
-H "Authorization: Bearer $WIRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"screen": "off"
}'
# Update both preference toggles in one call
curl -X POST "https://api.wiro.ai/v1/UserAgent/UpdateSettings" \
-H "Authorization: Bearer $WIRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"timezone": "Europe/Istanbul",
"teamsessionmode": "collaborative"
}'
Response
{
"result": true,
"errors": []
}
Light response by design.
UpdateSettingsreturns justresult+errors, not the full useragent shape. Pull the refreshed row withPOST /UserAgent/Detailif you need to re-render the panel after the write.
Common errors
| Code | Message key | When |
|---|---|---|
| 400 | request-parameter-required |
useragentguid missing from the body. |
| 400 | nothing-to-update |
Body had none of the recognised fields (timezone, teamsessionmode, a model override, enabledcommands, wiroapiallowedpaths, chatsetup or screen). |
| 400 | invalid-timezone |
timezone is not a valid IANA time zone. |
| 400 | teamsessionmode must be private or collaborative |
teamsessionmode wasn't one of the two supported values. |
| 400 | directchatmode is not accepted |
Obsolete separate mode was sent instead of unified teamsessionmode. |
| 400 | invalid-model-selection |
A model override (chatmodel / cronmodel / voiceprepmodel / voicepostcallmodel) was an unknown or non-selectable slug (tokenRates.models[<slug>].selectable !== true). |
| 400 | invalid-command-list |
enabledcommands was present but not an array. |
| 400 | invalid-command-selection |
enabledcommands contained a key that isn't in the slash-command catalog. |
| 400 | invalid-wiro-api-path-rule |
wiroapiallowedpaths was not an array, or a rule broke the format or the limits above. |
| 400 | chatsetup must be off, webchat or all |
chatsetup wasn't "all", "webchat", "off" or null. |
| 400 | screen must be on or off |
screen wasn't "on", "off" or null. |
| 403 | useragent-access-denied |
Caller is neither the owner nor on the agent's team. |
| 403 | useragent-team-admin-required |
Caller is a member of the agent's team but not a team admin. Carries errors[0].code: 97. |
| 500 | failed-to-update-useragent |
DB write failed (transient, safe to retry). |
POST /UserAgent/ResetBrowser
Signs the agent's browser out of every site. The agent's whole browser profile is deleted, with its sign-ins, cookies, history and saved site data, and the agent restarts with a fresh browser. Its files, memory and Connectors stay as they are. A reset is also how an agent that was in a team gets Take Control back: see Resetting the Browser.
Permission: owner or team admin only, as for UpdateSettings, with a signed-in session or a project API key. Team members can't reset it.
Restart: only a starting (status 3) or running (status 4) agent can be reset. The call moves it to Stopping (status 1), and its browser is reset as it starts again, about a minute later (see Automatic Restart). An agent in any other status is refused, and a refused call restarts nothing.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Your UserAgent instance guid. |
Request
curl -X POST "https://api.wiro.ai/v1/UserAgent/ResetBrowser" \
-H "Authorization: Bearer $WIRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321"
}'
Response
{
"result": true,
"restarting": true,
"errors": []
}
restarting is true once the agent is restarting for the reset; read Detail to follow its status from Stopping back to Running. Each reset adds an AGENT_BROWSER_RESET row, Agent browser reset, to the agent's activity log, with who did it (see Who-did-what rows).
Common errors
A refused call answers result: false and restarting: false with one entry in errors, and restarts nothing:
{
"result": false,
"restarting": false,
"errors": [
{
"code": 0,
"message": "The agent is not running. Start it, then reset its browser.",
"time": 1795113000
}
]
}
| Error | Code | When |
|---|---|---|
Request parameter [useragentguid] required |
0 | useragentguid is missing or blank |
This agent's browser can't be reset. |
96 | The agent is Studio or the Workflow Agent |
User agent not found |
95 | Unknown guid, or the agent has been deleted |
You don't have access to this user agent |
96 | The caller is neither the agent's owner nor on its team |
Only a team admin can perform this action on a team-owned agent. |
97 | The caller is a plain member of the agent's team |
The agent is not running. Start it, then reset its browser. |
0 | The agent is stopped (status 0), in error (5) or in Setup Required (6) |
The agent is starting or stopping. Try again once it is running. |
0 | The agent is stopping (status 1) or queued (2) |
Reset Browser is not available for this agent yet. Try again later. |
0 | Reset Browser can't be used on this agent at the moment |
The browser could not be reset just now. Try again in a minute. |
0 | The reset could not be started. Try again in a minute |
POST /UserAgent/Cover
Uploads a new cover image for the agent instance via multipart. Mirrors the /User/Avatar pattern: accepts jpg, png, gif, jpeg, webp; converts it to webp and saves its URL as the agent's cover.
If you already have a hosted URL, use POST /UserAgent/Update with cover: "<url>" instead.
Multipart fields:
| Field | Type | Required | Description |
|---|---|---|---|
useragentguid |
text | Yes | Your UserAgent instance guid |
image |
file | Yes | The cover image file (jpg/png/gif/jpeg/webp, max ~10MB) |
Response
{
"result": true,
"errors": [],
"cover": "https://cdn.wiro.ai/uploads/useragents/f8e7d6c5-b4a3-2190-fedc-ba0987654321-cover.webp",
"useragents": [
{
"guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"uuid": "ada-uuid",
"agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"teamguid": null,
"title": "My Instagram Bot",
"description": null,
"cover": "https://cdn.wiro.ai/uploads/useragents/f8e7d6c5-b4a3-2190-fedc-ba0987654321-cover.webp",
"categories": ["social-media", "marketing"],
"tier": "starter",
"monthlypriceusd": 5,
"monthlycredits": 500,
"extracredits": 0,
"usedcredits": 80,
"remainingcredits": 420,
"renewalcredits": 500,
"creditperiod": "2026-05",
"creditsyncat": 1714694400,
"status": 4,
"pinned": false,
"teamsessionmode": "private",
"agent": {
"guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": "Instagram Manager",
"slug": "instagram-manager",
"headline": "Automate your Instagram presence with AI",
"description": "An autonomous agent that manages your Instagram Business account.",
"cover": "https://cdn.wiro.ai/uploads/agents/instagram-manager-cover.webp",
"icon": "https://cdn.wiro.ai/uploads/agents/instagram-manager-icon.webp",
"categories": ["social-media", "marketing"]
},
"createdat": 1714608000,
"updatedat": 1714694500,
"queuedat": 1714694395,
"startedat": 1714694400,
"runningat": 1714694410,
"stoppingat": null,
"stopdat": null,
"errordat": null
}
]
}
Cover returns scalar useragent fields + the
agenttemplate summary only. Its credit fields read as onDetail(monthlycreditsfor this period,renewalcredits,extracredits,usedcredits,remainingcredits). It does not includesetuprequired,tokenRates,agentModel, or any composed children (credentials,customskills,scheduledskills,skills,skillsmeta,subscription). The endpoint is optimised for the cover refresh round-trip; callUserAgent/Detailafterwards if you need the full composed shape.
POST /UserAgent/CredentialUpsert
Writes one or more credential fields for one or multiple providers in a single call.
If the agent is starting or running, an upsert that changes a saved value triggers an automatic restart. Fields of a sign-in credential (one with an oauth_provider) that isn't connected before or after the save, such as own-mode app keys or a System User token saved before the sign-in or token check, restart nothing: the connection that follows restarts the agent once (see Automatic Restart).
Telegram, Slack, and Discord are optional credential groups. A channel appears in enabledChannels automatically when all of its catalog required_fields are complete. Clear any required field to disable it; there is no separate channel-enable endpoint or persisted switch.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Your UserAgent instance guid |
fields |
array | Yes | One or more field rows. Each row has { credentialkey, fieldname, fieldvalue, fieldstatus?, parentfield?, ordinal? }. You can write to more than one credentialkey in a single request. |
Each field row:
| Field | Type | Description |
|---|---|---|
credentialkey |
string | The provider key: e.g. "instagram", "google-ads", "wordpress", "telegram". Must match one of the credentials declared in credentials on /UserAgent/Detail. |
fieldname |
string | Field inside that credential: e.g. "apikey", "clientid", "bottoken". Must not start with _ (reserved for internal sentinels such as _isoptional, _isextra). |
fieldvalue |
string | number | array | The value to write. An empty string clears an optional single-value field; send [] to clear a list field. Clearing a required field fails validation, except on Telegram, Slack and Discord, where it disables the channel. |
fieldstatus |
string | Server-managed: ignored from the request body for API callers. The value is derived from the registry / OAuth flow on the server side (e.g. user for hand-edited fields, oauth_session for tokens written by the OAuth callback, oauth_app for app credentials, etc.). Do not set this field. It is stripped before any write. |
parentfield |
string | Optional. The key of a list field (e.g. "accounts" for firebase.accounts[]) when the row sets one field of a single entry in that list. A list inside the entry, such as its apps, is sent whole as that field's fieldvalue. |
ordinal |
number | Optional. Array index inside parentfield. Defaults to 0. |
Request
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"fields": [
{ "credentialkey": "wordpress", "fieldname": "url", "fieldvalue": "https://myblog.com" },
{ "credentialkey": "wordpress", "fieldname": "user", "fieldvalue": "admin" },
{ "credentialkey": "wordpress", "fieldname": "apppassword", "fieldvalue": "abcd efgh ijkl mnop" }
]
}'
Response
{ "result": true, "applied": 3, "errors": [] }
applied is the number of rows saved without an error; a row sent with its current value still counts. A secret sent as "••••••••", the mask UserAgent/Detail shows for a saved one, keeps the saved value and isn't counted (see Field-level write rules). Every row is validated before anything is written. If any row fails validation (for example a reserved fieldname, a Wiro-managed field or an OAuth token field), the whole request is rejected and nothing is saved: the response has result: false, one errors entry per invalid row, and no applied. If a save fails after validation has passed, the other rows are still saved and the response has result: false, the applied count, and each failed row in errors. Re-sending the same request is safe.
Twilio Voice: extra response fields. When any
twilio-voicefield is touched,CredentialUpsertalso auto-configures each Twilio phone number'sVoiceUrland surfaces the result on the response:
Field Type Meaning twilioWebhooksUpdatedstring[]E.164 numbers whose VoiceUrlwas just pointed at the Wiro Twilio webhook.twilioWebhookSkippedstringReturned instead of twilioWebhooksUpdatedwhen theVoiceUrlstep was skipped, with the reason: the Twilio credentials are incomplete, the credential has no phone numbers, or none of its numbers is on the Twilio account.twilioWebhooksFailedobject[]One { phoneNumber, error }entry per number whose update Twilio rejected.twilioWebhookErrorstringTop-level message when the entire VoiceUrl-rewrite flow failed (auth error, network outage). The credential rows are still saved. Only the auto-configuration step failed. Treat all four fields as best-effort: the credential write itself never depends on Twilio's API call succeeding. See Twilio Voice Integration for the full lifecycle.
POST /UserAgent/CredentialProjectBind
Connects an agent's Wiro AI Models connector (int-wiro-aimodels, the wiro key under credentials) to one of your Wiro projects. You name the project, and Wiro saves that project's API key on the agent. The agent's model runs are paid from the wallet of the workspace that owns the project.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Your UserAgent instance guid |
projectid |
string | number | Conditional | The project's id from POST /Project/List. A request made with a project API key can leave it out to bind that key's own project. Any other request must send it. |
To pick a project, call POST /Project/List with an empty body ({}). It returns the projects of the workspace you call from, newest first, up to 100. Each row of project has the id to send here and the project's name.
Who can bind which project:
- The caller is the agent's owner or a team admin of its team. With an API key, that is the user who created the key's project.
- The request comes from the agent's workspace: use a team project's key for a team agent and a personal project's key for a personal agent.
- The project belongs to the agent's workspace too. A personal agent takes one of its owner's personal projects. A team agent takes a project of its team: a team admin can bind any of them, and the member who deployed the agent can bind the ones they created.
Request
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialProjectBind" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "projectid": "4821" }'
Response
{
"result": true,
"errors": [],
"applied": 1,
"project": { "id": "4821", "name": "Agent models" },
"restart": "scheduled"
}
| Field | Type | Description |
|---|---|---|
applied |
number |
1 when the agent's saved key changed. 0 when the agent already had this project. |
project |
object |
The bound project: { id, name }, with id as a string. |
restart |
string |
What the call did to the agent. "scheduled": it was starting or running and now restarts with the project's key. "none": nothing changed, or it isn't running and uses the key at its next start. "failed": the key is saved, and the running agent picks it up when you stop and start it. |
Binding the project an agent already has changes nothing and restarts nothing. Changing a project's IP whitelist gives the project a new API secret; to load it, restart the agent with POST /UserAgent/Update and a body of { "guid": "<useragent-guid>" }.
On an agent at status: 6 (Setup Required), call POST /UserAgent/Update with { "guid": "<useragent-guid>" } after binding, as after CredentialUpsert. Binding doesn't change status: Update moves the agent to status: 0 (Stopped) once every required connector is set up, and Start refuses it until then.
If you already hold a project's key, CredentialUpsert with credentialkey wiro and fieldname apikey saves it too.
Common errors
Each of these comes back with result: false, and nothing is saved.
| Error | Code | When |
|---|---|---|
Request parameter [useragentguid] required |
0 | useragentguid is missing |
projectid is required: send the id of one of your projects from Project/List. Only a request made with a project API key may leave it out, to bind that key's own project. |
0 | The request has no projectid and wasn't made with a project API key |
projectid must be a project's id from Project/List. |
0 | projectid isn't a positive whole number |
User agent not found |
95 | Unknown guid, or the agent has been deleted |
You don't have access to this user agent |
96 | The caller is neither the agent's owner nor on its team |
Only a team admin can perform this action on a team-owned agent. |
97 | The caller is a plain member of the agent's team |
This agent belongs to a team. Switch to the team context to access it. |
0 | A team agent called from a personal workspace or a personal project's key |
This agent is in your personal workspace. Switch to personal context to access it. |
0 | A personal agent called from a team workspace or a team project's key |
This agent belongs to a different team. |
0 | A team agent called from another team's workspace or project key |
Project not found. Send the id of one of your projects from Project/List: one you created, or any project of a team you are an admin of. |
0 | The project doesn't exist, or the caller can't bind it |
This is a personal agent: bind one of its owner's personal projects. Its model runs are paid from that wallet. |
0 | A personal agent and a project from another workspace |
This is a team agent: bind one of its team's projects. Its model runs are paid from the team wallet. |
0 | A team agent and a project from another workspace |
This project's API key no longer works: the account that created it is not active, so the agent's model runs would fail. Bind another project. |
0 | The account that created the project is not active |
This project's API key no longer works: the person who created it is no longer in the team, so the agent's model runs would fail. Bind another project of the team. |
0 | The person who created the team project has left the team |
The project could not be bound. Try again. |
0 | Try again |
POST /UserAgent/CredentialFileUpload
Multipart-upload sibling of CredentialUpsert for credential fields whose registry schema declares type: "fileinput", typically large binary assets that don't fit comfortably in a JSON body (e.g. Twilio voice greeting MP3, custom hold music). The endpoint stores the blob under your account's MyUploads area, writes the resulting reference into the credential field the same way CredentialUpsert does, and restarts the agent so it uses the new file.
Unlike CredentialUpsert, this endpoint expects multipart/form-data: pass the metadata as form fields and the blob in a file part.
| Form field | Type | Required | Description |
|---|---|---|---|
useragentguid |
text | Yes | Your UserAgent instance guid |
credentialkey |
text | Yes | Provider key (e.g. twilio-voice). Must declare a fileinput field in its registry schema. |
fieldname |
text | Yes | The exact fieldname whose registry type is "fileinput" (e.g. holdaudio or holdmusic on twilio-voice). |
file |
file | Yes | The blob. Mimetype + size are validated against the registry's filetypes[] whitelist and maxsize (KB) cap. Default cap is 10 MB when the field omits maxsize. |
fileinputvsfileinput-base64. This endpoint is the storage path for thefileinputtype only: the file is stored by Wiro and the credential keeps a reference to it. The companionfileinput-base64type is stored with the credential (encrypted at rest) and is written via the standardCredentialUpsertJSONfields[]array (e.g.serviceaccountjsonongoogle-drive/google-calendar/google-play/firebase,privatekeyonapple-appstore). Sending a base64 field through this endpoint returnsField is not a fileinput type.
Request
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialFileUpload" \
-H "x-api-key: YOUR_API_KEY" \
-F "useragentguid=f8e7d6c5-b4a3-2190-fedc-ba0987654321" \
-F "credentialkey=twilio-voice" \
-F "fieldname=holdaudio" \
-F "file=@/path/to/greeting.mp3;type=audio/mpeg"
Response
{
"result": true,
"errors": [],
"url": "https://cdn.wiro.ai/uploads/users/.../holdaudio_1714694400_8273645.mp3",
"credentialkey": "twilio-voice",
"fieldname": "holdaudio"
}
The url is the public URL of the stored file, which the agent uses at runtime. Read the field again to get its current URL.
Common errors
| Error | When |
|---|---|
File required (form field name: file) |
Missing the file multipart part |
Unknown credential: <key> |
credentialkey not declared in the skill registry |
Unknown field: <name> |
fieldname not in the credential's credential_schema |
Field is not a fileinput type |
The schema field's type is not "fileinput" (use CredentialUpsert instead) |
Invalid file type. Allowed: <list> |
Mimetype not in the registry's filetypes[] whitelist |
File too large. Max: <kb> KB |
Size exceeds the registry's maxsize cap (default 10240 KB / 10 MB) |
Could not resolve upload folder / Upload failed |
The upload failed; usually transient, retry |
POST /UserAgent/CustomSkillUpsert
Writes a single custom skill: either a strategy (instructions read by other skills at runtime) or a scheduled task (cs-cron-*).
The endpoint auto-normalises the skillkey to its canonical form. Bare slugs become cs-<slug>; if you also send interval (a non-empty cron string), the slug is treated as a cron and becomes cs-cron-<slug>. So "weekly-health-check" with interval: "0 9 * * 1" is stored as cs-cron-weekly-health-check. Pass interval (or send the prefixed cs-cron-… key explicitly) to land under Scheduled Tasks. Rows created through this endpoint are stored with usercreated: true, so they can later be renamed or deleted; updating an existing row keeps its current usercreated value, so a preset row stays preset.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Your UserAgent instance guid |
skillkey |
string | Yes | The skill key. Strategies use bare names (e.g. "content-tone" → stored as cs-content-tone). For a scheduled task, send its full key (e.g. "cs-cron-social-content-scanner"), or a bare slug together with interval ("weekly-report" → cs-cron-weekly-report). A cron-<slug> key becomes cs-cron-<slug> too, with or without interval. |
value |
string | No | Strategy body / cron prompt text. Editable for preset strategies and user-created entries; bundled crons silently drop value writes. |
interval |
string | No | Cron expression (e.g. "0 */4 * * *"). Only persisted on cs-cron-* rows. On a scheduled task it must be a schedule the agent can run (see below). |
enabled |
boolean | No | Turn the skill on or off. Writable for both strategies (cs-*) and crons (cs-cron-*). A disabled strategy is suppressed end-to-end (it still appears in the list, but the agent never loads it). Defaults to true on insert. |
description |
string | No | Only persisted for user-created skills (preset descriptions are template-owned). On a preset row, sending the current description back unchanged is ignored; a different text is rejected with customskill-preset-description-not-editable. |
Text edits reach a running agent without a restart. A change to the
valueordescriptionof an existing skill or task goes to a running agent right away, and the agent keeps running; a starting agent restarts to load it. A new skill or task, a newinterval, or turning one on or off withenabledrestarts a starting or running agent, and so does any change tocs-approval-policy. If the running agent can't take the new text, Wiro restarts it instead.restartingin the response says whether the call restarted the agent.
Schedules the agent can't run are refused. A scheduled task's
intervalis a cron expression with five fields,minute hour day month weekday, such as0 9 * * 1-5. A schedule the agent can't run, or one whose date never comes, such as 30 February, is refused before anything is saved, and the error says what is wrong and what to write:0 25 * * *getsThis schedule can't run. The hour field takes 0 to 23. A schedule has five fields: minute hour day month weekday, for example 0 9 * * 1-5., and0 0 30 2 *getsThis schedule never comes up: February has no 30th. Pick a day February has, such as 28.Only a schedule sent in the request is checked, so a task that already has one can still be edited or turned on and off.
Request
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillUpsert" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"skillkey": "content-tone",
"value": "## Brand Voice\nTone: friendly\nTarget Audience: teens on Instagram"
}'
Response
{ "result": true, "errors": [], "restarting": false }
| Field | Type | Description |
|---|---|---|
restarting |
boolean |
true when the call restarted the agent to load the change. false when the agent wasn't starting or running, or got the new text without a restart. |
POST /UserAgent/CustomSkillRename
Renames a user-created custom skill, optionally updating its description in the same atomic write. Only rows with usercreated: true can be renamed. Preset-owned rows are refused with Preset skills cannot be renamed.
The skillkey flavour is preserved: a cs-cron-* scheduled task stays scheduled, a cs-* strategy stays a strategy. Cross-flavour renames are rejected. Delete + re-create via CustomSkillUpsert with the right kind if you need to switch sections.
Version history is migrated under the new key so the full audit chain stays continuous after the rename, and a new rename entry is appended.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Your UserAgent instance guid |
oldskillkey |
string | Yes | The skill's current canonical key (e.g. cs-my-strategy, cs-cron-daily-summary). |
newskillkey |
string | Yes | The new skill key. The server canonicalises bare slugs using the flavour of oldskillkey: if old is cs-cron-* the new slug lands on cs-cron-*; otherwise cs-*. |
description |
string | No | New description. Omit to leave unchanged; pass an empty string to clear. |
Restart. A starting or running agent restarts on success so it uses the renamed key, as it does when a custom skill is added.
Request
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillRename" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"oldskillkey": "cs-my-custom-strategy",
"newskillkey": "cs-my-renamed-strategy",
"description": "Updated note shown next to the name"
}'
Response
{ "result": true, "errors": [], "newskillkey": "cs-my-renamed-strategy" }
Error cases
| Error message key | When |
|---|---|
Preset skills cannot be renamed. |
Target row has usercreated: false (preset-owned). This refusal comes as the sentence, with no message key. |
agent-customskill-rename-flavour-mismatch |
Caller tried to rename cs-cron-* ↔ cs-*. Delete + re-create with the right kind instead. |
agent-customskill-rename-collision |
newskillkey already exists on this useragent. |
agent-customskill-rename-same-key |
oldskillkey equals canonicalised newskillkey: nothing to change. |
agent-customskill-not-found |
oldskillkey does not exist on the useragent. |
POST /UserAgent/CustomSkillAlternatives
Returns a list of alternative starter templates that the panel's custom-skill picker can offer for a given skillkey. Used by the "Browse alternatives" UX when the user wants to swap one bundled cron / strategy for another preset-owned variant without manually rewriting the value body.
This endpoint is read-only: it does not mutate the useragent. Apply a chosen alternative by calling CustomSkillUpsert with the alternative's value (and interval for crons).
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Your UserAgent instance guid (membership check only: the alternatives list is registry-derived, not per-instance). |
skillkey |
string | Yes | The skill the user is looking to swap, usually a cs-* strategy or a cs-cron-* cron currently on the useragent. |
Response
{
"result": true,
"errors": [],
"alternatives": [
{
"title": "Friendly / casual brand voice",
"description": "Tone: warm and approachable. Use first names and contractions.",
"value": "## Brand Voice\nTone: friendly, casual..."
},
{
"title": "Formal / professional brand voice",
"description": "Tone: polished and authoritative. Avoid slang.",
"value": "## Brand Voice\nTone: formal..."
},
{
"title": "Daily morning roundup (cron alt)",
"description": "Posts a 9 AM digest to Telegram with last 24 h activity.",
"value": "Every morning at 09:00 UTC, summarise overnight activity and post the digest to Telegram.",
"intervalexpr": "0 9 * * *"
}
]
}
Each entry carries title, description and value, plus intervalexpr (a cron expression) for cron-flavoured alternatives. The endpoint never returns a key field; alternatives are addressed by their position in the list and applied via CustomSkillUpsert on the current skillkey (so the operator can swap the body of cs-content-tone between presets without renaming it).
When the registry has no alternatives for the requested skillkey, the response is { "result": true, "alternatives": [] }. Empty lists are not an error.
POST /UserAgent/CustomSkillDelete
Removes a user-created custom skill. The endpoint enforces a hybrid delete policy to prevent accidental destruction of registry-owned scaffolding the runtime depends on:
| Row type | Delete result |
|---|---|
User-created (usercreated: true) on any agent |
Allowed: row is hard-deleted, agent restarts. |
Registry-owned / preset-owned (usercreated: false) on a template agent (the skill also exists in the template's preset skills) |
Rejected: "This skill belongs to the agent preset and cannot be deleted." Disable it via CustomSkillUpsert with enabled: false instead. |
Registry-owned (usercreated: false) on a custom-build agent (no preset to compare against) |
Rejected: "This skill is registry-owned and cannot be deleted." Disable it via CustomSkillUpsert with enabled: false instead. Custom builds carry registry-seeded rows (e.g. cs-approval-policy, bundled cs-cron-* clones) whose runtime contract the agent depends on, even though there's no template back-reference. |
In both reject branches the response carries suggestion: "disable-via-upsert" so panel UIs can offer a "Disable instead" CTA without re-querying the registry.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Your UserAgent instance guid |
skillkey |
string | Yes | The skill key to remove. User-created rows only. Registry-owned rows reject with disable-via-upsert. |
Response (delete allowed)
{ "result": true, "errors": [] }
Response (preset-owned, rejected with suggestion)
{
"result": false,
"errors": [
{
"code": 0,
"message": "This skill belongs to the agent preset and cannot be deleted. Use enabled=false to disable it instead."
}
],
"suggestion": "disable-via-upsert"
}
Response (registry-owned on a custom build, rejected with suggestion)
{
"result": false,
"errors": [
{
"code": 0,
"message": "This skill is registry-owned and cannot be deleted. Use enabled=false to disable it instead."
}
],
"suggestion": "disable-via-upsert"
}
POST /UserAgent/CustomSkillHistory
Returns the version history for one custom skill on a useragent: a per-write audit trail with diff metadata + the resolved actor for each entry. Powers the "Version History" modal in the panel; useful for API consumers building audit views.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Your UserAgent instance guid |
skillkey |
string | Yes | Canonical skill key (e.g. "cs-content-tone") |
startdate |
number | No | UTC epoch seconds: return entries on/after this time |
enddate |
number | No | UTC epoch seconds: return entries on/before this time |
Response
{
"result": true,
"errors": [],
"preset_default": {
"value": "## Brand Voice\nTone: friendly...",
"intervalexpr": null,
"enabled": true,
"description": "How the agent should sound across all generated copy."
},
"entries": [
{
"guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"skillkey": "cs-content-tone",
"operation": "upsert",
"value": "## Brand Voice\nTone: friendly\n...",
"intervalexpr": null,
"enabled": true,
"usercreated": false,
"prev_value": "## Brand Voice\nTone: professional\n...",
"prev_interval": null,
"prev_enabled": true,
"after_value": "## Brand Voice\nTone: friendly\n...",
"after_interval": null,
"after_enabled": true,
"changed_fields": ["value"],
"changedby": "ada-uuid",
"changedby_user": {
"uuid": "ada-uuid",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"username": "ada",
"avatar": "https://cdn.wiro.ai/avatars/ada.webp",
"avatarinitials": "AL"
},
"changedat": 1714694410
}
]
}
Field semantics. Each row captures the BEFORE state of the action that produced it (the history entry is written before the change is applied). The server-computed
after_*andprev_*fields give you the resolved AFTER + previous-version snapshots without you having to walk the list manually:
prev_*: value as of the immediately-older entry (nullfor the oldest row).after_*: value the row was left with after this action committed: pulled from the next-newer entry's BEFORE state, or from the skill's current live state for the newest entry.nullwhenoperation: "delete-user"(row was removed).changed_fields[]: names of fields whose value differs from the immediately-older entry. Subset of["value", "interval", "enabled"].changedby_user: resolved actor object (full shape:uuid,firstname,lastname,username,avatar,avatarinitials).nullwhenchangedbyis a system value such as"system"or"backfill-*", or when the user record was deleted.
POST /UserAgent/CustomSkillRevert
Reverts a custom skill to either (a) the agent template's preset default or (b) a specific historical version. Auto-triggers a restart on success unless the action is a no-op.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Your UserAgent instance guid |
skillkey |
string | Yes | Canonical skill key |
source |
string | Yes | "preset" (reset to template default) or "history" (jump to a versionguid) |
versionguid |
string | When source=history |
The entries[].guid from CustomSkillHistory |
Response
{
"result": true,
"errors": [],
"action": "reverted",
"current_value": "## Brand Voice\nTone: ...",
"current_interval": null,
"current_enabled": true
}
action is "reverted", "reset-to-preset", "deleted" (preset removed upstream), or "no-op" (already matches target).
POST /UserAgent/CredentialFieldHistory
Returns the per-field write history for one credential group on a useragent. Sensitive values are redacted at read time as a belt-and-suspenders guard:
oauth_sessionfields (access / refresh tokens) never appear in history at all. They're stripped before persisting.clientsecretand similaroauth_appsecret fields are stored as[REDACTED]in history rows (the live value stays server-side, andUserAgent/Detaildoesn't return it either).- Wiro-managed credentials return an empty
entries[].
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Your UserAgent instance guid |
credentialkey |
string | Yes | Provider key (e.g. "instagram", "wordpress") |
startdate |
number | No | UTC epoch seconds: return entries on/after this time |
enddate |
number | No | UTC epoch seconds: return entries on/before this time |
Response
{
"result": true,
"errors": [],
"entries": [
{
"guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"credentialkey": "instagram",
"fieldname": "igusername",
"fieldvalue": "myaccount",
"fieldstatus": "user",
"parentfield": null,
"ordinal": 0,
"operation": "upsert",
"changedby": "ada-uuid",
"changedby_user": {
"uuid": "ada-uuid",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"username": "ada",
"avatar": "https://cdn.wiro.ai/avatars/ada.webp",
"avatarinitials": "AL"
},
"changedat": 1714694410
},
{
"guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"credentialkey": "instagram",
"fieldname": "clientsecret",
"fieldvalue": "[REDACTED]",
"fieldstatus": "oauth_app",
"parentfield": null,
"ordinal": 0,
"operation": "upsert",
"changedby": "ada-uuid",
"changedby_user": {
"uuid": "ada-uuid",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"username": "ada",
"avatar": "https://cdn.wiro.ai/avatars/ada.webp",
"avatarinitials": "AL"
},
"changedat": 1714600000
}
]
}
changedby_useris the resolved actor object (uuid,firstname,lastname,username,avatar,avatarinitials). It isnullwhenchangedbyis a system value such as"system"or"backfill-*", or when the user record has been deleted.
POST /UserAgent/SkillsApply
Applies a batch of skill toggles in a single transactional unit. This is the only skill-toggle endpoint API consumers should use. Even when you're flipping a single skill, send it as a one-entry skills map. The single-skill SkillToggle endpoint also exists, but SkillsApply is the one to use from the API.
Every plan includes every skill, so a skill change never moves money: the plan's price and credits stay as they are, and the agent needs no active plan for it. Change the plan itself with UpgradeTier.
Designed for both the Skill Editor modal (multiple toggles in one save) and one-off API mutations:
- Triggers exactly one agent restart after all toggles land.
- Uses idempotency: concurrent calls or client retries can't apply the change twice.
- Atomic: the whole batch lands, or none of it does.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Your UserAgent instance guid (template deploy or custom build) |
skills |
object | Yes | Map of { "skillname": true | false } for every skill you want to set. Skills not in the map keep their current state. |
tier |
string | No | Kept for older clients. Skills never change the plan: a value other than the agent's current plan is refused with Change the plan with UpgradeTier. |
idempotencyKey |
string | Yes | Caller-generated unique key (UUID recommended). Replays of the same key return the cached response without applying the change again. |
Headers: No extra header is needed. For team agents, use an API key from a project in the agent's team. Keys from another workspace are rejected.
Request
curl -X POST "https://api.wiro.ai/v1/UserAgent/SkillsApply" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
"skills": {
"int-instagram-post": true,
"int-twitterx-post": true,
"int-reddit-post": false
}
}'
Response (success)
{
"result": true,
"errors": [],
"tier": "pro",
"restartTriggered": true,
"restartedAt": 1714694520,
"stripeProrationApplied": false,
"prepaidWalletDelta": null,
"usedCreditsUsd": 0,
"pricing": {
"previousPriceUsd": 30,
"newPriceUsd": 30,
"delta": 0,
"deltaUsd": 0,
"previousMonthlyCredits": 3000,
"newMonthlyCredits": 3000,
"deltaCredits": 0,
"creditsNow": 0,
"creditsThisPeriod": 3000,
"creditsFromRenewal": 3000,
"periodEnd": null,
"stripeProrationApplied": false,
"prepaidWalletDelta": null,
"usedCreditsUsd": 0,
"enabledSkills": ["int-instagram-post", "int-twitterx-post", "int-wiro-aimodels"]
}
}
Response (no-op short-circuit)
When every entry in your skills map already matches the persisted state, the endpoint returns a fast-path noOp: true reply with no DB writes and no restart. Use this signal to skip your own post-apply UI churn (toast, refresh) on detected no-op submissions.
{
"result": true,
"errors": [],
"noOp": true
}
| Field | Type | Description |
|---|---|---|
noOp |
boolean |
Present and true only on the no-op short-circuit response. Absent on the regular success path. When you see noOp: true, the rest of the field set (tier, restartTriggered, pricing) is omitted, because there was nothing to apply. |
tier |
string |
The agent's plan ("starter", "pro" or "max"), which a skill change never moves. |
restartTriggered |
boolean |
true when the call changed the skill set: a starting or running agent restarts to load it, and a stopped one loads it at its next start. false when nothing on the agent changed. |
restartedAt |
number|null |
Unix seconds when the change was saved and the restart was asked for. null when restartTriggered is false. |
pricing.enabledSkills |
array<string> |
Final enabled skill set including transitive depends_on closure, as a flat array of skill names. The matching useragent.skills array on the next Detail call is an object array ({name, enabled, _edited?, _user_created?}); take .name from each entry to compare. |
pricing.delta / deltaUsd / deltaCredits / creditsNow |
number |
Always 0: a skill change moves no money and no credits. The rest of pricing is kept for older clients and repeats the plan as it stands: its price in previousPriceUsd and newPriceUsd, its credits in previousMonthlyCredits, newMonthlyCredits, creditsThisPeriod and creditsFromRenewal, and periodEnd: null. stripeProrationApplied is always false, prepaidWalletDelta null and usedCreditsUsd 0, in pricing and at the top level. |
Common error codes
| Code | Meaning |
|---|---|
101 |
skillsapply-deps-violation: a final enabled skill has unsatisfied depends_on. Body includes deps[]. |
102 |
skillsapply-conflict: two finally-enabled skills are mutually exclusive. Body includes conflicts[]. |
104 |
skillsapply-in-progress: another SkillsApply is already running on this useragent. Wait and retry. |
105 |
Change the plan with UpgradeTier.: the tier sent is not the agent's current plan. Nothing is changed. Change the plan with UpgradeTier, and send skill changes without tier. |
108 |
skillsapply-db-tx-failed: DB transaction rolled back; safe to retry with a new idempotency key. |
POST /UserAgent/PricingPreview
Previews a plan or skill change without writing anything. It lists the three plans, resolves the skill set (with depends_on) and, for an agent with an active plan, says in planChange what the change would do today. The Build Your Agent and Skill Editor screens call it as the user picks a plan or toggles skills.
Two body shapes:
A. Draft preview (custom builder, no useragent yet)
{
"draft": true,
"tier": "pro",
"skills": ["int-instagram-post", "int-wiro-aimodels"]
}
B. Existing useragent preview
{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"tier": "max",
"skillOverrides": {
"int-instagram-post": true,
"int-reddit-post": false
}
}
| Parameter | Type | Required | Description |
|---|---|---|---|
draft |
boolean | A | When true, no useragent lookup happens; Wiro resolves the skills array directly. Used by Build Your Agent. |
skills |
array<string> | A | Draft mode only: the proposed enabled skill set. |
useragentguid |
string | B | Required for non-draft previews. |
skillOverrides |
object | No | Override the persisted state with { skillname: boolean } for the preview. Omit for "current state" preview. |
tier |
string | No | "starter", "pro" or "max": the plan to preview. Defaults to the agent's plan, or Starter in a draft. The response lists all three plans under tiers. |
Response
A Pro agent on a wallet plan, previewing Max with 15 days left of 30:
{
"result": true,
"errors": [],
"tier": "max",
"totalPriceUsd": 100,
"totalMonthlyCredits": 10000,
"skillBreakdown": [
{ "skill": "int-instagram-post", "priceUsd": 0, "credits": 0, "billing_model": "tokens" },
{ "skill": "int-wiro-aimodels", "priceUsd": 0, "credits": 0, "billing_model": "tokens" }
],
"enabledSkills": ["int-instagram-post", "int-wiro-aimodels"],
"directSkills": ["int-instagram-post"],
"tiers": {
"starter": { "priceUsd": 5, "credits": 500 },
"pro": { "priceUsd": 30, "credits": 3000 },
"max": { "priceUsd": 100, "credits": 10000 }
},
"plans": [
{ "key": "starter", "title": "Starter", "priceUsd": 5, "monthlyCredits": 500, "diskMb": 250 },
{ "key": "pro", "title": "Pro", "priceUsd": 30, "monthlyCredits": 3000, "diskMb": 500 },
{ "key": "max", "title": "Max", "priceUsd": 100, "monthlyCredits": 10000, "diskMb": 1024 }
],
"nextplan": null,
"planChange": {
"change": "upgrade",
"provider": "prepaid",
"fromTier": "pro",
"toTier": "max",
"nextplan": null,
"priceUsd": 100,
"monthlyCredits": 10000,
"effectiveAt": 1714694520,
"newPeriod": false,
"periodEnd": 1715990520,
"secondsLeft": 1296000,
"creditsNow": 3500,
"creditsThisPeriod": 6500,
"creditsFromRenewal": 10000,
"chargeNowUsd": 35
},
"tokenRates": {
"default_model": "openai/gpt-5.6-sol",
"fallback_rate": { "input_per_1m": 625, "output_per_1m": 3750, "cached_input_per_1m": 62.5, "cache_write_per_1m": 781.25 },
"models": {
"openai/gpt-5.6-sol": { "input_per_1m": 625, "output_per_1m": 3750, "cached_input_per_1m": 62.5, "cache_write_per_1m": 781.25, "selectable": true, "label": "GPT-5.6 Sol", "tier": "premium" },
"openai/gpt-5.6-terra": { "input_per_1m": 250, "output_per_1m": 1500, "cached_input_per_1m": 25, "cache_write_per_1m": 312.5, "selectable": true, "label": "GPT-5.6 Terra", "tier": "balanced" },
"openai/gpt-5.6-luna": { "input_per_1m": 25, "output_per_1m": 150, "cached_input_per_1m": 2.5, "cache_write_per_1m": 31.25, "selectable": true, "label": "GPT-5.6 Luna", "tier": "cheap" }
}
}
}
totalPriceUsd and totalMonthlyCredits are the previewed plan's price and credits; the skills never change them. plans lists the three plans with their names. enabledSkills is the full closure (including transitive depends_on); directSkills is just what the user explicitly toggled. Every skillBreakdown entry reads priceUsd: 0 and credits: 0, since every plan includes every skill. tokenRates carries the per-model rates used to meter each turn (see Token Billing). On an existing agent, nextplan is a lower plan already scheduled for its renewal, or null.
planChange comes with a preview of an existing agent that has an active plan, and is null otherwise. planChange.change says what the previewed tier would do: "upgrade" shows the charge and the credits that come with a higher plan, "downgrade" a lower plan that starts at the renewal with nothing charged now, and "none" the agent's own plan or a preview that only changes skills, with no charge and no credit change.
| Field | Type | Description |
|---|---|---|
planChange.change |
string |
"upgrade", "downgrade" or "none". |
planChange.provider |
string |
"prepaid" (wallet plan) or "stripe" (card plan). |
planChange.fromTier / toTier |
string |
The agent's plan and the plan previewed. |
planChange.nextplan |
string|null |
A lower plan already scheduled for the renewal. |
planChange.priceUsd / monthlyCredits |
number |
The previewed plan's monthly price and credits. |
planChange.effectiveAt |
number|null |
Unix seconds when the change would take effect: now for a higher plan on a wallet plan, periodEnd for a lower plan. null for a higher plan on a card plan, which starts once its checkout is paid, and for "none". |
planChange.newPeriod |
boolean |
true for a higher plan on a card plan: the paid checkout starts a new full period with the plan's full credits. |
planChange.periodEnd |
number |
Unix seconds when the current period ends, which is when a lower plan starts. |
planChange.secondsLeft |
number |
Seconds left in the current period. |
planChange.creditsNow |
number |
Credits this period gains now. |
planChange.creditsThisPeriod |
number |
Credits this period grants in all after the change. |
planChange.creditsFromRenewal |
number |
Credits each renewal grants after the change. |
planChange.chargeNowUsd |
number |
What a higher plan costs now, at list price before any discount: the prorated difference on a wallet plan, the plan's full price at the card checkout. 0 for "downgrade" and "none". |
POST /UserAgent/CreateSubscriptionCheckout
Subscribes a useragent that doesn't yet have an active subscription. Wallet is debited, a prepaid subscription row is inserted, and the agent is auto-queued, the same single-call behaviour as Deploy with useprepaid: true. Always pass useprepaid: true from the API.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Your UserAgent instance guid |
useprepaid |
boolean | Yes | Must be true for API consumers. |
tier |
string | No | "starter", "pro" or "max": overrides the useragent's persisted plan so the user can re-subscribe on a different plan without redeploying. Leave it out for the agent's own plan; any other value is refused with tier must be starter, pro or max. |
Response
{
"result": true,
"errors": [],
"subscriptionId": 8421,
"monthlypriceusd": 30,
"monthlycredits": 3000
}
If the useragent already has an active subscription, the call rejects with Subscription already active for this useragent. Cancel or modify the existing subscription instead.
If a card checkout for the agent is still open (for example, one started in the Wiro panel), it is closed before the wallet is charged, so the agent is never paid for twice. The call is refused, and nothing is charged, when:
| Error | When |
|---|---|
A payment for this agent is already being processed. It usually finishes within a minute; refresh to see the subscription. |
A card payment for the agent has gone through and its subscription is still being set up. The response also carries checkoutpending: true; call UserAgent/Detail in a minute instead of retrying |
A checkout for this agent is already being opened. Try again in a moment. |
Another subscription request for the same agent is in progress |
We couldn't confirm this agent's previous checkout. Please try again in a minute. |
The agent's previous card checkout couldn't be checked |
Another payment from this wallet is still going through. Nothing was charged; please try again in a minute. |
Another plan or credit pack payment from the same wallet is still going through |
POST /UserAgent/Start
Starts a stopped agent instance. The agent is moved to Queued (status 2) and then starts. Also valid for agents in Error state (5): Start re-queues them for another launch attempt.
| Parameter | Type | Required | Description |
|---|---|---|---|
guid |
string | Yes | Your UserAgent instance guid |
Response
{
"result": true,
"errors": [],
"useragents": []
}
useragentsis always returned (empty array on Start) because Start returns the standard agent response shape. Onlyresultanderrorscarry the outcome here.
Start will fail (returns { "result": false, "errors": [...] }) if:
- The agent is already running or queued
- The agent is currently stopping
- Setup is incomplete (status
6) - No credits remain (
monthlycredits + extracredits - usedcredits <= 0)
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 agent is shut down gracefully.
| Parameter | Type | Required | Description |
|---|---|---|---|
guid |
string | Yes | Your UserAgent instance guid |
Response
{
"result": true,
"errors": [],
"useragents": []
}
POST /UserAgent/Delete
Soft-deletes a useragent. Delete stamps deletedat (returned in the response) and unpins the agent; it doesn't erase the agent's history (transactions, credential and custom-skill change history, messages). The agent's working files, such as its memory and the files it saved while it ran, are kept for 30 days after the delete and then removed for good; media the agent sent in chat is stored separately and stays. The agent is then excluded from Detail, MyAgents, Start, Stop, the agent runtime and its scheduled jobs, and TransactionList, CredentialFieldHistory, CustomSkillHistory, Logs, LogsList, LogsFile, LogsDelete, RunStreamToken, Message/History, Message/Sessions, Message/DeleteSession, Message/RenameSession and Message/Delete return useragent-not-found (code 95) for it, so export anything you need before deleting.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Your UserAgent instance guid. guid is also accepted as an alias. |
Headers: No extra header is needed. The caller must be the row owner or a team admin (plain team members are rejected with code 97).
Guards (run in this order)
- Access: owner of the row or a team admin of the UA's team. Members get
useragent-team-admin-required(code97); strangers getuseragent-access-denied(code96); unknown / already-deleted rows getuseragent-not-found(code95). - Status: must be in a clean terminal state:
0(Stopped),5(Error), or6(Setup Required);5passes only once the agent no longer holds its runtime. Anything in flight (1Stopping,2Queued,3Starting,4Running) is rejected withuseragent-delete-running, and so is an errored agent that still holds its runtime. Stop the agent first and wait for status0. - Active subscription: a subscription with
status: "active"blocks delete (useragent-delete-sub-active).CancelSubscriptiondoesn't lift this right away: the subscription staysactiveuntil its period ends (cancelsAt) and is then marked expired. An expired, cancelled or refunded subscription, or none at all, passes.
Delete is safe to repeat: calling it again on an agent that's already deleted returns useragent-not-found (code 95, as in guard 1), so treat that code on a retry as already deleted. The stored deletedat never changes.
Response
{
"result": true,
"errors": [],
"useragent": {
"guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"deletedat": 1714694400
}
}
Common errors
| Error code / message | When |
|---|---|
useragent-not-found (95) |
Unknown guid, or the row is already soft-deleted |
useragent-access-denied (96) |
Caller is not the owner and not a member of the UA's team |
useragent-team-admin-required (97) |
Caller is a team member but not a team admin on the UA's team |
useragent-delete-running |
Status is 1 / 2 / 3 / 4, or 5 while the agent still holds its runtime. Call Stop first and retry once status reaches 0 |
useragent-delete-sub-active |
An active subscription is still attached. After CancelSubscription it stays active until the period ends (cancelsAt); retry once it has expired |
POST /UserAgent/Logs
Live activity feed for a useragent: what the agent did, when, and which user triggered it. The agent records one event per skill invocation, scheduled task and user message, grouped by day; this endpoint returns the latest N events for a given date, each with the user who triggered it. What people and API keys did to the agent is in the same list, as AGENT_* rows; see Agent Logs.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Your UserAgent instance guid |
date |
string | No | Activity date in YYYY-MM-DD (or "today"). Default: "today". |
lines |
number | No | Tail size: most recent N rows. Default 200, capped at 5000. |
Headers: No extra header is needed. Access: the agent's owner or a team admin of the agent's team (plain team members are rejected with code 97).
Polling
Poll every 30 seconds or more.
Response
{
"result": true,
"errors": [],
"events": [
{
"ts": "2026-05-03T14:00:03.000Z",
"kind": "token_usage",
"title": "Token Usage",
"model": "openai/gpt-5.4",
"tokens": { "input": 3450, "output": 820, "cacheRead": 2400, "cacheWrite": 0, "total": 6670 },
"tokencost": 5,
"durationMs": 4200,
"calls": 2,
"remainingcredits": 8995,
"userUuid": "ada-uuid",
"user": {
"uuid": "ada-uuid",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"avatar": "https://cdn.wiro.ai/uploads/users/ada-avatar.webp",
"avatarinitials": "AL"
}
},
{
"ts": "2026-05-03T14:00:01.000Z",
"kind": "tool_completed",
"tool": "exec",
"title": "Posted carousel: \"Brand voice teaser\"",
"summary": {
"skill": "int-instagram-post",
"action": "create",
"permalink": "https://www.instagram.com/p/CXY..."
},
"durationMs": 2480,
"ok": true,
"userUuid": "ada-uuid",
"user": {
"uuid": "ada-uuid",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"avatar": "https://cdn.wiro.ai/uploads/users/ada-avatar.webp",
"avatarinitials": "AL"
}
},
{
"ts": "2026-05-03T13:30:00.000Z",
"kind": "cron_finished",
"title": "Cron ran: Scheduled Skill (cs-cron-social-content-scanner)",
"summary": { "jobId": "6b1d9e2f-3a4c-4e5b-8f7a-1c2d3e4f5a6b", "status": "ok" },
"durationMs": 1860,
"ok": true,
"userUuid": "system",
"user": null
}
],
"date": "2026-05-03",
"totalLines": 1428
}
Field reference
| Field | Type | Description |
|---|---|---|
events[] |
array | One row per activity entry, newest first (descending by ts), so events[0] is the most recent event. Do not re-reverse for display. |
events[].ts |
string | ISO-8601 UTC datetime when the event was emitted (e.g. "2026-05-03T14:00:01.000Z"). Parse with Date.parse(ts) for arithmetic. |
events[].kind |
string | Fine-grained event class. One of: "turn_started", "turn_ended" (an LLM turn boundary); "tool_started", "tool_completed" (one pair per tool call); "tool_blocked" (a tool call the agent's safety rules refused); "cron_finished" (a scheduled task finished); "user_message" (a message received on a connected Telegram, Slack or Discord channel, not web chat); "token_usage" (a billed turn's token usage: chat / cron / voice post-call); "token_usage_idempotent" (a replayed usage report, already billed, informational only); "media_relay" (files from a reply were delivered); "background_reply" (a result that finished in the background was delivered to the chat). Rows about what was done to the agent have AGENT_* kinds, and two note rows, "runtime_log_unavailable" and "runtime_log_deleted", say what part of a day is missing; see Agent Logs. Show any kind you don't recognize by its title. |
events[].tool |
string | null | Present on tool_started / tool_completed / tool_blocked. The name of the tool the agent used. |
events[].toolintegration |
string | null | On tool_started / tool_completed when the step works in a connector: the connector's key (for example "wordpress"). Same closed list as on timeline tool blocks. |
events[].toolaction |
string | null | On tool_started / tool_completed when a word fits the step: what it does (for example "click"). Same closed list as on timeline tool blocks. Never set together with toolintegration. |
events[].title |
string | Human-readable one-line description (always present). |
events[].summary |
object | null | Structured event-specific payload. Treat as opaque and render as JSON when expanding. Secret values (apikey, apppassword, clientsecret, bearer, token, …) are masked before the event is written. Keys vary per kind/tool. |
events[].durationMs |
number | null | Wall-clock duration in milliseconds. Populated on tool_completed, turn_ended, cron_finished and token_usage events. |
events[].ok |
boolean | null | true on success, false on failure. Populated on tool_completed, turn_ended and cron_finished events, and always false on tool_blocked. Pair with error for failures. It is always true on AGENT_* rows. A turn_ended for a turn the caller cancelled has no ok, and its title reads Agent turn cancelled. A cron_finished for a Scheduled Task run that the agent's spend limit or Model Access rule paused has no ok either, and its title starts with Paused by a spend limit: or Paused by a Model Access rule:. |
events[].error |
string | null | One-line failure message (when ok: false). |
events[].model |
string | null | Canonical model slug billed for the turn. Present on token_usage / token_usage_idempotent events. |
events[].tokens |
object | null | Token breakdown on token_usage events: { input, output, cacheRead, cacheWrite, total }, nested camelCase (distinct from the flat lowercase inputtokens / outputtokens / … columns on message + transaction rows; same underlying data, different shape). |
events[].tokencost |
number | null | Credits deducted for the turn (1 credit = $0.01). Present on token_usage events. |
events[].calls |
number | null | Number of LLM calls made in the billed turn. Present on token_usage events. |
events[].remainingcredits |
number | null | Credit pool remaining after the deduct. Present on token_usage events. |
events[].userUuid |
string | null | Originating actor's UUID. "system" for cron / internal events. May be missing on older rows, in which case the server falls back to the agent owner. |
events[].user |
object | null | Resolved user shape (uuid, firstname, lastname, email, username, avatar, avatarinitials) when the actor is a real user. null for system events. |
date |
string | The date that was actually read (YYYY-MM-DD). |
totalLines |
number | Total rows for the day, who-did-what rows and notes included, whatever the lines cap. Use this to show "showing X of Y events" headers. |
Reading a stopped agent. When the agent isn't running, or its host doesn't answer, Logs still answers result: true for a day with who-did-what rows. events starts with a runtime_log_unavailable note, followed by those rows, and totalLines counts the note. An earlier day whose log was deleted starts with a runtime_log_deleted note instead. See Agent Logs.
Common errors
| Error | When |
|---|---|
useragentguid is required |
Missing useragentguid in the body |
Agent is not assigned to a worker. It may not be running. |
The agent isn't running on a host (never started, stopped or being moved). Start it and retry |
Worker not found |
The agent's host is not available right now. Retry later |
Agent is temporarily unavailable. Please try again shortly. |
The agent's host did not answer (offline, network blip). Retry |
Logs, LogsFile and LogsList answer with the last three errors only when there are no who-did-what rows to show. LogsDelete needs the agent on a host every time.
POST /UserAgent/LogsList
Lists the dates with activity: days with an activity log and days that only have who-did-what rows. Useful for building a date-picker UI before calling Logs / LogsFile for that day.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Your UserAgent instance guid |
Response
{
"result": true,
"errors": [],
"dates": [
{ "date": "2026-05-03", "sizeBytes": 184320, "compressed": false },
{ "date": "2026-05-02", "sizeBytes": 92160, "compressed": true },
{ "date": "2026-05-01", "sizeBytes": 0, "compressed": false }
]
}
| Field | Type | Description |
|---|---|---|
dates[].date |
string | Activity date in YYYY-MM-DD form. Sorted newest-first. |
dates[].sizeBytes |
number | null | Raw byte size of the file on disk (compressed size if compressed: true). 0 on a day with who-did-what rows and no log file, for example a day whose log was deleted. null when runtimeUnavailable is present. |
dates[].compressed |
boolean | true once the day's log has been compressed (<date>.jsonl.gz); false for the active day's plain .jsonl. |
runtimeUnavailable |
string | "not_running" or "no_answer". Present only when the agent isn't running or its host doesn't answer and the list holds who-did-what days alone. |
note |
string | Present with runtimeUnavailable: The agent's own log days can be read while it runs, so this list may be missing days. for not_running, The agent's own log days could not be read just now, so this list may be missing days. for no_answer. |
Reading a stopped agent. A stopped agent, or one whose host doesn't answer, still answers result: true when it has who-did-what days:
{
"result": true,
"errors": [],
"runtimeUnavailable": "not_running",
"note": "The agent's own log days can be read while it runs, so this list may be missing days.",
"dates": [
{ "date": "2026-05-03", "sizeBytes": null, "compressed": false },
{ "date": "2026-05-01", "sizeBytes": null, "compressed": false }
]
}
The host retains activity files for 180 days (rolling); older dates are removed and won't appear here.
POST /UserAgent/LogsDelete
Deletes the agent's own turns and tool calls for one date, plain or compressed, without waiting for the 180-day rotation. Who-did-what rows stay: the date can stay in LogsList with sizeBytes: 0, and reads of an earlier day you deleted start with a runtime_log_deleted note that says when.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Your UserAgent instance guid |
date |
string | Yes | Activity date to delete (YYYY-MM-DD). |
Headers: No extra header is needed. Access: the agent's owner or a team admin of the agent's team (plain team members are rejected with code 97).
Response
{
"result": true,
"errors": [],
"date": "2026-04-30",
"removed": { "plain": true, "gz": false }
}
Idempotent: deleting an already-gone date returns result: true with removed.plain: false and removed.gz: false.
POST /UserAgent/LogsFile
Downloads the full day's activity log (no lines cap). Use this when you need a complete forensic trace. Logs is for live-tail UX (capped at 5000 rows). The response is the same events[] shape as Logs, plus a truncated flag.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Your UserAgent instance guid |
date |
string | Yes | Activity date to download (YYYY-MM-DD). |
Headers: No extra header is needed. Access: the agent's owner or a team admin of the agent's team (plain team members are rejected with code 97).
Response
{
"result": true,
"errors": [],
"events": [/* …full day, newest first (descending by ts)… */],
"date": "2026-04-30",
"truncated": false
}
events is sorted newest first (descending by ts), the same contract as Logs, so events[0] is the freshest entry whether you're tailing the live day or downloading a historical one. truncated: true only when the day's file is larger than 10 MiB: its newest 10 MiB of events are returned. Who-did-what rows are included, and a stopped agent and a deleted day read as on Logs.
POST /UserAgent/RunStreamToken
Returns a token for following the agent's Scheduled Tasks, background runs and model runs live on the Agent WebSocket. Send it in an agent_run_subscribe frame: the events that follow say when each run starts, which step it is on and when it ends, with labels only. See Following an agent's background runs.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | The guid of your deployed agent |
Headers: No extra header is needed. Access: the agent's owner or a team admin of the agent's team (plain team members are rejected with code 97). A stopped agent gets a token too.
Response
{
"result": true,
"runstreamtoken": "Zr8Qm2Kx7VbN4tLpW1sYc9HdF6gJaE3uTo5iRk0nXqM",
"expiresat": 1793664000,
"errors": []
}
| Field | Type | Description |
|---|---|---|
runstreamtoken |
string | null | An opaque token valid until expiresat, 24 to 48 hours after it is issued. null when the call fails. Keep it private: whoever holds it can follow the agent's runs until it expires. |
expiresat |
number | null | Unix seconds when the token stops working. When less than 12 hours remain, get a new token and subscribe again with it. null when the call fails. |
Common errors
A failed call answers result: false with runstreamtoken and expiresat set to null and one entry in errors.
| Error | Code | When |
|---|---|---|
useragentguid is required |
0 | useragentguid is missing or blank |
User agent not found |
95 | Unknown guid, or the agent has been deleted |
You don't have access to this user agent |
96 | The caller is neither the agent's owner nor on its team |
Only a team admin can perform this action on a team-owned agent. |
97 | The caller is a plain member of the agent's team |
runstream-unavailable |
0 | Following runs live is not available right now. Try again later |
POST /UserAgent/Pin
Pins or unpins an agent instance from the user's pinned-agents quick list. Pinned agents appear in the global header dropdown (PinnedAgents) and get an unread badge from PinnedUnread.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Your UserAgent instance guid |
pinned |
boolean | Yes | true to pin, false to unpin |
Response
{ "result": true, "errors": [] }
POST /UserAgent/PinnedAgents
Lists the user's pinned agents. Returns the same composed shape as MyAgents: every field that appears on a MyAgents row except lastactivityat appears here, just filtered to pinned: true.
No request body fields are required: the workspace of your API key's project scopes the response.
Response
{
"result": true,
"errors": [],
"useragents": [
{
"guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"uuid": "ada-uuid",
"agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"teamguid": null,
"title": "My Instagram Bot",
"description": null,
"cover": null,
"categories": ["social-media", "marketing"],
"tier": "pro",
"nextplan": null,
"monthlypriceusd": 30,
"monthlycredits": 3000,
"extracredits": 5000,
"usedcredits": 1450,
"remainingcredits": 6550,
"renewalcredits": 3000,
"creditperiod": "2026-05",
"creditsyncat": 1714694410,
"status": 4,
"pinned": true,
"teamsessionmode": "private",
"setuprequired": false,
"subscription": {
"plan": "agent",
"status": "active",
"amount": 30,
"currency": "usd",
"currentperiodend": 1717200000,
"renewaldate": "2026-06-01T00:00:00.000Z",
"daysremaining": 28,
"pendingdowngrade": null,
"provider": "prepaid"
},
"agent": {
"guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": "Instagram Manager",
"slug": "instagram-manager",
"description": "An autonomous agent that manages your Instagram Business account.",
"cover": "https://cdn.wiro.ai/uploads/agents/instagram-manager-cover.webp",
"categories": ["social-media", "marketing"],
"tiers": {
"starter": { "priceUsd": 5, "credits": 500 },
"pro": { "priceUsd": 30, "credits": 3000 },
"max": { "priceUsd": 100, "credits": 10000 }
}
},
"enabledSkills": ["int-instagram-post", "int-twitterx-post", "int-wiro-aimodels"],
"tokenRates": {
"default_model": "openai/gpt-5.6-sol",
"fallback_rate": { "input_per_1m": 625, "output_per_1m": 3750, "cached_input_per_1m": 62.5, "cache_write_per_1m": 781.25 },
"models": {
"openai/gpt-5.6-sol": { "input_per_1m": 625, "output_per_1m": 3750, "cached_input_per_1m": 62.5, "cache_write_per_1m": 781.25, "selectable": true, "label": "GPT-5.6 Sol", "tier": "premium" },
"openai/gpt-5.6-terra": { "input_per_1m": 250, "output_per_1m": 1500, "cached_input_per_1m": 25, "cache_write_per_1m": 312.5, "selectable": true, "label": "GPT-5.6 Terra", "tier": "balanced" },
"openai/gpt-5.6-luna": { "input_per_1m": 25, "output_per_1m": 150, "cached_input_per_1m": 2.5, "cache_write_per_1m": 31.25, "selectable": true, "label": "GPT-5.6 Luna", "tier": "cheap" }
}
},
"agentModel": {
"chatModel": "openai/gpt-5.6-sol",
"cronModel": "openai/gpt-5.4-mini",
"voicePrepModel": "openai/gpt-5.4-mini",
"voicePostcallModel": "openai/gpt-5.4"
},
"extracreditsexpiry": 1730419200,
"createdat": 1714608000,
"updatedat": 1714694400,
"queuedat": 1714694395,
"startedat": 1714694400,
"runningat": 1714694410,
"stoppingat": null,
"stopdat": null,
"errordat": null
}
]
}
POST /UserAgent/PinnedUnread
Returns the latest message GUID per pinned agent. Compare each lastmessageguid against the last value you saw client-side to draw an unread badge, the same pattern the Wiro dashboard uses for its global header.
Response
{
"result": true,
"errors": [],
"data": [
{ "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "lastmessageguid": "5d6e7f80-9a1b-4c2d-8e3f-4a5b6c7d8e01" },
{ "useragentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "lastmessageguid": null }
]
}
Voice & Realtime
Endpoints for browser-based realtime voice sessions, the unified call history for both Web and Twilio channels, and the agent's live Screen. Per-channel setup, session handles, and the WebSocket protocols live on the dedicated pages:
| Operation | Endpoint |
|---|---|
| Start a browser realtime voice session | POST /UserAgent/Realtime/WebStart: see Web Voice |
| Cancel a pending realtime session | POST /UserAgent/Realtime/Cancel: see Web Voice, Step 3 |
| List recent realtime call sessions | POST /UserAgent/TwilioCallHistory/List: see Twilio Voice, Call History (returns Twilio and Web channel sessions despite the Twilio-named path). |
| Ask whether the agent's Screen can open, and whether Take Control can | POST /UserAgent/Realtime/ScreenInfo |
| Get a one-time ticket for the Screen socket, to watch or to take control | POST /UserAgent/Realtime/ScreenStart: see Screen and Take Control in Your App |
POST /UserAgent/Realtime/WebStart
Starts a browser-embedded realtime voice session with the agent. Returns two opaque one-time handles, valid for 5 minutes (until expiresAt), and the WebSocket URL the browser opens to stream microphone audio. The browser presents sessionToken as the first WS message ({ type: "session_start", sessionToken }), and cancelToken is for Realtime/Cancel. The WebSocket path carries no session identifier.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Useragent must be in status: 4 and have util-web-channel enabled (Voice Receptionist / Voice Sales Rep presets enable it by default; toggle it on other agents via SkillsApply). |
session_metadata.page_url |
string | No | Page URL the caller opened the mic from (≤ 2048 chars). Echoed back on Call History. |
session_metadata.display_identifier |
string | No | Operator-supplied display name. 1-100 chars, Unicode letters / numbers / spaces / @ . _ - ' +; other characters silently dropped. |
Response
{
"result": true,
"correlationId": "voice_3fK9xQ2LmVb7TzR1pWc8NdYa",
"wsUrl": "wss://socket.wiro.ai/v1/AgentRealtime/Web",
"sessionToken": "<opaque one-time session handle>",
"cancelToken": "<opaque one-time cancel handle>",
"expiresAt": 1748212800000,
"estimatedReadyMs": 8000
}
- Auth: same Bearer / API key path as every other
UserAgent/*endpoint. Bearer requests must come from wiro.ai; API-key requests have no Origin check. - Rate limit: fixed 60 sessions/hour per operator. Sessions that fail to start are not counted.
- Full WebSocket protocol, control frames, and JS snippet are in Web Voice.
Common errors
| Error | When |
|---|---|
useragentguid required |
Missing useragent reference. |
This agent belongs to a team. Switch to the team context to access it. |
Team agent called from a personal workspace or personal project key by a caller who is no longer a member of the agent's team. |
This agent belongs to a different team. |
Team agent called from another team's workspace or project key by a caller who is no longer a member of the agent's team. |
Agent is not running |
Useragent is not in status: 4. |
util-web-channel not enabled |
Toggle the skill via SkillsApply or pick a preset that bundles it. |
Web voice from this origin needs an API key. |
Bearer auth with an Origin outside the allow-list. |
Rate limit: max N web voice sessions per hour |
Operator burned through the per-hour cap. |
POST /UserAgent/Realtime/Cancel
Cancels a WebStart-initiated session before the WebSocket handshake. Use it when the browser can't progress past the mic-permission prompt, or the user changes their mind. The cancel handle works once; reusing it returns invalid token.
| Parameter | Type | Required | Description |
|---|---|---|---|
cancelToken |
string | Yes | The cancelToken returned by WebStart. One-time, valid until expiresAt; only the user who called WebStart can use it. |
Response
{ "result": true, "correlationId": "voice_3fK9xQ2LmVb7TzR1pWc8NdYa", "cancelled": true }
| HTTP | Error |
|---|---|
| 400 | cancelToken required |
| 401 | invalid token (unknown, already used or expired handle) |
| 403 | access denied (the handle was issued to another user) |
Without this call, the session is released after about 5 minutes. Calling
Cancelreleases it right away.
POST /UserAgent/TwilioCallHistory/List
Returns the last N realtime voice sessions for a useragent, covering both Twilio and Web channels despite the Twilio-named path, since both are stored as messages whose metadata.type starts with realtime_session. Owner / team-member access only.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Useragent instance guid. |
limit |
number | No | Max sessions to return. Default 50, hard-capped at 200. Sorted newest-first. |
Response
{
"result": true,
"errors": [],
"data": [
{
"messageguid": "5d6e7f80-9a1b-4c2d-8e3f-4a5b6c7d8e01",
"agenttoken": "8a5b9e2f-4d3c-4a01-9c2e-1b6d4e7a9c5d",
"channel": "twilio",
"callsid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"callerInfo": { "number": "+15551234567", "country": "US" },
"callerProfile": "Returning caller — last asked about pricing. Mentioned company name 'Acme Corp'.",
"status": "realtime_session",
"endReason": "wiro_completed",
"durationSeconds": 137,
"modelSlug": "gpt-realtime-mini",
"startedAt": 1730473321000,
"endedAt": 1730473458000
},
{
"messageguid": "5d6e7f80-9a1b-4c2d-8e3f-4a5b6c7d8e02",
"agenttoken": "8a5b9e2f-4d3c-4a01-9c2e-1b6d4e7a9c5d",
"channel": "web",
"callsid": "voice-call-7f3c2b1d8e",
"callerInfo": { "page_url": "https://example.com/contact", "display_identifier": "+15551234567" },
"callerProfile": null,
"status": "realtime_session",
"endReason": "browser_disconnect",
"durationSeconds": 84,
"modelSlug": "gpt-realtime-mini",
"startedAt": 1730473601000,
"endedAt": 1730473685000
}
]
}
| Field | Type | Description |
|---|---|---|
messageguid |
string | The guid of the message that holds this call. Use it with Message/Detail for the full transcript. |
agenttoken |
string | Useragent token. Same value across all rows for a given agent. |
channel |
"twilio" | "web" |
Which voice surface served the call. |
callsid |
string | Twilio Call SID for channel: "twilio"; the internal session id (voice-call-*) for channel: "web". |
callerInfo |
object | Twilio rows: { number, country } (E.164 + ISO-2). Web rows: { page_url, display_identifier? }, where display_identifier is only present when the embedding page validated a phone-style identifier; page_url is the page hosting the widget. |
callerProfile |
string | null | Free-text summary of the caller that the agent writes before the call. null until it is ready. |
status |
string | realtime_session_incoming (call accepted, prep in flight) → realtime_session_active (audio flowing) → realtime_session (completed normally) or realtime_session_rejected (rejected before active state, with metadata.reason). |
endReason |
string | null | Set on realtime_session rows only. One of: wiro_completed, wiro_cancelled, wiro_disconnect, wiro_error, twilio_disconnect, browser_disconnect, max_duration, spend_limit (a spend limit was reached during the call), balance (the balance ran out during the call). null while the call is still in flight or rejected. |
durationSeconds |
number | null | Total elapsed seconds. null until end. |
modelSlug |
string | null | Realtime model slug used for this call (e.g. gpt-realtime-mini). |
startedAt / endedAt |
number | null | Unix epoch ms. endedAt stays null until the call finishes or is rejected. |
Rows are returned newest-first. Rejected sessions (realtime_session_rejected) are intermixed and carry metadata.reason (visible by reading the same messageguid via Message/Detail) with values: concurrent_limit, agent_prep_timeout, realtime_ws_open_failed, realtime_stream_timeout. Full field reference: Twilio Voice, Call History.
POST /UserAgent/Realtime/ScreenInfo
Says whether the agent's Screen can open for the caller now, and whether Take Control can. Ask it before you offer a Screen button. It never refuses an agent: every no is result: true with available: false and a reason.
Permission: whoever may watch the agent (see Who Can Watch), with a project API key. A key acts as its owner, the person who created its project, and a team project's key opens only that team's agents. A signed-in session works only inside the Wiro panel, so from your own product, call it from your backend with your key. Any other caller, a signed-in session from outside the Wiro panel included, gets available: false with reason: "not_allowed".
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Your UserAgent instance guid. |
Request
curl -X POST "https://api.wiro.ai/v1/UserAgent/Realtime/ScreenInfo" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321"
}'
Response
{
"result": true,
"errors": [],
"available": true,
"canControl": true,
"reason": null
}
When the Screen can't open, here because the agent's screen setting is "off":
{
"result": true,
"errors": [],
"available": false,
"canControl": false,
"reason": "setting_off"
}
| Field | Type | Description |
|---|---|---|
available |
boolean | true when ScreenStart can open a view of the agent's screen for this caller now. |
canControl |
boolean | true when ScreenStart can also open Take Control (control: true) for this caller: the owner of a personal agent that has never been in a team, or whose browser was reset after it last left one, in the panel or with an API key of one of their personal projects. Always false while available is false. |
reason |
string|null | null while available is true; otherwise why not, one of the values below. |
reason |
Why available is false |
|---|---|
not_allowed |
The caller can't watch this agent: it is Studio or the Workflow Agent, the caller is neither its owner nor an admin of its team (see Who Can Watch), the key belongs to another workspace than the agent, or a signed-in session called from outside the Wiro panel. It is also the answer when no agent has this guid: it is unknown, or the agent was deleted. |
private_team |
A team agent whose Chat Mode is "private": its Screen stays closed to everyone. |
setting_off |
The agent's screen setting is "off" (see Turning the Screen Off). |
not_running |
The agent isn't running. Ask again once Detail reads status: 4. |
unsupported |
The agent's computer doesn't offer the Screen yet. It does once the agent has restarted. |
disabled |
The Screen is turned off on every agent at the moment. |
error |
The check couldn't finish. Ask again in a few seconds. |
When several apply, reason is the first in this order: disabled, not_allowed, private_team, setting_off, not_running, unsupported. The only result: false is a missing useragentguid: Request parameter [useragentguid] required (code 0).
POST /UserAgent/Realtime/ScreenStart
Issues a one-time ticket for the agent's Screen: to watch it, or with control: true to take control of it. Your page opens wsUrl, sends the ticket as its first message, and the screen then streams over that socket as RFB, the VNC protocol (see The Screen socket). A ticket works once and expires 60 seconds after it is issued, so get a new one for every socket you open. A start also adds the Screen rows to the agent's activity log.
Permission: as for ScreenInfo, and a signed-in session from outside the Wiro panel is refused with HTTP 403. control: true needs Take Control: the caller must be the owner of a personal agent that has never been in a team, or whose browser was reset after it last left one, and a key acts as its owner.
Call it from your backend. A browser can't call the API with your key, and must never hold it: hand your page only wsUrl, screenToken and the numbers.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Your UserAgent instance guid. |
control |
boolean | No | true for a Take Control session. Leave it out, or send false, to watch. |
Request
curl -X POST "https://api.wiro.ai/v1/UserAgent/Realtime/ScreenStart" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321"
}'
Add "control": true to the body for Take Control.
Response
A view:
{
"result": true,
"errors": [],
"wsUrl": "wss://socket.wiro.ai/v1/AgentRealtime/Screen",
"screenToken": "<one-time screen ticket>",
"control": false,
"canControl": true,
"maxSeconds": 1800
}
A Take Control session:
{
"result": true,
"errors": [],
"wsUrl": "wss://socket.wiro.ai/v1/AgentRealtime/Screen",
"screenToken": "<one-time screen ticket>",
"control": true,
"canControl": true,
"maxSeconds": 900,
"idleSeconds": 120
}
| Field | Type | Description |
|---|---|---|
wsUrl |
string | The Screen socket. Open it as given; don't build or hardcode the host. |
screenToken |
string | The one-time ticket. Send it in the socket's first message within 60 seconds. It is opaque: don't parse it, keep it in memory only, and never put it in a URL or a log. |
control |
boolean | true when the ticket opens a Take Control session. |
canControl |
boolean | Whether this caller may take control of this agent now, as in ScreenInfo. A view's answer tells you whether to offer Take Control. |
maxSeconds |
number | The longest the session can last: 1800 (30 minutes) to watch, 900 (15 minutes) in control. |
idleSeconds |
number | Control only: control ends after this many seconds without a key or pointer event (120). |
Common errors
A refused start answers result: false with one entry in errors, and no ticket. Every answer comes with HTTP 200 except the one marked HTTP 403 and the two marked HTTP 429 below. 95, 96 and 97 are the agent access codes the UserAgent endpoints share, and this endpoint gives 95 and 96 a few sentences of its own; 94, 98, 99, 409, 429 and 503 are this endpoint's own. In the Error Reference, 96, 97, 98 and 99 mean other things.
{
"result": false,
"errors": [
{
"code": 94,
"message": "Screen is off in this agent's settings.",
"time": 1795201200
}
]
}
| Error | Code | When |
|---|---|---|
Request parameter [useragentguid] required |
0 | useragentguid is missing or blank |
Open the Screen from the Wiro panel, or ask for it with a project API key. |
96 | HTTP 403: a signed-in session from outside the Wiro panel. Call ScreenStart from your backend with a project API key |
Screen is turned off. |
98 | The Screen is turned off on every agent at the moment |
You don't have access to this user agent |
96 | The agent is Studio or the Workflow Agent, or the caller is neither its owner nor on its team |
User agent not found |
95 | Unknown guid, or the agent has been deleted |
Only a team admin can perform this action on a team-owned agent. |
97 | The caller is a plain member of the agent's team |
This API key belongs to another workspace than this agent. Use a key of the agent's own workspace. |
96 | A team project's key for a personal agent, or for another team's agent |
This agent belongs to a team. Switch to the team context to access it. |
0 | A personal project's key for a team agent, when the key's owner is no longer a member of the team |
Screen is off for team agents whose chats are private: the screen shows every chat's work. |
96 | A team agent whose Chat Mode is "private" |
The screen could not be checked. Try again. |
0 | The agent's screen setting could not be read. Try again |
Screen is off in this agent's settings. |
94 | The agent's screen setting is "off" |
The agent is not running. |
95 | The agent's status isn't 4 |
Take Control is off for team agents: their browser is shared by the whole team. |
99 | control: true on a team agent |
Take Control is off for an agent that was used in a team, because its browser may still hold team members' sign-ins. |
99 | control: true on an agent that was in a team and whose browser hasn't been reset since it left (see Resetting the Browser) |
Take Control could not start just now. Try again in a minute. |
99, 503 | control: true when a check before control could not finish. Try again in a minute |
Take Control is not available for this agent right now. |
99 | control: true while Take Control can't be used on this agent. Watching still works |
The screen is not available on this agent yet. Restart the agent to turn it on. |
98 | The agent's computer doesn't offer the Screen yet |
Too many screen sessions started. Try again in a few minutes. |
429 | HTTP 429: more than 30 starts in 10 minutes (see Screen Limits) |
4 people are watching this agent's screen. Try again in a minute. |
429 | A view while 4 screens are open on the agent |
The agent's screen is not answering right now. Try again in a minute. |
98 | control: true while the agent's computer doesn't answer |
The agent is capturing its screen right now. Try again in a minute. |
409 | control: true while the agent takes a screenshot or otherwise captures its screen or a tab |
The agent's screen could not be checked. Try again in a moment. |
503 | control: true when the agent's computer didn't say whether it is capturing |
Take Control can be started 6 times an hour on this agent. Try again in 12 minutes. |
429 | HTTP 429: the seventh Take Control start on the agent in an hour. The wait is the time until the oldest of the 6 starts is an hour old |
The screen could not be started. Try again. |
0 | Something went wrong. Try again |
Extra Credit Packs
An agent with an active plan can buy extra credits at any time, whatever its plan. Every agent gets the same three packs, listed at agent.extracreditpacks on UserAgent/Detail and, before deploying, at extracreditpacks on Agent/Detail:
"extracreditpacks": [
{ "packkey": "small", "credits": 1000, "priceusd": 10, "enabled": true },
{ "packkey": "medium", "credits": 5000, "priceusd": 50, "enabled": true },
{ "packkey": "large", "credits": 20000, "priceusd": 200, "enabled": true }
]
Each pack carries:
| Field | Type | Description |
|---|---|---|
packkey |
string | The pack identifier: "small", "medium", or "large". Pass this as pack in POST /UserAgent/CreateExtraCreditCheckout. |
credits |
number | Credit amount this pack adds when purchased. |
priceusd |
number | Pack price in USD (debited from the wallet on purchase). |
enabled |
boolean | Whether the pack is currently purchasable. The list is server-filtered to enabled packs, so every entry here is true. |
POST /UserAgent/CreateExtraCreditCheckout
Purchases additional credits for a useragent. The wallet is debited the pack price and credits are added to the instance immediately.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Your UserAgent instance guid |
pack |
string | Yes | Pack key from agent.extracreditpacks[].packkey: "small" (1,000 credits, $10), "medium" (5,000, $50) or "large" (20,000, $200). |
useprepaid |
boolean | Yes | Must be true for API use. Pays the pack price from your wallet balance. |
Request
{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"pack": "medium",
"useprepaid": true
}
Response
{
"result": true,
"errors": []
}
The pack price is deducted from your wallet and credits are added to the instance immediately. Credits expire 6 months after purchase. The transaction is appended to the agent ledger (type: "purchase", action: "<pack>", provider: "prepaid") and surfaced on POST /UserAgent/TransactionList.
POST /UserAgent/CancelSubscription
Schedules the subscription to end at the current billing period's expiry (a cancel-at-period-end pattern). The agent keeps running with the full plan allowance until that moment. No wallet refund is issued for the remaining days; you're paying for the full period up front.
| Parameter | Type | Required | Description |
|---|---|---|---|
guid |
string | Yes | Your UserAgent instance guid |
Headers: No extra header is needed. For team agents, use an API key from a project in the agent's team. Keys from another workspace are rejected.
Response
{
"result": true,
"cancelsAt": 1717200000,
"errors": []
}
cancelsAtis the Unix timestamp when the subscription will finish.- Server-side,
subscription.pendingdowngradeis flipped to"cancel"andsubscription.statusstays"active"until the period end. SubsequentUserAgent/Detailresponses reflect this:subscription.pendingdowngrade = "cancel"and the usualcurrentperiodend. - A scheduled move to a lower plan is dropped: the agent's
nextplangoes back tonull. - To reverse the cancellation before the period ends, call
POST /UserAgent/RenewSubscription. It clears the flag without charging the wallet again. - When the period actually ends, the daily cron marks the subscription
"expired"and stops the agent (status: 0). At that point the user must callPOST /UserAgent/RenewSubscription(orCreateSubscriptionCheckoutfor a fresh sub) to continue.
Team agents paid by card
A team agent subscribed by card from the Wiro panel is billed to the card of the member who subscribed. For that plan the call schedules the card subscription to end at the end of the current period instead:
cancelsAtis the end of the current period. The agent keeps running until then, and the subscription ends at that point.subscription.pendingdowngradeisn't set, andRenewSubscriptioncan't undo the cancellation. Only the member whose card pays for the plan can undo it, from their own billing portal.- Only team admins and the organization owner can cancel it. Other members get code
97, including the member who deployed the agent.
Common errors:
| Error | When |
|---|---|
No active subscription found for this agent |
status != "active" on the subscription row |
User agent not found |
Caller doesn't own the agent and isn't on its team |
Only a team admin can perform this action on a team-owned agent. |
Caller is a member of the agent's team but not a team admin (code 97). For a team agent paid by card, this includes the member who deployed the agent |
A switch to prepaid billing is already scheduled for this plan. |
A team agent's card plan that is already set to move to wallet billing at the end of the period |
We couldn't schedule the cancellation. Please try again in a minute. |
A team agent's card plan, when the change couldn't be confirmed with the card payment provider |
POST /UserAgent/UpgradeTier
Moves an active subscription to another plan: "starter", "pro" or "max". Despite its name, the endpoint moves an agent down as well as up:
- A higher plan starts now. API-deployed agents pay through the wallet: the monthly difference for the time left in the current period, by the second, rounded up to the cent and at least one day's worth. The period gains the difference in credits for that same time, and every renewal grants the new plan in full. Existing extra credits and
usedcreditsare kept, and a running agent keeps running. - A lower plan starts at the next renewal, when the request sends
allowDowngrade: true. Without it, a lowertargetTieris refused and nothing changes, so a client that only means to upgrade never moves an agent down. Nothing is charged or refunded now. The agent keeps its current plan, price and credits until the period ends, andnextplanonUserAgent/Detailreads the lower plan. The renewal then charges the lower plan's price and grants its credits. The flag is only for a lower plan: a highertargetTiersent with it, such as from a page that still shows a plan the agent has since left, is refused, and nothing is changed or charged. - Asking for the agent's current plan cancels a scheduled move to a lower plan:
nextplangoes back tonull. An agent that still pays a price from before the three plans gets its current plan scheduled instead:nextplannames that plan, and the renewal moves the agent to the plan's own price and credits.
A move to a higher plan while a lower one is scheduled cancels the scheduled move first, then upgrades from the current plan. On a plan paid by card, a move to a higher plan returns a checkout url instead of charging the wallet, and nothing changes on the agent until it is paid: the answer's tier and nextplan are the agent's as they were. Once it is paid, the higher plan starts a new full period with its full credits, and a lower plan scheduled before is dropped. A lower plan on a card plan applies from the next card renewal. A scheduled move on a card plan can't be cancelled once it has started with the new billing period and its payment is going through: that payment moves the agent, and asking for the current plan is refused until the agent shows the new plan. A team agent's card plan can't be changed with a project API key: the call answers Card checkouts for a team agent need a signed-in session, not an API key. Pay from the team wallet (useprepaid) instead. and changes nothing.
| Parameter | Type | Required | Description |
|---|---|---|---|
guid |
string | Yes | Your UserAgent instance guid |
targetTier |
string | Yes | The plan to move to: "starter", "pro" or "max". The parameter name is targetTier. Passing it as tier returns targetTier must be starter, pro or max. |
allowDowngrade |
boolean | No | true to move to a lower plan at the next renewal. Without it, a targetTier lower than the agent's plan is refused and nothing changes. Send it only for a lower plan: with a targetTier higher than the agent's plan, the request is refused and nothing is changed or charged. The agent's current plan needs no flag. |
Headers: No extra header is needed. For team agents, use an API key from a project in the agent's team. Keys from another workspace are rejected.
Response
A Pro agent moving to Max with 15 days left of 30:
{
"result": true,
"change": "upgrade",
"tier": "max",
"previousTier": "pro",
"targetTier": "max",
"nextplan": null,
"effectiveAt": 1715644800,
"newPriceUsd": 100,
"newMonthlyCredits": 10000,
"creditsNow": 3500,
"creditsThisPeriod": 6500,
"creditsFromRenewal": 10000,
"periodEnd": 1716940800,
"chargedUsd": 35.00,
"proratedCharge": 35.00,
"errors": []
}
A move to a lower plan, sent with "allowDowngrade": true, keeps the agent where it is until the renewal:
{
"result": true,
"change": "downgrade",
"tier": "pro",
"previousTier": "pro",
"targetTier": "starter",
"nextplan": "starter",
"effectiveAt": 1716940800,
"startsAt": 1716940800,
"newPriceUsd": 5,
"newMonthlyCredits": 500,
"periodEnd": 1716940800,
"errors": []
}
Asking for the agent's current plan while a lower one is scheduled answers change: "downgrade-cancelled" with nextplan: null. For an agent that still pays a price from before the three plans, nextplan names its current plan instead, and startsAt, newPriceUsd and newMonthlyCredits give the renewal that moves it to that plan's own price:
{
"result": true,
"change": "downgrade-cancelled",
"tier": "pro",
"previousTier": "pro",
"targetTier": "pro",
"nextplan": "pro",
"effectiveAt": 1715644800,
"periodEnd": 1716940800,
"startsAt": 1716940800,
"newPriceUsd": 30,
"newMonthlyCredits": 3000,
"errors": []
}
| Field | Type | Description |
|---|---|---|
change |
string |
"upgrade", "downgrade" or "downgrade-cancelled". |
tier |
string |
The plan the agent is on after the call. |
previousTier / targetTier |
string |
The plan it was on and the plan asked for. |
nextplan |
string|null |
The plan scheduled for the renewal after the call, or null. |
effectiveAt |
number|null |
Unix seconds when the change takes effect: now for an upgrade on a wallet plan and for a cancelled downgrade, the renewal for a downgrade, null for an upgrade on a card plan, which starts once its checkout is paid. |
newPriceUsd / newMonthlyCredits |
number |
The new plan's monthly price and credits; for a downgrade, from the renewal on. A cancelled downgrade has them only when nextplan names the current plan: that plan's price and credits from the renewal on. |
creditsNow / creditsThisPeriod / creditsFromRenewal |
number |
Upgrade on a wallet plan: what this period gained, what it grants in all, and what each renewal grants. |
chargedUsd |
number |
Upgrade on a wallet plan: what the wallet paid now, in USD. proratedCharge carries the same amount. |
startsAt |
number |
Downgrade: the moment the lower plan starts, the same as effectiveAt. Cancelled downgrade with nextplan set: the renewal that moves the agent to its plan's own price. |
periodEnd |
number |
Unix seconds when the current period ends. |
url / targetPriceUsd / targetCredits |
string / number |
Upgrade on a card plan: the checkout link, and the plan's price and credits once it is paid. Nothing changes until then, so tier and nextplan are the agent's as they were. |
POST /UserAgent/RenewSubscription
Two distinct operations share this endpoint depending on the subscription's current state:
- Undo-cancel: active subscription with
pendingdowngrade: "cancel"→ clears the flag, no wallet charge. - Renew: subscription in
"expired"status → renews the same subscription for a new 30-day period, charges the wallet the plan's price (a scheduled lower plan's whennextplanis set), and queues a stopped or errored agent so it starts again.
The endpoint inspects the current subscription state and picks the right operation; the caller doesn't choose.
| Parameter | Type | Required | Description |
|---|---|---|---|
guid |
string | Yes | Your UserAgent instance guid |
Headers: No extra header is needed. For team agents, use an API key from a project in the agent's team. Keys from another workspace are rejected.
A renewal charges the agent's plan price and grants the plan's credits in full. When a lower plan is scheduled (
nextplan), the renewal charges and grants that plan instead and clearsnextplan. Once a wallet plan has ended, the agent shows the plan its renewal takes and that plan's price:tiernames it,nextplanisnullandmonthlypriceusdis the price. A renewal never charges more thanmonthlypriceusdshows. Skills never change what a renewal costs.
Response: undo-cancel
Called while the subscription is still "active" with a pending cancel flag set by CancelSubscription:
{
"result": true,
"action": "undo-cancel",
"errors": []
}
- Clears
subscription.pendingdowngradeback tonull. - No wallet charge: you've already paid for the full period.
- Agent status is unchanged (still running / stopped / whatever it was).
Response: renew
Called after the subscription has expired (daily cron flipped it to status: "expired" and stopped the agent). The renewal rolls the existing expired subscription forward into a fresh 30-day active row instead of inserting a new one:
{
"result": true,
"action": "renewed",
"plan": "agent",
"tier": "starter",
"amount": 5,
"monthlycredits": 500,
"errors": []
}
- Renews the subscription in place:
statusbecomes"active", a new 30-day period starts now (currentperiodendmoves to now + 30 days), andpendingdowngradeis cleared tonull. - Debits
amount, the plan's price, from the wallet (caller's personal wallet, or the agent's team wallet if the agent is team-scoped). tiernames the plan the renewal charged, andmonthlycreditsthe credits it granted.- Zeroes
usedcreditsand stamps the newcreditperiod. Existing extra credits are preserved. - If the agent was in
status: 0(Stopped) or5(Error), it's auto-queued back to2(Queued). It starts again without an extraStartcall. Statuses1/2/3/4are already in progress and settle on their own. - A card checkout still open for the agent (for example, one started in the Wiro panel) is closed before the wallet is charged, so the agent is never paid for twice.
Common errors:
| Error | When |
|---|---|
Subscription is already active |
Called on an active subscription with no pending cancel (nothing to do) |
No expired subscription found to renew |
No active sub and no expired sub: agent was never subscribed, or data is gone |
Insufficient wallet balance. Required: $X.XX, Available: $Y.YY |
Wallet (personal or team) can't cover the renewal price |
This plan now renews on the Max plan at $100.00 a month, not the $70.00 it showed. Nothing was charged. Renew again to pay the new price. (the plan's name and prices) |
The renewal costs more than the agent's monthlypriceusd showed. Nothing is charged, and the agent now shows the renewal's plan and price (tier and monthlypriceusd, with nextplan cleared). Show the new price, then call RenewSubscription again to pay it |
A payment for this agent is already being processed. It usually finishes within a minute; refresh to see the subscription. |
A card payment for the agent has gone through and its subscription is still being set up; nothing is charged. The response also carries checkoutpending: true |
A checkout for this agent is already being opened. Try again in a moment. |
Another subscription request for the same agent is in progress; nothing is charged |
We couldn't confirm this agent's previous checkout. Please try again in a minute. |
The agent's previous card checkout couldn't be checked; nothing is charged |
Another payment from this wallet is still going through. Nothing was charged; please try again in a minute. |
Another plan or credit pack payment from the same wallet is still going through; nothing is charged |
Full subscription lifecycle (prepaid)
Deploy (wallet charged, period starts)
│
▼
┌────────────────────────┐
│ status: "active" │
│ pendingdowngrade: null │◄──────── RenewSubscription
└───────────┬────────────┘ (undo-cancel, no charge)
│ ▲
│ CancelSubscription │
▼ │
┌────────────────────────┐ │
│ status: "active" │──────────┘
│ pendingdowngrade: │
│ "cancel" │
└───────────┬────────────┘
│ currentperiodend reached
│ (daily cron)
▼
┌────────────────────────┐
│ status: "expired" │
│ useragent.status: 0 │◄───┐
└───────────┬────────────┘ │
│ │
│ RenewSubscription (wallet charged,
│ new 30-day period, agent queued to start)
▼ │
┌────────────────────────┐ │
│ same subscription row │────┘
│ status: "active" │
│ new 30-day period │
└────────────────────────┘
Pricing Summary
| Component | Source | Notes |
|---|---|---|
| Plan price | tiers.{starter,pro,max}.priceUsd |
$5, $30 or $100 a month, the same for every template and custom build. The agent's own price is monthlypriceusd. |
| Monthly credits | tiers.{starter,pro,max}.credits |
500, 3,000 or 10,000. Every renewal grants a plan's credits in full: the current plan's (renewalcredits), or the scheduled plan's when nextplan is set. monthlycredits is what the current period grants. |
| Disk | plans[].diskMb |
250 MB, 500 MB or 1 GB for the agent's files: its workspace, generated media and temporary files. The agent's usage is disk on UserAgent/Detail. |
| Skills | Skills/List |
Every plan includes every skill. Turning one on or off costs nothing. |
| Per-turn token cost | tokenRates (per-model) |
Each chat / cron / voice-prep turn deducts credits metered by the tokens its model consumes (1 credit = $0.01). The same on every plan: a larger plan buys a larger monthly credit pool. |
| Extra credit packs | agent.extracreditpacks[] |
The same on every plan: small 1,000 credits for $10, medium 5,000 for $50, large 20,000 for $200. They expire 6 months after purchase. |
Payment Method
All API subscriptions use your prepaid wallet balance. The cost is deducted immediately when you deploy, renew, move to a higher plan, or buy an extra credit pack. Always pass useprepaid: true on Deploy, CreateSubscriptionCheckout, and CreateExtraCreditCheckout. That's the only path designed for API consumers. Make sure your wallet balance covers the plan's price before calling these endpoints; otherwise you'll get an Insufficient wallet balance error. In the Wiro dashboard, a new subscription is paid by card. A plan paid from the wallet starts only through the API, with Deploy or CreateSubscriptionCheckout and useprepaid: true, or from an MCP client.
Credit Consumption
Credits are used as the agent processes messages and generates content, not at Message/Send time. Each turn is billed by token usage: once the turn completes, Wiro prices its input, output and cached tokens with the per-model tokenRates (1 credit = $0.01). Each billed turn appears as an action: "tokens" row in TransactionList and lowers remainingcredits = max(0, monthlycredits + extracredits - usedcredits). You don't send anything: token billing is fully server-side. Per-turn token counts and cost also ride on each assistant message and arrive over the message WebSocket as an agent_usage_report frame (see Agent Messaging and Agent WebSocket).
The API-side check is gating only: POST /UserAgent/Start and POST /UserAgent/Message/Send refuse to launch / accept messages when remainingcredits <= 0, returning an Agent has no remaining credits… error plus an agentbalance snapshot ({ monthlycredits, extracredits, usedcredits, remainingcredits }). During an active session, monthly credits are consumed first; once usedcredits >= monthlycredits, extra credits (purchased via CreateExtraCreditCheckout) absorb the rest. When both pools are empty the agent stops accepting new turns until the subscription renews or an extra credit pack is bought.
On each billing cycle (subscription renewal) usedcredits is reset to zero, every renewal gives the whole allowance (monthlycredits equals renewalcredits again), and creditperiod advances to the new 'YYYY-MM' window; extra-credit purchases simply bump extracredits without resetting usage.
For the full audit trail (every token deduct / grant / purchase / renewal / expiry) call POST /UserAgent/TransactionList (see Agent Transactions).
Error Messages
Agent-specific errors you may encounter:
| Error | When |
|---|---|
Agent not found |
The agentguid or slug does not match any catalog agent |
User agent not found |
The guid does not match any of your deployed instances |
Agent not found or inactive |
The catalog agent exists but is disabled |
Agent is already running |
Start called on an agent with status 3 or 4 |
Agent is already queued to start |
Start called on an agent with status 2 |
Agent is already stopped |
Stop called on an agent with status 0 |
Agent is currently stopping, please wait |
Start called on an agent with status 1 |
Agent is in error state, use Start to retry |
Stop called on an agent with status 5 that has nothing left to stop; an errored agent that still holds its runtime is accepted and moves to 1 (Stopping) |
Duplicate deploy: an identical agent ("<title>") was already deployed Ns ago. Use the existing one, or wait a few seconds and retry. |
Deploy called a second time within 10s for the same caller, template and team (custom builds: same caller, title and team). Carries errors[0].code: 99 and a top-level existingUserAgentGuid field. |
A sentence that says what is wrong and what to write, such as This schedule can't run. The hour field takes 0 to 23. A schedule has five fields: minute hour day month weekday, for example 0 9 * * 1-5. or This schedule never comes up: February has no 30th. Pick a day February has, such as 28. |
CustomSkillUpsert with an interval the agent can't run on a scheduled task, or one whose date never comes. Nothing is saved. |
<skillkey>: followed by the same sentence |
Deploy with a customskills entry whose interval the agent can't run, or whose date never comes. Nothing is created or charged. |
A deploy takes up to 50 entries in customskills, and this one sent <n>. Send at most 50, then add the rest with /UserAgent/CustomSkillUpsert once the agent is deployed. |
Deploy with more than 50 customskills entries. Nothing is created or charged. |
Agent setup is not complete. Please finish setting up your connectors before starting. |
Status is 6: call CredentialUpsert / CredentialProjectBind / SkillsApply / CustomSkillUpsert to provide required values, then POST /UserAgent/Update to move the agent to status 0 |
Subscription required — please subscribe to this agent before starting it. |
Start called on a row with no active subscription AND no spendable extras (extracredits - usedcredits ≤ 0). Most often hit after a subscription expires with empty extras. Call RenewSubscription (useprepaid: true) to continue. |
No credits available. Please renew your subscription or purchase extra credits. |
Monthly and extra credits are both exhausted |
Subscription already active for this useragent. Cancel or modify the existing subscription instead. |
CreateSubscriptionCheckout called when a sub already exists |
Change the plan with UpgradeTier. |
SkillsApply with a tier other than the agent's current plan |
tier must be starter, pro or max |
Deploy or CreateSubscriptionCheckout with a tier that names no plan. Nothing is created or charged. |
targetTier must be starter, pro or max |
UpgradeTier with a targetTier outside the closed enum (typos, missing parameter name, etc.) |
Already on the Pro plan. (the plan's name) |
UpgradeTier with the agent's current plan when no lower plan is scheduled: no-op |
The Starter plan is smaller than this agent's Pro plan, so this is not an upgrade. Nothing was changed. A move to a smaller plan starts at the next renewal; to ask for it, send allowDowngrade: true. (the plans' names) |
UpgradeTier with a targetTier lower than the agent's plan and no allowDowngrade: true. Nothing is changed or charged |
This agent is on the Starter plan now, so Pro is an upgrade. Nothing was changed. Reload the plan and ask again. (the plans' names) |
UpgradeTier with allowDowngrade: true and a targetTier higher than the agent's plan, such as after the plan changed in another tab or at a renewal. Nothing is changed or charged |
The move to the Starter plan started with this billing period, and its payment moves the agent there, so it can no longer be undone. Nothing was changed. Once the agent shows the Starter plan, change the plan again. (the plan's name) |
UpgradeTier with the agent's current plan on a card plan whose scheduled plan has already started with the new billing period. Its payment moves the agent there |
No active plan. Use /UserAgent/CreateSubscriptionCheckout to start one on the plan you pick. |
UpgradeTier called without an active subscription |
This plan is set to end at the end of its period, so there is no renewal to change. Renew it first. |
UpgradeTier to a lower plan while the subscription is cancelled at period end. Undo the cancel with RenewSubscription first |
The plan change could not be scheduled. Nothing was changed; please try again in a minute. |
UpgradeTier to a lower plan on a card plan, when the change couldn't be set with the card payment provider |
Insufficient wallet balance. Required: $X.XX, Available: $Y.YY |
UpgradeTier: wallet can't cover the charge for a higher plan |
Wallet deduction failed: {error} |
UpgradeTier: wallet write itself failed (rare; transient backend error) |
Another change to this agent's plan is going through. Nothing was changed; please try again in a minute. |
UpgradeTier (code 104) while a skill change or another plan change of the same agent is going through |
The agent's plan changed while this was asked for. Nothing was changed; please retry. |
UpgradeTier when the agent's plan ended or moved off the wallet after the call was made |
Could not read the agent's plan. Nothing was changed; please retry. |
UpgradeTier: the agent's plan could not be read |
Another payment from this wallet is still going through. Nothing was charged; please try again in a minute. |
Deploy or CreateSubscriptionCheckout with useprepaid: true, CreateExtraCreditCheckout, RenewSubscription or UpgradeTier (code 104 on UpgradeTier) while another plan or credit pack payment from the same wallet is going through. A Deploy refused this way creates no agent |
Card checkouts for a team agent need a signed-in session, not an API key. Pay from the team wallet (useprepaid) instead. |
A card payment for a team agent asked for with a project API key: UpgradeTier on a plan paid by card, CreateExtraCreditCheckout paid by card, or CreateSubscriptionCheckout without useprepaid: true. Nothing is charged or changed |
Project not found. Send the id of one of your projects from Project/List: one you created, or any project of a team you are an admin of. |
CredentialProjectBind with a project that doesn't exist or that the caller can't bind. See its other errors |
Agent not found or access denied |
Message endpoint with invalid useragentguid |
User agent not found (code 95) |
Message/Send, Message/History, Message/Sessions, Message/DeleteSession, Message/RenameSession or Message/Delete called for an agent that has been deleted |
The sentence for the agent's status: Agent is stopped. Start it before sending messages. (status 0), Agent is stopping. Please wait a moment and try again. (status 1, when the agent is shutting down to stay stopped), Agent is restarting. Please wait a moment and try again. (status 1, when the agent is shutting down to start again, as in a restart), Agent is starting up. Please wait a moment and try again. (status 2 or 3), Agent is in error state. Restart it before sending messages. (status 5) or Agent setup is incomplete. Complete the setup before sending messages. (status 6) |
Message/Send while the agent isn't running (any status other than 4), for every message Wiro doesn't answer itself as a setup reply (see Replies Wiro handles itself). Response includes agentstatus (the integer) so your client can branch on it. |
Agent has no remaining credits. Renew your subscription or buy a credit pack to continue. |
Message/Send while remainingcredits <= 0. Response includes agentbalance, so your client can offer to buy credits. |
A spend limit refusal (code 93), such as This agent's monthly spend limit is reached ($20.35 of $20.00). It resets on December 1, 2026 at 00:00 UTC. |
Message/Send while the agent's own spend limit is used up; the response includes agentstatus. Paying from the wallet with Deploy, CreateSubscriptionCheckout, UpgradeTier, RenewSubscription or CreateExtraCreditCheckout is refused the same way when the price would take spending over a limit of the wallet. Nothing runs and nothing is charged |
A Model Access refusal (code 92), such as This agent can't use openai/gpt-5-6-sol. Model Access rules decide which models can run. |
Message/Send with a model that the agent's own Model Access rule blocks, or UpdateSettings with such a model override. Nothing runs and nothing is charged |
Message not found |
Detail / Cancel with invalid messageguid |
Message cannot be cancelled (status: {status}) |
Cancel on a message that's already in a terminal state |
Invalid redirect URL |
OAuth Connect with non-HTTPS URL |
Pack key required |
CreateExtraCreditCheckout without pack |
Could not retrieve wallet balance |
Wallet service lookup failed while checking balance |
runstream-unavailable |
RunStreamToken while following runs live is not available. Try again later |
A Screen refusal, such as Screen is off in this agent's settings. (code 94) or Take Control is off for team agents: their browser is shared by the whole team. (code 99) |
Realtime/ScreenStart when the agent's Screen, or Take Control, can't open for the caller. These codes are ScreenStart's own: see its errors |
Code Examples
curl
# List available agents (no auth required)
curl -X POST "https://api.wiro.ai/v1/Agent/List" \
-H "Content-Type: application/json" \
-d '{"limit": 10}'
# Get agent details by slug (no auth required)
curl -X POST "https://api.wiro.ai/v1/Agent/Detail" \
-H "Content-Type: application/json" \
-d '{"slug": "instagram-manager"}'
# Deploy a new agent instance (prepaid, pinned by default)
curl -X POST "https://api.wiro.ai/v1/UserAgent/Deploy" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": "My Instagram Bot",
"useprepaid": true,
"tier": "starter"
}'
# Deploy an agent your customers chat with (no setup changes from chat)
curl -X POST "https://api.wiro.ai/v1/UserAgent/Deploy" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": "Customer #1234 Bot",
"useprepaid": true,
"tier": "starter",
"chatsetup": "off"
}'
# Build a custom agent (no template — pick your own skill set)
curl -X POST "https://api.wiro.ai/v1/UserAgent/Deploy" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"custom": true,
"title": "Inbox Watcher",
"useprepaid": true,
"tier": "pro",
"skills": { "int-gmail-check": true, "int-wiro-aimodels": true }
}'
# Preview a plan change before you make it
curl -X POST "https://api.wiro.ai/v1/UserAgent/PricingPreview" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"tier": "max"
}'
# Cancel a subscription (cancels at end of billing period)
curl -X POST "https://api.wiro.ai/v1/UserAgent/CancelSubscription" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321"}'
# Move up to Pro (prepaid: a prorated charge now)
curl -X POST "https://api.wiro.ai/v1/UserAgent/UpgradeTier" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "targetTier": "pro"}'
# Renew expired subscription (or undo a pending cancel)
curl -X POST "https://api.wiro.ai/v1/UserAgent/RenewSubscription" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321"}'
# Buy extra credits with prepaid wallet
curl -X POST "https://api.wiro.ai/v1/UserAgent/CreateExtraCreditCheckout" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "pack": "small", "useprepaid": true}'
# Start an agent
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321"}'
# Get agent instance details
curl -X POST "https://api.wiro.ai/v1/UserAgent/Detail" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321"}'
# Update credentials on a running agent (triggers automatic restart)
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"fields": [
{ "credentialkey": "instagram", "fieldname": "authmethod", "fieldvalue": "wiro" }
]
}'
# Stop an agent
curl -X POST "https://api.wiro.ai/v1/UserAgent/Stop" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321"}'
Python
import requests
headers = {
"x-api-key": "YOUR_API_KEY",
"Content-Type": "application/json"
}
# List available agents (no auth required)
catalog = requests.post(
"https://api.wiro.ai/v1/Agent/List",
json={"limit": 10}
).json()
for agent in catalog["agents"]:
print(f"{agent['title']} ({agent['slug']}): Starter ${agent['tiers']['starter']['priceUsd']}/mo")
# Get agent details by slug
detail = requests.post(
"https://api.wiro.ai/v1/Agent/Detail",
json={"slug": "instagram-manager"}
).json()
agent = detail["agents"][0]
print(f"Credentials needed: {list(agent['credentials'].keys())}")
# Deploy a new instance (prepaid wallet, Starter plan)
deploy = requests.post(
"https://api.wiro.ai/v1/UserAgent/Deploy",
headers=headers,
json={
"agentguid": agent["guid"],
"title": "My Instagram Bot",
"useprepaid": True,
"tier": "starter"
}
).json()
instance_guid = deploy["useragents"][0]["guid"]
print(f"Deployed: {instance_guid}")
# Update credentials
requests.post(
"https://api.wiro.ai/v1/UserAgent/CredentialUpsert",
headers=headers,
json={
"useragentguid": instance_guid,
"fields": [
{ "credentialkey": "instagram", "fieldname": "authmethod", "fieldvalue": "wiro" }
]
}
)
# A prepaid Deploy already queued the agent: start it only when it is stopped (0) or errored (5)
instance = requests.post(
"https://api.wiro.ai/v1/UserAgent/Detail",
headers=headers,
json={"guid": instance_guid}
).json()
if instance["useragents"][0]["status"] in (0, 5):
requests.post(
"https://api.wiro.ai/v1/UserAgent/Start",
headers=headers,
json={"guid": instance_guid}
)
# Check status
import time
while True:
resp = requests.post(
"https://api.wiro.ai/v1/UserAgent/Detail",
headers=headers,
json={"guid": instance_guid}
).json()
status = resp["useragents"][0]["status"]
print(f"Status: {status}")
if status == 4:
print("Agent is running!")
break
if status == 5:
print("Agent errored")
break
time.sleep(5)
# Move up to Pro (prorated, debited from wallet)
requests.post(
"https://api.wiro.ai/v1/UserAgent/UpgradeTier",
headers=headers,
json={"guid": instance_guid, "targetTier": "pro"}
)
# Buy extra credits (any plan, prepaid wallet)
requests.post(
"https://api.wiro.ai/v1/UserAgent/CreateExtraCreditCheckout",
headers=headers,
json={"useragentguid": instance_guid, "pack": "small", "useprepaid": True}
)
# List your deployed agents
my_agents = requests.post(
"https://api.wiro.ai/v1/UserAgent/MyAgents",
headers=headers,
json={"limit": 50}
).json()
for ua in my_agents["useragents"]:
print(f"{ua['title']} - status: {ua['status']} - plan: {ua.get('tier')}")
# Stop the agent
requests.post(
"https://api.wiro.ai/v1/UserAgent/Stop",
headers=headers,
json={"guid": instance_guid}
)
Node.js
const axios = require('axios');
const headers = {
'x-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
};
async function main() {
// List available agents (no auth required)
const catalog = await axios.post(
'https://api.wiro.ai/v1/Agent/List',
{ limit: 10 }
);
catalog.data.agents.forEach(a =>
console.log(`${a.title} (${a.slug}): Starter $${a.tiers.starter.priceUsd}/mo`)
);
// Get agent details by slug
const detail = await axios.post(
'https://api.wiro.ai/v1/Agent/Detail',
{ slug: 'instagram-manager' }
);
const agent = detail.data.agents[0];
// Deploy a new instance (prepaid wallet, Starter plan)
const deploy = await axios.post(
'https://api.wiro.ai/v1/UserAgent/Deploy',
{ agentguid: agent.guid, title: 'My Instagram Bot', useprepaid: true, tier: 'starter' },
{ headers }
);
const instanceGuid = deploy.data.useragents[0].guid;
console.log('Deployed:', instanceGuid);
// Update credentials
await axios.post(
'https://api.wiro.ai/v1/UserAgent/CredentialUpsert',
{
useragentguid: instanceGuid,
fields: [
{ credentialkey: 'instagram', fieldname: 'authmethod', fieldvalue: 'wiro' }
]
},
{ headers }
);
// A prepaid Deploy already queued the agent: start it only when it is stopped (0) or errored (5)
const current = await axios.post(
'https://api.wiro.ai/v1/UserAgent/Detail',
{ guid: instanceGuid },
{ headers }
);
if ([0, 5].includes(current.data.useragents[0].status)) {
await axios.post(
'https://api.wiro.ai/v1/UserAgent/Start',
{ guid: instanceGuid },
{ headers }
);
}
// Poll until running
while (true) {
const resp = await axios.post(
'https://api.wiro.ai/v1/UserAgent/Detail',
{ guid: instanceGuid },
{ headers }
);
const status = resp.data.useragents[0].status;
console.log('Status:', status);
if (status === 4) { console.log('Agent is running!'); break; }
if (status === 5) { console.log('Agent errored'); break; }
await new Promise(r => setTimeout(r, 5000));
}
// Move up to Pro
await axios.post(
'https://api.wiro.ai/v1/UserAgent/UpgradeTier',
{ guid: instanceGuid, targetTier: 'pro' },
{ headers }
);
// Buy extra credits (prepaid wallet)
await axios.post(
'https://api.wiro.ai/v1/UserAgent/CreateExtraCreditCheckout',
{ useragentguid: instanceGuid, pack: 'small', useprepaid: true },
{ headers }
);
// Stop the agent
await axios.post(
'https://api.wiro.ai/v1/UserAgent/Stop',
{ guid: instanceGuid },
{ headers }
);
}
main();
PHP
<?php
$apiKey = "YOUR_API_KEY";
// List available agents (no auth required)
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.wiro.ai/v1/Agent/List");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(["limit" => 10]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$catalog = json_decode(curl_exec($ch), true);
curl_close($ch);
// Deploy a new instance (prepaid wallet, Starter plan)
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.wiro.ai/v1/UserAgent/Deploy");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Content-Type: application/json",
"x-api-key: $apiKey"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
"agentguid" => "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title" => "My Instagram Bot",
"useprepaid" => true,
"tier" => "starter"
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$deploy = json_decode(curl_exec($ch), true);
curl_close($ch);
echo "Deployed: " . $deploy["useragents"][0]["guid"];
C
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");
// Deploy a new instance (prepaid wallet, Starter plan)
var deployContent = new StringContent(
JsonSerializer.Serialize(new {
agentguid = "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
title = "My Instagram Bot",
useprepaid = true,
tier = "starter"
}),
Encoding.UTF8, "application/json");
var deployResp = await client.PostAsync(
"https://api.wiro.ai/v1/UserAgent/Deploy", deployContent);
var deployResult = await deployResp.Content.ReadAsStringAsync();
Console.WriteLine(deployResult);
// A prepaid Deploy already queued the agent: start it only when it is stopped (0) or errored (5)
var agentGuid = "f8e7d6c5-b4a3-2190-fedc-ba0987654321";
var detailResp = await client.PostAsync(
"https://api.wiro.ai/v1/UserAgent/Detail",
new StringContent(JsonSerializer.Serialize(new { guid = agentGuid }), Encoding.UTF8, "application/json"));
using var detail = JsonDocument.Parse(await detailResp.Content.ReadAsStringAsync());
var status = detail.RootElement.GetProperty("useragents")[0].GetProperty("status").GetInt32();
if (status == 0 || status == 5)
{
var startContent = new StringContent(
JsonSerializer.Serialize(new { guid = agentGuid }),
Encoding.UTF8, "application/json");
var startResp = await client.PostAsync(
"https://api.wiro.ai/v1/UserAgent/Start", startContent);
Console.WriteLine(await startResp.Content.ReadAsStringAsync());
}
Go
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"io"
)
func main() {
// Deploy a new instance (prepaid wallet, Starter plan)
body, _ := json.Marshal(map[string]interface{}{
"agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": "My Instagram Bot",
"useprepaid": true,
"tier": "starter",
})
req, _ := http.NewRequest("POST",
"https://api.wiro.ai/v1/UserAgent/Deploy",
bytes.NewBuffer(body))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("x-api-key", "YOUR_API_KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
data, _ := io.ReadAll(resp.Body)
fmt.Println(string(data))
}
Swift
import Foundation
let url = URL(string: "https://api.wiro.ai/v1/UserAgent/Deploy")!
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.setValue("application/json",
forHTTPHeaderField: "Content-Type")
request.setValue("YOUR_API_KEY",
forHTTPHeaderField: "x-api-key")
request.httpBody = try! JSONSerialization.data(
withJSONObject: [
"agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": "My Instagram Bot",
"useprepaid": true,
"tier": "starter"
])
let (data, _) = try await URLSession.shared
.data(for: request)
print(String(data: data, encoding: .utf8)!)
Kotlin
import java.net.HttpURLConnection
import java.net.URL
val url = URL("https://api.wiro.ai/v1/UserAgent/Deploy")
val conn = url.openConnection() as HttpURLConnection
conn.requestMethod = "POST"
conn.setRequestProperty("Content-Type", "application/json")
conn.setRequestProperty("x-api-key", "YOUR_API_KEY")
conn.doOutput = true
conn.outputStream.write("""{
"agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": "My Instagram Bot",
"useprepaid": true,
"tier": "starter"
}""".toByteArray())
val response = conn.inputStream.bufferedReader().readText()
println(response)
Dart
import 'dart:convert';
import 'package:http/http.dart' as http;
final response = await http.post(
Uri.parse('https://api.wiro.ai/v1/UserAgent/Deploy'),
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY',
},
body: jsonEncode({
'agentguid': 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
'title': 'My Instagram Bot',
'useprepaid': true,
'tier': 'starter',
}),
);
print(response.body);
What's Next
- Agent Builder: Build custom agents from scratch (
custom: true) with live pricing previews and skill picker - Agent Skills: Configure preferences, scheduled tasks, and skill toggles. Includes the registry browser endpoints (
Skills/List,Skills/Detail,Skills/Capabilities) - Agent Credentials: Integration catalog hub with 20+ dedicated per-provider setup guides (Meta Ads, Facebook, Instagram, LinkedIn, Twitter, and more) plus the registry endpoints (
Credentials/List,Credentials/Detail) - Agent Messaging: Send messages and receive responses from running agents
- Agent Chat Integration: Build your own chat for an agent, with setup cards, connections, restarts and the agent's live Screen
- Agent WebSocket: Real-time response streaming
- Agent Webhooks: Receive agent responses via HTTP callbacks
- Agent Transactions: Per-instance credit ledger (deductions, renewals, purchases, grants, refunds)
- Agent Logs: Per-instance activity feed (tool calls, cron runs, message exchanges)
- Authentication: API key setup and authentication methods
Agent Messaging
Send messages to AI agents and receive streaming responses in real time.
How It Works
Agent messaging follows the same async pattern as model runs:
- Send a message via REST → get an
agenttokenimmediately - Subscribe to Agent WebSocket with the
agenttoken→ receive orderedagent_timeline_deltablock updates plus provisional accumulated answer text - Or poll via the Detail endpoint to check status and fetch the completed response
- Or set a
callbackurlto 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.
Building a chat in your own product? Agent Chat Integration walks through the whole cycle with every request and answer: messages, setup cards, connecting each kind of connector, restarts, errors, and the agent's live Screen with Take Control.
Ordered turn timeline
Every Detail or History message row returns a top-level timeline[]. It is the ordered, persisted record of the turn. A turn can contain multiple interleaved blocks, for example:
Thinking → Answer or Tool → Thinking → Answer
Each block has an opaque deterministic blockid, call/content ordering coordinates, type (reasoning, answer, tool, or setup), safe public text, tool state or a setup card, phase (stream, end, or error), its own monotonically increasing version, and timestamps. Reasoning text is a model-provided reasoning summary, never raw hidden chain-of-thought. Tool blocks expose only toollabel, toolstatus, toolintegration, and toolaction, never a tool ID, arguments, results, or other internal execution metadata. toolintegration and toolaction each hold a word from a closed list or null. A setup block is a setup change the agent proposes; see Setup From Chat. When a turn ends with agent_error or agent_cancel, the server closes every block still at stream and sends each one as an agent_timeline_delta, usually just before that final event. After agent_end, open blocks normally close a few seconds later. A tool block that closed with toolstatus requested was cut off before it finished.
Live WebSocket updates arrive as agent_timeline_delta events carrying one public block. Merge by blockid, replace that block only when its incoming version is strictly newer, then sort by callindex, contentindex, and blockid. agent_subscribed.timeline carries the persisted reconnect snapshot. agent_output remains provisional cumulative SSE output until the corresponding answer block catches up; after completion or reconnect, Message/Detail is authoritative.
Message Lifecycle
Every agent message progresses through a defined set of stages:
agent_queue → agent_start → agent_output → agent_end
Message Statuses
| Status | Description |
|---|---|
agent_queue |
The message is queued and waiting to be picked up by the agent runtime. Emitted once when the message enters the queue. |
agent_start |
The agent has accepted the message and begun processing. The underlying LLM call is being prepared. |
agent_output |
The agent is producing output. This event is emitted multiple times: each chunk of the response arrives as a separate agent_output event via WebSocket, enabling real-time streaming. |
agent_end |
The agent has finished generating the response. The full output is available in the response and debugoutput fields. This is the event you should listen for to get the final result. |
agent_error |
The turn failed. response and debugoutput hold a coded message that says why; see Failed turns. |
agent_cancel |
The message was cancelled by the user before completion. Only messages in agent_queue, agent_start, or agent_output status can be cancelled. |
agent_done |
Marker-only terminal status. Used exclusively for model_change marker rows (see Message/History), never for a real user or assistant turn. Normal turns terminate at agent_end (or agent_error / agent_cancel). |
Failed turns
When a turn ends with agent_error or agent_cancel, response and debugoutput both hold one message: a code in brackets, then a fixed sentence. Message/Detail, Message/History, the agent_error and agent_cancel events of the Agent WebSocket and the webhook carry the same text, and the agent chat on wiro.ai shows its own sentence for the code. The underlying error is never returned.
| Code | Status | What happened | What to do |
|---|---|---|---|
[SECURITY_BLOCKED] |
agent_error |
The agent's security rules blocked the message. | Change the message and send it again. |
[SAFETY_POLICY_BLOCKED] |
agent_error |
The model's provider declined the request under its usage or safety policy. | Rephrase the request and send it again. |
[TURN_INTERRUPTED] |
agent_error |
The agent restarted while the turn was running. | Send the message again. |
[SPEND_LIMIT_REACHED] |
agent_error |
The agent's own spend limit is used up, so its model calls were refused. A turn that is already running stops at its next model call. | Wait for the limit to reset, or have someone who manages the workspace's spend limits raise it under Controls > Spend Limits: the account owner, or in a team a team admin or the organization owner. |
[USAGE_CEILING_REACHED] |
agent_error |
The agent reached its hourly or daily safety ceiling for AI model calls. | Wait until that hour or day is over. |
[MODEL_NOT_ALLOWED] |
agent_error |
The agent's own Model Access rule blocks the model it uses, so its model calls were refused. | Have someone who manages the workspace's Model Access rules allow the model under Controls > Model Access, or choose another model for the agent. |
[AGENT_UNAVAILABLE] |
agent_error |
Any other failure. | Try again after a short wait. |
[REQUEST_CANCELLED] |
agent_cancel |
The turn was cancelled, while it ran or while it was still queued. | Nothing to do. |
The full texts:
[SECURITY_BLOCKED] The agent's security rules blocked this message. Change it and send it again.
[SAFETY_POLICY_BLOCKED] The model's provider declined this request under its safety policy. Rephrase it and send it again.
[TURN_INTERRUPTED] This request was interrupted by a restart before it finished. Please send it again.
[SPEND_LIMIT_REACHED] This agent's spend limit is used up, so it paused. It runs again when the limit resets or is raised.
[USAGE_CEILING_REACHED] This agent reached its hourly or daily safety ceiling for AI model calls, so it paused. It runs again when that hour or day is over.
[MODEL_NOT_ALLOWED] This agent's Model Access rule blocks the model it uses, so it stopped. It runs again once the model is allowed or another one is chosen.
[AGENT_UNAVAILABLE] Agent is temporarily unavailable. Please try again shortly.
[REQUEST_CANCELLED] Request cancelled.
Match the code in brackets, never the sentence after it, which can change. Turns that failed before the codes existed are returned in the same form.
In Telegram, Slack and Discord the agent says the same without the code in brackets, when a turn stops and when a message arrives while its spend limit is used up or its rule blocks its model. The spend limit sentence also names the limit's period and when it resets, when the agent knows them: This agent's daily spend limit is used up, so it paused. It runs again when the limit resets at 00:00 UTC or is raised.
POST /UserAgent/Message/Send
Sends a user message to a deployed agent. The agent must be in running state (status 4), except for a setup reply that Wiro answers itself, such as a yes that applies a setup card, which works in any status (see Replies Wiro handles itself). Returns immediately with an agenttoken that you use to track the response via WebSocket, polling, or webhook.
Accepts either application/json (text-only) or multipart/form-data (text + file attachments). When sending files, the message field can be empty. The agent receives the attachments and any accompanying text.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | The agent instance GUID (from Deploy or MyAgents). |
message |
string | Conditional | The user message text. Required unless sending files via multipart. |
sessionkey |
string | No | Session identifier for conversation continuity. Defaults to "default". |
callbackurl |
string | No | Webhook URL: the system will POST the final response to this URL when the agent finishes. It must be a public http(s) address: a host that is, or resolves to, a private, loopback or link-local address gets no webhook. |
model |
string | No | Canonical model slug to run this turn on (e.g. "openai/gpt-5.6-sol"), chosen from the agent's selectable set. Validated server-side: an unknown or non-selectable slug is rejected in errors[] and the turn is not sent. So is a model that the agent's own Model Access rule blocks (code 92). Omit to use the agent's configured chat model. |
attachment / attachments[] |
file | No | Multipart only: one or more file attachments that the agent can process. |
Per-turn model selection.
modelselects the chat model for a single turn instead of the agent's configured default. Valid values are the agent's selectable slugs: thetokenRates.models[]entries whereselectableistrue, returned byUserAgent/Detail(see Agent Overview). The current set includesopenai/gpt-5.6-sol(the platform chat default),openai/gpt-5.6-terra,openai/gpt-5.6-luna,openai/gpt-5.5,openai/gpt-5.5-pro,openai/gpt-5.4,openai/gpt-5.4-mini,openai/gpt-5.2,openai/gpt-5.1,openai/gpt-5, andopenai/gpt-5-mini. Always read the live set from that field. The server applies the chosen model to that turn only.
Response
{
"result": true,
"errors": [],
"messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
"status": "agent_queue"
}
A successful Send response means the message was accepted and queued, not that it will definitely reach the agent. After this response the system queues the message for the agent. If that queueing step itself fails (for example, a queue outage), the message's
statusis set toagent_errorserver-side after the HTTP response was already sent withresult: true. Always confirm the final state viaPOST /UserAgent/Message/Detailor the WebSocket stream; don't assume the message progresses toagent_startjust because Send returnedresult: true.Reserved session keys. The platform reserves a small set of
sessionkeyprefixes for system-managed threads:wiro:api,voice-prep*,voice-call-*, andcs-cron-*. Sending a user message into one of these keys is rejected withReserved sessionkey(the same guard that protectsMessage/DeleteSession). Pick any other identifier for your own threads.
| Field | Type | Description |
|---|---|---|
messageguid |
string |
Unique identifier for this message. Use it with Detail, History, or Cancel. |
agenttoken |
string|null |
Token for WebSocket subscription and polling. Equivalent to tasktoken in model runs. null when Wiro handled the message itself (see below). |
status |
string |
Initial status: "agent_queue" on success, or "agent_end" when Wiro handled the message itself: a setup reply (see Replies Wiro handles itself) or an unknown or disabled command. |
modelChangeMarker |
object|null |
Present only when this turn's model selects a different chat model than the session was running, i.e. it rotates the model mid-session. Shape: { guid, type: "model_change", fromModel, toModel, createdat }. The platform also writes a matching marker row into history (see Message/History). Absent on turns that keep the session's model. |
content |
string |
Present when Wiro handled the message itself or removed a key from it: the message text as stored. See Keys in chat. |
contentmasked |
boolean |
Present (true) when Wiro removed a key from the message before the agent saw it; content holds the text the agent got. |
response |
string |
Only when Wiro handled the message itself: its result text. |
setupresult |
object |
Only when Wiro handled the message itself as a setup reply: { applied, dismissed, failed, restarting, next? }. See Replies Wiro handles itself. |
model_changemarker. Whenmodelrotates the session to a different chat model, the Send response carries amodelChangeMarkerdescribing the switch, and a standalone marker row (statusagent_done) is written into history at the same time:
json "modelChangeMarker": { "guid": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "type": "model_change", "fromModel": "openai/gpt-5.4", "toModel": "openai/gpt-5.5", "createdat": 1714694399 }See
Message/Historyfor the shape and ordering of the marker row it materializes.
Failure responses
When result: false, the response shape is { result: false, errors: [{ code, message }], messageguid: null, agenttoken: null, status: null }. Two branches add extra context:
| Failure branch | Extra fields | Notes |
|---|---|---|
Agent not running (status ≠ 4) |
agentstatus: <int> |
Returned for every message Wiro doesn't answer itself as a setup reply (see Replies Wiro handles itself). Echoes the agent's current status so the caller can decide whether to wait, call Start, or surface "Setup Required" UI: 0 Stopped (call Start), 1 Stopping, 2 Queued and 3 Starting (wait and retry), 5 Error (call Start to retry), 6 Setup Required. With status 1, the error reads Agent is stopping. Please wait a moment and try again. when the agent is shutting down to stay stopped, and Agent is restarting. Please wait a moment and try again. when it is shutting down to start again, as in a restart. See UserAgent Statuses. |
| Out of credits | agentstatus, agentbalance: { monthlycredits, extracredits, usedcredits, remainingcredits } |
Returned with the Agent has no remaining credits… error. remainingcredits: 0 is the trigger; surface a "Renew or buy a credit pack" CTA. |
Unknown or disabled commands
While the agent is running, Wiro answers a slash command the agent doesn't run, such as /status, or one of its commands that is turned off in enabledcommands. No agent turn runs and no credits are used, even when the agent has no credits left. Send answers at once:
{
"result": true,
"errors": [],
"messageguid": "e5f6a7b8-c9d0-1234-ef56-789012345678",
"agenttoken": null,
"status": "agent_end",
"response": "⛔ Unknown or disabled command: /status\nSend /agent_help to see the available commands.",
"content": "/status"
}
response names the command in lower case, and its second line comes only when the agent has agent_help on. There is no setupresult. The message is stored as a finished exchange, like a reply Wiro handles itself: Message/Detail and Message/History return it with status: "agent_end", metadata.type: "setup_result" and model: null. When the Send has a callbackurl, Wiro posts the answer to it right away with status: "agent_end", and its metadata holds type: "setup_result", cards: [] and command, the command's name. Files sent with the message are not kept.
Wiro finds the command this way:
- A command is a
/at the start of the message or after a space, tab or line break, followed by a letter or_. It counts anywhere in the text:Check the /pricing pagegets the answer for/pricing. A/inside a word or before a digit, as inand/oror/2fa, is plain text. - Links (
http://andhttps://addresses) and quoted lines (lines that start with>) are left out first, sosee https://example.com/pricingholds no command. - A message with one of the agent's enabled commands anywhere in it goes to the agent, which runs the command. A command runs only when it is written in lower case and followed by a space, tab, line break or the end of the message:
/AGENT_STATUSand/agent_status.get the answer. - Otherwise only the first command counts. When it is
/modelor/models, one of/start,/help,/settings,/app,/tmp,/run,/usr,/bin,/etc,/homeand/var, or a name of more than 32 characters, the message goes to the agent as usual:/usr/bin/envand/start /pricingreach the agent. Any other first command gets the answer.
While the agent isn't running, the message gets the not-running refusal with agentstatus, as every message does that Wiro doesn't answer as a setup reply.
POST /UserAgent/Message/Detail
Retrieves the current status and content of a single message. You can query by either messageguid or agenttoken.
| Parameter | Type | Required | Description |
|---|---|---|---|
messageguid |
string | No | The message GUID returned from Send. |
agenttoken |
string | No | The agent token returned from Send (alternative to messageguid). |
sessionkey |
string | No | Optional session scope. When supplied, the row is additionally constrained to this sessionkey, so a shared-owner agent (one API key fronting many end users) can ensure a user only reads their own turn. Omit for the default single-user behavior. |
Note: You must provide at least one of
messageguidoragenttoken.
Response
{
"result": true,
"errors": [],
"data": {
"guid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"uuid": "ada-uuid",
"agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
"user": {
"uuid": "ada-uuid",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"username": "ada",
"avatar": "https://cdn.wiro.ai/avatars/ada.webp",
"avatarinitials": "AL"
},
"sessionkey": "default",
"content": "What are the latest trends in AI?",
"response": "Here are the key AI trends for 2026...",
"debugoutput": "Here are the key AI trends for 2026...",
"timeline": [
{
"blockid": "c0:i0",
"callindex": 0,
"contentindex": 0,
"type": "reasoning",
"text": "I’ll distinguish deployed capabilities from current research.",
"phase": "end",
"version": 3,
"startedat": 1743350401,
"updatedat": 1743350405
},
{
"blockid": "c0:i1",
"callindex": 0,
"contentindex": 1,
"type": "answer",
"text": "Here are the key AI trends for 2026...",
"phase": "end",
"version": 8,
"startedat": 1743350405,
"updatedat": 1743350408
}
],
"status": "agent_end",
"metadata": {
"type": "progressGenerate",
"task": "Generate",
"speed": "14.2",
"speedType": "words/s",
"elapsedTime": "8.1s",
"tokenCount": 105,
"wordCount": 118
},
"attachments": [],
"deletestatus": 0,
"createdat": 1743350400,
"startedat": 1743350401,
"endedat": 1743350408,
"inputtokens": 3450,
"outputtokens": 820,
"cachereadtokens": 2400,
"cachewritetokens": 0,
"totaltokens": 6670,
"model": "openai/gpt-5.6-sol",
"tokencost": 5,
"processedms": 4200
}
}
| Field | Type | Description |
|---|---|---|
guid |
string |
Message GUID. |
uuid |
string |
The account UUID of the user who sent the message. |
agenttoken |
string|null |
The same token issued by Message/Send for this message. Lets callers that arrived at the row through Message/Detail (or Message/History) subscribe to the Agent WebSocket and pick up an in-flight response. This is useful when a chat UI rehydrates after a reload and finds a message still in agent_queue / agent_start / agent_output status. null for very old rows that pre-date the column, and for replies Wiro handles itself (see Replies Wiro handles itself). |
user |
object|null |
Resolved sender info: { uuid, firstname, lastname, email, username, avatar, avatarinitials }. Decorated server-side from the message's uuid so the chat bubble can render avatar / hover-tooltip without an extra User/Detail round-trip. null when the row was written by automation (sentinel uuid like "system") or when the user record was deleted. A message sent with a project API key is the key owner's, whoever typed it: a product of your own shows its own names, not this one. |
sessionkey |
string |
The session this message belongs to. |
content |
string |
The original user message. |
response |
string |
The agent's full response text. Empty until the turn ends. After agent_error or agent_cancel it holds the failure message; see Failed turns. |
debugoutput |
string |
Accumulated output text. Updated during streaming, contains the full response after completion. |
timeline |
array |
Ordered turn blocks. Always an array; [] means no public blocks were persisted. Merge live deltas by blockid and per-block version, then sort by call/content order. |
status |
string |
Current message status (see Message Lifecycle). |
metadata |
object |
Parsed JSON object (API returns it already decoded). Populated from the agent bridge on agent_end. Only type and a few keys are returned: on a finished turn (type: "progressGenerate") task, speed, speedType, elapsedTime, tokenCount and wordCount; on a model_change marker row fromModel and toModel; on other rows (setup_result, system, subagent) usually type alone, and in History systemcost: true on a row whose cost came from a scheduled or background run. The answer text is in response and timeline, never in metadata. Empty object {} for agent_error, agent_cancel, or when the bridge hasn't finished yet. Message status lives in the top-level status field, so don't read it from metadata.type. |
attachments |
array |
Always present as an array: empty [] for text-only messages. When the message was sent via multipart with files, each entry is a resolved {url, name, type, size} object (no further file-lookup needed). Identical shape in Message/History rows. |
deletestatus |
number |
Internal flag. 0 for normal messages. |
createdat |
number |
Unix timestamp (epoch seconds) when the message was created. |
startedat |
number |
Unix timestamp (epoch seconds) when the agent started processing. |
endedat |
number |
Unix timestamp (epoch seconds) when processing completed. May be empty for agent_cancel (cancel only sets status and updatedat). |
inputtokens |
number|null |
Uncached input (prompt) tokens billed at the model's input rate. Populated on the assistant turn once it completes; null on user-only, cron, legacy, and model_change marker rows. |
outputtokens |
number|null |
Billed output (completion) tokens the model generated this turn. null on the same non-assistant / marker / legacy rows. |
cachereadtokens |
number|null |
Tokens served from the model's prompt cache (billed at the cached-input rate). 0 when the model reported no cache hits; null on non-assistant rows. |
cachewritetokens |
number|null |
Tokens written to the prompt cache this turn. 0 when none; null on non-assistant rows. |
totaltokens |
number|null |
Exact component sum: inputtokens + outputtokens + cachereadtokens + cachewritetokens. null on non-assistant rows. |
model |
string|null |
Canonical slug of the chat model that actually ran the turn (e.g. "openai/gpt-5.4"), reflecting any per-turn model override from Send. null on non-assistant / marker / legacy rows. |
tokencost |
number|null |
Credits deducted for the turn, derived from the token counts and the model's tokenRates (see Agent Overview). null on non-assistant rows. |
processedms |
number|null |
Wall-clock model processing time for the turn, in milliseconds. null on non-assistant rows. |
Public timeline block fields
Only the fields below are returned in browser-facing REST and WebSocket timeline blocks. toollabel, toolstatus, toolintegration, and toolaction appear on tool blocks only, and setup on setup blocks only.
| Field | Type | Description |
|---|---|---|
blockid | string | Opaque deterministic identity for one logical block (for example c0:i0). Use it as the merge key; do not parse its current format. |
callindex | number | Zero-based call order within the turn. Primary sort key. |
contentindex | number | Zero-based content order within the call. Secondary sort key. |
type | string | reasoning, answer, tool, or setup. |
text | string|null | Safe public text for reasoning and answer; null for tool and setup blocks. Reasoning text is an OpenAI GPT-5 provider summary, not raw chain-of-thought. |
toollabel | string | Tool blocks only. Safe display label for the tool. Arguments and results are never included. |
toolstatus | string | Tool blocks only. requested while the step runs, then completed or error. |
toolintegration | string|null | Tool blocks only. The connector the step works in, as its key from POST /Credentials/List, for example shopify. null when the step doesn't work in a connector. See Tool integration and action values. |
toolaction | string|null | Tool blocks only. What the step does, for example screenshot or click. null when no word fits the step, and always null when toolintegration is set. See Tool integration and action values. |
setup | object | Setup blocks only. The change the agent proposes and its state; see The setup block. |
phase | string | stream, end, or error for this block. A block still at stream closes when its turn ends with agent_error or agent_cancel, and normally a few seconds after agent_end. |
version | number | Monotonic within this block. Ignore a delta whose version is not strictly newer than the stored block's version. |
startedat | number|null | Block start timestamp when available. |
updatedat | number|null | Most recent block update timestamp when available. |
Do not compare version across different blocks. Keep a map keyed by blockid, apply per-block last-write-wins, and render callindex ASC, contentindex ASC, blockid ASC. This makes the result independent of HTTP/WebSocket arrival order.
metadata.tokenCountvs the billing token columns.metadata.tokenCountis the live stream counter emitted inside theprogressGeneratepayload, a running word/token tally for the in-flight response. The flatinputtokens/outputtokens/cachereadtokens/cachewritetokens/totaltokens/tokencostcolumns are the final billed usage, written once the turn completes. They measure different things: usetokenCountfor a live progress indicator, and the flat columns for accounting and cost.
Tool integration and action values
toolintegration and toolaction say which connector a tool step works in and what the step does, so your app can show "Working in Shopify" or "Taking a screenshot" instead of only the tool's name. Each holds a word from a closed list or null, never free text, a host, a URL, a path, or an argument.
toolintegration is the key of the connector the step works in, as POST /Credentials/List lists it: adapty, adjust, apollo, apple-appstore, brevo, calendarific, dataforseo, facebook-pages, firebase, ga4, gmail, google-ads, google-business, google-calendar, google-drive, google-merchant-center, google-play, google-search-console, hubspot, instagram, keepa, lemlist, linkedin, mailchimp, meta-ads, reddit, revenuecat, roasit, sendgrid, serper, shopify, telegram, tiktok, tiktok-ads, twitter, wiro, woocommerce, wordpress, or youtube.
toolaction is one of these words:
| Value | Meaning |
|---|---|
screenshot |
Takes a screenshot of a page. |
open-page |
Opens a page. |
read-page |
Reads the open page. |
click |
Clicks on the page. |
type |
Types text into the page. |
press-key |
Presses a key. |
wait |
Waits for the page. |
upload |
Uploads a file to the page. |
download |
Downloads a file. |
read-file |
Reads a file. |
edit-media |
Edits a video, an image, or audio. |
A tool block never carries both words: when toolintegration is set, toolaction is null. Both are null when no word fits the step and on blocks saved before these fields existed, so fall back to toollabel then. The words come with the block's first requested update, and every later update of the block carries them. A later update can carry a different word if the step changed, so read the words from the newest version of the block, like its other fields. A block whose step is rewritten and no longer fits a word keeps its last word. More values can be added to either list later, so treat a value you don't know like null.
Two tool blocks from a timeline[]:
[
{
"blockid": "c0:i1",
"callindex": 0,
"contentindex": 1,
"type": "tool",
"text": null,
"toollabel": "exec",
"toolstatus": "completed",
"toolintegration": "shopify",
"toolaction": null,
"phase": "end",
"version": 3,
"startedat": 1743350402,
"updatedat": 1743350406
},
{
"blockid": "c1:i1",
"callindex": 1,
"contentindex": 1,
"type": "tool",
"text": null,
"toollabel": "browser",
"toolstatus": "requested",
"toolintegration": null,
"toolaction": "screenshot",
"phase": "stream",
"version": 1,
"startedat": 1743350408,
"updatedat": 1743350408
}
]
POST /UserAgent/Message/History
Retrieves conversation history for a specific agent and session. Messages are returned newest-first with cursor-based pagination.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | The agent instance GUID. |
sessionkey |
string | No | Session identifier. Defaults to "default". |
limit |
number | No | Maximum number of messages to return. Defaults to 50, max 200. |
before |
string | No | Message GUID to use as cursor: returns only messages created before this one. Omit for the most recent messages. |
Team agents: If the agent's
teamsessionmodeiscollaborative, History returns messages from all team members in the session, and the agent keeps one shared memory for the team. Inprivatemode, History only returns messages sent by the caller's ownuuidand memory stays per operator. The same visibility rule applies toSessionslisting.
Response
{
"result": true,
"errors": [],
"data": {
"messages": [
{
"guid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"uuid": "ada-uuid",
"agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
"user": {
"uuid": "ada-uuid",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"username": "ada",
"avatar": "https://cdn.wiro.ai/avatars/ada.webp",
"avatarinitials": "AL"
},
"content": "What are the latest trends in AI?",
"response": "Here are the key AI trends for 2026...",
"debugoutput": "Here are the key AI trends for 2026...",
"timeline": [
{
"blockid": "c0:i0",
"callindex": 0,
"contentindex": 0,
"type": "reasoning",
"text": "I’ll distinguish deployed capabilities from current research.",
"phase": "end",
"version": 3,
"startedat": 1743350401,
"updatedat": 1743350405
}
],
"status": "agent_end",
"metadata": {
"type": "progressGenerate",
"task": "Generate",
"speed": "14.2",
"speedType": "words/s",
"elapsedTime": "8.1s",
"tokenCount": 105,
"wordCount": 118
},
"attachments": [],
"deletestatus": 0,
"createdat": 1743350400,
"inputtokens": 3450,
"outputtokens": 820,
"cachereadtokens": 2400,
"cachewritetokens": 0,
"totaltokens": 6670,
"model": "openai/gpt-5.6-sol",
"tokencost": 5,
"processedms": 4200
},
{
"guid": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"uuid": "ada-uuid",
"agenttoken": null,
"user": {
"uuid": "ada-uuid",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"username": "ada",
"avatar": "https://cdn.wiro.ai/avatars/ada.webp",
"avatarinitials": "AL"
},
"content": "",
"response": "",
"debugoutput": "",
"timeline": [],
"status": "agent_done",
"metadata": {
"type": "model_change",
"fromModel": "openai/gpt-5.2",
"toModel": "openai/gpt-5.4"
},
"attachments": [],
"deletestatus": 0,
"createdat": 1743350399,
"inputtokens": null,
"outputtokens": null,
"cachereadtokens": null,
"cachewritetokens": null,
"totaltokens": null,
"model": null,
"tokencost": null,
"processedms": null
},
{
"guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"uuid": "ada-uuid",
"agenttoken": "tQ4nL8vY1zMkRpWdH7cXjBg6sFhPmA",
"user": {
"uuid": "ada-uuid",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"username": "ada",
"avatar": "https://cdn.wiro.ai/avatars/ada.webp",
"avatarinitials": "AL"
},
"content": "Tell me more about multimodal models",
"response": "Multimodal models combine...",
"debugoutput": "Multimodal models combine...",
"timeline": [],
"status": "agent_end",
"metadata": {},
"attachments": [],
"deletestatus": 0,
"createdat": 1743350300,
"inputtokens": 1180,
"outputtokens": 540,
"cachereadtokens": 0,
"cachewritetokens": 0,
"totaltokens": 1720,
"model": "openai/gpt-5.2",
"tokencost": 3,
"processedms": 3100
}
],
"count": 3,
"hasmore": false,
"sessiontoken": "Lp4vQ8sWn2KxT7cRb1YhZ6mDg9FjA3uEo5iNk0wXyHt"
}
}
Each message row carries
uuid(sender) and a server-decorateduserobject with the full sender shape, the same asMessage/Detail.userisnullfor rows with a sentineluuidsuch as"system"(older automation rows) or when the underlying account has been deleted.Resuming an in-flight stream. Every row carries the original
agenttokenfromMessage/Send. If a returned message'sstatusis non-terminal (agent_queue,agent_start, oragent_output), the agent is still processing it server-side. Hand theagenttokento the Agent WebSocket (agent_infoframe) and you'll receive the persistedagent_subscribed.timelinesnapshot, subsequentagent_timeline_deltablock updates, remaining provisionalagent_outputsnapshots, and the eventualagent_endevent, with no need to re-send the message.
| Field | Type | Description |
|---|---|---|
messages |
array |
Array of message objects, newest first. Each row has the fields of Message/Detail except sessionkey, startedat and endedat, including persisted timeline, the uuid sender, the agenttoken (so you can resubscribe over WebSocket if status is non-terminal), the decorated user object, and the per-turn token columns below. The array can also include model_change marker rows (see the note under the table). |
count |
number |
Number of messages in this page. |
hasmore |
boolean |
true if there are older messages available. Pass the last message's guid as before to fetch the next page. |
sessiontoken |
string |
Token for following this session live on the Agent WebSocket: messages added to the session between turns reach you as they are written. Treat it as opaque and keep it private, like an agenttoken. It can be absent; then read History again to pick up new messages. |
Each assistant row also carries the per-turn token-accounting columns, identical to Message/Detail:
| Field | Type | Description |
|---|---|---|
inputtokens |
number|null |
Uncached input (prompt) tokens billed at the model's input rate. null on user-only, cron, legacy, and model_change marker rows. |
outputtokens |
number|null |
Billed output (completion) tokens the model generated. null on the same non-assistant / marker / legacy rows. |
cachereadtokens |
number|null |
Tokens served from the model's prompt cache. 0 when none; null on non-assistant rows. |
cachewritetokens |
number|null |
Tokens written to the prompt cache. 0 when none; null on non-assistant rows. |
totaltokens |
number|null |
Exact component sum: inputtokens + outputtokens + cachereadtokens + cachewritetokens. null on non-assistant rows. |
model |
string|null |
Canonical slug of the chat model that ran the turn. null on non-assistant / marker / legacy rows. |
tokencost |
number|null |
Credits deducted for the turn. null on non-assistant rows. |
processedms |
number|null |
Wall-clock model processing time in milliseconds. null on non-assistant rows. |
model_changemarker rows. Switching the chat model (via themodelparam) drops a synthetic marker row into history alongside the real turns. A marker row hasstatus: "agent_done",model: null, emptycontent/response/debugoutput, every token columnnull, andmetadata: { "type": "model_change", "fromModel": "…", "toModel": "…" }. Detect it withmetadata.type === "model_change"and render it as an inline separator (e.g. "Switched to GPT-5.4") rather than a chat bubble. Itscreatedatis the triggering turn'screatedatminus one second, so it orders immediately before that turn (in the newest-first response it appears directly after the turn that triggered it).
Messages added between turns. Not every row answers a
Message/Sendof yours: the agent can also add a message to the session on its own, such as a scheduled report, files it sends after an answer, or the result of longer work it finished in the background. When it moves work to the background, the turn you sent ends with a short line saying the result will follow, and the result arrives later as a separate row. These rows arrive finished (status: "agent_end") with an emptycontentand the text inresponse. Theirmetadata.typeis"subagent"for the result of work the agent finished in the background (show it as the agent's reply) and"system"for the rest. They have no turn of their own: nothing streams on anagenttokenfor them and nocallbackurlis called. Read them with History, or follow the session withsessiontokento receive each one as it is added; see Following a session.
Pagination
To paginate through a long conversation:
Page 1 (most recent messages):
{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"sessionkey": "default",
"limit": 50
}
Page 2, passing the last (oldest, smallest createdat) message's guid from page 1 as the before cursor:
{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"sessionkey": "default",
"limit": 50,
"before": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
POST /UserAgent/Message/Sessions
Lists all conversation sessions for an agent. Returns each session's key, message count, last activity time, and the most recent message content. Sorted newest-first by updatedat.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | The agent instance GUID. |
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?",
"name": "Password help"
},
{
"sessionkey": "user-99-draft",
"messagecount": 0,
"updatedat": 1743348000,
"lastmessage": "",
"name": "New chat"
}
]
}
}
| Field | Type | Description |
|---|---|---|
sessionkey |
string |
The session identifier. |
messagecount |
number |
Total number of messages in this session. |
updatedat |
number |
Unix timestamp (epoch seconds) of the last activity in this session. |
lastmessage |
string |
The most recent message body: the message's content if the user sent a message, falling back to its response (assistant reply) when content is empty. |
name |
string? |
Optional display name set via Message/RenameSession. Omitted when the session was never named, so fall back to your own default label (e.g. the sessionkey or "New chat"). |
Named-but-empty sessions appear too. A session created by
RenameSessionbefore its firstMessage/Sendsurfaces here withmessagecount: 0,lastmessage: "", and thenameyou set, so a freshly created chat shows up in the list immediately.Reserved session keys. The list leaves out the reserved session keys
wiro:api,voice-prep*,voice-call-*andcs-cron-*.Message/HistoryandDeleteSessionreject them too.Marker rows excluded.
model_changemarker rows are not real turns. They're skipped when building this list, so they never surface as a session'slastmessage.
POST /UserAgent/Message/DeleteSession
Deletes messages in the given session for the calling user. This action cannot be undone.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | The agent instance GUID. |
sessionkey |
string | Yes | The session key to delete. |
rotate |
boolean | No | Default false. When true, after wiping the rows the server also clears the agent's memory of this session, so the next Message/Send on the same sessionkey starts a fresh reasoning context. With false (or omitted) the message rows are wiped but the agent may still recall them. Any display name set via RenameSession is dropped on delete. |
Scope of deletion: Hard delete. The session's messages are removed permanently, not hidden. Only the caller's own messages in the session are purged. This holds in both private and collaborative team modes. Even when
teamsessionmode: "collaborative"(e.g. Telegram group-shared sessions) means every member sees the same thread, each member'sDeleteSessiononly wipes their own contributions. Compare withMessage/Delete(per-message), which is a soft delete that hides messages instead of removing them.Reserved session keys.
wiro:api,voice-prep*,voice-call-*andcs-cron-*are reserved. Passing one of them assessionkeyreturns"Session not found", andSessionsnever lists them.
Response
{
"result": true,
"errors": []
}
POST /UserAgent/Message/RenameSession
Sets a human-readable display name on a session without touching its messages or its sessionkey. The name is stored in a separate overlay keyed by (useragentguid, sessionkey) and surfaces on Message/Sessions. Because the sessionkey is unchanged, the agent's conversation memory is fully preserved across a rename.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | The agent instance GUID. |
sessionkey |
string | Yes | The session to name. Reserved system keys (wiro:api, voice-prep*, voice-call-*, cs-cron-*) are rejected with "Session not found", same as DeleteSession. |
name |
string | Yes | The display name. The server strips control characters, collapses whitespace, trims, and caps the result at 40 characters. An empty string after sanitization is rejected with request-parameter-required. |
Doubles as "create a named session". Calling
RenameSessionwith a brand-newsessionkey, before anyMessage/Sendon it, seeds a named-but-empty session that immediately appears inMessage/Sessionswithmessagecount: 0andlastmessage: "". This is the canonical way to let a user open a fresh, titled chat before they type anything.
Request
curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/RenameSession" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"sessionkey": "user-42-support",
"name": "Password help"
}'
Response
{
"result": true,
"errors": []
}
POST /UserAgent/Message/Delete
Bulk-deletes one or more messages from a session, with per-side soft-delete semantics. Each item lets you choose whether to hide the user side of the bubble, the agent side, or both. This supports "delete just my message" / "delete only the response" / "delete the whole bubble" UX without losing the underlying record.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | The agent instance GUID. |
items |
array | Yes | One or more { messageguid, side } rows. |
Each item:
| Field | Type | Description |
|---|---|---|
messageguid |
string | The message to delete. Must belong to the agent identified by useragentguid, and its uuid must be yours: any other messageguid (for example, another team member's message in a shared session) is skipped silently and the call still returns result: true. On a team agent, any active member of the agent's team can call this from the team's workspace; it still hides only your own messages. |
side |
string | One of "user", "agent", or "both". Sets these bits in the message's deletestatus bitmask: user → 1, agent → 3, both → 3. agent and both both produce 3 (full hide on both sides). There is no side value that hides only the agent's view while keeping the row visible to the user. |
Soft delete, not hard delete. Deleted messages are kept with
deletestatusset rather than erased.Message/Historyonly returns messages whosedeletestatusis0, i.e. a message is hidden the moment any bit is set, regardless of which side flagged it. To wipe a whole session hard-and-fast (no soft-delete trail), useMessage/DeleteSessioninstead.
Request
curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/Delete" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"items": [
{ "messageguid": "c3d4e5f6-...", "side": "user" },
{ "messageguid": "d4e5f6a7-...", "side": "agent" },
{ "messageguid": "e5f6a7b8-...", "side": "both" }
]
}'
Response
{ "result": true, "errors": [] }
The endpoint is best-effort across the items array: invalid messageguid rows or invalid side values are silently skipped. The call returns result: true even when zero rows were updated, so callers should refetch Message/History to confirm the new state.
POST /UserAgent/Message/Cancel
Cancels an in-progress message. Only messages in agent_queue, agent_start, or agent_output status can be cancelled. Messages that have already reached agent_end, agent_error, or agent_cancel cannot be cancelled.
| Parameter | Type | Required | Description |
|---|---|---|---|
messageguid |
string | No | The message GUID to cancel. |
agenttoken |
string | No | The agent token to cancel (alternative to messageguid). |
sessionkey |
string | No | Optional session scope. When supplied, the cancel only matches a row in this sessionkey. This is useful for shared-owner agents so one end user can't cancel another's in-flight turn. Omit for the default single-user behavior. |
Note: You must provide at least one of
messageguidoragenttoken.
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_startoragent_output), the bridge's abort handler fires: subscribed WebSocket clients receive anagent_cancelevent,debugoutput/responseare set to[REQUEST_CANCELLED] Request cancelled., and thecallbackurlwebhook (if set) is triggered withstatus: "agent_cancel".- If the message was still queued (status
agent_queue) when cancelled, no processing attempt had started: the row is markedagent_cancel, Message/Detail and Message/History return[REQUEST_CANCELLED] Request cancelled.for it, no WebSocketagent_cancelevent is broadcast, and no webhook is triggered.When polling for the final state, check
status === "agent_cancel".
Setup From Chat
An agent can help the people who run it set it up in the chat: add or remove a connector or skill, save a key for a connector or remove it, connect a connector that uses a sign-in, create or change a scheduled task, create or change a custom skill, add to one or undo its last change, or change its time zone. The agent never changes its own setup and never sees a key. It proposes the change as a setup card: Wiro checks the card against the agent's current setup and stores it on the message that asked for it, where it shows as a setup block in that message's timeline[]. Nothing changes until an agent admin (the owner, or an admin of the agent's team) approves the card.
Where cards can be proposed and approved is the agent's chatsetup setting. Set it with UpdateSettings or at Deploy, and read it back as chatSetup on UserAgent/Detail:
| Value | What it allows |
|---|---|
all (default) |
Setup cards in the Wiro web chat and in messages sent with a project API key, such as from your backend or an MCP client. |
webchat |
Setup cards only in the Wiro web chat on wiro.ai. Messages sent with a project API key never get or approve a card. |
off |
No setup cards. The agent tells people that an agent admin makes the change in the agent's settings. |
Messages from Telegram, Slack or Discord never get or approve a card, whatever the setting: there the agent says that an agent admin makes the change in the agent's settings.
Agents your customers talk to. A message sent with your project API key acts with your rights, even when one of your end users typed it. If people who don't manage the agent talk to it through your app, set
chatsetupto"webchat"or"off", so a "yes" from one of them can't change the agent's setup.Setup cards in your own chat. To show the cards, their connect steps and restarts in your own product, follow Agent Chat Integration.
Studio and the Workflow Agent. Setup from chat is always off for them. Each one runs on one setup shared by everyone who uses it, so they never propose setup cards, and their connectors, skills and scheduled tasks are fixed. Asked to remember a rule or to do something on a schedule, they say so in one sentence and help with the request once, as a one-time task.
The setup block
A setup block has type: "setup", text: null and a setup object with the proposed change and its state. Setup blocks sort after every other block of the turn, in the order the agent proposed them, and their phase is always end. A message holds at most three. The card's status changes when someone approves or dismisses it. A pending card's block has version 1; once the card is applied, dismissed or failed, its block has version 2 with the new status, so keep the copy with the higher version whichever arrives first. Clients still subscribed to the message's agenttoken get the new block as an agent_timeline_delta, and Message/Detail and Message/History always return the current state.
A pending connect card's block also has next, beside setup: one entry { connector, title, mode } for the card's own connector, in the shape of an add card's needs, so a chat in your own product can show its own Connect button. It is gone from the block once the card is applied, dismissed or failed. A connect card stored before next existed may have none. It still gets one while a pending add card on the same message names its connector in needs. An add card's block has no next: its needs lists what it brings.
"next": [{ "connector": "serper", "title": "Serper Web Search", "mode": "key" }]
{
"blockid": "s:k3v9q2m8x1za",
"callindex": 1000000,
"contentindex": 0,
"type": "setup",
"text": null,
"setup": {
"v": 1,
"id": "k3v9q2m8x1za",
"kind": "schedule",
"action": "create",
"key": "cs-cron-morning-summary",
"title": "Morning summary",
"cron": "0 9 * * 1-5",
"instructions": "Every weekday, summarize yesterday's orders and post the summary in the web chat.",
"requestedby": "ada-uuid",
"createdat": 1743350406
},
"phase": "end",
"version": 1,
"startedat": 1743350406,
"updatedat": 1743350406
}
| Field | Type | Description |
|---|---|---|
v |
number |
Card format version, 1. |
id |
string |
The card's id: 12 lower-case letters and digits. Send it as cardid to SetupCardApply. |
kind |
string |
add (turn on a connector or skill), remove (turn one off), connect (connect a connector: save its key, or confirm a sign-in made on the card), disconnect (remove a connector's saved key), schedule (a scheduled task), skill (a custom skill) or timezone. |
action |
string |
schedule: create, update, pause, resume or delete. skill: create, update, append (add text to the end), revert (undo the last change), disable or enable; see Changing a custom skill. Absent on add, remove, connect, disconnect and timezone cards. |
connector |
string |
connect and disconnect only. The connector's key, as POST /Credentials/List lists it, for example serper. A card never holds a key's value. |
key |
string |
add, remove, schedule and skill only. On add and remove: the name of one connector (int-<name>) or skill (util-<name>) as POST /Skills/List lists it, up to 64 characters, for example int-brevo-email; see Adding and removing connectors and skills. On schedule and skill: the scheduled task's key (cs-cron-<name>) or the custom skill's key (cs-<name>). |
title |
string |
Optional. One line, up to 80 characters. |
cron |
string |
schedule only: always on create, optional on update. A 5-field cron in the agent's time zone. A task set up from chat runs at most once an hour. |
instructions |
string |
schedule and skill only. On create and update: the full text of the task or skill, up to 20,000 characters. On append: only the text to add, up to 20,000 characters. On revert: the text the skill goes back to, which Wiro takes from the skill's history; the agent never writes it. |
before |
string |
skill cards with update, append or revert only. The skill's text when Wiro checked the card, written by Wiro, never by the agent. Show it as the text before the change; see Changing a custom skill. It can be absent on older cards. |
with |
string[] |
add and remove only, written by Wiro, never by the agent. The other connectors and skills the card turns on (add) or off (remove) together with key, by name, sorted, at most 12. |
pauses / resumes |
string[] |
add and remove only, written by Wiro. The scheduled tasks (cs-cron-<name>) that pause, or run again, with this change, at most 20 each. |
needs |
object[] |
add only, written by Wiro. The connectors the change brings that aren't connected yet, at most 3, each { connector, title, mode }: connector is the connector's key, as a connect card names it, title is its name, and mode says how it is connected: key (with a key pasted in the chat or entered on its connect card), signin (with a sign-in through Wiro's app, on its connect card), appkeys (with the person's own app keys and then a sign-in, on its connect card), token (with a token Wiro checks, such as a Meta System User token, on its connect card) or page (set up outside the chat, with the credential endpoints or on the agent page: no card connects it). Read a mode you don't know as page. |
timezone |
string |
timezone only. The proposed IANA time zone, for example Europe/Istanbul. |
note |
string |
Optional. The agent's one-line note about the change, up to 300 characters. |
status |
string |
pending, applied, dismissed or failed. Absent means pending. |
actedat |
number |
Unix seconds when the card was applied, dismissed or failed. Absent while pending. |
actedby |
string |
Account UUID of the person who applied or dismissed the card. Absent while pending. |
error |
string |
failed only. A plain sentence that says why the change could not be made. When the cause was on Wiro's side, it reads The change could not be applied. Try again in a moment. |
requestedby |
string |
Account UUID of the person whose message asked for the change. |
createdat |
number |
Unix seconds when the agent proposed the change. |
Fields that don't apply to a card's kind are absent. More kinds and actions can be added later, so skip a card whose kind or action you don't know.
Changing a custom skill
A skill card changes one of the agent's custom skills. create and update carry the skill's full text in instructions, and disable and enable turn the skill off and on. Two more actions keep a change to an existing skill small:
appendadds text to the end of the skill.instructionsholds only the text to add, so a new rule goes into a long skill without the whole skill being sent again. Once applied, the skill's text isbeforewith the whitespace at its end removed, a blank line, theninstructions. Wiro refuses the card when the skill already holds that text, or when the skill would get too long to change from chat.revertundoes the skill's last change. The agent names only the skill, and Wiro puts the text to restore ininstructions: the newest version in the skill's version history whose text differs from the current text. When the skill has no earlier version, Wiro refuses the card.
An update, append or revert card also has before, the skill's text when Wiro checked the card. Wiro writes it; the agent never does. Show it next to the text after the change, which is instructions on update and revert cards and the joined text on append cards: on a pending card as the current and the proposed text, and on an applied card as the text before and after the change. Don't read the skill's live text for this, since it already holds the change once the card is applied. before can be absent on older cards.
{
"v": 1,
"id": "p7d2m4x9q1ka",
"kind": "skill",
"action": "append",
"key": "cs-blog-writing",
"instructions": "End every post with three questions readers ask, each with a two-sentence answer.",
"before": "Write each blog post in a friendly, plain tone.\nKeep posts under 900 words.",
"requestedby": "ada-uuid",
"createdat": 1743350406
}
Once this card is applied, the skill reads:
Write each blog post in a friendly, plain tone.
Keep posts under 900 words.
End every post with three questions readers ask, each with a two-sentence answer.
Wiro applies a card that has before only while the skill still holds that text. When the skill's text no longer matches before as the card is applied, for example because someone edited the skill on the agent page after the card was made, nothing changes and the card fails with This skill changed after the card was made. Ask the agent again.
Adding and removing connectors and skills
An add card turns on one connector (int-<name>) or skill (util-<name>) that the agent doesn't have, and a remove card turns off one it has, as the agent page does. key holds its name as POST /Skills/List lists it, one name per card. A change costs nothing: every plan includes every connector and skill, so the plan's price and credits stay the same. Cards work on agents deployed from a template and on custom builds, and once a card is applied, the agent restarts to load the change.
A change can turn on or off more than its key, so Wiro works out the rest and writes it on the card, and the person who approves sees the whole change. The agent never writes these fields: a proposal that sends them has them dropped.
with: on anadd, the connectors and skillskeydepends on (depends_onin Skills/List) that aren't on yet, which are turned on with it. On aremove, the linked partners the agent page turns off together with it (removingutil-video-creatoralso turns offutil-motion-effects), and the supporting parts (user_invocable: false) that nothing left on still needs.pausesandresumes: the scheduled tasks that stop running, or run again, because a connector or skill they use goes off or comes back on. A paused task keeps its text and schedule.needs: on anadd, the connectors it brings that aren't connected yet. A connector withmodekey,signin,appkeysortokengets aconnectcard, as below. One withpageis set up outside the chat: no card connects it.
Read a missing list as empty. An add card for Brevo Email, which brings two skills it depends on and the Brevo connector:
{
"v": 1,
"id": "m5t8c2w6r3pe",
"kind": "add",
"key": "int-brevo-email",
"with": ["util-anti-ai-human-copy", "util-chat-markdown-reporting"],
"needs": [{ "connector": "brevo", "title": "Brevo", "mode": "key" }],
"requestedby": "ada-uuid",
"createdat": 1743350406
}
A remove card keeps a connector's saved key, as turning a connector off on the agent page does, so adding it back later needs no new key. To remove the key too, use a disconnect card.
Adding a connector that takes a key. When an add card's needs names a connector with mode: "key", Wiro adds a connect card for that connector to the same reply, right after the add card, so the person sees both cards at once. It leaves the connect card out when the reply already has a pending connect card for that connector, or has no room for another card (a reply holds at most three). A reply keeps one pending connect card per connector, so a connect card the agent proposes for that connector afterwards isn't stored again. Wiro checks the connect card against the agent's setup as it will be once the add card is applied, since the connector isn't on yet. The add card goes first: until it is applied, applying the connect card changes nothing and answers Apply card <N> first: it turns on <Title>., where <N> is the add card's number on the reply, and the connect card stays pending. In a typed chat, a yes applies the add card as it does any card other than connect (see Approving a setup card). Wiro's answer then ends by asking for the key, naming the connector by its title in needs: Next: paste your <Title> key as your reply. When the agent restarts to load the add card, that line goes on with Send it now and it loads with this same restart. The key pasted as the next reply applies the connect card. The key doesn't have to wait for the restart the add card started: Wiro saves it right away, whether it is pasted as the reply or entered on the connect card. A key saved while the agent is still stopping or queued for that restart loads with it, so adding and connecting the connector takes one restart; a key saved once the agent is starting or running again restarts it once more. The add card can also take the key itself and apply both cards in one step; see Adding and connecting in one step. A connector set up outside the chat (mode: "page") gets no connect card: once the add card is applied, Wiro's answer says Connect <Title> in the agent's settings., naming each such connector by its title in needs, and its next lists the connector with mode: "page" and no card. A connector that uses a sign-in gets one too; see Connecting a sign-in connector.
Wiro checks an add or remove card when the agent proposes it and again when it is applied, and works out with, pauses, resumes and needs again. When the agent's connectors or skills changed in between, so that the card would now turn on more than it shows or turn off something else, nothing changes and the card fails with This agent's connectors or skills changed after the card was made. Ask the agent again. A dependency in with that was turned on in the meantime is not a change. An add card whose key itself was turned on in the meantime fails with <Title> is already on., and a remove card whose key was turned off fails with <Title> is not on this agent.
Wiro refuses an add or remove card with one plain sentence when:
- the name isn't a connector or skill Wiro has, or the
addnames one Wiro no longer offers (the sentence names its replacement when there is one); - it names a channel (Telegram, Slack or Discord), which is connected in the agent's settings, or a connector's key, such as
brevo, instead of the name that uses it, such asint-brevo-email; - it names a custom skill (
cs-<name>), which askillcard turns on and off; - it names a supporting part (
user_invocable: false), which comes with the connectors and skills that need it and isn't turned on or off by itself; - nothing would change: the
addnames one that is already on, or theremoveone the agent doesn't have; - it would change too much at once for a chat card: more than 12 connectors and skills in
with, or more than 20 scheduled tasks inpausesorresumes. The sentence reads<Title> changes too many connectors, skills or scheduled tasks at once for a chat card. Change it in the agent's settings.; - two connectors or skills that can't be on together (
conflicts_with) would both be on; - the
removewould take away something that connectors or skills staying on need: remove those first, or keep it; - voice calls would be left without a channel: with
util-voice-receptioniston, Twilio Voice Channel (int-twilio-channel) or Web Voice Channel (util-web-channel) must be on.
A card refused as the agent proposes it is never stored. A card refused as it is applied changes nothing and fails, with the sentence in error.
Adding and connecting in one step
An add card can take a key itself when its needs names a connector with mode: "key" and the same reply has a pending connect card for that connector, such as the one Wiro adds right after the add card. Wiro then applies the add card and, right after it, the connect card with the key, so both load with one restart.
With SetupCardApply. Send the add card's id to SetupCardApply with the key in values, as you would send it with the connect card:
curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/SetupCardApply" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"cardid": "q4n7s1v8b2xd",
"action": "apply",
"values": { "apikey": "YOUR_SERPER_API_KEY" }
}'
Wiro checks the values first, as applying the connect card would, against the connector as it will be once the add card is applied. When a value is refused, nothing is applied: both cards stay pending, and errors[0].message is the connect card's sentence, such as Serper API Key must be at least 20 characters. When the values pass, Wiro applies both cards and marks each one applied, and clients subscribed to the message's agenttoken get both new blocks. setup is the add card after the call, summary names both changes, and paired holds the connect card:
{
"result": true,
"errors": [],
"setup": {
"v": 1,
"id": "q4n7s1v8b2xd",
"kind": "add",
"key": "int-serper-search",
"needs": [{ "connector": "serper", "title": "Serper Web Search", "mode": "key" }],
"requestedby": "ada-uuid",
"createdat": 1743350406,
"status": "applied",
"actedat": 1743350460,
"actedby": "ada-uuid"
},
"restarting": true,
"summary": "Serper Web Search added. Serper Web Search connected.",
"paired": [
{
"setup": {
"v": 1,
"id": "h6w3k9p2m5tc",
"kind": "connect",
"connector": "serper",
"requestedby": "ada-uuid",
"createdat": 1743350406,
"status": "applied",
"actedat": 1743350460,
"actedby": "ada-uuid"
},
"result": true,
"error": null
}
]
}
Send every field the connector needs. A connector with more than one field, such as WooCommerce, WordPress or Gmail, is connected only once all its required fields are saved. When values hold only some of them, Wiro still applies the add card, and the connect card saves the fields it got and stays pending: result is true, summary names only the add card, and paired[0] has result: false and the error Saved <fields> for <Connector>. Still needed: <fields>. Send the missing fields with the connect card to finish it.
When the add card fails as it is applied, for example with Serper Web Search is already on., no key is saved. The connect card stays pending, and its error in paired reads <Connector title> is not connected: <Title> was not added. When the add card has no pending connect card to take the key, for example because its connector uses a sign-in or its connect card was turned down, Wiro answers This card takes no key. Apply it without one. When more than one of its connectors has a pending connect card, it answers This card brings more than one key. Apply it, then add each key on its own card. In both cases nothing changes and the card stays pending.
In messages sent with a project API key. When the only pending cards of the agent's latest reply are an add card and its connect card, and the key is all that connector needs, the card listing ends by offering the key as the reply:
The agent proposes this setup change. Nothing is applied yet.
Card 1: Add Serper Web Search (connector).
Still to connect: Serper Web Search.
Reply with your Serper Web Search key to add Serper Web Search and connect it at once, "yes" to add it now and give the key later, or "no" to turn it down.
Once Wiro has listed the add card, the key pasted as the reply applies both cards at once. Wiro reads the key from the reply by the same rules as in Keys in chat and answers ✅ Applied: Serper Web Search added. Serper Web Search connected., followed by Your agent is restarting to load the change. Continue in about a minute. when the agent restarts. setupresult.applied holds both cards' ids, and the stored message reads [key saved to Serper Web Search] in the key's place. A key the check refuses applies neither card, and Wiro answers ⚠️ Not saved: <reason>. Paste the key again as your reply. A yes after the listing applies the add card alone, and Wiro's answer ends by asking for the key with the Next: line. A key sent before Wiro has listed the add card saves nothing, since the person hasn't seen the change yet: the stored message reads [key removed] in its place, and Wiro answers with the listing. Send the key again after it. In the Wiro web chat, typed replies keep the two steps of adding a connector that takes a key. A connector that needs more than its key, such as WooCommerce, WordPress or Gmail, keeps the usual listing: a yes applies the add card, and its fields go on the connect card, in the web chat or as SetupCardApply values. To add and connect it at once, send all of its fields as values with the add card, as above. While the add card waits, a key typed as the reply saves nothing.
Connecting a sign-in connector
A sign-in connector is one with an oauth_provider in POST /Credentials/List, such as Google Analytics 4, Facebook or HubSpot. Its mode in needs says how its card connects it: appkeys takes the person's own app keys and then runs the sign-in, token takes a token and has Wiro check it (a Meta System User token, or Shopify's Client ID and Secret), and signin runs the sign-in with Wiro's app. Wiro adds its connect card to the reply with the add card that brings it, as for a key, and the agent can propose one for a sign-in connector that is on but not connected.
The card connects the connector with the endpoints and rules of your own integration: CredentialUpsert for the app keys or the token, OAuthConnect for the sign-in or the check, OAuthStatus for the accounts it listed and SetPickerAccounts for the ones picked. In the Wiro web chat the card does this for an agent admin; the agent never sees a key, a token or an account list, and a value typed into the chat is never saved to the connector.
Applying a sign-in connect card writes nothing. Wiro checks that the connector is connected, marks the card applied and answers summary <Title> connected with restarting: false, since the connection already restarted the agent if it needed to. Applied before the connection is complete, the card stays pending, with errorcode: "not_connected" and <Title> is not connected yet. Finish the sign-in on the card first. Sent with values, it stays pending with errorcode: "signin_values" and <Title> connects with its sign-in on the card, not with typed values. On a token card, both say token check in place of sign-in, such as <Title> is not connected yet. Finish the token check on the card first.
Adding and connecting in one step. Once the connector of an add card's sign-in connect card is connected, send the add card to SetupCardApply with signin: true. Wiro first checks that the connector reads connected as the add card will leave it; when it doesn't, nothing is applied (not_connected). Then it applies the add card, which restarts the agent once, and the connect card, and answers as for a key: summary <Add title> added. <Connector title> connected. and the connect card in paired. A connection made while nothing on the agent used it restarted nothing, so adding and connecting a sign-in connector this way restarts the agent once. When the add card itself fails, the connect card stays pending and its error in paired reads <Connector title> is connected, but <Add title> was not added. signin: true on an add card with no pending sign-in connect card answers signin_no_pair, This card has no sign-in to finish. Apply it without one., and on one that brings more than one, signin_many, This card brings more than one sign-in. Apply it, then connect each on its own card. signin_no_pair says token check in place of sign-in when every sign-in connector the add card names takes a token, and signin_many when every pending sign-in connect card it brings does. Without signin, the add card applies alone, as before, and its connect card stays pending.
In messages sent with a project API key, the connector is connected outside the chat, in your own product: its sign-in, app keys or token never go through the chat. When a yes applies an add card whose sign-in connect card still waits, Wiro's answer ends with Next: connect <Title> to finish. Its sign-in, app keys or token are entered outside this chat, never in it. A yes while only connect cards wait, one of them for a sign-in connector, applies nothing, starts no agent turn and is answered with A yes cannot connect <Title>. Its sign-in, app keys or token are entered outside this chat, never in it., one line per sign-in card. Both answers name each such card in setupresult.next, with the connector's mode, cardid and messageguid: connect it with the endpoints above, then apply the card with SetupCardApply. A sign-in connect card refused with not_connected answers the same entry in next. Each mode's calls, with every request and answer, are in Agent Chat Integration. In the Wiro web chat the same answers read Next: connect <Title> with its card in this chat. and A yes cannot sign in for you. Connect <Title> with its card in this chat.
Disconnecting a connector
A disconnect card removes a connector's saved key, as clearing it on the agent page does. It names the connector in connector and never holds a value. Once it is applied, the agent restarts without the connector's key, and skills that use the connector stop until it is connected again. The int-<name> connector that uses the key stays turned on: a remove card turns it off.
Wiro takes a disconnect card only for a connector that meets all three: it is connected now, it is connected with a key (the kind a connect card saves), and the agent can run without it (optional: true in the credentials of UserAgent/Detail). A connector turned off with a remove card counts too: its key stays saved, and a disconnect card can remove it even though nothing on the agent uses it any more. Connectors that use a sign-in (OAuth), channels (Telegram, Slack or Discord), the Wiro project the agent runs models with and connectors the agent needs to start are disconnected outside the chat, with the credential endpoints or on the agent page. A yes applies a disconnect card as it does any card other than connect.
Approving a setup card
After proposing a card, the agent asks in one short line whether to apply it, or, for a connect card, says how to connect it. An agent admin approves one card at a time, in one of three ways:
- Reply yes. Send a message that is only an approval, such as
yes,ok,approve,go ahead,evetor👍, withMessage/Sendin the same session. It acts on the pending cards of the agent's latest reply that are less than 30 minutes old, and it applies one card, only one whose exact content Wiro has shown you. - Press Apply on the card in the Wiro web chat.
- Call
POST /UserAgent/Message/SetupCardApplywith the card'sid. This also works after 30 minutes, as long as the card is pending.
What a yes does depends on where it is sent and how many cards are pending (connect cards don't count; see below):
| Pending cards | What yes does |
|---|---|
| One, in the Wiro web chat | Applies it. The card is shown under the agent's reply. |
| One, in a message sent with a project API key | The first yes applies nothing: Wiro answers with the card's exact content (the card listing). A second yes applies that card. |
| Several | The first yes gets the card listing, which numbers the cards. Then reply yes and a number, such as yes 2, to apply that card, one card per reply. A plain yes never applies one of several cards. In the web chat, the card's Apply button works too. |
A number works only for a card Wiro has listed: yes 2 sent before the listing gets the listing. A message that says more, such as yes, but at 10, is an ordinary message for the agent. A reply such as no or cancel dismisses the pending cards of the latest reply that are less than 30 minutes old, as a yes acts only on those, and goes to the agent as usual. A row added to the session between turns, such as a scheduled task's report, becomes the latest reply, so a yes or no sent after it finds no cards. While the agent isn't running, Wiro answers such a reply itself when it turned cards down: The setup change was turned down. or The <N> setup changes were turned down., with the cards' ids in setupresult.dismissed. A connect card needs its key or its sign-in, so a yes never applies one: when only connect cards for keys are pending, yes is an ordinary message, and when one of them is for a sign-in connector, Wiro answers the yes itself and says the connector is connected outside the chat (see Connecting a sign-in connector).
Wiro applies the stored card, checked again against the agent's current setup, never anything written in the reply. A card is applied at most once. When a connect card is applied, the other connect cards for the same connector still pending on the same person's messages in that chat from the last 7 days are marked applied too. setup and setupresult name only the card you acted on; History and Detail show the others. Only an agent admin can apply a card: a reply from anyone else changes nothing and gets Only an agent admin can apply setup changes. When a change needs a restart, the agent restarts to load it: continue the chat in about a minute. Replies Wiro handles itself don't have to wait for it; see Replies Wiro handles itself. Cards that restart a starting or running agent: add, remove, connect, disconnect and timezone cards, a schedule or skill card that creates one, a schedule card that changes the cron, and pause, resume, delete, disable and enable cards. A card that changes only the text of a custom skill or scheduled task (append, revert, or an update that keeps the schedule) reaches a running agent without a restart, and restarting is false; if the agent can't take the new text, Wiro restarts it instead.
The card listing
When a yes can't apply a card yet, Wiro answers it with the exact content of the pending cards and applies nothing. Each card has a number, its place on the agent's reply (1 to 3), a first line that says what it does, and the text it carries, each line starting with > . For one card, response reads:
The agent proposes this setup change. Nothing is applied yet.
Card 1: Create scheduled task cs-cron-morning-summary (title: Morning summary), schedule 0 9 * * 1-5.
Instructions:
> Every weekday, summarize yesterday's orders and post the summary in the web chat.
Reply "yes" to apply exactly this change, or "no" to turn it down.
An append card's first line reads Card 1: Add to custom skill <key>., followed by only the text it adds. A revert card's first line reads Card 1: Undo the last change to custom skill <key>., followed by the text it restores. A disconnect card has one line: Card 1: Disconnect <Connector> (its saved key is removed).
An add or remove card names what it changes by title, never by key. Its first line is Card 1: Add <Title> (connector)., Card 1: Add <Title> (skill)., Card 1: Remove <Title> (connector). or Card 1: Remove <Title> (skill)., and only the lines that apply follow it: Also turns on: <titles>., Also turns off: <titles>., Scheduled tasks that pause: <titles>., Scheduled tasks that run again: <titles>., Still to connect: <titles>., and Its saved key stays saved. for a connector removed while its key is saved. A connect card isn't listed: it waits for its key. When a message sent with a project API key gets the listing while the only pending cards are an add card and its connect card, and the key is all that connector needs, the listing's last line offers the key as the reply instead: Reply with your <Connector title> key to add <Title> and connect it at once, "yes" to add it now and give the key later, or "no" to turn it down. A connector that needs more keeps the usual last line. See Adding and connecting in one step.
With several cards, it starts with The agent proposes these setup changes. Nothing is applied yet. and ends with To apply one, reply "yes" and its number, such as "yes 1", one card per reply. Reply "no" to turn them all down. Show this text, as it is, to the person who approves. The listing is a reply Wiro handles itself (see below), and its setupresult lists no card.
Keys in chat
While setup from chat is on for a message, Wiro keeps keys out of the agent's conversation:
- A key as the reply. When the agent's latest reply has one pending
connectcard and its connector takes one key (or has one required key field still empty), an agent admin can paste the key as the reply, a text message of up to 2,000 characters with no attachments. Wiro reads the key for that card only while its connector is on the agent, or a pendingaddcard on the same reply names it inneedswithmode: "key"; otherwise the key is only removed, as in any other message. Wiro takes the reply as the key when it is in that connector's own key format, when the whole message is one key-like word, or when the key follows a word such askeyortoken(my key is ...). A sentence that only holds an id, a URL, an email address or a plain word is an ordinary message, and the card stays pending. While the connector is on the agent, Wiro saves the key to it and marks the card applied. The key never reaches the agent, and the stored message reads[key saved to <Connector title>]in its place. A key in another service's format is not saved, and when the connector needs more fields, the card stays pending and Wiro's answer names them; see Wiro's answers. A sign-in connector'sconnectcard never takes a key from the reply. While a pendingaddcard still brings the connector, the key is read for its card but not saved, since theaddcard goes first: Wiro answers⚠️ Not saved: Apply card <N> first: it turns on <Title>. Paste the key again as your reply., the stored message reads[key removed]in its place, and both cards stay pending. The one exception is a message sent with a project API key when the only pending cards are thatconnectcard and theaddcard that brings its connector, and the key is all that connector needs: once Wiro has listed theaddcard, the key applies both cards, and a key sent before that gets the listing. See Adding and connecting in one step. - Keys in other messages. Wiro removes clear keys: a key format Wiro knows for a provider or connector, and a key written after a word such as
key,token,secretorpassword. The stored text and the text the agent gets hold[key removed]in their place, and Send returnscontentmasked: truewith that text incontent. The agent can then propose aconnectcard. Other ids, such as Google Sheet and Drive ids, commit hashes and order numbers, reach the agent unchanged. While aconnectcard of the latest reply waits for its key, every key-like word in any other text message of up to 2,000 characters is removed without being saved. - From your own backend, save keys with
POST /UserAgent/CredentialUpsertinstead of sending them in a message. An MCP client saves them with itsset_agent_credentialstool.
Replies Wiro handles itself
When Wiro handles a message itself (a yes that applies a card or gets the card listing, a key pasted as the reply, a reply refused because the sender isn't an agent admin, a yes while a sign-in connect card waits, or a no that turned cards down while the agent isn't running), no agent turn runs and no credits are used, even when the agent has no credits left. Wiro does this whatever the agent's status, so these replies also work while the agent is stopped or restarting. Message/Send answers at once with the result:
{
"result": true,
"errors": [],
"messageguid": "d4e5f6a7-b8c9-0123-def4-567890123456",
"agenttoken": null,
"status": "agent_end",
"content": "yes",
"response": "✅ Applied: Scheduled task Morning summary created.\nYour agent is restarting to load the change. Continue in about a minute.",
"setupresult": {
"applied": ["k3v9q2m8x1za"],
"dismissed": [],
"failed": [],
"restarting": true
}
}
| Field | Type | Description |
|---|---|---|
agenttoken |
null |
There is no agent turn to follow on the WebSocket. |
status |
string |
"agent_end": the message is already finished. |
content |
string |
The message as stored. A saved key reads [key saved to <Connector title>]. |
response |
string |
Wiro's answer, always in English: the lines in Wiro's answers, or the card listing. Read setupresult in code, not this text. |
setupresult |
object |
applied and dismissed: the ids of the cards applied and dismissed. failed: [{ id, error }]. restarting: true when the agent restarts to load the change. All three lists are empty for a card listing. next: only when the answer leaves connectors to connect, [{ connector, title, mode, cardid?, messageguid? }]: first the connect cards its last lines name, each with its cardid and the messageguid of the message it is on, then each connector an applied add card brings that no card connects, such as one with mode: "page", without a card. Never on a listing, a refusal or a no. |
The message is stored like any finished exchange: Message/Detail and Message/History return it with status: "agent_end", metadata.type: "setup_result" and model: null. When the Send has a callbackurl, Wiro posts the result to it right away with status: "agent_end", as for a finished turn, and its metadata holds type: "setup_result", cards (the ids of the cards it acted on) and, when there is one, the same next as setupresult; see Agent Webhooks.
A card applied while the agent is stopped doesn't start it: the agent loads the change the next time it starts, and restarting is false. While the agent isn't running, every message Wiro doesn't answer itself gets the not-running refusal with agentstatus, a message with attachments or over 2,000 characters included.
Wiro's answers
The lines Wiro writes in response:
| Line | When |
|---|---|
✅ Applied: <summary>. |
The card was applied. The summary says what changed, such as Scheduled task Morning summary created, Custom skill Weekly report updated (also for an append card), Custom skill Weekly report restored, Custom skill Weekly report turned off, Time zone set to Europe/Istanbul, <Connector> connected, <Connector> disconnected, Brevo Email added or Weather removed. An add card applied together with its connect card's key names both, as in ✅ Applied: Serper Web Search added. Serper Web Search connected. An add card that brings a connector set up outside the chat, or a sign-in connector with no pending connect card on the reply, goes on with Connect <Title> in the agent's settings., naming each such connector by its title in needs. |
⚠️ Not applied: <reason> |
The change failed. The card's status is now failed, with the same reason in error. For example, This skill changed after the card was made. Ask the agent again. means the skill's text changed after an update, append or revert card was made. <Title> is not on this agent: add it first, then connect it. means a connect card's connector comes with a connector that isn't on, <Title>, and no pending add card on the reply turns it on, for example because that add card failed or was turned down. When more than one connector brings it, the sentence names them all and reads add one first. |
Your agent is restarting to load the change. Continue in about a minute. or Your agent is restarting to load the change. |
The change restarts the agent, or loads with a restart already under way, such as the one an add card started. The shorter line comes when the answer ends with a Next: line, which follows it. |
1 more setup change is still pending. or <N> more setup changes are still pending. |
Other cards of the same reply still wait. Reply yes and a card's number to apply the next one. |
Next: paste your <Title> key as your reply. or <N> connector cards still need their keys: add each key on its card. |
connect cards of the same reply still wait for their keys, such as the connect card that came with an add card just applied. A sign-in connect card is never counted. A connect card whose connector still waits for an add card that failed or was turned down isn't counted. When one card is counted, the Next: line ends the answer. <Title> is the connector's title in the needs of an add card on the same reply, or, when no add card names it, the connector's name in the agent's setup, such as Serper Web Search. When the answer says the agent is restarting, the line goes on with Send it now and it loads with this same restart., since a key saved while the agent is still stopping or queued for that restart loads with it. |
Next: connect <Title> to finish. Its sign-in, app keys or token are entered outside this chat, never in it. or Next: connect <Title> with its card in this chat. |
A yes applied an add card whose sign-in connect card still waits. In a message sent with a project API key, the connector is connected outside the chat, and setupresult.next names its card; in the Wiro web chat, the card connects it. See Connecting a sign-in connector. |
A yes cannot connect <Title>. Its sign-in, app keys or token are entered outside this chat, never in it. or A yes cannot sign in for you. Connect <Title> with its card in this chat. |
A yes while only connect cards wait, one of them for a sign-in connector. Nothing is applied and no agent turn runs. One line per sign-in card; key cards waiting with them keep their Next: line. In a message sent with a project API key, setupresult.next names the cards. |
Saved <fields> for <Connector>. Still needed: <fields>. |
The pasted key was saved, and the connector needs more fields. The card stays pending: add the rest on the card, or with CredentialUpsert. When Wiro can't name the missing fields, the second sentence reads It is not connected yet: finish it in the agent's settings. |
⚠️ Not saved: <reason>. Paste the key again as your reply. |
The pasted key was refused, for example because it is too short. Nothing was saved and the card stays pending. When the key was for an add card and its connect card, neither is applied. |
⚠️ Not saved: <Title> is still waiting. Reply "yes" to add it, or "no" to turn it down. |
In a chat over a project API key, a key came for an add card and its connect card after the connect card was applied, turned down or settled elsewhere. Nothing was saved, and the add card still waits for a yes or a no. |
That does not look like a <Connector> key, so it was not saved. Paste the <Connector> key as your reply. |
The reply holds a key in another service's format, while the latest reply's only pending connect card is for a connector that takes a key and is already on the agent. It comes whoever sent the key. Nothing was saved, the stored message reads [key removed] in its place, and the card stays pending. When Wiro knows the format, the sentence names it, such as (it looks like <kind>). Before a name that starts with a vowel, a becomes an, as in an Apollo key. While the connector isn't on the agent yet, as while the add card that brings it still waits, such a key is only removed, as in any other message. |
This setup change is being applied right now. Try again in a moment. |
Someone is applying the same card at this moment, or, for an add or remove card, another change to the agent's connectors and skills is going through. The card is still pending. |
This setup change was already handled. |
The card was applied or dismissed before this reply arrived. |
This card is older than 30 minutes. Use the card's button, or ask the agent again. |
The card turned 30 minutes old while the reply was handled. Apply it with its button or SetupCardApply. |
Only an agent admin can apply setup changes. |
The sender isn't an agent admin. Nothing changed. |
The setup change was turned down. or The <N> setup changes were turned down. |
A no or cancel sent while the agent isn't running turned the pending cards down. setupresult.dismissed holds their ids. While the agent runs, the no goes on to the agent like any other message. |
The agent proposes this setup change. Nothing is applied yet. |
The start of the card listing. Nothing changed. |
POST /UserAgent/Message/SetupCardApply
Applies or dismisses one setup card, or applies an add card together with its connect card when the key comes with it or its sign-in is done; the card's buttons in the Wiro web chat call it too. Wiro applies the stored card, checked again against the agent's current setup. See Setup From Chat.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | The agent instance GUID. |
messageguid |
string | Yes | The message that holds the card: the row whose timeline[] has the setup block. |
cardid |
string | Yes | The card's setup.id. |
action |
string | Yes | "apply" or "dismiss". |
values |
object | No | connect cards, and add cards that bring a connector with a pending connect card: { "<fieldname>": "<value>" } for the connector's fields, as POST /Credentials/Detail lists them. Only text, password, URL and email fields, up to 4,096 characters each. On an add card they are the values of its connect card, and Wiro applies both cards in one step. Send every field the connector needs: with only some of them, the add card is applied and the connect card saves those fields and stays pending. See Adding and connecting in one step. Wiro saves them to the connector; they are never returned and never reach the agent. |
signin |
boolean | No | true, with action: "apply", on an add card whose sign-in connect card's connector is now connected: Wiro applies both cards in one step. Never with values (Send values or signin, not both.). See Connecting a sign-in connector. |
Permission: applying needs an agent admin (the owner, or an admin of the agent's team). Any member who can see the chat can dismiss. The message must be one you can read with Message/History (in private Chat Mode, your own messages), and the card must be pending: an applied or dismissed card is never applied again.
Request
curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/SetupCardApply" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"cardid": "k3v9q2m8x1za",
"action": "apply"
}'
Response
{
"result": true,
"errors": [],
"setup": {
"v": 1,
"id": "k3v9q2m8x1za",
"kind": "schedule",
"action": "create",
"key": "cs-cron-morning-summary",
"title": "Morning summary",
"cron": "0 9 * * 1-5",
"instructions": "Every weekday, summarize yesterday's orders and post the summary in the web chat.",
"requestedby": "ada-uuid",
"createdat": 1743350406,
"status": "applied",
"actedat": 1743350460,
"actedby": "ada-uuid"
},
"restarting": true,
"summary": "Scheduled task Morning summary created"
}
| Field | Type | Description |
|---|---|---|
setup |
object|null |
The card after the action, in the same shape as a setup block's setup. null when the call is refused before the card is read: a missing parameter, an agent or message the caller can't reach, Setup From Chat off, a reply still being written, a caller who isn't an agent admin, a card someone else is applying at that moment, or a card that isn't there. |
restarting |
boolean |
true when the agent restarts to load the change. Continue the chat in about a minute. |
summary |
string |
A short English phrase that says what changed, such as Scheduled task Morning summary created or Brevo Email added. An add card applied with its connect card names both: Serper Web Search added. Serper Web Search connected. Empty when nothing was applied. |
paired |
object[] |
Only when values or signin: true are sent with a pending add card: its connect card after the call, as [{ setup, result, error }]. setup has the same shape as above, result is true when the card was applied with the key, and error is null or the sentence that says why not, such as Saved <fields> for <Connector>. Still needed: <fields>. when values held only some of the connector's fields. Empty when there is no single connect card to take the key. See Adding and connecting in one step. |
errorcode |
string |
Why a sign-in connect card, or an add card sent with signin: true, wasn't applied: not_connected, signin_values, signin_no_pair or signin_many. Absent otherwise. |
next |
object[] |
Only when the call leaves connectors to connect: [{ connector, title, mode, cardid?, messageguid? }]. An add card applied, alone, with values or with signin: true, lists its connectors that aren't connected yet, without the one its connect card connected in the same call. A sign-in connect card refused with not_connected or signin_values lists its own connector and card. A connect card for a connector set up outside the chat lists it with mode: "page". cardid and messageguid name the pending connect card that records the connection once it is made; a page entry has neither. Absent on the other refusals and on a dismissal. |
| Error | When |
|---|---|
Setup from chat is off for this agent. |
chatsetup is "off", or the call is sent with a project API key and chatsetup is "webchat". |
Wait until the agent finishes this reply, then apply it. |
action is "apply" while the reply that holds the card is still being written. "dismiss" works at any time. |
Only an agent admin can apply setup changes. |
The caller can see the chat but isn't an agent admin. |
Saved <fields> for <Connector>. Still needed: <fields>. |
A connect card's values were saved, and the connector needs more fields. The card stays pending and restarting can be true. Send the missing fields with the same card to finish it. Sent with an add card, the add card is applied, result is true, and this sentence is paired[0].error instead. |
The change could not be applied. Try again in a moment. |
The change failed on Wiro's side. The card's status is now failed. |
This skill changed after the card was made. Ask the agent again. |
An update, append or revert card whose skill text no longer matches its before: someone changed the skill after the card was made. Nothing changed, and the card's status is now failed. |
This agent's connectors or skills changed after the card was made. Ask the agent again. |
An add or remove card whose change no longer matches the agent's connectors and skills: it would turn on more than it shows, or turn off something else. Nothing changed, and the card's status is now failed. |
Apply card <N> first: it turns on <Title>. |
A connect card whose connector comes with an add card on the same message that isn't applied yet. Nothing is saved and the card stays pending: apply the add card first, or send the values with the add card to apply both. |
<Title> is not on this agent: add it first, then connect it. |
A connect card whose connector comes with a connector that isn't on, <Title>, when no pending add card on the message turns it on, for example because that add card failed or was turned down. Nothing is saved, and the card's status is now failed. When more than one connector brings it, the sentence names them all and reads add one first. |
This card takes no key. Apply it without one. |
values sent with an add card that has no pending connect card to take them. Nothing changed and the card stays pending. |
This card brings more than one key. Apply it, then add each key on its own card. |
values sent with an add card that brings more than one connector with a pending connect card. Nothing changed and the card stays pending. |
<Title> is not connected yet. Finish the sign-in on the card first. |
errorcode: "not_connected". A sign-in connect card, or an add card sent with signin: true, whose connector isn't connected yet. Nothing changed and the cards stay pending. For a token connector: <Title> is not connected yet. Finish the token check on the card first. On a connect card, next names its connector and the card. |
<Title> connects with its sign-in on the card, not with typed values. |
errorcode: "signin_values". values sent with a sign-in connect card. The card stays pending. For a token connector: <Title> connects with its token check on the card, not with typed values. |
This card has no sign-in to finish. Apply it without one. |
errorcode: "signin_no_pair". signin: true on an add card with no pending sign-in connect card. Nothing changed. When every sign-in connector the card names takes a token: This card has no token check to finish. Apply it without one. |
This card brings more than one sign-in. Apply it, then connect each on its own card. |
errorcode: "signin_many". signin: true on an add card that brings more than one sign-in connector with a pending connect card. Nothing changed. When each of those cards is a token card: This card brings more than one token check. Apply it, then connect each on its own card. |
Send values or signin, not both. |
Both were sent with the same call. |
<Title> is connected in the agent's settings, not from chat. |
A connect card whose connector is set up outside the chat. Nothing changed, the card stays pending, and next lists the connector with mode: "page". |
Another sentence in errors[0].message |
The message or card wasn't found, the card is no longer pending, a value was refused (nothing is saved and the card stays pending; on an add card, neither card is applied), or the change no longer fits the agent's setup. When the change itself fails, the card's status becomes failed with the sentence in error. |
Session Management
Sessions let you maintain separate conversation threads with the same agent:
- Each
sessionkeyrepresents 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
sessionkeyto continue a conversation - Delete a session with
/UserAgent/Message/DeleteSessionto clear history and free resources
User A's conversation:
{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"message": "Hello!",
"sessionkey": "user-alice"
}
User B's separate conversation with the same agent:
{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"message": "Hello!",
"sessionkey": "user-bob"
}
Multiple blocks in one turn
A single turn is not limited to one reasoning disclosure followed by one answer. The authoritative timeline can move through multiple calls:
call 0 / content 0: reasoning → Thinking
call 0 / content 1: answer → Initial answer text
call 0 / content 2: tool → Safe tool label/status
call 1 / content 0: reasoning → Thinking again
call 1 / content 1: answer → Final answer text
Render each reasoning block as its own accessible Thinking disclosure at its timeline position. Never combine reasoning blocks across calls, and never move them above or below answer/tool blocks to force an answer-first layout. Every reasoning block contains only the model-provided reasoning summary; raw chain-of-thought is never returned. agent_output is still useful for immediate accumulated answer typing, but it does not define the durable block order.
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",
"debugoutput": "",
"messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"timeline": [],
"result": true
}
3. Timeline block delta (emitted once per changed block):
{
"type": "agent_timeline_delta",
"agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
"message": {
"messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"block": {
"blockid": "c0:i0",
"callindex": 0,
"contentindex": 0,
"type": "reasoning",
"text": "I’ll compare verified releases and adoption data.",
"phase": "stream",
"version": 2,
"startedat": 1743350401,
"updatedat": 1743350403
}
},
"result": true
}
Merge message.block by blockid and accept it only when its version is strictly newer than the stored version of that block.
4. Provisional streaming output event (emitted multiple times, so replace your typing surface with message.raw 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...",
"answer": ["Here are the key AI trends..."]
},
"result": true
}
5. Final answer event (agent_end):
{
"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...",
"answer": ["Here are the key AI trends for 2026..."]
},
"result": true
}
| Field | Type | Description |
|---|---|---|
message.type |
string |
Always "progressGenerate" for agent output events. |
message.speed |
string |
Generation speed (e.g. "12.4"). |
message.speedType |
string |
Unit for speed: "words/s" (words per second). |
message.elapsedTime |
string |
Elapsed time since generation started (e.g. "3.2s"). |
message.tokenCount |
number |
Number of answer chunks received so far. Final model tokens arrive separately in agent_usage_report. |
message.wordCount |
number |
Number of words generated so far. |
message.raw |
string |
Full accumulated raw output text. |
message.answer |
string[] |
Array of answer blocks: the content to display. |
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):
POST /UserAgent/Message/Detail { "agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb" }
→ Check status field
→ If "agent_end": read response/debugoutput
→ If "agent_output": still generating, poll again
→ If "agent_error"/"agent_cancel": handle accordingly
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...",
"answer": ["Here are the key AI trends for 2026..."]
},
"endedat": 1743350408
}
Payload delivered to your
callbackurl.metadatais decoded into a JSON object. The webhook remains answer-focused and does not embed timeline blocks; callMessage/Detailwithmessageguidfor the authoritative persistedtimeline[].
Code Examples
curl (Send Message)
curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/Send" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"message": "What are the latest trends in AI?",
"sessionkey": "user-42"
}'
curl (Detail)
curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/Detail" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb"}'
curl (History)
curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/History" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"sessionkey": "user-42",
"limit": 50
}'
curl (Sessions / DeleteSession / Cancel)
# List sessions
curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/Sessions" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"useragentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}'
# Delete a session
curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/DeleteSession" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"sessionkey": "user-42"
}'
# Cancel an in-progress message
curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/Cancel" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb"}'
Python
import requests
import time
headers = {
"x-api-key": "YOUR_API_KEY",
"Content-Type": "application/json"
}
agent_guid = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
# Send a message
send_resp = requests.post(
"https://api.wiro.ai/v1/UserAgent/Message/Send",
headers=headers,
json={
"useragentguid": agent_guid,
"message": "What are the latest trends in AI?",
"sessionkey": "user-42"
}
)
send_data = send_resp.json()
agent_token = send_data["agenttoken"]
message_guid = send_data["messageguid"]
print(f"Message queued: {message_guid}")
# Poll until completion
while True:
detail_resp = requests.post(
"https://api.wiro.ai/v1/UserAgent/Message/Detail",
headers=headers,
json={"agenttoken": agent_token}
)
msg = detail_resp.json()["data"]
status = msg["status"]
print(f"Status: {status}")
if status == "agent_end":
print("Response:", msg["response"])
break
elif status in ("agent_error", "agent_cancel"):
print("Failed or cancelled:", msg["debugoutput"])
break
time.sleep(2)
# Get conversation history
history_resp = requests.post(
"https://api.wiro.ai/v1/UserAgent/Message/History",
headers=headers,
json={"useragentguid": agent_guid, "sessionkey": "user-42", "limit": 50}
)
messages = history_resp.json()["data"]["messages"]
for m in messages:
print(f"[{m['status']}] {m['content'][:60]}...")
# List sessions
sessions_resp = requests.post(
"https://api.wiro.ai/v1/UserAgent/Message/Sessions",
headers=headers,
json={"useragentguid": agent_guid}
)
for s in sessions_resp.json()["data"]["sessions"]:
print(f"Session: {s['sessionkey']} ({s['messagecount']} messages)")
# Cancel an in-progress message
requests.post(
"https://api.wiro.ai/v1/UserAgent/Message/Cancel",
headers=headers,
json={"agenttoken": agent_token}
)
Node.js
const axios = require('axios');
const headers = {
'x-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
};
const agentGuid = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
async function sendAndPoll() {
// Send a message
const sendResp = await axios.post(
'https://api.wiro.ai/v1/UserAgent/Message/Send',
{
useragentguid: agentGuid,
message: 'What are the latest trends in AI?',
sessionkey: 'user-42'
},
{ headers }
);
const { agenttoken, messageguid } = sendResp.data;
console.log('Message queued:', messageguid);
// Poll until completion
while (true) {
const detailResp = await axios.post(
'https://api.wiro.ai/v1/UserAgent/Message/Detail',
{ agenttoken },
{ headers }
);
const { status, response, debugoutput } = detailResp.data.data;
console.log('Status:', status);
if (status === 'agent_end') {
console.log('Response:', response);
break;
}
if (status === 'agent_error' || status === 'agent_cancel') {
console.log('Failed or cancelled:', debugoutput);
break;
}
await new Promise(r => setTimeout(r, 2000));
}
}
async function getHistory() {
const resp = await axios.post(
'https://api.wiro.ai/v1/UserAgent/Message/History',
{ useragentguid: agentGuid, sessionkey: 'user-42', limit: 50 },
{ headers }
);
const { messages, hasmore } = resp.data.data;
messages.forEach(m => console.log(`[${m.status}] ${m.content.slice(0, 60)}...`));
if (hasmore) console.log('More messages available — use "before" cursor to paginate');
}
async function manageSessions() {
// List sessions
const sessResp = await axios.post(
'https://api.wiro.ai/v1/UserAgent/Message/Sessions',
{ useragentguid: agentGuid },
{ headers }
);
sessResp.data.data.sessions.forEach(s =>
console.log(`Session: ${s.sessionkey} (${s.messagecount} messages)`)
);
// Delete a session
await axios.post(
'https://api.wiro.ai/v1/UserAgent/Message/DeleteSession',
{ useragentguid: agentGuid, sessionkey: 'old-session' },
{ headers }
);
}
// Cancel an in-progress message
async function cancelMessage(agenttoken) {
await axios.post(
'https://api.wiro.ai/v1/UserAgent/Message/Cancel',
{ agenttoken },
{ headers }
);
}
PHP
<?php
$headers = [
"Content-Type: application/json",
"x-api-key: YOUR_API_KEY"
];
$agentGuid = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
// Send a message
$ch = curl_init("https://api.wiro.ai/v1/UserAgent/Message/Send");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
"useragentguid" => $agentGuid,
"message" => "What are the latest trends in AI?",
"sessionkey" => "user-42"
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
$agentToken = $response["agenttoken"];
// Poll for result
do {
sleep(2);
$ch = curl_init("https://api.wiro.ai/v1/UserAgent/Message/Detail");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(["agenttoken" => $agentToken]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$detail = json_decode(curl_exec($ch), true);
curl_close($ch);
$status = $detail["data"]["status"];
} while (!in_array($status, ["agent_end", "agent_error", "agent_cancel"]));
echo $detail["data"]["response"];
C
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");
var agentGuid = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
// Send a message
var sendContent = new StringContent(
JsonSerializer.Serialize(new {
useragentguid = agentGuid,
message = "What are the latest trends in AI?",
sessionkey = "user-42"
}),
Encoding.UTF8, "application/json");
var sendResponse = await client.PostAsync(
"https://api.wiro.ai/v1/UserAgent/Message/Send", sendContent);
var sendResult = JsonSerializer.Deserialize<JsonElement>(
await sendResponse.Content.ReadAsStringAsync());
var agentToken = sendResult.GetProperty("agenttoken").GetString();
// Poll for result
while (true) {
await Task.Delay(2000);
var detailContent = new StringContent(
JsonSerializer.Serialize(new { agenttoken = agentToken }),
Encoding.UTF8, "application/json");
var detailResponse = await client.PostAsync(
"https://api.wiro.ai/v1/UserAgent/Message/Detail", detailContent);
var detail = JsonSerializer.Deserialize<JsonElement>(
await detailResponse.Content.ReadAsStringAsync());
var status = detail.GetProperty("data").GetProperty("status").GetString();
if (status == "agent_end") {
Console.WriteLine(detail.GetProperty("data").GetProperty("response").GetString());
break;
}
if (status is "agent_error" or "agent_cancel") break;
}
Go
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
"time"
)
func main() {
agentGuid := "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
// Send a message
sendBody, _ := json.Marshal(map[string]string{
"useragentguid": agentGuid,
"message": "What are the latest trends in AI?",
"sessionkey": "user-42",
})
req, _ := http.NewRequest("POST",
"https://api.wiro.ai/v1/UserAgent/Message/Send",
bytes.NewBuffer(sendBody))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("x-api-key", "YOUR_API_KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var sendResult map[string]interface{}
json.NewDecoder(resp.Body).Decode(&sendResult)
agentToken := sendResult["agenttoken"].(string)
// Poll for result
for {
time.Sleep(2 * time.Second)
detailBody, _ := json.Marshal(map[string]string{
"agenttoken": agentToken,
})
req, _ := http.NewRequest("POST",
"https://api.wiro.ai/v1/UserAgent/Message/Detail",
bytes.NewBuffer(detailBody))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("x-api-key", "YOUR_API_KEY")
resp, _ := http.DefaultClient.Do(req)
body, _ := io.ReadAll(resp.Body)
resp.Body.Close()
var detail map[string]interface{}
json.Unmarshal(body, &detail)
data := detail["data"].(map[string]interface{})
status := data["status"].(string)
if status == "agent_end" {
fmt.Println(data["response"])
break
}
if status == "agent_error" || status == "agent_cancel" {
fmt.Println("Failed:", data["debugoutput"])
break
}
}
}
Agent WebSocket
Receive real-time agent response streaming via a persistent WebSocket connection.
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, so 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. To follow a whole session instead, use the sessiontoken from Message/History; see Following a session. To follow an agent's Scheduled Tasks and other background runs, use a runstreamtoken; see Following an agent's background runs. The agent's live Screen has a socket of its own, opened with a one-time screenToken; see Screen and Take Control in Your App.
Connection Flow
- Connect: open a WebSocket connection to
wss://socket.wiro.ai/v1. - Receive welcome: the server pushes a one-shot
connectedframe confirming the upgrade. - Subscribe: send an
agent_infoframe with youragenttoken. - Receive
agent_subscribed: the server acknowledges the subscribe and reports the current lifecycle status, accumulated answer text, and persistedtimeline[]. - Stream: listen for
agent_start,agent_timeline_deltablock updates, provisionalagent_outputanswer snapshots, thenagent_end/agent_error/agent_cancel. - Receive
agent_usage_report: after a successfulagent_end, a one-shot token-usage/billing frame arrives on the sameagenttoken(~250-500 ms later). Optional to consume; keep the socket open briefly if you need it. - Close: keep the socket open for
agent_usage_reportif needed. After completion or reconnect, readMessage/Detailfor the authoritative persisted timeline and answer.
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, since 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 byPOST /UserAgent/Message/Send. Required, and only that token is accepted: a 30-character string of letters and digits. If it is missing, empty, or anything else (a session key, for example), the server responds with anerrorframe and subscribes to nothing (see Subscribe errors).
The server keeps the mapping connection ↔ agenttoken in memory for the life of the connection. You can send additional agent_info frames on the same socket to subscribe to more tokens (see Multi-session subscription).
3. Subscribe errors
If agenttoken is missing or blank, the server replies with:
{
"type": "error",
"message": "agenttoken-required",
"result": false
}
If agenttoken does not look like a Message/Send token (a session key, a user id, a number), the server replies with this instead and subscribes to nothing:
{
"type": "error",
"message": "agenttoken-invalid",
"result": false
}
The connection stays open: no disconnect. Fix the payload and resend. These two frames cover every shape-level rejection of an agent_info subscribe; message routing failures (unknown types, internal exceptions) are silently dropped and produce no frame at all.
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 does not add a second subscription. A connection holds up to 256 tokens: once it is full, each new token drops the oldest one, and a token you send again counts as the newest.
WS connect → { "type": "connected", "version": "1.0" }
{ agent_info, token: A } → { agent_subscribed ... token: A }
{ agent_info, token: B } → { agent_subscribed ... token: B }
{ agent_info, token: A } → (no-op — already subscribed)
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_infoandagent_infoframes both map to the same connection's token list.
There is no unsubscribe frame for agent_info tokens. To stop listening to a token without reconnecting, ignore its events client-side; tokens are cleaned up automatically when the connection closes.
Event Types
Frames flow in two directions. ↓ = server → client, ↑ = client → server.
| Direction | Event Type | Description |
|---|---|---|
| ↓ | connected |
Welcome frame pushed by the server right after the WebSocket upgrade. Fires exactly once per connection. |
| ↑ | agent_info |
Client-initiated subscribe frame. Carries the agenttoken issued by Message/Send. Can be sent multiple times on the same socket (one per token, up to 256). |
| ↓ | error |
Server-side rejection of a malformed subscribe (a missing or invalid agenttoken, or a malformed sessiontoken). Connection stays open; retry with a valid frame. An agent_run_subscribe can also get runstreamtoken-invalid or runstream-unavailable, which carry useragentguid; see Run stream errors. |
| ↓ | agent_subscribed |
Subscribe acknowledged. Carries the current lifecycle status, accumulated debugoutput, messageguid, and persisted timeline[]. If the agent already finished before you subscribed, this frame is your reconnect snapshot. |
| ↓ | agent_start |
The agent has started working on the message. The model is now generating. Emits exactly once per message. |
| ↓ | agent_timeline_delta |
One ordered public timeline-block update. Carries messageguid and one block; merge by blockid and that block's version, then sort by callindex, contentindex, and blockid. |
| ↓ | agent_output |
Provisional answer snapshot. Emits many times, and each carries the full accumulated raw answer text so far plus real-time metrics (speed, elapsedTime, tokenCount, wordCount). Replace (don't append) the typing surface on each event. |
| ↓ | agent_end |
Terminal success event. Same payload shape as agent_output but contains the final complete text with total metrics. Emits at most once. |
| ↓ | agent_error |
Terminal failure event. message is a plain string: the turn's coded failure message, the same text response holds (see Failed turns). Emits at most once. |
| ↓ | agent_cancel |
Terminal cancel event. Fires only when an already-active message is aborted mid-stream (via Message/Cancel or upstream abort). Cancels against a still-queued message do not broadcast this event, so check Message/Detail for those. Emits at most once. |
| ↓ | agent_usage_report |
Post-terminal usage/billing frame. Fires once, ~250-500 ms after a successful agent_end, on the same agenttoken. Carries the final token counts, model, tokencost, and remainingcredits for the message identified by messageguid. Not emitted for replayed usage callbacks or for turns with no chat message (cron/hook turns); follow those on the run stream. |
| ↓ | agent_wiroai_runtask |
Model-run discovery frame. Fires whenever the agent itself launches a Wiro model run during a turn (e.g. generating an image or video via int-wiro-aimodels). Arrives on the agenttoken of the turn that launched the run, carrying the new task's socketaccesstoken so you can subscribe to that run's task_* lifecycle and collect its outputs. See Model runs the agent triggers. |
| ↑ | agent_session_subscribe |
Follow a session with the sessiontoken from Message/History. See Following a session. |
| ↓ | agent_session_subscribed |
Session follow acknowledged. |
| ↓ | agent_message_inserted |
A message was added to a followed session between turns (a scheduled report, files sent after an answer, the result of background work). Carries the sessiontoken and the new row in message. |
| ↑ | agent_session_unsubscribe |
Stop following a session. No reply. |
| ↑ | agent_run_subscribe |
Follow an agent's background runs and model runs with the runstreamtoken from POST /UserAgent/RunStreamToken. See Following an agent's background runs. |
| ↓ | agent_run_subscribed |
Run stream follow acknowledged. Carries expiresat and the agent's open runs (runs) and model runs (models). |
| ↓ | agent_run_start |
A background run started: a Scheduled Task, a sub-agent, or another run with no chat message. Once per run. |
| ↓ | agent_run_block |
One step of an open background run changed. Carries one public block with text: null. |
| ↓ | agent_run_end |
A background run ended, with ok, reason, durationms, and endedat. Once per run. |
| ↓ | agent_run_model_start |
The agent started a Wiro model run, in a chat turn or a background run. Once per model run. |
| ↓ | agent_run_model_end |
A model run the agent started ended, with ok, outcome, durationms, and endedat. Once per model run. |
| ↑ | agent_run_unsubscribe |
Stop following an agent's runs. |
| ↓ | agent_run_unsubscribed |
Run stream follow stopped. |
Message Format
Every WebSocket frame is a JSON object. Agent stream frames (agent_start / agent_timeline_delta / agent_output / agent_end / agent_error / agent_cancel), plus the post-terminal agent_usage_report frame, share this base shape:
{
"type": "agent_output",
"agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
"message": { ... },
"result": true
}
| Field | Type | Description |
|---|---|---|
type |
string | Event name. See Event Types for the full list. |
agenttoken |
string | The token you subscribed with. Present on every agent lifecycle frame so multi-token subscribers can route the event to the right session. |
message |
varies | Empty string ("") for agent_start, { messageguid, block } for agent_timeline_delta, a progressGenerate answer object for agent_output / agent_end, the coded failure message (a plain string) for agent_error and agent_cancel, and a token-usage object for agent_usage_report. |
result |
boolean | true for success-side events (agent_subscribed / agent_start / agent_timeline_delta / agent_output / agent_end / agent_usage_report), false for failure-side events (agent_error / agent_cancel). See The result field. |
The control frames (connected, error) use a different shape with no agenttoken:
// Welcome — one per connection
{ "type": "connected", "version": "1.0" }
// Subscribe rejection — stays connected, just indicates the last agent_info was malformed
{ "type": "error", "message": "agenttoken-required", "result": false }
Run stream frames (agent_run_*) and their two errors carry useragentguid instead of an agenttoken; see Following an agent's background runs.
The agent_subscribed frame is a snapshot rather than a message wrapper. For a known token it carries status, debugoutput, messageguid, and timeline at the top level. When the token is unknown, status is "unknown" and those row-backed fields are omitted.
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,
debugoutputis always present andtimelineis an array (possibly empty). - If the agenttoken is unknown (typo, expired, already cleaned up from the buffer),
debugoutputis omitted entirely from the payload (no field at all). Always use"debugoutput" in payloadorpayload.debugoutput !== undefinedto 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": "",
"messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"timeline": [],
"result": true
}
Unknown token (status is "unknown" and no debugoutput field):
{
"type": "agent_subscribed",
"agenttoken": "wrongtoken123",
"status": "unknown",
"result": true
}
Possible status values:
| Status | Meaning |
|---|---|
agent_queue |
Message is queued, waiting for the agent to pick it up. |
agent_start |
Agent has started processing. |
agent_output |
Agent is actively streaming. debugoutput will contain accumulated text. |
agent_end |
Agent already finished. debugoutput contains the complete response. |
agent_error |
The turn failed. debugoutput holds its public failure message; see Failed turns. |
agent_cancel |
Message was cancelled. debugoutput may contain partial output. |
agent_done |
Status of a model_change marker row: a zero-content separator inserted when the chat model is switched mid-session. It is only used for these markers; normal turns terminate at agent_end and never carry this status. See Agent Messaging for model_change markers. |
unknown |
Status could not be determined. Treat as an error. |
agent_start
Signals that the agent has begun generating a response. The message field is an empty string:
{
"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...",
"answer": ["Here is the accumulated response text so far..."]
},
"result": true
}
The raw field contains the provisional cumulative SSE response as a single string. The answer array contains the same text split into segments. Replace your typing surface with raw (or joined answer) on each event; keep merging timeline updates independently until the corresponding answer block catches up.
agent_timeline_delta
Each event carries exactly one changed public block:
{
"type": "agent_timeline_delta",
"agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
"message": {
"messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"block": {
"blockid": "c0:i0",
"callindex": 0,
"contentindex": 0,
"type": "reasoning",
"text": "I’ll compare the available evidence before making a recommendation.",
"phase": "stream",
"version": 4,
"startedat": 1743350401,
"updatedat": 1743350404
}
},
"result": true
}
The merge contract is:
- Treat
blockidas an opaque deterministic identity. - Keep the incoming block only if there is no stored block with that ID, or its
versionis strictly greater than the stored version. - Replace only that block; a newer update for one block must never evict another block.
- Sort the merged values by
callindex ASC,contentindex ASC, thenblockid ASC.
version is per block, not global. A turn can therefore render Thinking → Answer or Tool → Thinking → Answer across multiple calls. reasoning blocks contain only model-provided reasoning summaries, never raw chain-of-thought. answer blocks expose safe answer text. tool blocks expose only toollabel, toolstatus, toolintegration, and toolaction; their text is null, and tool IDs, arguments, and results are not public.
The complete public block shape is blockid, callindex, contentindex, type, text, phase, version, startedat, and updatedat, and tool blocks also carry toollabel, toolstatus, toolintegration, and toolaction. Reasoning and answer blocks don't have these four fields. phase is stream, end, or error; timestamps can be null when unavailable. No additional internal correlation or execution metadata is emitted in this block.
When the agent proposes a setup change, a setup block arrives the same way. It sorts after the turn's other blocks, its text is null and it carries a setup object instead of tool fields; see Setup From Chat. A pending card's block has version 1. When the card is applied, dismissed or fails, the block comes again with version 2 and the new status; Message/Detail and Message/History always have the current state. A pending connect card's block also carries next, the connector it connects, as [{ connector, title, mode }].
Tool blocks carry two closed-list words:
toolintegrationnames the connector the step works in, as itskeyfromPOST /Credentials/List:adapty,adjust,apollo,apple-appstore,brevo,calendarific,dataforseo,facebook-pages,firebase,ga4,gmail,google-ads,google-business,google-calendar,google-drive,google-merchant-center,google-play,google-search-console,hubspot,instagram,keepa,lemlist,linkedin,mailchimp,meta-ads,reddit,revenuecat,roasit,sendgrid,serper,shopify,telegram,tiktok,tiktok-ads,twitter,wiro,woocommerce,wordpress, oryoutube.toolactionnames what the step does:screenshot,open-page,read-page,click,type,press-key,wait,upload,download,read-file, oredit-media.
Each is null when no word fits, and a block never has both. The words come with the block's first update, and every later update of the block carries them. A later update can carry a different word if the step changed, so read them from the newest version of the block. A block whose step is rewritten and no longer fits a word keeps its last word. Treat a value you don't know like null; Agent Messaging says what each word means.
A tool block update:
{
"type": "agent_timeline_delta",
"agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
"message": {
"messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"block": {
"blockid": "c0:i1",
"callindex": 0,
"contentindex": 1,
"type": "tool",
"text": null,
"toollabel": "exec",
"toolstatus": "requested",
"toolintegration": "shopify",
"toolaction": null,
"phase": "stream",
"version": 1,
"startedat": 1743350405,
"updatedat": 1743350405
}
},
"result": true
}
agent_end
Fires when the agent finishes responding. The structure is identical to agent_output, but 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...",
"answer": ["The complete agent response text..."]
},
"result": true
}
agent_error
The turn failed. message is a plain string: the turn's failure message, the same text the message's response and debugoutput hold, a code in brackets and a fixed sentence. The underlying error is never sent.
{
"type": "agent_error",
"agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
"message": "[AGENT_UNAVAILABLE] Agent is temporarily unavailable. Please try again shortly.",
"result": false
}
A turn that the model's safety policy stopped reads:
{
"type": "agent_error",
"agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
"message": "[SAFETY_POLICY_BLOCKED] The model's provider declined this request under its safety policy. Rephrase it and send it again.",
"result": false
}
To branch in code, match the code at the start of message; Failed turns lists every code and its text.
if (msg.type === 'agent_error') {
showError(msg.message)
if (msg.message.startsWith('[SAFETY_POLICY_BLOCKED]')) suggestRephrasing()
}
agent_cancel
Sent when the user cancels a message before the agent completes its response (only when the abort hits the bridge mid-flight, since queued-state cancels don't broadcast this event):
{
"type": "agent_cancel",
"agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
"message": "[REQUEST_CANCELLED] Request cancelled.",
"result": false
}
messageis[REQUEST_CANCELLED] Request cancelled.; usetype === "agent_cancel"as the signal. Subscribers that cancel from a queued state will receive no event at all (the message is simply markedagent_cancelin the database; check withPOST /UserAgent/Message/Detail).
agent_usage_report
A post-terminal frame that reports the final token usage and billing for the turn. It arrives shortly after agent_end (~250-500 ms later, once the turn's token usage has been metered and billed) on the same agenttoken-keyed channel as agent_start / agent_output / agent_end. A client already subscribed to the turn receives it automatically, with no extra subscribe needed.
{
"type": "agent_usage_report",
"agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
"result": true,
"message": {
"messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"inputtokens": 3450,
"outputtokens": 820,
"cachereadtokens": 2400,
"cachewritetokens": 0,
"totaltokens": 6670,
"model": "openai/gpt-5.6-sol",
"tokencost": 5,
"processedms": 4200,
"remainingcredits": 9995
}
}
The frame's agenttoken identifies the turn; the message.messageguid identifies the exact assistant message to patch. result is always true.
| Field | Type | Description |
|---|---|---|
messageguid |
string | UUID of the assistant message this usage applies to. Match it to the message row you want to update. |
inputtokens |
number | Uncached prompt tokens billed at the model's input rate. |
outputtokens |
number | Completion tokens generated by the model. |
cachereadtokens |
number | Prompt tokens served from the provider's prompt cache (billed at the cache-read rate). |
cachewritetokens |
number | Prompt tokens written to the provider's prompt cache during this turn. |
totaltokens |
number | Exact sum of input, output, cache-read, and cache-write tokens for the turn. |
model |
string | Provider/model slug used for this turn (e.g. "openai/gpt-5.6-sol"). |
tokencost |
number | Credits charged for this turn. |
processedms |
number | Server-side processing time for the turn, in milliseconds. |
remainingcredits |
number | Your account credit balance after this turn was billed. |
Use it to patch the per-message token columns and the live credit balance without re-fetching Message/History: when the frame arrives, look up the row by messageguid and write the token counts, model, tokencost, and remainingcredits straight onto it.
Like agent_output, it is a live broadcast: it is not replayed to clients that subscribe after it has already fired. If you reconnect after the fact, read usage from POST /UserAgent/Message/Detail (or Message/History) instead.
It is not emitted for:
- Idempotent / replayed usage callbacks: a turn is billed once, and a replayed usage callback does not re-broadcast the frame.
- Turns with no chat message: e.g. cron- or hook-triggered turns that produce no assistant message row have no
messageguidto key on, so no frame is sent. Follow those runs on the run stream instead.
Model runs the agent triggers
When the agent itself kicks off a Wiro model run during a turn (for example generating an image or a video through the int-wiro-aimodels skill), the bridge emits an agent_wiroai_runtask discovery frame. It hands you the new model run's socketaccesstoken so you can subscribe to that run and stream its progress and final media outputs. This is how a chat product surfaces a "live activity feed" of the media the agent is producing.
{
"type": "agent_wiroai_runtask",
"agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
"message": {
"taskid": "534574",
"socketaccesstoken": "eDcCm5yy7Z…",
"slugowner": "openai",
"slugproject": "gpt-image-1",
"categories": ["image"],
"status": "task_queue",
"response": { "result": true, "taskid": "534574", "socketaccesstoken": "eDcCm5yy7Z…" }
},
"result": true
}
| Field | Type | Description |
|---|---|---|
taskid |
string | The model run's task id, the same value as taskid in a POST /Run response. |
socketaccesstoken |
string | The run's task token. Subscribe to it (see below) to stream the model run's lifecycle and outputs. |
slugowner |
string | Model owner slug (e.g. "openai", "black-forest-labs"). |
slugproject |
string | Model slug (e.g. "gpt-image-1"). |
categories |
array<string> | The model's categories (e.g. ["image"], ["video"]). |
status |
string | Always "task_queue" at discovery: the run was just enqueued. |
response |
object | Convenience echo { result, taskid, socketaccesstoken }. |
This frame arrives on the turn's agenttoken. Like the lifecycle frames above, agent_wiroai_runtask goes to the sockets subscribed to the agenttoken of the turn in which the agent launched the run, and its agenttoken field carries that token. The subscription you already hold for the chat stream receives it, so no extra subscribe is needed. A session key is not a channel: agent_info with a session key returns agenttoken-invalid and brings nothing.
Then pivot to the task socket for outputs. Take message.socketaccesstoken and subscribe to the standard model-run WebSocket exactly as documented in WebSocket: send { "type": "task_info", "tasktoken": "<socketaccesstoken>" } and stream task_queue → task_start → task_output → task_postprocess_end. The final task_postprocess_end carries the output array (media URLs). The model-run task_* events are only delivered on the task's own socketaccesstoken channel. They are never re-broadcast on the agent channel.
Only fires for agent-initiated runs.
agent_wiroai_runtaskis emitted when the agent calls a model mid-turn. Model runs you launch yourself withPOST /Run(your ownx-api-key) do not produce this frame, because you already hold theirsocketaccesstokenfrom the/Runresponse. It fires only for model runs the agent starts while answering yourMessage/Sendturn. To see every model run the agent starts, Scheduled Tasks included, follow its run stream (agent_run_model_startandagent_run_model_end).
Following a session
Some messages are added to a session between turns: a scheduled report, files the agent sends after its answer, or the result of longer work it finished in the background. They belong to no turn, so they never stream on an agenttoken. To receive them as they are added, follow the session with the sessiontoken that Message/History returns for it:
{
"type": "agent_session_subscribe",
"sessiontoken": "Lp4vQ8sWn2KxT7cRb1YhZ6mDg9FjA3uEo5iNk0wXyHt"
}
The server acknowledges the follow:
{ "type": "agent_session_subscribed", "result": true }
Each message added to that session afterwards arrives as an agent_message_inserted frame:
{
"type": "agent_message_inserted",
"sessiontoken": "Lp4vQ8sWn2KxT7cRb1YhZ6mDg9FjA3uEo5iNk0wXyHt",
"message": {
"guid": "d4e5f6a7-b8c9-0123-def4-567890123456",
"uuid": "ada-uuid",
"sessionkey": "user-42",
"content": "",
"response": "Your product video is ready: https://cdn.wiro.ai/…/video.mp4",
"status": "agent_end",
"metadata": { "type": "subagent" },
"createdat": 1743350700,
"startedat": 1743350700,
"endedat": 1743350700
},
"result": true
}
| Field | Type | Description |
|---|---|---|
guid |
string | The new message's GUID. Add each guid once; skip it if History already gave it to you. |
uuid |
string | The row's uuid, as Message/History returns it. |
sessionkey |
string | The session the message was added to. |
content |
string | Always "": no prompt of yours belongs to these messages. |
response |
string | The message text. |
status |
string | Always "agent_end". |
metadata |
object | type is "subagent" for the result of work the agent finished in the background, "system" for the other messages. Other keys may appear; ignore the ones you don't use. |
createdat / startedat / endedat |
number | Unix timestamps in seconds, all set to when the message was added. |
- What arrives. A follower receives exactly the new messages its
Message/Historyread would show. Turns you start withMessage/Sendkeep streaming on their ownagenttoken; following the session doesn't repeat them. - Stop following with
{ "type": "agent_session_unsubscribe", "sessiontoken": "…" }. There is no reply. - Limit. One connection follows up to 16 sessions. Following another one drops the oldest follow.
- Errors. A malformed
sessiontokengets{ "type": "error", "message": "sessiontoken-invalid", "result": false }, and the connection stays open. The acknowledgement doesn't check which session a token belongs to, so send the token exactly as History returned it. - Reconnects. Frames aren't replayed, and follows end with the connection. After reconnecting, send
agent_session_subscribeagain and read History once to catch anything added while you were away. - Keep the token private. Whoever holds it receives the session's new messages. Read it from History when you open the session instead of storing it.
Following an agent's background runs
Some of an agent's work never shows up as a chat turn: its Scheduled Tasks, the sub-agents it starts to work on something in the background, and other runs that have no chat message, such as a reply on a connected Telegram, Slack or Discord channel. The run stream lets you follow them live: when each run starts, each step it takes, and when it ends. It also reports every Wiro model run the agent starts, in chat turns too, from start to end.
The stream carries labels only. Reasoning and answer text never appear on it (a block's text is always null), and a tool step shows only its label, its status and the two closed-list words a timeline tool block has.
Who can follow. The agent's owner and, on a team agent, the team's admins: the same people who can read the agent's Logs. With an API key, the check applies to the user who created the key's project, so the owner's project API key works too.
Get a run stream token
Call POST /UserAgent/RunStreamToken with the agent's guid:
curl -X POST "https://api.wiro.ai/v1/UserAgent/RunStreamToken" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321" }'
{
"result": true,
"runstreamtoken": "Zr8Qm2Kx7VbN4tLpW1sYc9HdF6gJaE3uTo5iRk0nXqM",
"expiresat": 1793664000,
"errors": []
}
runstreamtoken is an opaque token valid until expiresat, 24 to 48 hours after it is issued. Send it exactly as you got it, and keep it private: whoever holds it can follow the agent's runs until it expires. When less than 12 hours remain, get a new token and subscribe again with it. A stopped agent gets a token too.
Subscribe and unsubscribe
Send agent_run_subscribe on a connection to wss://socket.wiro.ai/v1. The same connection can carry your agent_info subscriptions too:
{
"type": "agent_run_subscribe",
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"runstreamtoken": "Zr8Qm2Kx7VbN4tLpW1sYc9HdF6gJaE3uTo5iRk0nXqM"
}
The server answers with the runs and model runs that are open right now:
{
"type": "agent_run_subscribed",
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"expiresat": 1793664000,
"runs": [
{
"runref": "q2Vt8kXw1bN0aZ3cR5sY7u",
"runkind": "cron",
"sessionkey": null,
"root": "cron",
"startedat": 1793491800,
"steps": 3,
"block": {
"blockid": "c2:i1",
"callindex": 2,
"contentindex": 1,
"type": "tool",
"text": null,
"toollabel": "exec",
"toolstatus": "requested",
"toolintegration": "shopify",
"toolaction": null,
"phase": "stream",
"version": 1,
"startedat": 1793491850,
"updatedat": 1793491850
}
}
],
"models": [
{
"modelref": "Hn4pW0sLx9Qe2Tm7Vb1Kd8",
"runref": "q2Vt8kXw1bN0aZ3cR5sY7u",
"sessionkey": null,
"slugowner": "google",
"slugproject": "nano-banana-pro",
"categories": ["image-generation"],
"startedat": 1793491860
}
],
"dropped": [],
"result": true
}
| Field | Type | Description |
|---|---|---|
useragentguid |
string | The agent you subscribed to. |
expiresat |
number | Unix seconds when this subscription ends: the expiresat of the token you sent. |
runs |
array | The agent's open runs, most recently active first, up to 256. Each has runref, runkind, sessionkey, root, startedat, steps, and block. |
models |
array | The agent's open model runs, newest startedat first, up to 256. Each has modelref, runref, sessionkey, slugowner, slugproject, categories, and startedat. |
dropped |
array | The guids of agents this connection stopped following to make room for this one. Usually empty; see Run stream limits. |
Run stream fields describes each field of a run and a model run. Events can start reaching you as soon as the subscription is in place, so one can arrive just before this reply. Subscribing again on the same connection is fine: the subscription then ends at the expiresat of the token you sent, and the reply has fresh lists.
To stop following an agent, send agent_run_unsubscribe. It needs no token, and the server answers agent_run_unsubscribed:
{
"type": "agent_run_unsubscribe",
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321"
}
{
"type": "agent_run_unsubscribed",
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"result": true
}
The reply comes even for an agent you weren't following. An unsubscribe with a malformed useragentguid gets no reply.
Run events
Each event carries type, useragentguid, message, and result. result is always true, also for a run that failed, so read ok. No event carries an agenttoken or any other token.
| Event | message keys |
When |
|---|---|---|
agent_run_start |
runref, runkind, sessionkey, root, startedat |
A background run started. Once per run. |
agent_run_block |
runref, runkind, sessionkey, root, block |
A step of an open background run changed. Sent only for a newer version of that block. |
agent_run_end |
runref, runkind, sessionkey, root, ok, reason, durationms, endedat |
The run ended. Once per run, and nothing follows it. |
agent_run_model_start |
modelref, runref, sessionkey, slugowner, slugproject, categories, startedat |
The agent started a Wiro model run. Once per model run. |
agent_run_model_end |
modelref, ok, outcome, durationms, endedat |
That model run ended. Once per model run. |
agent_run_start, agent_run_block, and agent_run_end cover only runs that have no chat message. A chat turn you start with Message/Send streams on its agenttoken and never shows up here. agent_run_model_start and agent_run_model_end cover every Wiro model run the agent starts, chat turns included.
A model run can start before its run's agent_run_start reaches you, and in rare cases a block can too: treat either one as the run being open.
A sub-agent started from a chat session:
{
"type": "agent_run_start",
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"message": {
"runref": "Lw7cR2nYb5Xq0Tz8Mk3Vh1",
"runkind": "subagent",
"sessionkey": "default",
"root": "chat",
"startedat": 1793492400
},
"result": true
}
A step of a Scheduled Task run finished:
{
"type": "agent_run_block",
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"message": {
"runref": "q2Vt8kXw1bN0aZ3cR5sY7u",
"runkind": "cron",
"sessionkey": null,
"root": "cron",
"block": {
"blockid": "c2:i1",
"callindex": 2,
"contentindex": 1,
"type": "tool",
"text": null,
"toollabel": "exec",
"toolstatus": "completed",
"toolintegration": "shopify",
"toolaction": null,
"phase": "end",
"version": 2,
"startedat": 1793491850,
"updatedat": 1793491858
}
},
"result": true
}
The Scheduled Task run ended:
{
"type": "agent_run_end",
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"message": {
"runref": "q2Vt8kXw1bN0aZ3cR5sY7u",
"runkind": "cron",
"sessionkey": null,
"root": "cron",
"ok": true,
"reason": "report",
"durationms": 147230,
"endedat": 1793491947
},
"result": true
}
A model run started in a chat turn, then its end:
{
"type": "agent_run_model_start",
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"message": {
"modelref": "Pz5mT1qXv8Rk3Nw0Yb7Lc2",
"runref": null,
"sessionkey": "default",
"slugowner": "google",
"slugproject": "nano-banana-pro",
"categories": ["image-generation"],
"startedat": 1793492460
},
"result": true
}
{
"type": "agent_run_model_end",
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"message": {
"modelref": "Pz5mT1qXv8Rk3Nw0Yb7Lc2",
"ok": true,
"outcome": "done",
"durationms": 41000,
"endedat": 1793492501
},
"result": true
}
Run stream fields
| Field | Type | Description |
|---|---|---|
useragentguid |
string | The agent the frame belongs to, for example "f8e7d6c5-b4a3-2190-fedc-ba0987654321". Route frames by it. |
runref |
string | null | Identifies one background run, for example "q2Vt8kXw1bN0aZ3cR5sY7u": 22 letters, digits, - or _. Every frame of a run carries the same value. Always set on run events and in runs. On model events and in models it names the run that started the model run, and it is null when a chat turn started it. |
modelref |
string | Identifies one model run, for example "Hn4pW0sLx9Qe2Tm7Vb1Kd8": 22 letters, digits, - or _. It is not the model run's taskid: this stream never carries a taskid or a socketaccesstoken. |
runkind |
string | What kind of run it is: cron (a Scheduled Task), subagent (a sub-agent working in the background), announce (a run that writes the result of background work back to its chat session), or other (any other run with no chat message, such as a reply on a connected channel). It can change while the run is open, for example from other to cron, but never back to other. Every event repeats it; the value on agent_run_end is final. Treat a value you don't know as other. |
root |
string | What the run belongs to: chat (a chat session, named in sessionkey), cron (a Scheduled Task), or unknown (not known yet). A later event can fill it in; once it is chat or cron, it never goes back to unknown. Model events don't carry it. Treat a value you don't know as unknown. |
sessionkey |
string | null | The key of the chat session the run works for: the sessionkey that Message/Send, Message/Sessions and Message/History use, for example "default", not the session's display name. Up to 512 characters, and only ASCII letters and digits, ., _, :, ~, @, + and -: a key with any other character, such as a space or ü, reads null here. A Scheduled Task run has null here, or its cs-cron- session key; root is cron either way. It is also null while the session isn't known yet. Once a run has a sessionkey, it doesn't go back to null. On model events it is the session key sent with the request that started the model run, or null. Whoever starts a session or a model run picks its key, so treat sessionkey as text from your users: escape it before you show it, and don't rely on it to tell who started a run. |
startedat |
number | Unix seconds when the run or model run started, for example 1793491800. When a run is first seen as it ends, agent_run_start and agent_run_end come together and startedat is worked out from the run's duration. |
steps |
number | In runs only: how many tool steps the run has taken so far, 0 or more. |
block |
object | null | On agent_run_block, the step that changed. In runs, the run's newest step, or null when it has none yet. See the block shape below. |
ok |
boolean | null | On end events: true when the run or model run succeeded, false when it failed, and null when its result is unknown (reason or outcome is lost). |
reason |
string | On agent_run_end, how the run ended. report: the run reported its own end. terminal: after the run's last update to a running step, a step ended (ok: true) or failed (ok: false), and no step was running again within two minutes. The first step to end or fail after that update sets ok and endedat; steps that end or fail after it change neither. lost: nothing came from the run for 60 minutes, it was still open 48 hours after it started, or the agent stopped, restarted or was deleted while the run was open (ok: null). Treat a value you don't know as lost. |
outcome |
string | On agent_run_model_end: done (the task reached task_postprocess_end with pexit "0"; ok: true), failed (task_error, or task_postprocess_end with another pexit; ok: false), cancelled (task_cancel: the task was cancelled or killed; ok: false), or lost (its end could not be read, for example it was still open after 24 hours; ok: null). Treat a value you don't know as lost. |
durationms |
number | On end events: how long the run or model run took, in milliseconds, for example 147230. Never null. |
endedat |
number | On end events: Unix seconds when it ended, for example 1793491947. With reason: "terminal", it is when that first step ended or failed (see reason); with reason: "lost", it is the run's last activity. |
slugowner, slugproject |
string | null | The model, as in POST /Run/{owner-slug}/{model-slug}, for example "google" and "nano-banana-pro". Each is up to 128 letters, digits, ., _ or -, or null when the slug is anything else. |
categories |
array | The model's categories as strings, for example ["image-generation"]. Up to 16, never null: an empty array when none are known. |
Every time is a whole number of Unix seconds and every duration a whole number of milliseconds.
block has the shape of an agent_timeline_delta block, with text always null:
- A tool block has
blockid,callindex,contentindex,type(tool),text,toollabel,toolstatus(requested,completed, orerror),toolintegration,toolaction,phase,version,startedat, andupdatedat.toolintegrationandtoolactionuse the same closed lists as timeline tool blocks, and whentoolintegrationis set,toolactionisnull. - A
reasoningoranswerblock hasblockid,callindex,contentindex,type,text,phase,version,startedat, andupdatedat. - A
blockidis unique within one run only, so key blocks byrunrefandblockidtogether.versionstarts at 1 and only grows: keep a block only when itsversionis higher than the one you hold. startedatis when the step was first seen, andupdatedatis the time of this update.phaseisstream,end, orerror. A step that reachedendorerrorstays there. An update that names no tool word keeps the block's last word.
Run stream errors
Both errors are error frames that carry useragentguid, and the connection stays open:
{
"type": "error",
"message": "runstreamtoken-invalid",
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"result": false
}
message |
When | What to do |
|---|---|---|
runstreamtoken-invalid |
The token is wrong, belongs to another agent or has expired, or the guid or the token is malformed. useragentguid is null when the guid itself is malformed. |
Get a new token, at most once a minute, and subscribe again. |
runstream-unavailable |
The agent's open runs could not be read just now, or the run stream is not available. | Keep the runs you hold and subscribe again later. |
When only the lists could not be read, your subscription is in place and events keep coming. The server never sends empty lists in place of runstream-unavailable, so empty runs and models always mean that nothing is open.
Run stream limits
- One connection follows up to 256 agents. Subscribing to one more drops the agent whose subscription is the oldest, and the reply lists it in
dropped. Subscribing again to an agent makes it the newest. Expired subscriptions are removed first and are not listed. runsandmodelshold up to 256 items each. An agent can have more than 256 open model runs:modelsthen holds the 256 newest.- An agent has up to 256 open runs at a time. A run that starts while 256 are open is sent late: at its next step once one of them has ended, or with its end.
categoriesholds up to 16 items, andsessionkeyup to 512 characters.- A run sends
agent_run_blockfor up to 512 different blocks. New blocks after that are not sent, and the run's end still comes. - A subscription ends at its
expiresat. Nothing arrives after that until you subscribe again with a new token.
Client rules
- Key runs by
runref, blocks byrunrefandblockid(keep a block only when itsversionis higher), and model runs bymodelref. - On
agent_run_subscribed, replace the agent's open runs and model runs with the lists, except one whose start or first frame reached you after you sent that subscribe: keep it, and let the next reply decide. Whenmodelshas 256 items, also keep the model runs it leaves out: they can still be open. - A run missing from a list has ended, and its result is unknown. So has a model run missing from a
modelslist with fewer than 256 items. - After
agent_run_endoragent_run_model_end, keep thatrunreformodelrefended for at least 10 minutes: a later list or frame never reopens it. - An
agent_run_blockoragent_run_model_startfor a ref you don't know opens it. - When
agent_run_block,agent_run_endoragent_run_model_endfor an agent you follow names a run or model run you don't hold, sendagent_run_subscribeagain for that agent, at most once every 30 seconds, so that its reply brings what you hold up to date. If a subscribe for that agent is already waiting for its reply, that one is enough. - After a reconnect, subscribe again for every agent: subscriptions belong to the connection, and frames are not replayed.
- While an agent has an open run or model run, subscribe again after 30 seconds with no
agent_run_*frame for it. - With no reply to
agent_run_subscribewithin 10 seconds, send it again after 5 seconds, then 15, then 60. - On
runstreamtoken-invalid, get a new token (at most once a minute) and subscribe again. Onrunstream-unavailable, keep what you hold and try again later. - When less than 12 hours remain before
expiresat, get a new token and sendagent_run_subscribewith it.
The result Field
Every agent lifecycle event includes a result boolean:
| Value | Events |
|---|---|
true |
agent_subscribed, agent_start, agent_timeline_delta, agent_output, agent_end, agent_usage_report, agent_session_subscribed, agent_message_inserted, agent_run_subscribed, agent_run_unsubscribed, agent_run_start, agent_run_block, agent_run_end, agent_run_model_start, agent_run_model_end |
false |
error (including the run stream's runstreamtoken-invalid and runstream-unavailable), agent_error, agent_cancel |
On agent_run_end and agent_run_model_end, result is true even when the run failed: read ok for how it went.
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:
| Field | Type | Description |
|---|---|---|
speed |
string | Current generation speed (e.g. "12.5"). |
speedType |
string | Speed unit: always "words/s" for agent responses. |
elapsedTime |
string | Wall-clock time since the stream started (e.g. "2.4s"). |
tokenCount |
number | Number of answer chunks received so far. Authoritative model token counts arrive in agent_usage_report. |
wordCount |
number | Total words in the accumulated response. |
These metrics update with every agent_output event, allowing you to display a live speed indicator or progress bar in your UI.
Timeline safety boundary
Public reasoning is available only as type: "reasoning" timeline blocks. Wiro publishes provider-authored summaries from supported OpenAI GPT-5 calls, not raw hidden chain-of-thought or generic provider traces. Tool blocks publish only a safe label, a status, and two closed-list words, toolintegration and toolaction. Wiro does not parse literal <think> tags from agent_output; treat any such text in raw as ordinary provisional answer output.
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"
}'
The response includes an agenttoken:
{
"result": true,
"errors": [],
"messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
"status": "agent_queue"
}
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: "", timeline: [] }
← agent_start { message: "" }
← agent_timeline_delta { message: { messageguid: "c3d4...", block: { blockid: "c0:i0", callindex: 0, contentindex: 0, type: "reasoning", version: 1 } } }
← agent_output { message: { raw: "Quantum", wordCount: 1 } }
← agent_timeline_delta { message: { messageguid: "c3d4...", block: { blockid: "c0:i1", callindex: 0, contentindex: 1, type: "answer", version: 1 } } }
← agent_output { message: { raw: "Quantum computing uses qubits...", wordCount: 28 } }
← agent_end { message: { raw: "Quantum computing uses qubits that...", wordCount: 118 } }
← agent_usage_report { result: true, message: { messageguid: "c3d4...", totaltokens: 6670, remainingcredits: 9994 } }
← = server → client, → = client → server. agent_output contains provisional full accumulated answer text. Replace (don't append) that typing surface; merge timeline blocks independently.
The full observable wire order for a normal turn is:
agent_queue → agent_start → (agent_timeline_delta | agent_output) × N → agent_end → agent_usage_report
agent_queue is not a WebSocket frame: it's the status returned synchronously in the Message/Send response (and reflected by agent_subscribed if you subscribe while the message is still queued). Timeline and provisional answer events can interleave between start and terminal status. On the failure path, agent_error or agent_cancel takes the place of agent_end, and no agent_usage_report follows. Message/Detail is authoritative for the final persisted timeline.
agent_wiroai_runtask is not part of this linear order: it fires out-of-band (zero or more times per turn, whenever the agent launches a model run) on the same agenttoken as the turn's other frames.
Code Examples
JavaScript
const agentToken = 'your-agent-token';
const ws = new WebSocket('wss://socket.wiro.ai/v1');
const timelineByMessage = new Map();
function mergeTimelineBlock(messageguid, block) {
const byId = timelineByMessage.get(messageguid) || new Map();
const previous = byId.get(block.blockid);
if (!previous || block.version > previous.version) {
byId.set(block.blockid, block);
}
timelineByMessage.set(messageguid, byId);
return [...byId.values()].sort(
(a, b) => a.callindex - b.callindex
|| a.contentindex - b.contentindex
|| a.blockid.localeCompare(b.blockid)
);
}
ws.onopen = () => {
console.log('Connected');
ws.send(JSON.stringify({
type: 'agent_info',
agenttoken: agentToken
}));
};
ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
switch (msg.type) {
case 'connected':
// One-shot welcome frame from server. OK to ignore.
break;
case 'error':
// Subscribe shape rejected (e.g. missing agenttoken).
console.error('Subscribe error:', msg.message);
ws.close();
break;
case 'agent_subscribed':
if (msg.status === 'unknown') {
console.error('Unknown token:', msg.agenttoken);
ws.close();
} else if (['agent_end', 'agent_error', 'agent_cancel'].includes(msg.status)) {
// We subscribed late — the agent already finished.
console.log('Already finished. Snapshot:', msg.debugoutput);
ws.close();
}
break;
case 'agent_start':
console.log('Agent started generating');
break;
case 'agent_output':
// message is a progressGenerate object; replace (don't append) your UI.
console.log('Streaming:', msg.message.raw);
break;
case 'agent_timeline_delta':
// Merge msg.message.block by blockid + per-block version, then sort
// by callindex/contentindex. Do not append in arrival order.
mergeTimelineBlock(msg.message.messageguid, msg.message.block);
break;
case 'agent_end':
console.log('Final:', msg.message.raw);
ws.close();
break;
case 'agent_error':
// message is the coded failure message, such as '[AGENT_UNAVAILABLE] ...'.
console.error('Failed:', msg.message);
ws.close();
break;
case 'agent_cancel':
console.warn('Cancelled:', msg.message);
ws.close();
break;
}
};
ws.onerror = (err) => console.error('WebSocket error:', err);
ws.onclose = () => console.log('Disconnected');
Python
import asyncio
import websockets
import json
async def listen_agent(agent_token):
uri = "wss://socket.wiro.ai/v1"
async with websockets.connect(uri) as ws:
await ws.send(json.dumps({
"type": "agent_info",
"agenttoken": agent_token
}))
print("Subscribed to agent session")
async for message in ws:
msg = json.loads(message)
print(f"Event: {msg['type']}")
if msg["type"] == "agent_output":
print("Streaming:", msg["message"].get("raw"))
elif msg["type"] == "agent_end":
print("Final:", msg["message"].get("raw"))
break
elif msg["type"] in ("agent_error", "agent_cancel"):
print("Error:", msg.get("message"))
break
asyncio.run(listen_agent("your-agent-token"))
Node.js
const WebSocket = require('ws');
const ws = new WebSocket('wss://socket.wiro.ai/v1');
ws.on('open', () => {
ws.send(JSON.stringify({
type: 'agent_info',
agenttoken: 'your-agent-token'
}));
});
ws.on('message', (data) => {
const msg = JSON.parse(data.toString());
console.log('Event:', msg.type);
if (msg.type === 'agent_output') {
console.log('Streaming:', msg.message?.raw);
}
if (msg.type === 'agent_end') {
console.log('Final:', msg.message?.raw);
ws.close();
}
});
ws.on('error', console.error);
ws.on('close', () => console.log('Disconnected'));
PHP
<?php
// Requires: composer require textalk/websocket
use WebSocket\Client;
$client = new Client("wss://socket.wiro.ai/v1");
$client->send(json_encode([
"type" => "agent_info",
"agenttoken" => "your-agent-token"
]));
while (true) {
$msg = json_decode($client->receive(), true);
echo "Event: " . $msg["type"] . PHP_EOL;
if ($msg["type"] === "agent_output") {
echo "Streaming: " . ($msg["message"]["raw"] ?? "") . PHP_EOL;
}
if ($msg["type"] === "agent_end") {
echo "Final: " . ($msg["message"]["raw"] ?? "") . PHP_EOL;
break;
}
}
$client->close();
C#
using System.Net.WebSockets;
using System.Text;
using System.Text.Json;
using var ws = new ClientWebSocket();
await ws.ConnectAsync(
new Uri("wss://socket.wiro.ai/v1"),
CancellationToken.None);
var subscribe = JsonSerializer.Serialize(new {
type = "agent_info",
agenttoken = "your-agent-token"
});
await ws.SendAsync(
Encoding.UTF8.GetBytes(subscribe),
WebSocketMessageType.Text, true,
CancellationToken.None);
var buffer = new byte[8192];
while (ws.State == WebSocketState.Open) {
var result = await ws.ReceiveAsync(
buffer, CancellationToken.None);
var json = Encoding.UTF8.GetString(
buffer, 0, result.Count);
using var doc = JsonDocument.Parse(json);
var type = doc.RootElement
.GetProperty("type").GetString();
Console.WriteLine("Event: " + type);
if (type == "agent_end") {
Console.WriteLine("Done!");
break;
}
}
Go
package main
import (
"encoding/json"
"fmt"
"log"
"github.com/gorilla/websocket"
)
func main() {
conn, _, err := websocket.DefaultDialer.Dial(
"wss://socket.wiro.ai/v1", nil)
if err != nil { log.Fatal(err) }
defer conn.Close()
sub, _ := json.Marshal(map[string]string{
"type": "agent_info",
"agenttoken": "your-agent-token",
})
conn.WriteMessage(websocket.TextMessage, sub)
for {
_, message, err := conn.ReadMessage()
if err != nil { break }
var msg map[string]interface{}
json.Unmarshal(message, &msg)
fmt.Println("Event:", msg["type"])
if msg["type"] == "agent_end" {
fmt.Println("Done!")
break
}
}
}
Swift
import Foundation
let url = URL(string: "wss://socket.wiro.ai/v1")!
let task = URLSession.shared.webSocketTask(with: url)
task.resume()
let subData = try! JSONSerialization.data(
withJSONObject: [
"type": "agent_info",
"agenttoken": "your-agent-token"
])
task.send(.string(
String(data: subData, encoding: .utf8)!
)) { _ in }
func receive() {
task.receive { result in
switch result {
case .success(let message):
switch message {
case .string(let text):
let msg = try! JSONSerialization
.jsonObject(with: text.data(
using: .utf8)!)
as! [String: Any]
print("Event:", msg["type"] ?? "")
if msg["type"] as? String == "agent_end" {
print("Done!")
return
}
case .data(let data):
print("Binary:", data.count, "bytes")
@unknown default: break
}
receive()
case .failure(let error):
print("Error:", error)
}
}
}
receive()
Kotlin
// Requires: org.java-websocket:Java-WebSocket
import org.java_websocket.client.WebSocketClient
import org.java_websocket.handshake.ServerHandshake
import java.net.URI
import org.json.JSONObject
val client = object : WebSocketClient(
URI("wss://socket.wiro.ai/v1")) {
override fun onOpen(h: ServerHandshake) {
send(JSONObject(mapOf(
"type" to "agent_info",
"agenttoken" to "your-agent-token"
)).toString())
}
override fun onMessage(message: String) {
val msg = JSONObject(message)
println("Event: " + msg.getString("type"))
if (msg.getString("type") == "agent_end") {
println("Done!")
close()
}
}
override fun onClose(
code: Int, reason: String, remote: Boolean
) { println("Disconnected") }
override fun onError(ex: Exception) {
ex.printStackTrace()
}
}
client.connect()
Dart
import 'dart:convert';
import 'package:web_socket_channel/web_socket_channel.dart';
final channel = WebSocketChannel.connect(
Uri.parse('wss://socket.wiro.ai/v1'),
);
channel.sink.add(jsonEncode({
'type': 'agent_info',
'agenttoken': 'your-agent-token',
}));
channel.stream.listen((message) {
final msg = jsonDecode(message);
print('Event: ' + msg['type'].toString());
if (msg['type'] == 'agent_output') {
print('Streaming: ' + (msg['message']?['raw'] ?? ''));
}
if (msg['type'] == 'agent_end') {
print('Done!');
channel.sink.close();
}
});
Quick Reference
connected, the welcome frame (server → client, sent once on upgrade):
{
"type": "connected",
"version": "1.0"
}
Subscribe frame (client → server):
{
"type": "agent_info",
"agenttoken": "aB3xK9..."
}
error for a malformed subscribe (server → client, sent when agent_info is missing agenttoken):
{
"type": "error",
"message": "agenttoken-required",
"result": false
}
error for a value that is not an agenttoken (server → client, for example a session key in agent_info):
{
"type": "error",
"message": "agenttoken-invalid",
"result": false
}
agent_subscribed for a valid token (empty debugoutput):
{
"type": "agent_subscribed",
"agenttoken": "aB3xK9...",
"status": "agent_queue",
"debugoutput": "",
"messageguid": "c3d4e5f6-...",
"timeline": [],
"result": true
}
agent_subscribed for an 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_timeline_delta with one public block update:
{
"type": "agent_timeline_delta",
"agenttoken": "aB3xK9...",
"message": {
"messageguid": "c3d4e5f6-...",
"block": {
"blockid": "c0:i0",
"callindex": 0,
"contentindex": 0,
"type": "reasoning",
"text": "I’ll verify the relevant constraints.",
"phase": "stream",
"version": 1,
"startedat": 1743350401,
"updatedat": 1743350402
}
},
"result": true
}
agent_output with streaming partials, emitted multiple times:
{
"type": "agent_output",
"agenttoken": "aB3xK9...",
"message": {
"raw": "Accumulated text...",
"speed": "12.5",
"wordCount": 28
},
"result": true
}
agent_end with the final response:
{
"type": "agent_end",
"agenttoken": "aB3xK9...",
"message": {
"raw": "Complete response...",
"speed": "14.2",
"wordCount": 118
},
"result": true
}
agent_error, the coded failure message:
{
"type": "agent_error",
"agenttoken": "aB3xK9...",
"message": "[AGENT_UNAVAILABLE] Agent is temporarily unavailable. Please try again shortly.",
"result": false
}
agent_cancel, sent only for an active-processing abort (queued-state cancels don't broadcast):
{
"type": "agent_cancel",
"agenttoken": "aB3xK9...",
"message": "[REQUEST_CANCELLED] Request cancelled.",
"result": false
}
agent_usage_report, the post-terminal usage/billing frame, ~250-500 ms after agent_end:
{
"type": "agent_usage_report",
"agenttoken": "aB3xK9...",
"result": true,
"message": {
"messageguid": "c3d4e5f6-...",
"totaltokens": 6670,
"model": "openai/gpt-5.4",
"tokencost": 5,
"remainingcredits": 9995
}
}
agent_run_subscribe, to follow an agent's background runs (client → server). Its reply, events, and errors are in Following an agent's background runs:
{
"type": "agent_run_subscribe",
"useragentguid": "f8e7d6c5-...",
"runstreamtoken": "Zr8Qm2..."
}
Connection Keep-Alive
The Wiro WebSocket server sends a ping every 30 seconds to keep the connection alive. Most standard WebSocket client libraries respond to pings automatically; if your client implements a custom frame handler, make sure it sends a pong within a few seconds of each ping or the server will drop the connection. After agent_error / agent_cancel you can close the socket immediately. After agent_end, one more frame (agent_usage_report) follows ~250-500 ms later; wait for it if you need usage/billing data. Read Message/Detail whenever you need the authoritative completed timeline.
Correlating Events With Your Messages
Every agent lifecycle frame carries agenttoken, so keep the mapping returned by Message/Send. Most stream frames do not include messageguid; agent_timeline_delta additionally carries message.messageguid, and agent_subscribed carries top-level messageguid. No chat stream frame carries useragentguid; only the run stream frames (agent_run_*) do.
The post-terminal agent_usage_report also names message.messageguid, but it arrives only after agent_end, so you still need the agenttoken → messageguid mapping for start/output/end/error/cancel routing.
Why agenttoken is the correlation key
Message/Sendissues exactly oneagenttokenper message and returns it alongsidemessageguidin the HTTP response.- The bridge stamps the same
agenttokenon every event it emits for that message. - Multiple connections can subscribe to the same
agenttokenand each gets the full event stream, soagenttokenis also the fan-out key. - A single socket can hold subscriptions for many
agenttokens at once (see Multi-session subscription), and the per-eventagenttokenlets your handler dispatch into the right UI element.
Recommended client pattern
- Call
POST /UserAgent/Message/Send: you get back{ messageguid, agenttoken, status: "agent_queue", ... }. - Store the mapping
agenttoken → messageguid(oragenttoken → your UI message id). - Send
{ "type": "agent_info", "agenttoken }on an open socket (new or existing, since connections can be reused). - In
ws.onmessage, readmsg.agenttokenon every lifecycle frame. Foragent_timeline_delta, mergemsg.message.blockbyblockidand strictly newer per-blockversion; never append in arrival order. - When the turn ends, delete the mapping so it doesn't leak memory across sessions. For successful turns, wait for the trailing
agent_usage_report(it arrives ~250-500 ms afteragent_end) before deleting, so you can attribute the usage to the right message; foragent_error/agent_cancel, delete immediately, since no usage report follows.
const tokenToMessageId = new Map()
const timelineByMessageId = new Map()
function mergeTimelineBlock(uiMessageId, block) {
const byId = timelineByMessageId.get(uiMessageId) || new Map()
const previous = byId.get(block.blockid)
if (!previous || block.version > previous.version) byId.set(block.blockid, block)
timelineByMessageId.set(uiMessageId, byId)
const timeline = [...byId.values()].sort(
(a, b) => a.callindex - b.callindex
|| a.contentindex - b.contentindex
|| a.blockid.localeCompare(b.blockid)
)
updateUI(uiMessageId, { timeline })
}
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 // unknown token — probably stale
switch (msg.type) {
case 'agent_timeline_delta':
mergeTimelineBlock(uiMessageId, msg.message.block)
break
case 'agent_output':
updateUI(uiMessageId, { streaming: msg.message.raw })
break
case 'agent_end':
// Keep the mapping — agent_usage_report still follows for successful turns.
updateUI(uiMessageId, { final: msg.message.raw, status: 'agent_end' })
break
case 'agent_usage_report':
updateUI(uiMessageId, { usage: msg.message, remainingCredits: msg.message.remainingcredits })
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 (oneagent_infoframe each, and the server de-duplicates automatically). - Key all UI updates on
agenttoken, not onsessionkey(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
- Detect disconnect:
ws.onclose/ stream exception / ping timeout. - Reconnect: open a new WebSocket to
wss://socket.wiro.ai/v1. - Wait for welcome: receive
{ "type": "connected", "version": "1.0" }(optional but clean). - Re-subscribe: send
{ "type": "agent_info", "agenttoken": "..." }with the same token. - Handle
agent_subscribed: the server reports the current status and persistedtimeline[]. Three cases:statusisagent_queue/agent_start/agent_output→ stream is still live; accumulated provisional answer text is indebugoutput. Seed your block map fromtimeline, then merge future deltas.statusisagent_end→ the agent already finished.debugoutputholds the full final response. FetchPOST /UserAgent/Message/Detailfor the canonical record (including completetimeline,metadata, attachments, and timestamps), then close the socket.statusisagent_error/agent_cancel→ the agent already failed / was cancelled.debugoutputmay contain partial output. No further events. FetchPOST /UserAgent/Message/Detailfor the persisted error details.
On reconnect you do not receive replays of past agent_output or agent_timeline_delta frames. Use debugoutput and timeline on agent_subscribed as the snapshot of what you missed.
Example retry strategy
const MAX_BACKOFF_MS = 30000
let backoff = 1000
function connect(agenttoken, onStreamingChunk, onFinal, onFailure) {
const ws = new WebSocket('wss://socket.wiro.ai/v1')
let finished = false
ws.onopen = () => {
backoff = 1000
ws.send(JSON.stringify({ type: 'agent_info', agenttoken }))
}
ws.onmessage = (event) => {
const msg = JSON.parse(event.data)
if (msg.type === 'connected') return
if (msg.type === 'agent_subscribed') {
if (msg.status === 'unknown') {
finished = true
onFailure({ reason: 'unknown-token' })
ws.close()
return
}
if (['agent_end', 'agent_error', 'agent_cancel'].includes(msg.status)) {
finished = true
onFinal(msg.debugoutput || '')
ws.close()
}
return
}
if (msg.type === 'agent_output') onStreamingChunk(msg.message)
if (msg.type === 'agent_end') {
finished = true
onFinal(msg.message.raw)
ws.close()
}
if (['agent_error', 'agent_cancel'].includes(msg.type)) {
finished = true
onFailure({ reason: msg.type, message: msg.message })
ws.close()
}
}
ws.onclose = () => {
if (finished) return
setTimeout(() => connect(agenttoken, onStreamingChunk, onFinal, onFailure), backoff)
backoff = Math.min(backoff * 2, MAX_BACKOFF_MS)
}
}
Guidance:
- 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 anunknownstatus, since the work is either done or the token is gone. - Idempotent re-subscribe: sending the same
agenttokenagain 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/Detailat 1-2 second intervals untilstatusis 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 message exists (Wiro does not auto-purge messages on a short timer; tokens remain queryable indefinitely after the run ends).
| Event | Effect on token |
|---|---|
Message/Send |
Token is minted, row is inserted with status: "agent_queue", broadcast to all queue subscribers. |
| Agent starts working | Emits agent_start to every active subscriber. |
| Timeline block changes | Emits one agent_timeline_delta update with { messageguid, block }; the persisted row keeps the merged ordered timeline. |
| Each SSE chunk | Emits agent_output to every active subscriber (with full accumulated raw). |
| Stream finishes | Emits agent_end with the final progressGenerate payload, or agent_error with the public failure message when the turn failed; the message's status becomes terminal. |
| Usage billed | ~250-500 ms after a successful agent_end, emits agent_usage_report with final token counts, model, tokencost, and remainingcredits. Not emitted for replayed usage callbacks or for turns with no chat message (cron/hook turns), which you follow on the run stream. |
| Bridge exception | Emits agent_error with the public failure message; the message's status becomes agent_error, and response and debugoutput hold the same text. |
Message/Cancel during active stream |
Bridge aborts, emits agent_cancel; the message's status becomes agent_cancel. |
Message/Cancel while queued |
The message's status becomes agent_cancel immediately. No WebSocket event is broadcast (the bridge never started). Clients checking via the socket must consult Message/Detail for queued-state cancels. |
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, so if you leak a token to another user, they can read the stream. Treat tokens like short-lived secrets scoped to the message.
Agent Webhooks
Receive agent response notifications via HTTP callbacks.
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 on the bridge, Wiro sends a POST request to your URL with the result. Callbacks fire on agent_end (success), agent_error (failure during processing), and agent_cancel only when the abort hits the bridge mid-flight. Messages cancelled while still queued (status agent_queue, before the bridge picks them up) are marked agent_cancel in the database but do not fire a webhook, because there was no processing attempt to report on. See the "When the cancel webhook fires" note below for the full decision table.
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.
A setup reply that Wiro handles itself, such as a yes that applies a setup card, runs no agent turn: Wiro posts its result to the callbackurl right away, with status: "agent_end". Its metadata holds type: "setup_result", cards (the ids of the cards it acted on) and, when the answer leaves connectors to connect, next: [{ connector, title, mode, cardid?, messageguid? }], as in setupresult. See Replies Wiro handles itself.
Results that arrive later. When the agent moves longer work to the background, its turn ends with a short line saying the result will follow, and that line is what your
callbackurlreceives (status: "agent_end"). The result is added to the session later as a separate message and doesn't call thecallbackurl. Read it withMessage/History, or follow the session on the Agent WebSocket.
Setting a Callback URL
Include callbackurl in your message request body. POST /UserAgent/Message/Send:
{
"useragentguid": "your-useragent-guid",
"message": "What are today's trending topics?",
"sessionkey": "user-123",
"callbackurl": "https://your-server.com/webhooks/agent-response"
}
The callback URL is stored per-message. You can use different URLs for different messages, or omit it entirely if you prefer polling or WebSocket.
Callback Payload
When the agent finishes, Wiro sends a POST request to your callbackurl with Content-Type: application/json. The payload is deliberately answer-focused: it contains the final answer/error and structured answer metadata, but not the ordered turn timeline.
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...",
"answer": ["Here are today's trending topics in tech..."]
},
"endedat": 1712050004
}
Error (agent_error)
{
"messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"status": "agent_error",
"content": "What are today's trending topics?",
"response": "[AGENT_UNAVAILABLE] Agent is temporarily unavailable. Please try again shortly.",
"debugoutput": "[AGENT_UNAVAILABLE] Agent is temporarily unavailable. Please try again shortly.",
"metadata": {},
"endedat": 1712050004
}
Cancelled (agent_cancel)
{
"messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"status": "agent_cancel",
"content": "What are today's trending topics?",
"response": "[REQUEST_CANCELLED] Request cancelled.",
"debugoutput": "[REQUEST_CANCELLED] Request cancelled.",
"metadata": {},
"endedat": 1712050004
}
The
responseanddebugoutputfields hold[REQUEST_CANCELLED] Request cancelled.; usestatus === "agent_cancel"as the signal.When the cancel webhook fires:
agent_cancelis delivered only when the agent bridge catches anAbortErrorduring active processing, i.e. the message had already started on the agent side and was aborted mid-flight (viaPOST /UserAgent/Message/Cancelor an upstream timeout). For messages cancelled before they reach the bridge (still queued, or an instantMessage/Cancelthat beats dispatching), the message is markedagent_cancelin the database and returned as such inPOST /UserAgent/Message/Detail, but no webhook is fired, because there was no processing attempt to report on. UsePOST /UserAgent/Message/Detail(checkingstatus === "agent_cancel") as the canonical source of truth for cancellation; WebSocket subscribers receive theagent_cancelevent only on active-processing aborts (same condition as the webhook). Treat the webhook as a best-effort "processing was interrupted" signal.
Field Reference
| Field | Type | Description |
|---|---|---|
messageguid |
string | Unique identifier of the message. Use this to correlate with your records. |
status |
string | Final status: agent_end, agent_error, or agent_cancel. |
content |
string | The original user message you sent. |
response |
string | The agent's full response text on success. For errors, contains the error message. For cancellation, contains the abort reason. |
debugoutput |
string | Same as response: the full accumulated output text. Included for consistency with the polling API. |
metadata |
object | Structured answer data, performance metrics, and raw text. Timeline blocks are not embedded in webhooks. Empty object ({}) for error and cancel statuses. |
endedat |
number | Unix timestamp (UTC seconds) when processing finished. |
The metadata Object
On successful completion (agent_end), the metadata object contains the structured answer and final stream metrics:
| Field | Type | Description |
|---|---|---|
type |
string | Always "progressGenerate". |
task |
string | Always "Generate". |
raw |
string | The complete response text. |
answer |
array | Array of response segments: the content to show the user. |
speed |
string | Final generation speed (e.g. "14.2"). |
speedType |
string | Speed unit: "words/s". |
elapsedTime |
string | Total generation time (e.g. "8.1s"). |
tokenCount |
number | Number of answer chunks received by the bridge. Use the message's billing columns for authoritative model tokens. |
wordCount |
number | Total words in the response. |
For agent_error and agent_cancel, metadata is an empty object {}. Always check status before accessing metadata fields.
After receiving the webhook, call POST /UserAgent/Message/Detail with messageguid whenever you need the authoritative top-level timeline[]. It preserves the ordered reasoning, answer, and safe tool-label/status blocks for the completed turn.
Note: For
agent_errorandagent_cancel, the webhook'sresponseanddebugoutputhold the same coded failure message asPOST /UserAgent/Message/Detail; see Failed turns. The underlying error is never sent.
Status Values
| Status | Description | response contains |
metadata contains |
|---|---|---|---|
agent_end |
Agent completed successfully | Full response text | Structured answer and metrics |
agent_error |
The turn failed | The public failure message; see Failed turns | Empty object {} |
agent_cancel |
Message was cancelled before completion | [REQUEST_CANCELLED] Request cancelled. |
Empty object {} |
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
messageguidagainst your own records - Always use HTTPS endpoints in production
- Use a public address. Wiro doesn't call a
callbackurlwhose host is, or resolves to, a private, loopback or link-local address; that message gets no webhook, and its result stays readable withMessage/Detail - Validate the payload structure before processing
- Consider returning 200 immediately and processing the payload asynchronously to avoid timeouts
Code Examples
Webhook Receiver: Node.js (Express)
const express = require('express');
const app = express();
app.use(express.json());
app.post('/webhooks/agent-response', (req, res) => {
const { messageguid, status, content, response, endedat } = req.body;
if (status === 'agent_end') {
console.log(`Agent completed: ${messageguid}`);
console.log(`Response: ${response}`);
} else if (status === 'agent_error') {
console.error(`Agent error for ${messageguid}: ${response}`);
} else if (status === 'agent_cancel') {
console.log(`Agent cancelled: ${messageguid}`);
}
res.sendStatus(200);
});
app.listen(3000);
Webhook Receiver: Python (Flask)
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/webhooks/agent-response', methods=['POST'])
def agent_webhook():
data = request.json
messageguid = data.get('messageguid')
status = data.get('status')
response_text = data.get('response')
if status == 'agent_end':
print(f"Agent completed: {messageguid}")
print(f"Response: {response_text}")
elif status == 'agent_error':
print(f"Agent error for {messageguid}: {response_text}")
elif status == 'agent_cancel':
print(f"Agent cancelled: {messageguid}")
return jsonify({"ok": True}), 200
if __name__ == '__main__':
app.run(port=3000)
Webhook Receiver: PHP
<?php
$payload = json_decode(file_get_contents('php://input'), true);
$messageguid = $payload['messageguid'] ?? '';
$status = $payload['status'] ?? '';
$response = $payload['response'] ?? '';
if ($status === 'agent_end') {
error_log("Agent completed: $messageguid");
error_log("Response: $response");
} elseif ($status === 'agent_error') {
error_log("Agent error for $messageguid: $response");
} elseif ($status === 'agent_cancel') {
error_log("Agent cancelled: $messageguid");
}
http_response_code(200);
echo json_encode(['ok' => true]);
Sending a Message with Callback: curl
curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/Send" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"message": "Summarize today'\''s news",
"sessionkey": "user-123",
"callbackurl": "https://your-server.com/webhooks/agent-response"
}'
Response
{
"result": true,
"errors": [],
"messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"agenttoken": "eDcCm5yyUfIvMFspTwww49OUfgXkQt",
"status": "agent_queue"
}
The agenttoken can be used to track the message via Agent WebSocket for real-time streaming, while the webhook delivers the final result to your server.
Agent Credentials & OAuth
Configure third-party service connections for your agent instances. Browse the platform's credential registry, set API keys, direct machine credentials, or OAuth, and audit credential edits over time.
Overview
Wiro agents connect to external services (social platforms, ad networks, email tools, CRMs) through three credential methods:
- API Key credentials: set directly via
POST /UserAgent/CredentialUpsert(bulk field upsert per provider). - OAuth credentials: redirect-based authorization via
POST /UserAgentOAuth/OAuthConnect, where Wiro handles token exchange server-side. - Hybrid direct credentials: save a machine credential, call
OAuthConnectfor server-side validation/discovery, then finalize any account picker without exposing provider tokens to the browser.
From the agent's chat. With Setup From Chat on, the agent can propose a
connectcard, and an agent admin pastes the key as the reply or enters it on the card. Wiro saves it to the connector, and the agent never sees it. A connector that uses a sign-in gets aconnectcard too: in the Wiro web chat the card takes its app keys or token and runs its sign-in with the endpoints below (see Connecting a sign-in connector). A connector set up only outside the chat gets noconnectcard. To run these steps from a chat in your own product, see Agent Chat Integration.
Each external service is documented as its own integration page with the complete setup walkthrough, API reference, troubleshooting, and multi-tenant architecture notes. Use the catalog below to jump to the one you need.
Read & write paths at a glance:
| Operation | Endpoint |
|---|---|
| Browse all credentials in the registry | POST /Credentials/List (public) |
| Inspect a single credential schema | POST /Credentials/Detail (public) |
| Find the credential a skill needs | POST /Skills/CredentialSchema (public) |
| Write one or more credential fields | POST /UserAgent/CredentialUpsert |
| Save a key from the agent's chat | A connect card: the key pasted as the reply, or POST /UserAgent/Message/SetupCardApply with values |
| Connect a sign-in connector from the agent's chat | Its connect card once the sign-in is done: POST /UserAgent/Message/SetupCardApply, with signin: true on the add card that brings it |
| Connect the agent's Wiro project by its id | POST /UserAgent/CredentialProjectBind |
| Discover external communication channels | POST /Skills/List → channels[] (public) |
| Connect or disable an external channel | POST /UserAgent/CredentialUpsert |
| Read version history of a credential | POST /UserAgent/CredentialFieldHistory |
Read responses from
POST /UserAgent/Detailexpose the composedcredentialstree (each provider with its_connected/optional/extra/_editable/_schemaflags), thecustomskills[]array, thescheduledskills[]array (scheduled tasks), theskills[]array of enabled skill names, thetokenRates+agentModelobjects, and the flat credit fields (monthlycredits,extracredits,usedcredits,remainingcredits,creditperiod,creditsyncat) as top-level fields on the useragent object.POST /UserAgent/MyAgentsrows carrytokenRates,agentModeland the credit fields, without the composed children. See Agent Overview for the full endpoint catalog.
Communication Channels
Every Wiro agent is reachable through web chat and the Agent Messaging API without additional configuration. Telegram, Slack, and Discord are optional external channels. They are available to every marketplace template and custom agent, but remain disabled until every registry-declared activation credential is complete. There is no separate enable switch on an existing agent.
Channels are not skills and do not affect pricing. Discover them from the top-level channels[] array returned by public POST /Skills/List:
curl -X POST "https://api.wiro.ai/v1/Skills/List" \
-H "Content-Type: application/json" \
-d '{}'
Each row contains:
| Field | Description |
|---|---|
id | Channel identifier (telegram, slack, or discord). |
credential_key | Key used inside the credentials object. |
required_fields | Fields that must all be populated for automatic activation. |
capabilities | Public UI hints for direct messages, rooms, threads, role allowlists, and command menus. |
credential | Full form descriptor, including credential_schema, labels, validation patterns, and setup help. |
POST /UserAgent/Detail, POST /UserAgent/Update and POST /UserAgent/Deploy return the same channels with this agent's state in communicationChannels: enabled, configured and missingfields.
Use POST /UserAgent/CredentialUpsert for an existing useragent. Send all activation fields in one fields[] request when connecting a channel:
{
"useragentguid": "your-useragent-guid",
"fields": [
{
"credentialkey": "telegram",
"fieldname": "bottoken",
"fieldvalue": "123456:ABC-DEF..."
},
{
"credentialkey": "telegram",
"fieldname": "allowedusers",
"fieldvalue": ["123456789"]
},
{
"credentialkey": "telegram",
"fieldname": "groups",
"fieldvalue": [
{
"chatid": "-1001234567890",
"allowedusers": ["123456789"]
}
]
}
]
}
For a new useragent, include the complete channel group in credentials. The channel activates from those credentials; Deploy accepts neither an enabledchannels toggle nor a chat-mode field. Configure Chat Mode after deployment with teamsessionmode in POST /UserAgent/UpdateSettings.
| Channel | Required fields | Optional scoped access |
|---|---|---|
| Telegram | bottoken, allowedusers[] | groups[] rows with negative chatid and room-specific allowedusers[]. |
| Slack | bottoken, apptoken, workspaceid, allowedusers[] | channels[] rows with immutable channelid and room-specific allowedusers[]. Enable Socket Mode and grant the app token connections:write. |
| Discord | bottoken, allowedusers[] | applicationid; guilds[] rows with guildid, channelids[], and optional allowedusers[] / allowedroles[]. |
teamsessionmode: "private" isolates each approved direct-message operator and each team member's Wiro web-chat history and native agent memory. "collaborative" shares those runtime contexts. Team deployments and transfers default to collaborative; personal deployments and team detachments default to private. Web and external-channel message lists remain separate transports, and room/thread sessions remain scoped to their room.
Send immutable platform IDs only. Display names, usernames, email addresses, and free-form room names are not authorization identifiers. Unlisted users and rooms are rejected, and room messages must mention the bot. To disable a channel, clear at least one of its
required_fieldswithCredentialUpsert. Completing the required fields again reactivates it automatically.
Credential Registry Endpoints
These endpoints are public, so no authentication is required. They return data straight from the credential registry, which is useful when you want to render a "Connect this provider" form without a deployed useragent (e.g. inside an onboarding wizard).
POST /Credentials/List
Lists all credentials in the registry.
| Parameter | Type | Required | Description |
|---|---|---|---|
credential_mode |
string | No | Filter by mode: "oauth", "sa" (service account), "api_key", "multi_api_key", "hybrid" (OAuth plus a direct/API-key mode), "imap_credentials", "jwt_sa", "rule_only". |
wiro_connect_pending |
boolean | No | Filter by the "Wiro mode coming soon" flag: credentials whose Wiro-shared OAuth client is still awaiting provider review (currently facebook-pages, instagram, google-ads, google-merchant-center, youtube, ga4, linkedin, tiktok, and meta-ads). Facebook Pages, Instagram, and Meta Ads remain usable through their ready customer-owned System User and/or OAuth alternatives. |
Response
{
"result": true,
"errors": [],
"total": 22,
"credentials": [
{
"key": "instagram",
"title": "Instagram",
"icon": "/images/icons/skills/instagram.svg",
"brand_color": "#e4405f",
"brand_text_color": "#ffffff",
"brand_logo_filter": "none",
"docs_url": "integration-instagram-skills",
"credential_mode": "hybrid",
"connection_modes": ["api_key", "own", "wiro"],
"default_connection_mode": "api_key",
"mode_badges": {
"api_key": "Recommended",
"own": "Advanced"
},
"wiro_connect_pending": true,
"credential_schema": [
{
"key": "appid",
"type": "text",
"label": "App ID",
"required": true,
"pattern": "^[0-9]+$",
"help": "<ol><li>Go to Meta for Developers → My Apps</li><li>Create App → Other → Business</li><li>Copy the App ID from the dashboard</li><li>Add Product → Facebook Login → Set Up</li><li>Add OAuth Redirect URI: https://api.wiro.ai/v1/UserAgentOAuth/IGCallback</li></ol>",
"oauth_managed": true,
"only_in_modes": ["own"]
},
{
"key": "appsecret",
"type": "password",
"label": "App Secret",
"required": true,
"show_toggle": true,
"help": "<ol><li>Meta for Developers → select your app</li><li>App Settings → Basic</li><li>Click Show next to App Secret and copy</li></ol>",
"oauth_managed": true,
"only_in_modes": ["own"]
},
{
"key": "systemusertoken",
"type": "password",
"label": "System User Token",
"required": true,
"encrypted": true,
"show_toggle": true,
"runtime_excluded": true,
"only_in_modes": ["api_key"]
},
{
"key": "accountId",
"type": "text",
"label": "Instagram Account ID",
"required": true,
"pattern": "^[0-9]+$",
"auto_filled_by_oauth": true,
"readonly_when_connected": true
},
{
"key": "igusername",
"type": "text",
"label": "Connected Account",
"required": false,
"auto_filled_by_oauth": true,
"readonly_when_connected": true
}
],
"oauth_provider": {
"auth_method_value": "wiro",
"connect_endpoint": "/UserAgentOAuth/OAuthConnect",
"disconnect_endpoint": "/UserAgentOAuth/OAuthDisconnect",
"status_endpoint": "/UserAgentOAuth/OAuthStatus",
"connect_button_label": "Connect with Instagram",
"connect_button_icon": "/images/icons/skills/instagram.svg",
"connect_button_brand_color": "#e4405f",
"connect_button_text_color": "#ffffff",
"connect_button_logo_filter": "none",
"username_field": "igusername",
"return_query_param": "ig_connected",
"return_error_param": "ig_error",
"return_error_detail_param": "ig_error_detail",
"direct_probe": {
"mode": "api_key",
"mode_label": "System User Token",
"token_field": "systemusertoken",
"required_fields": ["systemusertoken"],
"public_account_fields": ["id", "name"]
},
"account_picker": {
"enabled": true,
"multi_select": true,
"set_endpoint": "/UserAgentOAuth/SetPickerAccounts",
"item_value_field": "accountId",
"item_label_field": "igusername",
"item_noun": "Account",
"item_noun_plural": "Accounts",
"item_fields_to_save": ["accountId", "igusername"]
},
"extra_step": null
},
"used_by_skills": ["int-instagram-post"]
}
]
}
| Field | Type | Description |
|---|---|---|
key |
string |
Canonical credential key. Use this in CredentialUpsert.fields[].credentialkey. |
title |
string |
Display label shown on connector cards. |
icon |
string |
Path or URL to the brand icon (relative paths absolutized server-side). |
brand_color / brand_text_color / brand_logo_filter |
string|null |
Brand colours and CSS filter for icon rendering, the same shape as on skill registry entries. |
docs_url |
string|null |
Slug of the integration page on this docs site. Frontends prefix with /docs/. |
credential_mode |
string |
One of "oauth", "sa" (service account), "api_key", "multi_api_key", "hybrid" (OAuth plus a direct/API-key mode), "imap_credentials", "jwt_sa", "rule_only". |
connection_modes |
array<string> |
The auth modes the credential supports: for example ["wiro", "own"] for OAuth, ["api_key"] for API-key credentials, ["sa"] for service accounts, or ["api_key", "own", "wiro"] for the Meta hybrids. Drives the auth-method picker in the panel. |
default_connection_mode |
string|null |
The mode the Wiro dashboard selects for a new, disconnected credential ("api_key" System User mode for Facebook Pages, Instagram, and Meta Ads). OAuthConnect does not read it: send authmethod yourself. |
mode_badges |
object |
Optional labels shown beside auth modes, such as { "api_key": "Recommended", "own": "Advanced" }. |
wiro_connect_pending |
boolean |
When true, Wiro's shared OAuth client is awaiting provider review. Currently set on 9 credentials: facebook-pages, instagram, google-ads, google-merchant-center, youtube, ga4, linkedin, tiktok, and meta-ads. Ready alternative modes remain usable; Facebook Pages, Instagram, and Meta Ads expose customer-owned System User and/or OAuth paths. The flag does not strip or hide schema fields. |
credential_schema |
array<field> |
Per-field schema describing the credential form. Each entry is a field object (see below). |
oauth_provider |
object|null |
OAuth wiring (endpoints, button styling, picker config) when credential_mode includes OAuth. null for non-OAuth credentials. See below. |
used_by_skills |
array<string> |
Skill names that consume this credential, useful for "which skills will this connection enable?" hints. |
credential_schema[] field object:
| Sub-field | Type | Description |
|---|---|---|
key |
string |
Field name (the fieldname you send to CredentialUpsert). |
type |
string |
Input type: "text", "password", "select", "boolean", "string-array", "object-array", "fileinput" (public asset, written via CredentialFileUpload multipart), "fileinput-base64" (secret sent inline via CredentialUpsert), or "custom". |
label |
string |
Display label for the form input. |
required |
boolean |
Whether the field must be filled before the agent can use the integration. |
placeholder |
string? |
Placeholder text for the input. |
pattern |
string? |
Regex the value must satisfy. |
maxlength / minlength |
number? |
Length constraints. |
options |
array? |
For type: "select", [{ label, value }] choices. |
default |
string? |
Default value applied when the user hasn't set anything yet. |
help |
string? |
HTML help text rendered under the input. |
show_toggle |
boolean? |
For type: "password", render a "show / hide" toggle. |
oauth_managed |
boolean? |
true for OAuth app keys (clientid / clientsecret, appid / appsecret, …). You supply them in the modes listed in only_in_modes (own; Shopify also api_key); they are stored as oauth_app and left out of Detail responses. |
auto_filled_by_oauth |
boolean? |
true when the provider connection flow writes the value (e.g. igusername from OAuth or direct discovery). |
server_managed |
boolean? |
true when a picker endpoint writes the value (e.g. Meta Ads pagemappings). CredentialUpsert rejects writes to it, as it does for auto_filled_by_oauth fields. |
readonly_when_connected |
boolean? |
true when the field becomes read-only after a successful OAuth connection. |
only_in_modes |
array<string>? |
When set (e.g. ["own"]), the field only appears in the listed authmethod mode. |
runtime_excluded |
boolean? |
true when a setup secret is used only by Wiro's server and must never enter the agent runtime. The Instagram and Facebook Pages System User tokens use this flag. |
platform_managed |
boolean? |
true when Wiro fills the value server-side, so you can't supply it, such as Reddit's three approval flags. These fields are never returned. CredentialUpsert rejects writes to these fields with <Field label> is managed by the platform, and Deploy drops them. |
item_schema / item_type |
object? |
For array-of-object fields: describes the per-entry shape (e.g. apple-appstore.apps[].{appname, appid}). |
oauth_provider object (present when credential_mode includes OAuth):
| Sub-field | Type | Description |
|---|---|---|
auth_method_value |
string |
The provider's default OAuth authmethod value. It is "wiro" only for credentials that offer a Wiro-managed app; customer-owned-only providers use "own". |
connect_endpoint / disconnect_endpoint / status_endpoint |
string |
The OAuth endpoints under /UserAgentOAuth/... that drive the connect / disconnect / status flow for this provider. Today every OAuth credential resolves to the unified /UserAgentOAuth/OAuthConnect, /UserAgentOAuth/OAuthDisconnect, /UserAgentOAuth/OAuthStatus endpoints. The field is kept on the schema for forward-compat with future per-provider overrides. |
connect_button_label / connect_button_icon / connect_button_brand_color / connect_button_text_color / connect_button_logo_filter |
string |
Branding for the "Connect with X" button. |
username_field |
string |
The credential field that holds the connected account name (e.g. "igusername", "channelname"). |
return_query_param / return_error_param / return_error_detail_param |
string |
Names of this provider's result parameters on your redirecturl: return_query_param carries true on success and return_error_param the error code on failure. return_error_detail_param is only a reserved name: Merchant Center is the one credential that sends a detail parameter (mc_error_detail, with mc_error=no_accounts). |
account_picker |
object|null |
When non-null, the connection flow includes an account / page / channel picker after OAuth or direct discovery. Key fields: set_endpoint (always /UserAgentOAuth/SetPickerAccounts), trigger_param (the redirect parameter that carries the list, such as gads_accounts), url_item_fields (maps each accounts[] key to a field of the list items, such as { "customerid": "id" }), multi_select (true when 1+ entries can be picked, false for exactly one), item_value_field / item_label_field (which entry keys identify and label each account in the response), item_noun / item_noun_plural (what one item and several items are called, in Title Case, such as Property / Properties for GA4 or Ad Account / Ad Accounts for Meta Ads; next has its own, such as Page / Pages), item_fields_to_save (the fields each entry in the accounts body carries; only item_value_field is required), and optional next for a chained picker. next.discover_endpoint is /UserAgentOAuth/DiscoverPickerItems; its key, parent/item fields, set_endpoint, and persist_field define the grouped child-selection request and stored result. Meta Ads uses this for ad account → Facebook Pages, and Google Business Profile for account → locations. |
direct_probe |
object|null |
Registry contract for a non-redirect mode: identifies the mode and its token field, validates it server-side, discovers selectable accounts, and declares which public account fields may be returned. |
extra_step |
object|null |
Reserved for providers with a third onboarding step beyond OAuth + picker (currently null for every provider). |
fieldstatus values. Note: this is not part of the registry schema; it's the classification the server stamps onto each stored credential field when it's written. It controls who can see the value:
| Value | Who writes it | Visible to API caller? |
|---|---|---|
user |
API callers + UI users | Yes |
oauth_app |
API callers + UI users (own mode; Shopify also api_key) |
Partly: stripped from Detail responses. In history, secret fields such as clientsecret / appsecret are redacted to [REDACTED]; clientid / appid are not redacted |
oauth_session |
OAuth callback (server-only) | No: always stripped from responses |
oauth_picker |
OAuth callback / Set* picker endpoints |
Yes |
platform |
Wiro internal | No: always stripped from responses |
computed |
Server-derived | Yes |
control |
API callers, UI users and the connection flow (the authmethod switch) |
Yes |
POST /Credentials/Detail
Returns a single credential entry by key.
| Parameter | Type | Required | Description |
|---|---|---|---|
key |
string | Yes | Canonical credential key (e.g. "instagram", "google-ads", "telegram"). |
Response
Returns the same full credential entry as a row from Credentials/List: every field listed in the table above is present. Example for key: "instagram":
{
"result": true,
"errors": [],
"credential": {
"key": "instagram",
"title": "Instagram",
"icon": "/images/icons/skills/instagram.svg",
"brand_color": "#e4405f",
"brand_text_color": "#ffffff",
"brand_logo_filter": "none",
"docs_url": "integration-instagram-skills",
"credential_mode": "hybrid",
"connection_modes": ["api_key", "own", "wiro"],
"default_connection_mode": "api_key",
"mode_badges": {
"api_key": "Recommended",
"own": "Advanced"
},
"wiro_connect_pending": true,
"credential_schema": [
{
"key": "appid",
"type": "text",
"label": "App ID",
"required": true,
"pattern": "^[0-9]+$",
"help": "Meta for Developers → My Apps → Create App → copy App ID.",
"oauth_managed": true,
"only_in_modes": ["own"]
},
{
"key": "appsecret",
"type": "password",
"label": "App Secret",
"required": true,
"show_toggle": true,
"help": "Meta for Developers → App Settings → Basic → Show next to App Secret.",
"oauth_managed": true,
"only_in_modes": ["own"]
},
{
"key": "systemusertoken",
"type": "password",
"label": "System User Token",
"required": true,
"encrypted": true,
"show_toggle": true,
"runtime_excluded": true,
"only_in_modes": ["api_key"]
},
{
"key": "accountId",
"type": "text",
"label": "Instagram Account ID",
"required": true,
"pattern": "^[0-9]+$",
"auto_filled_by_oauth": true,
"readonly_when_connected": true
},
{
"key": "igusername",
"type": "text",
"label": "Connected Account",
"required": false,
"auto_filled_by_oauth": true,
"readonly_when_connected": true
}
],
"oauth_provider": {
"auth_method_value": "wiro",
"connect_endpoint": "/UserAgentOAuth/OAuthConnect",
"disconnect_endpoint": "/UserAgentOAuth/OAuthDisconnect",
"status_endpoint": "/UserAgentOAuth/OAuthStatus",
"connect_button_label": "Connect with Instagram",
"connect_button_icon": "/images/icons/skills/instagram.svg",
"connect_button_brand_color": "#e4405f",
"connect_button_text_color": "#ffffff",
"connect_button_logo_filter": "none",
"username_field": "igusername",
"return_query_param": "ig_connected",
"return_error_param": "ig_error",
"return_error_detail_param": "ig_error_detail",
"direct_probe": {
"mode": "api_key",
"mode_label": "System User Token",
"token_field": "systemusertoken",
"required_fields": ["systemusertoken"],
"public_account_fields": ["id", "name"]
},
"account_picker": {
"enabled": true,
"multi_select": true,
"set_endpoint": "/UserAgentOAuth/SetPickerAccounts",
"item_value_field": "accountId",
"item_label_field": "igusername",
"item_noun": "Account",
"item_noun_plural": "Accounts",
"item_fields_to_save": ["accountId", "igusername"]
},
"extra_step": null
},
"used_by_skills": ["int-instagram-post"]
}
}
Returns { "result": false, "errors": [{ "code": 404, "message": "Credential not found: <key>" }] } if the key is unknown.
Integration Catalog
OAuth Integrations
| Integration | Auth Modes | Setup Guide |
|---|---|---|
| Meta Ads | Own OAuth + System User token; Wiro-owned OAuth deferred until Advanced Access | Meta Ads Skills |
| TikTok Ads | Wiro only (TikTok for Business; authorization lasts 30 days, reconnect to renew) | TikTok Ads Skills |
| Shopify | Expiring offline OAuth + refresh token, or same-org client credentials (expires_in: 86399) |
Shopify Skills |
| Unavailable pending Reddit Data API approval and Wiro's written commercial contract | Reddit Skills | |
| Facebook Page | System User token (recommended) + Own OAuth (advanced); Wiro mode coming soon | Facebook Page Skills |
| System User token (recommended) + Own Instagram OAuth (advanced); Wiro mode coming soon | Instagram Skills | |
| Own only (Wiro mode coming soon) | LinkedIn Skills | |
| Twitter / X | Wiro + Own | Twitter Skills |
| TikTok | Own only (Wiro mode coming soon) | TikTok Skills |
| Google Ads | Own only (Wiro mode coming soon) | Google Ads Skills |
| YouTube | Own only (Wiro mode coming soon) | YouTube Skills (shares Google OAuth client with Google Ads) |
| Google Analytics 4 | Own only (Wiro mode coming soon) | Google Analytics 4 Skills (shares Google OAuth client with Google Ads) |
| Google Search Console | Own only (Wiro mode coming soon) | Google Search Console Skills (shares Google OAuth client with Google Analytics 4) |
| Merchant Center | Own only (Wiro mode coming soon) | Merchant Center Skills (shares Google OAuth client with Google Ads) |
| Google Business Profile | Own only (your Google Cloud project, approved for Business Profile API access) | Google Business Profile Skills |
| HubSpot | Wiro + Own | HubSpot Skills |
| Mailchimp | Wiro + Own + API Key | Mailchimp Skills |
Google OAuth is shared across 5 APIs. Google Ads, YouTube, Google Analytics 4, Merchant Center and Google Search Console can all be authorized through one of your own OAuth clients (one Google Cloud project, one OAuth 2.0 Client ID, multiple API scopes), or you can set up separate ones per product. Wiro's shared client for "wiro" mode is coming soon. Google Business Profile is not part of that shared client: it is own mode only, and the Google Cloud project behind your OAuth client must be approved for Business Profile API access.
Service Account Integrations
| Integration | Setup Guide |
|---|---|
| Google Drive | Google Drive Skills |
| Google Calendar | Google Calendar Skills |
| Google Play | Google Play Skills |
Meta Platforms availability: Meta Ads, Facebook Pages, and Instagram all offer customer-owned Business Manager System User connections now. Meta Ads and Facebook Pages also offer customer-owned Facebook OAuth; Instagram offers customer-owned Instagram Login OAuth. Their Wiro-shared OAuth modes remain pending provider review.
API Key Integrations
| Integration | Setup Guide |
|---|---|
| Serper Web Search | Serper Web Search Skills |
| Gmail | Gmail Skills |
| Telegram | Telegram Skills |
| Firebase | Firebase Skills |
| WordPress | WordPress Skills |
| Shopify (same-organization client ID + secret) | Shopify Skills |
| WooCommerce | WooCommerce Skills |
| Meta Ads (System User token) | Meta Ads Skills |
| Facebook Pages (System User token) | Facebook Page Skills |
| Instagram (System User token) | Instagram Skills |
| App Store Connect | App Store Skills |
| Apollo | Apollo Skills |
| Lemlist | Lemlist Skills |
| Roasit | Roasit Skills |
| DataForSEO | DataForSEO Skills |
| Keepa | Keepa Skills |
| RevenueCat | RevenueCat Skills |
| Adapty | Adapty Skills |
| Brevo | Brevo Skills |
| SendGrid | SendGrid Skills |
| Twilio Voice | Twilio Voice |
| Wiro AI Models | See Using Wiro AI Models from Your Agent |
| Calendarific | See Calendarific in your agent |
Wiro AI Models & Calendarific (User-Provided)
Two integrations are user-input credentials that ship in agent templates but require you (or your end users) to supply the key before the skill runs. They appear in POST /UserAgent/Detail credentials[] and accept writes via POST /UserAgent/CredentialUpsert like any other API-key integration.
Wiro AI Models: wiro credential
The int-wiro-aimodels skill lets an agent call Wiro's own AI models (image / video / audio / LLM generation, cover image creation, model discovery) using one of your Wiro projects. Each generated asset is billed to the wallet of the workspace that owns that project (your personal wallet, or the team wallet for a team project).
- Credential key:
wiro - Field:
apikey(label "Wiro Project"; single field, typecustom:wiro-project-pickerin the registry; the dashboard renders it as a project picker). - No secret to supply. Only the project is needed. Request signing for the agent's internal Wiro calls is handled automatically: Wiro derives the project's signing secret server-side from the key you pick, so there is no
apisecret(or similar) field to paste. - Setup in the dashboard: open the agent's Connectors tab and pick a project, or create one on the Projects page.
- Setup through the API: take the project's
idfromPOST /Project/Listand callPOST /UserAgent/CredentialProjectBind. A request made with a project API key can leaveprojectidout to bind that key's own project:
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialProjectBind" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"projectid": "your-project-id"
}'
The response names the project and says what happened to the agent: { "result": true, "errors": [], "applied": 1, "project": { "id": "4821", "name": "Agent models" }, "restart": "scheduled" }. See CredentialProjectBind for every field and error. If you already hold a project's key, POST /UserAgent/CredentialUpsert with credentialkey wiro and fieldname apikey saves it too.
Don't confuse
credentials.wiro.apikeywith your operator-level Wiro API key.credentials.wiro.apikeyis the project key the agent uses to run Wiro models. Thex-api-keyheader you send to Wiro endpoints from your own backend is your operator key, which authenticates your request (see Authentication). They are the same key only when you bind the project of the key you call with.
Most Wiro-provided agent templates (Social Manager, Blog Content, Push, App Event, Meta Ads, TikTok Ads, Google Ads) ship with int-wiro-aimodels: true enabled. The agent starts without a Wiro project and runs Wiro models once one is connected. Where the template marks this connector required (optional: false), UserAgent/Detail reads setuprequired: true until then.
Calendarific in your agent
The int-calendarific skill discovers global holidays and observances across 230+ countries via the Calendarific API. The free tier (1,000 calls/month) covers most agent use cases.
- Credential key:
calendarific - Field:
apikey(type: "password", encrypted at rest) - Setup:
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "calendarific", "fieldname": "apikey", "fieldvalue": "your_calendarific_api_key" }
]
}'
Templates that scan global holidays (App Event Manager, Push Notification Manager, Meta Ads, TikTok Ads, Google Ads) ship with int-calendarific: true and mark this connector optional (optional: true), so setuprequired doesn't wait for it. The agent starts without a key, and its holiday lookups need one.
Platform-Managed Credentials
Some credential fields are managed by Wiro. You don't provide them, and they are never returned in API responses.
- The chat model your agent runs on is set up by Wiro. Pick the model with
UserAgent/UpdateSettings; there is no key to supply.
CredentialUpsert rejects writes to these fields with <Field label> is managed by the platform, and Deploy drops them from credentials.
Auditing Credential Changes: CredentialFieldHistory
Every credential field write is appended to a versioned history. Use POST /UserAgent/CredentialFieldHistory to read it, the same idea as CustomSkillHistory for skills.
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialFieldHistory" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"credentialkey": "instagram"
}'
Response
{
"result": true,
"errors": [],
"entries": [
{
"guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"useragentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"credentialkey": "instagram",
"fieldname": "igusername",
"fieldvalue": "myaccount",
"fieldstatus": "user",
"parentfield": null,
"ordinal": 0,
"operation": "upsert",
"changedby": "ada-uuid",
"changedby_user": {
"uuid": "ada-uuid",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"username": "ada",
"avatar": "https://cdn.wiro.ai/avatars/ada.webp",
"avatarinitials": "AL"
},
"changedat": 1714694410
},
{
"guid": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"useragentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"credentialkey": "instagram",
"fieldname": "clientsecret",
"fieldvalue": "[REDACTED]",
"fieldstatus": "oauth_app",
"parentfield": null,
"ordinal": 0,
"operation": "upsert",
"changedby": "ada-uuid",
"changedby_user": {
"uuid": "ada-uuid",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"username": "ada",
"avatar": "https://cdn.wiro.ai/avatars/ada.webp",
"avatarinitials": "AL"
},
"changedat": 1714600000
}
]
}
changedby_user is the resolved actor object (uuid, firstname, lastname, email, username, avatar, avatarinitials). It is null when changedby is a system value such as "system" or "backfill-*", or when the user record has been deleted.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Your UserAgent instance guid |
credentialkey |
string | Yes | Provider key (e.g. "instagram", "wordpress") |
startdate |
number | No | UTC epoch seconds: return entries on/after this time |
enddate |
number | No | UTC epoch seconds: return entries on/before this time |
Sensitive values are redacted in history.
oauth_sessionrows (access/refresh tokens) never appear in history at all (they're stripped before persisting).clientsecretis stored as[REDACTED]in history rows; the live secret stays server-side.POST /UserAgent/Detailreturns the current values of the fields you can see, each saved secret as"••••••••";CredentialFieldHistoryonly shows the audit trail.
Setting API Key Credentials
Use POST /UserAgent/CredentialUpsert with a flat fields[] array. Each field row carries {credentialkey, fieldname, fieldvalue}. Each integration page documents the exact field names and shape. The Wiro project an agent runs models with has its own route, POST /UserAgent/CredentialProjectBind, which takes the project's id.
Bulk upsert pattern
/UserAgent/CredentialUpsert takes an array of field rows in one request. Only the fields you send are written; other credential groups and other fields inside the same group are untouched. The Wiro Dashboard follows this pattern exactly: each connector card sends a single CredentialUpsert call with its group's fields.
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "gmail", "fieldname": "account", "fieldvalue": "agent@company.com" },
{ "credentialkey": "gmail", "fieldname": "apppassword", "fieldvalue": "xxxx xxxx xxxx xxxx" }
]
}'
Response: { "result": true, "applied": 2, "errors": [] }. applied is the count of fields saved without an error (a field sent with its current value still counts; a secret sent back as the mask isn't counted, see below). All fields are validated before any is written: if one fails validation (for example a reserved fieldname prefixed with _), the whole request is rejected and nothing is saved; result is false and errors lists every invalid field. If a save fails after validation has passed, the other fields are still saved and each failed field is listed in errors with result: false. A starting or running agent restarts to apply the new values when the call changes a saved value. Saving only fields of a sign-in credential that isn't connected before or after the save, such as own-mode app keys, a System User token or authmethod before the sign-in or token check, restarts nothing: the connection that follows restarts the agent once.
Field-level write rules
fieldstatusis assigned by the server. Anyfieldstatusyou send is ignored: a field that already exists keeps its stored status, and a new field gets the status its registry schema implies. That is why own-mode app keys (clientid/clientsecret,appid/appsecret, …) and theauthmethodswitch can be written here. Fields that the connection flow fills in (schema flagauto_filled_by_oauthorserver_managed, such as account and page selections) are rejected with<Field label> is managed by the connection flowinerrors[]; set them through the OAuth and picker endpoints. OAuth tokens are written by Wiro's OAuth callback flow, not by your API.- Wiro-managed fields and OAuth tokens are rejected. You can't write a field whose status is
platformoroauth_session. Aplatformfield fails with<Field label> is managed by the platformand anoauth_sessionfield with<Field label> is managed by the connection flow; a field with no schema label is named<credentialkey>.<fieldname>instead. As with any invalid field, the whole request is rejected and nothing is saved.platform: fields Wiro manages, such as Reddit's approval flags that Wiro sets after its own review (developerprofileverified,dataapiaccessapproved,commercialwrittenapproval).oauth_session: the token fieldsaccesstoken,refreshtoken,connectedat,tokenexpiresatandrefreshtokenexpiresat, on any credential and in any letter case. They have no schema label, so the message reads, for example,reddit.accesstoken is managed by the connection flow.- These fields are rejected whatever status is stored. For any other field, the rejection check uses the schema's status when the registry schema declares it as a top-level field, even if a different status is stored, and the stored status otherwise; the write is rejected when that status is
platformoroauth_session.
- Reserved fieldnames are rejected. Any
fieldnamestarting with_(e.g._isoptional,_isextra) is a sentinel used by the template itself and cannot be set by API callers. - A secret sent back as the mask keeps its saved value.
UserAgent/Detailshows a saved secret (apasswordorfileinput-base64field) as"••••••••". A row whosefieldvalueis that mask, with or without spaces around it, keeps what is saved: it isn't written, isn't counted inappliedand restarts nothing. So a card sent back as Detail showed it changes only the fields you edited, unless a list in it has two saved entries with the same values (see below). To change a secret, send its new value. In a list sent whole, such asfirebase.accountsoradjust.apps, an entry whose secret is the mask keeps the secret of the saved entry with the same values in its other fields (lists inside the entry don't count). When no single saved entry matches, because you changed one of those values or two saved entries share them, the request is refused with<Key label> in <List label> #<n> stands for a saved value, but this entry matches no single saved one. Enter the <Key label> againand nothing is saved: send that entry's secret itself. The mask with other text beside it is refused too, with<Field label> holds "••••••••", which stands for a saved value. Clear it and enter the full value. - Whitespace around a value is trimmed. Text, password, email, URL and number values, and each entry of a list of strings, are saved without the spaces, tabs or line breaks around them and are validated after trimming, so a client ID pasted with a trailing newline is accepted. Spaces inside a value are kept (an app password with spaces keeps them), and multi-line text, selections, booleans, files and nested rows are saved as sent. The same applies to inline Deploy credentials.
- Standard integration credential groups must be declared by the agent template. Communication-channel credentials are the exception: every useragent may create the channel groups published in
POST /Skills/List→channels[], usingCredentialUpsertor inline Deploy credentials. - Nested arrays (
firebase.accounts[].apps[],google-drive.folders[],apple-appstore.apps[], etc.) are supported via the optionalparentfield(the list field's key, e.g."accounts") andordinal(array index) on each field row. An arrayfieldvalue(with noparentfield) replaces the whole stored list, so send the complete desired list. Per-row writes (a sub-field sent withparentfieldandordinal) change only that entry; indices you don't send are kept. To clear an optional top-level list (e.g.google-drive.folders,apple-appstore.apps), send[]as that field'sfieldvaluewith noparentfield. A nested list such asfirebase.accounts[].apps[]is always sent whole: inside the parentaccountslist, or as that entry'sappsrow (parentfield: "accounts"plus the entry'sordinal);firebase.accountsitself is required and can't be cleared. - Use
POST /UserAgent/Detailto inspect which fields each credential exposes, and the_connected/optional/extraflags that describe its readiness state.
Prepaid deploy: inline setup supported (with limitations)
If you call POST /UserAgent/Deploy with useprepaid: true, you may pass credentials, customskills (or the equivalent key customskills), and skills at the top level of the Deploy body. The server saves them on the new agent in the same call (one-shot deploy + initial setup).
Deploy body credentials rules:
- Values are validated against each credential's public registry schema.
- Registry-declared
string-arrayandobject-arrayfields are accepted as native JSON arrays. This includes channel allowlists (allowedusers, Telegramgroups, Slackchannels, Discordguilds). - Fieldnames starting with
_are reserved and ignored. - Each field's
fieldstatusis assigned by the server, exactly as forCredentialUpsert. - Deploy never saves a
platformoroauth_sessionfield sent incredentials, such as one of Reddit's approval flags oraccesstoken. This applies whethercredentialsis sent as an object or as a JSON string. In a communication-channel group (Telegram, Slack, Discord), such a field fails Deploy before the agent is created. In any other group, the field is dropped and Deploy continues. - A secret sent as the mask,
"••••••••", isn't saved: a new agent has no saved value for it to keep. In a communication-channel group (Telegram, Slack, Discord), the mask is refused with<Field label> holds "••••••••", which stands for a saved value. Clear it and enter the full value, and Deploy fails before the agent is created. In a list, such asfirebase.accounts, an entry whose secret is the mask takes it only from a saved entry with the same values, and a new agent has none, so that list isn't saved.UserAgent/Detailnever returns a saved secret, so to copy one agent's setup to another, send each secret's value. - If
credentialsincludes a communication-channel group, all of that channel'srequired_fieldsmust be present. A missing or invalid activation credential fails Deploy instead of creating a partially configured channel.
Deploy body customskills semantics:
- Each entry must have a
key. Server readsvalue,interval,enabledanddescription;_user_created: truemarks the row as yours, so it can be renamed or deleted later. The key is stored in its full form, asCustomSkillUpsertstores it: a bare slug with anintervalbecomescs-cron-<slug>, one without becomescs-<slug>, andcron-<slug>becomescs-cron-<slug>. - A scheduled task's
intervalis checked as inCustomSkillUpsert, and"manual"means no schedule. A schedule the agent can't run fails Deploy before anything is created or charged, with an error that starts with the skill's key, such ascs-cron-daily-report: This schedule can't run. The hour field takes 0 to 23. A schedule has five fields: minute hour day month weekday, for example 0 9 * * 1-5. - The request body accepts a single top-level
customskillsarray; server-side values are merged onto any existing preset rows for the same key. - Up to 50 entries per Deploy. A longer list is refused before anything is created or charged; add the rest with
CustomSkillUpsertonce the agent is deployed.
If you skip these keys in Deploy entirely, the instance is created empty and you set credentials/skills later with CredentialUpsert, CredentialProjectBind, CustomSkillUpsert, and SkillsApply.
OAuth Authorization Flow
For services that require user authorization, Wiro implements a full OAuth redirect flow. Your end users interact only with your app and the provider's consent screen, which shows your app's name in own mode and Wiro's in Wiro mode. A callback that cannot be matched to your flow, missing_params, or session_expired more than 24 hours after OAuthConnect, ends instead on a plain page of the API's own, https://api.wiro.ai/v1/UserAgentOAuth/SignInNotFinished, which names no brand and links nowhere: it says the sign-in could not be finished and shows the error code.
The
redirecturlyou pass toOAuthConnectis your own URL: any https page you control, orhttp://localhost/http://127.0.0.1for development. After authorization, users are redirected back to your app with status query parameters and, for credentials with an account picker, the list of accounts to show in your own UI (see Callback success & error parameters).
Generic flow
Your App (Frontend) Your Backend Wiro API Provider
| | | |
(1) | "Connect X" click | | |
|--------------------------->| | |
(2) | | POST OAuthConnect -> | |
| | { useragentguid, | |
| | credentialkey, | |
| | redirecturl, | |
| | authmethod } | |
(3) | |<-- { authorizeUrl } | |
(4) |<--- redirect to authorizeUrl -------------------------------------------->|
(5) | | |<-- User clicks Allow |
(6) | | (invisible callback) | |
| | Wiro exchanges code |<---------------------|
| | for tokens, saves | |
(7) |<------- 302 to YOUR redirecturl ---------------------------------------> |
| ?<prefix>_connected=true&... or ?<prefix>_error=<code> |
(8) | User picks accounts | | |
|--------------------------->| | |
(9) | | SetPickerAccounts -> | |
(10) | | OAuthStatus -------> | |
Steps 8 and 9 apply to credentials with an account picker; Meta Ads and Google Business Profile add a second picker step with DiscoverPickerItems. Call the Wiro endpoints (steps 2, 9 and 10) from your backend with your API key, not from the browser.
Each OAuthConnect call starts a sign-in, or a token check in a direct mode, and answers its flowid. The accounts it lists stay on Wiro's server for 15 minutes, for the account that started it: OAuthStatus returns them as candidates until they are saved, so your backend can read them without the redirect. The connection restarts a starting or running agent once, when it is complete: at the account save for a credential with an account picker, at the end of the sign-in or token check otherwise. See Automatic Restart.
Google sign-ins (Google Ads, Google Analytics 4, Google Business Profile, Merchant Center and YouTube) always open Google's account chooser and then its consent screen (prompt=select_account consent), so the person picks the Google account to connect even when the browser is already signed in to one, and Google issues a refresh token each time.
Auth Methods: "wiro" vs "own"
"wiro" |
"own" |
|
|---|---|---|
| OAuth app credentials | Wiro's pre-configured app | Your own app on the provider's developer portal |
| Setup required | None: just call Connect | Create an app on the provider, save its keys with CredentialUpsert, and register Wiro's callback URL |
| Consent screen branding | Shows "Wiro" as the app name | Shows your app name |
| Redirect after auth | To your redirecturl |
To your redirecturl |
| User sees wiro.ai? | No | No |
| Token management | Automatic by Wiro | Automatic by Wiro |
| Best for | Quick setup when available | Custom branding or bypassing review processes |
Own Mode = 2-Step API Flow
Own mode requires two sequential calls before initiating OAuth:
# Step 1: Save your provider app credentials + authmethod via CredentialUpsert
#
# NOTE: `clientid` / `clientsecret` are own-mode app fields. The server stores
# them as fieldstatus="oauth_app" (any fieldstatus you send is ignored) and
# leaves them out of Detail responses. Field names vary by provider, e.g.
# `appid` / `appsecret` or `clientkey`: check `POST /Credentials/Detail` for
# this credential's fields and its `connection_modes`.
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "twitter", "fieldname": "clientid", "fieldvalue": "YOUR_CLIENT_ID" },
{ "credentialkey": "twitter", "fieldname": "clientsecret", "fieldvalue": "YOUR_CLIENT_SECRET" },
{ "credentialkey": "twitter", "fieldname": "authmethod", "fieldvalue": "own" }
]
}'
# Step 2: Initiate OAuth
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "twitter",
"redirecturl": "https://your-app.com/callback",
"authmethod": "own"
}'
For credentials whose connection_modes includes an enabled "wiro" mode, you can skip Step 1 and call Step 2 with authmethod: "wiro". Omitting authmethod uses that credential's registry default. Wiro mode is still pending for Google Ads, Google Analytics 4, Merchant Center, YouTube, TikTok, LinkedIn, Facebook Page, Instagram and Meta Ads, and it is their default, so always send "own" (or "api_key" where offered) for them. Shopify and Reddit default to "own", and Shopify also accepts "api_key" (Client ID + Secret, exchanged server-side with no browser redirect). TikTok Ads accepts only "wiro". Google Business Profile accepts only "own", so always send it.
Callback URL pattern (own mode)
Register this URL in your OAuth app settings on the provider's developer portal:
https://api.wiro.ai/v1/UserAgentOAuth/{Provider}Callback
Provider-specific paths: XCallback, TikTokCallback, IGCallback, FBCallback, LICallback, GAdsCallback, MetaAdsCallback, MCCallback, YTCallback, GA4Callback, GBPCallback, HubSpotCallback, MailchimpCallback, ShopifyCallback, RedditCallback. TikTok Ads uses TikTokAdsCallback, but it is Wiro-managed only, so there is no app of your own to register it in. OAuthStatus returns the exact URL to register for each credential as redirecturi.
Callback success & error parameters
| Provider | Success Params | Error Param |
|---|---|---|
| Twitter / X | x_connected=true&x_username=... |
x_error=... |
| TikTok | tiktok_connected=true&tiktok_username=... |
tiktok_error=... |
ig_connected=true&ig_username=... |
ig_error=... |
|
| Facebook Pages | fb_connected=true&fb_pages=[...] |
fb_error=... |
li_connected=true&li_name=... |
li_error=... |
|
| Google Ads | gads_connected=true&gads_accounts=[...] |
gads_error=... |
| Meta Ads | metaads_connected=true&metaads_accounts=[...] |
metaads_error=... |
| TikTok Ads | tiktokads_connected=true&tiktokads_advertisers=[...] |
tiktokads_error=... |
| Merchant Center | mc_connected=true&mc_accounts=[...] |
mc_error=... (+ mc_error_detail=... with no_accounts) |
| YouTube | yt_connected=true&yt_channels=[...] |
yt_error=... |
| GA4 | ga4_connected=true&ga4_properties=[...] |
ga4_error=... |
| Google Search Console | gsc_connected=true&gsc_sites=[...] |
gsc_error=... |
| Google Business Profile | gbp_connected=true&gbp_accounts=[...] |
gbp_error=... |
| HubSpot | hubspot_connected=true&hubspot_portal=...&hubspot_name=... |
hubspot_error=... |
| Mailchimp | mailchimp_connected=true&mailchimp_account=... |
mailchimp_error=... |
| Shopify | shopify_connected=true&shopify_shop=...&shopify_name=... |
shopify_error=... |
reddit_connected=true&reddit_username=... |
reddit_error=... |
mc_error_detailis the only detail parameter. It comes withmc_error=no_accountswhen Google answered the Merchant Center account list with an error, and holds Google's error status or code, such asPERMISSION_DENIEDor403, never the message.Picker lists:
fb_pages,gads_accounts,metaads_accounts,tiktokads_advertisers,mc_accounts,yt_channels,ga4_propertiesandgbp_accountsare always present on success and hold at least one item. When the provider lists nothing to pick, Wiro saves nothing and the callback sends<prefix>_error=no_accountsinstead (fb_error=no_pagesfor Facebook Pages). For example, the Google user has no Google Ads account, YouTube channel or GA4 property, or the Google Ads developer token is missing or not approved. Picker data from the redirect lists the fields of each item.Empty values are left out: Wiro never sends a parameter with an empty value.
x_username,tiktok_username,ig_username,li_name,hubspot_portal,hubspot_name,mailchimp_account,shopify_shopandshopify_namecome from a profile lookup after the token exchange. When that lookup fails, the parameter is missing but<prefix>_connected=trueis still sent, so read these with a fallback.reddit_usernameis always present on success: if Wiro cannot read the Reddit account, the callback returnsreddit_error=developer_profile_mismatchinstead.List size: some lists hold only the provider's first page: Google Business Profile up to 20 accounts, Merchant Center up to 100 accounts, GA4 the properties of up to 200 accounts, YouTube up to 50 channels, and Facebook Pages through Facebook Login the first page Meta returns (25 Pages by default). Meta Ads and TikTok Ads list up to 500 and send
too_many_ad_accountsoraccount_list_too_largeabove that. Google Ads lists every customer the user can access directly. A list of more than 2,000 accounts on any credential fails withaccount_list_too_large, and nothing is saved. The list travels in the query string, and each item adds about 90 to 110 bytes, so 200 ad accounts make a URL of about 20 KB. Make sure the server behind yourredirecturlaccepts URLs that long; many servers refuse them with their default limits.
Common error codes across providers:
| Code | Meaning |
|---|---|
missing_params |
The callback was opened without an OAuth state. Wiro cannot tell which flow it belongs to, so the browser goes to the API's own neutral page, https://api.wiro.ai/v1/UserAgentOAuth/SignInNotFinished, with this code instead of to your app. Start a new flow with OAuthConnect. |
authorization_denied |
The user cancelled, the provider returned an error or no authorization code, or (Meta Dev Mode) the user is not in App Roles. |
session_expired |
More than 15 minutes passed between OAuthConnect and the callback. The browser returns to your redirecturl with this code; call OAuthConnect again. After 24 hours, or when the state is unknown, it goes to the same neutral page as missing_params instead. A callback that the browser repeats after a completed one (for example when the provider's Continue button is clicked twice) is not an error: it lands where the first one did. |
flow_replaced |
A newer sign-in or token check for the same agent and credential replaced this sign-in, whoever started it. Wiro saves nothing from it, and the newer one still works. |
token_exchange_failed |
The provider returned no usable token for the authorization code, for example because the saved Client/App Secret is wrong. |
useragent_not_found |
The agent was deleted, or is no longer owned by the account that started the flow, before the provider returned. A wrong useragentguid never gets this far: OAuthConnect refuses it with User agent not found or unauthorized. |
<Provider> credentials not configured |
Agent's credentials.<provider> block is empty (typically authmethod: "own" but clientid / clientsecret missing). Returned in errors[] of OAuthConnect itself, not as a redirect-URL *_error code. Fix with POST /UserAgent/CredentialUpsert. |
internal_error |
Unexpected server error. When it happens before the callback has read its flow, the browser goes to the same neutral page as missing_params. |
Provider-specific codes:
| Code | Provider | Meaning |
|---|---|---|
no_accounts |
Google Ads, Meta Ads, TikTok Ads, Merchant Center, YouTube, GA4, Google Business Profile | Sign-in worked, but the provider listed nothing the user can pick, and Wiro saved nothing. For Meta Ads this means no active ad account with both ADVERTISE and ANALYZE tasks; for Google Ads it also covers a missing or refused developer token. Merchant Center may add mc_error_detail. Fix the cause and call OAuthConnect again. |
no_pages |
OAuth succeeded but the user administers no Pages. | |
long_lived_exchange_failed |
Meta Ads | Meta did not return a long-lived token with an expiry. |
required_meta_scopes_missing |
Meta Ads | Meta reported the token as invalid, or without every required permission. |
meta_token_expired |
Meta Ads | The token or its data access has expired. |
meta_app_mismatch |
Meta Ads | The token belongs to a different Meta app than the saved App ID. |
too_many_ad_accounts |
Meta Ads | Meta returned more than 500 ad accounts. |
account_list_too_large |
TikTok Ads, and any credential with an account picker | TikTok returned more than 500 advertisers, or the provider listed more than 2,000 accounts to pick from. Nothing is saved. |
invalid_signature |
Shopify | The callback hmac is missing or does not match the one computed with the app's Client Secret. Nothing is saved. |
invalid_shop |
Shopify | The callback shop is not the shopdomain saved on the agent. Nothing is saved. |
developer_profile_mismatch |
The Reddit account that approved access is not the saved developerprofileusername, or Wiro could not read that account. Nothing is saved. |
Treat any other code like internal_error.
useragent_not_foundappears only in redirect URLs, when the agent went away during the flow. Auseragentguidthat doesn't exist or isn't yours is refused in the JSON response ofOAuthConnect,OAuthStatus,OAuthDisconnect,DiscoverPickerItemsandSetPickerAccountswith"User agent not found or unauthorized".
Generic OAuth Endpoints
All OAuth integrations share five unified endpoints. The provider is selected via a credentialkey body parameter (e.g. "google-ads", "twitter", "facebook-pages"):
| Endpoint | Purpose |
|---|---|
POST /UserAgentOAuth/OAuthConnect |
Start OAuth and return an authorize URL, or run a registry-declared direct credential probe and return discovered accounts. |
POST /UserAgentOAuth/OAuthStatus |
Check whether a provider is connected and which accounts are selected, follow a sign-in or token check under way, and read the accounts it listed. |
POST /UserAgentOAuth/OAuthDisconnect |
Clear stored credentials + tokens. |
POST /UserAgentOAuth/DiscoverPickerItems |
Discover grouped child resources for a registry-declared chained picker after its parent accounts are selected. |
POST /UserAgentOAuth/SetPickerAccounts |
Save the user's account selection after OAuth or direct discovery. |
Each provider's own callback URL (
XCallback,IGCallback,GAdsCallback, etc.) is still per-provider because external OAuth platforms redirect to fixed URLs. Only the five endpoints above are unified.Discover the full list via
POST /Credentials/List. Any entry with a non-nulloauth_providercan use these endpoints; hybrid credentials may offer OAuth and a direct probe. Theoauth_providerblock declares exact endpoint paths, supported direct mode, and picker contract.
POST /UserAgentOAuth/OAuthConnect
For OAuth mode, Wiro generates the provider authorize URL and a state token.
Your frontend redirects the user to authorizeUrl; after consent, the provider
returns to Wiro's registry-declared callback and Wiro redirects the browser to
your redirecturl. For direct modes such as Meta Ads, Facebook Pages, or
Instagram System User tokens and Shopify client credentials, this endpoint
validates or exchanges the already-saved credential server-side and returns
without a browser redirect.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
credentialkey |
string | Yes | Credential key with an oauth_provider block (for example "google-ads", "twitter", "meta-ads", "facebook-pages", "instagram", or "shopify"). |
redirecturl |
string | OAuth only | Your page that the browser returns to after OAuth: any https URL you control, or http://localhost / http://127.0.0.1 in development. Direct probes do not use it. |
authmethod |
string | No | One value from the credential's connection_modes, such as "wiro", "own", or "api_key". Omission uses oauth_provider.auth_method_value. |
Your
redirecturl. Use any https URL you control; plain http works only onlocalhostand127.0.0.1(any port). Wiro adds its parameters to the end of the URL, after?, or after&when the URL already has a query string, and keeps your own parameters. The redirect does not carryuseragentguidorcredentialkey, so put your own context (for example your customer ID) in the query string. Do not use a#fragment, because the parameters would land inside it. Values are URL-encoded, and empty values are left out. Success and every error code return to this URL, except a callback without a knownstateor one more than 24 hours afterOAuthConnect, which ends on the API's own neutral page,https://api.wiro.ai/v1/UserAgentOAuth/SignInNotFinished.Starting an OAuth flow for a credential that holds a System User token (Meta Ads, Facebook Pages, Instagram) or a Mailchimp API key clears that secret, and the connection and account selection made with it, right away, before the user consents. This also happens if the user then cancels, or if the call fails later, for example because your app keys are not saved.
Response
{
"result": true,
"errors": [],
"authorizeUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&scope=...&response_type=code&state=...",
"flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19"
}
flowid names this sign-in: 32 lowercase hex characters. A new sign-in or token check for the same agent and credential replaces it, whoever starts it; an OAuthConnect that Wiro refuses before it starts one, such as one with an invalid redirecturl, leaves it as it is. Follow the sign-in with OAuthStatus, and send the flowid with SetPickerAccounts when you save accounts from its list.
Direct probes return { "result": true, "errors": [], "accounts": [...], "flowid": "...", "account": "...", "restart": "none" } and no authorizeUrl. Meta Ads, Facebook Pages and Instagram return { id, name } entries to pick from; Shopify has no picker, so it returns an empty accounts array and is connected right away. First save the mode's fields together with authmethod: "api_key" through CredentialUpsert, then call OAuthConnect with the same authmethod; without the saved authmethod the probe fails with direct_token_missing. Each direct call that finds the saved fields clears the credential's earlier connection and account selection before it checks them with the provider, so save the selection again afterwards. A failed probe returns result: false, a general message in errors[] and an errorcode that names the cause, such as direct_token_missing, direct_token_invalid, no_accounts, no_pages, provider_rejected_request or provider_timeout; each integration page lists its codes. The check has a flowid like a sign-in, and a failed answer carries it too. account names who the token belongs to when the provider says so, such as a Meta System User's name or the Shopify store's name, and is empty otherwise. restart is "scheduled" when the check restarted the agent, else "none": a check that leaves accounts to pick restarts nothing, and the account save does.
Common errors
| Error message | Cause |
|---|---|
Request parameter [<name>] required |
useragentguid or credentialkey is missing, or redirecturl is missing in an OAuth mode. |
Unknown OAuth credential: <key> |
credentialkey not in registry, or not OAuth-enabled. |
Credential is not configured for the generic OAuth dispatcher: <key> |
This credential does not support OAuth. |
Unsupported connection mode for <Provider> |
authmethod is not in the credential's connection_modes, for example "own" for TikTok Ads or "wiro" for Shopify and Reddit. |
Invalid redirect URL |
redirecturl is not an https URL, or uses http on a host other than localhost / 127.0.0.1. |
<Provider> credentials not configured |
authmethod: "own" but clientid/clientsecret not saved yet. |
Sign-in with the platform's app is not enabled for <Provider> |
authmethod is "wiro", or left out where Wiro mode is the default, but that credential's Wiro mode is still pending (wiro_connect_pending: true). Use another mode from its connection_modes, such as "own". |
<Field> is required / Invalid <Field> |
A saved field the provider's consent page needs is missing or malformed: Shopify's Shop Domain (<shop>.myshopify.com) or Reddit's Developer Profile Username. Save it with CredentialUpsert. |
The platform must verify ... |
Reddit only: one of the three approval flags Wiro sets after its review is not set yet. You can't set them yourself. |
Invalid provider authorization URL |
The provider's consent URL could not be built from the saved fields. |
| Direct credential validation message | The saved direct credential fields failed the registry-declared exchange/probe, or no required account was assigned. Read errorcode for the cause. |
User agent not found or unauthorized |
useragentguid doesn't exist or doesn't belong to the caller. |
Mailchimp's api_key mode needs no OAuthConnect call: save apikey and authmethod: "api_key" with CredentialUpsert. Sending authmethod: "api_key" to OAuthConnect for Mailchimp starts a Wiro-mode OAuth flow.
POST /UserAgentOAuth/OAuthStatus
Returns whether the credential is connected and lists every account/property/page selected via the picker. Use this to render an "Already connected: N accounts selected" UI. It also says how the credential connects, and follows the sign-in or token check under way with the accounts it listed.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
credentialkey |
string | Yes | OAuth credential key. |
flowid |
string | No | The flowid your OAuthConnect returned. It filters nothing: the answer always describes the current sign-in or check, so compare flow.flowid with yours to tell whether a newer one replaced it. |
Response
{
"result": true,
"errors": [],
"connected": true,
"accounts": [
{ "id": "1234567890", "name": "Acme Corp" },
{ "id": "0987654321", "name": "Acme Subsidiary" }
],
"connectedat": "2026-05-25T12:00:00Z",
"tokenexpiresat": "2026-05-25T13:00:00Z",
"authmethod": "own",
"redirecturi": "https://api.wiro.ai/v1/UserAgentOAuth/GAdsCallback",
"appkeyssaved": true,
"tokensaved": false,
"flow": {
"flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19",
"mine": true,
"mode": "own",
"status": "saved",
"account": "",
"errorcode": "",
"errordetail": "",
"restart": "scheduled",
"expiresat": 1779711270
}
}
| Field | Type | Description |
|---|---|---|
connected |
boolean |
true when the active mode has a validated secret, the access token has not passed tokenexpiresat, and, for picker credentials, at least one account is selected. Second-step picks (Meta Ads Pages, Business Profile locations) don't count; pickersteps shows them. Wiro renews tokens while the agent runs, so a stopped agent can read false once its token expires (about an hour after the last renewal for Google, 30 minutes for HubSpot) and reads true again after it starts. If the agent cannot start yet, for example in Setup Required, connect again with OAuthConnect in the same mode; the saved accounts stay selected. _connected in UserAgent/Detail ignores the expiry. Mailchimp's API key mode always reads false here. |
accounts |
array<{id, name}> |
Picker credentials: one entry per selected account, Page or property, [] until something is saved. Credentials without a picker (X, TikTok, LinkedIn, HubSpot, Mailchimp, Reddit, Shopify): one entry while connected is true, with the connected account's display name in both id and name (for example the X username or the Shopify store name), and [] otherwise. |
connectedat |
string |
ISO timestamp of the last successful Connect. Automatic token refreshes do not change it. |
tokenexpiresat |
string |
ISO timestamp when the current access token expires. Empty for providers without a fixed expiry (e.g. Mailchimp). |
authmethod |
string |
The saved connection mode, such as "own" or "api_key". Empty when none is saved. |
redirecturi |
string |
The callback URL to register in your own app for own mode, for this credential, such as https://api.wiro.ai/v1/UserAgentOAuth/GA4Callback. |
appkeyssaved |
boolean |
true when every required own-mode app key is saved on this agent, such as clientid and clientsecret, or appid and appsecret. false for a credential without own mode. |
tokensaved |
boolean |
true when every field of the credential's direct mode is saved, such as a Meta systemusertoken, or Shopify's shopdomain, clientid and clientsecret. false for a credential without a direct mode. |
flow |
object |
The sign-in or token check of this agent and credential, while there is one; see below. Absent when there is none. |
candidates |
array<{id, name}> |
The accounts the current sign-in or token check listed, only for the account that started it and only while flow.status is candidates. Save the ones to use with SetPickerAccounts. |
Meta Ads and Google Business Profile also return their second picker step: pickersteps.pages and pagemappings (Meta Ads), pickersteps.locations and locationmappings (Google Business Profile). optional is true for Meta Ads Pages, which an agent can do without, and false for Business Profile locations. configured is true once at least one item is saved, and groups has one entry per selected account with its saved items:
"pickersteps": {
"pages": {
"pickerkey": "pages",
"optional": true,
"configured": true,
"groups": [
{
"parent": { "adaccountid": "123456789", "adaccountname": "Acme Ads" },
"items": [ { "pageid": "111222333", "pagename": "Acme" } ]
}
]
}
},
"pagemappings": [
{ "adaccountid": "123456789", "adaccountname": "Acme Ads", "pageid": "111222333", "pagename": "Acme" }
]
flow follows one sign-in or token check, which OAuthConnect starts for one agent and credential. A new sign-in or token check for them replaces it, whoever starts it. While a sign-in waits for the pick, connected is still false and the list is in candidates:
{
"result": true,
"errors": [],
"connected": false,
"accounts": [],
"connectedat": "2026-05-25T12:00:00Z",
"tokenexpiresat": "2026-05-25T13:00:00Z",
"authmethod": "own",
"redirecturi": "https://api.wiro.ai/v1/UserAgentOAuth/GA4Callback",
"appkeyssaved": true,
"tokensaved": false,
"flow": {
"flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19",
"mine": true,
"mode": "own",
"status": "candidates",
"account": "",
"errorcode": "",
"errordetail": "",
"restart": "none",
"expiresat": 1779711300
},
"candidates": [
{ "id": "123456789", "name": "Acme Web" },
{ "id": "987654321", "name": "Acme App" }
]
}
| Field | Type | Description |
|---|---|---|
flowid |
string |
32 lowercase hex characters, as OAuthConnect returned it. |
mine |
boolean |
true when the caller started it. For anyone else, flow holds only mine: false, status and expiresat. |
mode |
string |
The authmethod it runs in: wiro, own or api_key. |
status |
string |
waiting: the sign-in started and the provider hasn't sent the person back yet. candidates: the accounts are listed and none is saved yet. connected: finished, with nothing to pick. saved: the accounts were saved, and the list is used up. failed: see errorcode. |
account |
string |
Who signed in, when Wiro knows it: the X or TikTok username, the HubSpot portal, the Instagram username, the Shopify store, a Meta System User's name, or the name of the Facebook user after a Facebook or Meta Ads sign-in in own mode. Empty otherwise, for example after a Google sign-in. |
errorcode |
string |
With status: "failed", the code the redirect carried (see Callback success & error parameters) or the token check's errorcode. Empty otherwise. |
errordetail |
string |
With failed, Merchant Center's mc_error_detail when there is one. Empty otherwise. |
restart |
string |
What the step that ended it did to the agent: scheduled (it restarted the agent) or none. |
expiresat |
number |
Unix seconds when it ends: 15 minutes after OAuthConnect, or 15 minutes after the accounts were listed. After that, flow is absent. |
The list belongs to the Wiro account whose request started the sign-in or check (with an API key, the account the key belongs to). Another person who manages the agent, such as another admin of a team agent, sees that a sign-in is under way, but gets no candidates and can't save from it. OAuthStatus never returns a token, an app secret, the OAuth state or the authorize URL.
Multi-account picker fields are JSON arrays. Picker fields like
customerid(Google Ads),adaccountid(Meta Ads),advertiserid(TikTok Ads),merchantid(Merchant Center),channelid(YouTube),propertyid(GA4),accountid(Google Business Profile),pageid(Facebook Pages), and direct Instagram'saccountIdare stored as JSON arrays whenaccount_picker.multi_select === true. Instagram Login OAuth also stores its single authorized account as a one-entry array.
POST /UserAgentOAuth/DiscoverPickerItems
Discover child resources for a chained picker. Two credentials have a chained flow: in Meta Ads, ad accounts are the parents and eligible Facebook Pages are returned under each account; in Google Business Profile, Business Profile accounts are the parents and their locations are returned under each account. Without parents, Wiro discovers for the root accounts already saved. With parents, it discovers for accounts of the current sign-in's list before they are saved, so one SetPickerAccounts call can save both steps (see Both steps in one call). Wiro reads the active credential server-side; clients never send or receive access tokens.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
credentialkey |
string | Yes | Credential key with account_picker.next configured. Currently "meta-ads" or "google-business". |
pickerkey |
string | Yes | The chained picker key from the registry. Meta Ads uses "pages"; Google Business Profile uses "locations". |
parents |
string[] | No | Root account IDs from the current sign-in's or check's list (candidates), before they are saved: at most 50 Meta ad accounts or 20 Business Profile accounts. Only the account that started the sign-in can send them. |
flowid |
string | No | With parents: the flowid from OAuthConnect. When sent, it must be the current one. |
Example: discover Meta Ads Pages
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/DiscoverPickerItems" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "meta-ads",
"pickerkey": "pages"
}'
Response
{
"result": true,
"errors": [],
"pickerkey": "pages",
"groups": [
{
"parent": {
"adaccountid": "123456789",
"adaccountname": "Acme Ads"
},
"items": [
{ "pageid": "111222333", "pagename": "Acme" }
]
}
]
}
Each group corresponds to one selected parent account. A group may carry
errorcode and an empty items array when discovery failed safely for that
parent. Successful candidates are cached for the registry-declared selection
window (five minutes for Meta Ads and Google Business Profile). Call SetPickerAccounts with pickerkey
and one selections[] entry for every successful parent before that window
expires. A discovery with parents is kept for exactly those accounts and that sign-in: save them as the root accounts in the same call.
A group's errorcode is a short code such as too_many_pages (more than 500 Pages for one ad account), provider_rejected_request, provider_timeout or provider_request_failed. Business Profile returns at most the first 100 locations of each account.
Common errors
| Error message | Cause |
|---|---|
Request parameter [<name>] required |
useragentguid, credentialkey or pickerkey is missing. |
Unknown credential picker |
credentialkey and pickerkey do not name a chained picker. |
User agent not found or unauthorized |
useragentguid doesn't exist or doesn't belong to the caller. |
<Provider> account not connected |
Without parents: no parent account is saved yet, or OAuthStatus would report connected: false, for example because the access token expired while the agent was stopped. For an expired token, start the agent, or connect again with OAuthConnect in the same mode if it cannot start yet: the saved accounts stay selected. With parents: the sign-in's token is no longer saved in its mode, for example because authmethod changed. |
Too many parent accounts selected for picker discovery |
errorcode: "too_many_parents". More than 50 Meta ad accounts or more than 20 Business Profile accounts are selected, or sent in parents. |
parents must be a non-empty array of account ids |
parents was sent empty, or not as an array. |
The sentences of flow_expired, flow_other_person, flow_replaced, flow_failed, flow_waiting and not_listed |
With parents, as for SetPickerAccounts, with the same errorcode: no list is open, another account started it, flowid isn't the current one, the sign-in failed, the sign-in hasn't come back yet, or a parent isn't on the list. |
The account list could not be read. Try again in a moment. |
With parents: a temporary failure. Try again. |
Picker candidate limit exceeded |
Discovery found more than 2,000 items across all groups. |
Picker candidates could not be secured for selection / Picker discovery failed |
Temporary failure. Try again. |
POST /UserAgentOAuth/SetPickerAccounts
Save either the root account selection after an OAuth callback or direct discovery, or a chained child-resource selection after DiscoverPickerItems. Clients never supply access tokens. Wiro saves root accounts only from the list the sign-in or token check gave, and chained picks only from DiscoverPickerItems.
Accounts come from the sign-in's list. Every sign-in and token check keeps the accounts it listed on Wiro's server for 15 minutes (OAuthStatus returns them as candidates), and SetPickerAccounts saves root accounts only from that list, for every picker:
- Who. Only the account that called
OAuthConnect. Another admin of a team agent can't save from someone else's sign-in; they connect again themselves. - Which list. The current one. A newer sign-in or token check for the same agent and credential replaces it. Send its
flowidto save from the sign-in you showed: a different one is refused withflow_replaced. - Which accounts. Only IDs on the list. Wiro saves the name the list gives each account, never a name from the request.
- How often. Once. The first successful save uses the list up (
flow.statusreadssaved). To pick other accounts later, callOAuthConnectagain and save from the new list.
The registry declares each provider's picker shape. Multi-select pickers (Google Ads, Meta Ads, TikTok Ads, Merchant Center, YouTube, GA4, Google Business Profile, Facebook Pages, and direct Instagram) accept one or more entries.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
credentialkey |
string | Yes | Credential key with an account_picker defined. |
accountids |
array | Root picker: this or accounts |
The IDs of the accounts to save, as strings, taken from the list (candidates, or id in the redirect's list). |
accounts |
array | Root picker: this or accountids |
One or more account objects with the per-credential keys (see table below). Wiro reads only the ID key of each; the name comes from the list. |
flowid |
string | No | The flowid from OAuthConnect. When sent, it must be the current sign-in's or check's, or the save is refused with flow_replaced. |
pickerkey |
string | Chained picker | Chained picker key returned by DiscoverPickerItems. Sent with accountids or accounts, the second step is saved together with the root accounts; see Both steps in one call. |
selections |
array | Chained picker only | One { parentvalue, items } entry for every parent that DiscoverPickerItems returned without errorcode. Send each item exactly as discovered, ID and name (for example { pageid, pagename }); an item whose name differs is rejected. Leave out parents that came back with errorcode; they keep the items saved before. An empty items array selects nothing for that parent: no Pages for a Meta Ads ad account, no locations for a Google Business Profile account. Each entry can name its items by ID in itemids instead of items, for example { "parentvalue": "123456789", "itemids": ["111222333"] }. A successful save uses up the discovery result, so call DiscoverPickerItems again before the next change. |
Picker data from the redirect
Each list parameter is a URL-encoded JSON array. Your query parser has already decoded it, so parse the value once with JSON.parse; decoding it a second time breaks names that contain %. IDs arrive without provider prefixes such as customers/, act_ or properties/. Send each chosen item's id in accountids, or copy the item into the accounts[] keys of SetPickerAccounts:
| Credential | List | Item fields | accounts[] entry |
|---|---|---|---|
google-ads |
gads_accounts |
id, name, status |
{ customerid: id, customerdescriptivename: name } |
meta-ads |
metaads_accounts |
id, name |
{ adaccountid: id, adaccountname: name } |
tiktok-ads |
tiktokads_advertisers |
id, name |
{ advertiserid: id, advertisername: name } |
google-merchant-center |
mc_accounts |
id, name, websiteUrl |
{ merchantid: id, accountname: name } |
youtube |
yt_channels |
id, title, customUrl, subscriberCount |
{ channelid: id, channeltitle: title } |
ga4 |
ga4_properties |
id, displayName, account, propertyType |
{ propertyid: id, propertydisplayname: displayName } |
google-business |
gbp_accounts |
id, name |
{ accountid: id, accountname: name } |
facebook-pages |
fb_pages |
id, name |
{ pageid: id, fbpagename: name } |
Merchant Center's name can be empty and its websiteUrl is always empty, so label those accounts with their ID when needed. In candidates, such an account's name is its ID. Each integration page describes the other fields. In System User mode there is no redirect: OAuthConnect returns { id, name } items in accounts for Meta Ads ({ adaccountid: id, adaccountname: name }), Facebook Pages ({ pageid: id, fbpagename: name }) and Instagram ({ accountId: id, igusername: name }). Instagram Login in own mode has no list: Wiro saves the authorized account itself. POST /Credentials/Detail carries the same mapping: oauth_provider.account_picker.trigger_param names the list parameter, and url_item_fields maps each accounts[] key to an item field.
Per-credential accounts[] shape
| Credential | Keys per entry | Notes |
|---|---|---|
google-ads |
customerid, customerdescriptivename |
customerid is 10 digits; dashes/letters stripped server-side. |
meta-ads |
adaccountid, adaccountname |
act_ prefix stripped server-side. |
tiktok-ads |
advertiserid, advertisername |
Numeric advertiser ID; non-digits stripped server-side. Each call replaces the previous selection. |
google-merchant-center |
merchantid, accountname |
|
youtube |
channelid, channeltitle |
|
ga4 |
propertyid, propertydisplayname |
|
google-business |
accountid, accountname |
Numeric account ID; non-digits stripped server-side. Locations are chosen afterwards with the chained "locations" picker. |
facebook-pages |
pageid, fbpagename |
One or more Pages from the latest OAuth or System User discovery result. |
instagram |
accountId, igusername |
One or more accounts from direct System User discovery. Customer-owned Instagram OAuth does not use this picker and writes one authorized account directly. |
The first key is required in every entry, and the same ID twice is refused. Wiro takes each account's name from the list, so the name key can be left out, and a name you send is not read.
Example: Google Ads multi-select
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/SetPickerAccounts" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "google-ads",
"flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19",
"accountids": ["1234567890", "0987654321"]
}'
The accounts objects work too, for example "accounts": [{ "customerid": "1234567890" }, { "customerid": "0987654321" }].
Response
{
"result": true,
"errors": [],
"accounts": [
{ "id": "1234567890", "name": "Acme Corp" },
{ "id": "0987654321", "name": "Acme Subsidiary" }
],
"restart": "scheduled"
}
accounts are the saved accounts, with the names from the list. restart is "scheduled" when the save restarted the agent, else "none". The save that completes a connection restarts a starting or running agent once, and a save that changes nothing, such as the same accounts again, restarts nothing. See Automatic Restart.
Example: save Meta Ads Page mappings
Call this after DiscoverPickerItems and include every successful parent once:
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/SetPickerAccounts" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "meta-ads",
"pickerkey": "pages",
"selections": [
{
"parentvalue": "123456789",
"items": [
{ "pageid": "111222333", "pagename": "Acme" }
]
}
]
}'
The response includes pickerkey: "pages", the persisted, flat
pagemappings[] list and restart. Sending an empty items array skips Pages for that ad
account; Meta Ads reporting and other non-Page operations remain available.
Google Business Profile uses the same chained shape with pickerkey: "locations",
{ locationid, locationtitle } items, and a locationmappings[] list in the
response (see Google Business Profile → Connect through the API).
Saving the root accounts again, from a new sign-in's list, replaces the selection. Pages or locations already chosen for accounts that stay selected are kept, those of removed accounts are dropped, and an open DiscoverPickerItems result is discarded, so discover again before saving the second step.
Both steps in one call
Saving the accounts, then the Pages or locations, in two calls can restart a running agent twice. To save both in one call, so it restarts once:
- Call
DiscoverPickerItemswithparents, the chosen root IDs from the sign-in's list, and itsflowid. - Call
SetPickerAccountswith the same IDs inaccountids, theflowid,pickerkey, andselectionsfor every parent that discovery returned withouterrorcode.
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/SetPickerAccounts" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "meta-ads",
"flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19",
"accountids": ["123456789", "234567890"],
"pickerkey": "pages",
"selections": [
{ "parentvalue": "123456789", "itemids": ["111222333"] },
{ "parentvalue": "234567890", "itemids": [] }
]
}'
Response:
{
"result": true,
"errors": [],
"accounts": [
{ "id": "123456789", "name": "Acme Ads" },
{ "id": "234567890", "name": "Acme Retail" }
],
"pickerkey": "pages",
"pagemappings": [
{ "adaccountid": "123456789", "adaccountname": "Acme Ads", "pageid": "111222333", "pagename": "Acme" }
],
"restart": "scheduled"
}
Wiro writes the accounts and the mappings in one save. The discovery must be the one made with parents equal to accountids, for this sign-in, in the last five minutes; otherwise nothing is saved and the call answers next_expired, The list of pages expired. Load it again. (locations for Business Profile): call DiscoverPickerItems with parents again. Business Profile needs at least one location across the accounts; with none, the call answers next_required, Choose at least one location to finish. Meta Ads Pages stay optional. Later changes to the Pages or locations of saved accounts use the second step alone, as above.
Common errors
A refusal of the list rules also answers errorcode, as named below. The wording of its message depends on whether the list came from a sign-in or a token check. With no list, the mode saved in authmethod decides, and with none saved, the credential's default mode: a token check for Facebook Pages, Instagram and Meta Ads, a sign-in for the others. The table shows a sign-in's; a token check's reads, for example, The token check expired. Check the token again to choose the accounts.
| Error message | Cause |
|---|---|
The sign-in expired. Sign in again to choose the accounts. |
errorcode: "flow_expired". No list is open for this agent and credential: no sign-in or check was started, it was more than 15 minutes ago, a save already used its list, or the credential was disconnected. Call OAuthConnect again. |
Another admin started this sign-in. Sign in again to choose the accounts yourself. |
errorcode: "flow_other_person". Another account started the current sign-in or check. |
A newer sign-in replaced this one. Sign in again. |
errorcode: "flow_replaced". The flowid you sent isn't the current one. |
The sign-in did not finish. Sign in again. |
errorcode: "flow_failed". The current sign-in or check failed; flow.errorcode in OAuthStatus says why. |
The sign-in is not finished yet. Finish it, then choose the accounts. |
errorcode: "flow_waiting". The current sign-in hasn't come back from the provider yet, so it has no list. Finish it, then save. A new OAuthConnect would replace it. Only a sign-in waits, so this message has no token check wording. |
Choose accounts from the list the sign-in returned. |
errorcode: "not_listed". An ID isn't on the list. |
The account list could not be read. Try again in a moment. |
A temporary failure. Try again. |
accountids must be a non-empty array / Each account id must be text |
accountids is empty, or holds something other than strings and numbers. |
accounts must be a non-empty array |
Neither accountids nor a non-empty accounts was sent. |
Each account selection must be an object |
An accounts[] entry is not an object. |
Each account selection must include <field> |
An entry has no ID in the credential's ID field, such as customerid. |
Duplicate account selection: <id> |
Two entries have the same ID after cleanup (for example 123-456-7890 and 1234567890). |
Single-select picker requires exactly one account; got <N> |
Single-select credential received multiple entries. |
<Provider> account not connected |
A root save whose list is open but whose sign-in left no token in its mode, for example because authmethod was changed after the sign-in. A chained step alone returns it when no parent account is saved or the access token has expired. For an expired token, start the agent, or connect again with OAuthConnect in the same mode if it cannot start yet, then call DiscoverPickerItems again. |
No pending <Provider> connection. Please reconnect via OAuthConnect. |
Facebook Pages or System User Instagram: the list is open, but the Page tokens found with it are no longer on the server. Call OAuthConnect again. |
Selected <field> not found in pending list: <value> |
Facebook Pages or System User Instagram: an account on the list has no Page token. Call OAuthConnect again. |
Credential does not support account picker: <key> |
credentialkey doesn't have an account_picker (e.g. Twitter / TikTok / HubSpot). |
selections must be an array |
pickerkey was sent without a selections array. |
Unknown credential picker |
pickerkey is not this credential's chained picker. |
Each selection must contain parentvalue and items |
A selections[] entry is not { parentvalue, items: [...] }. |
Selected parent is not available |
parentvalue is not a selected account, appears twice, or came back from discovery with errorcode. |
Selected picker item is invalid / Selected picker item is not available |
An item is not an object, was not discovered for that parent, has a different name, or appears twice. |
Picker candidates expired. Discover them again. |
Chained picker candidates expired or the parent connection changed. Call DiscoverPickerItems again. |
The list of <items> expired. Load it again. |
errorcode: "next_expired". Both steps in one call, but the second step's discovery wasn't made with parents for these accounts and this sign-in, or more than five minutes ago. Call DiscoverPickerItems with parents again. |
Choose at least one <item> to finish. |
errorcode: "next_required". Both steps in one call for Google Business Profile with no location chosen. |
selections must include every available parent exactly once |
Chained picker request omitted or duplicated a successfully discovered parent. |
Selected parent is no longer available |
The root selection changed while saving. Call DiscoverPickerItems again. |
POST /UserAgentOAuth/OAuthDisconnect
Clears the credential's connection: tokens, authmethod, picker selections,
auto-filled values and the credential's other saved fields, such as LinkedIn's
organizationid, Shopify's shopdomain and Reddit's developerprofileusername;
save them again before you reconnect. Reddit's approval flags are cleared too,
so a Reddit reconnect waits until Wiro sets them again. Customer-owned OAuth app
keys (clientid, clientsecret, appid, appsecret, TikTok's clientkey,
Google Ads' developertoken) are kept for reconnection, also in Shopify's
Client ID + Secret mode. An alternative API-key field is kept while
disconnecting OAuth, but disconnecting that direct mode itself clears its
secret, such as Meta systemusertoken or Mailchimp apikey. Because
authmethod is cleared, send it again with the next OAuthConnect (and save it
again for a direct mode). A starting or running agent restarts when the disconnect removes a token, such as the ones a sign-in saved or a System User token, or when the connection was complete. A disconnect that removes no token from a credential that wasn't connected, such as one with only its own app keys saved, restarts nothing.
For providers that publish a token-revocation endpoint (currently X, TikTok, TikTok Ads and Reddit), Wiro also calls the provider's revoke endpoint for OAuth connections as a non-critical best-effort step. Other providers only clear local credentials; the token remains valid on the provider side until it expires.
A disconnect also ends a sign-in or token check under way for the credential: its account list is dropped, so SetPickerAccounts can't save from it.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
credentialkey |
string | Yes | OAuth credential key. |
Response
{
"result": true,
"errors": []
}
Token lifecycle
Wiro maintains renewable provider connections automatically while the agent is running. Direct Meta System User connections have no generic refresh contract: regenerate and reconnect an expiring or invalidated token. There is no customer-facing token-refresh endpoint or manual refresh action.
Use POST /UserAgentOAuth/OAuthStatus to monitor the connection. Wiro renews tokens only while the agent runs and when it starts, so a stopped agent reports connected: false once its last access token has expired, although the authorization is still valid (for example about an hour after the last renewal for Google, 30 minutes for HubSpot). Start the agent and check again. DiscoverPickerItems and the second-step SetPickerAccounts need a current token too. If the agent cannot start yet, for example while it is still in Setup Required, connect again with OAuthConnect in the same mode instead. Wiro stores the fresh token and keeps the saved accounts selected; run DiscoverPickerItems again before the second-step save. If connected stays false while the agent runs, or the provider revokes a connection that cannot be renewed, reconnect through POST /UserAgentOAuth/OAuthConnect. Provider-specific exceptions are documented in each integration guide.
Web UI Behaviors (Wiro Dashboard)
The Wiro Dashboard uses the same API. To match its behavior in your own integration:
- Per-group save: Save each credential group with its own
POST /UserAgent/CredentialUpsertcall that sends only that group'sfields[]. - Own mode in two steps: In own mode, first save
appid/appsecretandauthmethod: "own"withCredentialUpsert, then callPOST /UserAgentOAuth/OAuthConnectwithauthmethod: "own". - Recommended Meta direct mode: Facebook Pages, Instagram, and Meta Ads default to a System User token. Save
authmethod: "api_key"andsystemusertokenwithCredentialUpsert, callOAuthConnect, then finish the account selection withSetPickerAccounts. - Same-tab redirect: Open
authorizeUrlin the same tab, not in a popup, to avoid third-party cookie issues. - No manual token refresh: Wiro maintains supported connections automatically; reconnect with
OAuthConnectwhen authorization is required. - AI Setup Guide: On a connector that isn't set up yet, the Dashboard shows a Copy the AI Setup Guide link under the form. It opens a ready-to-paste prompt for AI assistants that goes through every connector field the agent needs. Useful for API users building their own configuration UIs. See the per-integration help texts for equivalent guidance.
- Registry-backed validation: Wiro validates declared types, patterns, lengths, URLs, enum values, and provider response contracts before persisting or connecting credentials. The provider remains authoritative for permissions and asset access.
- Platform-managed credentials are hidden: groups whose fields are all managed by Wiro are omitted from
POST /UserAgent/Detailresponses. They're set up by Wiro and can't be set by customers.
Setup Required State
Every fresh Deploy starts in Setup Required state (status: 6). While an agent is at status: 6, Start refuses it with Agent setup is not complete. Please finish setting up your connectors before starting.
API deploys must always pass useprepaid: true. The server provisions the prepaid subscription inline and moves the agent to status: 2 (Queued) whatever its connectors hold, and Wiro then starts it, so no Start call is needed. A connector the agent requires may still be incomplete while it runs: UserAgent/Detail reads setuprequired: true until every required connector is set up, and a running agent restarts to pick up each connector you save.
Saving a connector doesn't move the agent out of status: 6, whether with CredentialUpsert, CredentialProjectBind or an OAuth connection. After the last one, call POST /UserAgent/Update once with { "guid": "<useragent-guid>" }: that call moves the agent to status: 0 (Stopped) once every required connector is set up, so Start can launch it. Start doesn't read setuprequired on a stopped (status: 0) or errored (status: 5) agent.
setuprequired in UserAgent/Detail is true while the agent is at status: 6 or any non-optional credential is still incomplete; on UserAgent/MyAgents rows it follows status: 6 alone. The server treats a credential as complete when either:
- OAuth and hybrid connection credentials:
_connected: true(the active mode has a validated runtime token and every required picker field is populated), or - API-key credentials: at least one field saved on this agent with
fieldstatus: "user"has a non-empty value (any one user-writable field filled in makes the credential count as "entered"; there is no deeper per-field validation). A value the agent template holds doesn't count here, though it counts toward the card's_filledand_required_missing.
The two branches are checked together: setuprequired stays true until every required credential passes one of them.
Security
- OAuth access and refresh tokens are stored server-side and are never returned by the customer-facing credential endpoints. A token you save yourself, such as a System User token or a bot token, isn't returned either:
UserAgent/Detailshows it as"••••••••", as it shows every saved secret (see Credential object shape). A saved Google service account file reads as the mask too, and only its account's email is named beside it, as_service_account_email, for the agent's owner and team admins. oauth_sessionfields are always stripped from Detail,MyAgents, andCredentialUpsertresponses:accesstoken,refreshtoken,pageAccessTokenand any similar token rows never leave the server.OAuthStatusreturns only theconnectedatandtokenexpiresattimestamps, never a token.platformfields are always stripped from responses. In practice this affects Reddit's three approval flags and every other Wiro-managed field.credentials.wiro.apikeyandcredentials.calendarific.apikeyare user-supplied and appear in the response:wiro.apikeyas saved, andcalendarific.apikeyas the mask once saved.oauth_appfields (clientid/clientsecret,appid/appsecret) are stripped from Detail responses, even after an OAuth "own mode" setup writes them. The append-only credential history redactsclientsecretto[REDACTED]and always redactsoauth_sessionrows.fieldstatusis server-assigned. Afieldstatussent toCredentialUpsertis ignored; the server assigns the status itself.- Fields that the connection flow fills in, OAuth tokens included, are rejected with
<Field label> is managed by the connection flowinerrors[]. A token field has no schema label, so it is named<credentialkey>.<fieldname>. - Wiro-managed (
platform) fields are rejected with<Field label> is managed by the platform. - A request that fails validation saves nothing, and Deploy never saves either kind of field from its
credentialsbody.
- Fields that the connection flow fills in, OAuth tokens included, are rejected with
- The
redirecturlreceives only connection status parameters: no tokens, no secrets. - OAuth state parameters use a 15-minute TTL cache to prevent replay attacks.
- Redirect URLs must be https, on any host you control (or http on localhost/127.0.0.1 for development).
- Every sign-in and token check keeps the accounts it listed on the server for 15 minutes, as
{id, name}pairs, and gives them only to the account that started it. The Page access tokens found during Facebook Page and Instagram discovery never leave the server.
For Third-Party Developers
If you're building a product on top of Wiro agents and need your customers to connect their own accounts:
- Deploy an agent instance per customer via
POST /UserAgent/Deploy. - Connect: for
ownor a direct mode, first save that mode's fields andauthmethodwithPOST /UserAgent/CredentialUpsert(Wiro mode needs no app keys). Then callPOST /UserAgentOAuth/OAuthConnectwith the sameauthmethod. For OAuth, pass aredirecturlon your own site: any https page you control, orhttp://localhost/http://127.0.0.1while you develop. - OAuth branch: when
authorizeUrlis returned, send the customer's browser there. Wiro brings it back to yourredirecturlwith<prefix>_connected=trueand, for picker credentials, the account list, or with<prefix>_error=<code>. Your backend can also follow the sign-in withOAuthStatusand read the list there, ascandidates. - Direct branch: when
accountsis returned, there is no redirect; the list is in the response. - Pick: show the list in your own UI and save the choice with
POST /UserAgentOAuth/SetPickerAccounts(see Account picker in your own UI). - Verify: call
POST /UserAgentOAuth/OAuthStatusand checkconnected,accountsand, for a second picker step,pickersteps.
<prefix>_connected=true means the provider authorized Wiro. A picker credential is ready only after SetPickerAccounts saves at least one account; until then OAuthStatus reports connected: false, and Facebook Pages stores nothing at all before that call. Two cases differ: when the Google user has exactly one YouTube channel, Wiro saves that channel during the callback, and a reconnect in the same mode keeps the earlier selection until you save a new one, so OAuthStatus may already show the old accounts.
The Google Ads, Meta Ads, TikTok Ads, Facebook, Instagram, Google Business Profile, X, TikTok, LinkedIn, HubSpot and Mailchimp pages include a Multi-Tenant Architecture section with notes for running one agent per customer, such as token isolation, consent screen branding and provider rate limits.
When the agent proposes a connection in a chat, connect it with these same calls, then record it on its setup card with SetupCardApply: see Agent Chat Integration.
Account picker in your own UI
Google Ads, Meta Ads, TikTok Ads, Merchant Center, YouTube, GA4, Google Business Profile, Facebook Pages and System User Instagram ask the customer to pick accounts. You build that picker in your own app:
- Read the list. On success the redirect carries it in one parameter:
gads_accounts,metaads_accounts,tiktokads_advertisers,mc_accounts,yt_channels,ga4_properties,gbp_accountsorfb_pages(see Callback success & error parameters). It is a JSON array that your query parser has already decoded, so parse it once withJSON.parse. In System User mode the list is in theOAuthConnectresponse instead. Either way,OAuthStatusreturns it ascandidatesfor 15 minutes, to the account that started the sign-in. - Show it. Every item has an
idand a name; Picker data from the redirect lists each credential's item fields and the keys to save them under. - Save the choice. Send the chosen IDs in
accountids, or the items inaccounts[], toSetPickerAccountsfrom the same Wiro account and within 15 minutes. Every picker accepts several items, and each list can be saved once. - Second step. For Meta Ads Pages (optional) and Business Profile
locations, call
DiscoverPickerItems, show the groups, and save the choice withSetPickerAccounts,pickerkeyandselections[]within five minutes. To save both steps in one call, discover withparentsbefore the first save (see Both steps in one call). - Nothing to pick. When the provider lists nothing, the redirect carries
<prefix>_error=no_accounts(fb_error=no_pagesfor Facebook Pages) and Wiro saves nothing. Show the reason and let the customer connect again.
Wiro sends the list in that redirect or response, and OAuthStatus returns it as candidates for 15 minutes. After that, OAuthStatus shows only the saved selection. To offer changes later, run OAuthConnect again and save from the new list: a list that was saved once, or is older than 15 minutes, can't be saved from.
Handling the OAuth redirect in your app
app.get('/settings/integrations', (req, res) => {
// req.query values are already URL-decoded: parse each list once, without decodeURIComponent.
if (req.query.x_connected === 'true') {
return res.redirect(`/dashboard?connected=twitter&username=${encodeURIComponent(req.query.x_username || '')}`)
}
if (req.query.metaads_connected === 'true') {
const accounts = JSON.parse(req.query.metaads_accounts || '[]') // [{ id, name }]
return res.redirect(`/dashboard/meta-ads?accounts=${encodeURIComponent(JSON.stringify(accounts))}`)
}
if (req.query.fb_connected === 'true') {
const pages = JSON.parse(req.query.fb_pages || '[]') // [{ id, name }]
// Facebook always requires SetPickerAccounts to finalize, within 15 minutes
return res.redirect(`/dashboard/facebook?pick=${encodeURIComponent(JSON.stringify(pages))}`)
}
if (req.query.gads_connected === 'true') {
const customers = JSON.parse(req.query.gads_accounts || '[]') // [{ id, name, status }]
return res.redirect(`/dashboard/google-ads?pick=${encodeURIComponent(JSON.stringify(customers))}`)
}
// For example gads_error=no_accounts: the Google user has no Google Ads account to pick
const errKey = Object.keys(req.query).find((k) => k.endsWith('_error'))
if (errKey) {
return res.redirect(`/dashboard?error=${errKey}&reason=${encodeURIComponent(req.query[errKey])}`)
}
res.redirect('/dashboard')
})
// After the customer picks, save the choice from your backend within 15 minutes of the sign-in:
async function saveGoogleAdsPick(useragentguid, picked) {
const res = await fetch('https://api.wiro.ai/v1/UserAgentOAuth/SetPickerAccounts', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'x-api-key': process.env.WIRO_API_KEY },
body: JSON.stringify({
useragentguid,
credentialkey: 'google-ads',
accountids: picked.map((c) => c.id),
}),
})
return res.json() // { result, errors, accounts: [{ id, name }], restart }
}
Agent Chat Integration
Build your own chat for a Wiro agent, setup from chat included: every call, every answer field, and what your interface shows at each step.
Overview
This guide is for products that put a Wiro agent behind their own interface. Your users talk to the agent in your app. Your backend calls the API with your project API key, and your app shows the agent's answers, its setup cards and the connect steps with your own design. Your users never leave your product.
It covers the whole cycle in order: sending messages and showing answers, the setup cards the agent proposes, applying them, connecting each kind of connector, restarts, errors, chats without cards, the agent's live Screen and Take Control in your app, security, five worked examples and a checklist. Every request and answer is shown as JSON, so the guide can also be handed to a coding assistant that builds the integration for you.
What setup from chat is
An agent can help the people who manage it set it up in the chat. Asked to post on Facebook, report website traffic every Monday or search the web, it can propose the change itself: turn on a connector or skill, connect a connector, create or change a scheduled task or a custom skill, or change its time zone.
The agent never changes its own setup and never sees a key. It proposes the change as a setup card. Wiro checks the card against the agent's current setup and stores it on the message that asked for it, where it shows as a setup block in that message's timeline[]. Nothing changes until an agent admin applies the card. Wiro then applies the stored card, checked again against the agent as it is at that moment, and never anything written in the chat.
Your product shows everything
Wiro's answers in a chat sent with a project API key name no site, page or link. When something still has to be connected, the answer says so in a plain sentence and returns the same information as data, the next array, so your product shows its own Connect button. Keys, app keys and tokens go into your own forms and reach Wiro through the API, never through the chat. The provider's consent screen, when a connector uses one, shows your app's name when you connect it with your own app keys, and the browser comes back to a page on your own site.
A few fields are for your backend, not for your users: every message row and every card names your API key's owner as the person who sent, asked or applied (see API key), and the tokens and ids are your own references. Show your users your own names and words.
Connector titles name their vendors, such as Google Analytics 4 or WordPress. The connector the agent runs AI models with, key wiro, is titled Wiro AI Models, and so is its skill int-wiro-aimodels in Skills/List. That title comes wherever the API names it: in needs and next[].title, in the card listing and in summary, for every change that brings it, such as adding Video Creator or a voice channel. An agent that runs models through it can also write its public links in an answer, such as a model's page on wiro.ai or an output file on cdn1.wiro.ai. Your product may show its own label for the connector key wiro, as for any title the API gives.
A connector that signs in with Wiro's own app (mode signin, such as X, HubSpot, Mailchimp and TikTok Ads) shows that app's name on the provider's consent screen, so a product that wants its own name there connects with its own app keys, where the connector offers them (own in its connection_modes, see Modes). Every sign-in passes through its redirect URI on the API host (redirecturi in OAuthStatus), as registered with the provider, before the browser comes back to your redirecturl.
The flow at a glance
Your user types Your backend Wiro
-------------- ------------ ----
"Report our traffic" -> Message/Send ------------------> agent turn runs
WebSocket or Message/Detail <--- timeline: answer + setup blocks
Your app shows the card
User presses Connect -> CredentialUpsert / OAuthConnect -> sign-in, token check or key
OAuthStatus / SetPickerAccounts
User presses Apply -> Message/SetupCardApply --------> change applied, agent restarts
Your app shows "Restarting", then the agent answers again
Before You Start
API key
Every call in this guide is authenticated with a project API key from your Wiro dashboard, sent as the x-api-key header (signature-based projects also send x-nonce and x-signature). See Authentication. Call Wiro from your backend only: never put the key in browser or mobile app code.
Your app may hold two kinds of token, so that the browser follows a chat on the Agent WebSocket itself: a turn's agenttoken and a session's sessiontoken. The socket takes no API key, and each token reads only its own turn or session, so give a person only the tokens of their own chats. Or keep the socket on your backend and relay its events. To show the agent's live Screen, the page also gets a one-time screenToken for each screen it opens (see Screen and Take Control in Your App).
A call made with your API key acts as the key's owner: the person who created the project. Messages you send are stored as that person's messages, and setup cards are applied with that person's rights. So every row your users write carries the owner's account: uuid and the user object (first and last name, email, username, avatar) of each message row, and requestedby and actedby of each card. Never show them as the sender. Keep your own record of who wrote what, for example by sessionkey and messageguid, and show your own names.
Deploy an agent
Deploy one agent per customer of yours with POST /UserAgent/Deploy, with useprepaid: true and a plan in tier. The answer's useragents[0].guid is the agent's id: the useragentguid of every other call. The agent is queued and Wiro starts it: it is ready for messages when POST /UserAgent/Detail reads status: 4. Give each conversation its own sessionkey.
{
"agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": "Acme Marketing Agent",
"useprepaid": true,
"tier": "pro",
"chatsetup": "all"
}
Allow setup cards in API chats
Where setup cards can be proposed and applied is the agent's chatsetup setting. Wiro reads every request sent with a project API key as an API chat:
chatsetup |
Cards in your API chat | SetupCardApply with your API key |
|---|---|---|
all (the default) |
Yes | Works |
webchat |
No: only the Wiro web chat gets cards. In your product, the same as off. |
Refused: Setup from chat is off for this agent. |
off |
No | Refused: Setup from chat is off for this agent. |
So an integration that shows setup cards needs "all". Set it at Deploy with chatsetup, or later with POST /UserAgent/UpdateSettings, and read it back as chatSetup on UserAgent/Detail. A change from or to "off" restarts a starting or running agent once, and a change between "all" and "webchat" restarts nothing. UpdateSettings doesn't say whether it restarted the agent: read UserAgent/Detail after it, as in Showing a restart.
curl -X POST "https://api.wiro.ai/v1/UserAgent/UpdateSettings" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"chatsetup": "all"
}'
{ "result": true, "errors": [] }
With "webchat" or "off", the agent proposes no card in your chat and tells people that an agent admin makes the change in the agent's settings, which in your product are the settings screens you build on the same endpoints.
Who may apply a card
Applying a card needs an agent admin: the agent's owner, or an admin of the agent's team. With your API key, that is the key's owner, so every apply your backend sends counts as that person's approval. Dismissing a card needs only that the caller can see the chat.
Because of this, decide in your own product who may approve a change: show the Apply button, and pass a typed approval on to Wiro, only for the people allowed to change that agent. Wiro reads many words as an approval, not only yes, and a key pasted while a key connect card is the only connect card waiting can be saved to it when its connector is on the agent or a pending add card on the same reply brings it: Typed replies has the whole list. When people who must not change the agent talk to it through your app, set chatsetup to "off" for that agent and change its setup from your own settings screens instead. That is the safe choice for any agent that several of your users share.
Messages and Answers
Send a message
curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/Send" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"message": "Can you report our website traffic every Monday?",
"sessionkey": "customer-42"
}'
{
"result": true,
"errors": [],
"messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
"status": "agent_queue"
}
Keep messageguid (the turn) and agenttoken (its live stream). The full parameter list, attachments and per-turn model choice are in Message/Send. result: true means the message was queued: follow the turn to its end, since a turn that couldn't be handed to the agent still ends as agent_error (see When a turn fails).
When the agent isn't running, Send answers result: false with agentstatus and a sentence you can show as it is:
{
"result": false,
"errors": [{ "code": 0, "message": "Agent is restarting. Please wait a moment and try again.", "time": 1794654900 }],
"messageguid": null,
"agenttoken": null,
"status": null,
"agentstatus": 1
}
See Restarts for the other sentences.
When the agent has used all its credits, Send answers result: false with agentstatus and agentbalance:
{
"result": false,
"errors": [{ "code": 0, "message": "Agent has no remaining credits. Renew your subscription or buy a credit pack to continue.", "time": 1794654900 }],
"messageguid": null,
"agenttoken": null,
"status": null,
"agentstatus": 4,
"agentbalance": { "monthlycredits": 3000, "extracredits": 0, "usedcredits": 3000, "remainingcredits": 0 }
}
That sentence speaks to whoever pays for the agent, which is you. Detect the refusal by agentbalance, show your users your own words, and add credits from your backend: an extra credit pack with useprepaid: true, or a larger plan with UpgradeTier. Setup replies that Wiro answers itself still work without credits: see Replies the API answers itself.
Follow the turn
Use one of three ways:
- WebSocket (best for a live chat): connect to
wss://socket.wiro.ai/v1and send{ "type": "agent_info", "agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb" }. You getagent_subscribed(a snapshot withstatus,debugoutputandtimeline), thenagent_start, oneagent_timeline_deltaper changed block,agent_outputsnapshots of the answer text, andagent_end,agent_errororagent_cancel. See Agent WebSocket. - Polling: call
POST /UserAgent/Message/Detailwith{ "messageguid": "..." }every second or two untilstatusisagent_end,agent_errororagent_cancel. - Webhook: send
callbackurlwith the message, and Wiro posts the final answer to it. See Agent Webhooks.
Setup blocks arrive on the WebSocket like any other block, as agent_timeline_delta:
{
"type": "agent_timeline_delta",
"agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
"message": {
"messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"block": {
"blockid": "s:k3v9q2m8x1za",
"type": "setup",
"callindex": 1000000,
"contentindex": 0,
"text": null,
"setup": {
"v": 1,
"id": "k3v9q2m8x1za",
"kind": "schedule",
"action": "create",
"key": "cs-cron-weekly-traffic",
"title": "Weekly traffic report",
"cron": "0 9 * * 1",
"instructions": "Every Monday, report last week's sessions, users and top pages from Google Analytics 4.",
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811
},
"phase": "end",
"version": 1,
"startedat": 1794654811,
"updatedat": 1794654811
}
},
"result": true
}
When someone applies or dismisses the card later, the block comes again on the same agenttoken with version: 2 and the new status, as long as your socket is still subscribed to that token. Message/Detail and Message/History always return the current state, so after a reconnect, read them again.
To stop a reply that is still running, call POST /UserAgent/Message/Cancel with its messageguid, and with its sessionkey when several of your users share the agent, so that one person can't stop another's reply. The turn ends as agent_cancel.
When a turn fails
A turn that fails ends with status: "agent_error", and a cancelled one with "agent_cancel". Its response and debugoutput, and the text of the agent_error or agent_cancel event and of the webhook, hold one code in brackets and a fixed sentence:
| Code | Status | What to show |
|---|---|---|
[SECURITY_BLOCKED] |
agent_error |
The agent's security rules blocked the message: ask the person to change it. |
[SAFETY_POLICY_BLOCKED] |
agent_error |
The model's provider declined the request: ask the person to rephrase it. |
[TURN_INTERRUPTED] |
agent_error |
A restart cut the turn short: offer to send it again. |
[SPEND_LIMIT_REACHED] |
agent_error |
The agent's spend limit is used up: show the sentence as it is. |
[USAGE_CEILING_REACHED] |
agent_error |
The agent reached its hourly or daily safety ceiling for AI model calls: say it runs again when that hour or day is over. |
[MODEL_NOT_ALLOWED] |
agent_error |
The agent's Model Access rule blocks the model it uses: show the sentence as it is. |
[AGENT_UNAVAILABLE] |
agent_error |
Anything else, a message that couldn't be queued included: offer to try again shortly. |
[REQUEST_CANCELLED] |
agent_cancel |
The turn was cancelled. |
Match the code and show your own words, or the sentence after it. The full texts are in Failed turns.
Load a conversation
POST /UserAgent/Message/History returns a session's messages, newest first. Each row has the fields of a Message/Detail answer except sessionkey, startedat and endedat, which History doesn't return:
curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/History" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"sessionkey": "customer-42",
"limit": 50
}'
{
"result": true,
"errors": [],
"data": {
"messages": [
{
"guid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"content": "Can you report our website traffic every Monday?",
"response": "I can do that once Google Analytics 4 is on and connected. Approve the card below and connect your Google Analytics account.",
"status": "agent_end"
}
],
"count": 1,
"hasmore": false,
"sessiontoken": "Lp4vQ8sWn2KxT7cRb1YhZ6mDg9FjA3uEo5iNk0wXyHt"
}
}
The row is shortened here; the GA4 example in Worked Examples shows a whole one as Message/Detail returns it. Page back with before (the oldest guid you have) while hasmore is true. A session holds four kinds of row:
| Row | How you know it | What your UI shows |
|---|---|---|
| A turn | content holds the message as stored (keys taken out, see Security Rules), response the reply, timeline[] its blocks, setup blocks included, in their current state |
The person's message and the agent's reply. While status is agent_queue, agent_start or agent_output, the reply is in progress: subscribe to its agenttoken to follow it. |
| A reply Wiro answered itself | metadata.type is "setup_result", agenttoken is null, timeline is empty |
The message and response as plain text. See Replies the API answers itself. |
| A message added between turns | content is empty, the text is in response, metadata.type is "subagent" or "system" |
The agent's message with no message of the person's above it: a scheduled task's report, files sent after an answer, or, for "subagent", the result of work the agent finished in the background. |
| A model switch | status is "agent_done", metadata.type is "model_change" |
A thin separator, or nothing. It comes only when you pick a per-turn model. |
A message added between turns has no turn of its own: nothing streams on an agenttoken for it and no webhook is called. A scheduled task's report goes to the session the agent's latest message is in, so on an agent that several of your users share it can reach any of their chats. To get it live, follow the session with the sessiontoken above: send { "type": "agent_session_subscribe", "sessiontoken": "Lp4vQ8sWn2KxT7cRb1YhZ6mDg9FjA3uEo5iNk0wXyHt" } on the socket, and each new row arrives as an agent_message_inserted frame. Follows end with the connection, so after a reconnect subscribe again and read History once. See Following a session. The weekly report of the GA4 example below reaches your chat this way.
To list a customer's conversations, call POST /UserAgent/Message/Sessions with the useragentguid: it answers each session's sessionkey, messagecount, updatedat, lastmessage and, once named with RenameSession, name. It lists every session of the agent that your key's owner can read, so on an agent that several of your users share, show each person only the sessions your own records give them.
Render the timeline
A reply is an ordered list of blocks. Keep a map keyed by blockid, keep a block only when its version is newer than the one you hold, and draw the blocks sorted by callindex, then contentindex, then blockid.
type |
What it holds | What your UI shows |
|---|---|---|
reasoning |
text: a short summary of the agent's thinking |
A collapsed "Thinking" section, in its place in the list. |
answer |
text: the answer text |
The agent's message. Render it as Markdown. |
tool |
toollabel, toolstatus (requested, completed, error), toolintegration, toolaction |
A small status line, such as "Working in Shopify" or "Taking a screenshot". Use your own labels for the toolintegration and toolaction words, and toollabel when both are null. |
setup |
setup: a setup card; on a pending connect card, also next |
A card with buttons. See Setup Cards. |
Setup blocks have callindex: 1000000, so they sort after the reply's other blocks, in the order the agent proposed them, at most three per message. Skip a block whose type you don't know. The block fields are listed in Public timeline block fields.
Wiro cleans the agent's text before it reaches you, in the blocks, in response and in every event: a link to a private address or into the agent's own system reads [link removed], and a path inside the agent's system reads [private detail removed]. A turn in which the agent wrote nothing, older ones included, can read No response from agent. Show these as they are, or your own words. Public links stay as written, the Wiro AI Models links of Your product shows everything included.
Replies the API answers itself
Some messages are answered by Wiro itself, with no agent turn: a yes that applies a card or gets the card listing, a key typed as the reply while the latest reply has one pending connect card whose connector takes one key (Wiro reads it only while that connector is on the agent or a pending add card on the same reply brings it), and the others listed in Chats Without Cards. Message/Send then answers at once with status: "agent_end", agenttoken: null, the answer in response and the outcome in setupresult:
{
"result": true,
"errors": [],
"messageguid": "d4e5f6a7-b8c9-0123-def4-567890123456",
"agenttoken": null,
"status": "agent_end",
"response": "✅ Applied: Scheduled task Weekly traffic report created.\nYour agent is restarting to load the change. Continue in about a minute.",
"content": "yes",
"setupresult": {
"applied": ["k3v9q2m8x1za"],
"dismissed": [],
"failed": [],
"restarting": true
}
}
Show response as the reply, as plain text. There is nothing to follow on the WebSocket. In Message/History the row reads status: "agent_end", metadata: { "type": "setup_result" } and an empty timeline. These replies use no credits, and Wiro gives them while the agent is stopped or restarting too: see Messages during a restart for which ones.
Wiro also answers a slash command the agent doesn't run, such as /status, or one of its commands that is turned off, while the agent is running. It uses no credits, even when the agent has none left, and the answer has no setupresult:
{
"result": true,
"errors": [],
"messageguid": "e5f6a7b8-c9d0-1234-ef56-789012345678",
"agenttoken": null,
"status": "agent_end",
"response": "⛔ Unknown or disabled command: /status\nSend /agent_help to see the available commands.",
"content": "/status"
}
The second line comes only when the agent has agent_help on. Show response as the reply, and the row in History as you show the other replies Wiro answers itself. A command counts anywhere in the message, as in Check the /pricing page, but never inside a link or a quoted line. A message that holds one of the agent's enabled commands, written in lower case and followed by a space, a line break or the end of the message, goes to the agent, which runs it, and so does a message whose first command is /model, /models or one of a few common words and paths, such as /start, /help or /usr/bin/env. While the agent isn't running, the message gets the refusal in Messages during a restart. The full rules are in Unknown or disabled commands.
Setup Cards
Block fields
A setup block has the usual block fields, type: "setup", text: null and a setup object, the card:
{
"blockid": "s:h6w3k9p2m5tc",
"type": "setup",
"callindex": 1000000,
"contentindex": 1,
"text": null,
"setup": {
"v": 1,
"id": "h6w3k9p2m5tc",
"kind": "connect",
"connector": "serper",
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811
},
"phase": "end",
"version": 1,
"startedat": 1794654811,
"updatedat": 1794654811,
"next": [{ "connector": "serper", "title": "Serper Web Search", "mode": "key" }]
}
| Field | Description |
|---|---|
blockid |
s: and the card's id. Use it as the merge key. |
type |
setup. |
callindex |
1000000 for every setup block, so it sorts after the reply's other blocks. |
contentindex |
The card's place on the message: 0, 1 or 2. Add 1 for the card number a card listing uses. |
text |
Always null. |
setup |
The card. See Card fields. |
phase |
Always end. |
version |
1 while the card is pending, 2 once it is applied, dismissed or failed. Keep the copy with the higher version. |
startedat |
When the agent proposed the card (Unix seconds). |
updatedat |
When the card last changed. |
next |
Only on a pending connect card: how its own connector connects, as one entry { connector, title, mode }. It is gone once the card is applied, dismissed or failed. See Your Own Connect Button. An add card's block has no next: its setup.needs lists what it brings. A card stored before next existed may have none. It still gets one while a pending add card on the same message names its connector in needs. Without one, name its connector by credentials.<connector>._schema.title of UserAgent/Detail and send the person to your settings screen for it. |
Card fields
| Field | Kinds | Description |
|---|---|---|
v |
all | Card format version, 1. |
id |
all | The card's id: 12 lower-case letters and digits. Send it as cardid to SetupCardApply. |
kind |
all | add, remove, connect, disconnect, schedule, skill or timezone. Skip a card whose kind you don't know. |
action |
schedule, skill |
schedule: create, update, pause, resume or delete. skill: create, update, append (add text to the end), revert (undo the last change), disable or enable. |
key |
add, remove, schedule, skill |
add and remove: the connector (int-<name>) or skill (util-<name>) as POST /Skills/List names it. schedule: the task's key (cs-cron-<name>). skill: the custom skill's key (cs-<name>). |
connector |
connect, disconnect |
The connector's key as POST /Credentials/List lists it, such as serper. A card never holds a key's value. |
title |
schedule, skill |
Optional. One line, up to 80 characters. |
cron |
schedule |
Five fields, in the agent's time zone. Always on create, optional on update. A task set up from chat runs at most once an hour. |
instructions |
schedule, skill |
create and update: the full text. append: only the text to add. revert: the text it restores. Up to 20,000 characters on what the agent writes. |
before |
skill (update, append, revert) |
The skill's text when Wiro checked the card. Show it next to the text after the change: for append, that is before without the spaces and line breaks at its end, a blank line, then instructions. Can be absent on older cards. |
with |
add, remove |
Other connectors and skills turned on (add) or off (remove) together with key, by name, sorted, at most 12. Written by Wiro. An add names only the ones still off on this agent, so the same key can bring a different list, or none, on another agent. |
pauses, resumes |
add, remove |
Scheduled tasks (cs-cron-<name>) that stop, or run again, with this change, at most 20 each. Written by Wiro. Name each by the description of its entry in scheduledskills of UserAgent/Detail, or by its key in words. |
needs |
add |
The connectors the change brings that aren't connected yet, at most 3, each { connector, title, mode }. title can be absent: then use the connector's key. Written by Wiro. See Modes. |
timezone |
timezone |
The proposed IANA time zone, such as Europe/Istanbul. |
note |
all | Optional. The agent's one-line note on the change, up to 300 characters. |
status |
all | Absent while pending, then applied, dismissed or failed. |
actedat, actedby |
all | When the card was acted on (Unix seconds) and the account UUID of who did it. Absent while pending. With your API key, actedby is your key's owner. |
error |
all | Only when status is failed: one plain sentence that says why. |
requestedby |
all | The account UUID of the person whose message asked for the change: in your chats, your key's owner. |
createdat |
all | When the agent proposed the card (Unix seconds). |
Fields that don't apply to a card's kind are absent, and a missing list reads as empty. More kinds, actions and fields can be added later.
Every kind
add turns on a connector or skill. This one turns on Brevo Email, two skills it depends on, and brings the Brevo connector, which still needs its key:
{
"v": 1,
"id": "m5t8c2w6r3pe",
"kind": "add",
"key": "int-brevo-email",
"with": ["util-anti-ai-human-copy", "util-chat-markdown-reporting"],
"needs": [{ "connector": "brevo", "title": "Brevo", "mode": "key" }],
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811
}
When needs names a connector with mode key, signin, appkeys or token, Wiro stores a connect card for it on the same message, right after the add card, when the message has room for it (three cards at most) and no pending connect card for that connector yet. Show the two as one card: see Buttons.
remove turns one off. Its saved key stays saved:
{
"v": 1,
"id": "w2c8n5q1x7rd",
"kind": "remove",
"key": "int-brevo-email",
"pauses": ["cs-cron-newsletter-digest"],
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811
}
connect connects a connector that is on, or the one an add card on the same message brings:
{
"v": 1,
"id": "h6w3k9p2m5tc",
"kind": "connect",
"connector": "serper",
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811
}
disconnect removes a connector's saved key. Wiro takes it only for a connector that is connected with a key and that the agent can run without:
{
"v": 1,
"id": "b7k1m4t9w2zs",
"kind": "disconnect",
"connector": "brevo",
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811
}
schedule creates or changes a scheduled task:
{
"v": 1,
"id": "k3v9q2m8x1za",
"kind": "schedule",
"action": "create",
"key": "cs-cron-weekly-traffic",
"title": "Weekly traffic report",
"cron": "0 9 * * 1",
"instructions": "Every Monday, report last week's sessions, users and top pages from Google Analytics 4.",
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811
}
skill creates or changes a custom skill. An append card carries only the text it adds, and before:
{
"v": 1,
"id": "p7d2m4x9q1ka",
"kind": "skill",
"action": "append",
"key": "cs-blog-writing",
"instructions": "End every post with three questions readers ask, each with a two-sentence answer.",
"before": "Write each blog post in a friendly, plain tone.\nKeep posts under 900 words.",
"note": "Adds the reader questions you asked for.",
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811
}
timezone changes the agent's time zone:
{
"v": 1,
"id": "z4x8c1v6b3nm",
"kind": "timezone",
"timezone": "Europe/Istanbul",
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811
}
A card once acted on carries status, actedat and actedby, and a failed one error. This append card failed because someone edited the skill after the card was made:
{
"v": 1,
"id": "p7d2m4x9q1ka",
"kind": "skill",
"action": "append",
"key": "cs-blog-writing",
"instructions": "End every post with three questions readers ask, each with a two-sentence answer.",
"before": "Write each blog post in a friendly, plain tone.\nKeep posts under 900 words.",
"note": "Adds the reader questions you asked for.",
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811,
"status": "failed",
"actedat": 1794654870,
"actedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"error": "This skill changed after the card was made. Ask the agent again."
}
The full rules of each kind, such as what with, pauses and before mean, are in Setup From Chat.
Card states
| State | How you know | What it means |
|---|---|---|
| Pending | No status (block version 1) |
Waiting for someone to apply or dismiss it. |
| Applied | status: "applied" |
The change is made. The answer that applied it says in restarting whether the agent restarts. |
| Dismissed | status: "dismissed" |
Turned down. Nothing changed. |
| Failed | status: "failed" |
Wiro tried to apply it and couldn't: error says why. Nothing changed, with one exception: a disconnect card fails with <Title> is disconnected in the agent's settings. when the connector still reads connected after the agent's own key was removed, because the agent's template holds one too. That removal stays, and restarting in the answer says whether the agent restarts for it. |
Two more states exist only in your interface, between a click and the answer: applying (your call is under way), and refused, when SetupCardApply answers result: false and the card is still pending, for example a key that is too short or a sign-in that isn't finished. A refused card keeps its buttons. While the agent restarts after a change, show the card as applied with a restarting note; see Restarts.
Applying a connect card also marks the same person's other connect cards for that connector applied, when they are still pending on other messages of the same chat from the last 7 days. Their blocks come again on their own agenttokens, and History shows them applied.
What your UI shows for each kind
| Kind | Title line | Body | Buttons |
|---|---|---|---|
add |
"Add <title>", the title of key in Skills/List |
with as "Also turns on", pauses and resumes, and each entry of needs with its connect step |
Apply, Dismiss; Connect for each connector in needs that has a connect card |
remove |
"Remove <title>" |
with as "Also turns off", pauses and resumes. Say that a saved key stays saved. |
Apply, Dismiss |
connect |
"Connect <next[0].title>" |
By next[0].mode: a form for key, your Connect step for signin, appkeys and token, a link to your settings screen for page |
Save for key; Connect, which runs your flow and then applies the card, for the sign-in modes; none for page; and Dismiss |
disconnect |
"Disconnect <title>", the connector's title from UserAgent/Detail (credentials.<connector>._schema.title) |
Say that its saved key is removed and the skills that use it stop until it is connected again | Disconnect, Dismiss |
schedule |
"Create", "Change", "Pause", "Resume" or "Delete" scheduled task <title or key> |
The schedule in words, in the agent's time zone, and instructions |
Apply, Dismiss |
skill |
"Create", "Change", "Add to", "Undo the last change to", "Turn off" or "Turn on" custom skill <title or key> |
instructions; for update, append and revert, before next to the text after the change |
Apply, Dismiss |
timezone |
"Set the time zone to <timezone>" |
The current zone, timezone on UserAgent/Detail (null means UTC) |
Apply, Dismiss |
Show note, when there is one, under the title.
What your UI shows for each state
| State | Show | Buttons |
|---|---|---|
| Pending, reply still being written | The card | Apply disabled while the message's status is agent_queue, agent_start or agent_output; Dismiss works |
| Pending | The card | All enabled |
| Applying | The card with a spinner | Disabled |
| Refused | errors[0].message under the card; for errorcode: "not_connected", the Connect step again |
Enabled |
| Applied | "Applied", and summary from the answer when you have it |
None |
| Applied, agent restarting | "Applied" and "Restarting, about a minute" until the agent runs again | None |
| Dismissed | "Turned down" | None |
| Failed | "Not applied" and setup.error |
None |
Buttons
- Apply:
SetupCardApplywithaction: "apply". - Dismiss:
SetupCardApplywithaction: "dismiss". When you dismiss anaddcard, dismiss itsconnectcards too: they can't connect anything without it. - An
addcard with aconnectcard: theconnectcards on the same message whoseconnectoris in theaddcard'sneedsbelong to it. Show them inside theaddcard, with one button that does both:modekey: show the connector's fields and an Add and connect button:SetupCardApplyon theaddcard withvalues.modesignin,appkeysortoken: show a Connect button that runs your connection flow, then Add:SetupCardApplyon theaddcard withsignin: true.- Either way, offer Add now, connect later too:
SetupCardApplyon theaddcard alone. Its answer'snextthen names theconnectcard to finish later. valuesgo with the add card's onekeycard, andsignin: truewith its one sign-in card. With twokeycards it takes novalues, and with two sign-in cards nosignin: true: offer Add alone, then eachconnectcard's own button.
- A
connectcard alone:modekeyshows the fields and Save (SetupCardApplywithvalues). A sign-in mode shows Connect, which runs your connection flow, then callsSetupCardApplyon the card.modepageshows a link to your settings screen: applying it is refused.
A connector with mode page gets no connect card with its add card, and no card can connect it: its setup happens in your settings screens. See Page.
Applying and Dismissing
Request
POST /UserAgent/Message/SetupCardApply acts on one card:
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | The agent. |
messageguid |
string | Yes | The message that holds the card: the row whose timeline[] has the setup block. |
cardid |
string | Yes | The card's setup.id. |
action |
string | Yes | "apply" or "dismiss". |
values |
object | No | { "<fieldname>": "<value>" }. On a connect card for a key connector: its fields. On an add card whose connect card takes a key: that card's fields, and Wiro applies both cards in one step. Only text, password, url and email fields, up to 4,096 characters each, named as POST /Credentials/Detail lists them in credential_schema. Saved to the connector, never returned and never shown to the agent. |
signin |
boolean | No | true with action: "apply" on an add card whose sign-in connect card's connector you have just connected: Wiro applies both cards in one step. Never together with values. |
curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/SetupCardApply" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"cardid": "k3v9q2m8x1za",
"action": "apply"
}'
Answer
{
"result": true,
"errors": [],
"setup": {
"v": 1,
"id": "k3v9q2m8x1za",
"kind": "schedule",
"action": "create",
"key": "cs-cron-weekly-traffic",
"title": "Weekly traffic report",
"cron": "0 9 * * 1",
"instructions": "Every Monday, report last week's sessions, users and top pages from Google Analytics 4.",
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811,
"status": "applied",
"actedat": 1794654870,
"actedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f"
},
"restarting": true,
"summary": "Scheduled task Weekly traffic report created"
}
| Field | Description |
|---|---|
result |
true when the action went through. false when it was refused or failed: read errors[0].message, and setup.status when setup isn't null. |
errors |
[{ code, message, time }]. message is one plain sentence you can show as it is. |
setup |
The card after the call: still pending after a refusal, applied, dismissed or failed otherwise. null when the call was refused before the card was read: a missing parameter, an agent or message your key can't reach, setup from chat off, a reply still running, code 97, a card someone is applying at that moment, or a card that isn't there. |
restarting |
true when the agent restarts to load the change. See Restarts. It can be true with result: false too, when the call changed part of the setup before it was refused or failed: some fields saved while others are still needed, or the failed disconnect of Card states. |
summary |
A short phrase that says what changed, such as Scheduled task Weekly traffic report created or Serper Web Search added. Serper Web Search connected.. Empty when nothing was applied. |
paired |
Only when values or signin: true came with an add card: its connect card after the call, [{ setup, result, error }]. result is true when that card was applied too, and error is null or the sentence that says why not. [] when the add card has no single connect card to take them. |
next |
Only when something is left to connect: [{ connector, title, mode, cardid?, messageguid? }]. See Your Own Connect Button. |
errorcode |
Only on the refusals of a sign-in connect card, or of an add card sent with signin: true: not_connected, signin_values, signin_no_pair or signin_many. See Errors. |
Dismissing answers the card with status: "dismissed", restarting: false and an empty summary.
Everyone subscribed to the turn's agenttoken gets the card's new block as an agent_timeline_delta, and so does the connect card applied with an add card. Update your copy from the answer's setup right away, and from the block when it arrives.
Who may call it
With your project API key, a call acts as the key's owner, and works when all of these hold:
- The agent's
chatsetupis"all". Otherwise:Setup from chat is off for this agent. - The key's owner owns the agent or is a member of its team, and the key's project is in the agent's workspace: a team project's key for a team agent, a personal one for a personal agent. Otherwise:
Agent not found or access denied, or a sentence that names the workspace to use. - The message is one the key's owner can read with
Message/History: not deleted, not hidden, and in a private chat their own. Otherwise:This setup card was not found. - To apply: the reply that holds the card has finished (otherwise
Wait until the agent finishes this reply, then apply it.), and the key's owner is an agent admin (otherwise code97,Only an agent admin can apply setup changes.). Dismissing works at any time for anyone who can see the chat. - The card is pending. A card is applied at most once: on one that was acted on, the answer says
This card was already applied.,This card was already dismissed.orThis card was already failed., with the card insetup.
SetupCardApply takes no sessionkey. When several of your users share one agent, check in your backend that the messageguid belongs to the session of the person who clicked, for example with Message/Detail and its sessionkey.
Connecting a Connector
Modes
Each entry of needs and of next says how its connector connects in mode:
mode |
How it connects | Your UI | Calls |
|---|---|---|---|
key |
A key, or a few fields, typed by the person | A form with the connector's fields | SetupCardApply with values |
appkeys |
The person's own app keys, then the provider's sign-in | A form for the app keys, the redirect URI to register, then a Connect button | CredentialUpsert, OAuthConnect (own), OAuthStatus, SetPickerAccounts, then SetupCardApply |
token |
A token Wiro checks on the server, such as a Meta System User token | A form for the token, then the accounts to pick when the check lists some | CredentialUpsert, OAuthConnect (api_key), SetPickerAccounts when there are accounts to pick, then SetupCardApply |
signin |
The provider's sign-in with Wiro's own app | A Connect button | OAuthConnect (wiro), OAuthStatus, SetPickerAccounts when there are accounts to pick, then SetupCardApply |
page |
Anything else: service account files, lists, the Wiro project of Wiro AI Models | A link to your settings screen for that connector | The credential endpoints, with no card |
Read a mode you don't know as page. mode is the connector's usual way. A connector can offer others, listed in connection_modes of POST /Credentials/Detail by their authmethod: wiro is signin, own is appkeys and api_key is token. Any of them that connects the connector lets its card apply. wiro stays listed while wiro_connect_pending is true, and until that flag is false, OAuthConnect refuses it with Sign-in with the platform's app is not enabled for <Title>: don't offer it then. Each mode below uses one example connector, and the same calls work for every connector of that mode.
The fields of a connector are in POST /Credentials/Detail (credential_schema), which needs no API key, and in credentials.<connector>._schema.fields of UserAgent/Detail. Which of them a form shows:
appkeys,tokenandsignin: the fields whoseonly_in_modesis absent or names the mode'sauthmethod, leaving out the ones markedauto_filled_by_oauth,server_managedorplatform_managed, and any that isn't atext,password,urloremailinput. Every required one goes on the form: LinkedIn's app keys come with its organization ID, and Shopify's token check needs the shop domain besides the client ID and secret. Fortoken,oauth_provider.direct_probe.required_fieldsnames the fields the check reads.key: thetext,password,urlandemailfields,requiredmarking the ones the connector needs.
Key: Serper Web Search
A key connector takes its fields as values. Serper Web Search has one field, apikey (label "Serper API Key", at least 20 characters).
With its add card, in one step. Send the key with the add card that brings the connector. Wiro checks the key first, against the connector as the add card will leave it: a refused key applies nothing, and both cards stay pending. Otherwise both cards are applied, with one restart:
curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/SetupCardApply" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"cardid": "q4n7s1v8b2xd",
"action": "apply",
"values": { "apikey": "THE_SERPER_API_KEY" }
}'
{
"result": true,
"errors": [],
"setup": {
"v": 1,
"id": "q4n7s1v8b2xd",
"kind": "add",
"key": "int-serper-search",
"needs": [{ "connector": "serper", "title": "Serper Web Search", "mode": "key" }],
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811,
"status": "applied",
"actedat": 1794654870,
"actedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f"
},
"restarting": true,
"summary": "Serper Web Search added. Serper Web Search connected.",
"paired": [
{
"setup": {
"v": 1,
"id": "h6w3k9p2m5tc",
"kind": "connect",
"connector": "serper",
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811,
"status": "applied",
"actedat": 1794654870,
"actedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f"
},
"result": true,
"error": null
}
]
}
A key that is too short:
{
"result": false,
"errors": [{ "code": 0, "message": "Serper API Key must be at least 20 characters", "time": 1794654870 }],
"setup": {
"v": 1,
"id": "q4n7s1v8b2xd",
"kind": "add",
"key": "int-serper-search",
"needs": [{ "connector": "serper", "title": "Serper Web Search", "mode": "key" }],
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811
},
"restarting": false,
"summary": "",
"paired": [
{
"setup": {
"v": 1,
"id": "h6w3k9p2m5tc",
"kind": "connect",
"connector": "serper",
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811
},
"result": false,
"error": "Serper API Key must be at least 20 characters"
}
]
}
On its connect card. When the connector is already on, or its add card was applied without the key, send the fields with the connect card:
{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"cardid": "h6w3k9p2m5tc",
"action": "apply",
"values": { "apikey": "THE_SERPER_API_KEY" }
}
{
"result": true,
"errors": [],
"setup": {
"v": 1,
"id": "h6w3k9p2m5tc",
"kind": "connect",
"connector": "serper",
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811,
"status": "applied",
"actedat": 1794654900,
"actedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f"
},
"restarting": true,
"summary": "Serper Web Search connected"
}
A connect card sent before its add card is applied changes nothing and answers Apply card 1 first: it turns on Serper Web Search.. A connector with several fields, such as WordPress, is connected once all its required fields are saved: with only some of them, the fields you sent are saved, the card stays pending, and the answer is result: false with Saved <fields> for <Connector>. Still needed: <fields>.. Send the rest with the same card. The same values sent with the add card still apply the add card: the answer is result: true, summary names only the add, paired[0] has result: false and that sentence, and next names the connect card to finish. A save of some fields can restart the agent, so restarting can be true on either answer.
Own app keys: Google Analytics 4
The person connects with their own Google Cloud OAuth client, so Google's consent screen shows their app's name. The steps, for a pending add card for int-ga4-analytics and its connect card for ga4:
1. Read what the form needs. OAuthStatus returns the redirect URI to register in the app and whether app keys are saved already:
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthStatus" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "credentialkey": "ga4" }'
{
"result": true,
"errors": [],
"connected": false,
"accounts": [],
"connectedat": "",
"tokenexpiresat": "",
"authmethod": "",
"redirecturi": "https://api.wiro.ai/v1/UserAgentOAuth/GA4Callback",
"appkeyssaved": false,
"tokensaved": false
}
Show a form with the app's fields (clientid and clientsecret for Google, listed in credential_schema with only_in_modes: ["own"]) and the redirecturi to copy into the app's authorized redirect URIs. When appkeyssaved is true, the keys are saved already: offer to use them or replace them. Saved app keys are never returned.
2. Save the app keys with CredentialUpsert, with authmethod: "own". Saving app keys restarts nothing. In this flow the connection restarts nothing either, since nothing on the agent uses Google Analytics 4 until the add card is applied, and that apply restarts the agent once (step 8).
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"fields": [
{ "credentialkey": "ga4", "fieldname": "clientid", "fieldvalue": "1234567890-abc.apps.googleusercontent.com" },
{ "credentialkey": "ga4", "fieldname": "clientsecret", "fieldvalue": "GOCSPX-THE_CLIENT_SECRET" },
{ "credentialkey": "ga4", "fieldname": "authmethod", "fieldvalue": "own" }
]
}'
{ "result": true, "applied": 3, "errors": [] }
3. Start the sign-in with OAuthConnect, and your own page as redirecturl: any https URL you control, or http://localhost while you develop. The browser comes back to it with no useragentguid in the query, so put your own reference in it:
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"credentialkey": "ga4",
"authmethod": "own",
"redirecturl": "https://app.example.com/connect/done?ref=conn_8812"
}'
{
"result": true,
"errors": [],
"authorizeUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=1234567890-abc.apps.googleusercontent.com&redirect_uri=https%3A%2F%2Fapi.wiro.ai%2Fv1%2FUserAgentOAuth%2FGA4Callback&scope=...&response_type=code&state=...&access_type=offline&prompt=select_account+consent",
"flowid": "9d2c41e07ab35f8e6c1d0b9a87f6e5d4"
}
Keep flowid: it names this sign-in. A new OAuthConnect for the same agent and connector replaces it.
4. Send the browser to authorizeUrl. Either redirect the tab, or open a popup from the click handler and let your return page tell the opener (for example with postMessage) and close itself. Google shows its account chooser and then the consent screen.
5. Read the return. The browser comes back to your redirecturl, with the result added to the query:
https://app.example.com/connect/done?ref=conn_8812&ga4_connected=true&ga4_properties=%5B%7B%22id%22%3A%22123456789%22%2C%22displayName%22%3A%22Acme%20Web%22%2C%22account%22%3A%22Acme%22%2C%22propertyType%22%3A%22PROPERTY_TYPE_ORDINARY%22%7D%2C%7B%22id%22%3A%22987654321%22%2C%22displayName%22%3A%22Acme%20App%22%2C%22account%22%3A%22Acme%22%2C%22propertyType%22%3A%22PROPERTY_TYPE_ORDINARY%22%7D%5D
On failure it carries ga4_error=<code> instead; see Return codes. Each connector has its own prefix (ga4_, x_, fb_ and so on), listed in Callback success and error parameters.
6. Read the accounts to pick from your backend with OAuthStatus, called as in step 1. This also works when you didn't read the return, such as after a popup:
{
"result": true,
"errors": [],
"connected": false,
"accounts": [],
"connectedat": "2026-11-14T11:14:50.000Z",
"tokenexpiresat": "2026-11-14T12:14:50.000Z",
"authmethod": "own",
"redirecturi": "https://api.wiro.ai/v1/UserAgentOAuth/GA4Callback",
"appkeyssaved": true,
"tokensaved": false,
"flow": {
"flowid": "9d2c41e07ab35f8e6c1d0b9a87f6e5d4",
"mine": true,
"mode": "own",
"status": "candidates",
"account": "",
"errorcode": "",
"errordetail": "",
"restart": "none",
"expiresat": 1794655790
},
"candidates": [
{ "id": "123456789", "name": "Acme Web" },
{ "id": "987654321", "name": "Acme App" }
]
}
flow is the agent's current sign-in or token check for this connector, whoever started it: OAuthStatus takes no flowid, so compare flow.flowid with the one you kept. Another flowid means a newer sign-in replaced yours. To anyone but the person who started it, flow holds only mine, status and expiresat, such as { "mine": false, "status": "candidates", "expiresat": 1794655790 }, and candidates is absent. flow.status is waiting until the person comes back, then candidates (accounts to pick), connected (nothing to pick), saved (the accounts were saved and the list is used up), or failed with flow.errorcode. A flow lives 15 minutes from OAuthConnect, or 15 minutes from the moment its accounts were listed; after that flow is absent. Poll every two seconds or so while you wait. Show candidates as a list with checkboxes.
7. Save the accounts picked with SetPickerAccounts, the flowid and their ids, within 15 minutes of the sign-in:
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/SetPickerAccounts" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"credentialkey": "ga4",
"flowid": "9d2c41e07ab35f8e6c1d0b9a87f6e5d4",
"accountids": ["123456789"]
}'
{
"result": true,
"errors": [],
"accounts": [{ "id": "123456789", "name": "Acme Web" }],
"restart": "none"
}
The connector is now connected. restart is "none" because nothing on the agent uses Google Analytics 4 until the add card is applied.
Two connectors have a second step after the accounts: Meta Ads (its Facebook Pages, optional) and Google Business Profile (its locations, required). Discover the items with DiscoverPickerItems, sending the picked ids as parents and the sign-in's flowid, then save both steps in one SetPickerAccounts call with accountids, pickerkey and selections. For a Google Business Profile sign-in:
{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"credentialkey": "google-business",
"pickerkey": "locations",
"flowid": "7f3e2d1c0b9a88776655443322110ffe",
"parents": ["112233445566778899001"]
}
{
"result": true,
"errors": [],
"pickerkey": "locations",
"groups": [
{
"parent": { "accountid": "112233445566778899001", "accountname": "Acme Bakery" },
"items": [
{ "locationid": "9876543210987654321", "locationtitle": "Acme Bakery Downtown" },
{ "locationid": "1234567890123456789", "locationtitle": "Acme Bakery Riverside" }
]
}
]
}
{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"credentialkey": "google-business",
"flowid": "7f3e2d1c0b9a88776655443322110ffe",
"accountids": ["112233445566778899001"],
"pickerkey": "locations",
"selections": [{ "parentvalue": "112233445566778899001", "itemids": ["9876543210987654321"] }]
}
A group whose items couldn't be listed comes with items: [] and an errorcode of its own, such as provider_timeout: show it, and leave that account out of selections. See Both steps in one call for the rules of that save.
8. Apply the cards. Send the add card with signin: true. Wiro checks that the connector reads connected, then applies the add card, which restarts the agent once, and its connect card:
{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"cardid": "71xb9zrcd1sb",
"action": "apply",
"signin": true
}
{
"result": true,
"errors": [],
"setup": {
"v": 1,
"id": "71xb9zrcd1sb",
"kind": "add",
"key": "int-ga4-analytics",
"needs": [{ "connector": "ga4", "title": "Google Analytics 4", "mode": "appkeys" }],
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811,
"status": "applied",
"actedat": 1794654960,
"actedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f"
},
"restarting": true,
"summary": "Google Analytics 4 added. Google Analytics 4 connected.",
"paired": [
{
"setup": {
"v": 1,
"id": "ljehd9inazm4",
"kind": "connect",
"connector": "ga4",
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811,
"status": "applied",
"actedat": 1794654960,
"actedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f"
},
"result": true,
"error": null
}
]
}
When the add card was applied earlier on its own, apply the connect card instead, with no values. It writes nothing: it records that the connector is connected, and answers summary: "Google Analytics 4 connected" with restarting: false, since the connection itself restarted the agent.
Token: Facebook Pages
The person pastes a Meta Business System User token, Wiro checks it on the server and lists the Pages it can post to, and the person picks them. There is no browser redirect. For a pending add card for int-facebookpage-post and its connect card for facebook-pages:
1. Save the token with authmethod: "api_key". This restarts nothing.
{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"fields": [
{ "credentialkey": "facebook-pages", "fieldname": "authmethod", "fieldvalue": "api_key" },
{ "credentialkey": "facebook-pages", "fieldname": "systemusertoken", "fieldvalue": "THE_SYSTEM_USER_TOKEN" }
]
}
{ "result": true, "applied": 2, "errors": [] }
2. Check it with OAuthConnect and the same authmethod, and no redirecturl:
{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"credentialkey": "facebook-pages",
"authmethod": "api_key"
}
{
"result": true,
"errors": [],
"flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19",
"accounts": [
{ "id": "1029384756", "name": "Acme" },
{ "id": "5647382910", "name": "Acme Outlet" }
],
"account": "Acme Marketing System User",
"restart": "none"
}
accounts are the Pages to pick, and account names who the token belongs to. A refused check answers result: false with errorcode, such as direct_token_invalid or no_pages; see Token check codes.
3. Save the Pages picked:
{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"credentialkey": "facebook-pages",
"flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19",
"accountids": ["1029384756"]
}
{
"result": true,
"errors": [],
"accounts": [{ "id": "1029384756", "name": "Acme" }],
"restart": "none"
}
4. Apply the cards: the add card with signin: true, as for Google Analytics 4. The answer's summary reads Facebook Page Post added. Facebook connected. The token never reaches the agent, and the Page tokens Wiro finds with it never leave the server.
Sign-in: X with Wiro's app
A signin connector connects with Wiro's own app, so there are no app keys to collect: one button. The provider's consent screen then names Wiro's app, not yours. To show your own brand there, connect the same connector with your own app keys instead (authmethod: "own", as in Own app keys), where the connector offers it in connection_modes: a product whose users never see Wiro's name does that wherever it can, and shows its own label for Wiro AI Models (see Your product shows everything). For a pending add card for int-twitterx-post and its connect card for twitter:
1. Start the sign-in:
{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"credentialkey": "twitter",
"authmethod": "wiro",
"redirecturl": "https://app.example.com/connect/done?ref=conn_8813"
}
{
"result": true,
"errors": [],
"authorizeUrl": "https://x.com/i/oauth2/authorize?client_id=...&redirect_uri=https%3A%2F%2Fapi.wiro.ai%2Fv1%2FUserAgentOAuth%2FXCallback&scope=...&response_type=code&state=...&code_challenge=...&code_challenge_method=S256",
"flowid": "e1a2b3c4d5e6f708192a3b4c5d6e7f80"
}
2. Send the browser to authorizeUrl. The person approves on X and comes back to your page:
https://app.example.com/connect/done?ref=conn_8813&x_connected=true&x_username=acmeco
3. Check the connection with OAuthStatus. X has no accounts to pick, so the sign-in connects it:
{
"result": true,
"errors": [],
"connected": true,
"accounts": [{ "id": "acmeco", "name": "acmeco" }],
"connectedat": "2026-11-14T11:15:25.000Z",
"tokenexpiresat": "2026-11-14T13:15:25.000Z",
"authmethod": "wiro",
"redirecturi": "https://api.wiro.ai/v1/UserAgentOAuth/XCallback",
"appkeyssaved": false,
"tokensaved": false,
"flow": {
"flowid": "e1a2b3c4d5e6f708192a3b4c5d6e7f80",
"mine": true,
"mode": "wiro",
"status": "connected",
"account": "acmeco",
"errorcode": "",
"errordetail": "",
"restart": "none",
"expiresat": 1794655802
}
}
4. Apply the cards: the add card with signin: true. summary reads Twitter / X Post added. Twitter / X connected.
Page: set up outside the chat
A connector with mode page, such as Google Drive with its service account file, gets no connect card with its add card, and no card can connect it. When its add card is applied, summary goes on with Connect Google Drive in the agent's settings, and next lists it with mode: "page" and no cardid. The agent can still propose a connect card for it on its own: that block's next reads mode: "page", and applying the card is refused with Google Drive is connected in the agent's settings, not from chat. while it stays pending. Show such a card as a link to your settings screen, with Dismiss. Send the person to your own settings screen for that connector, which saves it with the credential endpoints, as its integration page shows:
{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"fields": [
{ "credentialkey": "google-drive", "fieldname": "serviceaccountjson", "fieldvalue": "BASE64_OF_THE_SERVICE_ACCOUNT_JSON" }
]
}
{ "result": true, "applied": 1, "errors": [] }
There is no card to apply afterwards. The save restarts a running agent once, so it loads the connector, but its answer doesn't say so: see Showing a restart. Files go through CredentialFileUpload, and the Wiro AI Models connector, the Wiro project the agent runs models with, through CredentialProjectBind, whose answer says in restart whether the agent restarts.
Your Own Connect Button
Where next appears
next is the list of connectors still to connect, as data for your own buttons. It comes in four places:
| Where | When | Entries |
|---|---|---|
| A setup block | On a pending connect card |
One entry, its own connector: { connector, title, mode }. No cardid: it is the block's own card. |
SetupCardApply answer |
An add card applied, alone, with values or with signin: true, that leaves connectors not connected; a sign-in connect card refused with not_connected or signin_values; a connect card for a page connector |
{ connector, title, mode, cardid?, messageguid? } |
setupresult.next in a Message/Send answer |
A yes that applied a card: the reply's key connect cards still waiting for their key, the sign-in connect cards of the add card it applied, and each connector that add card brings with no card to connect it. A yes while only connect cards wait, one of them a sign-in card: the waiting connect cards. A key typed for an add card and its connect card: the other connectors that add card brings. |
Same |
metadata.next in the webhook |
The same answers as setupresult.next, posted to the message's callbackurl |
Same |
next is absent when nothing is left to connect: never an empty array.
Entry fields
| Field | Description |
|---|---|
connector |
The connector's key, as needs[].connector and a connect card's connector name it. |
title |
Its name, one line, up to 80 characters. Use it on the button: "Connect Google Analytics 4". |
mode |
key, signin, appkeys, token or page. See Modes. |
cardid |
The pending connect card that records the connection once it is made. Never on page entries. |
messageguid |
The message that card is on. Present exactly when cardid is, and only in answers. |
From next to a button
// For each entry of next, show one button that runs the mode's flow,
// then applies the card that records the connection.
// own: for an entry of a block's next, that block's card and message.
async function connectFromNext(entry, useragentguid, own) {
const cardid = entry.cardid || (own && own.cardid);
const messageguid = entry.messageguid || (own && own.messageguid);
if (entry.mode === "page") {
return openSettingsScreen(entry.connector); // your own screen; no card to apply
}
if (entry.mode === "key") {
const values = await askForFields(entry.connector); // your form, never the chat
if (!cardid) return saveWithCredentialUpsert(entry.connector, values); // no card records it
return setupCardApply({ useragentguid, messageguid, cardid, action: "apply", values });
}
// signin, appkeys, token: run the connection, then record it on its card when there is one.
await runConnection(entry.connector, entry.mode); // OAuthConnect and the rest
if (!cardid) return;
return setupCardApply({ useragentguid, messageguid, cardid, action: "apply" });
}
// A pending connect card's block, on its Message/Detail or History row:
// connectFromNext(block.next[0], useragentguid, { cardid: block.setup.id, messageguid: row.guid });
A block's next names no card because the card is the block's own: pass its setup.id and the row's guid, as the last line shows. An entry of an answer with no cardid and a mode other than page has no card left to record it, for example because its connect card was turned down: connect it the same way, with CredentialUpsert for a key, and there is nothing to apply. When the answer to a sign-in connect card is errorcode: "not_connected" with next, the connection isn't finished: run the flow again from that entry.
Errors and What to Show
Every refusal comes as result: false with one plain sentence in errors[0].message. Show it as it is, or your own words for its code, and match codes, not sentences, in your code: sentences can change. A few sentences speak of the card's own sign-in or button, such as Finish the sign-in on the card first.: in your product, that is your Connect step.
SetupCardApply refusals
errorcode |
Sentence | What to do |
|---|---|---|
not_connected |
<Title> is not connected yet. Finish the sign-in on the card first. |
Run the Connect step, then apply again. The card stays pending. On a connect card, next names it. |
signin_values |
<Title> connects with its sign-in on the card, not with typed values. |
Don't send values to a sign-in connect card: connect it, then apply with no values. |
signin_no_pair |
This card has no sign-in to finish. Apply it without one. |
The add card has no pending sign-in connect card. Apply it without signin. |
signin_many |
This card brings more than one sign-in. Apply it, then connect each on its own card. |
Apply the add card alone, then connect each connector and apply its own connect card. |
For a token connector, such as Facebook, Instagram, Meta Ads or Shopify, each of these sentences says token check where it says sign-in: Facebook connects with its token check on the card, not with typed values.
Refusals with no errorcode:
| Sentence | What to do |
|---|---|
Request parameter [<name>] required, action must be apply or dismiss, values must be an object of field names and text. |
Fix the request. |
Setup from chat is off for this agent. |
Set chatsetup to "all", or change the setup from your settings screens. |
Agent not found or access denied, or a sentence that names the workspace to use |
Your key can't reach this agent: see Who may call it. |
Only an agent admin can apply setup changes. (code 97) |
The key's owner can't apply on this agent. |
Wait until the agent finishes this reply, then apply it. |
Enable Apply once the reply ends. |
This setup card was not found. |
Wrong messageguid or cardid, or a message the key's owner can't see. |
This card was already applied., This card was already dismissed., This card was already failed. |
Show the card from setup in its state. |
This card is being applied. Try again in a moment., The card could not be applied right now. Try again in a moment., Another change to this agent's connectors or skills is being applied. Try again in a moment. |
Someone is acting on this card, or on the agent's connectors and skills, right now. Let the person try again after a few seconds. |
Apply card <N> first: it turns on <Title>. |
Apply the add card first, or send the key with the add card. |
Send values or signin, not both. |
Send one of them. |
This card takes no key. Apply it without one., This card brings more than one key. Apply it, then add each key on its own card. |
values on an add card that can't take them. |
<Connector> needs its key. |
values held no field with a value. |
<Connector> takes only its own fields from a chat card., <Label> must be text., <Label> is too long. |
A field name the connector doesn't have, a value that isn't text, or one over 4,096 characters. Nothing was saved. |
Saved <fields> for <Connector>. Still needed: <fields>. |
Send the missing fields with the same card. |
Saved <fields> for <Connector>. It is not connected yet: finish it in the agent's settings. |
The fields are saved, and the connector still doesn't read connected: finish it in your settings screen for it. |
A field's sentence, such as Serper API Key must be at least 20 characters |
Show it next to the field. Nothing was saved. |
<Title> is connected in the agent's settings, not from chat. |
A page connector: next names it with mode: "page". |
<Connector> is not connected: <Add> was not added., <Title> is connected, but <Add> was not added. |
In paired[0].error, the first with values and the second with signin: true, when the add card failed: its connect card stays pending. When the add card's change waits for another change instead, both cards stay pending, and paired[0].error reads Another change to this agent's connectors or skills is being applied. Try again in a moment., as errors[0].message does. |
The setup card could not be applied. Try again. |
Something went wrong. Read the card again with Message/Detail before you offer to try again. |
These refusals carry code 0, except the rights refusal, whose code is 97. Check what you can before you call: that the reply has ended, that chatSetup is "all", and that the card is pending in your copy.
A card that fails as it is applied gets status: "failed" and its sentence in setup.error, and the answer is result: false with the same sentence. The usual ones are This agent's connectors or skills changed after the card was made. Ask the agent again., This skill changed after the card was made. Ask the agent again., <Title> is disconnected in the agent's settings. and The change could not be applied. Try again in a moment., when Wiro couldn't make the change. Show it on the card. A failed card can't be applied again: the person asks the agent for a new one.
Account list codes
SetPickerAccounts and DiscoverPickerItems answer these in errorcode, with a sentence in errors[0].message that speaks of a sign-in or of a token check, as the list came from one or the other. not_listed, for example, reads Choose accounts from the list the sign-in returned. or Choose accounts from the list the token check returned. The sentences are listed under SetPickerAccounts.
errorcode |
Meaning | What to show |
|---|---|---|
flow_expired |
No account list is open: no sign-in or check was started, it was over 15 minutes ago, a save already used its list, or the connector was disconnected. | "The connection timed out", and the Connect button again. |
flow_other_person |
Another account started the current sign-in or check. | The Connect button again. |
flow_replaced |
The flowid you sent isn't the current one: a newer sign-in or check replaced it. |
Use the newer one, or connect again. |
flow_failed |
The current sign-in or check failed. OAuthStatus shows why in flow.errorcode. |
The reason, and the Connect button. |
flow_waiting |
The sign-in hasn't come back from the provider yet, so there is no list. | Keep waiting for the person to finish; don't start a new sign-in, which would replace it. |
not_listed |
An id you sent isn't on the list the sign-in or check returned. | Pick again from candidates. |
next_expired |
Both steps in one call, but the second step's discovery is missing or more than five minutes old. | Call DiscoverPickerItems with parents again. |
next_required |
Both steps in one call for Google Business Profile with no location picked. | Ask for at least one location. |
too_many_parents |
More than 50 Meta ad accounts, or more than 20 Business Profile accounts, for the second step. | Ask the person to pick fewer. |
OAuthConnect refusals
Before it starts a sign-in, OAuthConnect can refuse with one of these sentences. Nothing starts then, and a sign-in already under way stays as it is.
| Sentence | What to do |
|---|---|
Request parameter [redirecturl] required, Invalid redirect URL |
Send an https redirecturl you control, or an http one on localhost or 127.0.0.1 while you develop. |
<Title> credentials not configured |
The app keys of authmethod: "own" aren't saved: save them with CredentialUpsert first. |
Unsupported connection mode for <Title> |
authmethod isn't in the connector's connection_modes. |
Sign-in with the platform's app is not enabled for <Title> |
authmethod: "wiro", sent or taken as the default, while the connector's wiro_connect_pending is true: use own or api_key. |
<Field> is required, Invalid <Field> |
A saved field the sign-in needs is missing or malformed, such as Shopify's shop domain: save it with CredentialUpsert. |
User agent not found or unauthorized |
Your key's owner can't manage this agent. |
Reddit also refuses until Wiro has set the approvals it reviews, with sentences such as The platform must verify Reddit Data API approval for this app before connecting.
Return codes on your redirect URL
After a sign-in, the browser comes back to your redirecturl with <prefix>_error=<code> when it failed:
| Code | What to show |
|---|---|
authorization_denied |
The person cancelled, or the provider refused. Offer to connect again. |
session_expired |
More than 15 minutes passed. Connect again. |
flow_replaced |
A newer sign-in replaced this one. Nothing was saved. |
token_exchange_failed |
The provider gave no usable token, for example because the app's client secret is wrong. Check the app keys. |
no_accounts, no_pages |
The sign-in worked, but there is nothing to pick. Say what to create first, such as a GA4 property. |
account_list_too_large |
More than 2,000 accounts to pick from. Connect with a login that sees fewer. |
useragent_not_found |
Before the sign-in came back, the agent was deleted, or the person who started the sign-in, your key's owner, could no longer manage it. Nothing was saved. |
internal_error, or any other code |
Something went wrong. Offer to connect again. |
Some connectors add their own codes, listed on their integration pages and in Callback success and error parameters, and Merchant Center can add mc_error_detail with the provider's status, such as PERMISSION_DENIED.
A callback that can't be matched to a sign-in, because it came without its state or more than 24 hours after OAuthConnect, can't return to your page. It ends on a plain page of the API's own, /v1/UserAgentOAuth/SignInNotFinished on the API's host, which names no brand and links nowhere: it says the sign-in could not be finished and the window can be closed, and shows the code (missing_params, session_expired or internal_error). Your return page hears nothing then, so when a popup doesn't report back, read OAuthStatus and offer to connect again.
Token check codes
A token check that fails answers OAuthConnect with result: false, a sentence, flowid, errorcode and restart, such as direct_token_missing (the token or authmethod: "api_key" isn't saved), direct_token_invalid, no_accounts, no_pages, too_many_pages, account_list_too_large, direct_picker_unavailable, provider_rejected_request, provider_request_failed or provider_timeout. Show the sentence, and let the person paste a new token. restart is "scheduled" when the failed check removed a connection the agent was using. Each integration page lists its codes.
Restarts
When the agent restarts
An agent loads its setup when it starts, so most changes restart it:
add,remove,connect(a key saved),disconnectandtimezonecards, ascheduleorskillcard that creates one, aschedulecard that changescron, andpause,resume,delete,disableandenablecards.- A card that changes only the text of a custom skill or scheduled task (
append,revert, or anupdatethat keeps the schedule) reaches a running agent without a restart. - A sign-in
connectcard writes nothing: the connection restarted the agent if it needed to, so its apply answersrestarting: false. - One change, one restart. An
addcard applied with its key, or withsignin: true, restarts the agent once for both cards, and a change made while a restart is still stopping or queued loads with that restart. - A connection made with a sign-in, app keys or a token check while nothing on the agent uses the connector restarts nothing, which is why connecting first and then applying the
addcard withsignin: truerestarts the agent once. Fields saved withCredentialUpsertfor a connector that has no sign-in, akeyconnector or apageone such as Google Drive, restart a starting or running agent whenever a saved value changes, whether or not anything on the agent uses the connector. - An agent that is stopped doesn't start: it loads the change when it next starts, and
restartingisfalse.
restarting in the SetupCardApply answer and in setupresult says whether this change restarts the agent.
Status values
Read the agent's status with POST /UserAgent/Detail { "guid": "<useragentguid>" }:
status |
During a restart |
|---|---|
1 Stopping |
The agent is shutting down to start again. |
2 Queued |
It waits to start. |
3 Starting |
It is starting. |
4 Running |
Ready for messages again. |
A restart takes about a minute. If the poll reads 0 (stopped), 5 (error) or 6 (setup required) instead, the agent won't start by itself: stop polling and say so. 0 and 5 start again with POST /UserAgent/Start, and 6 needs its missing connector first; see UserAgent Statuses.
Showing a restart
When an answer says the agent restarts, show a line such as "Restarting to load the change, about a minute" above the message box, and poll UserAgent/Detail every five seconds until status is 4. Then hide the line. You can leave the message box on: a message sent too early gets a clear refusal you can show.
Each call says it in its own field:
| Call | Says the agent restarts with |
|---|---|
SetupCardApply, and Message/Send in setupresult |
restarting: true |
OAuthConnect (a token check), SetPickerAccounts, CredentialProjectBind |
restart: "scheduled" |
OAuthStatus, after a sign-in came back |
flow.restart: "scheduled" |
CredentialUpsert, UpdateSettings |
Nothing. After a save that can restart the agent, such as a connector's key or fields, or chatsetup changed from or to "off", poll UserAgent/Detail the same way. |
So when a sign-in connect card's connector is on already, the connection itself restarts the agent through these calls, and the card's apply then answers restarting: false.
Messages during a restart
While the agent isn't running, Message/Send answers result: false with agentstatus and one of these sentences, shown as they are:
agentstatus |
Sentence |
|---|---|
1 |
Agent is restarting. Please wait a moment and try again. (or Agent is stopping. Please wait a moment and try again. when it stops for good) |
2, 3 |
Agent is starting up. Please wait a moment and try again. |
0 |
Agent is stopped. Start it before sending messages. |
5 |
Agent is in error state. Restart it before sending messages. |
6 |
Agent setup is incomplete. Complete the setup before sending messages. |
Before this refusal, Wiro still answers the replies it handles itself:
- A
yesthat lists or applies a card other than aconnectcard, and ayeswhile a sign-inconnectcard waits. - A key for a
keyconnect card that is the onlyconnectcard waiting, while its connector is on the agent or a pendingaddcard on the same reply brings it. Another service's key is answered too, whoever sends it, once that card's connector is on the agent, and nothing is saved:That does not look like a <Title> key (it looks like <kind>), so it was not saved. Paste the <Title> key as your reply.The part in brackets comes only when Wiro knows the kind, and before a title that starts with a vowel,abecomesan, as inan Apollo key. While the connector isn't on the agent yet, as while theaddcard that brings it still waits, another service's key is only taken out, and the message gets the refusal. - Such a
yes, or a key for the waitingkeycard, from a sender who isn't an agent admin, answeredOnly an agent admin can apply setup changes. - A
nothat turned pending cards down, answeredThe setup change was turned down.orThe <N> setup changes were turned down.
Every other message gets the refusal, a yes while only key connect cards wait, a key while more than one connect card waits, and a yes or no with no pending card included. A turn still running when the restart began, in another session for example, ends as agent_error with [TURN_INTERRUPTED]: offer to send it again.
Chats Without Cards
Your chat can work with text alone, or people may type yes even where you show cards. Wiro then reads the reply itself.
Typed replies
- Approve. A message that is only an approval, such as
yes,ok,approve,go ahead,evetor👍, acts on the pending cards of the agent's latest reply in the samesessionkey, when they are less than 30 minutes old. In a chat sent with your API key, the first approval applies nothing: Wiro answers with the card listing, the exact content of the cards. A second one applies the one card listed. With several cards,yes 2applies card 2 once the listing has shown it, one card per reply. - Turn down. A message that is only a refusal, such as
noorcancel, dismisses the pending cards of the latest reply that are less than 30 minutes old, then goes to the agent as a normal message. Older cards aren't dismissed, and thenogoes to the agent all the same. While the agent isn't running, Wiro answers it itself:The setup change was turned down., orThe <N> setup changes were turned down.for several cards. Anyone who can write in the chat can turn cards down. - A key as the reply. When the latest reply has one pending
connectcard for a key connector, a key pasted as the reply can be saved to it with your key owner's rights. Wiro reads the key for that card only while its connector is on the agent or a pendingaddcard on the same reply brings it; otherwise the key is only taken out, as in any other message. While the connector is on the agent, the key is saved, and the message is stored as[key saved to <Connector title>]. While a pendingaddcard still brings the connector, the key is read for its card but not saved, since theaddcard goes first: Wiro answers⚠️ Not saved: Apply card <N> first: it turns on <Title>. Paste the key again as your reply., the message is stored with[key removed]in its place, and both cards stay pending. The one exception is a chat sent with your API key when the only pending cards are anaddcard and itsconnectcard, and the key is all the connector needs: the key typed after the listing applies both cards at once. A key typed before that listing saves nothing: the message is stored with[key removed]in its place, and Wiro answers with the listing. - A
yesnever applies aconnectcard: a key or a sign-in connects it.
The latest reply is the newest row of the session, other than the replies Wiro answers itself and model switches. A row added between turns counts, such as a scheduled task's report written into that session: once it comes, a yes or no typed after it finds no cards. Your buttons still act on those cards, since SetupCardApply takes a pending card by its messageguid and cardid, at any age.
A message counts as an approval or a refusal when it is sent with no attachment and has at most four words, no question mark and nothing but these words. Case, accents and other punctuation don't matter:
| Kind | Words |
|---|---|
| Approval | yes, y, yeah, yep, yup, ok, okay, sure, approve, approved, confirm, confirmed, apply, lgtm, do it, go ahead, go for it, sounds good, looks good, please do, of course, evet, e, tamam, tamamdır, olur, onay, onayla, onaylıyorum, onayladım, uygula, kabul, kabul ediyorum, ja, oui, si, sim, da, hai, 👍, ✅, ✔ |
| Refusal | no, n, nope, nah, cancel, stop, don't, do not, never mind, not now, hayır, yok, iptal, vazgeç, vazgeçtim, istemiyorum, nein, non, não |
| Courtesy, allowed next to either | please, pls, plz, thanks, thx, ty, thank you, lütfen, teşekkürler, teşekkür ederim, sağol, sağolun, bitte, danke, merci, gracias, por favor |
| A card number, with an approval | One number from 1 to 3, as in yes 2, apply #1, evet 3 or yes card 2 |
If people who must not change the agent can write in your chat, hold back from Wiro the messages that are only these words, and a key sent while a key connect card waits, or set chatsetup to "off" for that agent. The full rules are in Approving a setup card.
Listing the cards
The first yes in a chat sent with your API key gets the listing:
{
"result": true,
"errors": [],
"messageguid": "e5f6a7b8-c9d0-1234-ef56-789012345678",
"agenttoken": null,
"status": "agent_end",
"response": "The agent proposes this setup change. Nothing is applied yet.\n\nCard 1: Add Google Analytics 4 (connector).\nStill to connect: Google Analytics 4.\n\nReply \"yes\" to apply exactly this change, or \"no\" to turn it down.",
"content": "yes",
"setupresult": { "applied": [], "dismissed": [], "failed": [], "restarting": false }
}
Show response as it is. Its lines are described in The card listing.
setupresult and next
| Field | Description |
|---|---|
applied |
Ids of the cards applied. |
dismissed |
Ids of the cards turned down. |
failed |
[{ id, error }] for cards that failed. |
restarting |
true when the agent restarts to load the change. |
next |
Only when the answer leaves connectors to connect: [{ connector, title, mode, cardid?, messageguid? }], as in Your Own Connect Button. |
The second yes, which applies an add card whose sign-in connect card still waits:
{
"result": true,
"errors": [],
"messageguid": "f6a7b8c9-d0e1-2345-f678-901234567890",
"agenttoken": null,
"status": "agent_end",
"response": "✅ Applied: Google Analytics 4 added.\nYour agent is restarting to load the change.\nNext: connect Google Analytics 4 to finish. Its sign-in, app keys or token are entered outside this chat, never in it.",
"content": "yes",
"setupresult": {
"applied": ["71xb9zrcd1sb"],
"dismissed": [],
"failed": [],
"restarting": true,
"next": [
{
"connector": "ga4",
"title": "Google Analytics 4",
"mode": "appkeys",
"cardid": "ljehd9inazm4",
"messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234"
}
]
}
}
Show response, and under it a "Connect Google Analytics 4" button built from next. A yes while only connect cards wait, one of them a sign-in card, applies nothing and answers A yes cannot connect <Title>. Its sign-in, app keys or token are entered outside this chat, never in it., with the cards in setupresult.next. A webhook posted for these replies carries the same list in metadata.next.
The answer lines
Wiro writes these lines in response, always in English. They name no site, page or link:
| Line | When |
|---|---|
✅ Applied: <summary>. |
A card was applied. An add card that brings a page connector, or a sign-in connector with no connect card on the message, goes on with Connect <Title> in the agent's settings. |
⚠️ Not applied: <reason> |
The change failed. |
1 more setup change is still pending., <N> more setup changes are still pending. |
A yes applied one card while other cards of the reply wait. |
<N> connector cards still need their keys: add each key on its card. |
Several key connect cards wait. |
This setup change was already handled. |
Someone acted on the card first, or it is gone. |
This setup change is being applied right now. Try again in a moment. |
Another call is applying the card. |
Your agent is restarting to load the change. Continue in about a minute. |
The change restarts the agent (shorter when a Next: line follows). |
Next: paste your <Title> key as your reply. |
A key connect card waits for its key. While the agent restarts, it goes on with Send it now and it loads with this same restart. |
Next: connect <Title> to finish. Its sign-in, app keys or token are entered outside this chat, never in it. |
An add card was applied and its sign-in connect card waits. |
A yes cannot connect <Title>. Its sign-in, app keys or token are entered outside this chat, never in it. |
A yes while only connect cards wait, one of them a sign-in card. |
Saved <fields> for <Connector>. Still needed: <fields>. |
A key was saved and the connector needs more fields. |
⚠️ Not saved: <reason>. Paste the key again as your reply. |
The key was refused. Nothing was saved. |
That does not look like a <Title> key (it looks like <kind>), so it was not saved. Paste the <Title> key as your reply. |
The key pasted is another service's, and the only connect card waiting is a key connect card whose connector is on the agent. It comes whoever sent the key. The part in brackets is there only when Wiro knows the kind. Before a title that starts with a vowel, a becomes an, as in an Apollo key. |
⚠️ Not saved: <Add title> is still waiting. Reply "yes" to add it, or "no" to turn it down. |
A key typed for an add card whose connect card no longer waits. |
This card is older than 30 minutes. Use the card's button, or ask the agent again. |
The card turned 30 minutes old while the reply was read. In your product, offer your own button, or ask the agent again. |
Only an agent admin can apply setup changes. |
The sender can't apply changes. |
The setup change was turned down., The <N> setup changes were turned down. |
A no while the agent isn't running. |
The full list is in Wiro's answers.
Screen and Take Control in Your App
Every agent has its own computer in the cloud: a 1920 x 1080 desktop with the web browser the agent works in. Your app can show that computer live, the agent's Screen, and let a person take control of it with the keyboard and mouse, for example to sign in to a site for the agent or to finish a step by hand. Your backend gets a one-time ticket with your API key, and your page opens a WebSocket with it and draws the screen with noVNC, an open source VNC client for the browser. The Wiro panel's own Screen works the same way: Screen and Take Control in the Agent Overview describes it, with what pauses during control, the limits and the activity log rows.
Your page Your backend Wiro
--------- ------------ ----
Show a Screen button? -> Realtime/ScreenInfo --------------> available, canControl, reason
Person opens it -> Realtime/ScreenStart -------------> wsUrl, screenToken (one use, 60 s)
new WebSocket(wsUrl), first frame: screen_start -------------> screen_ready
noVNC draws the binary frames (RFB 3.8) <--------------------> the agent's desktop
Take Control -> ScreenStart { control: true } ---> a new ticket for a new socket
Hand Back: close the control socket, open a view again
Decide who sees it
A call made with your API key acts as the key's owner, the person who created its project: every screen you open is that person's screen as far as Wiro is concerned. It watches the agents that person may watch, and takes control where that person may. Your key speaks for your whole product, so Wiro gives it a ticket whichever of your users it is for, and who sees what is your product's decision:
- Who may watch. Ask for a ticket only for the users you allow to see that agent's computer.
- Who may take control. Offer Take Control, and ask for
control: true, only to the users you allow to use its keyboard and mouse. - What a shared agent shows. An agent has one computer and one browser for all of its chats. Its Screen shows what the agent is doing in any of them: each of your users' chats, its Telegram, Slack and Discord chats and its Scheduled Tasks, and the agent brings the tab it is working in to the front. Take Control reaches every site that browser is signed in to, for all of the agent's users, and what a person signs in to during control stays there for all of them. It also pauses the agent's browser and desktop tools in every chat until control ends. With one agent per customer, the Screen shows only that customer's work. On an agent several of your users share, show it only to people who may see all of their work.
- The switch.
screen: "off"onUpdateSettingscloses the Screen for everyone, your users and the Wiro panel alike, and ends open screens within about half a minute."on"opens it again. Send it with the same API key; the key's owner must be the agent's owner or an admin of its team. It never restarts the agent.
curl -X POST "https://api.wiro.ai/v1/UserAgent/UpdateSettings" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"screen": "off"
}'
{ "result": true, "errors": [] }
Which agents your key opens:
| Your key | Watches | Takes control of |
|---|---|---|
| A personal project's key | Its owner's personal agents, and a team agent in Chat Mode "collaborative" while its owner deployed that agent or is an admin of its team, and is still a member |
Its owner's personal agents that have never been in a team, or whose browser was reset after they last left one |
| A team project's key | That team's agents in Chat Mode "collaborative", when its owner deployed the agent or is an admin of the team |
Nothing: no one takes control of a team agent |
Team agents in Chat Mode "private", Studio and the Workflow Agent have no Screen. A team project's key never opens a personal agent or another team's agent.
Ask whether the Screen can open
Before you show a Screen button, your backend asks POST /UserAgent/Realtime/ScreenInfo:
curl -X POST "https://api.wiro.ai/v1/UserAgent/Realtime/ScreenInfo" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321" }'
{ "result": true, "errors": [], "available": true, "canControl": true, "reason": null }
When the Screen can't open, available and canControl are false and reason says why, here because the screen setting is off:
{ "result": true, "errors": [], "available": false, "canControl": false, "reason": "setting_off" }
| Field | Description |
|---|---|
available |
Show the Screen button. |
canControl |
Offer Take Control once the screen is live, to the people you allow. |
reason |
null while available is true, otherwise why not. |
What to do for each reason:
reason |
What to do |
|---|---|
not_allowed |
Show no Screen: your key can't open this agent's Screen (see Decide who sees it), or no agent has this guid, because it is unknown or was deleted. |
private_team |
Show no Screen: a team agent in Chat Mode "private" has none. |
setting_off |
Show no Screen. Ask again after the screen setting changes; the Wiro panel asks every 60 seconds. |
not_running |
Ask again once Detail reads status: 4. |
unsupported |
The agent's computer doesn't offer the Screen yet. It does once the agent has restarted. |
disabled |
The Screen is turned off on every agent at the moment. Ask again later. |
error |
Ask again in a few seconds; the Wiro panel tries again after 5 seconds, 30 seconds and 2 minutes. |
ScreenInfo never refuses an agent: only a missing useragentguid answers result: false. Ask again when the agent starts or stops and when its screen setting changes.
Get a ticket
When a person opens the Screen, your page asks your backend, and your backend calls POST /UserAgent/Realtime/ScreenStart. Send { "useragentguid": "..." } to watch, and add "control": true for Take Control.
curl -X POST "https://api.wiro.ai/v1/UserAgent/Realtime/ScreenStart" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321" }'
{
"result": true,
"errors": [],
"wsUrl": "wss://socket.wiro.ai/v1/AgentRealtime/Screen",
"screenToken": "<one-time screen ticket>",
"control": false,
"canControl": true,
"maxSeconds": 1800
}
| Field | Description |
|---|---|
wsUrl |
The Screen socket. Pass it to the page as it is; don't build or hardcode the host. |
screenToken |
The one-time ticket. The page sends it as the socket's first message within 60 seconds. Keep it in memory only, never in a URL or a log. |
control |
true for a Take Control ticket. |
canControl |
Whether this person may take control now, as far as Wiro goes. Show or hide Take Control by it, together with your own rules. |
maxSeconds |
The longest the session lasts: 1800 seconds to watch, 900 in control. |
idleSeconds |
Control only: control ends after this many seconds without a key or pointer event (120). |
Your backend returns only these fields to the page, never your API key. Ask for a new ticket for every socket: each Reconnect, each Take Control and each view you open again. A refused start answers result: false with one sentence in errors[0].message, which you can show as it is; every code is listed under ScreenStart's errors.
{
"result": false,
"errors": [
{
"code": 99,
"message": "Take Control is off for team agents: their browser is shared by the whole team.",
"time": 1795201200
}
]
}
code |
What to do |
|---|---|
94 |
The screen setting is off: hide the Screen, as for setting_off. |
95 |
The agent isn't running, or is gone: hide the Screen until it runs again. |
96, 97 |
Your key can't open this agent's Screen: hide it. |
98 |
The Screen isn't ready on this agent: show the sentence and let the person try later. |
99 |
Take Control isn't available: keep the view, show the sentence, and hide Take Control until canControl is true again. Take Control could not start just now. Try again in a minute. is a check that couldn't finish, so ask ScreenInfo again in a minute: its canControl says when Take Control is back. |
409 |
The agent is capturing its screen: keep the view, show the sentence, and let the person try again in a minute. |
429 |
Too many starts, too many viewers or the hourly Take Control limit: show the sentence, which says how long to wait. Two of these come with HTTP 429. |
503 |
A check couldn't finish: show the sentence and offer to try again. |
0 |
Show the sentence, then ask ScreenInfo again and go by its answer. After This agent belongs to a team. Switch to the team context to access it. it says not_allowed: your key's owner is no longer a member of the agent's team, so hide the Screen. Request parameter [useragentguid] required means your backend sent no guid. Any other 0 is a check that couldn't finish: offer to try again. |
95, 96 and 97 are the agent access codes the UserAgent endpoints share, and ScreenStart gives 95 and 96 a few sentences of its own; 94, 98, 99, 409, 429 and 503 are ScreenStart's own. In the Error Reference, 96, 97, 98 and 99 mean other things.
The Screen socket
The page opens wsUrl with no extra headers, subprotocols or query string. When the socket opens, the page sends the ticket in a text frame, within 10 seconds:
{ "type": "screen_start", "screenToken": "<screenToken from ScreenStart>" }
The server answers with one text frame:
{ "type": "screen_ready", "control": true, "maxSeconds": 900, "idleSeconds": 120 }
idleSeconds comes only in control. From then on, every frame in both directions is binary: an RFB 3.8 stream (the VNC protocol) with security type None, so there is no password to send. noVNC speaks it; your page hands noVNC these binary frames and nothing else (see Drawing the screen with noVNC). Text frames the page sends after the first are ignored. The server pings every 25 seconds, and browsers answer by themselves.
Right before the server closes a session, it sends one more text frame that says why, then closes the socket with a code:
{ "type": "screen_end", "reason": "idle", "message": "Control was handed back after a while without keyboard or mouse input." }
| Close code | reason |
message |
When |
|---|---|---|---|
1000 |
none | none | Your page closed the socket, with code 1000: Hand Back, or the screen was closed. |
1008 |
none | none | The first message wasn't a screen_start with a screenToken, or didn't come within 10 seconds. |
4001 |
error |
This screen link expired. Open the screen again. |
The ticket is unknown, used or more than 60 seconds old. |
4001 |
error |
The agent's screen is not available right now. |
The agent was deleted after the ticket was issued. |
4004 |
agent_stopped |
The agent stopped. |
The agent isn't running, or stopped or restarted during the session. |
4003 |
screen_off |
Screen was turned off in this agent's settings. |
The screen setting is "off", checked at the start and every 25 seconds. |
4029 |
too_many_viewers |
Too many people are watching this agent's screen. |
4 screens are already open on the agent. |
4502 |
unavailable |
The agent's screen is not available right now. |
The agent's computer didn't answer at the start. |
4502 |
upstream_closed |
The agent's screen closed the connection. |
The agent's computer closed the stream during the session. |
4008 |
time_limit |
The screen session reached its time limit. |
maxSeconds passed. |
4000 |
control_taken |
Someone else took control of this computer. |
Control only: another Take Control started on the agent, from your app or the Wiro panel. |
4009 |
idle |
Control was handed back after a while without keyboard or mouse input. |
Control only: no key or pointer event for idleSeconds. |
4010 |
bad_input |
The browser sent input the screen does not accept. |
The page sent an RFB message the screen doesn't take (see Drawing the screen with noVNC). |
4011 |
input_rate |
Too much keyboard and mouse input arrived at once. |
Control only: more than 500 key and pointer events a second, beyond a short burst. |
4012 |
access_lost |
You can no longer control this agent's computer. |
Control only: Take Control stopped applying to your key's owner on this agent, for example because it moved into a team. |
4013 |
capturing |
The agent is capturing its screen right now. Try again in a minute. |
Control only: a capture began just as control was starting. |
1001 |
error |
The screen connection failed. |
The browser stopped answering the server's pings. |
1011 |
error |
The screen connection failed. |
The session could not start on the server. |
Your code goes by reason first and the close code second, never by message: the sentences can change. You can show message as it is, or your own words. A connection that drops without a screen_end reaches the page as 1006, or 1001 when the server goes away.
Drawing the screen with noVNC
Use noVNC 1.7.0, exactly that version: https://cdn.jsdelivr.net/npm/@novnc/novnc@1.7.0/core/rfb.js, an ES module under the MPL-2.0 license, or a copy of that release served from your own site. A control session takes only the messages noVNC 1.7.0 sends with the settings below, and another version can send one it refuses, which ends control with 4010. noVNC needs a secure context: serve the page over HTTPS, or from localhost while you build.
The page owns the socket, and noVNC never gets wsUrl: the first message must be your screen_start, the text frames are for your page, and the close code tells your page why a session ended. Hand noVNC a small channel object instead of the URL, one that passes it only the binary frames (ScreenChannel in the example), and create the RFB object only once screen_ready has come.
| Setting | Value | Why |
|---|---|---|
shared (a constructor option) |
true |
Other people may be watching the same screen. |
viewOnly |
true to watch, false in control |
A view sends no input. |
resizeSession |
false |
Required. The agent's screen keeps its size, and a resize request in control ends it with 4010. |
scaleViewport |
true |
Fits the screen into your element. Don't scale the canvas with a CSS transform: noVNC would then send the pointer to the wrong spot. |
clipViewport |
false |
The whole screen stays in view. |
qualityLevel, compressionLevel |
6, 2 |
The values the Wiro panel uses. |
focusOnClick |
true in control only |
A click on the screen gives it the keyboard. |
Keep to these rules too:
- No clipboard. The agent's clipboard is closed both ways. Don't offer copy or paste, and don't call
clipboardPasteFrom, which is dropped. To put text on the agent's screen, type it as keys withrfb.sendKey, paced: the Wiro panel sends 200 key events a second, a press and a release for each character. - No power actions or resizing. Don't call
machineShutdown,machineRebootormachineReset, and keepresizeSessionoff. Those messages end the session with4010. - Human speed. More than 500 key and pointer events a second, beyond a short burst, ends control with
4011. - A way out of the screen. In control, noVNC takes every key, Tab and Esc included, so a keyboard user can't leave the screen. Give them a way out: the example, like the Wiro panel, moves focus to Hand Back when Esc is pressed twice quickly, and the first Esc still reaches the agent.
- Touch screens. noVNC turns taps and drags into clicks and drags. A phone's keyboard doesn't open for the screen: to let people type there, add a text field of your own and send what they type with
rfb.sendKey, paced as above. - No blank flash. noVNC removes its canvas when a session ends. To keep the picture while you switch between watching and control, show a copy of the last frame (
rfb.toDataURL()) until the next session draws.
Take Control and Hand Back
Take Control is a new session on a new socket, not a switch on the open one:
- Offer Take Control only while a view is live and
canControlistrue. Ask the person first, for example: "Take control of the agent's computer? Control lasts up to 15 minutes. The agent's browser and desktop tools pause until you hand back." - Your backend calls
ScreenStartwith"control": true. Keep the view open meanwhile: if the start is refused, the view stays as it was and you showerrors[0].message. - Once you have the ticket, close the view's socket and open a new one with the control ticket. Its
screen_readysays"control": true, withmaxSecondsandidleSeconds. - Create noVNC with
viewOnly: falseandfocusOnClick: true, give the screen the focus, and show that the person has control, with the time left frommaxSeconds. - Hand Back closes the control socket with code
1000, which gives control back to the agent at once, then gets a view ticket and opens a view.
{ "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "control": true }
{
"result": true,
"errors": [],
"wsUrl": "wss://socket.wiro.ai/v1/AgentRealtime/Screen",
"screenToken": "<one-time screen ticket>",
"control": true,
"canControl": true,
"maxSeconds": 900,
"idleSeconds": 120
}
One person has control at a time: a new Take Control on the agent, from any of your users or from the Wiro panel, ends the current one with 4000 and control_taken. While control lasts, the agent's browser and desktop tools pause in every chat of the agent, and the agent says it will go on once control is handed back. When control ends, the tools work again at once, and each chat whose browser or desktop step was refused gets a note before its next turn (see While You Have Control). Whatever the person signed in to stays in the agent's browser, for every chat of the agent.
The idle warning
Control ends after idleSeconds (120) without a key press, click, touch or mouse movement that reaches the agent; changes on the screen itself don't count. Warn the person before that:
- Note the time when
screen_readycomes, and again whenever the page sends a key or pointer event: an RFB message of type 4, 5 or 255. The example'sScreenChannelcallsonInputfor each. - Every second, work out
left = idleSeconds - (now - lastInputAt) / 1000. Whileleftis 30 seconds or less (or half ofidleSeconds, when that is shorter), show a countdown, for example "Control hands back in 0:25 without input. Move the mouse, tap or type to keep it." - At
idleSecondsthe server ends control with4009andidle. Open a view again, as after every end of control.
What to show when a screen ends
Read the screen_end reason first and the close code second:
| End | What to do |
|---|---|
agent_stopped, 4004 |
Close the screen and hide the button until the agent runs again. |
screen_off (4003) |
Close the screen and hide the button: the screen setting is off. Ask ScreenInfo again later. |
control_taken, 4000, in control |
Open a view, with a note such as "Control was taken somewhere else. You're watching again." |
idle, bad_input, input_rate, access_lost, capturing (4009 to 4013), in control |
Open a view and show message. After access_lost, hide Take Control until a view's ScreenStart says canControl: true again. |
| Any of those ending a view | Say the screen stopped, and offer Reconnect. |
time_limit, 4008 |
"This session reached its time limit", with Reconnect. |
4001 |
"The connection expired", with Reconnect. |
too_many_viewers, 4029 |
"Too many people are watching", with Reconnect a little later. |
upstream_closed, unavailable (4502) |
The agent's desktop closed the connection or didn't answer: offer Reconnect. |
1001 or 1006 with no screen_end |
The connection dropped. Get a fresh ticket and connect again once by yourself, in the same mode, then offer Reconnect. |
error, 1011, anything else |
"The screen stopped", with Reconnect. |
After control ends, by Hand Back or by the server, always open a view, never control. Reconnect opens a view too. A control session your page connects again within 2 minutes after its connection dropped is a reconnect and doesn't count toward the agent's 6 Take Control starts an hour.
A complete example
The two files below run as they are. server.mjs is your backend: Node.js 18 or later, with no packages to install. It keeps your API key, signs requests for signature-based projects, asks ScreenInfo and ScreenStart, and gives the page only what it needs. screen.html opens the screen, takes control, hands back, warns before the idle end and handles every end above. Put both in one folder, start the server with your key and the agent's guid, and open http://localhost:3000. Replace currentUser, mayWatch and mayControl with your own sign-in and rules.
WIRO_API_KEY=YOUR_API_KEY WIRO_API_SECRET=YOUR_API_SECRET AGENT_GUID=f8e7d6c5-b4a3-2190-fedc-ba0987654321 node server.mjs
Leave WIRO_API_SECRET out for a project that uses API key only authentication.
server.mjs:
// server.mjs: your backend. It keeps the API key and hands the page only screen tickets.
// Run: WIRO_API_KEY=... WIRO_API_SECRET=... AGENT_GUID=... node server.mjs
// then open http://localhost:3000 (Node.js 18 or later, no packages to install).
import { createServer } from "node:http";
import { createHmac } from "node:crypto";
import { readFile } from "node:fs/promises";
const WIRO = "https://api.wiro.ai/v1";
const { WIRO_API_KEY, WIRO_API_SECRET = "", AGENT_GUID, PORT = "3000" } = process.env;
// Your own sign-in and rules go here. Wiro gives your key a ticket whichever of
// your users it is for, so this is where you decide who may watch the agent and
// who may take control of it.
function currentUser(req) {
return { id: "demo-user" };
}
function mayWatch(user, agentGuid) {
return agentGuid === AGENT_GUID;
}
function mayControl(user, agentGuid) {
return mayWatch(user, agentGuid);
}
async function wiro(path, body) {
const headers = { "Content-Type": "application/json", "x-api-key": WIRO_API_KEY };
if (WIRO_API_SECRET) {
// Signature-based projects: HMAC-SHA256 of secret + nonce, keyed with the API key.
const nonce = String(Date.now());
headers["x-nonce"] = nonce;
headers["x-signature"] = createHmac("sha256", WIRO_API_KEY).update(WIRO_API_SECRET + nonce).digest("hex");
}
const res = await fetch(WIRO + path, { method: "POST", headers, body: JSON.stringify(body) });
return res.json();
}
function send(res, status, data) {
res.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store" });
res.end(JSON.stringify(data));
}
const refused = (message) => ({ result: false, errors: [{ code: 0, message }] });
createServer(async (req, res) => {
try {
if (req.method === "GET" && (req.url === "/" || req.url === "/screen.html")) {
res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
return res.end(await readFile(new URL("./screen.html", import.meta.url)));
}
if (req.method !== "POST") return send(res, 404, refused("Not found."));
let raw = "";
for await (const chunk of req) raw += chunk;
const body = raw ? JSON.parse(raw) : {};
const user = currentUser(req);
const agent = AGENT_GUID;
if (!mayWatch(user, agent)) return send(res, 403, refused("You can't view this screen."));
if (req.url === "/api/screen/info") {
const info = await wiro("/UserAgent/Realtime/ScreenInfo", { useragentguid: agent });
return send(res, 200, {
available: info.available === true,
canControl: info.canControl === true && mayControl(user, agent),
reason: info.reason ?? null,
});
}
if (req.url === "/api/screen/start") {
const control = body.control === true;
if (control && !mayControl(user, agent)) return send(res, 403, refused("You can't take control of this screen."));
const t = await wiro("/UserAgent/Realtime/ScreenStart", { useragentguid: agent, control });
if (t.result !== true) {
return send(res, 200, { result: false, errors: (t.errors || []).map((e) => ({ code: e.code, message: e.message })) });
}
// Your own record: Wiro's activity log names your key's owner, never this user.
console.log(new Date().toISOString(), control ? "control" : "view", "ticket for", user.id);
return send(res, 200, {
result: true,
wsUrl: t.wsUrl,
screenToken: t.screenToken,
control: t.control,
canControl: t.canControl === true && mayControl(user, agent),
maxSeconds: t.maxSeconds,
idleSeconds: t.idleSeconds,
});
}
send(res, 404, refused("Not found."));
} catch (e) {
send(res, 500, refused("The screen could not be started. Try again."));
}
}).listen(Number(PORT), () => console.log("Open http://localhost:" + PORT));
screen.html, in the same folder:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Agent screen</title>
<style>
body { font: 15px/1.5 system-ui, sans-serif; margin: 24px; }
#bar { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; margin-bottom: 12px; }
#screen { width: 100%; max-width: 960px; aspect-ratio: 16 / 9; background: #1d1d1f; overflow: hidden; }
#screen.control { outline: 3px solid #f5a524; }
[hidden] { display: none !important; }
</style>
</head>
<body>
<div id="bar">
<button id="open" disabled>Screen</button>
<button id="take" hidden>Take Control</button>
<button id="back" hidden>Hand Back</button>
<button id="close" hidden>Close</button>
<span id="status"></span>
</div>
<div id="screen"></div>
<p id="notice" role="status"></p>
<p id="idle"></p>
<script type="module">
// noVNC 1.7.0 exactly: a control session accepts only what this version sends.
import RFB from "https://cdn.jsdelivr.net/npm/@novnc/novnc@1.7.0/core/rfb.js";
const $ = (id) => document.getElementById(id);
const screenEl = $("screen");
// Your backend (server.mjs). The page never sees the API key.
async function api(path, body = {}) {
try {
const res = await fetch(path, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });
return await res.json();
} catch {
return { result: false, errors: [{ code: 0, message: "Check your connection, then try again." }] };
}
}
// What noVNC reads instead of the socket: binary frames only. One class with no
// parent, because noVNC looks for send, close, binaryType, onerror, onmessage,
// onopen, protocol and readyState on the object and on its own class.
class ScreenChannel {
binaryType = "arraybuffer";
onopen = null;
onerror = null;
onclose = null;
onInput = null; // called for every key or pointer event that goes up
#ws;
#receive = null;
#held = [];
#ended = false;
#queued = false;
constructor(ws) {
this.#ws = ws;
}
get readyState() {
return this.#ended ? WebSocket.CLOSED : this.#ws.readyState;
}
get protocol() {
return this.#ws.protocol;
}
get onmessage() {
return this.#receive;
}
set onmessage(handler) {
this.#receive = handler;
if (handler && this.#held.length) this.#flush();
}
send(data) {
if (this.#ended) return;
this.#ws.send(data);
const bytes = ArrayBuffer.isView(data) ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength) : new Uint8Array(data);
// RFB KeyEvent (4), PointerEvent (5) and QEMU extended KeyEvent (255): what counts as input.
if (bytes.length && (bytes[0] === 4 || bytes[0] === 5 || bytes[0] === 255)) this.onInput?.();
}
close() {
if (!this.#ended) this.#ws.close(1000);
}
push(buffer) {
if (this.#ended) return;
if (this.#receive && !this.#held.length) return this.#receive({ data: buffer });
this.#held.push(buffer);
if (this.#receive) this.#flush();
}
closed(event) {
if (this.#ended) return;
this.#ended = true;
this.#held = [];
this.onclose?.(event);
}
// A microtask: noVNC sets onmessage inside its constructor, before it reads readyState.
#flush() {
if (this.#queued) return;
this.#queued = true;
queueMicrotask(() => {
this.#queued = false;
while (!this.#ended && this.#receive && this.#held.length) this.#receive({ data: this.#held.shift() });
});
}
}
// One session, a view or control, on one ticket from ScreenStart.
function openScreen(ticket, { onReady, onLive, onInput, onEnd }) {
const ws = new WebSocket(ticket.wsUrl); // as given: the ticket never goes in the URL
ws.binaryType = "arraybuffer";
const channel = new ScreenChannel(ws);
channel.onInput = onInput;
let rfb = null;
let rfbDone = false;
let ready = null;
let live = false;
let done = false;
let end = { reason: "", message: "" };
const watchdog = setTimeout(() => { if (!live) finish(0); }, 20000);
ws.onopen = () => ws.send(JSON.stringify({ type: "screen_start", screenToken: ticket.screenToken }));
ws.onmessage = (event) => {
if (typeof event.data !== "string") return channel.push(event.data);
let msg;
try { msg = JSON.parse(event.data); } catch { return; }
if (msg.type === "screen_ready" && !ready) {
ready = msg;
const control = msg.control === true;
onReady?.(msg);
rfb = new RFB(screenEl, channel, { shared: true }); // security type None: no credentials
rfb.viewOnly = !control;
rfb.focusOnClick = control;
rfb.resizeSession = false; // required: the agent's screen keeps its size
rfb.scaleViewport = true;
rfb.clipViewport = false;
rfb.qualityLevel = 6;
rfb.compressionLevel = 2;
rfb.addEventListener("connect", () => {
live = true;
clearTimeout(watchdog);
if (control) rfb.focus({ preventScroll: true });
onLive?.(msg);
});
rfb.addEventListener("disconnect", () => { rfbDone = true; finish(0); });
rfb.addEventListener("credentialsrequired", () => finish(0));
rfb.addEventListener("securityfailure", () => finish(0));
} else if (msg.type === "screen_end") {
end = { reason: String(msg.reason || "error"), message: String(msg.message || "") };
}
};
ws.onclose = (event) => finish(event.code);
// code: the socket's close code, 0 when this page gave up, -1 for stop().
function finish(code) {
if (done) return;
done = true;
clearTimeout(watchdog);
ws.onopen = ws.onmessage = ws.onclose = null;
if (rfb && !rfbDone) {
rfbDone = true;
try { rfb.disconnect(); } catch {}
}
channel.closed({ code: code > 0 ? code : 1000, reason: "", wasClean: true });
if (ws.readyState === WebSocket.CONNECTING || ws.readyState === WebSocket.OPEN) ws.close(1000);
if (code !== -1) onEnd?.({ code, ...end, control: ready?.control === true, ready: !!ready });
}
return { stop: () => finish(-1) };
}
// The page: one session at a time.
let current = null; // { control, live, liveAt, handle }
let canControl = false;
let retried = false;
let idleSeconds = 120;
let lastInputAt = 0;
let idleTimer = null;
let infoTimer = null;
function render() {
const open = current !== null;
$("open").hidden = open;
$("close").hidden = !open;
$("take").hidden = !(open && !current.control && current.live && canControl);
$("back").hidden = !(open && current.control);
screenEl.classList.toggle("control", open && current.control);
$("status").textContent = !open ? "" : !current.live ? "Connecting" : current.control ? "You have control" : "View only";
}
function say(text, reconnect = false) {
$("notice").textContent = text || "";
$("open").textContent = reconnect ? "Reconnect" : "Screen";
}
// No Screen for now: the button stays off, and ScreenInfo is asked again in a
// minute, unless the answer can't change by itself.
function noScreen(text, askAgain = true) {
$("open").disabled = true;
say(text);
clearTimeout(infoTimer);
if (askAgain) infoTimer = setTimeout(checkInfo, 60000);
}
function connect(ticket) {
const session = { control: ticket.control === true, live: false, liveAt: 0, handle: null };
current = session;
session.handle = openScreen(ticket, {
onReady: (ready) => {
if (session.control) {
idleSeconds = ready.idleSeconds || ticket.idleSeconds || 120;
lastInputAt = Date.now(); // the idle count starts here
}
},
onLive: () => {
if (current !== session) return;
session.live = true;
session.liveAt = Date.now();
if (session.control) startIdleWarning();
render();
},
onInput: () => { lastInputAt = Date.now(); },
onEnd: (end) => { if (current === session) ended(session, end); },
});
render();
}
async function openView(note = "") {
const t = await api("/api/screen/start", { control: false });
if (t.result !== true) {
current = null;
render();
const error = t.errors?.[0] || {};
// The screen setting is off (94) or the agent isn't running (95): no Screen for now.
if (error.code === 94 || error.code === 95) return noScreen(error.message);
// Your key can't open this agent's Screen (96, 97).
if (error.code === 96 || error.code === 97) return noScreen(error.message, false);
return say(error.message || "The screen couldn't open. Try again in a moment.", true);
}
canControl = t.canControl === true;
say(note);
connect(t);
}
async function takeControl() {
const view = current;
if (!view || view.control || !view.live || !canControl) return;
if (!confirm("Take control of the agent's computer?\n\nControl lasts up to 15 minutes. The agent's browser and desktop tools pause until you hand back.")) return;
$("take").disabled = true;
const t = await api("/api/screen/start", { control: true }); // the view stays open meanwhile
$("take").disabled = false;
if (current !== view) return;
if (t.result !== true) return say(t.errors?.[0]?.message || "You can't take control right now.");
retried = false;
say("");
view.handle.stop(); // close the view only once control is granted
connect(t);
}
async function handBack() {
const control = current;
if (!control || !control.control) return;
current = null;
stopIdleWarning();
control.handle.stop(); // first, so the agent's tools work again at once
retried = false;
await openView();
}
function closeScreen() {
const session = current;
current = null;
stopIdleWarning();
session?.handle.stop();
say("");
render();
}
// How a session ended: read screen_end's reason first, then the close code.
const CONTROL_ENDS = { control_taken: 4000, idle: 4009, bad_input: 4010, input_rate: 4011, access_lost: 4012, capturing: 4013 };
async function ended(session, { code, reason, message, control, ready }) {
current = null;
stopIdleWarning();
render();
if (session.liveAt && Date.now() - session.liveAt >= 30000) retried = false;
if (reason === "agent_stopped" || code === 4004) return noScreen("The agent stopped. Its screen comes back once it runs again.");
if (reason === "screen_off" || code === 4003) return noScreen("The screen was turned off for this agent.");
const controlEnd = Object.entries(CONTROL_ENDS).find(([r, c]) => reason === r || code === c);
if (controlEnd && control) {
if (controlEnd[0] === "access_lost") canControl = false; // until a view's ScreenStart says otherwise
const note = controlEnd[0] === "control_taken" ? "Control was taken somewhere else. You're watching again." : message;
return openView(note); // after control ends, always a view
}
if (!reason && (code === 1001 || code === 1006) && !retried) {
retried = true; // one retry with a fresh ticket, in the same mode
if (!control) return openView();
const t = await api("/api/screen/start", { control: true });
return t.result === true ? connect(t) : openView(t.errors?.[0]?.message || "");
}
if (reason === "time_limit" || code === 4008) return say("This session reached its time limit.", true);
if (code === 4001) return say("The connection expired.", true);
if (code === 4029) return say("Too many people are watching. Try again in a moment.", true);
if (code === 4502) return say(ready ? "The agent's desktop closed the connection." : "This agent's desktop isn't available right now.", true);
say(message || "The screen stopped.", true);
}
// Control hands back after idleSeconds without a key or pointer event: count down first.
function startIdleWarning() {
stopIdleWarning();
idleTimer = setInterval(() => {
const left = idleSeconds - (Date.now() - lastInputAt) / 1000;
const warn = left <= Math.min(30, idleSeconds / 2) && left > -5;
const s = Math.max(0, Math.ceil(left));
const time = Math.floor(s / 60) + ":" + String(s % 60).padStart(2, "0");
$("idle").textContent = warn ? "Control hands back in " + time + " without input. Move the mouse, tap or type to keep it." : "";
}, 1000);
}
function stopIdleWarning() {
clearInterval(idleTimer);
idleTimer = null;
$("idle").textContent = "";
}
// In control noVNC takes every key, Tab and Esc included. Esc twice quickly
// moves focus to Hand Back, so keyboard users can leave the screen. The first
// Esc still reaches the agent.
let lastEsc = 0;
document.addEventListener("keydown", (event) => {
if (event.key !== "Escape" || !current?.control || !screenEl.contains(document.activeElement)) return;
if (event.timeStamp - lastEsc < 600) {
event.preventDefault();
event.stopPropagation();
lastEsc = 0;
$("back").focus();
} else {
lastEsc = event.timeStamp;
}
}, true);
$("open").onclick = () => { retried = false; say(""); openView(); };
$("take").onclick = takeControl;
$("back").onclick = handBack;
$("close").onclick = closeScreen;
// Whether there is a Screen to show: asked first, and again after noScreen.
async function checkInfo() {
clearTimeout(infoTimer);
const info = await api("/api/screen/info");
if (current) return; // a screen opened meanwhile
canControl = info.canControl === true;
if (info.available === true) {
$("open").disabled = false;
say("");
} else {
const text = info.reason === "not_running" ? "The agent isn't running." : "The screen isn't available for this agent.";
noScreen(text, info.reason !== "not_allowed" && info.reason !== "private_team");
}
render();
}
checkInfo();
</script>
</body>
</html>
Screen limits for your key
Your key owner's API keys count as one person, apart from that person's own sessions in the Wiro panel, so these limits cover all of your users together:
| Limit | Value |
|---|---|
| Screens open on one agent at once, watching and control together, from your app and the Wiro panel | 4 |
| One watching session | 30 minutes (maxSeconds 1800) |
| One Take Control session | 15 minutes (maxSeconds 900) |
| Control without a key or pointer event | 2 minutes (idleSeconds 120) |
| Key and pointer events in control | 500 a second, beyond a short burst |
| Take Control starts on one agent, by everyone | 6 in any hour |
| Screens started on one agent with the API keys of your key's owner | 30 in 10 minutes |
- A control start with your key while a control session opened with your key owner's API keys is still open on the agent, or within 2 minutes after one's connection dropped, is a reconnect and doesn't count toward the 6 an hour. That covers all of your users: one of them taking control within 2 minutes after another one's control connection dropped is a reconnect too. The owner's own control sessions in the Wiro panel have a window of their own and don't make it one. After Hand Back, the idle end, the time limit or any other end, the next start counts.
- Every ticket counts toward the 30 in 10 minutes, and so does a start refused for too many viewers, a capture, a computer that doesn't answer or the hourly limit. Past that,
ScreenStartanswers HTTP 429 withToo many screen sessions started. Try again in a few minutes.until the 10 minutes are over.
Screen rows in the activity log
Every screen your key opens adds the Screen rows to the agent's activity log, named after your key's owner, the same rows the Wiro panel writes. Read them with POST /UserAgent/Logs and your API key:
{
"ts": "2026-11-20T18:03:05.000Z",
"kind": "AGENT_SCREEN_CONTROLLED",
"title": "Took control of the agent's screen (API key \"Acme App\")",
"ok": true,
"summary": { "project": "Acme App" },
"userUuid": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"user": {
"uuid": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"username": "ada",
"avatar": "",
"avatarinitials": "AL"
}
}
kind |
When | With your key |
|---|---|---|
AGENT_SCREEN_VIEWED |
ScreenStart issued a view ticket. |
At most one row an hour on each agent for each project's key, for all of your users together, apart from the rows the owner's own sessions in the Wiro panel write. The title ends with (API key "<project name>") and summary holds { "project": "<project name>" }, or the title ends with (via API key) for a personal project's key on a team agent. |
AGENT_SCREEN_CONTROLLED |
ScreenStart issued a Take Control ticket. |
At most one row every 10 minutes on each agent for each project's key, with the same title ending and summary. |
AGENT_SCREEN_CONTROL_ENDED |
A control session that started has ended. | One row for every session, with summary: { seconds, reason }, named after your key's owner; the title ends with (via API key). |
The rows never say which of your users watched or took control. Keep that in your own records, for example a line for every ticket your backend hands out, as server.mjs does.
Security Rules
- Keys never go into chat messages. Collect keys, app keys and tokens in your own forms and send them with
SetupCardApplyvaluesorCredentialUpsert. The agent never sees them. While setup from chat is on for a message, Wiro takes clear keys out of it before it is stored or reaches the agent: each one reads[key removed]in the stored text and in the text the agent gets, and Send answerscontentmasked: truewith that text incontent. A key pasted as the reply while akeyconnect card is the onlyconnectcard waiting can be saved to its connector, when that connector is on the agent or a pendingaddcard on the same reply brings it, and is then stored as[key saved to <Connector title>]. This runs only while setup from chat is on for the message, so treat it as a safety net, never as a way to send keys. See Keys in chat. - Saved secrets read as a mask.
UserAgent/Detailshows every savedpasswordorfileinput-base64field as"••••••••", for every caller, and returns no OAuth token and no OAuth app key at all. Show "Saved" instead of a value, and let people replace a secret, not read it. - The mask sent back keeps the saved value. A field sent to
CredentialUpsertas"••••••••"isn't written, so a form saved as Detail showed it changes only the fields edited. In a list sent whole, such asfirebase.accounts, an entry whose secret is the mask keeps the secret of the saved entry with the same values in its other fields. When no single saved entry matches, because those values changed or two saved entries share them, the request is refused and nothing is saved: send that entry's secret again. See Field-level write rules. - Which service account a key file is. A saved Google service account file (Google Drive, Google Play and Google Calendar's
serviceaccountjson, and each Firebase account's) reads as the mask too. So that you can show which account it is, the address people share a Drive folder, the Play Console or a calendar with, the agent's owner and team admins get_service_account_emailin that connector's group ofcredentials, inUserAgent/Detailand in theDeployandUpdateanswers:"_service_account_email": { "serviceaccountjson": "agent@acme-project.iam.gserviceaccount.com" }, or for Firebase"_service_account_email": { "accounts": [{ "serviceaccountjson": "push@acme-project.iam.gserviceaccount.com" }] }, one item per account in the list's order. A value is""when nothing is saved or the file doesn't read as a service account key. Only the account's address leaves the file. Leave the key out of what you send back: field names that start with_are refused. - Approvals act with your key's rights. Show Apply only to the people allowed to change the agent, hold back everyone else's typed approvals (see Typed replies), check that a
messageguidbelongs to the session of the person who clicked, and usechatsetup: "off"for agents whose users must not change them. - Your key's owner stays in your backend. Message rows carry your key owner's
uuidanduser(name, email, avatar), and cards itsuuid, whoever of your users wrote: show your own names instead. - Your API key stays on your server. Your app calls your backend, and your backend calls Wiro. A browser holds at most the
agenttokenandsessiontokenof its own person's chats, and the one-timescreenTokenof a screen you chose to show that person. - The Screen shows the whole agent. An agent's Screen shows the work of all of its chats, and Take Control reaches every site its browser is signed in to. Ask for a ticket only for the users you allow to see that agent, and for
control: trueonly for the users you allow to use it. Turn the Screen off withscreen: "off"on agents whose users must not see each other's work (see Decide who sees it). - A screen ticket is for one socket. Each
screenTokenworks once, within 60 seconds: hand it to one page, keep it out of URLs and logs, and get a new one for every socket. - Sign-ins come back to your page. The
redirecturlreceives only status parameters and the accounts to pick, never a token or a secret. A callback that can't be matched to a sign-in ends on the API's own neutral page instead (see Return codes).
Worked Examples
The first four examples start with a person's message in your chat and end with the change applied, and the fifth shows the agent's Screen with Take Control. Each one starts from the same agent as it was before any of them: Chat Markdown Reporting is on, and none of the examples' connectors are. The ids are the same throughout: the agent f8e7d6c5-b4a3-2190-fedc-ba0987654321, and 5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f, your key owner's account, on every message and card. The agent's own words vary from turn to turn.
Google Analytics 4 with your own app keys
1. The person asks. Message/Send with { "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "sessionkey": "customer-42", "message": "Can you report our website traffic every Monday?" } answers { "result": true, "errors": [], "messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234", "agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb", "status": "agent_queue" }.
2. The reply ends. Message/Detail with { "messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234" }:
{
"result": true,
"errors": [],
"data": {
"guid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"uuid": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"agenttoken": "aB3xK9mR2pLqWzVn7tYhCd5sFgJkNb",
"user": {
"uuid": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"username": "ada",
"avatar": "",
"avatarinitials": "AL"
},
"sessionkey": "customer-42",
"content": "Can you report our website traffic every Monday?",
"response": "I can do that once Google Analytics 4 is on and connected. Approve the card below and connect your Google Analytics account.",
"debugoutput": "I can do that once Google Analytics 4 is on and connected. Approve the card below and connect your Google Analytics account.",
"timeline": [
{
"blockid": "c0:i0",
"callindex": 0,
"contentindex": 0,
"type": "answer",
"text": "I can do that once Google Analytics 4 is on and connected. Approve the card below and connect your Google Analytics account.",
"phase": "end",
"version": 4,
"startedat": 1794654805,
"updatedat": 1794654811
},
{
"blockid": "s:71xb9zrcd1sb",
"type": "setup",
"callindex": 1000000,
"contentindex": 0,
"text": null,
"setup": {
"v": 1,
"id": "71xb9zrcd1sb",
"kind": "add",
"key": "int-ga4-analytics",
"needs": [{ "connector": "ga4", "title": "Google Analytics 4", "mode": "appkeys" }],
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811
},
"phase": "end",
"version": 1,
"startedat": 1794654811,
"updatedat": 1794654811
},
{
"blockid": "s:ljehd9inazm4",
"type": "setup",
"callindex": 1000000,
"contentindex": 1,
"text": null,
"setup": {
"v": 1,
"id": "ljehd9inazm4",
"kind": "connect",
"connector": "ga4",
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811
},
"phase": "end",
"version": 1,
"startedat": 1794654811,
"updatedat": 1794654811,
"next": [{ "connector": "ga4", "title": "Google Analytics 4", "mode": "appkeys" }]
}
],
"status": "agent_end",
"metadata": {
"type": "progressGenerate",
"task": "Generate",
"speed": "21.0",
"speedType": "words/s",
"elapsedTime": "6.2s",
"tokenCount": 38,
"wordCount": 23
},
"attachments": [],
"deletestatus": 0,
"createdat": 1794654804,
"startedat": 1794654805,
"endedat": 1794654811,
"inputtokens": 4210,
"outputtokens": 160,
"cachereadtokens": 3072,
"cachewritetokens": 0,
"totaltokens": 7442,
"model": "openai/gpt-5.6-sol",
"tokencost": 4,
"processedms": 6200
}
}
The row's uuid and user are your key owner's, whoever of your users wrote the message: show your own name for the sender. The fields of the row are described in Message/Detail.
3. Your app shows one card, "Add Google Analytics 4", with a "Connect Google Analytics 4" step: the Client ID and Client Secret fields and the redirect URI from OAuthStatus, and an Add button that waits for the connection. The connect card is drawn inside the add card, not on its own.
4. The person connects. Your backend runs the calls of Own app keys, compact here:
OAuthStatus { "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "credentialkey": "ga4" }
-> { "result": true, "errors": [], "connected": false, "accounts": [], "connectedat": "", "tokenexpiresat": "", "authmethod": "", "redirecturi": "https://api.wiro.ai/v1/UserAgentOAuth/GA4Callback", "appkeyssaved": false, "tokensaved": false }
CredentialUpsert { "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "fields": [{ "credentialkey": "ga4", "fieldname": "clientid", "fieldvalue": "1234567890-abc.apps.googleusercontent.com" }, { "credentialkey": "ga4", "fieldname": "clientsecret", "fieldvalue": "GOCSPX-THE_CLIENT_SECRET" }, { "credentialkey": "ga4", "fieldname": "authmethod", "fieldvalue": "own" }] }
-> { "result": true, "applied": 3, "errors": [] }
OAuthConnect { "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "credentialkey": "ga4", "authmethod": "own", "redirecturl": "https://app.example.com/connect/done?ref=conn_8812" }
-> { "result": true, "errors": [], "authorizeUrl": "https://accounts.google.com/o/oauth2/v2/auth?...", "flowid": "9d2c41e07ab35f8e6c1d0b9a87f6e5d4" }
(browser) Google account chooser and consent, then back to /connect/done?ref=conn_8812&ga4_connected=true&ga4_properties=[...]
OAuthStatus { "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "credentialkey": "ga4" }
-> { ..., "flow": { "flowid": "9d2c41e07ab35f8e6c1d0b9a87f6e5d4", "mine": true, "mode": "own", "status": "candidates", ... }, "candidates": [{ "id": "123456789", "name": "Acme Web" }, { "id": "987654321", "name": "Acme App" }] }
SetPickerAccounts { "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "credentialkey": "ga4", "flowid": "9d2c41e07ab35f8e6c1d0b9a87f6e5d4", "accountids": ["123456789"] }
-> { "result": true, "errors": [], "accounts": [{ "id": "123456789", "name": "Acme Web" }], "restart": "none" }
5. The person presses Add. SetupCardApply with { "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234", "cardid": "71xb9zrcd1sb", "action": "apply", "signin": true } answers as shown in step 8: both cards applied, summary Google Analytics 4 added. Google Analytics 4 connected. and restarting: true.
6. The agent restarts. Your app shows "Restarting" and polls UserAgent/Detail until status is 4. The person then asks again, and the agent proposes the scheduled task: a schedule card that your Apply button applies with SetupCardApply, as in Applying and Dismissing. Each Monday's report then comes as a message added between turns, in the agent's most recent session: see Load a conversation.
If the person typed yes instead of pressing Add, the first yes gets the listing and the second applies the add card alone; see setupresult and next. Its next names the connect card: after the connection, apply it with { "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234", "cardid": "ljehd9inazm4", "action": "apply" }. Applied before the connection, it answers:
{
"result": false,
"errors": [{ "code": 0, "message": "Google Analytics 4 is not connected yet. Finish the sign-in on the card first.", "time": 1794654845 }],
"setup": {
"v": 1,
"id": "ljehd9inazm4",
"kind": "connect",
"connector": "ga4",
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811
},
"restarting": false,
"summary": "",
"errorcode": "not_connected",
"next": [
{
"connector": "ga4",
"title": "Google Analytics 4",
"mode": "appkeys",
"cardid": "ljehd9inazm4",
"messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234"
}
]
}
and after it:
{
"result": true,
"errors": [],
"setup": {
"v": 1,
"id": "ljehd9inazm4",
"kind": "connect",
"connector": "ga4",
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811,
"status": "applied",
"actedat": 1794655020,
"actedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f"
},
"restarting": false,
"summary": "Google Analytics 4 connected"
}
That way restarts the agent twice: once for the add card, and once when the connection completes.
Facebook Pages with a token
1. The person asks "Post our weekly offer on our Facebook Page." The reply's timeline ends with two setup blocks:
[
{
"blockid": "s:z9n62skddnwz",
"type": "setup",
"callindex": 1000000,
"contentindex": 0,
"text": null,
"setup": {
"v": 1,
"id": "z9n62skddnwz",
"kind": "add",
"key": "int-facebookpage-post",
"with": ["util-anti-ai-human-copy", "util-social-posting-common"],
"needs": [{ "connector": "facebook-pages", "title": "Facebook", "mode": "token" }],
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811
},
"phase": "end",
"version": 1,
"startedat": 1794654811,
"updatedat": 1794654811
},
{
"blockid": "s:02e5m6mt4ktl",
"type": "setup",
"callindex": 1000000,
"contentindex": 1,
"text": null,
"setup": {
"v": 1,
"id": "02e5m6mt4ktl",
"kind": "connect",
"connector": "facebook-pages",
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811
},
"phase": "end",
"version": 1,
"startedat": 1794654811,
"updatedat": 1794654811,
"next": [{ "connector": "facebook-pages", "title": "Facebook", "mode": "token" }]
}
]
2. Your app shows "Add Facebook Page Post", "Also turns on: Anti-AI Human Copy, Social Posting Common Rules", and a "Connect Facebook" step with a System User token field. Titles come from Skills/List.
3. The person pastes the token and presses Connect:
CredentialUpsert { "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "fields": [{ "credentialkey": "facebook-pages", "fieldname": "authmethod", "fieldvalue": "api_key" }, { "credentialkey": "facebook-pages", "fieldname": "systemusertoken", "fieldvalue": "THE_SYSTEM_USER_TOKEN" }] }
-> { "result": true, "applied": 2, "errors": [] }
OAuthConnect { "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "credentialkey": "facebook-pages", "authmethod": "api_key" }
-> { "result": true, "errors": [], "flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19", "accounts": [{ "id": "1029384756", "name": "Acme" }, { "id": "5647382910", "name": "Acme Outlet" }], "account": "Acme Marketing System User", "restart": "none" }
4. The person picks the Acme Page and presses Add:
SetPickerAccounts { "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "credentialkey": "facebook-pages", "flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19", "accountids": ["1029384756"] }
-> { "result": true, "errors": [], "accounts": [{ "id": "1029384756", "name": "Acme" }], "restart": "none" }
SetupCardApply { "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "messageguid": "c3d4e5f6-a7b8-9012-cdef-345678901234", "cardid": "z9n62skddnwz", "action": "apply", "signin": true }
{
"result": true,
"errors": [],
"setup": {
"v": 1,
"id": "z9n62skddnwz",
"kind": "add",
"key": "int-facebookpage-post",
"with": ["util-anti-ai-human-copy", "util-social-posting-common"],
"needs": [{ "connector": "facebook-pages", "title": "Facebook", "mode": "token" }],
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811,
"status": "applied",
"actedat": 1794654990,
"actedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f"
},
"restarting": true,
"summary": "Facebook Page Post added. Facebook connected.",
"paired": [
{
"setup": {
"v": 1,
"id": "02e5m6mt4ktl",
"kind": "connect",
"connector": "facebook-pages",
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811,
"status": "applied",
"actedat": 1794654990,
"actedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f"
},
"result": true,
"error": null
}
]
}
Had the person pressed Add before the Pages were saved, the answer would be result: false, errorcode: "not_connected" and Facebook is not connected yet. Finish the token check on the card first., with both cards still pending and that sentence in paired[0].error.
5. The agent restarts once, and the person's next message reaches it with Facebook connected.
X with Wiro's app
1. The person asks "Post this thread on X for us." The reply holds an add card for int-twitterx-post, with with: ["util-anti-ai-human-copy", "util-social-posting-common"] and needs: [{ "connector": "twitter", "title": "Twitter / X", "mode": "signin" }], and a connect card for twitter whose block carries next: [{ "connector": "twitter", "title": "Twitter / X", "mode": "signin" }].
2. Your app shows "Add Twitter / X Post" with a "Connect Twitter / X" button. No form: X connects with Wiro's app.
3. The person presses Connect:
OAuthConnect { "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "credentialkey": "twitter", "authmethod": "wiro", "redirecturl": "https://app.example.com/connect/done?ref=conn_8813" }
-> { "result": true, "errors": [], "authorizeUrl": "https://x.com/i/oauth2/authorize?...", "flowid": "e1a2b3c4d5e6f708192a3b4c5d6e7f80" }
(browser) X consent screen, then back to /connect/done?ref=conn_8813&x_connected=true&x_username=acmeco
OAuthStatus { "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "credentialkey": "twitter" }
-> { "result": true, "errors": [], "connected": true, "accounts": [{ "id": "acmeco", "name": "acmeco" }], ..., "flow": { "flowid": "e1a2b3c4d5e6f708192a3b4c5d6e7f80", "mine": true, "mode": "wiro", "status": "connected", "account": "acmeco", "errorcode": "", "errordetail": "", "restart": "none", "expiresat": 1794655802 } }
4. The person presses Add. SetupCardApply on add card r8k2v6n4p1wa with signin: true:
{
"result": true,
"errors": [],
"setup": {
"v": 1,
"id": "r8k2v6n4p1wa",
"kind": "add",
"key": "int-twitterx-post",
"with": ["util-anti-ai-human-copy", "util-social-posting-common"],
"needs": [{ "connector": "twitter", "title": "Twitter / X", "mode": "signin" }],
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811,
"status": "applied",
"actedat": 1794655010,
"actedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f"
},
"restarting": true,
"summary": "Twitter / X Post added. Twitter / X connected.",
"paired": [
{
"setup": {
"v": 1,
"id": "t3m9x5c7b2qe",
"kind": "connect",
"connector": "twitter",
"requestedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f",
"createdat": 1794654811,
"status": "applied",
"actedat": 1794655010,
"actedby": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f"
},
"result": true,
"error": null
}
]
}
X's consent screen named Wiro's app. To show your own app there, save your X app's clientid and clientsecret with authmethod: "own", register https://api.wiro.ai/v1/UserAgentOAuth/XCallback in your X app, and start the sign-in with authmethod: "own". The cards apply the same way.
Serper Web Search with a key
1. The person asks "Search the web for our competitors' prices." The reply holds an add card q4n7s1v8b2xd for int-serper-search with needs: [{ "connector": "serper", "title": "Serper Web Search", "mode": "key" }], and a connect card h6w3k9p2m5tc for serper, whose block is the one in Block fields.
2. Your app shows "Add Serper Web Search" with one field, "Serper API Key", from Credentials/Detail, and an Add and connect button.
3. The person pastes the key and presses the button. Your backend sends the add card with values: { "apikey": "..." }; the answer, and the one for a key that is too short, are in Key. The agent restarts once and can search the web.
In a chat without cards, the same takes two replies:
Message/Send "yes"
-> response: "The agent proposes this setup change. Nothing is applied yet.\n\nCard 1: Add Serper Web Search (connector).\nStill to connect: Serper Web Search.\n\nReply with your Serper Web Search key to add Serper Web Search and connect it at once, \"yes\" to add it now and give the key later, or \"no\" to turn it down."
setupresult: { "applied": [], "dismissed": [], "failed": [], "restarting": false }
Message/Send "<the Serper API key>"
-> content: "[key saved to Serper Web Search]"
response: "✅ Applied: Serper Web Search added. Serper Web Search connected.\nYour agent is restarting to load the change. Continue in about a minute."
setupresult: { "applied": ["q4n7s1v8b2xd", "h6w3k9p2m5tc"], "dismissed": [], "failed": [], "restarting": true }
A second yes instead of the key applies the add card alone and answers Next: paste your Serper Web Search key as your reply. Send it now and it loads with this same restart., with the connect card in setupresult.next. Even here, a form is safer than the chat: send the key from it with SetupCardApply values.
The Screen with Take Control
The agent is a personal agent that your key's owner deployed with a personal project's API key, named Acme App, and it has never been in a team, so Take Control applies. Your own rules let the person in this example watch it and take control.
1. Your app asks whether there is a Screen. Your backend sends ScreenInfo { "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321" } and gets { "result": true, "errors": [], "available": true, "canControl": true, "reason": null }. The page shows a Screen button.
2. The person opens it. Your backend sends ScreenStart { "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321" }, notes the ticket against the person in your own records, and gives the page { "wsUrl": "wss://socket.wiro.ai/v1/AgentRealtime/Screen", "screenToken": "<one-time screen ticket>", "control": false, "canControl": true, "maxSeconds": 1800 }.
3. The page connects.
page -> {"type":"screen_start","screenToken":"<one-time screen ticket>"}
page <- {"type":"screen_ready","control":false,"maxSeconds":1800}
page <> binary RFB 3.8 frames: noVNC draws the agent's browser, view only
4. The person takes control. They press Take Control and confirm. Your backend sends ScreenStart { "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "control": true } and gets a control ticket with "maxSeconds": 900 and "idleSeconds": 120. The page closes the view with 1000, opens a new socket with the control ticket and gets {"type":"screen_ready","control":true,"maxSeconds":900,"idleSeconds":120}. noVNC now sends their clicks and keys, and they sign in to their store's admin site in the agent's browser. If the agent reaches for its browser in any chat meanwhile, the call is refused, and the agent says it will continue once control is handed back.
5. The person looks away. After 90 seconds without input the page shows "Control hands back in 0:30 without input. Move the mouse, tap or type to keep it." They move the mouse, and the countdown goes away.
6. They hand back. Hand Back closes the control socket with 1000. The agent's browser and desktop tools work again at once, and the sign-in stays in its browser. Your backend gets a view ticket, and the page opens the view again.
7. The activity log. The day's events from POST /UserAgent/Logs, read with your API key, hold these three rows, newest first. The view after Hand Back added no row, since one came earlier in the same hour:
[
{
"ts": "2026-11-20T18:06:47.000Z",
"kind": "AGENT_SCREEN_CONTROL_ENDED",
"title": "Control of the agent's screen ended after 3 minutes 40 seconds: handed back (via API key)",
"ok": true,
"summary": { "seconds": 220, "reason": "hand_back" },
"userUuid": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f"
},
{
"ts": "2026-11-20T18:03:05.000Z",
"kind": "AGENT_SCREEN_CONTROLLED",
"title": "Took control of the agent's screen (API key \"Acme App\")",
"ok": true,
"summary": { "project": "Acme App" },
"userUuid": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f"
},
{
"ts": "2026-11-20T18:02:11.000Z",
"kind": "AGENT_SCREEN_VIEWED",
"title": "Watched the agent's screen (API key \"Acme App\")",
"ok": true,
"summary": { "project": "Acme App" },
"userUuid": "5f0c9a2e-1b7d-4c3a-9e8f-2a6b7c8d9e0f"
}
]
Each row also carries user, your key owner's account, left out here. The rows name your key's owner, and your own record says which of your users it was.
Integration Checklist
- Your backend holds the project API key, and your app talks only to your backend. A browser holds at most the
agenttokenandsessiontokenof its own person's chats, and ascreenTokenfor each screen you chose to show that person. - One agent per customer, deployed with
useprepaid: true, andchatsetupset:"all"for setup cards in your chat,"off"for agents whose users must not change them. - Each conversation has its own
sessionkey, and you check that everymessageguida person acts on is in their session. - Message rows and cards name your key's owner: your UI shows your own names for the sender.
- Messages go out with
Message/Send; replies are followed on the WebSocket or withMessage/Detail, and loaded withMessage/History; rows added between turns arrive on the session'ssessiontoken. - Failed turns are told apart by their bracketed code, and an out-of-credits refusal by
agentbalance. - Timeline blocks are merged by
blockidand newerversion, sorted bycallindex,contentindex,blockid, and drawn bytype; unknown types and kinds are skipped. - Replies Wiro answers itself (
agenttoken: null,status: "agent_end") showresponseas plain text. - Setup cards show the right title, body and buttons for their kind and state,
addcards together with theirconnectcards. - Apply waits for the reply to finish; Apply and Dismiss call
SetupCardApply, and the card updates from the answer'ssetup(which can benull) and from laterversion2 blocks. - Each connector mode has its flow and its form fields:
key(fields asvalues),appkeys(CredentialUpsert,OAuthConnectwithown, the return page,OAuthStatus,SetPickerAccounts),token(CredentialUpsert,OAuthConnectwithapi_key,SetPickerAccounts),signin(OAuthConnectwithwiro), andpage(your settings screens). - After connecting, the
addcard is applied withsignin: true(one restart), or theconnectcard is applied. nextfrom blocks,SetupCardApplyanswers,setupresultand webhooks turns into your own Connect buttons.- Every
result: falseshows its sentence or your own words; code branches onerrorcode,flow.statusand the return codes, never on sentences. - Every restart signal (
restarting,restart,flow.restart, and the saves that answer none) shows a restarting line untilUserAgent/Detailreadsstatus: 4, and the poll stops at0,5or6; Send refusals during a restart are shown as they are. - Typed approvals and pasted keys from people who must not change the agent never reach Wiro.
- Keys never go into chat messages; secrets show as "Saved", and the mask sent back is left alone.
- Your
redirecturlpage handles<prefix>_connected=trueand<prefix>_error=<code>, inside a popup or as a full page, and a popup that never reports back is checked withOAuthStatus. - Your product decides who may watch each agent's Screen and who may take control, and agents whose users must not see each other's work have
screenset to"off". - The Screen:
ScreenInfobefore the button, a freshScreenStartfrom your backend for every socket,screen_startas the socket's first frame, and noVNC 1.7.0 created afterscreen_readyand fed only the binary frames, withresizeSessionoff, no clipboard and a way out of the keyboard in control. - Take Control opens a new socket while the view stays until it is granted; Hand Back closes it with
1000and opens a view; a countdown runs beforeidleSeconds; every end of control opens a view,screen_offandagent_stoppedclose the screen, and a dropped connection is retried once. - Your own records say which of your users got each screen ticket.
Related
- Agent Messaging: every messaging endpoint, and the full rules of Setup From Chat.
- Agent WebSocket: live events.
- Agent Webhooks: the callback payload.
- Agent Credentials & OAuth: every credential and OAuth endpoint in detail.
- Agent Overview: Deploy, Detail, UpdateSettings and restarts.
- Screen and Take Control: the agent's Screen in the Wiro panel, with its rules, limits and log rows, and the
ScreenInfoandScreenStartreference. - The integration pages, such as Google Analytics 4, Facebook Page, Twitter / X and Serper Web Search: each connector's own setup.
Agent Skills
Configure agent behavior with editable preferences, scheduled automation tasks, and skill toggles. Browse the platform's skill registry and inspect every skill's capabilities and credential requirements.
Read & write paths at a glance:
| Operation | Endpoint |
|---|---|
| Browse all skills (registry) | POST /Skills/List (public) |
| Browse communication channels and their credential schemas | POST /Skills/List → channels[] (public) |
| Inspect a single skill | POST /Skills/Detail (public) |
| Find the credential a skill needs | POST /Skills/CredentialSchema (public) |
| List the closed-set capability vocabulary | POST /Skills/Capabilities (public) |
Edit a preference skill's value or a cron's interval/enabled |
POST /UserAgent/CustomSkillUpsert |
| Rename a user-created custom skill (key + optional description) | POST /UserAgent/CustomSkillRename |
| Delete a user-created scheduled task | POST /UserAgent/CustomSkillDelete |
| Read version history of a custom skill | POST /UserAgent/CustomSkillHistory |
| Revert a custom skill to preset / a historical version | POST /UserAgent/CustomSkillRevert |
Toggle one or more integration skills (the top-level skills array, e.g. int-instagram-post) on/off |
POST /UserAgent/SkillsApply |
| Preview a skill set or a plan change without saving it | POST /UserAgent/PricingPreview |
Read responses from
POST /UserAgent/Detailexpose the composedcustomskills[]array (preference skills + non-cron user-created skills), thescheduledskills[]array (scheduled tasks), and theskills[]array as top-level fields on the useragent object.skills[]is an object array: each entry is{ name, enabled, _edited?, _user_created? }(e.g.[{ "name": "int-instagram-post", "enabled": true }, { "name": "int-wiro-aimodels", "enabled": true }]).
Skill Registry vs Custom Skills
Two concepts share the word "skill" in the agent system. Keep them straight:
| Concept | What it is | Where it lives | API surface |
|---|---|---|---|
| Registry skills | Platform-shipped capabilities: Wiro defines them, they have credential requirements and runtime tools, and every plan includes them. Examples: int-instagram-post, int-gmail-check, int-wordpress-post, int-wiro-aimodels. |
Wiro's skill registry. | POST /Skills/List / POST /Skills/Detail (read), POST /UserAgent/SkillsApply (toggle on/off per useragent). |
| Custom skills | User-editable preference text (cs-content-tone) or scheduled tasks (cs-cron-blog-scanner) that live ON a useragent. They reference registry skills (e.g. a scheduled task calls into int-wordpress-post) but are scoped to one instance. |
Per useragent on the Wiro platform. | POST /UserAgent/CustomSkillUpsert / POST /UserAgent/CustomSkillRename / POST /UserAgent/CustomSkillDelete / POST /UserAgent/CustomSkillHistory / POST /UserAgent/CustomSkillRevert. |
The rest of this page documents both: the registry endpoints first (so you can discover what's possible), then the per-useragent endpoints (so you can configure them).
Skill Registry Endpoints
These four endpoints are public, so no authentication is required. They return data straight from the skill registry.
POST /Skills/List
Lists all skills in the registry.
| Parameter | Type | Required | Description |
|---|---|---|---|
category |
string | No | Filter by "int" (integration with a third-party service) or "util" (utility, no credential to connect: rule sets, playbooks, and keyless tools such as weather and diagrams). |
capability |
string | No | Filter by capability key (see POST /Skills/Capabilities for the closed-set vocabulary). |
user_invocable |
boolean | No | When true, only return skills end users can call directly through chat (filters out plumbing skills wired by the runtime). |
requires_credentials |
boolean | No | Filter by whether the skill requires a credential. |
wiro_connect_pending |
boolean | No | Filter by the "Wiro mode coming soon" flag: integrations whose Wiro-shared OAuth client is still awaiting provider review (currently 9 user-facing credentials: facebook-pages, instagram, google-ads, google-merchant-center, youtube, ga4, linkedin, tiktok, and meta-ads). Facebook Pages, Instagram, and Meta Ads remain usable through their customer-owned System User and/or OAuth alternatives. When true, only pending skills are returned; when false, only ready-to-use skills. The flag is read off the credential, not the skill. |
name_in |
array<string> | No | Restrict the response to a specific list of skill names. |
Response
{
"result": true,
"errors": [],
"total": 45,
"skills": [
{
"name": "int-instagram-post",
"category": "int",
"version": "1.0.0",
"title": "Instagram Post",
"description": "Post carousel feed and multi-story via Meta Graph API.",
"icon": "/images/icons/skills/instagram.svg",
"brand_color": "#e4405f",
"brand_text_color": "#ffffff",
"brand_logo_filter": "brightness(0) invert(1)",
"docs_url": "integration-instagram-skills",
"requires_credentials": true,
"credential_key": "instagram",
"capabilities": ["social_publishing"],
"depends_on": [],
"conflicts_with": [],
"user_invocable": true,
"deprecated": false,
"replacement": null,
"pricing": {
"monthly_price_weight_usd": 0,
"monthly_credits_weight": 0,
"billing_model": "tokens"
}
}
],
"channels": [
{
"id": "telegram",
"plugin": "telegram",
"credential_key": "telegram",
"title": "Telegram",
"required_fields": ["bottoken", "allowedusers"],
"capabilities": {
"direct": true,
"rooms": true,
"threads": true,
"roles": false,
"command_menu": true
},
"credential": {
"key": "telegram",
"credential_schema": ["..."]
}
}
]
}
| Field | Type | Description |
|---|---|---|
name |
string |
Canonical skill key, including the registry prefix (int-* for integration skills, util-* for utility skills). Use this exact value in SkillsApply and Deploy.body.skills. |
category |
string |
"int" (third-party integration) or "util" (utility, no credential to connect: rule sets, playbooks, and keyless tools such as weather and diagrams). |
version |
string |
Semver for the registry entry. Bumped when the skill's tool surface changes. |
title |
string |
Display name shown on chips / filters / cards. |
description |
string |
One-line summary used on marketing surfaces. |
icon |
string |
Path or URL to the brand icon (relative paths are absolutized to https://wiro.ai/... on the wire). Utility skills carry a LineIcons class name instead, such as lni lni-cloud-sun. |
brand_color |
string|null |
Brand background colour (hex) for chips and cards. |
brand_text_color |
string|null |
Foreground colour to render on top of brand_color. |
brand_logo_filter |
string|null |
CSS filter value applied to monochrome SVG icons (e.g. "brightness(0) invert(1)") so the same source SVG renders correctly on light and dark brand colours. |
docs_url |
string|null |
Slug or path of the integration page on this docs site. Frontends prefix with /docs/ when rendering. |
requires_credentials |
boolean |
true when the skill needs a credential the operator must supply (effectively true whenever credential_key names a credential you supply). |
credential_key |
string|null |
The provider this skill needs ("instagram", "google-ads", "wiro", "calendarific", …). null for util skills and skills whose credential Wiro manages. Use POST /Credentials/Detail to inspect the schema. |
additional_credential_keys |
array<string> |
Optional: only present when the skill writes secondary credentials. App-store / Google-Play review skills include ["var-support-email"] for the support-email variable bag; most skills omit this field entirely. |
capabilities |
array<string> |
High-level snake_case capability tags from the closed vocabulary returned by POST /Skills/Capabilities. Drives the "Find skills that can: ___" picker. |
depends_on |
array<string> |
Other skill names that must be enabled. Wiro auto-enables transitive deps when you toggle the parent skill on. |
conflicts_with |
array<string> |
Mutually-exclusive skill names. SkillsApply rejects toggle batches that would enable two conflicting skills. |
user_invocable |
boolean |
true when end users can call the skill via chat. Most user-facing skills (including int-wiro-aimodels and int-calendarific) are true; false marks supporting parts that come with another skill, such as util-video-shots and util-video-docs, which come with util-video-creator. |
deprecated |
boolean |
true for skills slated for removal, and replacement (if any) names the migration target. |
replacement |
string|null |
When deprecated: true, the registry-recommended successor skill name. |
pricing |
object |
{ monthly_price_weight_usd, monthly_credits_weight, billing_model }. Every plan includes every skill, so both weights are 0 (see below). |
channels[] is a separate, unfiltered catalog returned alongside skills[]. Skill filters do not remove channel rows. Each channel includes its stable id, credential_key, activation required_fields, UI-facing capabilities, and the full registry credential descriptor. Use these values to render channel setup. Save the matching credential group through UserAgent/CredentialUpsert; the channel activates automatically when every required_fields value is complete. Channels are not skills and do not affect pricing.
pricing object:
| Sub-field | Type | Description |
|---|---|---|
monthly_price_weight_usd |
number |
Always 0: a skill adds nothing to the agent's price. |
monthly_credits_weight |
number |
Always 0: a skill adds nothing to the agent's monthly credits. |
billing_model |
string |
Always "tokens". Per-turn conversation cost is token-metered at the agent's per-model tokenRates (credits per 1M input / output / cached-input tokens). See token billing in the Agent Overview. Voice skills bill realtime audio to the operator's own Wiro wallet through int-wiro-aimodels, the Wiro AI Models connector (your own Wiro API key); the voice-prep and post-call text turns are normal token deducts. |
Every plan includes every skill. An agent's price and monthly credits come from its plan (Starter, Pro or Max), never from its skills, so turning a skill on or off changes neither. See Pricing Model.
Optional filter
wiro_connect_pending. When you query withwiro_connect_pending: trueyou get every skill whose connecting integration's Wiro-shared OAuth client is awaiting App Review, currentlyint-instagram-post,int-facebookpage-post,int-linkedin-post,int-tiktok-post,int-metaads-manage, the Google OAuth skills listed above, and pairedutil-*helpers. Facebook Pages, Instagram, and Meta Ads already expose customer-owned System User and/or OAuth alternatives. The flag itself lives on the credential entry underPOST /Credentials/Detail.
POST /Skills/Detail
Returns a single skill by name.
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Canonical skill name with prefix (e.g. "int-instagram-post", "util-social-posting-common"). Registry-only: cs-* and cs-cron-* user-level customskills are not exposed here. |
Response
{
"result": true,
"errors": [],
"skill": {
"name": "int-instagram-post",
"category": "int",
"version": "1.0.0",
"title": "Instagram Post",
"description": "Post carousel feed and multi-story via Meta Graph API.",
"icon": "/images/icons/skills/instagram.svg",
"brand_color": "#e4405f",
"brand_text_color": "#ffffff",
"brand_logo_filter": "brightness(0) invert(1)",
"docs_url": "integration-instagram-skills",
"requires_credentials": true,
"credential_key": "instagram",
"capabilities": ["social_publishing"],
"depends_on": [],
"conflicts_with": [],
"user_invocable": true,
"deprecated": false,
"replacement": null,
"pricing": {
"monthly_price_weight_usd": 0,
"monthly_credits_weight": 0,
"billing_model": "tokens"
}
}
}
Returns the full registry entry: same shape as a row from Skills/List. The endpoint surfaces every field the registry has stored. If the skill is not found you get { "result": false, "errors": [{ "code": 404, "message": "Skill not found: <name>" }] }.
POST /Skills/CredentialSchema
Convenience endpoint: returns the credential entry for a given skill name in one call. Useful when you've discovered a skill via Skills/List and want to render the credential form without a separate Credentials/Detail round-trip.
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Skill name (with the registry prefix, e.g. "int-instagram-post"). |
Response
{
"result": true,
"errors": [],
"credential": {
"key": "instagram",
"title": "Instagram",
"icon": "/images/icons/skills/instagram.svg",
"brand_color": "#e4405f",
"brand_text_color": "#ffffff",
"brand_logo_filter": "none",
"docs_url": "integration-instagram-skills",
"credential_mode": "hybrid",
"connection_modes": ["api_key", "own", "wiro"],
"default_connection_mode": "api_key",
"mode_badges": {
"api_key": "Recommended",
"own": "Advanced"
},
"wiro_connect_pending": true,
"credential_schema": [
{
"key": "appid",
"type": "text",
"label": "App ID",
"required": true,
"pattern": "^[0-9]+$",
"help": "<ol><li>Go to Meta for Developers → My Apps</li><li>Create App → Other → Business</li><li>Copy the App ID from the dashboard</li><li>Add Product → Facebook Login → Set Up</li><li>Add OAuth Redirect URI: https://api.wiro.ai/v1/UserAgentOAuth/IGCallback</li></ol>",
"oauth_managed": true,
"only_in_modes": ["own"]
},
{
"key": "appsecret",
"type": "password",
"label": "App Secret",
"required": true,
"show_toggle": true,
"help": "<ol><li>Meta for Developers → select your app</li><li>App Settings → Basic</li><li>Show next to App Secret and copy</li></ol>",
"oauth_managed": true,
"only_in_modes": ["own"]
},
{
"key": "systemusertoken",
"type": "password",
"label": "System User Token",
"required": true,
"encrypted": true,
"show_toggle": true,
"runtime_excluded": true,
"only_in_modes": ["api_key"]
},
{
"key": "accountId",
"type": "text",
"label": "Instagram Account ID",
"required": true,
"pattern": "^[0-9]+$",
"auto_filled_by_oauth": true,
"readonly_when_connected": true
},
{
"key": "igusername",
"type": "text",
"label": "Connected Account",
"required": false,
"auto_filled_by_oauth": true,
"readonly_when_connected": true
}
],
"oauth_provider": {
"auth_method_value": "wiro",
"connect_endpoint": "/UserAgentOAuth/OAuthConnect",
"disconnect_endpoint": "/UserAgentOAuth/OAuthDisconnect",
"status_endpoint": "/UserAgentOAuth/OAuthStatus",
"connect_button_label": "Connect with Instagram",
"connect_button_icon": "/images/icons/skills/instagram.svg",
"connect_button_brand_color": "#e4405f",
"connect_button_text_color": "#ffffff",
"connect_button_logo_filter": "none",
"username_field": "igusername",
"return_query_param": "ig_connected",
"return_error_param": "ig_error",
"return_error_detail_param": "ig_error_detail",
"direct_probe": {
"mode": "api_key",
"mode_label": "System User Token",
"token_field": "systemusertoken",
"required_fields": ["systemusertoken"],
"public_account_fields": ["id", "name"]
},
"account_picker": {
"enabled": true,
"multi_select": true,
"set_endpoint": "/UserAgentOAuth/SetPickerAccounts",
"item_value_field": "accountId",
"item_label_field": "igusername",
"item_fields_to_save": ["accountId", "igusername"]
},
"extra_step": null
},
"used_by_skills": ["int-instagram-post"]
}
}
Returns the full registry credential entry: same shape as a row from POST /Credentials/Detail. Returns { "result": false, "errors": [{ "code": 404, "message": "No credential associated with skill: <name>" }] } if the skill exists but has credential_key: null (util / platform-managed) or if the skill is unknown.
POST /Skills/Capabilities
Returns the closed-set vocabulary of high-level capability tags. Use this to build a "Find skills that can: ___" picker in your UI, or to filter Skills/List via the capability parameter.
Response
{
"result": true,
"errors": [],
"capabilities": [
{ "name": "direct_reporting", "description": "Generates direct reports on request" },
{ "name": "attribution_cross_check", "description": "Cross-check platform conversions vs GA4 paid traffic" },
{ "name": "cross_check", "description": "Cross-system data validation" },
{ "name": "campaign_management", "description": "Create/pause/modify ad campaigns" },
{ "name": "campaign_reporting", "description": "Campaign performance reports" },
{ "name": "approval_flow", "description": "Approval commands for actions that wait for your approval" },
{ "name": "recommendation_ledger", "description": "Recommendation queue/log management" },
{ "name": "recommendation_execution", "description": "Execute approved recommendations" },
{ "name": "content_generation", "description": "Generate content (text, media)" },
{ "name": "creative_generation", "description": "Generate ad creatives" },
{ "name": "image_generation", "description": "Generate images" },
{ "name": "video_generation", "description": "Generate videos" },
{ "name": "motion_graphics", "description": "Compose and render motion graphics (HTML/CSS/GSAP animations, sound effects, transitions) to video" },
{ "name": "audio_generation", "description": "Generate audio / voice clips (TTS, music, SFX)" },
{ "name": "realtime_conversation", "description": "Bidirectional realtime audio/text conversation (Wiro realtime, OpenAI realtime)" },
{ "name": "vision", "description": "Vision LLM analysis of images (caption, describe, OCR, visual QA)" },
{ "name": "human_copywriting", "description": "Enforce anti-AI human copy rules" },
{ "name": "anti_ai_tone", "description": "Reject AI-generated tone patterns" },
{ "name": "memory_management", "description": "Keep the agent's memory files tidy (size limits, trimming, removing duplicates)" },
{ "name": "markdown_reporting", "description": "Structured markdown reports (tables, code blocks, splits)" },
{ "name": "store_review_response", "description": "Craft App Store / Google Play review responses" },
{ "name": "outreach_compliance", "description": "Outreach PII/opt-out/consent rules (GDPR, CAN-SPAM)" },
{ "name": "web_publishing", "description": "Publish web content (WordPress, etc.)" },
{ "name": "email_publishing", "description": "Send emails / newsletters" },
{ "name": "social_publishing", "description": "Post to social platforms (Twitter, IG, FB, LI, TikTok)" },
{ "name": "push_notification", "description": "Send push notifications (FCM)" },
{ "name": "lead_enrichment", "description": "Enrich prospect data (Apollo, HubSpot)" },
{ "name": "sequence_automation", "description": "Run outreach sequences (Lemlist, Apollo)" },
{ "name": "multi_platform_detection", "description": "Auto-detect available platforms" },
{ "name": "holiday_discovery", "description": "Discover global holidays (Calendarific)" },
{ "name": "product_feed_management", "description": "Manage product feeds (Merchant Center)" },
{ "name": "commerce_management", "description": "Manage storefront catalogs, inventory, orders, customers, discounts, and fulfillment workflows" },
{ "name": "review_monitoring", "description": "Monitor store reviews (App Store, Google Play)" },
{ "name": "app_metadata", "description": "Fetch app store metadata (description, pricing, features)" },
{ "name": "event_management", "description": "Manage app events (App Store in-app events)" },
{ "name": "file_asset_management", "description": "Manage asset files from cloud storage (Drive)" },
{ "name": "voice_call_handling", "description": "Receive and handle inbound voice calls via Twilio or web browser" },
{ "name": "caller_identification", "description": "Match caller phone number against CRM records (HubSpot, Apollo)" },
{ "name": "live_transcript", "description": "Stream real-time call transcripts to your chat" },
{ "name": "voice_persona", "description": "Configure AI voice persona (alloy/echo/etc) for phone interactions" },
{ "name": "phone_inbound", "description": "Accept inbound PSTN phone calls (Twilio)" },
{ "name": "browser_voice", "description": "Accept inbound voice calls from website browser (Web Audio API)" },
{ "name": "appointment_management", "description": "Manage calendar appointments (find slots, create events)" },
{ "name": "calendar_lookup", "description": "Read calendar/availability data (Google Calendar)" },
{ "name": "realtime_session_prep", "description": "Gets a call ready before realtime audio starts: reads your own skills, starts the realtime model and connects the call" },
{ "name": "web_search", "description": "Search the public web (Google Programmable Search / Custom Search JSON API)" },
{ "name": "weather_lookup", "description": "Current weather and forecasts for any place (MET Norway, OpenStreetMap geocoding)" },
{ "name": "diagram_rendering", "description": "Render diagrams (Mermaid flowcharts, sequence, state and ER diagrams, mind maps, timelines; agent-drawn SVG) to PNG with an SVG copy" }
]
}
Capability names are snake_case strings. Pass any of them as the capability parameter to Skills/List to filter (e.g. { "capability": "social_publishing" } returns every skill that publishes to a social platform).
Custom Skills: Discovery (Per-Instance)
Once you've deployed a useragent, its current custom skills live under customskills[] (preferences + non-cron user-created skills) and scheduledskills[] (scheduled tasks) on the POST /UserAgent/Detail response.
Request:
{ "guid": "your-useragent-guid" }
Response (top-level customskills and scheduledskills excerpt, same shape as on POST /UserAgent/Detail):
{
"customskills": [
{
"key": "cs-content-tone",
"description": "Brand voice + posting rules read by every content-generation skill on this agent.",
"value": "## Brand Voice\nTone: friendly, casual, never salesy.\nTarget Audience: indie devs and side-project builders.\n\n## Hashtag Strategy\nMax 3 per post. Always include #BuildInPublic and #Indie.\n\n## Platform Rules\n- Instagram: square images only, carousels for tutorials.\n- Twitter: thread format for posts longer than 200 chars.",
"enabled": true,
"interval": null,
"_source": "preset-strategy",
"_editable": true,
"_edited": true
}
],
"scheduledskills": [
{
"key": "cs-cron-social-content-scanner",
"description": "Polls the content sources every 4 hours and queues fresh ideas for the post generator.",
"value": "Scan the configured RSS / sitemap sources, dedupe against last 14 days, and queue up to 3 fresh items into the post pipeline.",
"enabled": true,
"interval": "0 */4 * * *",
"_source": "skill-bundle",
"_editable": true,
"_edited": false
},
{
"key": "cs-cron-weekly-health-check",
"description": "User-created weekly summary cron that posts a Monday recap to Telegram.",
"value": "Every Monday at 09:00 UTC, summarize last week's published posts (titles + engagement) and post the recap to Telegram.",
"enabled": true,
"interval": "0 9 * * 1",
"_source": "user-created",
"_editable": true,
"_edited": false,
"_user_created": true
}
],
"skills": [
{ "name": "int-instagram-post", "enabled": true },
{ "name": "int-googleads-manage", "enabled": false },
{ "name": "int-wiro-aimodels", "enabled": true }
]
}
The exact key names depend on the agent template. Always fetch
POST /UserAgent/Detailto see the real list for your deployed instance, because skill keys, default cron schedules, and even the set of skills can evolve as templates are updated.
| Field | Type | Description |
|---|---|---|
key |
string | Canonical key. Always carries the cs- runtime prefix. Strategies are cs-<slug>; crons are cs-cron-<slug>. The server normalises bare slugs you send to CustomSkillUpsert: "content-tone" becomes cs-content-tone, "weekly-health-check" with interval: "0 9 * * 1" becomes cs-cron-weekly-health-check. |
value |
string | Skill instructions / cron prompt body. Populated only for editable preference skills and user-created entries; bundled crons have it empty. |
description |
string | Human-readable description. Writable only on user-created rows. Sending a different description for a preset strategy or a skill-bundled cron is rejected with customskill-preset-description-not-editable; sending the current one back unchanged is ignored. |
enabled |
boolean | Whether the skill is active. Writable for both strategies (cs-*) and crons (cs-cron-*). A disabled strategy is suppressed end-to-end (kept in the merged customskills[] so it still appears in the list, but the agent never loads it). |
interval |
string | null | Cron expression for scheduled execution, or null for preference skills. Writable on scheduled tasks; ignored on preferences. |
_source |
string | preset-strategy (editable preference), skill-bundle (cron owned by an integration skill), or user-created (cron added via CustomSkillUpsert). |
_editable |
boolean | Convenience flag: true for preset strategies and user-created rows (you can write value), false for skill-bundled crons (you can only write enabled / interval). |
_user_created |
boolean | Present (and true) only on _source: "user-created" rows. Omitted on preset strategies and skill-bundled crons. |
Understanding _source
Agent responses merge three sources into a single set of custom-skill rows:
- Preset strategies (
_source: "preset-strategy"): preferences defined by the agent preset (e.g.cs-content-tone,cs-ad-strategy). You can writevalue. - Bundled crons (
_source: "skill-bundle"): cron tasks shipped inside a specific integration skill. Automatically materialized when the integration is enabled. You can writeintervalandenabled, but notvalue(the skill owns the cron instruction text). - User-created rows (
_source: "user-created"): entries added viaPOST /UserAgent/CustomSkillUpsert. You can write all fields. Crons are flagged viainterval(or an explicitcs-cron-prefix), notusercreated.
Updating Preference Skills
Preference skills (_source: "preset-strategy", _editable: true) let you customize the agent's behavior by editing its instructions.
Send one CustomSkillUpsert call per skill. Unspecified skills are untouched. The typical update is just value. You can also pass enabled: false to disable a strategy (the agent will skip it everywhere it would otherwise inject the strategy's instructions). interval has no effect on strategies: they're read on-demand by cron tasks via cs-<slug>, never scheduled themselves. description is rejected on preset rows with customskill-preset-description-not-editable, because the description is template-owned.
Example: Social Manager (Brand Voice)
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-social-manager-guid",
"skillkey": "content-tone",
"value": "## Brand Voice\nTone: Professional and informative. No slang.\nTarget Audience: Developers and product managers\nKey Topics: Developer tools, APIs, product updates\nHashtag Strategy: Max 3 per post. Always include #AI and #YourBrand.\n\n## Content Sources\nPrimary Source: https://your-site.com/blog/feed.xml\nSort Order: newest first\nCTA URL Pattern: https://your-site.com/posts/{slug}\n\n## Post Format\nCaption Style: short hook, 3 emoji bullet points, CTA line\nSignature Phrase: \"Build faster with YourBrand\"\n"
}'
Response: { "result": true, "errors": [], "restarting": false }. A running agent gets the new text right away, without a restart.
Example: Lead Generation Manager (ICP Definition)
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-leadgen-guid",
"skillkey": "lead-strategy",
"value": "## Our Business\nCompany: Acme Corp\nProduct: AI-powered CRM\n\n## Ideal Customer Profile\nIndustry: SaaS, FinTech\nCompany size: 50-500\nJob titles: VP Sales, CTO\n\n## Outreach Tone\nCasual but professional."
}'
Managing Scheduled Tasks
Scheduled tasks run on a cron schedule: bundled ones (_source: "skill-bundle") ship with integration skills and run automatically when the integration is enabled. User-created ones (_source: "user-created") are added at any time.
For bundled crons, only
enabledandintervalare writable. The task body (value) comes from the integration skill and is restored whenever the agent restarts. To change what a bundled scheduled task does, edit the paired preference skill (e.g.content-toneis read bycs-cron-social-content-scannerat runtime). For user-created crons, all three (value,interval,enabled) are writable.
Example: Change a bundled cron's frequency
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"skillkey": "cs-cron-review-scanner",
"enabled": true,
"interval": "0 */4 * * *"
}'
Example: Disable a bundled cron
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"skillkey": "cs-cron-social-content-scanner",
"enabled": false
}'
Example: Create a user-defined cron
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"skillkey": "weekly-health-check",
"value": "Every Monday, check the inbox and report the count to Telegram.",
"interval": "0 9 * * 1",
"enabled": true,
"description": "Weekly inbox health check"
}'
The call sends an interval, so the server stores the key as cs-cron-weekly-health-check. Later upserts can name it "cs-cron-weekly-health-check" or "cron-weekly-health-check", or "weekly-health-check" together with an interval. "weekly-health-check" without interval names a strategy, cs-weekly-health-check, and creates a new one.
Example: Delete a user-created cron
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillDelete" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"skillkey": "cs-cron-weekly-health-check"
}'
Preset-owned crons cannot be deleted: the call returns This skill belongs to the agent preset and cannot be deleted. Use enabled=false to disable it instead. with suggestion: "disable-via-upsert". Disable them via CustomSkillUpsert + enabled: false.
Example: Rename a user-created custom skill
Only user-created rows (_source: "user-created") can be renamed through CustomSkillRename. The skillkey flavour is preserved: a cs-cron-* scheduled task cannot be renamed to a cs-* strategy (delete + re-create with the right kind instead). The full version-history chain follows the rename under the new key, and a rename audit event is appended.
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillRename" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"oldskillkey": "cs-cron-weekly-health-check",
"newskillkey": "cs-cron-weekly-system-check",
"description": "Weekly system health probe"
}'
Successful responses include the canonical newskillkey the server ended up writing (after slug normalisation), so follow-up calls that reference the skill should use that value.
Common Cron Expressions
| Expression | Meaning |
|---|---|
*/30 * * * * |
Every 30 minutes |
0 * * * * |
Every hour |
0 */2 * * * |
Every 2 hours |
0 */4 * * * |
Every 4 hours |
0 9 * * * |
Daily at 9:00 AM UTC |
0 9 * * 1 |
Every Monday at 9:00 AM UTC |
0 10 * * 3 |
Every Wednesday at 10:00 AM UTC |
Version History: Audit and Revert
Every write through CustomSkillUpsert appends a row to the version history. Read it via POST /UserAgent/CustomSkillHistory; revert to any version (or to the preset default) via POST /UserAgent/CustomSkillRevert.
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillHistory" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"skillkey": "cs-content-tone"
}'
{
"result": true,
"errors": [],
"preset_default": {
"value": "## Brand Voice\nTone: friendly\nTarget Audience: ...",
"intervalexpr": null,
"enabled": true,
"description": "How the agent should sound across all generated copy."
},
"entries": [
{
"guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"skillkey": "cs-content-tone",
"operation": "upsert",
"value": "## Brand Voice\nTone: professional...",
"intervalexpr": null,
"enabled": true,
"usercreated": false,
"prev_value": "## Brand Voice\nTone: friendly...",
"prev_interval": null,
"prev_enabled": true,
"after_value": "## Brand Voice\nTone: professional...",
"after_interval": null,
"after_enabled": true,
"changed_fields": ["value"],
"changedby": "ada-uuid",
"changedby_user": {
"uuid": "ada-uuid",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"username": "ada",
"avatar": "https://cdn.wiro.ai/avatars/ada.webp",
"avatarinitials": "AL"
},
"changedat": 1714694410
},
{
"guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"skillkey": "cs-content-tone",
"operation": "upsert",
"value": "## Brand Voice\nTone: friendly...",
"intervalexpr": null,
"enabled": true,
"usercreated": false,
"prev_value": null,
"prev_interval": null,
"prev_enabled": null,
"after_value": "## Brand Voice\nTone: professional...",
"after_interval": null,
"after_enabled": true,
"changed_fields": [],
"changedby": "ada-uuid",
"changedby_user": {
"uuid": "ada-uuid",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"username": "ada",
"avatar": "https://cdn.wiro.ai/avatars/ada.webp",
"avatarinitials": "AL"
},
"changedat": 1714600000
}
]
}
Each entry carries the BEFORE state of the action that produced it (the history entry is written before the change is applied), plus server-computed prev_*, after_*, and changed_fields[] so you don't have to walk the list yourself. changedby_user is the resolved actor object, or null for system / cron writes (sentinel changedby) or deleted users. Full field reference and revert flow live in Agent Overview → CustomSkillHistory.
Revert to the preset default:
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillRevert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"skillkey": "cs-content-tone",
"source": "preset"
}'
Or jump back to a specific version:
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillRevert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"skillkey": "cs-content-tone",
"source": "history",
"versionguid": "v1-1714600000-def"
}'
The response carries the post-revert state (current_value, current_interval, current_enabled) so the UI can refresh without a full Detail round-trip.
Toggling Integration Skills
The top-level skills[] array on UserAgent/Detail lists every integration skill on the instance as an object array: [{ name, enabled, _edited?, _user_created? }, ...]. enabled: false entries are still returned (so a UI can show disabled rows); filter on enabled: true to get only the active set. Example: [{ "name": "int-instagram-post", "enabled": true }, { "name": "int-googleads-manage", "enabled": false }, { "name": "int-wiro-aimodels", "enabled": true }]. To enable or disable several skills in one shot, use POST /UserAgent/SkillsApply. Even when you only want to flip a single skill, send it as a one-entry skills map. The endpoint:
- Triggers exactly one agent restart after the new skill set lands.
- Uses idempotency: concurrent calls or client retries can't apply the change twice.
- Is atomic: the whole batch lands, or none of it does.
A skill change costs nothing: every plan includes every skill, so the agent's price and credits stay the same.
Single-skill enable:
curl -X POST "https://api.wiro.ai/v1/UserAgent/SkillsApply" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"idempotencyKey": "550e8400-e29b-41d4-a716-446655440001",
"skills": {
"int-instagram-post": true
}
}'
Batch toggle in one call:
curl -X POST "https://api.wiro.ai/v1/UserAgent/SkillsApply" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
"skills": {
"int-instagram-post": true,
"int-twitterx-post": true,
"int-wordpress-post": false
}
}'
idempotencyKey is required: use a UUID per "user clicks Save" event. The full response shape and error-code table live on SkillsApply.
Template deploys too.
SkillsApplyworks on agents deployed from a marketplace template as well as on custom builds. On a template agent, a skill you change overrides the template for that skill only; later template updates still reach every skill you never changed.Bundled crons follow the integration toggle. When you disable an integration skill (e.g.
int-instagram-post), every bundled cron it owns (_source: "skill-bundle") is hidden from the top-levelcustomskills/scheduledskillslists until the integration is re-enabled, so you don't need to touch them individually.
Preview a Skill Change
Before you commit SkillsApply (or the user clicks Save in your UI), call POST /UserAgent/PricingPreview to see the skill set the change would leave, with its depends_on resolved. No state is mutated, and the price and credits stay the plan's: its planChange shows no charge and no credit change. See PricingPreview for the full response shape.
curl -X POST "https://api.wiro.ai/v1/UserAgent/PricingPreview" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"skillOverrides": {
"int-twitterx-post": true,
"int-wordpress-post": false
}
}'
For Build Your Agent (no useragent yet), use draft mode:
curl -X POST "https://api.wiro.ai/v1/UserAgent/PricingPreview" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"draft": true,
"tier": "starter",
"skills": ["int-gmail-check", "int-wordpress-post"]
}'
See Agent Builder for the full custom-build walkthrough.
Full Example: Push Notification Manager
Complete flow: fetch skills, then update preferences and schedules with three separate calls.
Step 1: Discover skills.
curl -X POST "https://api.wiro.ai/v1/UserAgent/Detail" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-push-agent-guid" }'
Response excerpt (top-level customskills and scheduledskills):
{
"customskills": [
{
"key": "cs-push-preferences",
"value": "## Push Tone\nWrite like a mobile growth expert...",
"description": "Push notification style, language, and targeting preferences",
"enabled": true,
"interval": null,
"_source": "preset-strategy",
"_editable": true
}
],
"scheduledskills": [
{
"key": "cs-cron-push-scanner",
"value": "",
"description": "Scan holidays and craft push notification suggestions",
"enabled": true,
"interval": "0 9 * * *",
"_source": "skill-bundle",
"_editable": false
},
{
"key": "cs-cron-push-dispatcher",
"value": "",
"description": "Send queued push notifications on schedule",
"enabled": true,
"interval": "0 * * * *",
"_source": "skill-bundle",
"_editable": false
}
]
}
Step 2: Update each skill with its own call.
# 1. Rewrite preference value
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillUpsert" \
-H "Content-Type: application/json" -H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-push-agent-guid",
"skillkey": "push-preferences",
"value": "## Push Tone\nFriendly and casual. Turkish for locale_tr, English for locale_en.\n\n## Holiday Preferences\nFocus on: New Year, Ramadan, Republic Day.\nSkip: Valentine'\''s Day, Halloween.\n\n## Targeting\nAlways segment by locale. Premium version for paid users."
}'
# 2. Change scanner schedule from daily to Mondays only
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillUpsert" \
-H "Content-Type: application/json" -H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-push-agent-guid",
"skillkey": "cs-cron-push-scanner",
"enabled": true,
"interval": "0 9 * * 1"
}'
# 3. Change dispatcher schedule from hourly to every 2 hours
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillUpsert" \
-H "Content-Type: application/json" -H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-push-agent-guid",
"skillkey": "cs-cron-push-dispatcher",
"interval": "0 */2 * * *"
}'
All three requests succeed independently. The agent restarts once: the server coalesces the restart trigger after all three succeed within the same request window.
Available Skills by Agent
Integration setup guides: Every skill below that needs a third-party connection links to a dedicated integration page with the full OAuth / API key walkthrough, required scopes or permissions, callback URL, troubleshooting, and multi-tenant architecture notes. See the Integration Catalog for the full list.
Discovery is canonical. Skill keys evolve as agent templates are updated. To see the exact keys for a specific agent instance, always fetch
POST /UserAgent/Detailfirst. The top-levelcustomskills/scheduledskillsarrays are the source of truth. The tables below reflect current intended keys;CustomSkillUpsertsilently accepts keys that exist on the instance and returnsskill-not-foundfor unknown keys without altering other state.
Preferences (Editable Instructions)
| Agent | Skill Key | What It Controls |
|---|---|---|
| Social Manager | content-tone |
Brand voice, hashtags, posting style |
| Blog Content Editor | content-strategy |
Writing style, topics, research rules |
| App Review Support | review-preferences |
Response tone, support channels |
| App Event Manager | event-preferences |
Event regions, holiday priorities |
| Push Notification | push-preferences |
Push tone, language, targeting |
| Newsletter Manager | newsletter-strategy |
Topics, tone, audience, frequency |
| Lead Generation Manager | lead-strategy |
ICP definition, outreach tone |
| Google Ads Manager | ad-strategy |
Target audience, budget goals |
| Meta Ads Manager | ad-strategy |
Target audience, creative preferences |
| TikTok Ads Manager | ad-strategy, tiktok-ads-strategy |
Target audience, budget goals; TikTok tracking gates, kill thresholds, placement, Spark Ads and Smart+ rules |
| Video Creator | video-preferences, saved-logins |
Default format, length, voice, look, music, captions and ending card; test accounts for the screens behind a login |
Scheduled Tasks
Scheduled task keys are defined per agent template and may be updated over time. The table below reflects the current keys and default cron expressions shipped with Wiro's built-in agent templates, but the source of truth for any specific deployed agent is always
POST /UserAgent/Detail→ top-levelscheduledskills.
| Agent | Skill Key | Cron | What It Does |
|---|---|---|---|
| Social Manager | cs-cron-social-content-scanner |
0 */4 * * * |
Content discovery and draft posts with rotating strategies (reads content-tone; disabled by default) |
| Social Manager | cs-cron-social-drive-scanner |
0 10 * * * |
Scans Google Drive for new post assets and prepares posts (disabled by default) |
| Blog Content Editor | cs-cron-blog-scanner |
0 9 * * * |
Topic discovery and article drafting (reads content-strategy) |
| Blog Content Editor | cs-cron-blog-gmail-checker |
*/30 * * * * |
Checks the inbox for topic requests and writing instructions (disabled by default) |
| App Review Support | cs-cron-review-scanner |
0 */2 * * * |
Scans App Store and Google Play for new reviews and prepares replies (reads review-preferences; disabled by default) |
| App Event Manager | cs-cron-app-event-scanner |
0 9 * * 1 |
Scans global holidays and suggests App Store in-app events (reads event-preferences; disabled by default) |
| Push Notification Manager | cs-cron-push-scanner |
0 9 * * * |
Scans holidays and prepares push notification suggestions (reads push-preferences) |
| Push Notification Manager | cs-cron-push-dispatcher |
0 * * * * |
Sends queued push notifications on schedule |
| Newsletter Manager | cs-cron-newsletter-sender |
0 9 * * 1 |
Newsletter drafting and sending (reads newsletter-strategy; disabled by default) |
| Newsletter Manager | cs-cron-newsletter-subscriber-scanner |
0 10 * * * |
Daily subscriber list health check and bounce monitoring (disabled by default) |
| Lead Generation Manager | cs-cron-lead-prospect-scanner |
0 10 * * 1 |
Weekly prospect search, enrichment and scoring (reads lead-strategy; disabled by default) |
| Lead Generation Manager | cs-cron-lead-outreach-reporter |
0 9 * * * |
Daily outreach performance report (disabled by default) |
| Lead Generation Manager | cs-cron-lead-reply-handler |
0 */4 * * * |
Checks new replies, analyzes sentiment and proposes responses (disabled by default) |
| Google Ads Manager | cs-cron-googleads-performance-reporter |
0 9 * * * |
Daily performance report with recommendations (reads ad-strategy) |
| Google Ads Manager | cs-cron-googleads-recommendations-fetcher |
0 8 * * * |
Daily Google Ads recommendations: safe items become low-risk suggestions, risky ones wait for your approval |
| Google Ads Manager | cs-cron-googleads-competitor-scanner |
0 10 * * 1 |
Weekly competitor analysis, keyword opportunities and account health audit |
| Google Ads Manager | cs-cron-googleads-holiday-planner |
0 10 * * 3 |
Upcoming holidays and seasonal campaign suggestions |
| Google Ads Manager | cs-cron-googleads-audience-refresher |
0 7 * * * |
Daily Customer Match refresh from a connected CRM (HubSpot, Apollo, Lemlist) or a Google Drive CSV (disabled by default) |
| Google Ads Manager | cs-cron-googleads-drive-scanner |
0 10 * * * |
Scans Google Drive for new creative folders and proposes campaigns (disabled by default) |
| Google Ads Manager | cs-cron-merchant-center-scanner |
30 8 * * * |
Daily Merchant Center product feed health check (runs only when Merchant Center is connected; disabled by default) |
| Google Ads Manager | cs-cron-ga4-attribution-auditor |
0 11 * * 1 |
Weekly conversion tracking and attribution health audit (cross-checks Google Ads with GA4 when connected; disabled by default) |
| Google Ads Manager | cs-cron-adjust-creative-roas-reporter |
0 10 * * * |
Daily Adjust creative-level ROAS report with scale/pause recommendations (disabled by default) |
| Google Ads Manager | cs-cron-roasit-creative-roas-reporter |
30 10 * * * |
Daily Roasit creative-level ROAS report with scale/pause recommendations (disabled by default) |
| Google Ads Manager | cs-cron-ads-recommendation-cleanup |
0 0 * * * |
Nightly cleanup of expired recommendations |
| Meta Ads Manager | cs-cron-metaads-performance-reporter |
0 9 * * * |
Daily performance report with creative health, audience analysis and recommendations (reads ad-strategy) |
| Meta Ads Manager | cs-cron-metaads-audience-scanner |
0 10 * * 1 |
Weekly audience, creative health and account health audit |
| Meta Ads Manager | cs-cron-metaads-holiday-planner |
0 10 * * 3 |
Upcoming holidays and seasonal campaign suggestions |
| Meta Ads Manager | cs-cron-metaads-drive-scanner |
0 10 * * * |
Scans Google Drive for new creative folders and proposes campaigns |
| Meta Ads Manager | cs-cron-ga4-attribution-auditor |
0 11 * * 1 |
Weekly conversion tracking and attribution health audit (cross-checks Google Ads with GA4 when connected; disabled by default) |
| Meta Ads Manager | cs-cron-adjust-creative-roas-reporter |
0 10 * * * |
Daily Adjust creative-level ROAS report with scale/pause recommendations (disabled by default) |
| Meta Ads Manager | cs-cron-roasit-creative-roas-reporter |
30 10 * * * |
Daily Roasit creative-level ROAS report with scale/pause recommendations (disabled by default) |
| Meta Ads Manager | cs-cron-ads-recommendation-cleanup |
0 0 * * * |
Nightly cleanup of expired recommendations |
| TikTok Ads Manager | cs-cron-tiktokads-performance-reporter |
0 9 * * * |
Performance reporting per advertiser, plus the 30-day reconnect reminder (reads ad-strategy) |
| TikTok Ads Manager | cs-cron-tiktokads-audience-scanner |
0 10 * * 1 |
Weekly audience, creative health and account health audit |
| TikTok Ads Manager | cs-cron-tiktokads-holiday-planner |
0 10 * * 3 |
Upcoming holidays and seasonal campaign suggestions |
| TikTok Ads Manager | cs-cron-tiktokads-drive-scanner |
0 10 * * * |
Scans Google Drive for new creative folders and proposes TikTok Ads campaigns (does nothing until Google Drive is connected) |
| TikTok Ads Manager | cs-cron-ga4-attribution-auditor |
0 11 * * 1 |
Weekly conversion tracking and attribution health audit (cross-checks Google Ads with GA4 when connected; disabled by default) |
| TikTok Ads Manager | cs-cron-adjust-creative-roas-reporter |
0 10 * * * |
Daily Adjust creative-level ROAS report with scale/pause recommendations (disabled by default) |
| TikTok Ads Manager | cs-cron-roasit-creative-roas-reporter |
30 10 * * * |
Daily Roasit creative-level ROAS report with scale/pause recommendations (disabled by default) |
| TikTok Ads Manager | cs-cron-ads-recommendation-cleanup |
0 0 * * * |
Nightly cleanup of expired recommendations |
| Google Review Manager | cs-cron-google-review-scanner |
0 */2 * * * |
Scans Google Business Profile locations for new reviews and prepares replies |
How Preferences and Scheduled Tasks Work Together
Each scheduled task reads its paired preference skill at runtime. The mechanism:
POST /UserAgent/CustomSkillUpsertwrites your preferencevaluefor keycontent-tone(stored ascs-content-tone).- When the agent starts, each
customskills/scheduledskillsrow becomes a skill named by its key: a preference skill with keycs-content-tonebecomes the skillcs-content-tone, and a scheduled task with keycs-cron-social-content-scannerbecomescs-cron-social-content-scanner. - The scheduled task's
value(shipped in the integration skill, not user-editable) references its paired preference by its skill name,cs-<preference-key>, for example:0. Read the cs-content-tone skill first — follow ALL its rules. 1. ... - At each cron tick, the agent LLM reads
cs-content-tone, applies your instructions, then executes the scan/report/dispatch workflow.
Slug normalization: the
<slug>incs-<slug>/cs-cron-<slug>is the raw key lowercased with any run of non-alphanumeric characters replaced by a single-(leading/trailing dashes trimmed). Template keys already follow this shape so the slug matches 1:1.
This means your editable preference becomes the single place to customize agent behavior (brand voice, target audience, content sources, holiday markets, etc.), and the bundled scheduled task is a thin orchestration layer that defers to your preference.
Skill → Integration Mapping
Skills that depend on third-party credentials. Follow the linked integration page for provider setup, OAuth walkthrough, and troubleshooting.
| Skill | Credential Key | Integration Guide |
|---|---|---|
int-metaads-manage |
meta-ads (System User or OAuth) |
Meta Ads Skills |
int-tiktok-ads |
tiktok-ads (Wiro OAuth) |
TikTok Ads Skills |
int-facebookpage-post |
facebook-pages (System User or OAuth) |
Facebook Page Skills |
int-instagram-post |
instagram (System User or Instagram OAuth) |
Instagram Skills |
int-linkedin-post |
linkedin (OAuth) |
LinkedIn Skills |
int-twitterx-post |
twitter (OAuth) |
Twitter / X Skills |
int-tiktok-post |
tiktok (OAuth) |
TikTok Skills |
int-youtube-manage |
youtube (OAuth) |
YouTube Skills |
int-googleads-manage |
google-ads (OAuth) |
Google Ads Skills |
int-merchant-center |
google-merchant-center (OAuth) |
Merchant Center Skills |
int-ga4-analytics |
ga4 (OAuth) |
GA4 Skills |
int-google-business-reviews |
google-business (Own OAuth) |
Google Business Profile Skills |
int-hubspot-crm |
hubspot (OAuth) |
HubSpot Skills |
int-mailchimp-email |
mailchimp (OAuth or API key) |
Mailchimp Skills |
int-google-drive |
google-drive (Service Account) |
Google Drive Skills |
int-google-calendar |
google-calendar (Service Account) |
Google Calendar Skills |
int-gmail-check |
gmail (App Password) |
Gmail Skills |
int-firebase-push |
firebase (Service Account) |
Firebase Skills |
int-wordpress-post |
wordpress (App Password) |
WordPress Skills |
int-roasit-attribution |
roasit (API token) |
Roasit Skills |
int-search-console |
google-search-console (OAuth, your own Google Cloud client) |
Google Search Console Skills |
int-dataforseo |
dataforseo (API login and password) |
DataForSEO Skills |
int-keepa |
keepa (API key) |
Keepa Skills |
int-revenuecat |
revenuecat (secret API key) |
RevenueCat Skills |
int-adapty |
adapty (secret API key) |
Adapty Skills |
int-brevo-email |
brevo (API key) |
Brevo Skills |
int-sendgrid-email |
sendgrid (API key) |
SendGrid Skills |
int-appstore-reviews, int-appstore-metadata, int-appstore-events |
apple-appstore (JWT / Service Account) |
App Store Skills |
int-googleplay-reviews, int-googleplay-metadata |
google-play (Service Account) |
Google Play Skills |
int-googleplay-events |
google-play-apps (Service Account, separate per-app registry) |
Google Play Skills |
int-apollo-sales |
apollo (API key) |
Apollo Skills |
int-lemlist-outreach |
lemlist (API key) |
Lemlist Skills |
int-twilio-channel |
twilio-voice (API key) |
Twilio Voice |
int-wiro-aimodels |
wiro (the Wiro project the agent runs models with) |
See Using Wiro AI Models from Your Agent |
int-calendarific |
calendarific (API key) |
Calendarific in your agent |
Agents can optionally forward operator notifications to a Telegram bot via the telegram credential (see Telegram Skills). This is never required; every agent remains fully usable over web chat and the Messaging API without a bot configured.
Utility Skills
util-* skills need no credential. Most are rule sets that come with an integration skill as one of its depends_on. These three can be added to any agent with SkillsApply, on any plan and at no charge:
| Skill | What it adds |
|---|---|
util-weather |
Current weather and a 9-day forecast for any place: temperature, rain, wind and UV from MET Norway's open forecast data, with the place found on OpenStreetMap. |
util-diagram |
Flowcharts, architecture and sequence diagrams, state machines, data models, mind maps, timelines, Gantt plans and concept drawings as PNG images with an editable SVG copy, checked for overlapping or cut-off text. |
util-video-creator |
The Video Creator's playbook: finished videos with voice-over, music and captions from a website or web app (behind a login too), an app-store listing, a document, an article or product photos; 16:9 or 9:16, up to 3 minutes. It brings util-video-shots, util-video-docs, util-motion-effects and int-wiro-aimodels with it, so the agent needs your Wiro project key, which pays the video's model runs (see Using Wiro AI Models from Your Agent). util-motion-effects and util-video-creator always come together, whichever one you turn on. |
POST /Skills/List with { "category": "util" } returns every utility skill.
Restart behavior: On a starting or running agent (status 3 or 4),
SkillsApply,CustomSkillRename,CustomSkillDeleteandCustomSkillRevertrestart it so the new skill configuration is picked up, as credential updates do.CustomSkillUpsertrestarts it for a new skill or task, a newintervalor anenabledchange. A change to the text or description of an existing one reaches the running agent without a restart, except forcs-approval-policy. See Automatic Restart.
Using Wiro AI Models from Your Agent
int-wiro-aimodels lets an agent call Wiro's own AI models (image / video / audio / LLM generation, cover image creation, model discovery) while it works. When it's enabled on an agent:
credentials.wiro.apikeyis operator-supplied: pick or create a Wiro project at wiro.ai/panel/project and connect it on the agent's Connectors tab, or through the API withPOST /UserAgent/CredentialProjectBind. Each generated asset is billed to the wallet of the workspace that owns that project (your personal wallet, or the team wallet for a team project).- The agent can run Wiro models only when
int-wiro-aimodelsis enabled and awiro.apikeyvalue has been written. int-wiro-aimodelsis markeduser_invocable: truein the registry: end-user messages can trigger it directly, and other skills / scheduled tasks invoke it internally when they need to generate content.
Most Wiro-provided agent templates (Social Manager, Blog Content, Push, App Event, Meta Ads, TikTok Ads, Google Ads) ship with int-wiro-aimodels: true. Templates that don't need AI generation (App Review Support, Lead Generation Manager) ship with int-wiro-aimodels: false. Either way, the agent starts without a Wiro project. Where the template marks this connector required, UserAgent/Detail reads setuprequired: true until one is connected. projectid in the call below comes from POST /Project/List; see CredentialProjectBind for the response and errors.
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialProjectBind" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"projectid": "your-project-id"
}'
To verify the skill is active on a deployed agent:
curl -X POST "https://api.wiro.ai/v1/UserAgent/Detail" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
# The top-level skills[] array should contain { "name": "int-wiro-aimodels", "enabled": true }
# credentials.wiro.apikey holds the project's key once the project is connected
Project key vs operator key
credentials.wiro.apikey is a per-agent Wiro project key: the agent runs Wiro models with it. The x-api-key header you send to the public Wiro endpoints from your own backend (e.g. POST /UserAgent/Deploy, POST /Run) is your operator key: it authenticates your request. These are two roles, and they are the same key only when you bind the project of the key you call with. If you're building on top of Wiro programmatically and want to call the Run / Task / LLM APIs directly from your own backend, use your operator key (see Run a Model and LLM & Chat Streaming).
Update Rules Summary
| Operation | Endpoint | Allowed on preset strategy (_source: preset-strategy) |
Allowed on skill-bundled cron (_source: skill-bundle) |
Allowed on user-created cron (_source: user-created) |
|---|---|---|---|---|
Write value |
CustomSkillUpsert |
Yes | No: silently dropped (skill owns the cron body) | Yes |
Write interval |
CustomSkillUpsert |
No: silently dropped (strategies aren't scheduled) | Yes | Yes |
Write enabled |
CustomSkillUpsert |
Yes (disabling suppresses the strategy end-to-end) | Yes | Yes |
Write description |
CustomSkillUpsert |
No: a changed text is rejected with customskill-preset-description-not-editable (the current text is ignored) |
No: a changed text is rejected with customskill-preset-description-not-editable (the current text is ignored) |
Yes |
| Create | CustomSkillUpsert with a new key |
n/a | n/a | Yes |
| Rename key (+ optional description) | CustomSkillRename |
No: preset-forbidden | No: preset-forbidden | Yes (flavour preserved; cs-cron-* ↔ cs-* rejected) |
| Delete | CustomSkillDelete |
Rejected with suggestion: "disable-via-upsert" |
Rejected with suggestion: "disable-via-upsert" |
Yes (hard delete: live row + full history purged) |
| Read history | CustomSkillHistory |
Yes | Yes (only enabled / interval writes show up) |
Yes (post-rename, the chain is migrated under the new key; a rename event marks the transition) |
| Revert to preset | CustomSkillRevert (source: "preset") |
Yes | Yes (resets interval / enabled to preset defaults) |
Yes (deletes the row if no preset baseline exists) |
| Revert to a version | CustomSkillRevert (source: "history") |
Yes | Yes | Yes |
- Send only the fields you want to change. Omitted fields keep their current values.
- Unknown skill keys return
skill-not-foundin theerrors[]without altering other state. - To clear a cron schedule, call
CustomSkillUpsertwithenabled: false. Settinginterval: ""ornullalso clears it. - A schedule must be one the agent can run, written as five fields,
minute hour day month weekday, such as0 9 * * 1-5. A schedule the agent can't run, or one whose date never comes, such as 30 February, is refused and nothing is saved. The error says what is wrong and what to write, for exampleThis schedule can't run. The hour field takes 0 to 23. A schedule has five fields: minute hour day month weekday, for example 0 9 * * 1-5. - Integration toggles (top-level
skills[]) are a separate endpoint (see Toggling Integration Skills andSkillsApply).
What happens when Wiro updates an agent template
Skills occasionally evolve on Wiro's side: new preset strategies, new bundled crons, improved instructions. Deployed instances are reconciled with the latest template without destroying your edits:
| Row type | Behavior on template update |
|---|---|
Preset strategy (_source: "preset-strategy") |
Your value is preserved (rows with useredited: true). New placeholder structure in the template appears only on fresh deploys. |
Skill-bundled cron (_source: "skill-bundle") |
The value (cron instructions) is re-materialized from the new skill. Your custom interval and enabled are preserved when useredited: true. |
| New preset strategy upstream | Added to your instance with the template's default value. |
| Preset strategy removed upstream | Removed from your instance on the next reconciliation. |
| User-created cron | Always preserved. |
Cascade reconciliation is async: each template update enqueues a job that fans out to every deployed useragent in the background. Per-useragent edits (useredited: true) are protected from being overwritten by the cascade.
Agent Builder
Build a custom agent from scratch: no marketplace template required. Pick your own skill set and a plan, and deploy in one call.
Overview
Wiro's agent runtime supports two deploy paths:
| Path | When to use | Endpoint |
|---|---|---|
| Template deploy | The marketplace already has an agent that does what you need (Instagram Manager, Push Notifications, App Review Support, …). You inherit the template's default skill set + configuration. | POST /UserAgent/Deploy with agentguid |
| Custom build | You want a unique skill combination: for example a custom support bot that watches Gmail, publishes a daily digest to WordPress, and uses Wiro's image generator. No marketplace template fits. | POST /UserAgent/Deploy with custom: true |
The two paths produce the same useragent shape at the end (same customskills, scheduledskills, credentials, subscription, tokenRates, etc.). The only differences are:
| Aspect | Template deploy | Custom build |
|---|---|---|
| Linked marketplace template | The template you deployed | None |
agent.cover on the response |
Template's cover image | The cover you sent at Deploy (or a placeholder) |
| Cascade updates | When Wiro updates the template, your useragent reconciles | No template: the agent is fully owned by you |
Both paths are sold on the same three plans, Starter at $5, Pro at $30 and Max at $100 a month (see Pricing Model), and the skills you pick never change the price.
Custom builds don't share a marketplace listing. They are private to your account; nothing about a custom agent appears on
/Agent/Listor/Agent/Detail. Discovery happens through your own product surface.
Step 1: Browse Available Skills
Custom builds start from the skill registry, the catalogue of every skill the platform supports. Browse it with POST /Skills/List and inspect details with POST /Skills/Detail.
Both endpoints are public, so no authentication is required.
# Browse all integration skills
curl -X POST "https://api.wiro.ai/v1/Skills/List" \
-H "Content-Type: application/json" \
-d '{ "category": "int" }'
Pick the skill names you want to enable. Each skill descriptor tells you:
name: the canonical skill key you'll send inskills/skillOverridescategory:int(integration with a third-party service) orutil(utility, no credential to connect)credential_key: which credential the skill needs (nullforutilor platform-managed skills)requires_credentials: boolean, whether the user must supply a credential before the skill can rundepends_on: array of skill names that must also be enabled (Wiro auto-enables transitive deps)conflicts_with: array of skill names that cannot coexist with this onepricing:billing_model: "tokens"; itsmonthly_price_weight_usdandmonthly_credits_weightare0on every skill, since every plan includes every skill
Use
POST /Skills/Capabilitiesto discover the closed-set capability vocabulary (the high-level tasks skills can perform). Useful when you want to find every skill that can "post-content" or "send-email".
Step 1b: Discover Communication Channels
The same POST /Skills/List response also includes a top-level channels[] catalog. Channel discovery is registry-driven and does not depend on which marketplace template you deploy.
{
"result": true,
"channels": [
{
"id": "telegram",
"credential_key": "telegram",
"title": "Telegram",
"required_fields": ["bottoken", "allowedusers"],
"capabilities": {
"direct": true,
"rooms": true,
"threads": true,
"roles": false,
"command_menu": true
},
"credential": {
"key": "telegram",
"credential_schema": ["..."]
}
}
]
}
The current external channel IDs are telegram, slack, and discord. channels[] is returned in full even when the request filters skills[]. Render each channel's form from credential.credential_schema and use required_fields to decide which values must be present before the operator can connect it. A channel activates automatically when every required value is complete.
Web chat and the Messaging API are always available. External channels have no separate enablement parameter: pass a complete channel group in Deploy's credentials object, or add it later with POST /UserAgent/CredentialUpsert. The channel activates automatically when all required_fields are complete. Channels do not add skills or change agent pricing.
Step 2: Preview the Build
Before you commit, resolve the proposed skill set and see the plans with POST /UserAgent/PricingPreview. The draft mode runs without touching any DB state.
curl -X POST "https://api.wiro.ai/v1/UserAgent/PricingPreview" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"draft": true,
"tier": "pro",
"skills": ["int-gmail-check", "int-wordpress-post", "int-wiro-aimodels"]
}'
Response
{
"result": true,
"errors": [],
"tier": "pro",
"totalPriceUsd": 30,
"totalMonthlyCredits": 3000,
"skillBreakdown": [
{ "skill": "int-gmail-check", "priceUsd": 0, "credits": 0, "billing_model": "tokens" },
{ "skill": "int-wordpress-post", "priceUsd": 0, "credits": 0, "billing_model": "tokens" },
{ "skill": "int-wiro-aimodels", "priceUsd": 0, "credits": 0, "billing_model": "tokens" }
],
"enabledSkills": ["int-gmail-check", "int-wordpress-post", "int-wiro-aimodels"],
"directSkills": ["int-gmail-check", "int-wordpress-post", "int-wiro-aimodels"],
"tokenRates": {
"default_model": "openai/gpt-5.6-sol",
"fallback_rate": { "input_per_1m": 625, "output_per_1m": 3750, "cached_input_per_1m": 62.5, "cache_write_per_1m": 781.25 },
"models": {
"openai/gpt-5.6-sol": { "input_per_1m": 625, "output_per_1m": 3750, "cached_input_per_1m": 62.5, "cache_write_per_1m": 781.25, "selectable": true, "label": "GPT-5.6 Sol", "tier": "premium" },
"openai/gpt-5.6-terra": { "input_per_1m": 250, "output_per_1m": 1500, "cached_input_per_1m": 25, "cache_write_per_1m": 312.5, "selectable": true, "label": "GPT-5.6 Terra", "tier": "balanced" },
"openai/gpt-5.6-luna": { "input_per_1m": 25, "output_per_1m": 150, "cached_input_per_1m": 2.5, "cache_write_per_1m": 31.25, "selectable": true, "label": "GPT-5.6 Luna", "tier": "cheap" },
"openai/gpt-5.5": { "input_per_1m": 625, "output_per_1m": 3750, "cached_input_per_1m": 62.5, "selectable": true, "label": "GPT-5.5", "tier": "premium" },
"openai/gpt-5.4": { "input_per_1m": 312.5, "output_per_1m": 1875, "cached_input_per_1m": 31.25, "selectable": true, "label": "GPT-5.4", "tier": "balanced" }
}
},
"tiers": {
"starter": { "priceUsd": 5, "credits": 500 },
"pro": { "priceUsd": 30, "credits": 3000 },
"max": { "priceUsd": 100, "credits": 10000 }
},
"plans": [
{ "key": "starter", "title": "Starter", "priceUsd": 5, "monthlyCredits": 500, "diskMb": 250 },
{ "key": "pro", "title": "Pro", "priceUsd": 30, "monthlyCredits": 3000, "diskMb": 500 },
{ "key": "max", "title": "Max", "priceUsd": 100, "monthlyCredits": 10000, "diskMb": 1024 }
]
}
Read the response:
tiers→ the three plans: what your wallet is charged each month and the credits each one grants. The skills don't change these numbers.plans→ the same three plans as a list with their names (key,title,priceUsd,monthlyCredits) and their disk space in MB (diskMb).totalPriceUsdandtotalMonthlyCredits→ the plan you passed intier.tokenRates→ per-model token rates (credits per 1M input / output / cached-input tokens). Each conversation turn is metered against these (see token billing).skillBreakdown[]→ each skill withpriceUsd: 0, since every plan includes every skill.enabledSkills→ final closure (includes any transitively-enableddepends_on).
The plan sets the price. A custom build pays its plan's price whatever skills it has: $5 a month with 500 credits on Starter, $30 with 3,000 on Pro, $100 with 10,000 on Max. Per-turn conversation cost is metered separately against the agent's
tokenRates(see token billing).
Step 3: Deploy the Custom Agent
Send the same skill set you previewed to POST /UserAgent/Deploy with custom: true and useprepaid: true. The price of the plan you pass in tier is debited immediately.
curl -X POST "https://api.wiro.ai/v1/UserAgent/Deploy" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"custom": true,
"title": "Inbox Watcher",
"description": "Watches inbound Gmail and forwards a summary to Telegram every 4 hours.",
"useprepaid": true,
"tier": "pro",
"skills": {
"int-gmail-check": true,
"int-wordpress-post": true,
"int-wiro-aimodels": true
},
"credentials": {
"gmail": { "account": "agent@company.com", "apppassword": "xxxx xxxx xxxx xxxx" },
"telegram": {
"bottoken": "123456:ABC-DEF...",
"allowedusers": ["123456789"]
}
},
"customskills": [
{
"key": "cs-cron-summarize-inbox",
"value": "Every 4 hours, scan all unread Gmail messages from the past 4 hours, summarize each in 1 sentence, and post the digest to Telegram.",
"interval": "0 */4 * * *",
"enabled": true,
"_user_created": true,
"description": "Inbox summary digest"
}
]
}'
Response (excerpt)
{
"result": true,
"errors": [],
"useragents": [
{
"guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"agentguid": null,
"title": "Inbox Watcher",
"description": "Watches inbound Gmail and forwards a summary to Telegram every 4 hours.",
"tier": "pro",
"status": 2,
"setuprequired": false,
"monthlycredits": 3000,
"monthlypriceusd": 30,
"remainingcredits": 3000,
"renewalcredits": 3000,
"creditperiod": "2026-05",
"tokenRates": {
"default_model": "openai/gpt-5.6-sol",
"fallback_rate": { "input_per_1m": 625, "output_per_1m": 3750, "cached_input_per_1m": 62.5, "cache_write_per_1m": 781.25 },
"models": {
"openai/gpt-5.6-sol": { "input_per_1m": 625, "output_per_1m": 3750, "cached_input_per_1m": 62.5, "cache_write_per_1m": 781.25, "selectable": true, "label": "GPT-5.6 Sol", "tier": "premium" },
"openai/gpt-5.6-terra": { "input_per_1m": 250, "output_per_1m": 1500, "cached_input_per_1m": 25, "cache_write_per_1m": 312.5, "selectable": true, "label": "GPT-5.6 Terra", "tier": "balanced" },
"openai/gpt-5.6-luna": { "input_per_1m": 25, "output_per_1m": 150, "cached_input_per_1m": 2.5, "cache_write_per_1m": 31.25, "selectable": true, "label": "GPT-5.6 Luna", "tier": "cheap" },
"openai/gpt-5.5": { "input_per_1m": 625, "output_per_1m": 3750, "cached_input_per_1m": 62.5, "selectable": true, "label": "GPT-5.5", "tier": "premium" },
"openai/gpt-5.4": { "input_per_1m": 312.5, "output_per_1m": 1875, "cached_input_per_1m": 31.25, "selectable": true, "label": "GPT-5.4", "tier": "balanced" }
}
},
"agentModel": {
"chatModel": "openai/gpt-5.6-sol",
"cronModel": "openai/gpt-5.4-mini",
"voicePrepModel": "openai/gpt-5.4-mini",
"voicePostcallModel": "openai/gpt-5.4"
},
"skills": ["int-gmail-check", "int-wordpress-post", "int-wiro-aimodels"],
"customskills": [],
"scheduledskills": [
{
"key": "cs-cron-summarize-inbox",
"value": "Every 4 hours, scan all unread Gmail messages from the past 4 hours, summarize each in 1 sentence, and post the digest to Telegram.",
"interval": "0 */4 * * *",
"enabled": true,
"_source": "user-created",
"_editable": true,
"_user_created": true
}
],
"communicationChannels": [
{ "id": "telegram", "credentialkey": "telegram", "title": "Telegram", "required_fields": ["bottoken", "allowedusers"], "enabled": true, "configured": true, "missingfields": [] }
],
"enabledChannels": ["telegram"],
"teamsessionmode": "private",
"credentials": {
"gmail": { "_connected": false, "optional": false, "extra": false, "account": "agent@company.com", "apppassword": "••••••••" },
"telegram": { "_connected": false, "optional": false, "extra": false, "bottoken": "••••••••", "allowedusers": ["123456789"] }
},
"agent": {
"custom": true,
"title": "Inbox Watcher",
"tiers": {
"starter": { "priceUsd": 5, "credits": 500 },
"pro": { "priceUsd": 30, "credits": 3000 },
"max": { "priceUsd": 100, "credits": 10000 }
},
"plans": [
{ "key": "starter", "title": "Starter", "priceUsd": 5, "monthlyCredits": 500, "diskMb": 250 },
{ "key": "pro", "title": "Pro", "priceUsd": 30, "monthlyCredits": 3000, "diskMb": 500 },
{ "key": "max", "title": "Max", "priceUsd": 100, "monthlyCredits": 10000, "diskMb": 1024 }
],
"extracreditpacks": [
{ "packkey": "small", "credits": 1000, "priceusd": 10, "enabled": true },
{ "packkey": "medium", "credits": 5000, "priceusd": 50, "enabled": true },
{ "packkey": "large", "credits": 20000, "priceusd": 200, "enabled": true }
]
}
}
]
}
Notes on the response:
agentguid: nullconfirms this is a custom build with no marketplace template.agent.custom: trueis the synthesized template placeholder. Same shape as a template'sagentblock but noslug/cover/categories(custom builds aren't in the marketplace).scheduledskillsalready contains the cron from the Deploy body. Deploy stores eachcustomskillskey in its full form, asCustomSkillUpsertdoes: a bare slug with anintervalbecomescs-cron-<slug>, one without becomescs-<slug>, and a key that isn't a slug fails the deploy before anything is created or charged.status: 2means Deploy auto-queued the instance becauseuseprepaid: trueprovisioned a subscription in the same call. Wiro starts the agent from the queue; you do not need to callPOST /UserAgent/Startafter a prepaid deploy.- Communication-channel credentials are validated independently from
skills. Every channel group present incredentialsmust contain all of itsrequired_fieldsor Deploy fails without leaving a partial agent behind. - The Gmail app password and the Telegram bot token you sent come back as
"••••••••": likeUserAgent/Detail, the response shows a saved secret only as the mask.
Step 4: Refine Skills After Deploy
Toggle skills on/off after deploy with POST /UserAgent/SkillsApply. Even when you only want to flip a single skill, send it as a one-entry skills map. The endpoint triggers exactly one agent restart, applies the whole batch or none of it, and never charges: every plan includes every skill, so the price and the credits stay the same. Template deploys accept the same call.
Single-skill enable
curl -X POST "https://api.wiro.ai/v1/UserAgent/SkillsApply" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"idempotencyKey": "550e8400-e29b-41d4-a716-446655440001",
"skills": {
"int-instagram-post": true
}
}'
The response confirms the skill set and the restart:
{
"result": true,
"errors": [],
"tier": "pro",
"restartTriggered": true,
"restartedAt": 1714694520,
"stripeProrationApplied": false,
"prepaidWalletDelta": null,
"usedCreditsUsd": 0,
"pricing": {
"previousPriceUsd": 30,
"newPriceUsd": 30,
"delta": 0,
"deltaUsd": 0,
"previousMonthlyCredits": 3000,
"newMonthlyCredits": 3000,
"deltaCredits": 0,
"creditsNow": 0,
"creditsThisPeriod": 3000,
"creditsFromRenewal": 3000,
"periodEnd": null,
"stripeProrationApplied": false,
"prepaidWalletDelta": null,
"usedCreditsUsd": 0,
"enabledSkills": ["int-gmail-check", "int-wordpress-post", "int-wiro-aimodels", "int-instagram-post"]
}
}
tier stays the agent's plan: a skill change never moves it, and nothing is charged.
Batch toggle in one call
When the user stages many toggles in your UI and commits them all together, send everything in one SkillsApply call:
curl -X POST "https://api.wiro.ai/v1/UserAgent/SkillsApply" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
"skills": {
"int-gmail-check": true,
"int-wordpress-post": true,
"int-wiro-aimodels": true,
"int-instagram-post": true,
"int-metaads-manage": false
}
}'
idempotencyKey is required: use a UUID per "user clicks Save" event. A retry of the same key returns the cached response without applying the change again. To change the plan, call UpgradeTier; SkillsApply refuses a tier other than the agent's current plan.
Common Recipes
A. Email-driven Telegram digest
{
"custom": true,
"title": "Email Digest Bot",
"useprepaid": true,
"tier": "starter",
"skills": { "int-gmail-check": true, "int-wordpress-post": true },
"credentials": {
"gmail": { "account": "agent@company.com", "apppassword": "xxxx xxxx xxxx xxxx" },
"telegram": { "bottoken": "123456:ABC-DEF...", "allowedusers": ["123456789"] }
},
"customskills": [
{
"key": "cs-cron-email-digest",
"value": "Twice a day, summarize unread Gmail messages in one Telegram message.",
"interval": "0 9,17 * * *",
"enabled": true,
"_user_created": true,
"description": "Daily email digest"
}
]
}
B. WordPress publisher with weekly research
{
"custom": true,
"title": "Blog Research & Publish",
"useprepaid": true,
"tier": "pro",
"skills": { "int-wordpress-post": true, "int-wiro-aimodels": true },
"credentials": {
"wordpress": { "url": "https://blog.example.com", "user": "admin", "apppassword": "xxxx xxxx xxxx xxxx" },
"var-website": { "urls": "[{\"websitename\":\"Wired\",\"url\":\"https://www.wired.com/feed/rss\"}]" }
},
"customskills": [
{
"key": "cs-content-strategy",
"value": "## Writing Style\nShort, punchy, technical. Always include code examples.\n\n## Sources\nWired, ArsTechnica, Hacker News.\n\n## Cadence\nOne 600-word article every Monday.",
"_user_created": false
},
{
"key": "cs-cron-weekly-blog",
"value": "Every Monday morning, scan the websites listed under your var-website credential, draft one 600-word article, and publish to WordPress as a draft.",
"interval": "0 9 * * 1",
"enabled": true,
"_user_created": true,
"description": "Weekly WordPress publish"
}
]
}
C. Multi-channel social poster
{
"custom": true,
"title": "Cross-Channel Social",
"useprepaid": true,
"tier": "pro",
"skills": {
"int-twitterx-post": true,
"int-instagram-post": true,
"int-linkedin-post": true,
"int-facebookpage-post": true,
"int-wiro-aimodels": true
},
"credentials": {}
}
OAuth providers are connected later via POST /UserAgentOAuth/OAuthConnect with the provider's credentialkey (see Agent Credentials).
Subscription & Billing for Custom Builds
Subscriptions for custom builds work exactly like template deploys:
- A 30-day prepaid subscription row (
plan: "agent",tier: <starter|pro|max>,provider: "prepaid") is inserted at Deploy. POST /UserAgent/CancelSubscriptionschedules cancel-at-period-end.POST /UserAgent/RenewSubscriptioneither undoes a pending cancel (no charge) or creates a fresh 30-day period (wallet charged).POST /UserAgent/UpgradeTierchanges the plan: a higher plan starts now with a prorated wallet debit, a lower plan (sent withallowDowngrade: true) at the next renewal.
Turning a skill on or off never changes the subscription: the plan's price and credits stay the same (see Step 4 above).
Limits & Notes
- A build costs its plan's price, whatever its skills. One skill or twenty, Starter is $5 a month with 500 credits, Pro $30 with 3,000 and Max $100 with 10,000.
- Conflict / dependency violations are surfaced eagerly. If you toggle on two mutually-exclusive skills,
SkillsApplyreturns code102with aconflicts[]array; if adepends_onis missing, code101withdeps[]. Resolve in the UI before committing. - Custom builds receive the same auto-restart on configuration changes as template deploys (status
3/4→ status1, then re-queued). - Cover image: custom builds can ship a
coverURL in the Deploy body, or upload one later viaPOST /UserAgent/Cover. - The agent's persona is editable via the standard
customskillsflow. Add acs-personastrategy viaCustomSkillUpsertto set the agent's voice, role, and constraints.
What's Next
- Agent Skills: Discover the skill registry, browse credentials per skill, and configure preferences + scheduled tasks
- Agent Credentials: Connect OAuth providers and set API-key credentials
- Agent Messaging: Chat with your custom agent
- Agent Transactions: Audit credit deductions, renewals, and grants
Agent Transactions
Per-instance credit ledger: every credit deduction, renewal, purchase, refund, grant, and cancel for a useragent in a single immutable feed.
Overview
Wiro keeps a complete, append-only agent transaction ledger for every UserAgent instance. Whenever credits move (the agent runtime burns them on a chat turn, a subscription renews, the user buys an extra-credit pack or moves to a higher plan mid-period), a row is inserted into the ledger and surfaced through POST /UserAgent/TransactionList.
The ledger is the single source of truth for "where did my credits go?" and powers the Transactions view in your dashboard.
Transaction type |
Source | When it fires |
|---|---|---|
deduct |
Agent runtime | Per-turn LLM token charge (action: "tokens") for every chat, cron, and voice post-call turn. Negative amount. |
renewal |
Subscription cron | At each 30-day rollover when the wallet successfully covers the renewal. Positive amount = monthly credits granted. |
purchase |
Extra-credit checkout | When POST /UserAgent/CreateExtraCreditCheckout (useprepaid: true) succeeds. Positive amount = pack credits. |
grant |
Plan change / skill change | When a move to a higher plan lifts this period's credits. Positive amount: what this period gained. metadata.creditsFromRenewal is what each renewal grants. A skill change through SkillsApply or SkillToggle also writes a grant row with amount: 0: action: "skill-toggle" (metadata: { skill, enabled }) or "skills-apply" (metadata: { diff, idempotencyKey }). A skill change row with a non-zero amount or a metadata.usedCreditsUsd is from before skill changes became free. |
expired |
Subscription end | When a cancelled subscription rolls past currentperiodend and the cron revokes any remaining monthly leftover (action: "subscription"). Negative amount. Rows from before skill changes became free can also come from a skill turned off mid-period (action: "skill-toggle" or "skills-apply", with metadata.usedCreditsUsd). |
refund |
Server-side refund | Issued by Wiro support when a previous charge is reversed. Positive amount. |
adjust |
Wiro support | A record for Wiro support. Rows with amount: 0 and action: "skill-change-not-undone" (a failed skill change that could not be taken back) or "skill-credit-failed" (a skill credit that was not added to the wallet) are from before skill changes became free. |
guid that the server uses for deduplication (so a duplicate retry of the same deduct event is a no-op).POST /UserAgent/TransactionList
Returns the ledger rows for a single useragent sorted newest-first, plus a snapshot summary of the current balance.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | The useragent instance guid. |
limit |
number | No | Max rows to return. Default 50, max 500. |
start |
number | No | Offset for pagination. Default 0. |
Authorization: the agent's owner, a team admin of the agent's team or the organization owner (plain team members are rejected with code 97). No extra header is needed.
Request
curl -X POST "https://api.wiro.ai/v1/UserAgent/TransactionList" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "limit": 50 }'
Response
{
"result": true,
"errors": [],
"total": 312,
"summary": {
"monthlycredits": 3000,
"extracredits": 5000,
"usedcredits": 1450,
"remainingcredits": 6550,
"renewalcredits": 3000,
"creditperiod": "2026-05",
"creditsyncat": 1714694410,
"byModel": [
{ "model": "openai/gpt-5.4", "inputtokens": 1011250, "outputtokens": 241300, "cachereadtokens": 149800, "cachewritetokens": 0, "totaltokens": 1402350, "tokencost": 1443, "turncount": 288 },
{ "model": "unknown", "inputtokens": 4200, "outputtokens": 900, "cachereadtokens": 0, "cachewritetokens": 0, "totaltokens": 5100, "tokencost": 7, "turncount": 3 }
]
},
"transactions": [
{
"guid": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e01",
"type": "deduct",
"action": "tokens",
"amount": -5,
"balanceafter": null,
"description": "LLM openai/gpt-5.4 (uncached in 3450, cached in 512, out 820, total 4782 tokens)",
"sessionkey": "default",
"agentsessionkey": "default",
"messageguid": "5d6e7f80-9a1b-4c2d-8e3f-4a5b6c7d8e01",
"inputtokens": 3450,
"outputtokens": 820,
"cachereadtokens": 512,
"cachewritetokens": 0,
"totaltokens": 4782,
"tokencost": 5,
"processedms": 4120,
"model": "openai/gpt-5.4",
"provider": "agent",
"providerref": null,
"metadata": null,
"uuid": "ada-uuid",
"user": {
"uuid": "ada-uuid",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"username": "ada",
"avatar": "https://cdn.wiro.ai/avatars/ada.webp",
"avatarinitials": "AL"
},
"createdat": 1714694400
},
{
"guid": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e02",
"type": "purchase",
"action": "medium",
"amount": 5000,
"balanceafter": 6555,
"description": "Extra credits — medium (wallet)",
"sessionkey": null,
"messageguid": null,
"inputtokens": null,
"outputtokens": null,
"cachereadtokens": null,
"cachewritetokens": null,
"totaltokens": null,
"tokencost": null,
"processedms": null,
"model": null,
"provider": "prepaid",
"providerref": null,
"metadata": { "price": 50, "currency": "usd" },
"uuid": "ada-uuid",
"user": {
"uuid": "ada-uuid",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"username": "ada",
"avatar": "https://cdn.wiro.ai/avatars/ada.webp",
"avatarinitials": "AL"
},
"createdat": 1714692800
},
{
"guid": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e03",
"type": "renewal",
"action": "monthly",
"amount": 3000,
"balanceafter": 3000,
"description": "Subscription renewal",
"sessionkey": null,
"messageguid": null,
"inputtokens": null,
"outputtokens": null,
"cachereadtokens": null,
"cachewritetokens": null,
"totaltokens": null,
"tokencost": null,
"processedms": null,
"model": null,
"provider": "prepaid",
"providerref": null,
"metadata": { "period": "2026-05", "priceUsd": 30 },
"uuid": "ada-uuid",
"user": {
"uuid": "ada-uuid",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"username": "ada",
"avatar": "https://cdn.wiro.ai/avatars/ada.webp",
"avatarinitials": "AL"
},
"createdat": 1714608000
},
{
"guid": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e04",
"type": "grant",
"action": "tier-change",
"amount": 1250,
"balanceafter": 1430,
"description": "Plan Starter to Pro",
"sessionkey": null,
"messageguid": null,
"inputtokens": null,
"outputtokens": null,
"cachereadtokens": null,
"cachewritetokens": null,
"totaltokens": null,
"tokencost": null,
"processedms": null,
"model": null,
"provider": "prepaid",
"providerref": null,
"metadata": {
"fromTier": "starter",
"toTier": "pro",
"previousPriceUsd": 5,
"newPriceUsd": 30,
"proratedCharge": 12.5,
"creditsFromRenewal": 3000
},
"uuid": "ada-uuid",
"user": {
"uuid": "ada-uuid",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"username": "ada",
"avatar": "https://cdn.wiro.ai/avatars/ada.webp",
"avatarinitials": "AL"
},
"createdat": 1712880000
}
]
}
The user object is the resolved actor that triggered the ledger entry: uuid, firstname, lastname, email, username, avatar, avatarinitials. Every row is recorded for an account uuid (renewals, expiry sweeps and other automated rows carry the agent owner's), so user is null only when that user record has been deleted.
Summary fields
| Field | Type | Description |
|---|---|---|
monthlycredits | number | The credits this period grants. |
renewalcredits | number | The credits a renewal grants on the agent's current plan. When the agent has a nextplan (on UserAgent/Detail), the next renewal grants that plan's credits instead. |
extracredits | number | Active extra-credit balance (sum of non-expired packs). |
usedcredits | number | Consumed during the current period (reported by the runtime). |
remainingcredits | number | max(0, monthlycredits + extracredits - usedcredits). |
creditperiod | string | 'YYYY-MM' billing window. Rolls over on subscription renewal. |
creditsyncat | number|null | Unix seconds of the last monthly usage reset, the start of the current credit period; byModel counts turns from this moment on (null until the first reset). |
extrapacks | array | The agent's extra-credit packs: { id, credits, remainingcredits, status, provider, purchasedat, expiresat }. Active packs are used oldest first. |
byModel | array | Per-model token rollup for the current billing period, aggregating only action: "tokens" rows, sorted by tokencost descending. A null or empty model is bucketed as "unknown". Each entry: { model, inputtokens, outputtokens, cachereadtokens, cachewritetokens, totaltokens, tokencost, turncount }. Within a period that stays inside monthlycredits, the tokencost values add up to usedcredits; credits spent from extra packs are counted here but come off extracredits instead. |
Transaction fields
| Field | Type | Description |
|---|---|---|
guid | string | Stable id of the ledger row. Daemon retries reuse this guid for idempotency. |
type | string | One of "deduct", "renewal", "purchase", "grant", "expired", "refund", "adjust". There is no "cancel" type: a user-initiated subscription cancel only flips auto-renew off; credits are not forfeited until currentperiodend is reached, at which point the cron writes the ledger row as type: "expired", action: "subscription". |
action | string|null | Fine-grained detail. Values depend on type: "tokens" (deduct: the per-turn LLM token charge Wiro records for every chat, cron, and voice post-call turn); "monthly" (renewal); "small", "medium", "large" (purchase); "upgrade", "tier-change" (grant: a move to a higher plan); "skill-toggle", "skills-apply" (grant: a skill change, with amount: 0; grant or expired rows with a non-zero amount are from before skill changes became free); "subscription" (expired, end-of-period cancel rollover; refund); "skill-change-not-undone", "skill-credit-failed" (adjust, rows from before skill changes became free). Legacy deduct rows may also carry "message", "create", "modify", or "regenerate". |
amount | number | Signed credit delta: negative for deductions, positive for grants. |
balanceafter | number|null | Remaining credit balance snapshot written at the time of the event. null on per-turn deduct rows. |
description | string|null | Human-readable label. On an action: "tokens" row it spells the counts out: LLM <model> (uncached in N, cached in N, out N, cache write N, total N tokens), where cached in and cache write appear only above 0. |
sessionkey | string|null | Session the deduct belongs to (deduct rows only). |
agentsessionkey | string|null | Alias of sessionkey (same value), present on every row for a unified per-session attribution key across TaskList / TransactionList / wallet responses. |
messageguid | string|null | Agent message that triggered the deduct (deduct rows only). |
inputtokens | number|null | Uncached prompt tokens billed at the model's input rate (action: "tokens" rows only). |
outputtokens | number|null | Completion tokens billed for the turn (action: "tokens" rows only). |
cachereadtokens | number|null | Prompt tokens served from cache for the turn (action: "tokens" rows only). |
cachewritetokens | number|null | Prompt tokens written to cache for the turn (action: "tokens" rows only). |
totaltokens | number|null | Exact inputtokens + outputtokens + cachereadtokens + cachewritetokens sum (action: "tokens" rows only). |
tokencost | number|null | Credit cost for the turn; equals abs(amount) (action: "tokens" rows only). |
processedms | number|null | Model processing time for the turn, in milliseconds (action: "tokens" rows only). |
model | string|null | Model id that served the turn, e.g. "openai/gpt-5.4" (action: "tokens" rows only). |
provider | string|null | "agent" (runtime deduct) or "prepaid" (wallet-backed change). API-deployed agents always run on the prepaid path. |
providerref | string|null | Provider-side reference id. Always populated for prepaid rows (wallet transaction id); null for agent runtime deducts. |
metadata | object|null | Arbitrary JSON context attached at write time (plan change, period, prorated charge, …). |
uuid | string|null | UUID of the account the row is recorded for: the user who acted, or the agent\'s owner for renewals and other automated rows. Never a "system" placeholder. |
user | object|null | Resolved actor: { uuid, firstname, lastname, email, username, avatar, avatarinitials }. null when the user record was deleted. |
createdat | number | Unix seconds. |
total so you can render a precise paginator. Default page size is 50, max is 500. Use start to skip rows.Reading the Ledger: Patterns
Daily / weekly reports
Filter client-side on createdat to bucket transactions per day or per skill:
import requests
from collections import defaultdict
from datetime import datetime
resp = requests.post(
"https://api.wiro.ai/v1/UserAgent/TransactionList",
headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
json={"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "limit": 500}
).json()
per_day_burn = defaultdict(int)
for tx in resp["transactions"]:
if tx["type"] == "deduct":
day = datetime.utcfromtimestamp(tx["createdat"]).strftime("%Y-%m-%d")
per_day_burn[day] += abs(tx["amount"])
for day in sorted(per_day_burn):
print(f"{day}: {per_day_burn[day]} credits")
Audit a billing-period rollover
type: "renewal" rows are written exactly once per billing-period rollover. Pair them with the most recent summary.creditperiod to confirm the new period started on time.
const renewals = transactions.filter(t => t.type === 'renewal');
const lastRenewal = renewals[0]; // newest-first ordering
console.log('Last renewal:', new Date(lastRenewal.createdat * 1000).toISOString());
console.log('Granted:', lastRenewal.amount, 'credits');
console.log('Now in period:', summary.creditperiod);
Reconcile a plan change
When the user moves to a higher plan mid-period, the ledger gets one grant row for the credits the move added to this period. For a wallet-billed (prepaid) agent, UpgradeTier writes action: "tier-change" with those credits as amount (the monthly difference for the time left in the period), a description like "Plan Pro to Max" and metadata: { fromTier, toTier, previousPriceUsd, newPriceUsd, proratedCharge, creditsFromRenewal }; a card-billed upgrade writes action: "upgrade". A move to a lower plan takes effect at the renewal, and that renewal row grants the lower plan's credits. Use these rows to render a plan history in your UI.
Errors
| Error | When |
|---|---|
useragentguid is required | TransactionList without useragentguid |
useragent-access-denied | Caller is neither the owner nor on the agent's team |
useragent-team-admin-required | Caller is a member of the agent's team but not a team admin (code 97) |
Invalid credentials | API key is missing or doesn't resolve to a valid Wiro user |
transactions-list-failed | TransactionList server-side error (DB): surfaced loudly so it's distinguishable from "empty ledger" |
Code Examples
curl
# Latest 50 transactions for a useragent
curl -X POST "https://api.wiro.ai/v1/UserAgent/TransactionList" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "limit": 50 }'
# Page 2 (next 50)
curl -X POST "https://api.wiro.ai/v1/UserAgent/TransactionList" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "limit": 50, "start": 50 }'
Python
import requests
headers = {"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"}
resp = requests.post(
"https://api.wiro.ai/v1/UserAgent/TransactionList",
headers=headers,
json={"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "limit": 100}
).json()
print(f"Balance — remaining: {resp['summary']['remainingcredits']}/{resp['summary']['monthlycredits']}")
print(f"Total ledger rows: {resp['total']}")
for tx in resp["transactions"][:10]:
sign = "+" if tx["amount"] > 0 else ""
print(f" [{tx['type']:>9}] {sign}{tx['amount']:>6} {tx['description']}")
Node.js
const axios = require('axios');
const headers = { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' };
const { data } = await axios.post(
'https://api.wiro.ai/v1/UserAgent/TransactionList',
{ useragentguid: 'f8e7d6c5-b4a3-2190-fedc-ba0987654321', limit: 100 },
{ headers }
);
console.log(`Balance: ${data.summary.remainingcredits}/${data.summary.monthlycredits}`);
console.log(`Period: ${data.summary.creditperiod}`);
data.transactions.slice(0, 10).forEach(tx => {
const sign = tx.amount > 0 ? '+' : '';
console.log(` [${tx.type.padStart(9)}] ${sign}${tx.amount} ${tx.description}`);
});
PHP
<?php
$ch = curl_init("https://api.wiro.ai/v1/UserAgent/TransactionList");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Content-Type: application/json",
"x-api-key: YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
"useragentguid" => "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
"limit" => 100
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$resp = json_decode(curl_exec($ch), true);
curl_close($ch);
echo "Balance: {$resp['summary']['remainingcredits']}/{$resp['summary']['monthlycredits']}\n";
foreach (array_slice($resp['transactions'], 0, 10) as $tx) {
$sign = $tx['amount'] > 0 ? '+' : '';
echo "[{$tx['type']}] {$sign}{$tx['amount']} {$tx['description']}\n";
}
What's Next
- Agent Logs: Activity feed (tool calls, cron runs, message exchanges) for the same useragent
- Agent Overview: Full agent endpoint catalog, including subscription / billing operations
- Agent Builder: Build a custom agent and watch the ledger fill up as it runs
Agent Logs
Per-instance activity feed (tool calls, scheduled cron runs, message exchanges, and turn boundaries) for any deployed agent.
Overview
Every Wiro agent appends one structured ActivityEvent JSON line per tool call, LLM turn boundary, scheduled task run and billed turn, plus each message that arrives on a connected Telegram, Slack or Discord channel. Secrets (matched by field name and by high-entropy value), internal tool-call IDs and API credentials are redacted before an event is written, so what shows up in Logs is safe to show end users.
A daily JSONL file is written for each calendar day; files older than 7 days are gzipped, files older than 180 days are deleted by the agent's daily maintenance cron.
The feed also lists what people and API keys did to the agent: starts and stops, renames, skill, connector and billing changes, connections, Screen views and Take Control sessions, browser resets, and deleted log days, each with who did it. These who-did-what rows don't depend on the agent running.
The endpoints below are owner-or-team-admin scoped. Plain members of the agent's team receive useragent-team-admin-required (code 97); outside callers receive useragent-access-denied.
| Endpoint | Purpose |
|---|---|
POST /UserAgent/Logs | Live tail (last N events for today, or a specific date). Poll it every 30 seconds or more. |
POST /UserAgent/LogsList | List the days (YYYY-MM-DD) that have activity, with the size of each day's log. |
POST /UserAgent/LogsFile | Read the full log of a specific date. |
POST /UserAgent/LogsDelete | Delete the agent's own turns and tool calls for one date. Idempotent. |
POST /UserAgent/RunStreamToken | Get a token for following the agent's Scheduled Tasks, background runs and model runs live on the Agent WebSocket, instead of polling Logs. |
Message/History. Message/History is a chat-bubble-level read of the conversation. Logs is a runtime view: every tool call, every turn and every scheduled task run. They serve different audiences (Message/History for end users, Logs for operators / power users).ActivityEvent Shape
Every event is a JSON object with this base shape:
{
"ts": "2026-05-03T14:00:10.234Z",
"kind": "tool_completed",
"tool": "web_fetch",
"title": "Fetched https://blog.example.com/weekly-roundup-12",
"summary": {
"url": "https://blog.example.com/weekly-roundup-12",
"status": 200,
"bytes": 18432
},
"durationMs": 1840,
"ok": true,
"userUuid": "ada-uuid",
"user": {
"uuid": "ada-uuid",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"username": "ada",
"avatar": "https://cdn.wiro.ai/avatars/ada.webp",
"avatarinitials": "AL"
}
}
| Field | Type | Description |
|---|---|---|
ts | string | ISO-8601 UTC datetime when the event was recorded (e.g. "2026-05-03T14:00:10.234Z"). Parse with Date.parse(ts) for arithmetic. |
kind | string | Fine-grained event class. One of: "turn_started", "turn_ended" (an LLM turn boundary); "tool_started", "tool_completed" (one pair per tool call); "tool_blocked" (a tool call the agent's safety rules refused); "cron_finished" (a scheduled task finished); "user_message" (a message received on a connected Telegram, Slack or Discord channel, not web chat); "token_usage" (a billed turn's token usage: chat / cron / voice post-call); "token_usage_idempotent" (a replayed usage report, already billed, informational only); "media_relay" (files from a reply were delivered); "background_reply" (a result that finished in the background was delivered to the chat). Rows about what was done to the agent have AGENT_* kinds, and two note rows, "runtime_log_unavailable" and "runtime_log_deleted", say what part of a day is missing. Show any kind you don't recognize by its title. |
tool | string? | Present on tool_started / tool_completed / tool_blocked. The name of the tool the agent used. |
toolintegration | string? | On tool_started and tool_completed when the step works in a connector: the connector's key, for example "wordpress". Same closed list as on timeline tool blocks. |
toolaction | string? | On tool_started and tool_completed when a word fits the step: what it does, for example "click". Same closed list as on timeline tool blocks. Never set together with toolintegration. |
title | string | Human-readable one-line description of what happened (e.g. "Posted carousel: \"Brand voice teaser\"", "Fetched https://…", "Token Usage"). Always present. |
summary | object? | Structured event-specific payload. Opaque on the wire, so render it as JSON when expanding the row. Secret values (apikey, apppassword, clientsecret, bearer, token, …) are masked before the event is written. Common keys: file, method, host, path, preview, messageCount, jobId, status, reason. |
durationMs | number? | Wall-clock duration in milliseconds. Populated on tool_completed, turn_ended, cron_finished and token_usage events. |
ok | boolean? | true for a successful completion, false for a failure. Populated on tool_completed, turn_ended and cron_finished events, and always false on tool_blocked. Pair with error for failure rows. It is always true on AGENT_* rows. A turn_ended for a turn the caller cancelled has no ok, and its title reads Agent turn cancelled. A cron_finished for a Scheduled Task run that the agent's spend limit or Model Access rule paused has no ok either, and its title starts with Paused by a spend limit: or Paused by a Model Access rule:. |
error | string? | One-line failure message (when ok: false). |
cost | object? | Legacy per-action credit charge, { credits, skill, action }. Only events recorded before agents switched to per-turn token billing can carry it; current events never do. See the token_usage event for what a turn cost. |
userUuid | string? | UUID of the actor who triggered the event. "system" for cron / internal events. May be missing on older rows, in which case the server falls back to the agent owner. |
user | object|null | Resolved actor: { uuid, firstname, lastname, email, username, avatar, avatarinitials }. null when userUuid is "system" (automation / cron) or when the user record was deleted. |
summary for? Tool events carry a short summary of the call: for example the file path for file tools, the program for exec, or the method, host and path for web requests. Turn events carry a short preview (plus messageCount on turn_ended); cron_finished carries { jobId, status }, plus reason (spend_limit or model_access) when status is paused; user_message carries { preview }; tool_blocked carries the reason. Treat the object as opaque and render-on-expand, since its shape depends on the tool and may change without a docs revision.To tell what a tool call is doing, read toolintegration and toolaction instead of parsing title or summary. Both are missing when no word fits the step, and tool_blocked events don't carry them.
Token-usage events
A token_usage event records the token spend and credit deduction for one billed turn: a chat reply, a cron run, or a voice post-call. A token_usage_idempotent event carries the same shape for a replayed usage callback that was already billed (informational; it does not deduct again). On top of the base ActivityEvent fields, these events add:
| Field | Type | Description |
|---|---|---|
model | string | Canonical model slug that served the turn (e.g. "openai/gpt-5.4"). |
tokens | object | Nested token counts in camelCase: { input, output, cacheRead, cacheWrite, total } (each an integer). |
tokencost | number | Credits deducted for the turn (1 credit = $0.01). |
durationMs | number | Wall-clock duration of the turn in milliseconds. |
calls | number | Number of LLM calls made during the turn. |
remainingcredits | number | Credit pool remaining after the deduction. |
{
"ts": "2026-05-03T14:02:55.310Z",
"kind": "token_usage",
"title": "Token Usage",
"model": "openai/gpt-5.4",
"tokens": { "input": 3450, "output": 820, "cacheRead": 2400, "cacheWrite": 0, "total": 6670 },
"tokencost": 5,
"durationMs": 4200,
"calls": 2,
"remainingcredits": 9995,
"userUuid": "system",
"user": null
}
token_usage event nests its counts in camelCase under tokens.{input, output, cacheRead, cacheWrite, total}. input is uncached input and total is the exact sum of all four components. This is distinct from the flat, lowercase columns on message rows (inputtokens, outputtokens, cachereadtokens, …). Same underlying data, different shape.token_usage event is one billed turn, and its tokencost is in credits (100 credits = $1). A Wiro model the agent runs, for example through int-wiro-aimodels, is billed separately: Wiro charges it to the wallet of the workspace that owns the agent's Wiro API key at the model's usual price, passed through unchanged. That run shows up as an ordinary tool_completed event with no credit figure; its cost is the task's totalcost (see Billing & Cost).Who-did-what rows
Logs and LogsFile also return what people and API keys did to the agent, and LogsList lists the days that have such rows. These rows sit in the same events list, in time order, with an AGENT_* value in kind. They come on top of the kinds above, which keep their meaning.
{
"ts": "2026-05-03T09:12:44.000Z",
"kind": "AGENT_RENAMED",
"title": "Agent renamed from \"Inbox Bot\" to \"Inbox Watcher\"",
"ok": true,
"summary": { "title": "Inbox Watcher", "previoustitle": "Inbox Bot", "fields": ["title"] },
"userUuid": "ada-uuid",
"user": {
"uuid": "ada-uuid",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"username": "ada",
"avatar": "https://cdn.wiro.ai/avatars/ada.webp",
"avatarinitials": "AL"
}
}
title is the line to show. summary holds the names and amounts behind it, never a connector value. userUuid and user name who did it. When an API key made the change, the title ends with (API key "<project name>") or (via API key).
kind | Example title |
|---|---|
AGENT_STARTED, AGENT_STOPPED, AGENT_RESTARTED | Agent started, Agent stopped, Agent restarted |
AGENT_RENAMED | Agent renamed from "Inbox Bot" to "Inbox Watcher" |
AGENT_UPDATED | Agent details updated: description, cover |
AGENT_SETTINGS_UPDATED | Agent settings updated: timezone Europe/Istanbul, Agent settings updated: screen off |
AGENT_TRANSFERRED | Agent moved to a team workspace, Agent moved to the personal workspace; the system's rows when the agent's team or organization is deleted read Agent moved to the personal workspace: its team was deleted and Agent moved to the personal workspace: its organization was deleted |
AGENT_INSTRUCTION_ADDED, AGENT_INSTRUCTION_UPDATED, AGENT_INSTRUCTION_RENAMED, AGENT_INSTRUCTION_DELETED, AGENT_INSTRUCTION_REVERTED | Custom skill added: cs-brand-voice, Scheduled task updated: cs-cron-blog-scanner (text, schedule 0 9 * * 1), Custom skill renamed: cs-brand-voice to cs-house-style, Scheduled task deleted: cs-cron-blog-scanner, Custom skill reverted to its preset: cs-brand-voice |
AGENT_SKILLS_UPDATED | Connectors updated: int-gmail-check on, Skills updated: util-web-channel off, Connectors and skills updated: int-gmail-check on, util-web-channel off |
AGENT_CREDENTIAL_SAVED | Connector setting saved: wiro.apikey |
AGENT_CREDENTIAL_REMOVED | Disconnected: serper (a disconnect card from chat removed the connector’s saved key) |
AGENT_OAUTH_CONNECT_STARTED, AGENT_OAUTH_CONNECTED, AGENT_OAUTH_DISCONNECTED | Connection started: instagram (own), Connected: instagram, Disconnected: instagram |
AGENT_PLAN_STARTED, AGENT_PLAN_RENEWED, AGENT_PLAN_CANCELLED, AGENT_PLAN_RESUMED | Starter plan started: $5.00 charged, Starter plan renewed: $5.00 charged, Plan cancelled, ends 2026-06-01, Plan cancellation undone |
AGENT_TIER_UPGRADED | Plan upgraded from Starter to Pro; $12.50 charged |
AGENT_PLAN_CHANGE_SCHEDULED, AGENT_PLAN_CHANGE_CANCELLED | Plan change scheduled: Pro to Starter on 2026-06-01, Scheduled plan change cancelled: stays on Pro |
AGENT_PLAN_MOVE_SCHEDULED | Moves to the Starter plan ($5.00 a month) on 2026-06-01 (an agent subscribed before the three plans) |
AGENT_CREDITS_PURCHASED | Extra credits bought: small pack, 1000 credits, $10.00 charged |
AGENT_CHECKOUT_CREATED | Card checkout link created: plan |
AGENT_LOG_DAY_DELETED | Activity log day deleted: 2026-05-02 |
AGENT_SCREEN_VIEWED, AGENT_SCREEN_CONTROLLED | Watched the agent's screen, Took control of the agent's screen |
AGENT_SCREEN_CONTROL_ENDED | Control of the agent's screen ended after 4 minutes 10 seconds: handed back (summary: { seconds, reason }; see Screen in the Activity Log) |
AGENT_BROWSER_RESET | Agent browser reset (see Resetting the Browser) |
AGENT_DISK_ALMOST_FULL, AGENT_DISK_FULL | Disk almost full: 210 MB of 250 MB used., Disk full: 260 MB of 250 MB used. The agent can't save new files until some are deleted. (see Disk Space) |
AGENT_DISK_TEMP_CLEARED, AGENT_DISK_HOST_RESTART | Temporary files passed 1 GB, so the agent restarted and cleared them., The agent restarted to clear its temporary files. (see Disk Space) |
Note rows
Two more kinds say what part of a day is missing. They are notes, so they carry a title and no ok.
kind | title | When |
|---|---|---|
runtime_log_unavailable | The agent's own turns and tool calls can be read while it runs | The agent isn't running, so only its who-did-what rows are listed. |
runtime_log_unavailable | The agent's own turns and tool calls could not be read just now | The agent's host did not answer. Read the day again later. |
runtime_log_deleted | The agent's own turns and tool calls for this day were deleted on 2026-05-04 | The day's log was deleted on a later day with LogsDelete. The day's who-did-what rows follow it. |
POST /UserAgent/Logs
Live tail of the agent's activity feed. Returns the last N events for the requested date (defaults to today).
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid | string | Yes | Your UserAgent instance guid. |
date | string | No | YYYY-MM-DD to read a specific day's file. Default: today (UTC). |
lines | number | No | Max events to return (max 5000). Default: 200. |
Polling: leave 30 seconds or more between repeated polls.
Request
curl -X POST "https://api.wiro.ai/v1/UserAgent/Logs" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "lines": 200 }'
Response
{
"result": true,
"errors": [],
"date": "2026-05-03",
"totalLines": 1428,
"events": [
{
"ts": "2026-05-03T14:02:55.310Z",
"kind": "token_usage",
"title": "Token Usage",
"model": "openai/gpt-5.4",
"tokens": { "input": 3450, "output": 820, "cacheRead": 2400, "cacheWrite": 0, "total": 6670 },
"tokencost": 5,
"durationMs": 4200,
"calls": 2,
"remainingcredits": 9995,
"userUuid": "system",
"user": null
},
{
"ts": "2026-05-03T14:02:54.902Z",
"kind": "tool_completed",
"tool": "exec",
"toolintegration": "wiro",
"title": "POST api.wiro.ai/v1/Run/google/nano-banana",
"summary": {
"method": "POST",
"host": "api.wiro.ai",
"path": "/v1/Run/google/nano-banana",
"headers": ["Content-Type: application/json", "x-api-key: ***"],
"body": { "prompt": "A paper boat on a calm lake at sunrise" }
},
"durationMs": 640,
"ok": true,
"userUuid": "system",
"user": null
},
{
"ts": "2026-05-03T14:00:10.305Z",
"kind": "tool_completed",
"tool": "exec",
"title": "Posted: \"Weekly Roundup\"",
"summary": {
"title": "Weekly Roundup",
"url": "https://blog.example.com/weekly-roundup-12",
"categories": ["AI", "Tutorial"]
},
"durationMs": 1840,
"ok": true,
"userUuid": "system",
"user": null
},
{
"ts": "2026-05-03T13:30:00.000Z",
"kind": "cron_finished",
"title": "Cron ran: Scheduled Skill (cs-cron-blog-scanner)",
"summary": { "jobId": "0f3c2a1b-7d4e-4c8f-9a6b-2e5d1c7f8a90", "status": "ok" },
"durationMs": 4210,
"ok": true,
"userUuid": "system",
"user": null
},
{
"ts": "2026-05-03T13:14:42.118Z",
"kind": "turn_ended",
"title": "Agent turn completed",
"summary": {
"preview": "Here is this week's roundup draft…",
"messageCount": 6
},
"durationMs": 8104,
"ok": true,
"userUuid": "ada-uuid",
"user": {
"uuid": "ada-uuid",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"username": "ada",
"avatar": "https://cdn.wiro.ai/avatars/ada.webp",
"avatarinitials": "AL"
}
}
]
}
user field. Every event is decorated with the resolved actor: { uuid, firstname, lastname, email, username, avatar, avatarinitials }.
- An event with a user's
userUuidcarries that user's profile, ornullwhen the user record was deleted. - An event triggered by automation has
userUuid: "system"anduser: null. That covers cron runs, the token usage of scheduled turns, and similar non-interactive writes (the system rows above). - An event without a
userUuid(an incoming channel message, or a row older than user attribution) carries the agent owner's profile, so the row never shows an empty placeholder.
| Field | Type | Description |
|---|---|---|
date | string|null | The actual date the events were read from (YYYY-MM-DD). |
totalLines | number | Total rows for the day, who-did-what rows and notes included, whatever the lines cap. |
events | array<ActivityEvent> | Newest first (descending by ts): events[0] is the most recent event; do not re-reverse. |
With a lines cap, older who-did-what rows of the day can take the place of the oldest agent events, up to half of the answer, so a stop from this morning stays in reach on a busy day. The answer stays within lines.
Reading a stopped agent. When the agent isn't running, or its host doesn't answer, Logs still answers result: true for a day with who-did-what rows. events starts with a runtime_log_unavailable note, followed by those rows, and totalLines counts the note:
{
"result": true,
"errors": [],
"date": "2026-05-03",
"totalLines": 3,
"events": [
{
"ts": "2026-05-03T16:20:11.000Z",
"kind": "runtime_log_unavailable",
"title": "The agent's own turns and tool calls can be read while it runs",
"userUuid": "system",
"user": null
},
{
"ts": "2026-05-03T16:20:11.000Z",
"kind": "AGENT_STOPPED",
"title": "Agent stopped",
"ok": true,
"userUuid": "ada-uuid",
"user": { "uuid": "ada-uuid", "firstname": "Ada", "lastname": "Lovelace" }
},
{
"ts": "2026-05-03T09:12:44.000Z",
"kind": "AGENT_CREDENTIAL_SAVED",
"title": "Connector setting saved: wiro.apikey",
"ok": true,
"summary": { "fields": ["wiro.apikey"] },
"userUuid": "ada-uuid",
"user": { "uuid": "ada-uuid", "firstname": "Ada", "lastname": "Lovelace" }
}
]
}
A day without such rows answers with one of the errors below.
POST /UserAgent/LogsList
Returns the dates that have activity for this agent: days with a log file and days that only have who-did-what rows. Useful for rendering a date-picker.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid | string | Yes | Your UserAgent instance guid. |
Response
{
"result": true,
"errors": [],
"dates": [
{ "date": "2026-05-03", "sizeBytes": 184220, "compressed": false },
{ "date": "2026-05-02", "sizeBytes": 41280, "compressed": true },
{ "date": "2026-05-01", "sizeBytes": 0, "compressed": false }
]
}
Each entry exposes date (YYYY-MM-DD, sorted newest-first), sizeBytes (raw byte size on disk; compressed size when compressed: true), and compressed (true once the day's log has been compressed to <date>.jsonl.gz; false for the active day's plain .jsonl). sizeBytes is 0 on a day with who-did-what rows and no log file, for example a day whose log was deleted. Reading either form via LogsFile returns the same decoded events. The host retains activity files for 180 days (rolling); older dates are removed and won't appear here.
Reading a stopped agent. When the agent isn't running, or its host doesn't answer, and it has who-did-what days, LogsList still answers result: true with those days and two more fields:
{
"result": true,
"errors": [],
"runtimeUnavailable": "not_running",
"note": "The agent's own log days can be read while it runs, so this list may be missing days.",
"dates": [
{ "date": "2026-05-03", "sizeBytes": null, "compressed": false },
{ "date": "2026-05-01", "sizeBytes": null, "compressed": false }
]
}
| Field | Type | Description |
|---|---|---|
runtimeUnavailable | string | "not_running" or "no_answer". Present only on this answer. |
note | string | The agent's own log days can be read while it runs, so this list may be missing days. for not_running, The agent's own log days could not be read just now, so this list may be missing days. for no_answer. |
dates[].sizeBytes | null | On this answer the size of a day isn't known. |
An agent with no who-did-what days answers with one of the errors below.
POST /UserAgent/LogsFile
Reads the full log of a specific date and returns every event in it, who-did-what rows included. A stopped agent and a deleted day read as on Logs. Use this for "Download today's activity" buttons or for off-band analysis.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid | string | Yes | Your UserAgent instance guid. |
date | string | Yes | YYYY-MM-DD of the file to read. |
Response
{
"result": true,
"errors": [],
"date": "2026-05-02",
"truncated": false,
"events": [
{
"ts": "2026-05-02T08:00:20.142Z",
"kind": "turn_started",
"title": "Agent turn started",
"summary": { "preview": "Hi, can you draft a roundup post?" },
"userUuid": "ada-uuid",
"user": {
"uuid": "ada-uuid",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"username": "ada",
"avatar": "https://cdn.wiro.ai/avatars/ada.webp",
"avatarinitials": "AL"
}
},
{
"ts": "2026-05-02T08:00:19.870Z",
"kind": "user_message",
"title": "User: Hi, can you draft a roundup post?",
"summary": { "preview": "Hi, can you draft a roundup post?" },
"user": {
"uuid": "ada-uuid",
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"username": "ada",
"avatar": "https://cdn.wiro.ai/avatars/ada.webp",
"avatarinitials": "AL"
}
}
]
}
Events are returned newest first (descending by ts), same as the live tail, so events[0] is the most recent; do not re-reverse. The user field follows the same resolution rules as the live tail above (see the Logs section's "About the user field" callout).
truncated is true when the day's file is larger than 10 MiB. Only its newest 10 MiB of events are returned; older events of that day are not retrievable through this endpoint.POST /UserAgent/LogsDelete
Deletes the agent's own turns and tool calls for one date: its activity file and the gzipped sibling, if present. Who-did-what rows stay, so the date can stay in LogsList with sizeBytes: 0. The deletion adds an AGENT_LOG_DAY_DELETED row on the day you make it, and reads of an earlier day you deleted start with a runtime_log_deleted note that says when. Idempotent: deleting an already-gone date is a success no-op.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid | string | Yes | Your UserAgent instance guid. |
date | string | Yes | YYYY-MM-DD of the day to delete. |
Response
{
"result": true,
"errors": [],
"date": "2026-05-01",
"removed": { "plain": false, "gz": true }
}
removed.{plain,gz} reports which physical files were actually deleted. Both false is also a success (file was already gone).
POST /UserAgent/RunStreamToken
Returns a token for following the agent's Scheduled Tasks, background runs and model runs live on the Agent WebSocket, so you see a run while it happens instead of polling Logs. Same access as Logs: the agent's owner and, on a team agent, the team's admins. A stopped agent gets a token too.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid | string | Yes | The guid of your deployed agent. |
Request
curl -X POST "https://api.wiro.ai/v1/UserAgent/RunStreamToken" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321" }'
Response
{
"result": true,
"runstreamtoken": "Zr8Qm2Kx7VbN4tLpW1sYc9HdF6gJaE3uTo5iRk0nXqM",
"expiresat": 1793664000,
"errors": []
}
| Field | Type | Description |
|---|---|---|
runstreamtoken | string | null | An opaque token valid until expiresat, 24 to 48 hours after it is issued. Send it in an agent_run_subscribe frame. null when the call fails. |
expiresat | number | null | Unix seconds when the token stops working, for example 1793664000. null when the call fails. |
Keep the token private: whoever holds it can follow the agent's runs until expiresat. When less than 12 hours remain, call RunStreamToken again and subscribe with the new token. How to subscribe, the events, and the client rules are in Following an agent's background runs.
A failed call has one entry in errors:
{
"result": false,
"runstreamtoken": null,
"expiresat": null,
"errors": [
{
"code": 97,
"message": "Only a team admin can perform this action on a team-owned agent.",
"time": 1793491800
}
]
}
| Error | Code | When |
|---|---|---|
useragentguid is required | 0 | useragentguid is missing or blank |
User agent not found | 95 | Unknown guid, or the agent has been deleted |
You don't have access to this user agent | 96 | The caller is neither the agent's owner nor on its team |
Only a team admin can perform this action on a team-owned agent. | 97 | The caller is a plain member of the agent's team |
runstream-unavailable | 0 | Following runs live is not available right now. Try again later |
Usage Patterns
Live polling for an in-app activity feed
Polling Logs every 30 seconds is the recommended cadence:
async function pollActivity(useragentguid, onEvents) {
let lastTs = 0;
setInterval(async () => {
const { data } = await axios.post(
'https://api.wiro.ai/v1/UserAgent/Logs',
{ useragentguid, lines: 200 },
{ headers: { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' } }
);
const fresh = data.events.filter(e => Date.parse(e.ts) > lastTs);
if (fresh.length === 0) return;
onEvents(fresh);
lastTs = Date.parse(fresh[0].ts);
}, 30_000);
}
To show a Scheduled Task or another background run while it happens, follow the agent's run stream and read Logs again when agent_run_end arrives.
Daily download for off-band analysis
# 1) discover available dates
curl -X POST "https://api.wiro.ai/v1/UserAgent/LogsList" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321" }'
# 2) download a specific date's full file
curl -X POST "https://api.wiro.ai/v1/UserAgent/LogsFile" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "date": "2026-05-02" }' \
> logs-2026-05-02.json
Filtering server-side by kind
The endpoints don't support server-side filtering, so apply filters client-side:
import requests
resp = requests.post(
"https://api.wiro.ai/v1/UserAgent/LogsFile",
headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
json={"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "date": "2026-05-02"}
).json()
cron_runs = [e for e in resp["events"] if e["kind"] == "cron_finished"]
print(f"{len(cron_runs)} cron runs on 2026-05-02")
for e in cron_runs:
summary = e.get("summary") or {}
print(f" {e['title']} status={summary.get('status')}")
Delete a day
LogsDelete removes the agent's own turns and tool calls for one day without waiting for the 180-day rotation. Who did what to the agent that day stays in the log:
curl -X POST "https://api.wiro.ai/v1/UserAgent/LogsDelete" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "date": "2026-05-02" }'
Errors
| Error | When |
|---|---|
useragentguid is required | Missing required parameter |
date is required | LogsFile / LogsDelete without date |
useragent-access-denied | Caller is neither the owner nor on the agent's team |
useragent-team-admin-required | Caller is a member of the agent's team but not a team admin (code 97) |
Agent is not assigned to a worker. It may not be running. | The agent isn't running on a host (never started, stopped or being moved). Start it and retry |
Worker not found | The agent's host is not available right now. Retry later |
Agent is temporarily unavailable. Please try again shortly. | The agent's host did not answer (offline, network blip). Retry |
runstream-unavailable | RunStreamToken only: following runs live is not available right now. Try again later |
Logs, LogsFile and LogsList answer with the last three errors only when there are no who-did-what rows to show. LogsDelete needs the agent on a host every time. RunStreamToken needs no host: a stopped agent gets a token too.
Retention & Rotation
| Period | What happens |
|---|---|
| Day 0-6 | File is plain JSONL (YYYY-MM-DD.jsonl). Live tail + LogsFile read it directly. |
| Day 7-180 | File is gzipped (YYYY-MM-DD.jsonl.gz). Reads are transparently decompressed; size in LogsList reports the on-disk compressed bytes. |
| Day 181+ | File is deleted by the agent's daily maintenance cron. LogsList no longer surfaces the date. |
Who-did-what rows are kept for the same 180 days.
LogsFile download to your own storage.What's Next
- Agent Transactions: Credit ledger for the same useragent
- Agent Messaging: User-facing message exchanges (with full prompts and responses)
- Agent WebSocket: Follow the agent's Scheduled Tasks, background runs and model runs live
- Agent Overview: Full agent endpoint catalog
Meta Ads Integration
Connect your agent to Meta's advertising platform to manage campaigns, ad sets, creatives, and performance insights across Facebook and Instagram ads.
Overview
The Meta Ads integration powers the int-metaads-manage skill: creating and managing campaigns, pulling insights, managing creatives, and analyzing ad account data through direct Meta Graph / Marketing API v26 calls.
Skills that use this integration:
int-metaads-manage: Campaign / ad set / creative CRUD, insights reporting, direct Graph API v26 operationsutil-ads-manager-common: Shared ads helpers (works alongsideint-metaads-manageandint-googleads-manage)
Agents that typically enable this integration:
- Meta Ads Manager
- Any custom agent that needs paid-media capabilities on Meta
Availability
| Path | Status | Notes |
|---|---|---|
| Wiro-owned approved-app OAuth | Pending provider approval | Not available yet. OAuthConnect with "wiro", or with no authmethod, returns Sign-in with the platform's app is not enabled for Meta Ads while Wiro's Meta app waits for App Review and Advanced Access. |
"own" |
Available now | You create your own Meta Developer App and connect it to Wiro. No App Review required when Development Mode + App Roles is used. |
"api_key" |
Available now (recommended) | Paste a Business Manager System User token. No browser OAuth redirect and no App ID or App Secret is submitted to Wiro. Choose Never for token expiration when Meta offers it. |
There is no app-less Meta “machine key.” A System User token is the closest machine-to-machine option: it removes the browser OAuth flow and recurring human sign-in, but Meta generates it for a System User through a Business Portfolio and a Meta Business app. The app, System User, ad accounts, Pages, and permissions remain customer-owned.
Today the two enabled modes are the recommended token-only System User path and customer-owned OAuth. Once Wiro's approved app has Advanced Access, a Wiro-owned OAuth option can be enabled without removing either customer-owned path.
Prerequisites
- A Wiro API key: see Authentication for how to issue keys and sign requests.
- A deployed agent: see Agent Overview and call
POST /UserAgent/Deployfirst. You need the returneduseragents[0].guidfor every step below. - A Meta Business account (business.facebook.com).
- For the currently enabled customer-owned paths, a Meta Developer account and Business app (developers.facebook.com). The future Wiro-owned OAuth path will not require each customer to create an app.
- For OAuth mode: an HTTPS return URL that your backend controls. Meta's callback is the fixed Wiro URL shown below;
redirecturlis where Wiro sends the browser after processing that callback.http://localhostandhttp://127.0.0.1are accepted for local development only.
Recommended: System User token (no browser OAuth)
Use this path for a stable server-to-server connection owned by the customer's Business Portfolio.
- Open Meta Business Settings → Users → System Users, then create or select a System User.
- Assign each required ad account with both
ADVERTISEandANALYZEtasks. For Page-backed creatives, also assign the relevant Facebook Pages. - Generate a token for the Business app used by that System User. Choose Never under Set expiration when Meta offers it; some businesses are required to use an expiring token.
- Grant
ads_management,ads_read, andbusiness_management. For Page discovery and Page-backed creatives, also grantpages_show_list,pages_read_engagement, andpages_manage_ads. - Save only the connection mode and token to Wiro:
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "meta-ads", "fieldname": "authmethod", "fieldvalue": "api_key" },
{ "credentialkey": "meta-ads", "fieldname": "systemusertoken", "fieldvalue": "YOUR_SYSTEM_USER_ACCESS_TOKEN" }
]
}'
- Ask Wiro to validate the token and discover assigned ad accounts:
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "meta-ads",
"authmethod": "api_key"
}'
Wiro validates the token against Meta and returns only active ad accounts whose
effective user_tasks contain both ADVERTISE and ANALYZE. The token is
encrypted at rest, and this answer never repeats it. Once saved, it reads
"••••••••" on UserAgent/Detail, like every saved secret. Wiro does not require or store an App ID/App Secret for this direct mode.
- Persist one or more returned ad accounts with
POST /UserAgentOAuth/SetPickerAccountsas shown in Step 10. API clients must perform this request even when only one account is returned. - Optionally discover and select Page mappings with
POST /UserAgentOAuth/DiscoverPickerItems, then save them through the chainedSetPickerAccountsshape shown in Step 10b. To save the ad accounts and their Pages in one call, discover the Pages first, as the end of Step 10b shows.
Customer-owned app OAuth
Step 1: Create a Meta Developer App
- Go to developers.facebook.com/apps and click Create app.
- Choose "Other" as the use case, then "Business" as the app type.
- Set an App display name (this is what your end users see on the consent screen, so use your company or product name, not "Wiro").
- Enter an App contact email.
- Select the Meta Business Account that owns the ad accounts you plan to manage, then click Create app.
You're now on the app dashboard. The app is in Development Mode by default. Leave it there. Development Mode is exactly what lets you skip App Review.
Step 2: Add the Marketing API product
- From the app dashboard, click Add product.
- Find "Marketing API" and click Set up.
- No further configuration is required inside Marketing API itself: adding the product unlocks the
ads_*permissions.
Step 3: Add "Facebook Login for Business" and register the redirect URI
Meta Ads OAuth uses Facebook Login under the hood.
- Click Add product again.
- Find "Facebook Login for Business" and click Set up.
- Left sidebar: Facebook Login for Business → Settings.
- Scroll to Valid OAuth Redirect URIs and add exactly:
https://api.wiro.ai/v1/UserAgentOAuth/MetaAdsCallback
- Save changes at the bottom.
This is the single most common place where own-mode setups fail. The redirect URI must be exact: HTTPS, no trailing slash, same capitalization.
Step 4: Note the required permissions
Wiro requests these exact scopes during OAuth:
ads_management,ads_read,business_management,pages_show_list,pages_read_engagement,pages_manage_ads
| Permission | Why Wiro requests it |
|---|---|
ads_management |
Create, update, and pause campaigns, ad sets, and ads. |
ads_read |
Read insights, performance metrics, and account metadata. |
business_management |
Discover and validate Business-managed assets used by the full management workflow. |
pages_show_list |
Discover Pages available to the connected principal for each selected ad account. |
pages_read_engagement |
Read page-level engagement metrics that some creative types reference. |
pages_manage_ads |
Use an assigned Page in Page-backed ad creatives. |
These permissions normally require App Review/Advanced Access for a multi-tenant Live Mode app. In a customer-owned app's Development Mode they work without App Review for Facebook users listed under that app's Roles. This is a testing/customer-owned fallback and does not make Wiro's future one-click shared-app path live; that path waits for Wiro's app to receive Advanced Access.
Step 5: Copy your App ID and App Secret
App settings → Basic → copy the App ID, click Show next to App Secret and copy that too.
Step 6: Add the users who will connect as Testers (only if they're not you)
- Connecting your own Facebook account? You're already the app Admin; skip this step.
- Connecting a different Facebook account (typical for SaaS customers)? Go to App Roles → Roles → Add People and invite them as Testers or Developers. They accept at facebook.com/settings → Business Integrations.
Users not listed in App Roles will be blocked at the consent screen in Development Mode.
Step 7: Save your Meta App credentials to Wiro
Push the appid and appsecret into the agent's meta-ads credential group. Wiro merges credential updates per group: fields you don't send are preserved, and credentials from other groups are untouched.
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "meta-ads", "fieldname": "appid", "fieldvalue": "YOUR_META_APP_ID" },
{ "credentialkey": "meta-ads", "fieldname": "appsecret", "fieldvalue": "YOUR_META_APP_SECRET" },
{ "credentialkey": "meta-ads", "fieldname": "authmethod", "fieldvalue": "own" }
]
}'
Successful response:
{
"result": true,
"errors": [],
"applied": 3
}
Credentials sent at Deploy: Deploy saves
appid,appsecretandauthmethodsent in themeta-adsgroup of itscredentialsbody when they pass validation, but it doesn't report a result for each field. Call this step anyway and check its response before initiating OAuth.Only user-writable fields are accepted.
appidandappsecretare user-writable in themeta-adscredential. Fields the connection flow fills in (the ad account and the selected Facebook Pages) are rejected with<Field label> is managed by the connection flowinerrors[], and nothing in that request is saved.appidandappsecretare not returned byPOST /UserAgent/Detail, so checkresultanderrors[]on theCredentialUpsertresponse to confirm the write.
Step 8: Initiate OAuth
Start the flow with authmethod: "own" so Wiro uses your customer-owned appid and appsecret.
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "meta-ads",
"redirecturl": "https://your-app.com/settings/integrations",
"authmethod": "own"
}'
Response:
{
"result": true,
"authorizeUrl": "https://www.facebook.com/v26.0/dialog/oauth?client_id=...&redirect_uri=https%3A%2F%2Fapi.wiro.ai%2Fv1%2FUserAgentOAuth%2FMetaAdsCallback&state=...&scope=ads_management%2Cads_read%2Cbusiness_management%2Cpages_show_list%2Cpages_read_engagement%2Cpages_manage_ads",
"flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19",
"errors": []
}
Redirect the user's browser to authorizeUrl. Full-page redirect is recommended over a popup, because some browsers block third-party cookies in popups, breaking the OAuth session.
State TTL: Wiro caches the OAuth state for 15 minutes. If the user takes longer to complete consent, the callback returns
metaads_error=session_expiredand you must callOAuthConnectagain.
Step 9: Handle the callback
After the user consents, Meta sends them back to Wiro's callback URL. Wiro exchanges the code for a long-lived token, verifies its App ID, expiry, data-access expiry, and required scopes through debug_token, then fetches the user's eligible ad accounts. It writes the token into the agent's config and redirects the user to your redirecturl with query parameters.
Success URL looks like:
https://your-app.com/settings/integrations?metaads_connected=true&metaads_accounts=%5B%7B%22id%22%3A%22123456789%22%2C%22name%22%3A%22My%20Ad%20Account%22%7D%5D
metaads_accountsisencodeURIComponent(JSON.stringify([...])). Your query parser decodes it, so parse it once withJSON.parse.- Each array element:
{ id, name }. - The
idhas theact_prefix stripped by Wiro. - Only ad accounts with
account_status === 1and effectiveuser_taskscontaining bothADVERTISEandANALYZEare included. Read-onlyANALYZEaccounts are excluded because this skill supports mutations. - The list always holds at least one account. When no ad account qualifies, the redirect carries
metaads_error=no_accountsinstead, and nothing is saved.
Parse in the browser:
const params = new URLSearchParams(window.location.search);
if (params.get("metaads_connected") === "true") {
// URLSearchParams has already decoded the value, so don't call decodeURIComponent on it.
const accounts = JSON.parse(params.get("metaads_accounts") || "[]");
if (accounts.length === 1) {
// One ad account: SetPickerAccounts is still required.
await setAdAccount({ adaccountid: accounts[0].id, adaccountname: accounts[0].name });
} else {
presentAccountPicker(accounts);
}
} else if (params.get("metaads_error")) {
// For example no_accounts: no active ad account with ADVERTISE and ANALYZE tasks.
handleError(params.get("metaads_error"));
}
Step 10: Persist the ad account selection
Persist one or more discovered ad accounts. This is required for the connection to become active. The Wiro dashboard auto-selects a sole result and opens a multi-select picker when several accounts are returned; API clients must always call this endpoint explicitly.
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/SetPickerAccounts" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "meta-ads",
"accounts": [
{ "adaccountid": "123456789", "adaccountname": "My Ad Account" }
]
}'
Response:
{
"result": true,
"accounts": [
{ "id": "123456789", "name": "My Ad Account" }
],
"restart": "scheduled",
"errors": []
}
Behavior:
- Pass the ad account ID without the
act_prefix. If you include it, Wiro strips it automatically. adaccountnameis optional: Wiro saves the name from its list, whichOAuthStatusresponses and dashboards show.- Pass multiple
{ adaccountid, adaccountname }entries to authorize the agent against several ad accounts at once. - A save replaces the previous selection. Wiro saves only ad accounts from the list of this token check or sign-in, from the same Wiro account within 15 minutes, and the first save uses the list up: to change the ad accounts later, connect again (step 6 of the System User path, or Step 8) and save from the new list. Page mappings are kept only for ad accounts that stay selected, so run Step 10b again for ad accounts you add.
- If the agent was running (status
3or4), Wiro marks itstatus: 1and restarts it after the stop cycle, so the agent uses the new ad account. No manual Start needed.
Step 10b: Discover and select Facebook Pages (optional)
After the ad-account selection is saved, discover Pages that Meta reports as promotable for each selected account:
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/DiscoverPickerItems" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "meta-ads",
"pickerkey": "pages"
}'
Response:
{
"result": true,
"pickerkey": "pages",
"groups": [
{
"parent": {
"adaccountid": "123456789",
"adaccountname": "My Ad Account"
},
"items": [
{ "pageid": "111222333", "pagename": "My Facebook Page" }
]
}
],
"errors": []
}
Save the selected Pages within five minutes. Include every parent returned
without an errorcode exactly once, and copy pageid and pagename exactly as
discovered; an empty items array means no Page is selected for that ad
account:
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/SetPickerAccounts" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "meta-ads",
"pickerkey": "pages",
"selections": [
{
"parentvalue": "123456789",
"items": [
{ "pageid": "111222333", "pagename": "My Facebook Page" }
]
}
]
}'
The dashboard runs this chained flow automatically after ad-account selection. It auto-selects the only Page when there is exactly one candidate; otherwise it shows Pages grouped by ad account and permits multiple selections. The Page step is optional, so reporting and non-Page operations remain available when no Page is selected.
Ad accounts and Pages in one call. Steps 10 and 10b can restart a running agent twice. To restart it once, skip Step 10: call DiscoverPickerItems with the chosen ad accounts in parents and the flowid of the token check or sign-in, then save both with one SetPickerAccounts call that sends accountids, flowid, pickerkey and selections, with each parent's Pages in itemids or items. Both calls must name the same ad accounts within five minutes, or the save answers next_expired and you discover again. See Both steps in one call.
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/DiscoverPickerItems" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "meta-ads",
"pickerkey": "pages",
"flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19",
"parents": ["123456789"]
}'
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/SetPickerAccounts" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "meta-ads",
"flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19",
"accountids": ["123456789"],
"pickerkey": "pages",
"selections": [
{ "parentvalue": "123456789", "itemids": ["111222333"] }
]
}'
Step 11: Verify the connection
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthStatus" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "meta-ads"
}'
Response:
{
"result": true,
"connected": true,
"accounts": [
{ "id": "123456789", "name": "My Ad Account" }
],
"pagemappings": [
{
"adaccountid": "123456789",
"adaccountname": "My Ad Account",
"pageid": "111222333",
"pagename": "My Facebook Page"
}
],
"pickersteps": {
"pages": {
"pickerkey": "pages",
"optional": true,
"configured": true,
"groups": [
{
"parent": {
"adaccountid": "123456789",
"adaccountname": "My Ad Account"
},
"items": [
{ "pageid": "111222333", "pagename": "My Facebook Page" }
]
}
]
}
},
"connectedat": "2026-04-17T12:00:00.000Z",
"tokenexpiresat": "2026-06-16T12:00:00.000Z",
"errors": []
}
Field notes:
- OAuth mode requires
authmethod: "own"and an access token. Direct mode requiresauthmethod: "api_key", a validatedsystemusertoken, and a successful probe marker; it does not require App ID or App Secret. Both modes require at least one selected ad account beforeconnectedbecomestrue. accounts[]carries one entry per selected ad account (id=adaccountidwithoutact_prefix,name=adaccountname). Emptynamestrings appear when noadaccountnamewas supplied in Step 10.pickersteps.pages.groups[]andpagemappings[]expose the saved Page selections without any access token.tokenexpiresatcomes from Meta's OAuth token response. It is empty for the token-only System User mode because Wiro stores the supplied token unchanged. If an expiring System User token is used, the operator must replace it before Meta invalidates it.- Meta User OAuth has no generic refresh-token contract. When a
wiroorownUser token expires or is invalidated, reconnect through the browser.
Step 12: Start the agent if it's not running
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
Start doesn't wait for every connector. setuprequired: true on POST /UserAgent/Detail means another connector the agent requires is still missing, and the agent starts all the same. Only an agent still at status: 6 is refused: call POST /UserAgent/Update on it first. See Agent Credentials: Setup Required.
Agents already running when you connected Meta Ads restart automatically.
How Meta Ads uses selected Pages
Meta Ads has no scalar/default pageid. Step 10b persists account-scoped
pagemappings, and the runtime exposes each selected ad account with its own
pages[] list.
- Zero Pages: only Page-backed creative creation is unavailable; reporting and other account operations continue.
- One Page under the target ad account: the agent uses it automatically.
- Multiple Pages: the agent requires an explicit Page ID/name in the request or asks the operator which Page to use. It never picks the first Page or borrows a Page from another ad account.
Before creating the creative, the skill verifies the chosen Page through Meta. The connected person or System User must still have the required Page task and the Page must be usable with the resolved ad account.
If you need organic posting (writing posts directly to a Facebook Page rather
than running ads), that's a separate integration (see the
Facebook Page integration). The
int-facebookpage-post skill uses the facebook-pages credential group, not
meta-ads.
API Reference
All endpoints require Wiro authentication: see Authentication for x-api-key + optional signature headers.
POST /UserAgentOAuth/OAuthConnect
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
credentialkey |
string | Yes | "meta-ads". |
redirecturl |
string | OAuth only | Any HTTPS URL you control (or http://localhost / http://127.0.0.1 for dev) where users return after consent. Direct System User token validation does not use this field. |
authmethod |
string | No | "api_key" for the recommended System User token mode or "own" for advanced customer-owned app OAuth. Always send it: without it the request runs in Wiro mode and fails with Sign-in with the platform's app is not enabled for Meta Ads. |
OAuth response: { result, authorizeUrl, flowid, errors }. Direct System User token response: { result, accounts: [{id, name}], flowid, account, restart, errors } with no authorizeUrl, where account is the System User's name and restart is "none" until the ad accounts are saved. A failed direct check returns { result: false, errorcode, flowid, errors }: no_accounts (no active ad account with both ADVERTISE and ANALYZE), too_many_ad_accounts (Meta listed more than 500 ad accounts), direct_token_missing, direct_token_invalid, provider_rejected_request, provider_timeout or provider_request_failed. A check that finds a saved token first clears the saved ad account and Page selection.
If result: false, inspect errors[0].message. Common messages: Request parameter [useragentguid] required, Request parameter [credentialkey] required, Request parameter [redirecturl] required (OAuth only), Invalid redirect URL, User agent not found or unauthorized, Sign-in with the platform's app is not enabled for Meta Ads (no authmethod, or "wiro"), Unsupported connection mode for Meta Ads, and Meta Ads credentials not configured (own mode before appid and appsecret are saved with CredentialUpsert).
GET /UserAgentOAuth/MetaAdsCallback
Server-side endpoint invoked by Meta. You don't call it. You only handle the final redirect back to your redirecturl. The callback path is per-provider: Meta Ads's stays MetaAdsCallback.
| Query param | Meaning |
|---|---|
metaads_connected=true |
OAuth completed successfully. |
metaads_accounts |
URL-encoded JSON array of { id, name } for active ad accounts. Always at least one entry. |
metaads_error=<code> |
OAuth failed. See Troubleshooting. |
POST /UserAgentOAuth/SetPickerAccounts
The same endpoint persists both picker stages.
Root ad-account selection:
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
credentialkey |
string | Yes | "meta-ads". |
accounts |
array | Yes | One or more { adaccountid, adaccountname } entries. adaccountid must be without the act_ prefix (prefix stripped automatically if sent); Wiro saves the name from its list as adaccountname, the display name shown in dashboards and OAuthStatus responses. |
Response: { result, accounts: [{id, name}, ...], restart, errors }. The save that completes the connection restarts a running agent once (restart: "scheduled"), and a save that changes nothing restarts nothing.
Chained Page selection, after DiscoverPickerItems:
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
credentialkey |
string | Yes | "meta-ads". |
pickerkey |
string | Yes | "pages". |
selections |
array | Yes | One { parentvalue, items } entry for every discovery group without an errorcode. parentvalue is the ad account ID; each item carries pageid and pagename exactly as discovered, or itemids holds the Page IDs. Empty items is allowed because Pages are optional. |
Response:
{ result, pickerkey: "pages", pagemappings: [{adaccountid, adaccountname, pageid, pagename}], restart, errors }.
Both stages in one call: send accountids (or accounts), flowid, pickerkey and selections together, after DiscoverPickerItems with the same ad accounts in parents. Response: { result, accounts: [{id, name}, ...], pickerkey: "pages", pagemappings, restart, errors }.
POST /UserAgentOAuth/DiscoverPickerItems
Discovers eligible Facebook Pages grouped under the selected ad accounts: the saved ones, or, with parents and flowid, ad accounts of the current token check's or sign-in's list before they are saved.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
credentialkey |
string | Yes | "meta-ads". |
pickerkey |
string | Yes | "pages". |
parents |
string[] | No | Ad account IDs from the list of the current token check or sign-in, before they are saved (at most 50). |
flowid |
string | No | With parents: the flowid from OAuthConnect. |
Response:
{ result, pickerkey: "pages", groups: [{parent: {adaccountid, adaccountname}, items: [{pageid, pagename}], errorcode?}], errors }.
Wiro keeps the active token server-side and caches only secret-free candidates
for five minutes. Call the chained SetPickerAccounts shape before they expire.
Discovery covers at most 50 selected ad accounts and 2,000 Pages in total; above that the call fails with Too many parent accounts selected for picker discovery or Picker candidate limit exceeded. An ad account with more than 500 Pages comes back with errorcode: "too_many_pages". Leave groups that carry an errorcode out of selections (their saved Pages stay as they are), and copy pageid and pagename from the response unchanged. Otherwise SetPickerAccounts returns Selected parent is not available or Selected picker item is not available.
POST /UserAgentOAuth/OAuthStatus
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
credentialkey |
string | Yes | "meta-ads". |
Response fields:
| Field | Type | Description |
|---|---|---|
connected |
boolean | true when the selected customer-owned mode has a validated credential and at least one selected ad account. Note: this reflects connection completion, not readiness of unrelated required credentials. Use setuprequired from POST /UserAgent/Detail for whole-agent readiness. |
accounts |
array | One { id, name } per selected ad account (id = adaccountid without act_ prefix, name = adaccountname). |
pagemappings |
array | Flat, account-scoped Page mappings. Each entry contains adaccountid, optional adaccountname, pageid, and pagename. |
pickersteps.pages |
object | Grouped Page status for UI rendering: { pickerkey, optional, configured, groups[] }. |
connectedat |
string | ISO timestamp of connection. |
tokenexpiresat |
string | ISO expiry for OAuth tokens. Empty for direct System User mode because Wiro stores the supplied token unchanged. |
POST /UserAgentOAuth/OAuthDisconnect
Body: { useragentguid, credentialkey: "meta-ads" }. Clears the active token,
probe marker, ad-account selection, and Page mappings. Customer-owned OAuth App
ID/App Secret values are preserved for reconnect; direct mode's
systemusertoken is cleared. This endpoint clears Wiro's copy, so
administrators should also revoke the app or token in Meta Business Settings
when immediate provider-side invalidation is required.
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthDisconnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "meta-ads"
}'
Response: { "result": true, "errors": [] }. A starting or running agent restarts when the disconnect removes a token or the connection was complete. Otherwise, for example with only the app keys saved, it restarts nothing.
Token lifecycle
Wiro does not exchange or renew a direct System User token. Prefer Never expiration when Meta offers it; otherwise generate a replacement and reconnect before the token expires. User OAuth connections must be reconnected after Meta expires or invalidates them. Raw tokens and App Secrets are never exposed to the agent model.
Using the Skill
Enable int-metaads-manage on the agent via POST /UserAgent/SkillsApply (see Agent Skills → Toggling Integration Skills). Adjust the cron of the built-in cs-cron-metaads-performance-reporter task (Meta Ads Manager) with enabled and interval only. The task body (value) is owned by the bundled integration skill and silently dropped on writes:
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"skillkey": "cs-cron-metaads-performance-reporter",
"enabled": true,
"interval": "0 9 * * *"
}'
To change what the reporter includes (thresholds, reporting preferences, holiday markets), edit the paired preference skill ad-strategy instead (see Agent Skills → Updating Preferences).
Troubleshooting
| Error code | Meaning | What to do |
|---|---|---|
missing_params |
The callback was opened without an OAuth state. This error ends on the API's own neutral page, not on your app. |
Don't open the callback URL directly. Start a new flow from Step 8. |
session_expired |
More than 15 minutes elapsed between OAuthConnect and the consent return. |
Call OAuthConnect again to refresh the state. |
flow_replaced |
A newer sign-in or token check for the same agent and credential replaced this sign-in, whoever started it, so nothing from it was saved. | Use the newer sign-in or check, or start again with OAuthConnect. |
authorization_denied |
User clicked Cancel, or Facebook returned error=access_denied. In Development Mode this also happens when the user isn't listed under App Roles. |
Add the user as a Tester (Step 6), have them accept, retry. |
token_exchange_failed |
Facebook rejected the token exchange. Usually wrong App Secret, revoked app, or redirect URI mismatch. | Re-copy the App Secret from Settings → Basic, verify the redirect URI exactly matches, retry. |
useragent_not_found |
The agent was deleted, or is no longer owned by the account that started the flow, before Meta returned. | Start again with OAuthConnect for an existing agent. |
Meta Ads credentials not configured |
Returned in OAuthConnect's errors[] when authmethod: "own" but appid / appsecret are missing. |
Call POST /UserAgent/CredentialUpsert to add meta-ads.appid and meta-ads.appsecret, then retry OAuthConnect. |
required_meta_scopes_missing |
Meta's debug_token check reported the token as invalid, or without every scope listed in Step 4. |
Grant the listed scopes to the app/token and reconnect. |
long_lived_exchange_failed |
Meta did not return a long-lived token with an expiry for this authorization. | Start a new flow from Step 8. If it keeps happening, contact Wiro support. |
too_many_ad_accounts |
Meta listed more than 500 ad accounts for this user or System User. | Connect with a user or System User that has access to fewer ad accounts. |
meta_app_mismatch |
The token was issued to a different Meta App ID. | Generate or authorize the token with the same app whose App ID and Secret were saved. |
meta_token_expired |
The OAuth token or its data-access window has expired. | Reconnect customer-owned OAuth. Direct mode does not use debug_token; replace a rejected/expired System User token in Business Settings. |
no_accounts |
No active account has both ADVERTISE and ANALYZE tasks. |
Assign the connected principal those tasks on an active ad account in Business Settings, then reconnect. |
Picker candidates expired. Discover them again. |
More than five minutes elapsed after Page discovery, or the parent account connection changed. | Call DiscoverPickerItems again, then resubmit the Page selection. |
The list of pages expired. Load it again. |
errorcode: "next_expired": ad accounts and Pages were saved in one call, but the Pages weren't discovered with parents for those ad accounts, from this sign-in, in the last five minutes. |
Call DiscoverPickerItems with parents again, then save. |
selections must include every available parent exactly once |
The Page selection omitted or duplicated a successful ad-account group. | Include one selections[] entry per successful groups[] entry; use items: [] to select no Page for a parent. |
internal_error |
Unexpected server error during callback processing. | Retry once. If it persists, contact Wiro support with the timestamp and your useragentguid. |
"App not verified" warning on consent
Facebook shows a yellow banner in Development Mode. This is expected and not a blocker: users listed under App Roles can click Continue and finish authorization. Users outside App Roles are hard-blocked.
connected: false after completing OAuth
OAuthStatus returns connected: true only when the selected mode has a validated credential and at least one ad account was saved. If you skipped Step 10 (SetPickerAccounts), connected remains false. If account selection is complete but the status is still false, check the callback or direct-probe error and reconnect.
Token keeps expiring
User OAuth and System User tokens do not have the same lifecycle:
- User OAuth (
wiro/own): reconnect through the browser after expiry or invalidation. - System User (
api_key): choose Never expiration when Meta permits it. If Meta requires an expiring token, generate a replacement and reconnect before expiry. Wiro does not renew or exchange it.
Multi-Tenant Architecture
For SaaS products connecting many customers' Meta Ads accounts through a single Wiro-powered backend:
- Recommended today: use one System User token per customer-owned Business Portfolio when that operating model fits. Customer-owned OAuth remains available for interactive user authorization; Wiro-owned OAuth is not available yet.
- One Wiro agent instance per customer. Call
POST /UserAgent/Deployduring onboarding, then complete the recommended direct steps or the advanced OAuth flow for that customer'suseragentguid. - Tokens are isolated per agent instance. Customer A's Meta token is never visible to Customer B, because they live under different
useragentguidvalues. - Consent branding follows the selected path. Customer-owned OAuth shows the customer's app; the future simple path shows Wiro's reviewed app.
- Customer-owned Development Mode: add each connecting user to that app's Roles. Multi-tenant use outside app roles requires the appropriate App Review/Advanced Access; do not treat Development Mode as production approval.
- Rate limits are per app, not per customer. The Marketing API tier (Development → Standard → Advanced) governs aggregate call volume. See Meta's Rate Limiting docs.
Related
- Agent Credentials & OAuth: integration catalog hub and generic OAuth reference.
- Agent Overview: deploying, starting, and lifecycle.
- Agent Skills: configuring
int-metaads-manageand scheduled runs. - Google Ads integration: for cross-platform paid campaigns.
- TikTok Ads integration: for cross-platform paid campaigns.
TikTok Ads Integration
Connect your agent to TikTok's advertising platform to report on and manage campaigns, ad groups, ads, audiences, and creatives through TikTok's official TikTok for Business MCP server.
Overview
The TikTok Ads integration powers the int-tiktok-ads skill (TikTok Ads Manager). The agent works through TikTok's official TikTok for Business MCP server (Model Context Protocol), which exposes TikTok API for Business v1.3 capabilities as tools: reporting, campaign / ad group / ad management, Upgraded Smart+, audiences, creatives, Spark Ads, and TikTok's own diagnosis tools.
This integration covers advertising only. It does not post organic videos to a TikTok profile. That is the separate TikTok integration, which uses its own tiktok credential.
Skills that use this integration:
int-tiktok-ads: Reporting, campaign / ad group / ad management, Upgraded Smart+ and GMV Max, audiences, creatives, Spark Ads, and diagnosisutil-ads-manager-commonandutil-ads-playbook: Shared ads helpers (approval flow, recommendations queue, daily report template, kill / scale / test playbook), also used by the Meta Ads and Google Ads skills
Agents that typically enable this integration:
- TikTok Ads Manager (prebuilt;
int-tiktok-adsis on by default) - Any Custom Build agent that needs paid-media capabilities on TikTok
Availability
| Mode | Status | Notes |
|---|---|---|
"wiro" |
Available | One-click connect through Wiro's TikTok for Business app. You don't create a developer app, request an API key, or go through app review. |
"own" |
Available | Your own client for the TikTok for Business MCP server, registered once with TikTok's dynamic client registration. The consent screen names your app instead of Wiro AI. There is no client secret: the connection uses PKCE. See "Connect with your own client" below. |
| Pasted token | Not offered | TikTok Ads has no "api_key" mode. OAuthConnect rejects any other authmethod with Unsupported connection mode for TikTok Ads. |
Authorization lasts 30 days. TikTok ends every TikTok for Business authorization 30 days after it is granted, and refreshing the access token does not extend it. Reconnect with the same TikTok for Business account to renew it (see "The 30-day authorization" below).
Prerequisites
- A TikTok for Business account with access to at least one advertiser (ad account), for example through TikTok Ads Manager or membership in a Business Center. For the agent to make changes, not just report, that account needs a role on the advertiser that allows campaign management.
- An agent with
int-tiktok-adsenabled: TikTok Ads Manager has it on by default. On any other agent, enable it withPOST /UserAgent/SkillsApply(see "Using the Skill" below). - For API integrations only: a Wiro API key (Authentication), a deployed agent (Agent Overview) and its
useragentguid, and an HTTPS return URL that your backend controls.http://localhostandhttp://127.0.0.1are accepted for local development only.
Connect in the Wiro dashboard
- Open your agent, go to Connectors, and find the TikTok Ads card.
- Click Connect TikTok for Business.
- Sign in to TikTok for Business and approve the consent screen. It names the app Wiro AI and asks for the
mcp:tt4bpermission scope. - Back in Wiro, pick the advertisers the agent may manage. You can select several; when your account has exactly one advertiser, it is selected for you.
- Wiro saves the selection and restarts the agent if it was running, so the agent picks up the new connection.
Connect with your own client
Use this when the people who connect should see your app's name on TikTok's consent screen instead of Wiro AI. One client serves all of your agents.
Step 1: Register a client once
TikTok's MCP server registers public clients on request. Use your app name and Wiro's redirect URI:
curl -X POST "https://business-api.tiktok.com/open_mcp/tt-ads-mcp-flat/oauth/register" \
-H "Content-Type: application/json" \
-d '{
"client_name": "Your App Name",
"redirect_uris": ["https://api.wiro.ai/v1/UserAgentOAuth/TikTokAdsCallback"],
"token_endpoint_auth_method": "none"
}'
The response holds a client_id and no secret. Keep the client_id.
Step 2: Save the client ID to Wiro
In the dashboard, switch the TikTok Ads card to your own app, paste the Client ID and save. With the API:
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "tiktok-ads", "fieldname": "clientid", "fieldvalue": "YOUR_CLIENT_ID" },
{ "credentialkey": "tiktok-ads", "fieldname": "authmethod", "fieldvalue": "own" }
]
}'
Step 3: Connect
Start the connection with "authmethod": "own":
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "tiktok-ads",
"redirecturl": "https://your-app.com/settings/integrations",
"authmethod": "own"
}'
Everything after sign-in works as in the Wiro app: you pick the advertisers, tokens refresh on their own, and the 30-day authorization applies the same way.
The 30-day authorization
- TikTok ends every TikTok for Business authorization 30 days after it is granted. Refreshing the access token does not extend it; this is TikTok's rule, not a Wiro setting.
- To renew, reconnect with the same TikTok for Business account: click Disconnect on the TikTok Ads card, then Connect TikTok for Business again and confirm the advertisers. A different TikTok for Business account may see different advertisers.
- From 7 days before the end, the daily performance report opens its Risk Flags & Account Health section with the end date and a reconnect reminder. When you chat with the agent in that window, it mentions the end date once at the top of its reply.
- After the authorization ends, the daily performance report sends a one-line notice that TikTok Ads reporting stopped and asks you to reconnect. The other TikTok Ads scheduled tasks stay quiet until you reconnect.
- Expiry does not pause your ads. Campaigns keep delivering in TikTok; only the agent loses access.
- The short-lived access tokens (about 24 hours) are renewed by Wiro automatically. You never see or handle a TikTok token.
Advertiser selection
- The agent works only on the advertisers you selected when you connected. Any request for another advertiser is refused.
- To change the selection, click Disconnect on the TikTok Ads card, then connect again and pick the advertisers you want.
- Until at least one advertiser is selected, the TikTok Ads card reads
_connected: false, and an agent that requires TikTok Ads (such as TikTok Ads Manager) readssetuprequired: trueonUserAgent/Detail.
What the agent can do
| Area | What the agent does |
|---|---|
| Reporting | Account, campaign, ad group, and ad metrics (spend, impressions, clicks, CTR, CPC, CPM, conversions, cost per conversion, ROAS, video views and watch time); age, gender, and country breakdowns; placement (TikTok, Pangle, Global App Bundle) and device platform breakdowns; asynchronous reports for long date ranges; Upgraded Smart+ creative reports; GMV Max reports. |
| Campaign management | Create and update campaigns, ad groups, and ads; pause, enable, or delete them; change budgets and schedules; copy campaigns; run split tests; set up automated rules; manage search negative keywords. |
| Upgraded Smart+ and GMV Max | Create, update, and change the status of Upgraded Smart+ campaigns. Update and report on existing GMV Max campaigns. |
| Audiences | Custom and lookalike audiences, saved audiences, audience size estimates, and audience insights. |
| Creatives | Upload images and videos by URL, choose music, generate creatives with Wiro AI models (when the Wiro AI Models skill is set up), check creative fatigue, run video fix tasks, and preview ads. |
| Spark Ads | Promote posts from your own TikTok account linked to the advertiser, or authorize a creator's post with the Spark Ads code the creator sends you. |
| Placement control | Pangle block lists and inventory filters. |
| Diagnosis | TikTok's own diagnosis tools for delivery and performance issues (no spend, low spend, high CPA, creative fatigue). |
| Ad comments | Reply to or hide comments on ads, and manage blocked words. |
What the agent cannot do
These operations are not available through this integration, by design. When you ask for one, the agent tells you it is not available instead of trying another way.
- Business Center administration.
- Billing, payments, balances, invoices, or fund transfers. TikTok charges ad spend to the advertiser's own payment method; handle billing in TikTok Ads Manager.
- Downloading lead data. Lead generation campaigns can be reported on (cost per lead) and paused.
- TikTok One (Creator Marketplace).
- Catalogs.
- Pixel and event configuration.
- Reach & Frequency purchases.
- Creating GMV Max campaigns. TikTok starts them delivering as soon as they are created, so create them in TikTok Ads Manager; the agent can then report on them and apply approved updates.
- Customer-file audiences. They need an audience file upload; create them in TikTok Ads Manager.
- Organic posting to a TikTok profile. Use the TikTok integration.
Safety and approvals
- Every change goes through the agent's approval policy (the
approval-policycustom skill). By default the agent describes the change (object, IDs, old and new value, reason) and waits for your approval. Reads (reports, lookups, previews) never need approval. - New objects start paused. Campaigns, ad groups, ads, Upgraded Smart+ campaigns, and campaign copies are always created paused. Turning one on is a separate change that needs its own approval.
- Deletes happen only when you ask. Campaigns, ad groups, ads, audiences, creative assets, blocked words, ad comments, and search negative keywords can be deleted on request, after approval. Deleting cannot be undone. The agent never deletes on its own; when it recommends stopping something, it pauses it.
- Rejected changes are not retried. If TikTok rejects a change, the agent reports TikTok's message and request ID and stops.
- Scheduled tasks only read from TikTok. They put proposed changes into the recommendations queue; a change runs only after you approve it in chat (for example
apply 1). - Budgets are in the advertiser's currency, not cents. The agent confirms the currency before changing a budget and states it in the approval request. TikTok requires a new budget to be at least 105% of what has already been spent and does not accept budget changes between 23:55 and 00:00 advertiser time.
- Rate limits. TikTok allows most tools 3 requests per second per tool for each TikTok for Business user; a few, such as asynchronous report creation and campaign copies, have lower limits per app. When TikTok rate-limits a report or lookup, the agent backs off and retries; a rate-limited change is reported and not retried.
- No secrets in chat. The agent never asks for a TikTok password or token. The only code you paste is a Spark Ads authorization code.
Scheduled tasks
TikTok Ads Manager ships with these scheduled tasks. Times use the agent's time zone.
| Task | Skill key | Default schedule | What it does |
|---|---|---|---|
| Daily performance report | cs-cron-tiktokads-performance-reporter |
0 9 * * * (daily 09:00) |
Account, campaign, placement, device, country, and ad-level performance for the last 7 days, anomaly checks, and recommendations. Carries the 30-day reconnect reminder and the expiry notice. |
| Weekly audience & account health scan | cs-cron-tiktokads-audience-scanner |
0 10 * * 1 (Mondays 10:00) |
Age, gender, and placement breakdowns, creative health, custom audience status, rejected or stuck ads, audience fatigue, and new targeting ideas. |
| Drive creative scanner | cs-cron-tiktokads-drive-scanner |
0 10 * * * (daily 10:00) |
Looks for new creative folders in Google Drive and proposes TikTok campaigns for them. Runs daily; does nothing until Google Drive is connected and has creative folders. |
| Holiday campaign planner | cs-cron-tiktokads-holiday-planner |
0 10 * * 3 (Wednesdays 10:00) |
Scans upcoming holidays from the holiday calendar (Calendarific) and suggests seasonal campaigns. Does nothing until Calendarific is connected. |
Shared ads tasks also cover TikTok Ads: the nightly cs-cron-ads-recommendation-cleanup expires stale recommendations, and the optional Adjust creative ROAS report (cs-cron-adjust-creative-roas-reporter) cross-checks TikTok spend when Adjust is connected.
To change what the tasks look for, edit these custom skills (stored as cs-<key>) rather than the tasks:
tiktok-ads-strategy: TikTok-specific knobs for tracking quality gates, kill thresholds, placement strategy, Spark Ads and Smart+ rules.ad-strategy: cross-platform KPI thresholds, shared with Meta Ads and Google Ads.approval-policy: which changes wait for approval.
Multiple advertisers
- Scheduled tasks run once per selected advertiser. Each report is headed with the advertiser's name and ID and uses that advertiser's currency and time zone.
- In chat, name the advertiser when more than one is selected; otherwise the agent asks which one to use. A single request or change never mixes advertisers.
- The 30-day reminder appears in each advertiser's daily report; the expiry notice is sent once for the whole connection.
Connect through the API
Use this flow when you build your own settings screen on top of Wiro agents. Every request is authenticated as described in Authentication.
Step 1: Start the connection
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "tiktok-ads",
"redirecturl": "https://your-app.com/settings/integrations"
}'
Response:
{
"result": true,
"errors": [],
"authorizeUrl": "https://business-api.tiktok.com/portal/mcp-tt4b-authorize?client_id=...&redirect_uri=https%3A%2F%2Fapi.wiro.ai%2Fv1%2FUserAgentOAuth%2FTikTokAdsCallback&scope=mcp%3Att4b&response_type=code&state=...&code_challenge=...&code_challenge_method=S256&resource=...",
"flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19"
}
Redirect the user's browser to authorizeUrl with a full-page redirect rather than a popup. Wiro adds the PKCE challenge itself, so you never handle a code verifier or client secret. authmethod can be omitted: "wiro" is the default and the only accepted value.
State TTL: Wiro keeps the OAuth state for 15 minutes. If the user takes longer on TikTok's consent screen, the connection fails with
tiktokads_error=session_expiredand you must callOAuthConnectagain.
Step 2: Handle the return
After the user approves, TikTok sends them to Wiro's callback (https://api.wiro.ai/v1/UserAgentOAuth/TikTokAdsCallback). Wiro exchanges the code, lists the advertisers the TikTok for Business user can access, stores the tokens server-side, and redirects the browser to your redirecturl.
Success URL looks like:
https://your-app.com/settings/integrations?tiktokads_connected=true&tiktokads_advertisers=%5B%7B%22id%22%3A%227012345678901234567%22%2C%22name%22%3A%22Brand%20X%22%7D%5D
tiktokads_advertisersisencodeURIComponent(JSON.stringify([...])).- Each element is
{ id, name }:idis the numeric advertiser ID as a string,nameis the advertiser name. - The list is never empty on success. When no advertiser can be listed, the callback returns
tiktokads_error=no_accountsinstead. - On a first connection (or after
OAuthDisconnect), nothing is selected yet: the connection becomes active only after Step 3, even when a single advertiser is returned. Reconnecting withoutOAuthDisconnectkeeps the previous selection.
Parse in the browser:
const params = new URLSearchParams(window.location.search);
if (params.get("tiktokads_connected") === "true") {
const advertisers = JSON.parse(params.get("tiktokads_advertisers") || "[]");
if (advertisers.length === 1) {
await saveAdvertisers(advertisers);
} else {
presentAdvertiserPicker(advertisers);
}
} else if (params.get("tiktokads_error")) {
handleError(params.get("tiktokads_error"));
}
Step 3: Save the advertiser selection
This call is required. The Wiro dashboard selects a sole advertiser automatically, but API clients must always send the selection themselves.
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/SetPickerAccounts" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "tiktok-ads",
"accounts": [
{ "advertiserid": "7012345678901234567", "advertisername": "Brand X" }
]
}'
Response:
{
"result": true,
"errors": [],
"accounts": [
{ "id": "7012345678901234567", "name": "Brand X" }
],
"restart": "scheduled"
}
Behavior:
- Send one or more
{ advertiserid, advertisername }entries picked fromtiktokads_advertisers(idbecomesadvertiserid,namebecomesadvertisername). Non-digits inadvertiseridare stripped server-side. - A save replaces the previous selection. Wiro saves only advertisers from this sign-in's list, under the names it lists, when the call comes from the same Wiro account within 15 minutes. The first save uses the list up: to change the selection later, connect again. See SetPickerAccounts.
- If the agent was running, Wiro restarts it so it picks up the selection. No manual Start needed.
Step 4: Verify the connection
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthStatus" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "tiktok-ads"
}'
Response:
{
"result": true,
"errors": [],
"connected": true,
"accounts": [
{ "id": "7012345678901234567", "name": "Brand X" }
],
"connectedat": "2026-09-26T08:14:00.000Z",
"tokenexpiresat": "2026-09-27T08:14:00.000Z"
}
Field notes:
connectedistruewhen the connection has a current access token and at least one advertiser is selected.connectedatis when the user authorized. The authorization ends 30 days after this time.tokenexpiresatis the expiry of the current access token (about 24 hours), not the end of the 30-day authorization. Wiro renews the access token while the agent is running, so this value moves forward about once a day.- If the agent has been stopped for more than a day,
connectedcan readfalseuntil the agent runs again. Starting the agent renews the access token as long as the 30-day authorization has not ended.
Step 5: Start the agent if it's not running
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
Start doesn't wait for every connector. setuprequired: true on POST /UserAgent/Detail means TikTok Ads or another connector the agent requires is still incomplete, and the agent starts all the same. Only an agent still at status: 6 is refused: call POST /UserAgent/Update on it first. See Agent Credentials: Setup Required.
Agents already running when you connected TikTok Ads restart automatically.
Credential fields
| Field | Type | Description |
|---|---|---|
advertiserid |
array of strings | Numeric IDs of the selected advertisers. Required. Written by SetPickerAccounts. |
advertisername |
array of strings | Names of the selected advertisers, in the same order. Written by SetPickerAccounts. |
Both fields are returned by POST /UserAgent/Detail and are managed by the connection flow: POST /UserAgent/CredentialUpsert rejects writes to them (for example Advertiser ID is managed by the connection flow). Access and refresh tokens are stored server-side and are never returned by any endpoint.
API Reference
All endpoints require Wiro authentication: see Authentication for x-api-key + optional signature headers.
POST /UserAgentOAuth/OAuthConnect
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
credentialkey |
string | Yes | "tiktok-ads". |
redirecturl |
string | Yes | HTTPS URL (or http://localhost / http://127.0.0.1 for development) where the browser returns after TikTok. |
authmethod |
string | No | "wiro" (the default) or "own" for your own client (see "Connect with your own client"). |
Response: { result, errors, authorizeUrl, flowid }. If result: false, inspect errors[0].message. Common messages: Request parameter [useragentguid] required, Request parameter [credentialkey] required, Request parameter [redirecturl] required, Invalid redirect URL, User agent not found or unauthorized, Unsupported connection mode for TikTok Ads, and TikTok Ads credentials not configured.
GET /UserAgentOAuth/TikTokAdsCallback
Server-side endpoint invoked by TikTok. You don't call it. You only handle the final redirect back to your redirecturl. The callback path is per-provider: TikTok Ads's is TikTokAdsCallback, separate from the organic TikTok integration's TikTokCallback.
| Query param | Meaning |
|---|---|
tiktokads_connected=true |
Authorization completed. |
tiktokads_advertisers |
URL-encoded JSON array of { id, name } for the advertisers the TikTok for Business user can access. Always at least one entry. |
tiktokads_error=<code> |
The connection failed. See Troubleshooting below. |
POST /UserAgentOAuth/SetPickerAccounts
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
credentialkey |
string | Yes | "tiktok-ads". |
accounts |
array | Yes | One or more { advertiserid, advertisername } entries. advertiserid is the numeric advertiser ID (non-digits stripped); Wiro saves the name from its list as advertisername, the display name shown in dashboards and OAuthStatus responses. |
Response: { result, errors, accounts: [{id, name}, ...], restart }. Replaces the previous selection. The save that completes the connection restarts a running agent once (restart: "scheduled"), and a save that changes nothing restarts nothing. Returns The sign-in expired. Sign in again to choose the accounts. (errorcode: "flow_expired") when no sign-in's list is open: none was started, it was more than 15 minutes ago, or a save already used it. Returns The sign-in is not finished yet. Finish it, then choose the accounts. (errorcode: "flow_waiting") when the sign-in started but TikTok hasn't sent the user back yet.
POST /UserAgentOAuth/OAuthStatus
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
credentialkey |
string | Yes | "tiktok-ads". |
Response fields:
| Field | Type | Description |
|---|---|---|
connected |
boolean | true when the connection has a current access token and at least one selected advertiser. Note: this reflects the TikTok Ads connection only. Use setuprequired from POST /UserAgent/Detail for whole-agent readiness. |
accounts |
array | One { id, name } per selected advertiser (id = advertiserid, name = advertisername). |
connectedat |
string | ISO timestamp of the authorization. The 30-day authorization ends 30 days after it. |
tokenexpiresat |
string | ISO expiry of the current access token (about 24 hours ahead while the agent runs). |
POST /UserAgentOAuth/OAuthDisconnect
Body: { useragentguid, credentialkey: "tiktok-ads" }. Asks TikTok to revoke the authorization and clears the connection in Wiro: tokens, connection time, and the advertiser selection. The Wiro side is cleared even if TikTok's revoke request fails. An access token TikTok issued earlier may stay valid at TikTok for up to 24 hours, but the agent no longer has it.
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthDisconnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "tiktok-ads"
}'
Response: { "result": true, "errors": [] }. A starting or running agent restarts when the disconnect removes a token or the connection was complete. Otherwise it restarts nothing.
Token lifecycle
Wiro renews the 24-hour access token automatically while the agent is running. The authorization behind it lasts 30 days from connectedat and cannot be extended by refreshing. To renew it, run the flow again: OAuthDisconnect, then OAuthConnect, the callback, and SetPickerAccounts. There is no customer-facing token-refresh endpoint, and raw tokens are never exposed to the agent model or to API callers.
Using the Skill
TikTok Ads Manager has int-tiktok-ads on by default. On any other agent, enable it via POST /UserAgent/SkillsApply (see Agent Skills → Toggling Integration Skills). Adjust the cron of a bundled task such as the daily performance report with enabled and interval only. The task body (value) is owned by the bundled integration skill and silently dropped on writes:
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"skillkey": "cs-cron-tiktokads-performance-reporter",
"enabled": true,
"interval": "0 9 * * *"
}'
To change what the reports include (tracking quality gates, kill thresholds, placement strategy, Spark Ads and Smart+ rules), edit the preference skill tiktok-ads-strategy (stored as cs-tiktok-ads-strategy), or ad-strategy for cross-platform thresholds (see Agent Skills → Updating Preferences).
Troubleshooting
| Error code | Meaning | What to do |
|---|---|---|
missing_params |
The callback was opened without an OAuth state. |
Don't open the callback URL directly. Start a new flow with OAuthConnect. |
session_expired |
More than 15 minutes passed between OAuthConnect and the return from TikTok. A callback the browser repeats after a completed one is not an error: it lands where the first one did. |
Call OAuthConnect again. |
flow_replaced |
A newer sign-in for the same agent and credential replaced this one, whoever started it, so nothing from it was saved. | Use the newer sign-in, or start again with OAuthConnect. |
authorization_denied |
The user cancelled on TikTok's consent screen, or TikTok returned an error instead of an authorization code. | Start again and approve the consent screen. |
token_exchange_failed |
TikTok did not return a usable access and refresh token for the authorization code. | Start a new flow. If it persists, contact Wiro support. |
no_accounts |
Sign-in worked, but no advertiser could be listed for this TikTok for Business user: the user has no advertiser access, or TikTok's advertiser lookup failed. | Get access to an advertiser in TikTok Ads Manager or Business Center, then connect again. If this user already has advertiser access, try connecting again. |
account_list_too_large |
The TikTok for Business user can access more than 500 advertisers. | Connect with a TikTok for Business user that has access to fewer advertisers. |
useragent_not_found |
The agent was deleted, or is no longer owned by the account that started the flow, before TikTok returned. | Start again with OAuthConnect for an existing agent. |
internal_error |
Unexpected server error during callback processing. | Retry once. If it persists, contact Wiro support with the timestamp and your useragentguid. |
Unsupported connection mode for TikTok Ads |
Returned in OAuthConnect's errors[] when authmethod is anything other than "wiro" or "own". |
Omit authmethod, or send "wiro" or "own". |
TikTok Ads credentials not configured |
Returned in OAuthConnect's errors[] when authmethod: "own" but no clientid is saved. |
Save the client ID with UserAgent/CredentialUpsert (see "Connect with your own client"), then connect again. |
TikTok Ads credentials not configured |
Returned in OAuthConnect's errors[] when TikTok Ads is not available for this account. |
Contact Wiro support. |
flow_waiting |
Returned by SetPickerAccounts (The sign-in is not finished yet. Finish it, then choose the accounts.) while the sign-in has started but TikTok hasn't sent the user back yet, so there is no list to save from. |
Let the user finish on TikTok's consent screen, then save the selection. Don't call OAuthConnect again meanwhile: it would replace the sign-in under way. |
TikTok Ads account not connected |
Returned by SetPickerAccounts when the sign-in's list is open but the sign-in's token is no longer saved. |
Run Steps 1-2 again, then save the selection. |
missing_params sends the browser to the API's own neutral page, https://api.wiro.ai/v1/UserAgentOAuth/SignInNotFinished, because a callback without a state has no return address. session_expired comes back to your redirecturl. It ends on that page only when the callback arrives more than 24 hours after OAuthConnect or carries a state Wiro never issued.
"No accounts available" after signing in
Either the TikTok for Business user you signed in with has no advertiser access, or TikTok's advertiser lookup failed. Get access to an advertiser in TikTok Ads Manager or through Business Center membership, then connect again. If this user already has advertiser access, try connecting again.
The agent says the TikTok Ads connection expired
The 30-day authorization ended. Click Disconnect on the TikTok Ads card, then connect again with the same TikTok for Business account and confirm the advertisers. Your campaigns kept running in TikTok in the meantime.
A change was refused
The action is outside what this integration allows (see "What the agent cannot do"), it targets an advertiser that was not selected, or the TikTok for Business user's role on the advertiser does not allow campaign management. Change roles in TikTok's business settings; change the advertiser selection by disconnecting and connecting again.
A report metric is rejected by TikTok
Nothing to do. The agent drops the metric TikTok rejected and runs the report again without it.
connected: false after completing the flow
OAuthStatus returns connected: true only when there is a current access token and at least one advertiser is saved. If you skipped Step 3 (SetPickerAccounts), connected stays false. If the selection is saved, check whether the 30-day authorization has ended (reconnect) or the agent has been stopped for more than a day (start it).
Multi-Tenant Architecture
For SaaS products connecting many customers' TikTok Ads accounts through a single Wiro-powered backend:
- One Wiro agent instance per customer. Call
POST /UserAgent/Deployduring onboarding, then run the connection flow for that customer'suseragentguid. Each customer signs in with their own TikTok for Business account. - Tokens are isolated per agent instance. Customer A's TikTok authorization is never visible to Customer B, because they live under different
useragentguidvalues. - The consent screen shows Wiro AI. There is no customer-owned app mode, so the consent screen cannot be white-labeled.
- Plan for the 30-day renewal. Every customer has to reconnect every 30 days. Track
connectedatfromOAuthStatusand prompt the customer before the 30 days are up. - Rate limits are mostly per TikTok for Business user. TikTok allows most tools 3 requests per second per tool for each user; asynchronous report creation and campaign copies have lower per-app limits that all connections share.
Related
- Agent Credentials & OAuth: integration catalog hub and generic OAuth reference.
- Agent Overview: deploying, starting, and lifecycle.
- Agent Skills: configuring
int-tiktok-adsand scheduled runs. - TikTok integration: organic video posting to a TikTok profile (separate
tiktokcredential). - Meta Ads integration: for cross-platform paid campaigns.
- Google Ads integration: for cross-platform paid campaigns.
Shopify Integration
Connect a Wiro agent to Shopify's official GraphQL Admin API 2026-07 to manage products, variants, inventory, orders, customers, discounts, collections, and fulfillments.
Overview
The Shopify integration powers the int-shopify-manage skill. It uses only the official GraphQL Admin API pinned to 2026-07; the REST Admin API, latest, unstable, and release-candidate schemas are outside the contract.
Available connection modes:
| Mode | Status | Best for |
|---|---|---|
Client ID + Secret ("api_key") |
Available | Server-to-server automation when the Dev Dashboard app and store belong to the same Shopify organization. Tokens report expires_in: 86399 and are re-exchanged before expiry. |
Customer-owned app OAuth ("own") |
Available | Apps installed on merchant stores in another organization. Uses an expiring offline access token plus rotating refresh token. |
Wiro does not provide a shared Shopify OAuth app. Both modes use customer-owned credentials.
Prerequisites
- A deployed Wiro agent with the
int-shopify-manageskill enabled. - A Shopify store and permission to install or create apps.
- The canonical store hostname, for example
example-store.myshopify.com. Custom storefront domains are not accepted for Admin API authentication.
Option A: Client ID + Secret
1. Create and install a Dev Dashboard app
In Shopify's Dev Dashboard:
- Create an app in the same Shopify organization as the target store.
- Configure only the Admin API scopes the agent needs.
- Release an app version and install it on the store.
- Copy the Client ID and Client Secret from the app's Settings page.
Product, inventory, order, customer, discount, fulfillment, and location operations require their matching read/write scopes. The app can do only what its granted scopes and the installing staff account permit.
Shopify's client-credentials grant works only when both the app and store belong to the same organization. For a merchant store in another organization, use Option B.
2. Save the store and app credentials
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "shopify", "fieldname": "authmethod", "fieldvalue": "api_key" },
{ "credentialkey": "shopify", "fieldname": "shopdomain", "fieldvalue": "example-store.myshopify.com" },
{ "credentialkey": "shopify", "fieldname": "clientid", "fieldvalue": "YOUR_SHOPIFY_CLIENT_ID" },
{ "credentialkey": "shopify", "fieldname": "clientsecret", "fieldvalue": "YOUR_SHOPIFY_CLIENT_SECRET" }
]
}'
3. Validate the connection
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "shopify",
"authmethod": "api_key"
}'
This is a server-side credential exchange and probe, not a browser redirect. Wiro submits the Shopify client-credentials form (grant_type=client_credentials, Client ID, and Client Secret) to the canonical shop, receives an access token whose expires_in is exactly 86399 seconds, verifies the shop identity, and stores the connection. Running agents re-exchange the client credentials before expiry; the Client Secret is never sent to the GraphQL Admin API.
The response is { "result": true, "errors": [], "accounts": [], "flowid": "...", "account": "...", "restart": "scheduled" }, where account is the store's name and restart says whether the check restarted a running agent. Shopify has no account picker, so there is nothing to select; OAuthStatus then reports connected: true with the shop name in accounts[0]. If the check fails, the response has result: false, a message asking you to check the myshopify.com domain, the app's organization and its Admin API scopes, and an errorcode. direct_token_missing means authmethod is not saved as "api_key" or one of the three fields is empty. Any other code, such as provider_rejected_request or direct_token_invalid, means the exchange or the shop check failed, and any earlier Shopify connection on the agent is cleared too.
Option B: Customer-owned app OAuth
1. Configure the Shopify app
Create or select the customer's app in the Shopify Dev Dashboard and add this exact redirect URL:
https://api.wiro.ai/v1/UserAgentOAuth/ShopifyCallback
The authorization-code grant requests an expiring offline token. Wiro's authorize URL asks for these Admin API scopes: read_products, write_products, read_inventory, write_inventory, read_orders, write_orders, read_customers, write_customers, read_discounts, write_discounts, read_publications, write_publications, read_returns, read_merchant_managed_fulfillment_orders, write_merchant_managed_fulfillment_orders and read_locations.
Wiro validates the callback before exchanging the code:
- the callback HMAC is computed with the app's Client Secret over every callback query field except
hmac, sorted by name; - comparison is timing-safe, and the callback
stateand canonicalshopmust match the connection that Wiro started; - the authorization code is sent only to that shop's
/admin/oauth/access_tokenendpoint asapplication/x-www-form-urlencoded, withexpiring=1.
This callback-query HMAC is not Shopify's webhook-signature format, and it is not computed over the token form body.
2. Save app credentials
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "shopify", "fieldname": "authmethod", "fieldvalue": "own" },
{ "credentialkey": "shopify", "fieldname": "shopdomain", "fieldvalue": "example-store.myshopify.com" },
{ "credentialkey": "shopify", "fieldname": "clientid", "fieldvalue": "YOUR_SHOPIFY_CLIENT_ID" },
{ "credentialkey": "shopify", "fieldname": "clientsecret", "fieldvalue": "YOUR_SHOPIFY_CLIENT_SECRET" }
]
}'
3. Start OAuth
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "shopify",
"authmethod": "own",
"redirecturl": "https://your-app.example/settings/integrations"
}'
Open the returned authorizeUrl in the user's browser. After consent, Wiro exchanges the code for an expiring offline access token and refresh token, records both provider expiry values, reads the shop's ID, name and myshopify.com domain through GraphQL, and redirects to your redirecturl with shopify_connected=true&shopify_shop=<shop>.myshopify.com&shopify_name=<shop name> (the shop parameters are left out when that lookup fails). A failed connection gets shopify_error=<code> instead, for example invalid_signature (the callback HMAC is missing or does not match), invalid_shop (the callback shop is not the saved shopdomain), authorization_denied, session_expired or token_exchange_failed (also when Shopify's token response has no refresh token or expiry values). Refresh uses grant_type=refresh_token; Shopify can rotate both tokens, so Wiro stores each replacement atomically rather than reusing an old refresh token.
Check or disconnect
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthStatus" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "useragentguid": "your-useragent-guid", "credentialkey": "shopify" }'
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthDisconnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "useragentguid": "your-useragent-guid", "credentialkey": "shopify" }'
Disconnect clears the tokens, the shop name and ID, shopdomain and the saved authmethod. Wiro does not revoke the token at Shopify. clientid and clientsecret stay saved. Before you reconnect, save shopdomain again, plus authmethod: "api_key" for Client ID + Secret. Without shopdomain, OAuthConnect in "own" mode returns Shop Domain is required.
Runtime behavior
- Endpoint:
https://{shop}.myshopify.com/admin/api/2026-07/graphql.json - Authentication:
X-Shopify-Access-Token - Client-credentials tokens report
expires_in: 86399and are re-exchanged automatically before expiry. - Customer-owned OAuth uses expiring offline access and refresh tokens. Wiro refreshes and atomically replaces the pair before the access token expires; reconnect is required if the refresh authorization expires or is revoked.
- Reads are paginated with GraphQL cursors.
- Every mutation checks both top-level
errorsand mutation-specificuserErrors. - Products are created as drafts unless publication is explicitly requested.
- Missing scopes are treated as hard permission boundaries; the agent does not switch authentication methods or attempt a workaround.
Mutation safety
- Compare-and-set inventory:
inventorySetQuantitiesincludes the last-read quantity for each inventory item/location. A stale comparison stops the write; Wiro re-reads state instead of bypassing the conflict. - Scoped idempotency: Wiro reuses one stable key only for mutations whose 2026-07 schema documents native idempotency. It does not attach an idempotency directive to arbitrary GraphQL mutations.
- Ambiguous outcomes: timeout, disconnect, throttle, or 5xx after transmission is
unknown, not an automatic retry. Wiro queries the natural resource key and reconciles remote state first. - Collections: membership changes use only collection mutations supported by the 2026-07 schema. Deprecated legacy collection add/remove operations are not used.
- Protected customer data: nominal customer scopes may still require Shopify protected-customer-data approval and staff permissions. Wiro requests the minimum fields needed and does not put customer PII, addresses, order details, or payment data into its mutation ledger.
Related
WooCommerce Integration
Connect a Wiro agent directly to a WooCommerce store with a REST API consumer key and secret.
Overview
The int-woocommerce-manage skill uses WooCommerce's official, current recommended WP REST API namespace, wc/v3, to work with products, variations, taxonomy, inventory, orders, refunds, coupons, customers, reports, and supported store settings.
| Mode | Status | Notes |
|---|---|---|
| Consumer key + consumer secret | Available | Direct HTTPS Basic Authentication. No OAuth app or browser redirect. |
Prerequisites
- A deployed Wiro agent with the
int-woocommerce-manageskill enabled. - A public HTTPS WooCommerce store with REST API routing enabled.
- A WordPress user with the minimum permissions needed for the requested operations.
Setup
1. Create a WooCommerce REST API key
In WordPress Admin:
- Open WooCommerce → Settings → Advanced → REST API.
- Select Add key.
- Choose the WordPress user the agent should act as.
- Choose Read/Write only if the agent must modify the store; otherwise use Read.
- Generate the key and copy both the consumer key and consumer secret.
2. Save credentials
Use the store's public base URL. Keep an existing WordPress subdirectory, but omit /wp-json/wc/v3, query strings, fragments, and the trailing slash.
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "woocommerce", "fieldname": "storeurl", "fieldvalue": "https://store.example.com" },
{ "credentialkey": "woocommerce", "fieldname": "consumerkey", "fieldvalue": "ck_..." },
{ "credentialkey": "woocommerce", "fieldname": "consumersecret", "fieldvalue": "cs_..." }
]
}'
3. Start or restart the agent
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
Credential fields
| Field | Type | Description |
|---|---|---|
storeurl |
string | Public HTTPS store URL, without the WooCommerce REST path. |
consumerkey |
secret string | WooCommerce consumer key, normally beginning with ck_. |
consumersecret |
secret string | WooCommerce consumer secret, normally beginning with cs_. |
Runtime behavior
- Base endpoint:
{storeurl}/wp-json/wc/v3 - Authentication: HTTPS Basic Auth with the consumer key and secret.
- Credentials are never added to URL query parameters.
- Collection endpoints use page-number pagination and inspect
X-WP-TotalPages. - The agent reads the current resource before a write and verifies the resource after a successful mutation.
- Ambiguous create/update outcomes are reconciled by reading remote state before any retry. WooCommerce has no universal idempotency header.
- Refund amount, currency, line items, restock behavior, and gateway behavior must be explicit; the agent does not infer them.
Products, inventory, and batch requests
- Product and variation writes use documented fields such as
manage_stock,stock_quantity,stock_status, andbackorders. Wiro does not treatlow_stock_amountas a supported product/variation mutation field. POST /products/batchacceptscreate,update, anddeletearrays. It is a convenience batch, not one atomic transaction: inspect every returned array item, and reconcile each item independently.- A top-level 2xx response does not mean every batch item succeeded. Do not retry the whole batch after a partial or ambiguous result; retrying confirmed successes can duplicate creates.
- WooCommerce has no universal idempotency-key header. Wiro uses natural keys such as SKU/slug, records one ledger entry per item, and reads remote state before retrying an uncertain write.
Settings
- Read groups with
GET /settings, group options withGET /settings/{group_id}, and one option withGET /settings/{group_id}/{option_id}. - Update one writable option with
PUT /settings/{group_id}/{option_id}. - Batch-update writable options in one group with
POST /settings/{group_id}/batchand anupdatearray. This endpoint does not create or delete arbitrary settings. - Payment gateways and shipping zones are separate resources, not generic setting options.
Errors and rate limits
WooCommerce/WordPress errors use the HTTP status plus a JSON object shaped like { code, message, data }; data.status commonly repeats the status. For batch calls, also inspect each returned item.
Core wc/v3 does not publish one built-in global request quota or standardized rate-limit header contract. A store, host, WAF, reverse proxy, or plugin can still return 429. When it does, honor Retry-After or another explicit reset header if present; otherwise stop and retry later with conservative backoff. Do not copy the optional WooCommerce Store API RateLimit-* contract onto wc/v3.
Troubleshooting
- 400: The payload, field, or state transition is invalid. Read the response's
code,message, anddata; do not infer success from a partially populated object. - 401: The key/secret is invalid, revoked, or belongs to a different store.
- 403: The key's WordPress user or permission level cannot access the resource.
- 404 under
/wp-json/wc/v3: The store URL or WordPress subdirectory is wrong, WooCommerce REST routing is unavailable, or permalinks need configuration. - 409: The resource changed or conflicts with current state. Re-read it before deciding whether a new write is appropriate.
- 429: A store-specific limiter blocked the request. Follow the headers that store actually returned;
wc/v3itself does not guaranteeRetry-After. - 5xx or transport timeout after a write: The outcome is unknown. Reconcile by resource ID or natural key before any retry.
- WAF or reverse proxy failures: Allow authenticated requests to the WooCommerce REST route without redirecting to another hostname.
Related
Reddit Integration
Technical contract for connecting a Wiro agent to Reddit with a customer-owned Reddit web app. The endpoints remain documented, but the feature is not available until Reddit approves Wiro's commercial use and a written commercial contract is in force.
Overview
The int-reddit-post skill supports:
- connected-user identity;
- subscribed and contributor subreddits;
- subreddit rules;
- text and link submissions;
- comments and replies;
- editing or deleting only content authored by the connected Reddit identity.
Voting, private messages, chat, moderation queues, bulk posting, mass cross-posting, scraping, and browser automation are out of scope.
Unavailable pending Reddit approval. Wiro is a commercial product. A checkbox or customer-owned app does not authorize commercial Data API use. Wiro will not enable this integration until Reddit has granted explicit Data API approval for the use case and both parties have completed the required written commercial contract.
Availability and policy requirements
| Mode | Status | Notes |
|---|---|---|
Customer-owned OAuth app ("own") |
Unavailable pending Wiro approval/contract | The authorization-code endpoints and callback contract are implemented, but production access remains disabled. |
| Wiro shared app | Not offered | Each operator supplies and controls its own Reddit app. |
| Permanent pasted bearer token | Not supported | Access and refresh tokens are managed by the OAuth callback. |
The prerequisites are cumulative:
- Reddit Data API approval for Wiro's described use case.
- Reddit's explicit written commercial approval and completed contract.
- A registered developer profile and visible App profile label.
- A dedicated app account used only for app functions, not a mixed-use personal account.
- A customer-owned Reddit
web appregistered with the Wiro callback.
Three Wiro-managed flags gate the connection: developerprofileverified, dataapiaccessapproved and commercialwrittenapproval. Wiro sets them only after it has reviewed the labeled developer profile, Reddit's Data API approval for this app and Reddit's written commercial approval. You cannot set them: CredentialUpsert refuses each one with <Field label> is managed by the platform. Until all three are on, OAuthConnect returns an error such as The platform must verify Reddit Data API approval for this app before connecting. The flags grant no rights and do not replace Reddit's review or the commercial contract.
Prerequisites
- A deployed Wiro agent with the
int-reddit-postskill enabled. - A dedicated Reddit app account.
- A customer-owned Reddit app created as type web app.
- A registered Reddit developer profile and App profile label that accurately describes the app and its commercial purpose.
- Confirmed Reddit Data API approval plus Wiro's written commercial contract with Reddit.
Technical setup after approval
The requests below describe the hard-cutover API contract for rollout readiness. They do not bypass the availability gate above.
1. Create the Reddit web app
Create the app in Reddit's developer settings and use this exact redirect URI:
https://api.wiro.ai/v1/UserAgentOAuth/RedditCallback
Copy the app's client ID and client secret. The developer profile, App profile label, and dedicated app account must remain attached to this app; do not create duplicate accounts or apps to evade review or limits.
2. Save the app credentials and the developer profile
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "reddit", "fieldname": "authmethod", "fieldvalue": "own" },
{ "credentialkey": "reddit", "fieldname": "clientid", "fieldvalue": "YOUR_REDDIT_CLIENT_ID" },
{ "credentialkey": "reddit", "fieldname": "clientsecret", "fieldvalue": "YOUR_REDDIT_CLIENT_SECRET" },
{ "credentialkey": "reddit", "fieldname": "developerprofileusername", "fieldvalue": "your_app_account" }
]
}'
developerprofileusername is the dedicated Reddit app account that owns the web app, without the u/ prefix (3 to 20 letters, digits, _ or -). Without it OAuthConnect returns Developer Profile Username is required. Do not send the approval flags: Wiro sets them and CredentialUpsert refuses them.
3. Start OAuth
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "reddit",
"authmethod": "own",
"redirecturl": "https://your-app.example/settings/integrations"
}'
Open the returned authorizeUrl in the user's browser. Wiro requests these scopes:
identity read mysubreddits submit edit history
history is used only for bounded recovery: after an ambiguous create/reply outcome, Wiro may inspect at most the connected user's latest 25 submissions/comments to determine whether the write landed. It is not permission for broad history collection.
The flow requests duration=permanent, allowing Wiro to refresh the one-hour access token with the callback-managed refresh token. Approve access while signed in to Reddit as the developer profile account. After consent, the browser returns to your redirecturl with reddit_connected=true&reddit_username=<name>. If the account that approved access is not developerprofileusername, or Wiro cannot read it, the redirect carries reddit_error=developer_profile_mismatch instead and nothing is saved. Other failures return reddit_error=<code>, such as authorization_denied, session_expired or token_exchange_failed. Production OAuth remains blocked until Wiro's approval/contract gate is complete.
Check or disconnect
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthStatus" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "useragentguid": "your-useragent-guid", "credentialkey": "reddit" }'
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthDisconnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "useragentguid": "your-useragent-guid", "credentialkey": "reddit" }'
Disconnect asks Reddit to revoke the refresh token and clears the connection in Wiro even if that request fails. clientid and clientsecret stay saved, but developerprofileusername and Wiro's three approval flags are cleared too, so save the username again and wait for Wiro to set the flags before you reconnect.
Runtime safeguards
- Authenticated API calls use
https://oauth.reddit.com; OAuth token calls usehttps://www.reddit.com. - Every request carries the User-Agent
server:<CLIENT_ID>:1.0.0 (by /u/<DEVELOPER_PROFILE_USERNAME>), built from the app's client ID anddeveloperprofileusername. Wiro does not use a browser/default User-Agent or misidentify the client. - The agent reads subreddit rules before a write.
- One approval covers one concrete subreddit or fullname and one payload. A request to post everywhere is refused.
- The agent blocks duplicate and near-duplicate submissions and does not fan a single payload out across communities.
- Edits and deletes require a fresh ownership check against the connected Reddit username.
- Ambiguous write outcomes are not automatically retried.
- Recovery reads are bounded to the latest 25 items and require the
historyscope; no scraping or broad history retention is permitted.
Rate limits
Reddit documents OAuth limits through the response headers:
X-Ratelimit-UsedX-Ratelimit-RemainingX-Ratelimit-Reset(seconds until reset)
The 100 queries-per-minute OAuth-client limit, averaged over a 10-minute window, applies only to clients that Reddit has found eligible for free Data API access. It is not a commercial entitlement. Wiro follows the limits and commercial terms assigned by Reddit; response headers and the executed contract are authoritative. Calls are sequential, and Wiro enters cooldown on HTTP 429 or a Reddit RATELIMIT error without retrying before reset.
Deletion and retention obligations
- Wiro stores only bounded mutation/recovery metadata needed to prevent duplicate writes; it does not build or retain a broad Reddit history dataset.
- If a Reddit post or comment is deleted, all retained title, body, URL, and related content must be removed. If an account is deleted, retained user IDs and author-identifying references must also be removed.
- De-identified or anonymized copies of deleted Reddit content are not retained as a workaround.
- Stored Reddit data is routinely minimized and deletion checks follow Reddit's contract and compliance tooling; Reddit recommends removing stored user data/content within 48 hours.
- Disconnecting the integration stops new access but does not weaken obligations to honor content/account deletions already received.
Related
Facebook Page Integration
Connect your agent to one or more Facebook Pages with a recommended Meta System User token or advanced customer-owned OAuth.
Overview
The Facebook Page integration uses Meta Graph API v26 with a separate Page-scoped access token for every selected Page. The recommended direct mode accepts a Meta Business Manager System User token, validates it only on Wiro's server, discovers its assigned Pages, and derives the selected Page tokens. The API never returns the Page tokens, and the System User token never reaches the agent. Customer-owned OAuth remains available as an advanced path.
Skills that use this integration:
int-facebookpage-post: Publish text, photo, and video posts to a Facebook Page, and read Page and post insights
Agents that typically enable this integration:
- Social Manager
- Any custom agent that needs Facebook Page posting
Availability
| Mode | Status | Notes |
|---|---|---|
"api_key" |
Recommended | Enter a Business Manager System User token. No App ID, App Secret, or browser redirect is entered in Wiro. |
"own" |
Advanced | Use your own Meta Developer App and browser OAuth. Development Mode works for users assigned an App Role. |
"wiro" |
Coming soon | Wiro's shared Meta App is under review by Meta. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview); keep the
useragents[0].guid. - A Meta Business account (business.facebook.com).
- At least one Facebook Page assigned to the connecting principal with the
CREATE_CONTENTtask. AddMODERATEwhen the agent should add comments, andANALYZEwhen it should read insights. - Recommended direct mode: a System User and the Business app used to generate its token.
- Advanced OAuth mode: a Meta Developer account, your own Business app, and an HTTPS callback URL for your backend.
Recommended Setup: System User Token
This path is selected by default in the Wiro dashboard. It avoids browser OAuth and does not require entering an App ID or App Secret in Wiro.
Step 1: Prepare the System User and Page assets
- Open Meta Business Settings → Users → System Users.
- Create or select a System User.
- Assign every Facebook Page the agent may publish to with the
CREATE_CONTENTtask. Also assignMODERATEwhen the agent should add comments, andANALYZEwhen it should read insights. - Select Generate new token and choose the Business app used for the integration.
- At Set expiration, choose Never when Meta offers it. Some businesses are required to use an expiring token; reconnect Wiro with a newly generated token before that token expires.
- Grant:
business_managementpages_show_listpages_read_engagementpages_manage_postspages_manage_engagementwhen comments are neededpublish_videowhen Page video publishing is neededread_insights(optional) when Page and post insights are needed
If a permission is absent from the token dialog, add the corresponding app use case using Meta's use-case permission mapping. The Business app must not require appsecret_proof on every server request, because direct mode intentionally does not collect the App Secret.
Step 2: Save the token
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "facebook-pages", "fieldname": "authmethod", "fieldvalue": "api_key" },
{ "credentialkey": "facebook-pages", "fieldname": "systemusertoken", "fieldvalue": "YOUR_SYSTEM_USER_ACCESS_TOKEN" }
]
}'
The token is stored encrypted and never reaches the agent. Once saved, it reads "••••••••" on UserAgent/Detail, like every saved secret. To change it, save a new token.
Step 3: Validate the token and discover Pages
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "facebook-pages",
"authmethod": "api_key"
}'
Response:
{
"result": true,
"accounts": [
{ "id": "123", "name": "Main Page" },
{ "id": "456", "name": "Regional Page" }
],
"flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19",
"account": "Acme System User",
"restart": "none",
"errors": []
}
Only Page IDs and names are returned. Wiro keeps the System User token and all derived Page access tokens server-side. A valid token with no assigned Page carrying CREATE_CONTENT returns an error instead of an empty successful connection.
Step 4: Select one or more Pages
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/SetPickerAccounts" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "facebook-pages",
"accounts": [
{ "pageid": "123", "fbpagename": "Main Page" },
{ "pageid": "456", "fbpagename": "Regional Page" }
]
}'
This finalizes the connection by matching each requested Page against the server-side discovery result and storing only its Page-scoped runtime token. Call it within 15 minutes of OAuthConnect. The dashboard auto-selects a sole Page and opens a multi-select Page picker when several are returned. API clients must still perform this request explicitly.
Step 5: Verify the connection
Call POST /UserAgentOAuth/OAuthStatus with { "useragentguid": "...", "credentialkey": "facebook-pages" }. A successful direct connection returns the selected Pages, connected: true, and an empty tokenexpiresat.
Advanced Setup: Customer-Owned OAuth
This path uses Meta's documented Facebook Login for Business flow.
Step 1: Create a Meta Developer App
You can reuse a single Meta App for Facebook Page, Instagram, and Meta Ads.
- developers.facebook.com/apps → Create app → Other → Business.
- Enter an App display name (what users see on consent screens), App contact email, select your Business Account, then Create app.
- Leave it in Development Mode.
Step 2: Add "Facebook Login for Business" and register the redirect URI
- Add product → Facebook Login for Business → Set up.
- Facebook Login for Business → Settings.
-
Under Valid OAuth Redirect URIs, add:
https://api.wiro.ai/v1/UserAgentOAuth/FBCallback - Save changes.
Step 3: Note the required permissions
Wiro requests these exact scopes:
pages_show_list,pages_manage_posts,publish_video,pages_manage_engagement,pages_read_engagement,pages_read_user_content,pages_manage_metadata,pages_messaging,read_insights
| Permission | Why |
|---|---|
pages_show_list |
Enumerate the Pages the user administers. |
pages_manage_posts |
Publish and manage Page posts and photos. |
publish_video |
Publish videos to a Page. |
pages_manage_engagement |
Add and moderate comments as the Page. |
pages_read_engagement |
Read likes, comments, and shares on the Page's posts. |
pages_read_user_content |
Read user-generated content on the Page (for context). |
pages_manage_metadata |
Webhook subscriptions and Page metadata. |
pages_messaging |
Send and receive messages on behalf of the Page (some skills use this). |
read_insights |
Read Page and post insights (see Insights). |
These work without App Review in Development Mode for any Facebook user in App Roles.
Step 4: Copy your App ID and App Secret
App settings → Basic → copy App ID and App Secret.
Step 5: Add other Facebook accounts as Testers (only if needed)
Connecting your own Facebook account? You're the app Admin, so skip this. Connecting a customer's account? Add them under App Roles → Roles → Add People → Testers. They accept at facebook.com/settings → Business Integrations.
Step 6: Save your Meta App credentials to Wiro
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "facebook-pages", "fieldname": "appid", "fieldvalue": "YOUR_META_APP_ID" },
{ "credentialkey": "facebook-pages", "fieldname": "appsecret", "fieldvalue": "YOUR_META_APP_SECRET" },
{ "credentialkey": "facebook-pages", "fieldname": "authmethod", "fieldvalue": "own" }
]
}'
Wiro merges this into only the facebook-pages group, and other credentials are untouched.
Step 7: Initiate OAuth
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "facebook-pages",
"redirecturl": "https://your-app.com/settings/integrations",
"authmethod": "own"
}'
Response:
{
"result": true,
"authorizeUrl": "https://www.facebook.com/v26.0/dialog/oauth?client_id=...&redirect_uri=...&scope=pages_show_list%2Cpages_manage_posts%2Cpublish_video%2Cpages_manage_engagement%2Cpages_read_engagement%2Cpages_read_user_content%2Cpages_manage_metadata%2Cpages_messaging%2Cread_insights&auth_type=rerequest&response_type=code&state=...",
"flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19",
"errors": []
}
Redirect the user's browser to authorizeUrl. State has a 15-minute TTL.
Step 8: Handle the callback and list returned Pages
After consent, Wiro exchanges the code for a user access token, reads the user's Pages with their page-specific access tokens, keeps the list server-side, and redirects the user to your redirecturl. Wiro reads only the first page of Meta's Page list, so a user with many Pages may not see all of them, and the list does not check the user's task on each Page. System User mode reads up to 500 assigned Pages and lists only Pages with CREATE_CONTENT.
Crucial: Wiro does not auto-select a Page. On a first connection, after OAuthDisconnect, or when switching from System User mode, the connection is incomplete until the client calls SetPickerAccounts, and OAuthStatus returns connected: false until then. On a reconnect, the Pages saved earlier stay connected until SetPickerAccounts replaces them.
Success URL:
https://your-app.com/settings/integrations?fb_connected=true&fb_pages=%5B%7B%22id%22%3A%22123%22%2C%22name%22%3A%22Page%20A%22%7D%2C%7B%22id%22%3A%22456%22%2C%22name%22%3A%22Page%20B%22%7D%5D
Query parameters:
| Param | Meaning |
|---|---|
fb_connected=true |
OAuth completed; credentials are cached server-side awaiting page selection. |
fb_pages |
URL-encoded JSON array [{ id, name }, ...] of the Pages Wiro read for this user (the first page of Meta's list). The per-page access tokens stay server-side. The client only receives ID and name. |
fb_error=<code> |
Failure. See Troubleshooting. |
Parse:
const params = new URLSearchParams(window.location.search);
if (params.get("fb_connected") === "true") {
// URLSearchParams already decodes the value, so don't call decodeURIComponent on it.
const pages = JSON.parse(params.get("fb_pages") || "[]");
if (pages.length === 0) {
// Not expected: the callback returns fb_error=no_pages when no Page can be listed.
showError("No Facebook Pages to manage.");
} else if (pages.length === 1) {
// One Page: SetPickerAccounts is still required.
await setPickerAccounts([{ pageid: pages[0].id, fbpagename: pages[0].name }]);
} else {
presentPagePicker(pages);
}
} else if (params.get("fb_error")) {
handleError(params.get("fb_error"));
}
Step 9: Persist the page selection (required)
This step is mandatory. On a first connection, the connection remains incomplete and OAuthStatus reports connected: false until you call SetPickerAccounts.
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/SetPickerAccounts" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "facebook-pages",
"accounts": [
{ "pageid": "456", "fbpagename": "Page B" }
]
}'
Response:
{
"result": true,
"accounts": [
{ "id": "456", "name": "Page B" }
],
"restart": "scheduled",
"errors": []
}
Wiro validates every requested Page against the server-side discovery result, stores its long-lived Page access token without returning it to the client, and restarts a running agent so the new selection takes effect.
If the 15-minute window lapses before you call SetPickerAccounts, or an earlier call already saved a selection from it, you'll get The sign-in expired. Sign in again to choose the accounts. with errorcode: "flow_expired" (the wording depends on whether it was a sign-in or a token check). Repeat Step 3 for System User mode or Step 7 for OAuth.
Wiro saves each Page's name from its list (the name in fb_pages or in the OAuthConnect response), so fbpagename can be left out, and a name you send is not read. Only the Wiro account that started the sign-in or check can save from its list. The Facebook Pages picker accepts one or more entries: pass multiple { pageid, fbpagename } objects to authorize the agent against several Pages at once.
Step 10: Verify the connection
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthStatus" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "facebook-pages"
}'
Response:
{
"result": true,
"connected": true,
"accounts": [
{ "id": "456", "name": "Page B" }
],
"connectedat": "2026-04-17T12:00:00.000Z",
"tokenexpiresat": "",
"errors": []
}
connected: truerequires a validated active mode and at least one saved Page, meaningSetPickerAccountscompleted successfully.accounts[]carries one entry per selected page (id=pageid,name=fbpagename).- Long-lived Facebook Page tokens have no fixed expiration date. They can still be invalidated when the user changes access, removes permissions, deauthorizes the app, or changes security-sensitive account settings.
Step 11: Start the agent if it's not running
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
Agents already running at SetPickerAccounts time restart automatically to pick up the new credentials.
API Reference
POST /UserAgentOAuth/OAuthConnect
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
credentialkey |
string | Yes | "facebook-pages". |
redirecturl |
string | OAuth only | Any HTTPS URL you control (or http://localhost / http://127.0.0.1 for dev). Direct System User validation does not use it. |
authmethod |
string | No | "api_key" for the recommended System User path, "own" for customer-owned OAuth, or "wiro" when Wiro-managed OAuth becomes available. Send the value explicitly. |
OAuth response: { result, authorizeUrl, flowid, errors }. Direct response: { result, accounts: [{id, name}], flowid, account, restart, errors } with no authorizeUrl, where account is the System User's name and restart is "none" until the Pages are saved. A failed direct check returns { result: false, errorcode, flowid, errors }. Read errorcode, because most failures share one message: no_pages (no assigned Page with CREATE_CONTENT), too_many_pages (Meta listed more than 500 Pages), direct_token_missing (no systemusertoken saved, or the saved authmethod is not "api_key"), direct_token_invalid or provider_rejected_request (Meta refused the token or the request), provider_timeout or provider_request_failed (Meta did not answer). Other codes mean the check could not finish; try again. A check that finds a saved token first clears the saved Page selection, so call SetPickerAccounts after every successful check.
GET /UserAgentOAuth/FBCallback
Server-side. Query params appended to your redirecturl:
| Param | Meaning |
|---|---|
fb_connected=true |
OAuth completed; pending payload cached awaiting SetPickerAccounts. |
fb_pages |
URL-encoded JSON [{id, name}, ...] of the Pages Wiro read for this user (the first page of Meta's list). |
fb_error=<code> |
Failure. |
The callback path is per-provider: Facebook's stays FBCallback.
POST /UserAgentOAuth/SetPickerAccounts
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
credentialkey |
string | Yes | "facebook-pages". |
accounts |
array | Yes | One or more { pageid, fbpagename } entries. The per-page access token is resolved from the latest server-side OAuth or System User discovery result, so don't supply it. |
Response: { result, accounts: [{id, name}, ...], restart, errors }. The save that completes the connection restarts a running agent once (restart: "scheduled"), and a save that changes nothing restarts nothing.
Call within 15 minutes of the OAuth callback or direct OAuthConnect discovery. A successful call uses up that discovery result, so to choose other Pages later, restart the selected connection flow.
POST /UserAgentOAuth/OAuthStatus
Body: { useragentguid, credentialkey: "facebook-pages" }. Response: connected (only true after the active mode is validated and at least one Page is selected), accounts: [{id, name}, ...] (every selected Page), connectedat, and an empty tokenexpiresat.
POST /UserAgentOAuth/OAuthDisconnect
Body: { useragentguid, credentialkey: "facebook-pages" }. Clears the active token and Page selection without remote revocation. Direct mode also clears systemusertoken; customer-owned OAuth App ID and App Secret are preserved for reconnection.
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthDisconnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "facebook-pages"
}'
Token lifecycle
Selected Pages use long-lived Page tokens with no fixed expiration timestamp. Meta can still invalidate them when permissions, asset assignments, app access, or account security settings change. In direct mode, an expiring System User token must also be regenerated before Meta's stated expiry. If either token is invalidated, enter a current System User token or repeat customer-owned OAuth, then select the Pages again.
Using the Skill
Once the Facebook Page is connected, the agent uses int-facebookpage-post to publish text, photo, and video posts, and to read Page and post insights. To adjust the Social Manager's bundled cs-cron-social-content-scanner schedule, call POST /UserAgent/CustomSkillUpsert with enabled and interval only:
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"skillkey": "cs-cron-social-content-scanner",
"enabled": true,
"interval": "0 */4 * * *"
}'
To change what the scheduled task posts (topics, tone, content angle), edit the paired preference skill cs-content-tone instead (see Agent Skills → Updating Preference Skills).
The agent posts an approved draft, or the text, link and media you give it in chat. Hashtags, calls to action and links come from the draft, cs-content-tone, or the agent's preferences; without hashtag rules the agent adds 1 to 3. Facebook makes links clickable, so a draft's page link goes into the post.
Insights
The agent can also read how a connected Page and its posts are doing. Ask in chat, for example "How did my last 10 Facebook posts do?" or "Facebook Page views and follower change for October". Reading insights posts nothing and changes nothing, so it needs no approval. When several Pages are connected, name one, or ask for all of them.
| What | The agent reports | Facebook metrics |
|---|---|---|
| Posts | Views, unique viewers, reactions by type, activity by type (such as comments and shares), and clicks per post | post_media_view, post_total_media_view_unique, post_reactions_by_type_total, post_activity_by_action_type, post_clicks |
| The Page over a date range | Views, post engagements, new follows, unfollows, and the follower total on the first and last day | page_media_view, page_post_engagements, page_daily_follows_unique, page_daily_unfollows_unique, page_follows |
| Page reach | Unique viewers in the 28 days ending on the range's last day | page_total_media_view_unique |
- Aggregate numbers only. The agent never reads comment text, commenter names, follower lists, or audience demographics.
- Permission. Page insights need
read_insightsand theANALYZEtask on the Page. In System User mode, assignANALYZE(see Step 1), generate a new token that also grantsread_insights, save it, and connect again. Customer-owned OAuth requestsread_insights; a connection made before it was added needs one more sign-in. When the permission is missing, the agent asks you to reconnect with it. - Date range. Every reply names its date range. Without one, the agent uses the last 28 days ending yesterday. One request covers at most 90 days, Facebook keeps two years, and most Page metrics update once a day.
- Limits. A Page needs at least 100 likes for insights. Page insights don't count Reel interactions, and Facebook has no saves metric for Page posts. Meta retired
page_impressions,post_impressions, and thepage_fansmetrics in 2025; the views metrics above replace them. When Facebook has no number yet, the agent says so instead of showing 0.
Troubleshooting
| Error code | Meaning | What to do |
|---|---|---|
missing_params |
The callback was opened without an OAuth state. This error ends on the API's own neutral page, not on your app. |
Don't open the callback URL directly. Start a new flow from Step 7. |
session_expired |
>15 min between OAuthConnect and the callback. |
Call OAuthConnect again. |
flow_replaced |
A newer sign-in or token check for the same agent and credential replaced this sign-in, whoever started it, so nothing from it was saved. | Use the newer sign-in or check, or start again with OAuthConnect. |
authorization_denied |
User cancelled, or not listed in App Roles (Development Mode). | Add as Tester (Step 5), retry. |
token_exchange_failed |
Wrong App Secret or redirect URI mismatch. | Re-copy App Secret; verify redirect URI exactly. |
Facebook shows Invalid Scopes |
The app was set up with use cases and has not added a permission the connection asks for, such as read_insights. Facebook shows this only to the app's developers, which in own mode is usually the person connecting. |
In the app, open Use cases → Manage everything on your Page, add every permission in the scope table above, then connect again. |
no_pages |
User has no administered Facebook Pages. | Ask the user to create/administer a Page first, retry. |
useragent_not_found |
The agent was deleted, or is no longer owned by the account that started the flow, before Facebook returned. | Start again with OAuthConnect for an existing agent. |
Facebook credentials not configured |
Returned in OAuthConnect's errors[] when authmethod: "own" but appid / appsecret are missing. |
Call POST /UserAgent/CredentialUpsert with facebook-pages.appid and facebook-pages.appsecret, then retry. |
Meta could not validate this System User token |
Direct mode received an invalid token, missing permission, or inaccessible asset. | Generate a current System User token with the documented permissions and Page assignments, save it, and retry. |
| Valid token but no assigned Facebook Page | The System User has no Page with the CREATE_CONTENT task. |
Assign the Page in Business Settings and reconnect. |
internal_error |
Unexpected server error. | Retry once. If persistent, contact support. |
SetPickerAccounts returns flow_expired
No discovery result is waiting: the 15-minute window expired, a previous SetPickerAccounts already used it, or a newer connection replaced it. Repeat Step 3 for System User mode or Step 7 for OAuth. No pending Facebook connection. Please reconnect via OAuthConnect. means the same: connect again.
SetPickerAccounts returns flow_waiting
The OAuth sign-in of Step 7 hasn't come back yet, so it has no list to save from (The sign-in is not finished yet. Finish it, then choose the accounts.). Finish it, then save the Pages it lists. Don't call OAuthConnect again in the meantime: a new sign-in replaces the one under way. System User mode never returns this code.
SetPickerAccounts returns not_listed
The pageid you sent isn't in the latest discovery result (Choose accounts from the list the token check returned., or Choose accounts from the list the sign-in returned. after a sign-in). Verify you're parsing fb_pages correctly and sending the exact ID string.
Posts publish but as the wrong author
Check POST /UserAgent/Detail and verify credentials.facebook-pages.pageid is the Page you intended. If not, connect again (Step 3 or Step 7) and save the right Page from the new list within 15 minutes.
"App not verified" banner on consent
Expected in Development Mode. Users in App Roles can click Continue.
The agent says no Facebook Page is connected
The agent has int-facebookpage-post, but no Page is connected to it. It asks you to connect one instead of posting, and scheduled posting runs do nothing. Connect a Page and select it with SetPickerAccounts (Step 4, or Step 9 for OAuth), then ask again.
The agent asks you to reconnect for insights
Facebook refused an insights read because the connection lacks read_insights or the Page's ANALYZE task. In System User mode, assign ANALYZE, generate a new token that also grants read_insights, save it with CredentialUpsert, and repeat Steps 3 and 4. With customer-owned OAuth, connect again (Step 7), allow the permission, and select the Pages (Step 9). Publishing keeps working in the meantime.
Multi-Tenant Architecture
- One Wiro agent instance per customer.
- Recommended direct mode: each customer supplies a System User token from their own Business Portfolio. No browser consent screen or shared Wiro Meta app is involved.
- Advanced OAuth mode: each customer-owned Meta app controls its own App Roles, review status, and consent branding.
- Every Page token is isolated per useragent. Customer A's token is never returned to or shared with Customer B.
- Asset tasks must remain current. Losing
CREATE_CONTENT,MODERATE, orANALYZEaccess invalidates the corresponding publish, comment, or insights capability. MonitorOAuthStatusand require reconnection when it becomes disconnected.
Related
- Agent Credentials & OAuth
- Agent Overview
- Agent Skills
- Meta Ads integration: separate product; used for paid media, not organic posting.
- Instagram integration
- Meta for Developers: Pages API
- Meta for Developers: System User API calls
- Meta for Developers: Page insights
Instagram Integration
Connect your agent to one or more Instagram professional accounts with a recommended Meta System User token, or one account through advanced customer-owned Instagram OAuth.
Overview
The Instagram integration supports two official Meta paths. Recommended direct mode uses a Business Manager System User and the Facebook Pages linked to Instagram Business or Creator accounts. It supports selecting one or more discovered professional accounts. Advanced mode uses Instagram API with Instagram Login directly, authorizes one account per OAuth connection, and does not require a Facebook Page. Both paths keep tokens server-side and publish through Graph API v26.
The two token types use different official hosts: System User mode derives a Facebook Page access token and publishes through graph.facebook.com/v26.0; Instagram Login issues an Instagram User access token and publishes through graph.instagram.com/v26.0. Wiro selects the matching host automatically.
Skills that use this integration:
int-instagram-post: Publish feed carousels, Reels, and Stories, and read post and account insights; any agent can also post a finished video as a Reel
Agents that typically enable this integration:
- Social Manager
- Video Creator: to post the videos it makes as Reels. Add
int-instagram-postwithSkillsApply; like every skill, it is included in every plan. Video Creator then posts a Reel when the request asks for it or anInstagramline in itsvideo-preferencessays to, and otherwise offers to. - Any custom agent that needs Instagram publishing
Availability
| Mode | Status | Notes |
|---|---|---|
"api_key" |
Recommended | Enter a Business Manager System User token. Wiro discovers eligible linked Instagram professional accounts without browser OAuth. |
"own" |
Advanced | Use your own Meta Business app and Instagram Login OAuth. This path does not require a linked Facebook Page. |
"wiro" |
Coming soon | Wiro's shared Meta App is under review. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview); keep the
useragents[0].guid. - A Meta Business account (business.facebook.com).
- One or more Instagram Business or Creator accounts. Personal accounts cannot use content publishing.
- Recommended direct mode: a System User, the Business app used to generate its token, and a Facebook Page linked to each Instagram professional account you want the agent to use.
- Advanced OAuth mode: a Meta Developer account, an app configured for Instagram Login, and an HTTPS callback URL. A Facebook Page is not required for this mode.
Preparing the Instagram account
For recommended System User mode:
- In the Instagram mobile app: Settings → Account → Switch to Professional Account → pick Business or Creator.
- In Meta Business Suite: select the Facebook Page that should own the Instagram account → Settings → Linked accounts → Instagram → Connect account. Sign in with the Instagram account and grant manage permissions.
Without both steps, Facebook Graph API cannot discover the professional account from the System User's assigned Pages.
For advanced Instagram Login OAuth, only step 1 is required. Meta's Instagram Login flow accesses the professional account directly and does not require a Facebook Page.
Recommended Setup: System User Token
This is the dashboard's default path. Wiro uses the System User token only on the server to discover assigned Pages, find their linked Instagram professional accounts, and derive the Page access token required by the Facebook Login form of Instagram Content Publishing.
Step 1: Assign the Page and Instagram assets
- Complete Preparing the Instagram account.
- Open Meta Business Settings → Users → System Users.
- Create or select a System User.
- Assign every linked Facebook Page the agent may use with
CREATE_CONTENT. - Assign each Instagram account's Content task.
- Select Generate new token and choose the Business app used for this integration.
- At Set expiration, choose Never when Meta offers it. If Meta requires an expiring token for the business, regenerate and reconnect before expiry.
- Grant:
business_managementinstagram_basicinstagram_content_publishpages_show_listpages_read_engagementads_readads_managementinstagram_manage_insights(optional) when the agent should read insights
Meta's Page-linked publishing contract requires both ads permissions when the Page role is granted through Business Manager. instagram_manage_insights is needed only for insights; a token without it still publishes.
If a permission does not appear, add the matching app use case through Meta's use-case permission mapping. The Business app must not require appsecret_proof on every request because direct mode does not collect its App Secret.
Step 2: Save the token
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "instagram", "fieldname": "authmethod", "fieldvalue": "api_key" },
{ "credentialkey": "instagram", "fieldname": "systemusertoken", "fieldvalue": "YOUR_SYSTEM_USER_ACCESS_TOKEN" }
]
}'
The System User token is stored encrypted and never reaches the agent. Once saved, it reads "••••••••" on UserAgent/Detail, like every saved secret. To change it, save a new token.
Step 3: Validate and discover Instagram accounts
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "instagram",
"authmethod": "api_key"
}'
Response:
{
"result": true,
"accounts": [
{ "id": "17841400000000000", "name": "my_brand" }
],
"flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19",
"account": "Acme System User",
"restart": "none",
"errors": []
}
Only public IDs and usernames are returned. The System User and derived Page tokens stay server-side.
Step 4: Select the Instagram accounts
Instagram is a multi-select picker in recommended System User mode. Send one or more entries from the latest discovery response:
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/SetPickerAccounts" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "instagram",
"accounts": [
{ "accountId": "17841400000000000", "igusername": "my_brand" },
{ "accountId": "17841400000000001", "igusername": "my_second_brand" }
]
}'
Call this within 15 minutes of OAuthConnect. Wiro matches the selection against its server-side discovery result and stores each derived Page-scoped runtime token. The dashboard auto-selects a sole result; API clients must still call this endpoint explicitly. If several linked professional accounts are returned, the dashboard opens a checkbox picker and saves every selected account with its own server-side Page token.
Step 5: Verify the connection
Call POST /UserAgentOAuth/OAuthStatus with { "useragentguid": "...", "credentialkey": "instagram" }. A successful direct connection returns every selected numeric account ID and username in accounts[], connected: true, and an empty tokenexpiresat.
Advanced Setup: Customer-Owned Instagram OAuth
Step 1: Create a Meta Developer App
You may reuse a compatible Business app that already has the Instagram product configured.
- developers.facebook.com/apps → Create app → Other → Business.
- App display name, contact email, Business Account → Create app.
- Leave in Development Mode.
Step 2: Add the "Instagram" product
- From the app dashboard, Add product.
- Find "Instagram" (not "Instagram Basic Display", which is for personal accounts and is being deprecated).
- Set up.
Step 3: Configure the OAuth redirect URI
- Left sidebar: Instagram → API setup with Instagram login.
- Scroll to Business login settings → OAuth settings.
-
Add to Valid OAuth Redirect URIs:
https://api.wiro.ai/v1/UserAgentOAuth/IGCallback - Save changes.
Note: Instagram OAuth has its own authorize URL at instagram.com/oauth/authorize (not facebook.com/…), but the redirect URI is still registered inside the Meta Developer App.
Step 4: Note the required permissions
Wiro requests these exact scopes:
instagram_business_basic,instagram_business_content_publish,instagram_business_manage_messages,instagram_business_manage_comments,instagram_business_manage_insights
| Permission | Why |
|---|---|
instagram_business_basic |
Basic account info, profile data. |
instagram_business_content_publish |
Publish feed, carousel, reel, and story content. |
instagram_business_manage_messages |
Read and reply to DMs (used by some skills). |
instagram_business_manage_comments |
Read, reply, hide, delete comments. |
instagram_business_manage_insights |
Read engagement insights for posts and profile. |
These work without App Review in Development Mode for any Facebook user in App Roles. No pages_* scopes are requested, since Instagram Login uses its own scope family.
Step 5: Copy your App ID and App Secret
App settings → Basic → copy App ID, click Show → copy App Secret.
Step 6: Add users as Testers (only if needed)
If the connecting person is not the app Admin, add them under App Roles → Roles → Add People → Testers and have them accept before starting OAuth.
Step 7: Save your Meta App credentials to Wiro
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "instagram", "fieldname": "appid", "fieldvalue": "YOUR_META_APP_ID" },
{ "credentialkey": "instagram", "fieldname": "appsecret", "fieldvalue": "YOUR_META_APP_SECRET" },
{ "credentialkey": "instagram", "fieldname": "authmethod", "fieldvalue": "own" }
]
}'
Step 8: Initiate OAuth
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "instagram",
"redirecturl": "https://your-app.com/settings/integrations",
"authmethod": "own"
}'
Response:
{
"result": true,
"authorizeUrl": "https://www.instagram.com/oauth/authorize?client_id=...&redirect_uri=...&scope=instagram_business_basic%2Cinstagram_business_content_publish%2Cinstagram_business_manage_messages%2Cinstagram_business_manage_comments%2Cinstagram_business_manage_insights&response_type=code&state=...",
"flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19",
"errors": []
}
Step 9: Handle the callback
After consent, Wiro exchanges the code for a short-lived token, upgrades it to a long-lived token via graph.instagram.com/access_token?grant_type=ig_exchange_token, fetches the Instagram user info, and redirects the user back.
Success URL:
https://your-app.com/settings/integrations?ig_connected=true&ig_username=my_brand
Parse:
const params = new URLSearchParams(window.location.search);
if (params.get("ig_connected") === "true") {
const username = params.get("ig_username");
showSuccess(username ? `Connected @${username}` : "Instagram connected");
} else if (params.get("ig_error")) {
handleError(params.get("ig_error"));
}
Advanced Instagram Login OAuth has no secondary selection step. The authorized Instagram professional account is written directly by the callback as a one-entry account/token array, matching the same runtime contract as System User mode. The SetPickerAccounts step applies only to recommended System User mode.
Step 10: Verify the connection
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthStatus" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "instagram"
}'
{
"result": true,
"connected": true,
"accounts": [
{ "id": "17841400000000000", "name": "my_brand" }
],
"connectedat": "2026-04-17T12:00:00.000Z",
"tokenexpiresat": "2026-06-16T12:00:00.000Z",
"errors": []
}
connected: truerequires the active mode's validated secret plus the selected or authorized Instagram account.- Each
accounts[].idis a selected numeric Instagram professional account ID. - Each
accounts[].nameis its Instagram username without@. - Recommended System User mode can return multiple entries. Advanced Instagram Login OAuth returns one entry because one account is authorized per consent.
tokenexpiresatis empty for direct System User mode and approximately 60 days for customer-owned Instagram OAuth.- No
refreshtokenexpiresat: Instagram does not expose a separate refresh token for this connection.
Step 11: Start the agent if it's not running
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
API Reference
POST /UserAgentOAuth/OAuthConnect
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
credentialkey |
string | Yes | "instagram". |
redirecturl |
string | OAuth only | Any HTTPS URL you control (or localhost/127.0.0.1 for dev). Direct System User validation does not use it. |
authmethod |
string | No | "api_key" for recommended System User mode, "own" for customer-owned Instagram OAuth, or "wiro" when Wiro-managed OAuth becomes available. Send the value explicitly. |
OAuth response: { result, authorizeUrl, flowid, errors }. Direct response: { result, accounts: [{id, name}], flowid, account, restart, errors } with no authorizeUrl, where account is the System User's name and restart is "none" until the accounts are saved. A failed direct check returns { result: false, errorcode, flowid, errors }. Read errorcode, because most failures share one message: no_accounts (no assigned Page exposes a linked Instagram professional account with CREATE_CONTENT), too_many_instagram_accounts (Meta listed more than 500 Pages), direct_token_missing (no systemusertoken saved, or the saved authmethod is not "api_key"), direct_token_invalid or provider_rejected_request (Meta refused the token or the request), provider_timeout or provider_request_failed (Meta did not answer). Other codes mean the check could not finish; try again. A check that finds a saved token first clears the saved account selection, so call SetPickerAccounts after every successful check.
GET /UserAgentOAuth/IGCallback
Server-side. Query params appended to your redirecturl:
| Param | Meaning |
|---|---|
ig_connected=true |
OAuth succeeded. |
ig_username |
Connected Instagram handle (without @). |
ig_error=<code> |
Failure. |
The callback path is per-provider: Instagram's stays IGCallback.
POST /UserAgentOAuth/SetPickerAccounts
Used only by direct System User mode after OAuthConnect discovery.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
credentialkey |
string | Yes | "instagram". |
accounts |
array | Yes | One or more { accountId, igusername } entries from the latest discovery response (accountId is its id; Wiro saves its name from the list as igusername, so a name you send is not read). Do not supply access tokens. |
Call within 15 minutes of direct discovery. The response contains { result, accounts: [{id, name}], restart, errors }. The save that completes the connection restarts a running agent once (restart: "scheduled").
POST /UserAgentOAuth/OAuthStatus
Body: { useragentguid, credentialkey: "instagram" }. Response: connected, accounts: [{id, name}] where id is the numeric account ID and name is the username, connectedat, and tokenexpiresat.
POST /UserAgentOAuth/OAuthDisconnect
Body: { useragentguid, credentialkey: "instagram" }. Clears the active token and selected account without remote revocation. Direct mode also clears systemusertoken; customer-owned OAuth App ID and App Secret are preserved for reconnection.
Token lifecycle
Wiro refreshes renewable customer-owned Instagram OAuth tokens while the agent is running. Direct mode uses a System User token plus a derived Page token with no fixed expiry recorded by Wiro. Meta can still invalidate either token when permissions, asset assignments, or account security change; expiring System User tokens must be regenerated before Meta's stated expiry. If OAuthStatus keeps reporting connected: false while the agent runs, reconnect using the active mode.
Using the Skill
Once Instagram professional accounts are connected, the agent uses int-instagram-post to publish feed carousels, reels, and stories, and to read their insights. A request must identify one account when multiple are connected; the agent never guesses or publishes to all accounts from an ambiguous instruction. To adjust the Social Manager's bundled cs-cron-social-content-scanner schedule, call POST /UserAgent/CustomSkillUpsert with enabled and interval only:
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"skillkey": "cs-cron-social-content-scanner",
"enabled": true,
"interval": "0 */4 * * *"
}'
To change what the scheduled task posts (topics, tone, hashtag rules, caption style), edit the paired preference skill cs-content-tone instead (see Agent Skills → Updating Preference Skills).
Hashtags, calls to action and links come from your draft, cs-content-tone, or the agent's preferences. Without hashtag rules the agent adds 3 to 5 relevant hashtags; Instagram allows at most 5 per post. Instead of a drafted post, you can give the agent the caption and the images or videos in chat: the first one is the cover.
Posting a video as a Reel
Any agent with int-instagram-post and a connected account can post one finished video as a Reel, for example a video made by Video Creator. Ask for it in chat, and name the account when several are connected.
- No drafts. Instagram's API has no draft or private post, so a Reel is public as soon as it is published. The agent posts when your request asks for it, or after you approve; otherwise it waits.
- The video. A vertical (9:16) MP4 of 3 seconds to 15 minutes, up to 300 MB and at most 1920 px wide. A 16:9 video is too wide for a Reel, so Video Creator makes a 9:16 version instead.
- The caption. The hook first, then a few short lines and the call to action. Instagram doesn't make links in a caption clickable, so the call to action points to the link in your profile.
- The reply carries the Reel's link. If publishing fails, the agent checks the account's latest posts first, since the Reel may already be live.
Instagram allows each account 50 posts through the API in 24 hours.
Insights
The agent can also read how a connected account is doing. Ask in chat, for example "How did my last 10 Instagram posts do?" or "Instagram reach and follower change for October". Reading insights posts nothing and changes nothing, so it needs no approval. When several accounts are connected, name one, or ask for all of them.
| What | The agent reports | Instagram metrics |
|---|---|---|
| Posts, carousels and Reels | Reach, views, saves, shares, comments, likes, and total interactions per post | reach, views, saved, shares, comments, likes, total_interactions |
| Stories (System User mode only) | Reach, views, shares, and total interactions while the story is live | reach, views, shares, total_interactions |
| The account over a date range | Reach, views, total interactions, and accounts engaged | reach, views, total_interactions, accounts_engaged |
| Followers | Accounts that followed and accounts that unfollowed in the range, and the current follower count | follows_and_unfollows, followers_count |
- Aggregate numbers only. The agent never reads comment text, commenter names, follower lists, or audience demographics.
- Permission. System User mode needs
instagram_manage_insightson the token: generate a new token that includes it (see Step 1), save it, and connect again. Instagram Login already requestsinstagram_business_manage_insights. When the permission is missing, the agent asks you to reconnect with it. - Date range. Every reply names its date range. Without one, the agent uses the last 28 days ending yesterday. Instagram keeps account metrics for 90 days and post metrics for up to 2 years, and its numbers can be up to 48 hours behind.
- Limits. Story metrics last 24 hours, and Instagram hides story numbers below 5. Follows and unfollows need at least 100 followers. Instagram has no insights for the single photos inside a carousel. When Instagram has no number yet, the agent says so instead of showing 0.
Troubleshooting
| Error code | Meaning | What to do |
|---|---|---|
missing_params |
The callback was opened without an OAuth state. This error ends on the API's own neutral page, not on your app. |
Don't open the callback URL directly. Start a new flow from Step 8. |
session_expired |
>15 min between OAuthConnect and callback. |
Call OAuthConnect again. |
flow_replaced |
A newer sign-in or token check for the same agent and credential replaced this sign-in, whoever started it, so nothing from it was saved. | Use the newer sign-in or check, or start again with OAuthConnect. |
authorization_denied |
User cancelled, or not in App Roles (Development Mode). | Add as Tester (Step 6), retry. |
token_exchange_failed |
Wrong App Secret, redirect URI mismatch, or Instagram rejected the authorization code. | Re-copy the App Secret, verify the redirect URI, and retry Instagram Login. |
useragent_not_found |
The agent was deleted, or is no longer owned by the account that started the flow, before Instagram returned. | Start again with OAuthConnect for an existing agent. |
Instagram credentials not configured |
Returned in OAuthConnect's errors[] when authmethod: "own" but appid / appsecret are missing. |
POST /UserAgent/CredentialUpsert with instagram.appid and instagram.appsecret. |
Meta could not validate this System User token |
Direct mode received an invalid token, missing permission, or inaccessible asset. | Generate a current token with the documented permissions and asset assignments, save it, and retry. |
| Valid token but no connected Instagram professional account | No assigned Page exposes a linked professional account with CREATE_CONTENT. |
Link the account to the Page, assign both assets to the System User, and reconnect. |
internal_error |
Unexpected server error. | Retry. If persistent, contact support. |
No Instagram account found after connecting
In System User mode, OAuthConnect returns errorcode: "no_accounts" when the account is still Personal, is not linked to an assigned Facebook Page, or the Page lacks CREATE_CONTENT. In advanced Instagram OAuth mode, the usual cause is a Personal account or an app-role / permission problem. Follow the mode-specific prerequisites above.
Publishing fails with "media upload failed"
Common causes:
- Image resolution too low (<320px) or aspect ratio outside Instagram's allowed ranges.
- Media that does not meet Meta's current format, duration, size, or codec requirements.
- Instagram account switched back to Personal after connection: the token becomes invalid. Ask the user to switch back to Business and reconnect.
The agent says no Instagram account is connected
The agent has int-instagram-post, but no Instagram account is connected to it. It asks you to connect one instead of posting, and scheduled posting runs do nothing. Connect an account (in System User mode, select it with SetPickerAccounts as in Step 4) and ask again.
The agent asks you to reconnect for insights
Instagram refused an insights read because the connection lacks the insights permission. In System User mode, generate a new token that also grants instagram_manage_insights, save it with CredentialUpsert, and repeat Steps 3 and 4. With Instagram Login, connect again (Step 8) and allow insights access. Publishing keeps working in the meantime.
Multi-Tenant Architecture
- One Wiro agent instance per customer.
- Recommended direct mode: each customer supplies a System User token from its own Business Portfolio and assigns its own Page plus Instagram assets.
- Advanced OAuth mode: each customer-owned Meta app controls its own App Roles, review status, and Instagram consent branding.
- Page linkage is mode-specific. It is mandatory for System User mode but not for Instagram API with Instagram Login.
- Tokens are isolated per useragent and are never returned to another customer. Access tokens are never returned at all, and a saved System User token reads only as
"••••••••".
Related
- Agent Credentials & OAuth
- Agent Overview
- Agent Skills
- Facebook Page integration: Page linkage is required for System User mode, not Instagram Login OAuth.
- Meta Ads integration: for Instagram-placement paid ads.
- Meta for Developers: Instagram Graph API
- Meta for Developers: Content Publishing API comparison
- Meta for Developers: Instagram media insights
- Meta for Developers: Instagram account insights
LinkedIn Integration
Connect your agent to a LinkedIn Company Page to publish posts and engage with followers.
Overview
The LinkedIn integration uses the LinkedIn Marketing Developer Platform via OAuth 2.0. Agents publish posts on behalf of a Company Page using the connecting member's admin rights.
Skills that use this integration:
int-linkedin-post: Publish text, image, and video posts to a Company Page
Agents that typically enable this integration:
- Social Manager
- Any custom agent that needs LinkedIn Company Page publishing
Availability
| Mode | Status | Notes |
|---|---|---|
"wiro" |
Coming soon | LinkedIn partner app review pending. |
"own" |
Available now | Create your own LinkedIn Developer App. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- A LinkedIn Company Page the connecting user is an admin of. Personal profiles are not supported.
- The numeric LinkedIn organization ID (not the vanity slug). Find it in
linkedin.com/company/<ID>/admin/. - An HTTPS callback URL for your backend.
Complete Integration Walkthrough
Step 1: Create a LinkedIn Developer App
- linkedin.com/developers/apps → Create app.
-
Fill in:
- App name (shown on consent screen).
- LinkedIn Page (associate with a Company Page you own, which gives admins automatic development access).
- Privacy policy URL.
- App logo (128×128 PNG).
- Agree to Legal terms → Create app.
Step 2: Request the required products
Products tab. Request:
- Sign In with LinkedIn using OpenID Connect: for
openidandprofilescopes. - Community Management API: required for Company Page posting (
w_organization_social,r_organization_social).
Community Management API approval is a manual review that can take days. While pending, your app can still post to the Company Page it's associated with for admins listed on that page, which is enough for development and testing.
Step 3: Configure the OAuth redirect URI
- Auth tab.
-
OAuth 2.0 settings → Authorized redirect URLs for your app → add:
https://api.wiro.ai/v1/UserAgentOAuth/LICallback - Save.
Step 4: Note the required OAuth 2.0 scopes
Wiro requests these exact scopes:
openid profile w_organization_social r_organization_social
| Scope | Why |
|---|---|
openid |
OpenID Connect basic identity. |
profile |
Member's display name and headline (shown on consent). |
w_organization_social |
Post, comment, and reply on behalf of the Company Page. |
r_organization_social |
Read Company Page posts and engagement. |
Wiro does not request email, w_member_social, or rw_organization_admin. Keep your app's scope list limited to the four above for consistency with the Wiro flow.
Enable all four in Auth → OAuth 2.0 scopes. Scopes not enabled in this list will fail at the consent screen.
Step 5: Copy your Client ID and Client Secret
Auth → Application credentials → copy Client ID. Copy the Primary Client Secret, which is shown in plain text here. Store it like a password.
Step 6: Save credentials to Wiro
LinkedIn requires clientid, clientsecret, and organizationid all in the same credential block.
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "linkedin", "fieldname": "clientid", "fieldvalue": "YOUR_LINKEDIN_CLIENT_ID" },
{ "credentialkey": "linkedin", "fieldname": "clientsecret", "fieldvalue": "YOUR_LINKEDIN_CLIENT_SECRET" },
{ "credentialkey": "linkedin", "fieldname": "organizationid", "fieldvalue": "12345678" },
{ "credentialkey": "linkedin", "fieldname": "authmethod", "fieldvalue": "own" }
]
}'
organizationid is the numeric ID from your Company Page admin URL. The vanity slug won't work.
Step 7: Initiate OAuth
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "linkedin",
"redirecturl": "https://your-app.com/settings/integrations",
"authmethod": "own"
}'
Response:
{
"result": true,
"authorizeUrl": "https://www.linkedin.com/oauth/v2/authorization?response_type=code&client_id=...&redirect_uri=...&scope=openid%20profile%20w_organization_social%20r_organization_social&state=...",
"flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19",
"errors": []
}
Step 8: Handle the callback
After consent, LinkedIn redirects to Wiro's callback. Wiro exchanges the code for access + refresh tokens, fetches the member's localizedFirstName + localizedLastName from GET /v2/me, and returns the user to your redirecturl.
Success URL:
https://your-app.com/settings/integrations?li_connected=true&li_name=Jane%20Doe
li_name is the connected LinkedIn member's display name (a human), not the Company Page name. The page is identified by organizationid which you set in Step 6.
const params = new URLSearchParams(window.location.search);
if (params.get("li_connected") === "true") {
const name = params.get("li_name");
showSuccess(name ? `Connected as ${name}` : "LinkedIn connected");
} else if (params.get("li_error")) {
handleError(params.get("li_error"));
}
Step 9: Verify
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthStatus" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "linkedin"
}'
Response:
{
"result": true,
"connected": true,
"accounts": [
{ "id": "Jane Doe", "name": "Jane Doe" }
],
"connectedat": "2026-04-17T12:00:00.000Z",
"tokenexpiresat": "2026-06-16T12:00:00.000Z",
"errors": []
}
accounts[0].idandaccounts[0].nameboth carry the connected LinkedIn member's display name (a human), not the Company Page name. The page is identified byorganizationidyou set in Step 6.- Access tokens last ~60 days; LinkedIn typically issues a longer-lived refresh token. Wiro maintains the connection automatically while the agent is running.
Step 10: Start the agent
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
API Reference
POST /UserAgentOAuth/OAuthConnect
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
credentialkey |
string | Yes | "linkedin". |
redirecturl |
string | Yes | Any HTTPS URL you control; the browser returns there after consent. http://localhost and http://127.0.0.1 also work for development. |
authmethod |
string | Yes | "own". Wiro mode is not available yet: leaving authmethod out (it defaults to "wiro") or sending "wiro" returns Sign-in with the platform's app is not enabled for LinkedIn. |
GET /UserAgentOAuth/LICallback
Server-side endpoint invoked by LinkedIn with code and state. You don't call it. You only handle the final redirect back to your redirecturl, which carries li_connected=true&li_name=<name> or li_error=<code>. The callback path is per-provider: LinkedIn's stays LICallback.
POST /UserAgentOAuth/OAuthStatus
Body: { useragentguid, credentialkey: "linkedin" }. Response: connected, accounts: [{id, name}] (1-element with the connected LinkedIn member's name), connectedat, tokenexpiresat.
POST /UserAgentOAuth/OAuthDisconnect
Body: { useragentguid, credentialkey: "linkedin" }. Clears the tokens, the connected name and organizationid (no remote revoke). clientid and clientsecret stay saved. Save organizationid again when you reconnect.
Token lifecycle
Wiro renews the LinkedIn token while the agent is running and when it starts, if LinkedIn issued a refresh token. OAuthStatus reports connected: false as soon as the stored token has expired, which can happen to a stopped agent while its authorization is still valid. Start the agent and check again. Reconnect through the OAuth flow if LinkedIn revoked the authorization or the status stays false while the agent runs.
Using the Skill
Once the LinkedIn Company Page is connected (organization ID persisted), the agent's scheduled tasks use the int-linkedin-post platform skill to publish text, image, and video posts to the Company Page. To adjust the cron of the built-in cs-cron-social-content-scanner task (Social Manager), call POST /UserAgent/CustomSkillUpsert with enabled and interval only. Scheduled task bodies are template-controlled and value is silently ignored for bundled tasks.
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"skillkey": "cs-cron-social-content-scanner",
"enabled": true,
"interval": "0 */4 * * *"
}'
To change what the scheduled task posts (topics, tone, audience angle), edit the paired preference skill content-tone instead (see Agent Skills → Updating Preference Skills).
Troubleshooting
| Error code | Meaning | What to do |
|---|---|---|
missing_params |
The callback was opened without an OAuth state. The browser ends on the API's own neutral page, not on your redirecturl. |
Don't open the callback URL directly. Start again from Step 7. |
session_expired |
>15 min between OAuthConnect and callback. |
Call OAuthConnect again. |
flow_replaced |
A newer sign-in for the same agent and credential replaced this one, whoever started it, so nothing from it was saved. | Use the newer sign-in, or start again with OAuthConnect. |
authorization_denied |
The user cancelled, or LinkedIn returned an error instead of an authorization code. | Verify all four scopes are enabled under Auth → OAuth 2.0 scopes. |
token_exchange_failed |
Wrong Client Secret or redirect URI mismatch. | Re-copy secret; verify URL. |
useragent_not_found |
The agent was deleted, or is no longer owned by the account that started the flow, before LinkedIn returned. | Start again with OAuthConnect for an existing agent. |
LinkedIn credentials not configured |
Returned in OAuthConnect's errors[] when authmethod: "own" but clientid / clientsecret are missing. |
UserAgent/CredentialUpsert with clientid + clientsecret. |
Sign-in with the platform's app is not enabled for LinkedIn |
Returned in OAuthConnect's errors[] when authmethod is missing or "wiro". |
Send authmethod: "own". |
internal_error |
Server error. | Retry; contact support if persistent. |
Posts rejected with 401 Unauthorized
Most likely cause: the Community Management API product hasn't been approved yet. During the pending phase, posting works only for admins of the Company Page the app is associated with (My Pages in LinkedIn Developers). Verify admin membership.
"Scope w_organization_social not authorized"
Enable it under Auth → OAuth 2.0 scopes, then have the user reconnect. LinkedIn doesn't automatically grant scopes you haven't enabled.
Wrong organization ID
Use the numeric ID from linkedin.com/company/<ID>/admin/, not the slug. Update via POST /UserAgent/CredentialUpsert and reconnect if needed.
Multi-Tenant Architecture
- One LinkedIn Developer App per product.
- One Wiro agent instance per customer; capture
organizationidduring onboarding. - Community Management API approval is per app (not per customer), so apply once.
- Tokens are isolated per agent instance.
- Rate limits per app and per organization; see LinkedIn's rate-limits docs.
Related
Twitter / X Integration
Connect your agent to an X (formerly Twitter) account to publish posts, read timelines, and reply to mentions.
Overview
The Twitter / X integration uses X API v2 with OAuth 2.0 Authorization Code Flow + PKCE.
Skills that use this integration:
int-twitterx-post: Publish posts, threads, and replies; read mentions
Agents that typically enable this integration:
- Social Manager
- Any custom agent that needs X posting
Availability
| Mode | Status | Notes |
|---|---|---|
"wiro" |
Available | One-click connect using Wiro's shared X app. |
"own" |
Available | Use your own X Developer app for custom branding. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- (Own mode) An X Developer account (developer.x.com).
- An HTTPS callback URL for your backend.
Wiro Mode (Simplest)
Skip all the own-mode setup. Just call Connect without authmethod:
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "twitter",
"redirecturl": "https://your-app.com/settings/integrations"
}'
User consents on the Wiro-branded consent screen. On return parse x_connected=true&x_username=<handle>. Jump to Step 8: Verify below.
Complete Integration Walkthrough: Own Mode
Step 1: Create an X Developer App
- developer.x.com/portal → sign in.
- Apply for a developer account if needed (free tier works for testing).
- Create a Project → create an App inside it.
- Name your app: this shows on the consent screen.
Step 2: Enable OAuth 2.0 with PKCE
- User authentication settings → Set up.
- Pick OAuth 2.0, type: Web App, Automated App or Bot.
- Enable any extras you need (e.g. email).
-
Callback URI / Redirect URL:
https://api.wiro.ai/v1/UserAgentOAuth/XCallback - Set your Website URL (public product URL).
- Save.
Step 3: Note the required scopes
Wiro requests these exact scopes:
tweet.read tweet.write users.read offline.access
| Scope | Why |
|---|---|
tweet.read |
Read timeline, mentions, replies. |
tweet.write |
Publish posts and replies. |
users.read |
Get connected user's handle and display name. |
offline.access |
Issues a refresh token alongside the access token. |
Step 4: Copy Client ID and Client Secret
After enabling OAuth 2.0, X shows Client ID and Client Secret. Save the secret immediately. You cannot retrieve it later, only regenerate.
Step 5: Save credentials to Wiro
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "twitter", "fieldname": "clientid", "fieldvalue": "YOUR_X_CLIENT_ID" },
{ "credentialkey": "twitter", "fieldname": "clientsecret", "fieldvalue": "YOUR_X_CLIENT_SECRET" },
{ "credentialkey": "twitter", "fieldname": "authmethod", "fieldvalue": "own" }
]
}'
Step 6: Initiate OAuth
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "twitter",
"redirecturl": "https://your-app.com/settings/integrations",
"authmethod": "own"
}'
Response:
{
"result": true,
"authorizeUrl": "https://x.com/i/oauth2/authorize?response_type=code&client_id=...&redirect_uri=...&scope=tweet.read%20tweet.write%20users.read%20offline.access&state=...&code_challenge=...&code_challenge_method=S256",
"flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19",
"errors": []
}
PKCE: X uses PKCE (Proof Key for Code Exchange, S256), and so does TikTok Ads. Wiro creates the code_verifier, keeps it in the OAuth state, and adds the code_challenge to authorizeUrl. You don't need to handle PKCE yourself.
Step 7: Handle the callback
User returns with:
https://your-app.com/settings/integrations?x_connected=true&x_username=jane_doe
const params = new URLSearchParams(window.location.search);
if (params.get("x_connected") === "true") {
const handle = params.get("x_username");
showSuccess(handle ? `Connected @${handle}` : "X account connected");
} else if (params.get("x_error")) {
handleError(params.get("x_error"));
}
x_username is left out when X's profile lookup fails during the callback. The account is still connected, but OAuthStatus then returns an empty accounts array.
Step 8: Verify
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthStatus" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "twitter"
}'
Response:
{
"result": true,
"connected": true,
"accounts": [
{ "id": "jane_doe", "name": "jane_doe" }
],
"connectedat": "2026-04-17T12:00:00.000Z",
"tokenexpiresat": "2026-04-17T14:00:00.000Z",
"errors": []
}
- Access token lifetime: ~2 hours (short!). Wiro auto-refreshes.
- Refresh token: X does not report a lifetime. Wiro uses it to renew the access token while the agent runs; if X stops accepting it,
OAuthStatusreportsconnected: falseand the user reconnects. accounts[0].id=@-less X handle (Twitter has no picker: it is a single-account flow).
Step 9: Start the agent
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
API Reference
POST /UserAgentOAuth/OAuthConnect
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
credentialkey |
string | Yes | "twitter". |
redirecturl |
string | Yes | Any HTTPS URL you control (or http://localhost / http://127.0.0.1 for development). The browser returns there after X. |
authmethod |
string | No | "wiro" (default) or "own". |
GET /UserAgentOAuth/XCallback
Query params: x_connected=true&x_username=<handle> or x_error=<code>. The callback path is per-provider: Twitter's stays XCallback.
POST /UserAgentOAuth/OAuthStatus
Body: { useragentguid, credentialkey: "twitter" }. Response: connected, accounts: [{id, name}] (1-element with the connected handle), connectedat, tokenexpiresat (~2h).
POST /UserAgentOAuth/OAuthDisconnect
Body: { useragentguid, credentialkey: "twitter" }. Calls X's revoke endpoint (POST https://api.x.com/2/oauth2/revoke) with Basic auth, then clears credentials. X is one of the few providers where Wiro actively revokes.
Token lifecycle
Wiro renews the 2-hour access token while the agent is running. OAuthStatus checks that token, so it can report connected: false while the agent is stopped; starting the agent renews it. Reconnect through the OAuth flow when the user revoked the app, or when connected stays false while the agent runs.
Using the Skill
Once the X account is connected, the agent's existing scheduled tasks use the int-twitterx-post platform skill to publish. To adjust the cron of the built-in cs-cron-social-content-scanner task (Social Manager), call POST /UserAgent/CustomSkillUpsert with enabled and interval only. Scheduled task bodies are template-controlled and value is silently ignored for bundled tasks:
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"skillkey": "cs-cron-social-content-scanner",
"enabled": true,
"interval": "0 */4 * * *"
}'
To change what the scheduled task posts (topics, tone, hashtag rules), edit the paired preference skill content-tone instead (see Agent Skills → Updating Preference Skills).
Troubleshooting
| Error code | Meaning | What to do |
|---|---|---|
missing_params |
The callback was opened without an OAuth state. This error ends on the API's own neutral page, not on your app. |
Don't open the callback URL directly. Start a new flow from Step 6. |
authorization_denied |
User cancelled, or OAuth 2.0 not enabled in app settings. | Verify OAuth 2.0 setup (Step 2); retry. |
session_expired |
15-min state cache expired (includes PKCE verifier). | Call OAuthConnect again. |
flow_replaced |
A newer sign-in for the same agent and credential replaced this one, whoever started it, so nothing from it was saved. | Use the newer sign-in, or start again with OAuthConnect. |
token_exchange_failed |
Wrong Client Secret, redirect URI mismatch, or lost PKCE verifier. | Re-copy Client Secret; verify URL; start over. |
useragent_not_found |
The agent was deleted, or is no longer owned by the account that started the flow, before X returned. | Start again with OAuthConnect for an existing agent. |
Twitter / X credentials not configured |
Returned in OAuthConnect's errors[] when authmethod: "own" but clientid / clientsecret are missing. |
UserAgent/CredentialUpsert with clientid + clientsecret. |
internal_error |
Server error. | Retry; contact support. |
Posts fail with 429 Too Many Requests
Free-tier X Developer apps have strict per-app rate limits. For production, move to Basic ($100/mo) or higher. Limits are per app, not per user, so high-volume multi-tenant partners need a higher tier.
Token expires every 2 hours
Access token lifetime is unusually short, so Wiro maintains it automatically while the agent is running. If the user revokes the app in X settings or X invalidates the authorization, the next skill call can fail with a 401 and reconnection is required.
Multi-Tenant Architecture
- One X Developer app per product in own mode. Wiro-mode partners share Wiro's app.
- One Wiro agent instance per customer.
- Your app display name appears on every customer's consent screen (own mode).
- Rate limits are per app. Plan your X Developer tier around aggregate volume.
Related
TikTok Integration
Connect your agent to a TikTok account to publish videos.
Overview
The TikTok integration uses TikTok's OAuth 2.0 with the Content Posting API.
Skills that use this integration:
int-tiktok-post: Publish videos and carousel posts
Agents that typically enable this integration:
- Social Manager
- Any custom agent that needs TikTok publishing
Availability
| Mode | Status | Notes |
|---|---|---|
"own" |
Available | Use your own TikTok for Developers app. |
"wiro" |
Coming soon | Wiro's shared TikTok app is awaiting TikTok's review. Until then, OAuthConnect in Wiro mode, which is also what you get when you leave out authmethod, returns Sign-in with the platform's app is not enabled for TikTok. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- A TikTok for Developers account (developers.tiktok.com).
- An HTTPS callback URL.
Complete Integration Walkthrough: Own Mode
Step 1: Create a TikTok for Developers App
- developers.tiktok.com/apps → sign in.
- Create app.
- App name, category, description, icon.
Step 2: Add Login Kit + Content Posting API
- Add products.
- Add Login Kit and Content Posting API.
Step 3: Configure redirect URI
- Login Kit → Platforms → Web.
-
Add callback URL:
https://api.wiro.ai/v1/UserAgentOAuth/TikTokCallback - Save.
Step 4: Note the required scopes
Wiro requests these exact scopes:
user.info.basic,video.publish
| Scope | Why |
|---|---|
user.info.basic |
User handle, avatar, display name. |
video.publish |
Publish video content to the authorized account. |
Other scopes like video.upload, video.list are not used by Wiro.
Step 5: Copy Client Key and Client Secret
App details → copy Client Key and Client Secret. Note: TikTok calls the first one "key" (not "ID"), and the field name in Wiro is clientkey.
Step 6: Save credentials
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "tiktok", "fieldname": "clientkey", "fieldvalue": "YOUR_TIKTOK_CLIENT_KEY" },
{ "credentialkey": "tiktok", "fieldname": "clientsecret", "fieldvalue": "YOUR_TIKTOK_CLIENT_SECRET" },
{ "credentialkey": "tiktok", "fieldname": "authmethod", "fieldvalue": "own" }
]
}'
Step 7: Initiate OAuth
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "tiktok",
"redirecturl": "https://your-app.com/settings/integrations",
"authmethod": "own"
}'
Response:
{
"result": true,
"authorizeUrl": "https://www.tiktok.com/v2/auth/authorize/?client_key=...&scope=user.info.basic,video.publish&response_type=code&redirect_uri=...&state=...",
"flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19",
"errors": []
}
Step 8: Handle the callback
Success: ?tiktok_connected=true&tiktok_username=<display_name>.
Error: ?tiktok_error=<code>.
tiktok_username in the callback is populated from TikTok's display_name field (the creator's public display name), not the handle. The handle/username as it appears in URLs is not exposed by TikTok's OAuth user info endpoint. It is left out when TikTok's profile lookup fails during the callback; the account is still connected, but OAuthStatus then returns an empty accounts array.
Step 9: Verify
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthStatus" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "tiktok"
}'
Response:
{
"result": true,
"connected": true,
"accounts": [
{ "id": "Creator Display Name", "name": "Creator Display Name" }
],
"connectedat": "2026-04-17T12:00:00.000Z",
"tokenexpiresat": "2026-04-18T12:00:00.000Z",
"errors": []
}
- Access token: ~1 day (86400s).
- Refresh token: ~1 year (31536000s).
accounts[0].idandaccounts[0].name= TikTok display name (the creator's public display name as set in their profile), NOT the@handle. The handle/URL username is not exposed by TikTok's OAuthuser/info/endpoint, so Wiro storesdisplay_nameand returns it as both the account identifier and its name.
Step 10: Start the agent
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
API Reference
POST /UserAgentOAuth/OAuthConnect
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
credentialkey |
string | Yes | "tiktok". |
redirecturl |
string | Yes | Any HTTPS URL you control (or http://localhost / http://127.0.0.1 for development). The browser returns there after TikTok. |
authmethod |
string | No | "own". Omitted, it means "wiro", which is not available yet. |
GET /UserAgentOAuth/TikTokCallback
Query params: tiktok_connected=true&tiktok_username=<display_name> or tiktok_error=<code>. tiktok_username is TikTok's display name (from the OAuth user/info/ endpoint's display_name field), not the @handle. The callback path is per-provider: TikTok's stays TikTokCallback.
POST /UserAgentOAuth/OAuthStatus
Body: { useragentguid, credentialkey: "tiktok" }. Response: connected, accounts: [{id, name}] (1-element with the connected display name), connectedat, tokenexpiresat (~1 day).
POST /UserAgentOAuth/OAuthDisconnect
Body: { useragentguid, credentialkey: "tiktok" }. Calls TikTok's revoke endpoint (POST https://open.tiktokapis.com/v2/oauth/revoke/), then clears credentials. TikTok is one of the few providers where Wiro actively revokes.
Token lifecycle
Wiro renews the 24-hour access token while the agent is running. OAuthStatus checks that token, so it can report connected: false while the agent is stopped; starting the agent renews it. Reconnect through the OAuth flow when TikTok revoked the authorization, or when connected stays false while the agent runs.
Troubleshooting
| Error code | Meaning | What to do |
|---|---|---|
missing_params |
The callback was opened without an OAuth state. This error ends on the API's own neutral page, not on your app. |
Don't open the callback URL directly. Start a new OAuth flow. |
authorization_denied |
User cancelled, or scopes not enabled. | Verify scope configuration. |
session_expired |
15-min state cache expired. | Restart OAuth. |
flow_replaced |
A newer sign-in for the same agent and credential replaced this one, whoever started it, so nothing from it was saved. | Use the newer sign-in, or start again with OAuthConnect. |
token_exchange_failed |
Wrong Client Secret or redirect URI mismatch. | Re-copy; verify URL. |
Sign-in with the platform's app is not enabled for TikTok |
Returned in OAuthConnect's errors[]: Wiro mode isn't available yet, and it is the default when authmethod is left out. |
Save your app credentials (Step 6) and call OAuthConnect with "authmethod": "own". |
useragent_not_found |
The agent was deleted, or is no longer owned by the account that started the flow, before TikTok returned. | Start again with OAuthConnect for an existing agent. |
TikTok credentials not configured |
Returned in OAuthConnect's errors[] when authmethod: "own" but clientkey / clientsecret are missing. |
UserAgent/CredentialUpsert with clientkey + clientsecret. |
internal_error |
Server error. | Retry. |
"unaudited_client" or limited publishing
Until your TikTok app is audited, publishing may be limited to private posts or a small set of listed test users. Submit for audit in the TikTok Developer portal for production volume.
Multi-Tenant Architecture
- One TikTok app per product in own mode.
- One Wiro agent instance per customer.
- TikTok per-app limits apply: plan around aggregate volume.
Related
- Agent Credentials & OAuth
- Agent Overview
- Agent Skills
- TikTok Ads integration: separate product for paid advertising; this page covers organic posting only.
- TikTok for Developers
Google Ads Integration
Connect your agent to Google Ads for campaign management, keyword research, and ad copy.
Overview
The Google Ads integration uses Google OAuth 2.0 with the Google Ads API v23 REST endpoints.
Skills that use this integration:
int-googleads-manage: Campaign / ad group / keyword management, insightsutil-ads-manager-common: Shared ads helpers
Agents that typically enable this integration:
- Google Ads Manager
- Any custom agent that needs paid-search capabilities
Availability
| Mode | Status | Notes |
|---|---|---|
"own" |
Available | Your own Google Cloud project, OAuth client and Developer Token. |
"wiro" |
Coming soon | Wiro's shared Google Cloud project is awaiting Google's review. Until then, OAuthConnect in Wiro mode, which is also what you get when you leave out authmethod, returns Sign-in with the platform's app is not enabled for Google Ads. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- A Google Ads account (or MCC) the connecting user administers.
- A Google Cloud project with the Google Ads API enabled.
- A Google Ads Developer Token, requested from your MCC.
- A return URL: any HTTPS page you control (or
http://localhost/http://127.0.0.1for development) to pass asredirecturl.
Complete Integration Walkthrough: Own Mode
Step 1: Create a Google Cloud Project
- console.cloud.google.com → create a project.
- APIs & Services → Library → enable Google Ads API.
-
OAuth consent screen:
- External user type for multi-tenant.
- App name, support email, dev contact.
- Add scope:
https://www.googleapis.com/auth/adwords. - Publish the app (In production) before your customers connect. While it is in Testing, only the test users you add can connect, and Google expires their refresh tokens after 7 days, so the agent loses access every week.
- Google Ads API: for Google Ads
- YouTube Data API v3 + YouTube Analytics API v2: for YouTube (used by the
int-youtube-manageskill, also consumed byint-googleads-managefor Video / Demand Gen campaigns) - Google Analytics Data API + Google Analytics Admin API: for Google Analytics 4
- Merchant API: for Merchant Center
OAuthConnect, consent and picker. Add the callback of every integration you use as an Authorized redirect URI on the client, or Google stops with redirect_uri_mismatch: https://api.wiro.ai/v1/UserAgentOAuth/GAdsCallback, https://api.wiro.ai/v1/UserAgentOAuth/YTCallback, https://api.wiro.ai/v1/UserAgentOAuth/GA4Callback, https://api.wiro.ai/v1/UserAgentOAuth/MCCallback. Then save the Client ID and Client Secret under each credential key you use (google-ads, youtube, ga4, google-merchant-center).
curl -X POST \
"https://merchantapi.googleapis.com/accounts/v1/accounts/{YOUR_MC_ID}/developerRegistration:registerGcp" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{}'
This call is made once per GCP project. After it returns a DeveloperRegistration resource, the same GCP can call the Merchant API against any merchant account whose admin grants OAuth consent, with no per-account registration needed (see Google's 3P/agency guidance). Each GCP can be registered with at most one primary Merchant Center at a time; registering against a second account returns ALREADY_REGISTERED.
Step 2: Create OAuth 2.0 Client ID
- APIs & Services → Credentials → Create credentials → OAuth client ID.
- Application type: Web application.
-
Authorized redirect URIs:
https://api.wiro.ai/v1/UserAgentOAuth/GAdsCallback - Save; copy Client ID and Client Secret.
Step 3: Get a Developer Token
- Sign in to your Google Ads MCC.
- Admin → API Center → request a token.
- Start with a test token; apply for basic access for production.
Step 4: Save credentials to Wiro
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "google-ads", "fieldname": "clientid", "fieldvalue": "YOUR_GOOGLE_OAUTH_CLIENT_ID" },
{ "credentialkey": "google-ads", "fieldname": "clientsecret", "fieldvalue": "YOUR_GOOGLE_OAUTH_CLIENT_SECRET" },
{ "credentialkey": "google-ads", "fieldname": "developertoken", "fieldvalue": "YOUR_GOOGLE_ADS_DEVELOPER_TOKEN" },
{ "credentialkey": "google-ads", "fieldname": "authmethod", "fieldvalue": "own" }
]
}'
Don't send managercustomerid. CredentialUpsert refuses it with Manager Customer ID (MCC) is managed by the connection flow, and one refused field fails the whole request, so nothing is saved.
Step 5: Initiate OAuth
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "google-ads",
"redirecturl": "https://your-app.com/settings/integrations",
"authmethod": "own"
}'
Response:
{
"result": true,
"authorizeUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&response_type=code&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fadwords&state=...&access_type=offline&prompt=select_account+consent",
"flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19",
"errors": []
}
Scope is a single string: https://www.googleapis.com/auth/adwords. access_type=offline with prompt=select_account consent makes Google ask which Google account to connect and issue a refresh token every time.
Step 6: Handle the callback
After the token exchange, Wiro lists the customers the Google user can open directly (customers:listAccessibleCustomers) and looks up each one's descriptive name and status. A client account that the user reaches only through a manager (MCC) account is not listed.
Success URL:
https://your-app.com/settings/integrations?gads_connected=true&gads_accounts=%5B%7B%22id%22%3A%221234567890%22%2C%22name%22%3A%22My%20Client%22%2C%22status%22%3A%22ENABLED%22%7D%5D
gads_accountsis always there on success, with at least one entry. When Google lists no customer for this user, for example because the developer token is missing or refused, Wiro saves nothing and returnsgads_error=no_accountsinstead.- Each entry is
{ id, name, status }:idis the 10-digit customer ID,namethe descriptive name, andstatusthe Google Ads customer status (for example"ENABLED","CANCELED","SUSPENDED").nameandstatusare empty strings when the lookup for that customer failed.
const params = new URLSearchParams(window.location.search);
if (params.get("gads_connected") === "true") {
const accounts = JSON.parse(params.get("gads_accounts") || "[]");
if (accounts.length === 1) {
await setCustomerId(accounts[0]);
} else if (accounts.length > 1) {
presentCustomerPicker(accounts);
}
}
Step 7: Persist the customer ID selection
This call is required, even when gads_accounts has one entry. Until it runs, OAuthStatus reports connected: false.
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/SetPickerAccounts" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "google-ads",
"accounts": [
{ "customerid": "1234567890", "customerdescriptivename": "Acme Corp Production" }
]
}'
customerid: either 10-digit or123-456-7890format works, and non-digits are stripped automatically.customerdescriptivename(optional): Wiro saves the name its list gives the customer, so you can leave it out. Takecustomeridfrom thegads_accountsentry'sid.- Pass multiple
{ customerid, customerdescriptivename }entries to authorize the agent against several customers at once. - Wiro saves only customers from this sign-in's list, under the names it lists, when the call comes from the same Wiro account within 15 minutes. The first save uses the list up: to change the selection later, connect again. See SetPickerAccounts.
Response:
{
"result": true,
"accounts": [
{ "id": "1234567890", "name": "Acme Corp Production" }
],
"restart": "scheduled",
"errors": []
}
The save that completes the connection restarts a running agent once (restart: "scheduled"), and a save that changes nothing restarts nothing.
Step 8: Verify and Start
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthStatus" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "google-ads"
}'
Response:
{
"result": true,
"connected": true,
"accounts": [
{ "id": "1234567890", "name": "Acme Corp Production" }
],
"connectedat": "2026-04-17T12:00:00.000Z",
"tokenexpiresat": "2026-04-17T13:00:00.000Z",
"errors": []
}
accounts[]carries one entry per selected customer (id=customerid,name=customerdescriptivename).- Access token lifetime: 1 hour (short). Wiro maintains it automatically while the agent is running.
- Google's refresh tokens stay valid until they are revoked, except while the consent screen is in Testing: then Google expires them after 7 days.
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
API Reference
POST /UserAgentOAuth/OAuthConnect
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
credentialkey |
string | Yes | "google-ads". |
redirecturl |
string | Yes | Any HTTPS URL you control (or http://localhost / http://127.0.0.1 for development). |
authmethod |
string | No | "own". Omitted, it means "wiro", which is not available yet. |
GET /UserAgentOAuth/GAdsCallback
Server-side endpoint invoked by Google. You don't call it: you register it as the Authorized redirect URI of your OAuth client. Wiro then sends the browser to your redirecturl with gads_connected=true&gads_accounts=<JSON> or gads_error=<code>. The callback path is per-provider: Google Ads's stays GAdsCallback.
POST /UserAgentOAuth/SetPickerAccounts
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
credentialkey |
string | Yes | "google-ads". |
accounts |
array | Yes | One or more { customerid, customerdescriptivename } entries. customerid is 10 digits (dashes/letters stripped server-side); Wiro saves the entry's name from its list as customerdescriptivename. |
Response: { result, accounts: [{id, name}, ...], restart, errors }. The save that completes the connection restarts a running agent once (restart: "scheduled"), and a save that changes nothing restarts nothing.
POST /UserAgentOAuth/OAuthStatus
Body: { useragentguid, credentialkey: "google-ads" }. Response: connected, accounts: [{id, name}, ...] (one entry per selected customer: id = customerid, name = customerdescriptivename), connectedat, tokenexpiresat (~1h).
POST /UserAgentOAuth/OAuthDisconnect
Body: { useragentguid, credentialkey: "google-ads" }. Clears the tokens and the selected customers in Wiro. Your Client ID, Client Secret and developer token are kept, so you can connect again without saving them again. Wiro does not ask Google to revoke the authorization.
Token lifecycle
Wiro renews the Google Ads access token while the agent is running. When the agent is stopped, the token runs out after about an hour and OAuthStatus reports connected: false until the agent starts and renews it. Reconnect through OAuth when Google revokes the authorization, or when connected stays false while the agent runs.
Using the Skill
Once Google Ads is connected and customerid is persisted, the agent's scheduled tasks use the int-googleads-manage platform skill to pull metrics and manage campaigns. Adjust the cron of the built-in cs-cron-googleads-performance-reporter task (Google Ads Manager) with enabled and interval only. The task body (value) is owned by the bundled integration skill and silently dropped on writes:
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"skillkey": "cs-cron-googleads-performance-reporter",
"enabled": true,
"interval": "0 9 * * *"
}'
To change what the reporter includes (wasted-spend threshold, target ROAS, reporting preferences), edit the paired preference skill ad-strategy instead (see Agent Skills → Updating Preference Skills).
Troubleshooting
| Error code | Meaning | What to do |
|---|---|---|
missing_params |
The callback was opened without a state, so the browser ends on the API's own neutral page instead of your app. |
Start a new flow from Step 5. |
authorization_denied |
User cancelled, or consent screen in Testing and the user isn't a test user. | Add test user or publish consent screen. |
session_expired |
State cache expired. | Restart. |
flow_replaced |
A newer sign-in for the same agent and credential replaced this one, whoever started it, so nothing from it was saved. | Use the newer sign-in, or start again with OAuthConnect. |
token_exchange_failed |
Google did not return an access token for the authorization code, usually because the saved Client Secret is wrong. | Re-copy the Client Secret (Step 4) and connect again. |
no_accounts |
Sign-in worked, but Google listed no Google Ads customer for this user, and nothing was saved. A missing or refused developer token, or a Google Ads API that isn't enabled in your project, ends here too. | Check the developertoken from Step 4 and its access level, and that the Google Ads API is enabled, then connect again with a Google user who can open the account. |
account_list_too_large |
Google listed more than 2,000 customers for this user, and nothing was saved. | Connect with a Google user who can open fewer customers directly. |
Sign-in with the platform's app is not enabled for Google Ads |
Returned in OAuthConnect's errors[]: Wiro mode isn't available yet, and it is the default when authmethod is left out. |
Save your credentials (Step 4) and call OAuthConnect with "authmethod": "own". |
useragent_not_found |
The agent was deleted, or is no longer owned by the account that started the flow, before Google returned. | Start again with OAuthConnect for an existing agent. |
Google Ads credentials not configured |
Returned in OAuthConnect's errors[] when authmethod: "own" but clientid / clientsecret are missing. |
UserAgent/CredentialUpsert with clientid + clientsecret (Step 4). |
internal_error |
Server error. | Retry; contact support. |
redirect_uri_mismatch on Google's page
The Authorized redirect URIs of your OAuth client don't include https://api.wiro.ai/v1/UserAgentOAuth/GAdsCallback exactly as written. Google stops on its own error page, so nothing comes back to your redirecturl. Add the URI (Step 2) and connect again.
USER_PERMISSION_DENIED on API calls
The OAuth-authorized user lacks access to the customerid you chose. Pick a different customer from gads_accounts or have the user request access.
Developer Token rejected
Test tokens can only query accounts in your own MCC hierarchy. For customer accounts outside your MCC, you need Basic Access. Apply in Admin → API Center.
Multi-Tenant Architecture
- One Google Cloud project per product. Publish the OAuth consent screen.
- Apply for Basic or Standard Developer Token access based on expected volume.
- One Wiro agent instance per customer;
customeridis per-instance. - Tokens auto-refresh via the stored refresh token.
Related
YouTube Integration
Connect your agent to a YouTube channel to upload and publish videos and Shorts, edit their details and playlists, list the channel's videos, report performance, and pick video assets for Google Ads Video/Demand Gen campaigns.
Overview
The YouTube integration uses Google OAuth 2.0 with:
- YouTube Data API v3: channel info, video listings, uploads, video details, playlists, and thumbnails
- YouTube Analytics API v2: view counts, watch time, subscriber metrics
Skills that use this integration:
int-youtube-manage: Uploads and publishes videos and Shorts (title, description, tags, visibility or a scheduled release, playlist, thumbnail), lists channel videos, edits video details and playlists, reports performance, and picks video assets for Google Ads Video/Demand Gen campaigns
Agents that typically enable this integration:
- Video Creator: to publish the videos it makes to your channel. Add
int-youtube-managewithSkillsApply; like every skill, it is included in every plan. Video Creator then publishes a finished video when the request asks for it or aYouTubeline in itsvideo-preferencessays to, and otherwise offers to. - Google Ads Manager: for creating Video and Demand Gen campaigns that reference existing YouTube videos
Availability
| Mode | Status | Notes |
|---|---|---|
"own" | Available | Your own Google Cloud project and OAuth client. |
"wiro" | Coming soon | Wiro's shared Google Cloud project is awaiting Google's review. Until then, OAuthConnect in Wiro mode, which is also what you get when you leave out authmethod, returns Sign-in with the platform's app is not enabled for YouTube. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- A YouTube channel the connecting Google account owns or manages.
- A Google Cloud project with YouTube Data API v3 and YouTube Analytics API enabled.
- An HTTPS callback URL.
Connect
Step 1: Create a Google Cloud project and enable the YouTube APIs
- console.cloud.google.com → create a project.
- APIs & Services → Library → enable:
- OAuth consent screen:
- External user type for multi-tenant use
- App name, support email
- Add scopes:
youtube,youtube.readonly,yt-analytics.readonly - Publish the app (In production). While it is in Testing, Google expires its refresh tokens after 7 days and the agent loses the channel.
Step 2: Create the OAuth client
APIs & Services → Credentials → Create Credentials → OAuth client ID:
- Application type: Web application
- Authorized redirect URIs:
https://api.wiro.ai/v1/UserAgentOAuth/YTCallback
Copy the client ID and the client secret. If you missed the secret, open the client and use Reset secret.
Step 3: Save the OAuth client to Wiro
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "youtube", "fieldname": "clientid", "fieldvalue": "123-abc.apps.googleusercontent.com" },
{ "credentialkey": "youtube", "fieldname": "clientsecret", "fieldvalue": "YOUR_CLIENT_SECRET" },
{ "credentialkey": "youtube", "fieldname": "authmethod", "fieldvalue": "own" }
]
}'
Step 4: Start the connection
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "youtube",
"redirecturl": "https://your-app.com/settings/integrations",
"authmethod": "own"
}'
Send the user to the returned authorizeUrl. Google asks which Google account to connect, even when the browser is already signed in to one.
Step 5: Save the channel selection
After consent the user returns with ?yt_connected=true&yt_channels=<URL-encoded-JSON>. Each entry is { id, title, customUrl, subscriberCount }: id is the channel ID, title the channel name, customUrl its custom URL or handle (empty when it has none), and subscriberCount a string ("0" when YouTube returns no count). When the Google account has a single channel, Wiro selects it for you. Otherwise map the user's choice to { channelid, channeltitle } (id becomes channelid, title becomes channeltitle) and call SetPickerAccounts:
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/SetPickerAccounts" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "youtube",
"accounts": [
{ "channelid": "UC...", "channeltitle": "My Channel" }
]
}'
Pass multiple { channelid, channeltitle } entries to authorize the agent against several channels at once. Wiro saves only channels from this sign-in's list, under the names it lists, when the call comes from the same Wiro account within 15 minutes. The first save uses the list up: to change the selection later, connect again. See SetPickerAccounts.
Disconnect
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthDisconnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "youtube"
}'
Status
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthStatus" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "youtube"
}'
Response:
{
"result": true,
"connected": true,
"accounts": [
{ "id": "UC...", "name": "My Channel" }
],
"connectedat": "2026-04-17T12:00:00.000Z",
"tokenexpiresat": "2026-04-17T13:00:00.000Z",
"errors": []
}
accounts[] carries one entry per selected channel (id = channelid, name = channeltitle).
API Reference
POST /UserAgentOAuth/OAuthConnect
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid | string | Yes | Agent instance GUID. |
credentialkey | string | Yes | "youtube". |
redirecturl | string | Yes | Any HTTPS URL you control (or http://localhost / http://127.0.0.1 for development). |
authmethod | string | No | "own". Omitted, it means "wiro", which is not available yet. |
GET /UserAgentOAuth/YTCallback
Server-side endpoint invoked by Google. You don't call it: you register it as the Authorized redirect URI of your OAuth client. Wiro then sends the browser to your redirecturl with yt_connected=true&yt_channels=<JSON> (a URL-encoded array of { id, title, customUrl, subscriberCount }) or yt_error=<code>. The callback path is per-provider: YouTube's stays YTCallback. When you pass a channel to SetPickerAccounts, map it to { channelid: id, channeltitle: title }.
POST /UserAgentOAuth/SetPickerAccounts
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid | string | Yes | Agent instance GUID. |
credentialkey | string | Yes | "youtube". |
accounts | array | Yes | One or more { channelid, channeltitle } entries. |
Response: { result, accounts: [{id, name}, ...], restart, errors }. The save that completes the connection restarts a running agent once (restart: "scheduled"), and a save that changes nothing restarts nothing.
POST /UserAgentOAuth/OAuthStatus
Body: { useragentguid, credentialkey: "youtube" }. Response: connected, accounts: [{id, name}, ...] (one entry per selected channel: id = channelid, name = channeltitle), connectedat, tokenexpiresat.
POST /UserAgentOAuth/OAuthDisconnect
Body: { useragentguid, credentialkey: "youtube" }. Clears the tokens and the selected channels in Wiro. Your Client ID and Client Secret are kept. Wiro does not ask Google to revoke the authorization.
What the agent does with this integration
Uploading and publishing videos
Ask the agent to put a video on YouTube, for example one it made with Video Creator. It uploads the video to the selected channel and replies with the link.
- Regular videos and Shorts. One upload covers both: YouTube files a vertical (9:16) or square video of up to 3 minutes as a Short and anything else as a regular video. A Short needs no
#Shortstag. - Details. Title (up to 100 characters), description (up to 5,000), tags, category, language, the made-for-kids setting, and visibility: public, unlisted, private, or a scheduled release time. A video that shows realistic AI-generated people or scenes is marked as altered or synthetic content, and YouTube labels it.
- Playlist and thumbnail. The agent can add the video to a playlist and set a frame of it as the thumbnail. YouTube accepts custom thumbnails for regular videos on verified channels.
- Approval. Uploads go through the agent's approval policy (the
approval-policycustom skill). A request that already says to upload or publish is the approval; otherwise the agent shows the title, description, tags, playlist and visibility first and uploads after you approve. - Drafts. Ask for a private or unlisted upload, and ask the agent to publish it later: it makes the video public, or schedules it, and keeps the synthetic-content label.
- No duplicates. When an upload fails, the agent looks for the video among the channel's uploads before it tries once more.
The reply gives the video's link, its visibility or scheduled time, and its playlist.
Videos from an unaudited Google Cloud project stay private. YouTube restricts videos uploaded through a Google Cloud project created after 28 July 2020 that has not passed the YouTube API audit to private viewing, whatever visibility was asked for. The agent reads the video back after the upload; if YouTube has locked it, the agent tells you once and does not upload it again. Request the audit for the project behind your OAuth client with YouTube's API audit form. Until it passes, download the video from the chat and upload it in YouTube Studio.
Channel video listing
Agent lists channel uploads:
Operator → "show my last 20 YouTube videos"
Agent → GET /youtube/v3/playlistItems?playlistId=UU{channel}
returns 20 items with video IDs, titles, dates, durations
Video asset for Google Ads campaigns
Google Ads Manager agent uses this skill to pick video assets for Video and Demand Gen campaigns:
Agent → /youtube-manage list last 30 days of videos
→ picks top 3 by views
→ /googleads-manage create Video campaign with these as creatives
Performance analytics
Agent queries video-level metrics:
Operator → "which videos performed best last month?"
Agent → POST /youtubeAnalytics/v2/reports
with dimensions=[video], metrics=[views, averageViewDuration, estimatedMinutesWatched]
Skill reference
- agent-skills.md: custom skill schema and the
int-youtube-managekey
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
Sign-in with the platform's app is not enabled for YouTube in OAuthConnect's errors[] | Wiro mode isn't available yet, and it is the default when authmethod is left out | Save your OAuth client (Step 3) and call OAuthConnect with "authmethod": "own" |
YouTube credentials not configured | authmethod: "own" without a saved clientid and clientsecret | Save them (Step 3), then retry |
yt_error=no_accounts on your redirecturl | Google listed no YouTube channel for this account, and Wiro saved nothing: the account has no channel, or the YouTube Data API v3 is not enabled in your project | Enable the API (Step 1), or have the user create a channel, then call OAuthConnect again |
quotaExceeded | Daily quota hit | Wait 24h or request higher quota from Google |
channelNotFound | Channel deleted or moved | Connect again with OAuthConnect, then save the channel with SetPickerAccounts |
invalid_grant | Refresh token expired or revoked; a consent screen still in Testing expires it after 7 days | Publish the consent screen, then re-connect via OAuthConnect |
| A video uploaded as public or unlisted stays private | The Google Cloud project hasn't passed the YouTube API audit | Request the audit; until then upload the video in YouTube Studio |
redirect_uri_mismatch on Google's page
The Authorized redirect URIs of your OAuth client don't include https://api.wiro.ai/v1/UserAgentOAuth/YTCallback exactly as written. Google stops on its own error page, so nothing comes back to your redirecturl. Add the URI (Step 2) and connect again.
Google Analytics 4 Integration
Connect your agent to Google Analytics 4 (GA4) for conversion reporting, audience listing, and attribution cross-checks against your advertising platforms.
Overview
The GA4 integration uses Google OAuth 2.0 with the GA4 Data API v1beta and the GA4 Admin API v1beta/v1alpha.
Skills that use this integration:
int-ga4-analytics: Direct GA4 reporting + Google Ads / Meta Ads attribution cross-check
Agents that typically enable this integration:
- Google Ads Manager
- Meta Ads Manager
- TikTok Ads Manager
- Any agent that needs to audit ad-reported conversions against GA4
Availability
| Mode | Status | Notes |
|---|---|---|
"own" | Available | Your own Google Cloud project and OAuth client. |
"wiro" | Coming soon | Wiro's shared Google Cloud project is awaiting Google's review. Until then, OAuthConnect in Wiro mode, which is also what you get when you leave out authmethod, returns Sign-in with the platform's app is not enabled for Google Analytics 4. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- A GA4 Property the connecting user administers.
- A Google Cloud project with GA4 Data API and GA4 Admin API enabled.
- An HTTPS callback URL.
Own Mode
Step 1: Create a Google Cloud Project
- console.cloud.google.com → create a project.
- APIs & Services → Library → enable:
- OAuth consent screen:
- External user type for multi-tenant use
- App name, support email, developer contact
- Add scopes:
analytics.readonly,analytics.edit - Publish the app (In production). While it is in Testing, Google expires its refresh tokens after 7 days and the agent loses access.
Step 2: Create OAuth Client
APIs & Services → Credentials → Create Credentials → OAuth client ID:
- Application type: Web application
- Authorized redirect URIs:
https://api.wiro.ai/v1/UserAgentOAuth/GA4Callback
Copy the Client ID and Client Secret to your agent credentials.
Step 3: Connect
Save the Client ID and Client Secret with POST /UserAgent/CredentialUpsert:
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "ga4", "fieldname": "clientid", "fieldvalue": "123-abc.apps.googleusercontent.com" },
{ "credentialkey": "ga4", "fieldname": "clientsecret", "fieldvalue": "YOUR_CLIENT_SECRET" },
{ "credentialkey": "ga4", "fieldname": "authmethod", "fieldvalue": "own" }
]
}'
Then start OAuthConnect in own mode:
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "ga4",
"redirecturl": "https://your-app.com/settings/integrations",
"authmethod": "own"
}'
The response returns { result: true, authorizeUrl: "...", flowid: "..." }. Redirect the user to authorizeUrl. Google asks which Google account to connect, even when the browser is already signed in to one.
Step 4: Property Picker
After consent, the user returns with ?ga4_connected=true&ga4_properties=<URL-encoded-JSON>. Each entry is { id, displayName, account, propertyType }: id is the property number, displayName the property name, account the name of the GA4 account that owns it, and propertyType Google's property type (for example PROPERTY_TYPE_ORDINARY). Map the user's choice to the picker shape and call SetPickerAccounts:
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/SetPickerAccounts" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "ga4",
"accounts": [
{ "propertyid": "123456789", "propertydisplayname": "MyApp Production" }
]
}'
Pass several { propertyid, propertydisplayname } entries to authorize the agent against several GA4 properties at once (id becomes propertyid). Wiro saves each property's displayName from its list as propertydisplayname, so a name you send is not read. account is handy for grouping the list in your UI, but it is not stored. Wiro saves only properties from this sign-in's list, under the names it lists, when the call comes from the same Wiro account within 15 minutes. The first save uses the list up: to change the selection later, connect again. See SetPickerAccounts.
Disconnect
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthDisconnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "ga4"
}'
Clears the tokens and the selected properties in Wiro. Your Client ID and Client Secret are kept, so you can connect again without saving them again. Wiro does not ask Google to revoke the authorization.
Status
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthStatus" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "ga4"
}'
Response:
{
"result": true,
"connected": true,
"accounts": [
{ "id": "123456789", "name": "MyApp Production" }
],
"connectedat": "2026-04-17T12:00:00.000Z",
"tokenexpiresat": "2026-04-17T13:00:00.000Z",
"errors": []
}
accounts[] carries one entry per selected property (id = propertyid, name = propertydisplayname).
What the agent does with this integration
Direct reporting
Agent runs GA4 reports on operator request:
Operator → "show paid search performance last 14 days"
Agent → POST /v1beta/properties/123456789:runReport
with dimensions=[sessionDefaultChannelGroup]
and metrics=[sessions, purchases, totalRevenue]
Attribution cross-check
Agent cross-checks ad platform conversions against GA4 paid traffic for the same period, flags >20% deltas.
Audience listing
Agent reads GA4 predefined + custom audiences via Admin API and can propose Customer Match sync candidates.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
Sign-in with the platform's app is not enabled for Google Analytics 4 in OAuthConnect's errors[] | Wiro mode isn't available yet, and it is the default when authmethod is left out | Save your OAuth client (Step 3) and call OAuthConnect with "authmethod": "own" |
Google Analytics 4 credentials not configured in OAuthConnect's errors[] | authmethod: "own" without a saved clientid and clientsecret | Save them (Step 3), then retry |
invalid_grant | Refresh token expired or revoked; a consent screen still in Testing expires it after 7 days | Publish the consent screen, then re-connect via OAuthConnect |
PERMISSION_DENIED | User not a property administrator | Ask user to add the GA account |
403 Request had insufficient authentication | Missing scopes | Re-consent with full scope set |
ga4_error=no_accounts on your redirecturl | Google listed no GA4 property for this user, and Wiro saved nothing: the user has no property, or the Google Analytics Admin API is not enabled in your project | Enable the Admin API (Step 1), or have the user create a property or get access to one, then call OAuthConnect again |
OAuthStatus returns connected: false right after consent | No GA4 property has been saved yet; the connection is complete only once SetPickerAccounts stores at least one | Call SetPickerAccounts with a property from ga4_properties (Step 4) |
redirect_uri_mismatch on Google's page
The Authorized redirect URIs of your OAuth client don't include https://api.wiro.ai/v1/UserAgentOAuth/GA4Callback exactly as written. Google stops on its own error page, so nothing comes back to your redirecturl. Add the URI (Step 2) and connect again.
Skill reference
- agent-skills.md: custom skill schema and the
int-ga4-analyticskey
Roasit Integration
Connect your agent to Roasit mobile attribution: creative, campaign and network ROAS, cohort revenue and retention, iOS SKAdNetwork reports and install reconciliation, read with one read-only API token.
Overview
Roasit is a mobile measurement partner (MMP): it attributes app installs to ad networks, pulls ad spend from Meta, Google Ads, TikTok and AppLovin, and joins in-app and ad revenue into install cohorts. This integration lets an agent read those numbers (the same figures the Roasit dashboard's Reports screen shows) and act on them through the ad-platform skills.
Skills that use this integration:
int-roasit-attribution: Read-only reports from the Roasit API, covering creative / campaign / network ROAS (roas_all, ad-only and in-app-only ROAS, day-N ROAS), installs, spend, CPI, cohort revenue, retention, iOS SKAdNetwork reports, install reconciliation against the stores, and data freshness. Rows carry the ad networks' own campaign / ad ids, so the agent can map a creative back to Google Ads, Meta Ads or TikTok Ads.
Bundled task:
cs-cron-roasit-creative-roas-reporterruns daily at 10:30 UTC and reports the last 7 days' creative ROAS per app, pause / scale recommendations for creatives that pass the significance gate, and an attribution audit (network-claimed vs Roasit-attributed installs, network claims vs store installs). Off until the Roasit credential is filled.
Agents that typically enable this integration:
- Google Ads Manager, Meta Ads Manager and TikTok Ads Manager: MMP-verified ROAS next to the platform's own numbers.
- Custom app-marketing agents that report on app growth.
Availability
| Mode | Status | Notes |
|---|---|---|
| API Token (Roasit) | Available | One read-only Roasit API token per agent. It sees the apps your Roasit account can see and cannot change anything. No extra charge: like every skill, it is included in every plan. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- A Roasit account with at least one app, and its Roasit SDK sending installs.
Setup
Step 1: Create a Roasit API token
- Sign in to Roasit and open your Account page.
- Under API tokens, give the token a name (for example
Wiro agent) and click Create. - Copy the token. It starts with
roapi_and is shown only once.
The token is read-only: it can read reports for the apps your Roasit account can see, and nothing else. Revoking it on the Account page cuts the agent off immediately.
Step 2: Find your Roasit app tokens (optional)
Leave the apps list empty and the agent reports on every app the token can see. To limit it to specific apps, or to give an app the name you use in chat, add one row per app and platform:
- Open the app in Roasit.
- Copy the App token shown in the app's header: 12 lowercase hex characters such as
a1b2c3d4e5f6, the same token the app's Roasit SDK starts with. - Pick the row's Platform: iOS, Android, or Web for a web app measured by Roasit's browser SDK and Stripe sales. One app token covers every platform of the app, so an app you run on several gets one row per platform with the same token; the agent filters each row's reports to its platform.
Step 3: Save the credential to Wiro
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "roasit", "fieldname": "apitoken", "fieldvalue": "roapi_YOUR_ROASIT_TOKEN" },
{ "credentialkey": "roasit", "parentfield": "apps", "ordinal": 0, "fieldname": "appname", "fieldvalue": "My Game" },
{ "credentialkey": "roasit", "parentfield": "apps", "ordinal": 0, "fieldname": "platform", "fieldvalue": "ios" },
{ "credentialkey": "roasit", "parentfield": "apps", "ordinal": 0, "fieldname": "apptoken", "fieldvalue": "a1b2c3d4e5f6" },
{ "credentialkey": "roasit", "parentfield": "apps", "ordinal": 0, "fieldname": "storeid", "fieldvalue": "1234567890" },
{ "credentialkey": "roasit", "parentfield": "apps", "ordinal": 1, "fieldname": "appname", "fieldvalue": "My Game" },
{ "credentialkey": "roasit", "parentfield": "apps", "ordinal": 1, "fieldname": "platform", "fieldvalue": "android" },
{ "credentialkey": "roasit", "parentfield": "apps", "ordinal": 1, "fieldname": "apptoken", "fieldvalue": "a1b2c3d4e5f6" },
{ "credentialkey": "roasit", "parentfield": "apps", "ordinal": 1, "fieldname": "storeid", "fieldvalue": "com.example.game" }
]
}'
Or fill it in the panel: My Agents → open agent → Connectors → Roasit.
Step 4: Make sure the skill is on
Google Ads Manager, Meta Ads Manager and TikTok Ads Manager agents include int-roasit-attribution at no extra charge, so saving the credential is enough. On any other agent, turn it on:
curl -X POST "https://api.wiro.ai/v1/UserAgent/SkillsApply" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"skills": { "int-roasit-attribution": true },
"idempotencyKey": "550e8400-e29b-41d4-a716-446655440000"
}'
Or flip the toggle in the panel under Skills (see Agent Skills).
Step 5: Start the agent
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
Credential Fields
| Field | Type | Required | Description |
|---|---|---|---|
apitoken | string (secret) | Yes | Roasit API token, roapi_ followed by 43 characters. Encrypted at rest. |
apps[].appname | string | Yes (per row) | Friendly label the agent uses in chat and reports. |
apps[].platform | ios / android / web | Yes (per row) | The platform the row reports on. An app on several platforms has one row per platform with the same app token. A web row has no SKAN or install reconciliation. |
apps[].apptoken | string (12 hex characters) | Yes (per row) | The Roasit app token shown in the app's header. |
apps[].storeid | string | No | The row's Apple ID or Android package name, to join Roasit numbers with your App Store / Google Play integrations. |
Credentials schema (as returned by POST /UserAgent/Detail)
"roasit": {
"_connected": true,
"optional": true,
"extra": true,
"apitoken": "••••••••",
"apps": [
{ "appname": "My Game", "platform": "ios", "apptoken": "a1b2c3d4e5f6", "storeid": "1234567890" },
{ "appname": "My Game", "platform": "android", "apptoken": "a1b2c3d4e5f6", "storeid": "com.example.game" }
]
}
optional and extra are true on the ads-manager agents: Roasit is an optional attribution source, and its connector card shows up even before the skill is on.
What the agent reports
The agent reads Roasit's report API, one app per request, and never recomputes a metric itself, so every number equals the Roasit dashboard's for the same app, dates, grouping, filters and IAP setting.
| Metric | Meaning |
|---|---|
roas_all | Cohort revenue to date ÷ ad spend. |
roas_ad_all / roas_iap_all | The ad-revenue / in-app-revenue part of it. |
roas_N, ret_N, arpu_N | Day-N ROAS, retention and ARPU (mature cohorts only). |
installs, network_installs | Installs Roasit attributed vs. installs the ad networks claim. |
spend, cpi, impressions, clicks | Paid media, in the report's currency (USD unless the app reports in another one). |
rev_all, rev_ad, rev_iap | Cohort revenue to date, total / ads / in-app. |
Breakdowns: day, platform, country, network, campaign, ad group and ad. A "-" (null) value means the dashboard shows none yet (no spend, a cohort not old enough, or a day whose spend is not final) and is never treated as zero.
Creative-level ROAS needs Roasit to pull spend at ad level for that network (Spend detail in the Roasit app settings); networks pulled at campaign level are reported at campaign level.
Billing
Every plan includes the integration, so it changes neither the agent's price nor its credits. As with every agent turn, the reports and the daily task are billed on the LLM tokens they use, from the agent's existing credits.
Recommendations & approval
The daily task writes pause_creative_low_roas, scale_creative_high_roas and attribution_audit items to the agent's recommendation ledger; nothing changes on an ad platform until you approve an item (apply 1,3, apply all safe, skip 2). Thresholds (minimum spend and installs, the ROAS metric, floor and ceiling, drift and overcount limits) live in the editable roasit-strategy custom skill and fall back to ad-strategy.
Troubleshooting
- 401: The token was revoked or mistyped. Create a new one on Roasit's Account page and save it again.
- 404 for an app: The app token is wrong, or the Roasit account behind the token cannot see that app.
- Creative ROAS shows "-": That network's spend is pulled at campaign level in Roasit, so raise Spend detail or read the campaign-level row.
- Today's or yesterday's ROAS is missing: Roasit's nightly spend pull has not finalised the day yet; the report names the excluded days.
- Agent says "not connected" with the token filled: The agent restarts to pick up new credentials; give it a moment after saving, then retry.
Related
Google Merchant Center Integration
Connect your agent to Google Merchant Center (Shopping) for product feed management, status issues, and shopping reports.
Overview
The Merchant Center integration uses the Merchant API v1 (the newer replacement for the deprecated Content API for Shopping v2.1).
Skills that use this integration:
int-merchant-center: Product feed management, status issue scanning, shipping/tax, orders
Agents that typically enable this integration:
- Google Ads Manager: for Shopping and PMax campaigns that depend on the product feed
Availability
| Mode | Status | Notes |
|---|---|---|
"own" | Available | Your own Google Cloud project and OAuth client, plus a one-time developer registration of that project against your primary Merchant Center. |
"wiro" | Coming soon | Wiro's shared Google Cloud project is awaiting Google's review. Until then, OAuthConnect in Wiro mode, which is also what you get when you leave out authmethod, returns Sign-in with the platform's app is not enabled for Merchant Center. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- A Merchant Center account the connecting user administers.
- A Google Cloud project with Merchant API enabled.
- Developer Registration: a one-time step to link your GCP project to your primary MC account.
- An HTTPS callback URL.
Own Mode
Step 1: Create GCP project + enable Merchant API
- console.cloud.google.com → create a project.
- APIs & Services → Library → enable Merchant API.
- OAuth consent screen:
- External user type for multi-tenant use
- App name, support email
- Add scope:
https://www.googleapis.com/auth/content - Publish the app (In production). While it is in Testing, Google expires its refresh tokens after 7 days and the agent loses access.
Step 2: Create OAuth Client
APIs & Services → Credentials → Create Credentials → OAuth client ID:
- Application type: Web application
- Authorized redirect URIs:
https://api.wiro.ai/v1/UserAgentOAuth/MCCallback
Copy the client ID and the client secret.
Step 3: Register Developer Registration (REQUIRED, one-time)
Merchant API requires that your GCP project be registered against your primary Merchant Center account before it will answer for any merchant account you authorize:
curl -X POST \
"https://merchantapi.googleapis.com/accounts/v1/accounts/{YOUR_PRIMARY_MC_ID}/developerRegistration:registerGcp" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{}'
Where:
YOUR_PRIMARY_MC_ID: your own Merchant Center ID (you, the developer)ACCESS_TOKEN: a fresh access token for your primary MC account
Once registered, your GCP project can call Merchant API on any merchant account that a user authorizes through OAuth.
Step 4: Connect
Save the OAuth client with POST /UserAgent/CredentialUpsert:
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "google-merchant-center", "fieldname": "clientid", "fieldvalue": "123-abc.apps.googleusercontent.com" },
{ "credentialkey": "google-merchant-center", "fieldname": "clientsecret", "fieldvalue": "YOUR_CLIENT_SECRET" },
{ "credentialkey": "google-merchant-center", "fieldname": "authmethod", "fieldvalue": "own" }
]
}'
Then start OAuthConnect in own mode:
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "google-merchant-center",
"redirecturl": "https://your-app.com/settings/integrations",
"authmethod": "own"
}'
The response returns { result: true, authorizeUrl: "...", flowid: "..." }. Redirect the user to authorizeUrl. Google asks which Google account to connect, even when the browser is already signed in to one.
Step 5: Save the account selection
After consent the user returns with ?mc_connected=true&mc_accounts=<URL-encoded-JSON>. Each entry is { id, name, websiteUrl }: id is the numeric Merchant Center ID, name is the account name and can be empty, and websiteUrl is always empty. When name is empty, label the account with its ID. Send the user's choice to SetPickerAccounts as { merchantid, accountname } (id becomes merchantid, name becomes accountname):
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/SetPickerAccounts" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "google-merchant-center",
"accounts": [
{ "merchantid": "1234567890", "accountname": "Acme Store" }
]
}'
This call is required, even when mc_accounts has one entry. Until it runs, OAuthStatus reports connected: false.
Pass multiple { merchantid, accountname } entries to authorize the agent against several merchant accounts at once. Wiro saves only accounts from this sign-in's list, under the names it lists, when the call comes from the same Wiro account within 15 minutes. The first save uses the list up: to change the selection later, connect again. See SetPickerAccounts.
Disconnect
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthDisconnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "google-merchant-center"
}'
Clears the tokens and the selected accounts in Wiro. Your Client ID and Client Secret are kept. Wiro does not ask Google to revoke the authorization.
Status
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthStatus" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "google-merchant-center"
}'
Response:
{
"result": true,
"connected": true,
"accounts": [
{ "id": "1234567890", "name": "Acme Store" }
],
"connectedat": "2026-04-17T12:00:00.000Z",
"tokenexpiresat": "2026-04-17T13:00:00.000Z",
"errors": []
}
accounts[] carries one entry per selected merchant (id = merchantid, name = accountname).
Skill reference
- agent-skills.md: custom skill schema and the
int-merchant-centerkey
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
Sign-in with the platform's app is not enabled for Merchant Center in OAuthConnect's errors[] | Wiro mode isn't available yet, and it is the default when authmethod is left out | Save your OAuth client (Step 4) and call OAuthConnect with "authmethod": "own" |
PERMISSION_DENIED on any merchant call | GCP project not registered | Complete Step 3 once |
Merchant Center credentials not configured in OAuthConnect's errors[] | authmethod: "own" without a saved clientid and clientsecret | Save them (Step 4), then retry |
invalid_grant | Refresh token expired or revoked; a consent screen still in Testing expires it after 7 days | Publish the consent screen, then re-connect via OAuthConnect |
mc_error=no_accounts on your redirecturl | The Merchant API listed no account for this Google user, and Wiro saved nothing. With mc_error_detail (for example PERMISSION_DENIED), Google refused the call: the Merchant API may be disabled or the project not registered (Step 3). | Enable the Merchant API, complete Step 3, or connect with a user who has Merchant Center access, then call OAuthConnect again. |
| Content API deprecation error | You're on old v2.1 endpoints | Switch to v1 (merchantapi.googleapis.com) |
redirect_uri_mismatch on Google's page
The Authorized redirect URIs of your OAuth client don't include https://api.wiro.ai/v1/UserAgentOAuth/MCCallback exactly as written. Google stops on its own error page, so nothing comes back to your redirecturl. Add the URI (Step 2) and connect again.
Google Business Profile Integration
Connect your agent to Google Business Profile to read the Google reviews of the locations you choose, draft a reply to each new review, and post the replies you approve.
Overview
The Google Business Profile integration powers the int-google-business-reviews skill (Google Business Reviews). The agent works through Google's Business Profile APIs with an OAuth client from your own Google Cloud project. It reads the reviews of the Business Profile locations you selected, drafts one reply per new review in the reviewer's language, sends the drafts to you, and posts a reply only after you approve it.
Skills that use this integration:
int-google-business-reviews: Reads the Google reviews of the selected locations, drafts replies, posts approved replies, and follows Google's moderation of each posted reply.
Bundled task:
cs-cron-google-review-scannerruns every 2 hours (0 */2 * * *), scans the selected locations for new reviews and sends you the drafted replies. It runs only when Google Business Profile is connected.
Availability
| Mode | Status | Notes |
|---|---|---|
"own" | Available (the only mode) | An OAuth client from your own Google Cloud project. Google must approve that project for Business Profile API access before any call works. |
"wiro" | Not available | Wiro-managed one-click connect is not available for Google Business Profile. |
Google approves the project first. You request Business Profile API access for your Google Cloud project, and Google reviews requests within 14 days. Until the project is approved, every call to Google fails, and connecting typically ends with "No accounts available". See Google Cloud setup.
Prerequisites
- A verified Business Profile. Google asks for a profile that has been verified and active for 60+ days, with the business website listed, before it grants API access.
- A Google account that is an owner or manager of the Business Profile. Request API access with its email, and connect with the Google account that manages the business.
- A Google Cloud project approved for Business Profile API access, with an OAuth client of type Web application (see Google Cloud setup).
- An agent with
int-google-business-reviewsenabled: see Using the Skill. - For API integrations only: a Wiro API key (Authentication), a deployed agent (Agent Overview) and its
useragentguid, and an HTTPS return URL that your backend controls.http://localhostandhttp://127.0.0.1are accepted for local development only.
Google Cloud setup
Do these steps once, in this order, in the Google Cloud project whose OAuth client the agent will use.
Step 1: Create or pick a project
In the Google Cloud Console, create a project or pick an existing one. Copy its Project number from the project dashboard; you need it for the access request in Step 2.
Step 2: Request Business Profile API access
- Open Google's Business Profile API contact form and choose Application for Basic API Access.
- Apply for the project from Step 1, with an email that is an owner or manager of the Business Profile.
- Google asks for a profile that has been verified and active for 60+ days, with the business website listed, and reviews requests within 14 days. See Google's prerequisites and FAQ.
Step 3: Check the approval
Open IAM & Admin → Quotas for the project and look at the requests-per-minute quota of the Business Profile APIs:
- 0 requests per minute: not approved yet. Every call to Google fails until this changes.
- 300 requests per minute: approved. Continue with Step 4.
Step 4: Enable the APIs
After approval, enable these three APIs in the project:
- Google My Business API: listed in the API Library only after the project is approved.
- My Business Account Management API
- My Business Business Information API
Step 5: Set the audience
In Google Auth Platform → Audience:
- Choose External.
- Set the publishing status to In production. While the app is in Testing, Google expires the refresh token after 7 days (Google's OAuth 2.0 documentation), and the agent loses access every week.
When you connect, Google may warn that the app is unverified. It is your own app: continue as the app's owner.
Step 6: Add the scope
In Data Access, add this scope:
https://www.googleapis.com/auth/business.manage
Step 7: Create the OAuth client
In Clients, create an OAuth client of type Web application and add this Authorized redirect URI, exactly as written:
https://api.wiro.ai/v1/UserAgentOAuth/GBPCallback
Copy the Client ID and the Client Secret.
Connect in the Wiro dashboard
- Open your agent, go to Connectors, and find the Google Business Profile card.
- Paste the OAuth Client ID and OAuth Client Secret from Step 7.
- Click Connect Google Business Profile and sign in with the Google account that manages the business. If Google warns that the app is unverified, continue as the app's owner.
- Choose the Business Profile accounts the agent may use.
- Choose the locations. Up to 100 locations per account are listed.
- Wiro saves the selection and restarts the agent if it was running.
To change the locations later, use Manage on the Google Business Profile card. The agent reads and answers reviews only for the locations you selected.
What the agent does
- Reads new reviews of the selected locations.
- Drafts one reply per new review, in the reviewer's language. When Google shows a translated review, the agent answers the original text.
- Follows your review preferences. Before drafting, it reads the
cs-review-preferencescustom skill: tone, length by rating, contact line, sign-off, and house rules. -
Sends the drafts to you, numbered, in chat and on Telegram if it is connected. Answer in chat:
ok 1: approve draft 1ok all: approve every draftskip 2: skip draft 2edit 1: <text>(replace draft 1 with your text)
- Posts approved replies through the Google Business Profile API.
- Follows Google's moderation. Google reviews every reply before it is public: a reply is
PENDING, thenAPPROVED, orREJECTEDwith a policy violation. The agent tells you about rejected replies. - Edits or deletes a posted reply only when you ask.
- Starts with recent reviews. The first scan of a location drafts replies only for unanswered reviews from the last 30 days, and reports how many older reviews have no reply.
- Escalates instead of answering. Legal, health, safety and discrimination complaints go to you instead of getting a reply.
- Never offers incentives for reviews, and never shares reviewer details beyond their public first name.
- Keeps review content for at most 30 days, as Google's API policy requires.
What the agent cannot do
These are outside this integration:
- Changing business details: name, hours, address, or photos.
- Creating posts.
- Answering Q&A.
- Reporting or removing a review. The business does that in Google Maps.
- Replying for locations you did not select.
Approvals
- Every reply waits for your approval by default, one approval per reply. The rule lives in the
cs-approval-policycustom skill. - Why: Google's Business Profile API policies say automated replies need the business's prior, specific and express consent. This is why replies wait for your approval by default.
- Auto-approve rules. You can add an override to
cs-approval-policy, for example "auto-approve replies to 5-star reviews". Matching replies are then posted without asking, at most 5 per scan unlesscs-review-preferencessets another number.
Limits
| Limit | Value |
|---|---|
| Reply length | At most 4096 bytes. Letters such as ç, ğ, ş and é count as 2 bytes. |
| Google API quota | 300 requests per minute for the Google Cloud project after approval (0 before). |
| Business Profile accounts listed | Up to 20. |
| Locations listed per account | Up to 100. |
| Automatic replies | At most 5 per scan, unless cs-review-preferences sets another number. |
| Review content kept | At most 30 days. |
Scheduled task
| Task | Skill key | Default schedule | What it does |
|---|---|---|---|
| Review scanner | cs-cron-google-review-scanner | 0 */2 * * * (every 2 hours) | Reads new reviews of the selected locations, drafts replies, and sends them to you for approval; posts the replies an auto-approve rule allows. Runs only when Google Business Profile is connected. |
To change what the scanner does, edit the custom skills it reads rather than the task:
cs-review-preferences: tone, length by rating, contact line, sign-off, house rules, and the number of automatic replies per scan.cs-approval-policy: which replies wait for your approval.
Connect through the API
Use this flow when you build your own settings screen on top of Wiro agents. Complete the Google Cloud setup first. Every request is authenticated as described in Authentication.
Step 1: Save your OAuth client
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "google-business", "fieldname": "clientid", "fieldvalue": "YOUR_GOOGLE_OAUTH_CLIENT_ID" },
{ "credentialkey": "google-business", "fieldname": "clientsecret", "fieldvalue": "YOUR_GOOGLE_OAUTH_CLIENT_SECRET" },
{ "credentialkey": "google-business", "fieldname": "authmethod", "fieldvalue": "own" }
]
}'
Response: { "result": true, "errors": [], "applied": 3 }. clientid and clientsecret are not returned by POST /UserAgent/Detail, so check result and errors[] here.
Step 2: Start the connection
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "google-business",
"redirecturl": "https://your-app.com/settings/integrations",
"authmethod": "own"
}'
Response:
{
"result": true,
"errors": [],
"authorizeUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=https%3A%2F%2Fapi.wiro.ai%2Fv1%2FUserAgentOAuth%2FGBPCallback&response_type=code&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fbusiness.manage&state=...&access_type=offline&prompt=select_account+consent",
"flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19"
}
Redirect the user's browser to authorizeUrl with a full-page redirect rather than a popup. Wiro requests the business.manage scope with offline access, so Google issues a refresh token. Google asks which Google account to connect, even when the browser is already signed in to one.
Always send authmethod: "own". Without it, or with "wiro", OAuthConnect returns Sign-in with the platform's app is not enabled for Google Business Profile.
State TTL: Wiro keeps the OAuth state for 15 minutes. If the user takes longer on Google's consent screen, the connection fails with gbp_error=session_expired; call OAuthConnect again.
Step 3: Handle the return
After the user approves, Google sends them to Wiro's callback (https://api.wiro.ai/v1/UserAgentOAuth/GBPCallback). Wiro exchanges the code, lists the Business Profile accounts the Google user can access, stores the tokens server-side, and redirects the browser to your redirecturl.
Success URL looks like:
https://your-app.com/settings/integrations?gbp_connected=true&gbp_accounts=%5B%7B%22id%22%3A%22112233445566778899001%22%2C%22name%22%3A%22Acme%20Bakery%22%7D%5D
gbp_accountsisencodeURIComponent(JSON.stringify([...])).- Each element is
{ id, name }:idis the numeric Business Profile account ID as a string,nameis the account name. - The list is never empty on success. When no Business Profile account can be listed, the callback returns
gbp_error=no_accountsinstead; right after setup this usually means Google has not approved the project yet or an API is disabled (see Troubleshooting). - On failure the URL carries only
gbp_error=<code>.
Parse in the browser:
const params = new URLSearchParams(window.location.search);
if (params.get("gbp_connected") === "true") {
const accounts = JSON.parse(params.get("gbp_accounts") || "[]");
presentAccountPicker(accounts);
} else if (params.get("gbp_error")) {
handleError(params.get("gbp_error"));
}
Step 4: Save the account selection
This call is required, even when only one account is returned:
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/SetPickerAccounts" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "google-business",
"accounts": [
{ "accountid": "112233445566778899001", "accountname": "Acme Bakery" }
]
}'
Response:
{
"result": true,
"errors": [],
"accounts": [
{ "id": "112233445566778899001", "name": "Acme Bakery" }
],
"restart": "scheduled"
}
Behavior:
- Send one or more
{ accountid, accountname }entries picked fromgbp_accounts(idbecomesaccountid,namebecomesaccountname). Non-digits inaccountidare stripped server-side. - A save replaces the previous account selection. Locations already chosen for accounts that stay selected are kept; locations of removed accounts are dropped. Wiro saves only accounts from this sign-in's list, under the names it lists, when the call comes from the same Wiro account within 15 minutes. The first save uses the list up: to change the selection later, connect again. See SetPickerAccounts.
- If the agent was running, Wiro restarts it.
Step 5: Choose the locations
Discover the locations of the selected accounts:
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/DiscoverPickerItems" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "google-business",
"pickerkey": "locations"
}'
Response:
{
"result": true,
"errors": [],
"pickerkey": "locations",
"groups": [
{
"parent": {
"accountid": "112233445566778899001",
"accountname": "Acme Bakery"
},
"items": [
{ "locationid": "9876543210987654321", "locationtitle": "Acme Bakery Downtown" },
{ "locationid": "1234567890123456789", "locationtitle": "Acme Bakery Riverside" }
]
}
]
}
Up to 100 locations per account are listed. A group carries errorcode and an empty items array when Google did not return the locations of that account. errorcode is provider_rejected_request when Google refused the call (for example the Google user can't manage that account, or an API is disabled) and provider_timeout when Google did not answer within 10 seconds; provider_request_failed, invalid_provider_response, response_too_large and picker_discovery_failed cover other failures.
Save the selection within five minutes. Copy locationid and locationtitle from the discovery response unchanged, and include every group returned without an errorcode exactly once; an empty items array selects no location for that account. Leave out groups that carry an errorcode: sending one fails with Selected parent is not available, and the locations already saved for that account stay as they are:
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/SetPickerAccounts" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "google-business",
"pickerkey": "locations",
"selections": [
{
"parentvalue": "112233445566778899001",
"items": [
{ "locationid": "9876543210987654321", "locationtitle": "Acme Bakery Downtown" }
]
}
]
}'
Response:
{
"result": true,
"errors": [],
"pickerkey": "locations",
"locationmappings": [
{
"accountid": "112233445566778899001",
"accountname": "Acme Bakery",
"locationid": "9876543210987654321",
"locationtitle": "Acme Bakery Downtown"
}
],
"restart": "scheduled"
}
The dashboard runs this step automatically after the account selection. If the agent was running, Wiro restarts it.
Accounts and locations in one call. Steps 4 and 5 can restart a running agent twice. To restart it once, skip the save of Step 4: call DiscoverPickerItems with the chosen accounts in parents and the flowid from OAuthConnect, then save both with one SetPickerAccounts call that sends accountids, flowid, pickerkey and selections, with each account's locations in itemids or items. Choose at least one location across the accounts, or the save answers Choose at least one location to finish. (errorcode: "next_required"). Both calls must name the same accounts within five minutes, or the save answers next_expired and you discover again. See Both steps in one call.
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/DiscoverPickerItems" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "google-business",
"pickerkey": "locations",
"flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19",
"parents": ["112233445566778899001"]
}'
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/SetPickerAccounts" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "google-business",
"flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19",
"accountids": ["112233445566778899001"],
"pickerkey": "locations",
"selections": [
{ "parentvalue": "112233445566778899001", "itemids": ["9876543210987654321"] }
]
}'
Step 6: Verify the connection
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthStatus" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "google-business"
}'
Response:
{
"result": true,
"errors": [],
"connected": true,
"accounts": [
{ "id": "112233445566778899001", "name": "Acme Bakery" }
],
"connectedat": "2026-10-17T09:00:00.000Z",
"tokenexpiresat": "2026-10-17T10:00:00.000Z",
"pickersteps": {
"locations": {
"pickerkey": "locations",
"optional": false,
"configured": true,
"groups": [
{
"parent": {
"accountid": "112233445566778899001",
"accountname": "Acme Bakery"
},
"items": [
{ "locationid": "9876543210987654321", "locationtitle": "Acme Bakery Downtown" }
]
}
]
}
},
"locationmappings": [
{
"accountid": "112233445566778899001",
"accountname": "Acme Bakery",
"locationid": "9876543210987654321",
"locationtitle": "Acme Bakery Downtown"
}
]
}
Field notes:
connectedistruewhen the connection has a current access token and at least one account is selected. It does not look at locations:pickersteps.locations.configuredistrueonce at least one location is selected.tokenexpiresatis the expiry of the current access token (about one hour ahead). Wiro renews the access token while the agent is running.connectedatis the time of the last successful Connect.
Step 7: Start the agent if it's not running
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
Start doesn't wait for every connector. setuprequired: true on POST /UserAgent/Detail means a connector the agent requires is still incomplete, and the agent starts all the same. Only an agent still at status: 6 is refused: call POST /UserAgent/Update on it first. See Agent Credentials: Setup Required.
Credential fields
| Field | Type | Description |
|---|---|---|
clientid | string | OAuth Client ID of your Google Cloud OAuth client (own mode). Not returned by POST /UserAgent/Detail. |
clientsecret | string (secret) | OAuth Client Secret (own mode). Encrypted at rest; not returned by POST /UserAgent/Detail. |
accountid | array of strings | Numeric IDs of the selected Business Profile accounts. Required. Filled by the connection flow (SetPickerAccounts). |
accountname | array of strings | Names of the selected accounts, in the same order. Filled by the connection flow. |
locationmappings | array of objects | The selected locations, one { accountid, accountname, locationid, locationtitle } entry per location. Server-managed; written by the location step. |
POST /UserAgent/CredentialUpsert rejects writes to accountid, accountname and locationmappings with <Field label> is managed by the connection flow. Access and refresh tokens are stored server-side and are never returned by any endpoint.
API Reference
All endpoints require Wiro authentication: see Authentication for x-api-key + optional signature headers.
POST /UserAgentOAuth/OAuthConnect
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid | string | Yes | Agent instance GUID. |
credentialkey | string | Yes | "google-business". |
redirecturl | string | Yes | Any HTTPS URL you control (or http://localhost / http://127.0.0.1 for development) where the browser returns after Google. |
authmethod | string | Yes | "own", the only available mode. |
Response: { result, errors, authorizeUrl, flowid }. If result: false, inspect errors[0].message. Common messages: Invalid redirect URL, User agent not found or unauthorized, Sign-in with the platform's app is not enabled for Google Business Profile (no authmethod, or "wiro"), and Google Business Profile credentials not configured (the Client ID or Client Secret is not saved).
GET /UserAgentOAuth/GBPCallback
Server-side endpoint invoked by Google. You don't call it: you register it as the Authorized redirect URI of your OAuth client and handle the final redirect back to your redirecturl.
| Query param | Meaning |
|---|---|
gbp_connected=true | Authorization completed. |
gbp_accounts | URL-encoded JSON array of { id, name }, with up to 20 Business Profile accounts the Google user can access. Always at least one entry. |
gbp_error=<code> | The connection failed. See Troubleshooting. |
POST /UserAgentOAuth/SetPickerAccounts
The same endpoint saves both picker steps.
Account selection:
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid | string | Yes | Agent instance GUID. |
credentialkey | string | Yes | "google-business". |
accounts | array | Yes | One or more { accountid, accountname } entries. accountid is the numeric account ID (non-digits stripped); Wiro saves the name from its list as accountname, the display name shown in dashboards and OAuthStatus responses. |
Response: { result, errors, accounts: [{id, name}, ...], restart }. Replaces the previous account selection. The save that completes the connection restarts a running agent once (restart: "scheduled"), and a save that changes nothing restarts nothing.
Location selection, after DiscoverPickerItems:
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid | string | Yes | Agent instance GUID. |
credentialkey | string | Yes | "google-business". |
pickerkey | string | Yes | "locations". |
selections | array | Yes | One { parentvalue, items } entry for every group discovery returned without an errorcode. parentvalue is the account ID; each item carries locationid and locationtitle. Empty items selects no location for that account. Leave out groups that carry an errorcode: sending one fails with Selected parent is not available, and the locations already saved for that account stay as they are. |
Response: { result, errors, pickerkey: "locations", locationmappings: [{accountid, accountname, locationid, locationtitle}], restart }.
POST /UserAgentOAuth/DiscoverPickerItems
Lists the locations of the selected Business Profile accounts, grouped by account. Call it after the account selection is saved, or, with parents and flowid, before it, to save the accounts and their locations in one call.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid | string | Yes | Agent instance GUID. |
credentialkey | string | Yes | "google-business". |
pickerkey | string | Yes | "locations". |
parents | string[] | No | Account IDs from the sign-in's list, before they are saved (at most 20). |
flowid | string | No | With parents: the flowid from OAuthConnect. |
Response: { result, errors, pickerkey: "locations", groups: [{parent: {accountid, accountname}, items: [{locationid, locationtitle}], errorcode?}] }. Up to 100 locations per account. The access token stays server-side. Wiro keeps the discovered candidates for five minutes; save the location selection before they expire.
POST /UserAgentOAuth/OAuthStatus
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid | string | Yes | Agent instance GUID. |
credentialkey | string | Yes | "google-business". |
Response fields:
| Field | Type | Description |
|---|---|---|
connected | boolean | true when the connection has a current access token and at least one selected account. Use setuprequired from POST /UserAgent/Detail for whole-agent readiness. |
accounts | array | One { id, name } per selected account (id = accountid, name = accountname). |
locationmappings | array | The selected locations, one { accountid, accountname, locationid, locationtitle } entry each. |
pickersteps.locations | object | Location selection grouped by account for UI rendering: { pickerkey, optional, configured, groups[] }. |
connectedat | string | ISO timestamp of the last successful Connect. |
tokenexpiresat | string | ISO expiry of the current access token (about one hour ahead while the agent runs). |
POST /UserAgentOAuth/OAuthDisconnect
Body: { useragentguid, credentialkey: "google-business" }. Clears the tokens and the account and location selections in Wiro. Your Client ID and Client Secret are kept, so you can connect again without re-entering them. Wiro does not ask Google to revoke the authorization.
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthDisconnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "google-business"
}'
Response: { "result": true, "errors": [] }. A starting or running agent restarts when the disconnect removes a token or the connection was complete. Otherwise, for example with only the app keys saved, it restarts nothing.
Token lifecycle
Wiro renews the access token with the stored refresh token while the agent is running. When the agent is stopped, the token runs out about an hour after the last renewal: OAuthStatus then reports connected: false, and DiscoverPickerItems answers Google Business Profile account not connected, until the agent starts and renews it. While the consent screen is in Testing, Google expires the refresh token after 7 days; set it to In production to avoid weekly disconnects. If Google revokes the access, or connected stays false while the agent runs, call OAuthDisconnect and run Steps 2 to 5 again. There is no customer-facing token-refresh endpoint.
Using the Skill
Google Review Manager has int-google-business-reviews on by default. On any other agent, enable it with POST /UserAgent/SkillsApply (see Agent Skills → Toggling Integration Skills):
curl -X POST "https://api.wiro.ai/v1/UserAgent/SkillsApply" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"idempotencyKey": "550e8400-e29b-41d4-a716-446655440002",
"skills": {
"int-google-business-reviews": true
}
}'
Pricing: like every skill, int-google-business-reviews is included in every plan: turning it on costs nothing and keeps the plan's price and credits. As with every agent turn, scans and replies are billed on the LLM tokens they use.
Adjust the scanner's schedule with enabled and interval only. The task body (value) is owned by the bundled integration skill and silently dropped on writes:
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"skillkey": "cs-cron-google-review-scanner",
"enabled": true,
"interval": "0 */4 * * *"
}'
To change how replies read, edit cs-review-preferences; to change which replies wait for approval, edit cs-approval-policy (see Agent Skills → Updating Preferences).
Troubleshooting
| Error code | Meaning | What to do |
|---|---|---|
no_accounts | Sign-in worked, but no Business Profile account could be listed for this Google user. Right after setup this usually means the project is not approved yet (quota 0) or an API is disabled. | Check Steps 3 and 4 of the Google Cloud setup, then connect again. Otherwise connect with the Google account that owns or manages the business. |
authorization_denied | The user cancelled on Google's consent screen, or Google returned an error instead of an authorization code. | Start again and approve the consent screen. |
session_expired | More than 15 minutes passed between OAuthConnect and the return from Google. A repeated return after a completed one is not an error: it lands where the first one did. | Call OAuthConnect again. |
flow_replaced | A newer sign-in for the same agent and credential replaced this one, whoever started it, so nothing from it was saved. | Use the newer sign-in, or start again with OAuthConnect. |
missing_params | The callback was opened without an OAuth state. | Don't open the callback URL directly. Start a new flow with OAuthConnect. |
token_exchange_failed | Google did not return an access token for the authorization code, usually because of a wrong Client Secret or a redirect URI mismatch. | Re-copy the Client Secret, check the redirect URI, and connect again. |
useragent_not_found | The agent was deleted, or is no longer owned by the account that started the flow, before Google returned. | Start again with OAuthConnect for an existing agent. |
internal_error | Unexpected server error during callback processing. | Retry once. If it persists, contact Wiro support with the timestamp and your useragentguid. |
Sign-in with the platform's app is not enabled for Google Business Profile | Returned in OAuthConnect's errors[] when authmethod is missing or "wiro". | Send authmethod: "own". |
Google Business Profile credentials not configured | Returned in OAuthConnect's errors[] when the Client ID or Client Secret is not saved. | Save both with POST /UserAgent/CredentialUpsert (Step 1), then retry. |
Picker candidates expired. Discover them again. | More than five minutes passed after location discovery, or the account selection changed. | Call DiscoverPickerItems again, then resubmit the location selection. |
Choose at least one location to finish. | errorcode: "next_required": the accounts and locations were saved in one call with no location chosen. | Choose at least one location and save again. |
The list of locations expired. Load it again. | errorcode: "next_expired": the accounts and locations were saved in one call, but the locations weren't discovered with parents for those accounts, from this sign-in, in the last five minutes. | Call DiscoverPickerItems with parents again, then save. |
selections must include every available parent exactly once | The location selection left out or repeated an account group. | Send one selections[] entry per group returned without errorcode; use items: [] to select no location for an account. |
Google Business Profile account not connected | Returned by DiscoverPickerItems or the location SetPickerAccounts call when no account is saved yet, or when the access token has run out: about an hour after the last renewal while the agent is stopped. | Save the account selection (Step 4). If it is saved, start the agent so Wiro renews the token, or connect again with Steps 2 and 3: the saved accounts stay selected. |
Without a state, Wiro can't tell which flow the callback belongs to, so missing_params sends the browser to the API's own neutral page, https://api.wiro.ai/v1/UserAgentOAuth/SignInNotFinished, instead of to your app. session_expired returns to your redirecturl, as long as the return comes within a day of OAuthConnect.
"No accounts available" right after connecting
The Google Cloud project is usually not approved yet (0 requests per minute in IAM & Admin → Quotas), or one of the three APIs from Step 4 is disabled. Connect again once Google has approved the project and the APIs are enabled.
redirect_uri_mismatch on Google's page
The Authorized redirect URI on your OAuth client does not exactly match https://api.wiro.ai/v1/UserAgentOAuth/GBPCallback. Fix it in Clients; Google can take from a few minutes to a few hours to apply the change (Google Cloud help).
The connection drops every week
The consent screen is still in Testing, where Google expires the refresh token after 7 days. Set the publishing status to In production in Audience, then connect again.
The agent reports a Google access problem
The agent tells you in chat when Google says the project is not approved, an API is disabled, the account cannot manage a location, or the connection expired. Fix the cause in Google Cloud or in the Business Profile. For an expired connection, click Disconnect on the Google Business Profile card, then connect again.
Google rejected a reply
Google reviews every reply before it is public. When it marks a reply REJECTED for a policy violation, the agent tells you; ask it to edit or delete that reply.
connected: true, but no reviews are answered
connected covers the account selection only. Check that at least one location is selected: use Manage on the Google Business Profile card, or run the location step (Step 5) through the API.
Multi-Tenant Architecture
For SaaS products connecting many businesses through a single Wiro-powered backend:
- One Wiro agent instance per business. Call
POST /UserAgent/Deployduring onboarding, then run the connection flow for that business'suseragentguid. - Tokens are isolated per agent instance. One business's Google authorization is never visible to another, because they live under different
useragentguidvalues. - The consent screen shows your app. The connection uses your own OAuth client, so Google shows the app name of your Google Cloud project.
- The quota belongs to the Google Cloud project. Every connection made with the same OAuth client shares its 300 requests per minute.
Related
- Agent Credentials & OAuth: integration catalog hub and generic OAuth reference.
- Agent Overview: deploying, starting, and lifecycle.
- Agent Skills: configuring
int-google-business-reviews, custom skills, and scheduled runs. - Telegram integration: receive the drafts on Telegram as well as in chat.
- App Store Connect integration and Google Play integration: reviews of your apps.
- Business Profile APIs prerequisites
Google Search Console Integration
Connect your agent to Google Search Console for read-only organic search reporting: clicks, impressions, click-through rate and average position by query, page, country and device, period comparisons, sitemap status and URL Inspection.
Overview
The Google Search Console integration uses Google OAuth 2.0 with the Google Search Console API and the read-only scope https://www.googleapis.com/auth/webmasters.readonly. The agent reads Search Console data only: it cannot add or remove properties, submit or delete sitemaps, or request indexing.
Skills that use this integration:
int-search-console: Search Analytics reporting (top, rising and falling queries and pages, period comparisons), sitemap status and URL Inspection, read-only
Agents that typically enable this integration:
- Content and SEO agents that plan or check articles against real search demand
- Any agent that reports on Google organic search next to Google Analytics 4
Availability
| Mode | Status | Notes |
|---|---|---|
"own" | Available | Your own Google Cloud project and OAuth client. |
"wiro" | Coming soon | Wiro's shared Google Cloud project is not enabled for Search Console yet. Until then, OAuthConnect in Wiro mode, which is also what you get when you leave out authmethod, returns Sign-in with the platform's app is not enabled for Google Search Console. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- A Search Console property the connecting Google account can open as an owner, full user or restricted user. Properties the account has not verified are not listed.
- A Google Cloud project with the Google Search Console API enabled.
- An HTTPS callback URL.
Own Mode
Step 1: Create a Google Cloud Project
- console.cloud.google.com → create a project, or use the one behind your Google Analytics 4 client.
- APIs & Services → Library → enable the Google Search Console API.
- OAuth consent screen:
- External user type for multi-tenant use
- App name, support email, developer contact
- Add the scope
webmasters.readonly(https://www.googleapis.com/auth/webmasters.readonly) - While the app is in Testing, only the test users you list can connect, and Google ends their authorization 7 days after consent. Add the connecting Google account as a test user, or publish the app (In production) so the agent keeps access.
Step 2: Create OAuth Client
APIs & Services → Credentials → Create Credentials → OAuth client ID:
- Application type: Web application
- Authorized redirect URIs:
https://api.wiro.ai/v1/UserAgentOAuth/SearchConsoleCallback
The OAuth client you made for Google Analytics 4 works too: add this redirect URI to it and enable the Google Search Console API in its project.
Copy the Client ID and Client Secret to your agent credentials.
Step 3: Connect
Save the Client ID and Client Secret with POST /UserAgent/CredentialUpsert:
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "google-search-console", "fieldname": "clientid", "fieldvalue": "123-abc.apps.googleusercontent.com" },
{ "credentialkey": "google-search-console", "fieldname": "clientsecret", "fieldvalue": "YOUR_CLIENT_SECRET" },
{ "credentialkey": "google-search-console", "fieldname": "authmethod", "fieldvalue": "own" }
]
}'
Then start OAuthConnect in own mode:
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "google-search-console",
"redirecturl": "https://your-app.com/settings/integrations",
"authmethod": "own"
}'
The response returns { result: true, authorizeUrl: "...", flowid: "..." }. Redirect the user to authorizeUrl. Google asks which Google account to connect, even when the browser is already signed in to one, and asks for read-only access to Search Console data.
Step 4: Property Picker
After consent, the user returns with ?gsc_connected=true&gsc_sites=<URL-encoded-JSON>. Each entry is { id, displayName, permissionLevel }: id is the property exactly as Search Console names it (sc-domain:example.com for a Domain property, or the full address of a URL-prefix property with its trailing slash, such as https://www.example.com/), displayName the same without the sc-domain: prefix, and permissionLevel Google's permission level for the connecting account (for example siteOwner, siteFullUser or siteRestrictedUser). Properties the account has not verified are left out. Map the user's choice to the picker shape and call SetPickerAccounts:
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/SetPickerAccounts" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "google-search-console",
"accounts": [
{ "siteurl": "sc-domain:example.com", "sitename": "example.com" }
]
}'
Pass several { siteurl, sitename } entries to authorize the agent against several properties at once (id becomes siteurl). Wiro saves each property's displayName from its list as sitename, so a name you send is not read. permissionLevel is handy for your UI, but it is not stored. Wiro saves only properties from this sign-in's list, under the names it lists, when the call comes from the same Wiro account within 15 minutes. The first save uses the list up: to change the selection later, connect again. See SetPickerAccounts.
Disconnect
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthDisconnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "google-search-console"
}'
Clears the tokens and the selected properties in Wiro. Your Client ID and Client Secret are kept, so you can connect again without saving them again. Wiro does not ask Google to revoke the authorization.
Status
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthStatus" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "google-search-console"
}'
Response:
{
"result": true,
"connected": true,
"accounts": [
{ "id": "sc-domain:example.com", "name": "example.com" }
],
"connectedat": "2026-11-21T12:00:00.000Z",
"tokenexpiresat": "2026-11-21T13:00:00.000Z",
"errors": []
}
accounts[] carries one entry per selected property (id = siteurl, name = sitename).
What the agent does with this integration
Search performance reports
Agent runs Search Analytics queries on operator request:
Operator → "top queries for the last 28 days"
Agent → POST /webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query
with dimensions=[query], type=web, rowLimit=25
and a date range that ends on the last day with data
Every answer names the property, the date range, the search type and Google Search Console as the source. Queries can be grouped and filtered by query, page, country, device, date and search appearance.
Period comparisons and movers
Agent compares two periods of the same length (for example the last 28 days against the 28 days before, or against the same dates a year earlier) and lists the queries and pages that gained or lost the most clicks, with the change in impressions, click-through rate and average position.
Sitemaps and URL Inspection
Agent lists the property's submitted sitemaps with their errors, warnings and last download, and inspects single URLs on request: index verdict, coverage, canonical URLs, last crawl, robots.txt and page fetch state. Google allows 2,000 URL inspections per property per day.
Data freshness
Google says Search Console data is typically available after 2-3 days. The agent finds the last day with data before it reports, does not read the newest days as a drop, and uses Pacific Time dates as Search Console does.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
Sign-in with the platform's app is not enabled for Google Search Console in OAuthConnect's errors[] | Wiro mode isn't available yet, and it is the default when authmethod is left out | Save your OAuth client (Step 3) and call OAuthConnect with "authmethod": "own" |
Google Search Console credentials not configured in OAuthConnect's errors[] | authmethod: "own" without a saved clientid and clientsecret | Save them (Step 3), then retry |
gsc_error=no_accounts on your redirecturl | Google listed no verified Search Console property for this user, and Wiro saved nothing: the account has no property or only unverified ones, or the Google Search Console API is not enabled in your project. In the last case gsc_error_detail carries Google's status, such as PERMISSION_DENIED | Enable the API (Step 1), or connect with a Google account that has access to a verified property, then call OAuthConnect again |
invalid_grant | Refresh token expired or revoked; a consent screen still in Testing expires it 7 days after consent | Publish the consent screen, then re-connect via OAuthConnect |
403 Request had insufficient authentication scopes | The consent did not include webmasters.readonly | Add the scope to the consent screen (Step 1) and connect again |
| The agent reports a 403 for one property | The Google account lost access to it, or the property is no longer verified | Restore the account's access in Search Console, or connect again and pick another property |
OAuthStatus returns connected: false right after consent | No property has been saved yet; the connection is complete only once SetPickerAccounts stores at least one | Call SetPickerAccounts with a property from gsc_sites (Step 4) |
redirect_uri_mismatch on Google's page
The Authorized redirect URIs of your OAuth client don't include https://api.wiro.ai/v1/UserAgentOAuth/SearchConsoleCallback exactly as written. Google stops on its own error page, so nothing comes back to your redirecturl. Add the URI (Step 2) and connect again.
Error 403: access_denied on Google's page
The app is in Testing and the Google account is not one of its test users. Add the account under test users (Step 1), or publish the app, then connect again.
Skill reference
- agent-skills.md: custom skill schema and the
int-search-consolekey
DataForSEO Integration
Give your agent keyword, search and app store data from your own DataForSEO account: search volume, CPC and competition, keyword difficulty, related keywords, SERP features, Google Trends, local map rankings, Google Shopping prices and app store rankings.
Overview
DataForSEO sells SEO and marketing data through a pay-as-you-go API. This integration connects an agent to your own DataForSEO account with its API login and API password, so content, SEO, ads and app marketing agents work from real numbers instead of guesses. The agent only reads data: every answer names DataForSEO as the source, gives the date of the numbers and says what the requests cost.
Skills that use this integration:
int-dataforseo: Read-only research through the DataForSEO API: Google Ads search volume, CPC and competition for up to 1,000 keywords per request, DataForSEO Labs keyword difficulty, related keywords and keyword ideas, Google SERP features (featured snippets, People Also Ask, local packs, AI Overviews), Google Trends, Google Maps rankings by coordinate (a local rank grid), Google Shopping prices and Google Play / App Store rankings.
Agents that typically enable this integration:
- Blog Content Editor: pick topics with real search volume and difficulty, and see what Google already shows for them, before drafting.
- Google Ads Manager: check search volume, CPC and competition before adding keywords.
- Custom SEO, local marketing, e-commerce and app marketing agents.
Availability
| Mode | Status | Notes |
|---|---|---|
| API Login + API Password (DataForSEO) | Available | The API login and API password from your DataForSEO dashboard. DataForSEO bills each request to your own balance (pay-as-you-go). No extra charge on the agent: like every skill, it is included in every plan. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- A DataForSEO account with balance. New accounts get a $1 trial credit; the minimum top-up is $50.
Setup
Step 1: Copy your DataForSEO API login and API password
- Sign up or sign in at app.dataforseo.com.
- Open API Access in the dashboard menu (app.dataforseo.com/api-access).
- Copy the API login. On newer accounts it is a string DataForSEO generated; on older accounts it can be your sign-up email.
- Copy the API password. It is shown for the first 24 hours after you sign up; after that, click Send by e-mail and DataForSEO mails it to your account address.
The API password is not the password you sign in to DataForSEO with. Using the sign-in password is the most common cause of a 40100 "not authorized" error.
Step 2: Save the credential to Wiro
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "dataforseo", "fieldname": "login", "fieldvalue": "YOUR_DATAFORSEO_API_LOGIN" },
{ "credentialkey": "dataforseo", "fieldname": "password", "fieldvalue": "YOUR_DATAFORSEO_API_PASSWORD" }
]
}'
Or fill it in the panel: My Agents → open agent → Connectors → DataForSEO.
Step 3: Enable the skill
DataForSEO ships available but off. Turn int-dataforseo on for the agent:
curl -X POST "https://api.wiro.ai/v1/UserAgent/SkillsApply" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"skills": { "int-dataforseo": true },
"idempotencyKey": "550e8400-e29b-41d4-a716-446655440000"
}'
Or flip the toggle in the panel under Skills (see Agent Skills).
Step 4: Start the agent
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
Credential Fields
| Field | Type | Required | Description |
|---|---|---|---|
login | string | Yes | DataForSEO API login, from the API Access page. One word with no colon. Encrypted at rest. |
password | string (secret) | Yes | DataForSEO API password, not the sign-in password. Encrypted at rest. |
Credentials schema (as returned by POST /UserAgent/Detail)
"dataforseo": {
"_connected": true,
"optional": false,
"extra": false,
"login": "your-api-login",
"password": "••••••••"
}
What the agent can pull
The agent calls the DataForSEO v3 API at https://api.dataforseo.com/v3/ with HTTP Basic auth (your API login and API password), sends a whole keyword list in one request, and checks DataForSEO's own status_code in every answer: DataForSEO can answer HTTP 200 with an error inside.
| Data | DataForSEO endpoint | How | Date the agent reports |
|---|---|---|---|
| Search volume, CPC and competition (up to 1,000 keywords) | Keywords Data: Google Ads Search Volume | Live | The 12 months the monthly average covers |
| Keyword difficulty (up to 1,000 keywords) | DataForSEO Labs: Bulk Keyword Difficulty | Live | The Labs data update date |
| Related keywords and keyword ideas | DataForSEO Labs: Related Keywords, Keyword Ideas | Live | Each keyword's last update |
| SERP features for a query | SERP: Google Organic (advanced) | Live | When DataForSEO loaded the page |
| Interest over time (up to 5 keywords) | Keywords Data: Google Trends Explore | Live | The window of the graph |
| Google Maps rank at a point, local rank grid | SERP: Google Maps (advanced) at a coordinate | Live, one request per grid point | When each point was loaded |
| Google Shopping prices | Merchant: Google Shopping Products | Posted, then collected | When DataForSEO loaded the results |
| App store rankings for a keyword | App Data: Google Play and App Store App Searches | Posted, then collected | When DataForSEO loaded the results |
| Keywords an app ranks for (United States, English) | DataForSEO Labs: Keywords For App | Live | Each ranking's last check |
Results are aggregate: keywords, volumes, ranks, prices, domains and business or app names. When DataForSEO fails, the agent says so; it never falls back to another source or to scraping Google.
Local rank grid
Google ranks local results by where the searcher is, so a business ranks differently across its area. For a local rank grid the agent runs the same Google Maps search from evenly spaced points around the business (3 x 3 by default, up to 5 x 5, at a spacing you choose), one request per point, and reports the business's rank at each point in a table laid out like the map, with its average rank and the number of points where it is in the top 3.
Posted tasks
Google Shopping and app store searches have no live mode at DataForSEO. The agent posts every query in one request, then collects each result by its task id; collecting is free for 30 days. When results are not ready within the turn, the agent lists the task ids and collects them on your next request.
Cost & billing
- DataForSEO bills each request to your own DataForSEO balance, pay-as-you-go with no subscription, and funds do not expire. The agent reports the cost DataForSEO returns with each answer. Location lookups, the balance check and collecting a posted task are free. See DataForSEO pricing for each API's rates.
- The agent: every plan includes the integration, so it changes neither the agent's price nor its credits. As with every agent turn, the work is billed on the LLM tokens it uses, from the agent's existing credits.
Troubleshooting
40100/ HTTP 401 (not authorized): The API login or API password is wrong. Copy both again from API Access; the API password is not your sign-in password.40200/40210(balance): Your DataForSEO balance is too low. Top it up in the DataForSEO dashboard.40104: Your DataForSEO account is not verified yet. Complete the verification in the DataForSEO dashboard.40207(IP not allowed): Your DataForSEO account accepts API requests only from the IP addresses on its allowlist. Clear the allowlist in the API Access section of the DataForSEO dashboard so the agent can connect.40202(rate limit): Too many requests in a minute; Google Ads volume requests are limited to 12 a minute per account. The agent retries once, then stops.- "Results are being prepared": A posted Google Shopping or app store task is still in DataForSEO's queue. Ask again in a few minutes; the agent collects it by its task id.
- Agent says "not connected" with both fields filled: The agent restarts to pick up new credentials; give it a moment after saving, then retry.
Related
Keepa Integration
Give your agent Amazon price, sales rank and offer history from Keepa, read with your own Keepa API key, so pricing, catalog and competitor agents answer with real numbers and dates.
Overview
Keepa tracks Amazon products and keeps their price, sales rank and offer history. This integration lets an agent read that history through the Keepa API with your own key: prices now, averages, the lowest and highest prices with their dates, daily or weekly price and rank tables, Amazon product search, best seller lists, categories and Keepa's product finder. It only reads data: nothing on Keepa or Amazon changes.
Skills that use this integration:
int-keepa: Read-only Keepa API calls for product price and sales rank history (with statistics), product search, best sellers, category search and lookup, and the product finder. Every answer names the source (Keepa), the marketplace and the date range, and reports the Keepa tokens left.
Agents that typically enable this integration:
- Custom pricing, catalog and Amazon seller agents that watch competitor prices and sales ranks.
- Commerce agents that run a Shopify or WooCommerce store and want Amazon price context before they reprice.
Availability
| Mode | Status | Notes |
|---|---|---|
| API Key (Keepa) | Available | Your own Keepa API access key (64 letters and digits) with an active Keepa API plan. The integration is included in every plan at no extra charge; Keepa tokens come from your Keepa plan. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- A Keepa account with an active API plan (keepa.com/api/pricing). Keepa says a Keepa Pro subscription includes a small API allowance, enough to try it; an API plan sets the rate for regular use.
Setup
Step 1: Get a Keepa API key
- Sign in at keepa.com and open the API page.
- Subscribe to an API plan. Plans differ in how many tokens they add per minute, are billed monthly by Keepa and can be canceled at any time.
- Copy your API access key (64 letters and digits) from the API page.
The key is all the agent needs: there is no app to register and no sign-in. Keep it secret, since anyone with the key can spend your tokens. You can generate a new key on the same page at any time.
Step 2: Save the credential to Wiro
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "keepa", "fieldname": "apikey", "fieldvalue": "YOUR_KEEPA_API_KEY" }
]
}'
Or fill it in the panel: My Agents → open agent → Connectors → Keepa.
A value that is not exactly 64 letters and digits is refused when you save it.
Step 3: Enable the skill
Keepa ships available but off. Turn int-keepa on for the agent:
curl -X POST "https://api.wiro.ai/v1/UserAgent/SkillsApply" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"skills": { "int-keepa": true },
"idempotencyKey": "550e8400-e29b-41d4-a716-446655440000"
}'
Or flip the toggle in the panel under Skills (see Agent Skills).
Step 4: Start the agent
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
Credential Fields
| Field | Type | Required | Description |
|---|---|---|---|
apikey |
string (secret) | Yes | Keepa API access key, exactly 64 letters and digits. Encrypted at rest. |
Credentials schema (as returned by POST /UserAgent/Detail)
"keepa": {
"_connected": true,
"optional": false,
"extra": false,
"apikey": "••••••••"
}
On a custom build with int-keepa on, optional and extra are false: Keepa is that skill's own connector.
What the agent can look up
| Request | Keepa endpoint | Keepa tokens | What comes back |
|---|---|---|---|
| Token status | /token | 0 | Tokens left, refill rate and time to the next refill. |
| Product history | /product with stats and days | 1 per product (up to 100 per call) | Prices now, 30 and 90 day averages, lowest and highest in the range with dates, lowest ever, daily or weekly tables of any price or rank series, sales rank drops, Amazon's "bought in past month" bracket. Products are found by ASIN, or by UPC, EAN, GTIN or ISBN-13. |
| Product search | /search?type=product | 10 per search | Up to 20 products in Amazon's search order (sponsored results left out), with price now and sales rank. |
| Best sellers | /bestsellers | 50 per list (0 when Keepa has no list) | The ranked ASIN list of a category or product group: by current rank, by the 30, 90 or 180 day average rank, or for a past month (last 36 months). |
| Category search and lookup | /search?type=category, /category | 1 | Category ids, names, the path to the root, product counts and average Buy Box price. |
| Product finder | /query | 10 + 1 per 100 ASINs | ASINs matching filters such as category, brand, price range, sales rank, monthly sold, or a price drop against the 90 day average. |
The Keepa options that cost extra tokens stay off unless you ask for that data:
| Option | Extra Keepa tokens | Adds |
|---|---|---|
offers | 6 per page of 10 offers found (5 when there are none), instead of the base 1 | Live marketplace offers, Buy Box history, FBA, FBM and Amazon Warehouse prices, rating and review history |
buybox | 2 per product | Buy Box price history and Buy Box statistics |
stock | 2 per product, when stock data comes back | Stock levels |
rating | up to 1 per product | Rating and review count history |
historical-variations | 1 per product with a parent ASIN | Variations that are no longer listed |
Supported marketplaces
| Domain id | Marketplace | Currency |
|---|---|---|
| 1 | amazon.com | USD |
| 2 | amazon.co.uk | GBP |
| 3 | amazon.de | EUR |
| 4 | amazon.fr | EUR |
| 5 | amazon.co.jp | JPY |
| 6 | amazon.ca | CAD |
| 8 | amazon.it | EUR |
| 9 | amazon.es | EUR |
| 10 | amazon.in | INR |
| 11 | amazon.com.mx | MXN |
| 12 | amazon.com.br | BRL |
These are all the marketplaces Keepa covers. Amazon.com.tr (Türkiye) is not supported, and neither are amazon.com.au, amazon.nl, amazon.se, amazon.pl, amazon.com.be, amazon.ae, amazon.sa, amazon.sg and amazon.eg. Asked about one of them, the agent says Keepa does not cover it.
How the agent reads Keepa data
- Time: Keepa stores minutes since its own epoch. The agent converts them to UTC dates: Unix milliseconds = (Keepa time + 21564000) × 60000.
- Prices are integers in the currency's smallest unit (cents, pence, paise; yen have none).
-1means there was no offer at that time, never a price of zero. - Sales rank is the rank in the product's main category; lower is better. History holds a point only when a value changed.
- New and Used prices: until 2026-02-22 Keepa recorded the lowest listing price, and from 2026-02-23 the lowest price including shipping. The agent says so when a range spans that date.
- History series the agent can tabulate include Amazon's own offer, the lowest New and Used prices, the sales rank, the list price, offer counts, and (with the matching option) the Buy Box, FBA, FBM and Warehouse prices, rating and reviews.
- Every answer names the source, the marketplace and the date range, for example "Source: Keepa · amazon.de · 2026-08-23 to 2026-11-21 (UTC)", followed by the tokens used and left.
Keepa tokens & billing
- Keepa plans add a fixed number of tokens per minute. Unused tokens expire after 60 minutes, so a plan holds at most one hour's worth. Keepa bills the plan monthly to your Keepa account.
- Before a costly call (a search, a best seller list, the product finder) the agent checks your balance; when the call costs more than you have left, it says so and asks first in chat, and skips it in a scheduled task.
- When tokens run out, Keepa answers HTTP 429. The agent stops and says in one sentence when the next call can run; it never retries in a loop.
- Billing on Wiro: every plan includes the integration, so it changes neither the agent's price nor its credits. As with every agent turn, its work is billed on the LLM tokens it uses, from the agent's existing credits.
Troubleshooting
- 402 "No active API plan found": the key is unknown or its Keepa plan has ended. Check the plan on the Keepa API page, or save the current key again if you generated a new one.
- 400 invalidParameter: a request parameter was wrong; the error names it. A rejected
keymeans the saved key is not the one Keepa issued. - 429: out of Keepa tokens. Wait for the refill the agent names, or move to a larger Keepa plan.
- 500: a Keepa error. The agent retries once, then reports that Keepa is not answering.
- Empty best seller list: Keepa has no list for that category on that marketplace; no tokens were used.
- A marketplace is "not covered": Keepa has no data for it (for example amazon.com.tr).
- Agent says "not connected" with the key filled: the agent restarts to pick up new credentials; give it a moment after saving, then retry.
Related
- Agent Credentials & OAuth
- Agent Skills
- Shopify Skills / WooCommerce Skills: your own store's catalog and prices
- Merchant Center Skills: Google Shopping product feeds
RevenueCat Integration
Connect your agent to RevenueCat subscription analytics: MRR, revenue, active subscriptions and trials, churn, conversion, retention and LTV charts, read with your own RevenueCat secret API key. Aggregate numbers only, never customer records.
Overview
RevenueCat runs in-app subscriptions across the App Store, Google Play, Stripe, Amazon and its own web billing. This integration lets an agent read your project's aggregate subscription numbers through the RevenueCat REST API v2: the same overview cards and charts the RevenueCat dashboard shows.
Skills that use this integration:
int-revenuecat: Read-only RevenueCat reporting. Overview metrics (MRR, active subscriptions, active trials, revenue, new and active customers), revenue for any date range, charts (revenue, MRR, ARR, churn, trials, trial and paid conversion, retention, LTV, refunds, cohorts) by date range and resolution with the filters and segments each chart offers, and the project's apps, products, offerings and entitlements.
Agents that typically enable this integration:
- Custom app-growth and reporting agents that answer questions about subscription revenue.
- Any agent that reports on an app's subscription business next to its ads or store numbers.
Availability
| Mode | Status | Notes |
|---|---|---|
| Secret API key (RevenueCat REST API v2) | Available | One read-only v2 secret key per agent. It reads the RevenueCat project the key belongs to. No extra charge: like every skill, it is included in every plan. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- A RevenueCat project, and a project admin who can create its API keys.
Setup
Step 1: Create a RevenueCat v2 secret key
- Sign in to RevenueCat and open your project.
- Open Project settings, then API keys.
- Click + New secret API key, give it a name (for example
Wiro agent) and choose version V2. - Set its permissions: read-only for Charts & Metrics (overview and charts) and Project configuration, and no access to Customer information.
- Create the key and copy it. It starts with
sk_.
A v1 key does not work with the v2 API. The agent never reads customer data, so the key needs no Customer information access. Deleting the key in RevenueCat cuts the agent off immediately.
Step 2: Save the credential to Wiro
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "revenuecat", "fieldname": "apikey", "fieldvalue": "sk_YOUR_REVENUECAT_KEY" }
]
}'
Or fill it in the panel: My Agents → open agent → Connectors → RevenueCat.
Step 3: Turn on the skill
RevenueCat Metrics ships available but off. Turn int-revenuecat on for the agent:
curl -X POST "https://api.wiro.ai/v1/UserAgent/SkillsApply" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"skills": { "int-revenuecat": true },
"idempotencyKey": "550e8400-e29b-41d4-a716-446655440000"
}'
Or flip the toggle in the panel under Skills (see Agent Skills).
Step 4: Start the agent
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
Credential Fields
| Field | Type | Required | Description |
|---|---|---|---|
apikey | string (secret) | Yes | RevenueCat REST API v2 secret key, starting with sk_. Encrypted at rest. |
Credentials schema (as returned by POST /UserAgent/Detail)
"revenuecat": {
"_connected": true,
"optional": false,
"extra": false,
"apikey": "••••••••"
}
On an agent you build yourself with int-revenuecat on, the card is required (optional: false): the agent's setup is complete once the key is saved.
What the agent reports
| Source | What it gives |
|---|---|
| Overview | Active Trials, Active Subscriptions and MRR as of now; Revenue, New Customers and Active Customers for the last 28 days. |
| Revenue | Gross revenue, revenue net of taxes, or proceeds (after taxes and store commissions) for any date range. |
| Charts | revenue, mrr, arr, actives, trials, churn, trial_conversion_rate, initial_conversion, conversion_to_paying, subscription_retention, ltv_per_customer, ltv_per_paying_customer, cohort_explorer, refund_rate and the rest of RevenueCat's charts, by day, week, month, quarter or year, with the filters and segments each chart offers (such as country, store, product or app). |
| Configuration | Apps, products, offerings (and which one is current) and entitlements. |
Every report names its source and its date range. Chart dates are in UTC, as in RevenueCat's charts. A partial period (the current one, or a first period that starts mid-way) is called out and left out of trends, and money is shown in the currency RevenueCat returns (USD unless you ask for another).
Privacy
The agent reads aggregate numbers only. It never reads customers, subscribers, subscriptions, purchases, invoices, audiences or collaborators, and requests to customer endpoints are refused. A question about one customer is declined.
Billing
Every plan includes the integration, so it changes neither the agent's price nor its credits. As with every agent turn, reports are billed on the LLM tokens they use, from the agent's existing credits.
Rate limits
RevenueCat allows each key 25 Charts & Metrics requests a minute (overview, revenue and charts) and 60 Project configuration requests a minute. The agent keeps its calls few; when RevenueCat asks it to slow down, it waits and retries once.
Troubleshooting
- 401: The key was revoked or mistyped, or it is a v1 key. Create a new v2 secret key and save it again.
- 403: The key lacks a permission. Give it read access to Charts & Metrics and Project configuration.
- 429: RevenueCat's rate limit. The agent waits the time RevenueCat names and retries once.
- Numbers differ from App Store Connect or Google Play: RevenueCat counts differently; for example, Google counts trials as active subscriptions and RevenueCat does not.
- Agent says "not connected" with the key filled: The agent restarts to pick up new credentials; give it a moment after saving, then retry.
Related
Adapty Integration
Connect your agent to Adapty subscription analytics: revenue, MRR, ARR, subscriptions, trials, conversions, funnels, retention, LTV and install cohorts, read with your app's Adapty secret API key. Aggregate numbers only, never user profiles.
Overview
Adapty runs in-app subscriptions and paywalls for mobile apps. This integration lets an agent read the numbers the Adapty Dashboard's analytics show for one app, through Adapty's Analytics Export API.
Skills that use this integration:
int-adapty: Read-only Adapty reporting. Charts (revenue, proceeds and net revenue, MRR, ARR, ARPU, ARPPU, active and new subscriptions, trials, cancellations, expirations, refunds, installs), conversion rates, funnels, retention, LTV and install cohorts, by date range with an optional comparison period, filters (country, store, product, segment, attribution, offer) and one grouping per report.
Agents that typically enable this integration:
- Custom app-growth and reporting agents that answer questions about subscription revenue.
- Any agent that reports on an app's subscription business next to its ads or store numbers.
Availability
| Mode | Status | Notes |
|---|---|---|
| Secret API key (Adapty Analytics Export API) | Available | One Adapty secret key per agent. Adapty keys belong to one app, so the agent reports on that app. No extra charge: like every skill, it is included in every plan. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- An Adapty app with subscription data, and access to its App settings.
Setup
Step 1: Copy the app's Adapty secret key
- Sign in to the Adapty Dashboard and pick the app.
- Open App settings and stay on the General tab.
- In API keys, copy the Secret key. It starts with
secret_live_.
The agent uses the key only with Adapty's Analytics Export API and reads aggregate analytics only, never user profiles. To cut the agent off, click Generate new key in App settings and delete the old key.
Step 2: Save the credential to Wiro
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "adapty", "fieldname": "apikey", "fieldvalue": "secret_live_YOUR_ADAPTY_KEY" }
]
}'
Or fill it in the panel: My Agents → open agent → Connectors → Adapty.
Step 3: Turn on the skill
Adapty Analytics ships available but off. Turn int-adapty on for the agent:
curl -X POST "https://api.wiro.ai/v1/UserAgent/SkillsApply" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"skills": { "int-adapty": true },
"idempotencyKey": "550e8400-e29b-41d4-a716-446655440000"
}'
Or flip the toggle in the panel under Skills (see Agent Skills).
Step 4: Start the agent
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
Credential Fields
| Field | Type | Required | Description |
|---|---|---|---|
apikey | string (secret) | Yes | The app's Adapty secret API key, starting with secret_live_. Encrypted at rest. |
Credentials schema (as returned by POST /UserAgent/Detail)
"adapty": {
"_connected": true,
"optional": false,
"extra": false,
"apikey": "••••••••"
}
On an agent you build yourself with int-adapty on, the card is required (optional: false): the agent's setup is complete once the key is saved.
What the agent reports
| Report | What it gives |
|---|---|
| Charts | revenue (with proceeds and net revenue), mrr, arr, arpu, arppu, subscriptions_active, subscriptions_new, subscriptions_renewal_cancelled, subscriptions_expired, trials_active, trials_new, trials_renewal_cancelled, trials_expired, grace_period, billing_issue, refund_events, refund_money, non_subscriptions and installs, by day, week, month, quarter or year. |
| Conversion | Conversion rates between subscription states, such as paid to more than 6 months. |
| Funnel | Users at each stage from install and paywall view to trial, paid and renewals, with drop-off. |
| Retention | Retention period by period, counted from the purchase or from the trial. |
| LTV | Realized lifetime value on revenue, proceeds and net revenue. |
| Cohorts | Install-date cohorts: installs, subscribers, revenue, ARPU and ARPPU per period, with Adapty's predictions. |
Every report can take a comparison period, filters (country, store, store product, subscription duration, offer, attribution, and Adapty segment, audience, paywall, placement or flow ids) and one grouping. Money is in USD, as Adapty exports it. Every report names its source and its date range; chart revenue counts on the day of each transaction, and cohort revenue on each user's install date.
Privacy
The agent reads aggregate analytics only. It uses the key only with Adapty's Analytics Export API, never Adapty's server-side API, so it never reads user profiles. A question about one user is declined.
Billing
Every plan includes the integration, so it changes neither the agent's price nor its credits. As with every agent turn, reports are billed on the LLM tokens they use, from the agent's existing credits.
Rate limits
Adapty allows 2 requests a second per app, shared by all of the app's keys. The agent sends its calls one after another; when Adapty asks it to slow down, it waits about a minute and retries once.
Troubleshooting
- 401: The key was replaced or mistyped. Copy the app's current secret key from App settings and save it again.
- 400: A filter or option Adapty does not accept, such as a product id without its store (
app_store:premium_monthly). The agent reads Adapty's message and fixes the request once. - 429: Adapty's rate limit. The agent waits about a minute and retries once.
- Numbers for another app: One key reads one app. Connect that app's key on another agent.
- Agent says "not connected" with the key filled: The agent restarts to pick up new credentials; give it a moment after saving, then retry.
Related
HubSpot Integration
Connect your agent to HubSpot for contact, deal, and engagement management via the HubSpot CRM API.
Overview
The HubSpot integration uses HubSpot's OAuth 2.0.
Skills that use this integration:
int-hubspot-crm: Contact/deal CRUD, note and task creation, sequence enrollmentutil-newsletter-compose: optional; uses HubSpot as an ESP when enabled alongside
Agents that typically enable this integration:
- Lead Generation Manager
- Newsletter Manager (HubSpot as ESP)
- Any custom agent with CRM capabilities
Availability
| Mode | Status | Notes |
|---|---|---|
"wiro" |
Available | One-click connect using Wiro's HubSpot app. |
"own" |
Available | Your own HubSpot developer app. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- A HubSpot account the connecting user is an admin of.
- (Own mode) A HubSpot developer account (developers.hubspot.com).
- An HTTPS callback URL.
Wiro Mode
Call OAuthConnect with credentialkey: "hubspot" and without authmethod, redirect, parse hubspot_connected=true&hubspot_portal=<id>&hubspot_name=<name>.
Complete Integration Walkthrough: Own Mode
Step 1: Create a HubSpot App
- developers.hubspot.com → sign in → Create app.
- Set App name and App description (shown on consent).
Step 2: Configure Auth
- Open the Auth tab.
-
Redirect URL:
https://api.wiro.ai/v1/UserAgentOAuth/HubSpotCallback -
Scopes: Wiro requests a fixed scope string plus optional_scopes. Enable all of the following in your HubSpot app's Auth tab:
Required
scope(mandatory: OAuth fails if any is missing):crm.objects.contacts.readcrm.objects.contacts.writecrm.lists.readcrm.lists.writeoauth
optional_scope(granted on consent if enabled, otherwise skipped, and Wiro doesn't fail if missing):crm.objects.companies.readcrm.objects.companies.writecrm.objects.deals.readcrm.objects.deals.writecrm.objects.owners.readcrm.schemas.contacts.readcontenttransactional-emailfiles
- Save.
Wiro's authorize URL is built with this exact scope list, so you cannot customize it per integration. Enabling additional scopes in your HubSpot app beyond this set has no effect (Wiro won't request them). If a required scope is missing from your app's configuration, the consent screen will error.
Step 3: Copy Client ID and Client Secret
Auth tab → copy Client ID and Client Secret.
Step 4: Save credentials to Wiro
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "hubspot", "fieldname": "clientid", "fieldvalue": "YOUR_HUBSPOT_CLIENT_ID" },
{ "credentialkey": "hubspot", "fieldname": "clientsecret", "fieldvalue": "YOUR_HUBSPOT_CLIENT_SECRET" },
{ "credentialkey": "hubspot", "fieldname": "authmethod", "fieldvalue": "own" }
]
}'
Step 5: Initiate OAuth
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "hubspot",
"redirecturl": "https://your-app.com/settings/integrations",
"authmethod": "own"
}'
Response:
{
"result": true,
"authorizeUrl": "https://app.hubspot.com/oauth/authorize?client_id=...&redirect_uri=...&scope=...&state=...",
"flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19",
"errors": []
}
Step 6: Handle the callback
Wiro exchanges the code, then calls GET https://api.hubapi.com/oauth/v1/access-tokens/<access_token> to fetch hub_id (portalid) and hub_domain (portalname). When HubSpot returns no hub_domain, portalname is the response's user value, the email of the user who connected. If this lookup fails, the connection still succeeds and the redirect carries only hubspot_connected=true.
Success URL:
https://your-app.com/settings/integrations?hubspot_connected=true&hubspot_portal=12345678&hubspot_name=My%20Workspace
Step 7: Verify and Start
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthStatus" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "hubspot"
}'
Response:
{
"result": true,
"connected": true,
"accounts": [
{ "id": "Acme Corp HubSpot", "name": "Acme Corp HubSpot" }
],
"connectedat": "2026-04-17T12:00:00.000Z",
"tokenexpiresat": "2026-04-17T12:30:00.000Z",
"errors": []
}
HubSpot tokens expire in 30 minutes. Wiro maintains the connection automatically while the agent is running. If authorization is revoked, reconnect HubSpot through the OAuth flow.
Note: For HubSpot, the unified OAuthStatus mirrors the saved portalname into both accounts[0].id and accounts[0].name (HubSpot has no separate picker: there's exactly one portal per OAuth grant). The numeric portalid is captured by HubSpotCallback as hubspot_portal=<id> on the redirect URL but is not re-surfaced by OAuthStatus.
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
API Reference
POST /UserAgentOAuth/OAuthConnect
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
credentialkey |
string | Yes | "hubspot". |
redirecturl |
string | Yes | Any HTTPS URL you control; the browser returns there after consent. http://localhost and http://127.0.0.1 also work for development. |
authmethod |
string | No | "wiro" (default) or "own". |
GET /UserAgentOAuth/HubSpotCallback
Server-side endpoint invoked by HubSpot with code and state. You don't call it. You only handle the final redirect back to your redirecturl, which carries hubspot_connected=true&hubspot_portal=<id>&hubspot_name=<name> or hubspot_error=<code>. The callback path is per-provider: HubSpot's stays HubSpotCallback.
POST /UserAgentOAuth/OAuthStatus
Body: { useragentguid, credentialkey: "hubspot" }. Response: connected, accounts: [{id, name}] (1-element with the saved portalname mirrored into both id and name), connectedat, tokenexpiresat (~30 min).
POST /UserAgentOAuth/OAuthDisconnect
Body: { useragentguid, credentialkey: "hubspot" }. Clears HubSpot credentials (no remote revoke).
Token lifecycle
Wiro renews the HubSpot token while the agent is running and when it starts. OAuthStatus reports connected: false and an empty accounts array as soon as the stored token has expired, so an agent stopped for more than 30 minutes shows false while its authorization is still valid. Start the agent and check again. Reconnect through OAuth only if HubSpot revoked the authorization or the status stays false while the agent runs.
Using the Skill
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"skillkey": "lead-enrichment",
"enabled": true,
"interval": "0 */4 * * *",
"value": "Enrich new contacts with company information"
}'
Troubleshooting
| Error code | Meaning | What to do |
|---|---|---|
missing_params |
The callback was opened without an OAuth state. The browser ends on the API's own neutral page, not on your redirecturl. |
Don't open the callback URL directly. Start a new flow with OAuthConnect. |
authorization_denied |
The user cancelled, or HubSpot returned an error instead of an authorization code. | Verify the scope list in the HubSpot app's Auth tab. |
session_expired |
State cache expired (15 min TTL). | Restart the OAuth flow. |
flow_replaced |
A newer sign-in for the same agent and credential replaced this one, whoever started it, so nothing from it was saved. | Use the newer sign-in, or start again with OAuthConnect. |
token_exchange_failed |
Wrong Client Secret or redirect URI mismatch. | Re-copy; verify URL. |
useragent_not_found |
The agent was deleted, or is no longer owned by the account that started the flow, before HubSpot returned. | Start again with OAuthConnect for an existing agent. |
HubSpot credentials not configured |
Returned in OAuthConnect's errors[] when authmethod: "own" but clientid / clientsecret are missing. |
UserAgent/CredentialUpsert with clientid + clientsecret. |
internal_error |
Server error. | Retry; contact support. |
403 Forbidden on API calls
Usually a missing scope. Look up the specific HubSpot API endpoint you're hitting, add the required scope in your app's Auth tab, then disconnect and reconnect (scope changes require re-consent).
Token expired error at runtime
HubSpot's 30-minute token lifetime makes continuous authorization important. If you see a token-expired error:
- The agent is stopped (status 0/1/6). Start it:
POST /UserAgent/Start. - The authorization may have been revoked in HubSpot's app management UI. Reconnect the user.
- If the agent is running and reconnection does not resolve it, contact Wiro support.
Multi-Tenant Architecture
- One HubSpot developer app per product: submit to the HubSpot App Marketplace for listed visibility, or stay private.
- One Wiro agent instance per customer.
- Portal IDs are unique per customer's HubSpot account.
- Per-app rate limits apply: see HubSpot's API usage guidelines.
Related
Mailchimp Integration
Connect your agent to Mailchimp for audience and campaign management. Supports OAuth 2.0 or direct API key.
Overview
The Mailchimp integration supports three connection modes: Wiro's shared OAuth app, your own OAuth app, or a direct API key with no OAuth.
Skills that use this integration:
int-mailchimp-email: Audience and campaign managementutil-newsletter-compose: optional; uses Mailchimp as an ESP when enabled alongside. Newsletter Manager has it on; on other agents turn onutil-newsletter-composeyourself. Mailchimp alone adds no newsletter tasks.
Agents that typically enable this integration:
- Newsletter Manager
Availability
| Mode | Status | Notes |
|---|---|---|
"wiro" |
Available | OAuth with Wiro's shared Mailchimp app. |
"own" |
Available | OAuth with your own Mailchimp registered app. |
| API key | Available | Paste a server-scoped Mailchimp API key directly, with no OAuth. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- A Mailchimp account.
- (Own OAuth mode) A registered Mailchimp app (admin.mailchimp.com/account/oauth2_client).
- (API-key mode) A server-scoped Mailchimp API key.
Option A: OAuth (Wiro or Own Mode)
Own Step 1: Register a Mailchimp app
- admin.mailchimp.com/account/oauth2_client.
- Register and manage your apps.
- Fill App name, Description, Company, App website.
-
Under Redirect URI, add:
https://api.wiro.ai/v1/UserAgentOAuth/MailchimpCallback - Save; copy Client ID and Client Secret.
No OAuth scopes to configure. Mailchimp's OAuth 2.0 doesn't use scopes: connected apps get full account access. Wiro's authorizeUrl omits any scope parameter.
Own Step 2: Save credentials
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "mailchimp", "fieldname": "clientid", "fieldvalue": "YOUR_MAILCHIMP_CLIENT_ID" },
{ "credentialkey": "mailchimp", "fieldname": "clientsecret", "fieldvalue": "YOUR_MAILCHIMP_CLIENT_SECRET" },
{ "credentialkey": "mailchimp", "fieldname": "authmethod", "fieldvalue": "own" }
]
}'
clientid and clientsecret are required. CredentialUpsert refuses an empty value with Client ID is required or Client Secret is required, and then saves no field of that request.
OAuth Step 3: Initiate
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "mailchimp",
"redirecturl": "https://your-app.com/settings/integrations",
"authmethod": "own"
}'
Response:
{
"result": true,
"authorizeUrl": "https://login.mailchimp.com/oauth2/authorize?response_type=code&client_id=...&redirect_uri=...&state=...",
"flowid": "4b1f0c7a9e2d4c1b8a7f6e5d4c3b2a19",
"errors": []
}
No scope parameter: Mailchimp OAuth doesn't use scopes.
Starting OAuth removes a saved API key. OAuthConnect with "wiro" or "own" clears apikey first, so an API-key setup stops working even if the OAuth start fails or the user never finishes consent.
OAuth Step 4: Handle the callback
Wiro exchanges the code via POST https://login.mailchimp.com/oauth2/token, then fetches metadata from GET https://login.mailchimp.com/oauth2/metadata with Authorization: OAuth <access_token> to retrieve the server prefix (dc) and account name. The connection needs the server prefix: if the metadata has no server prefix, nothing is saved and the redirect carries mailchimp_error=token_exchange_failed.
Success URL:
https://your-app.com/settings/integrations?mailchimp_connected=true&mailchimp_account=Your%20Company
OAuth Step 5: Verify
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/OAuthStatus" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"credentialkey": "mailchimp"
}'
Response:
{
"result": true,
"connected": true,
"accounts": [
{ "id": "Your Company", "name": "Your Company" }
],
"connectedat": "2026-04-17T12:00:00.000Z",
"errors": []
}
Mailchimp tokens don't expire. OAuthStatus responses leave tokenexpiresat empty for Mailchimp. Reconnect only if the authorization is revoked or otherwise invalidated.
Option B: Direct API Key (No OAuth)
For server-side agents where OAuth is overkill:
Step 1: Get a Mailchimp API Key
- Sign in → Profile → Extras → API keys.
- Create A Key, name it, copy the value. The key ends in a datacenter prefix like
-us14.
Step 2: Save to Wiro
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "mailchimp", "fieldname": "authmethod", "fieldvalue": "api_key" },
{ "credentialkey": "mailchimp", "fieldname": "apikey", "fieldvalue": "abcdef1234567890-us14" }
]
}'
apikey is required. An empty value is refused with API Key (alternative) is required, and then no field of that request is saved. To remove a saved key, call OAuthDisconnect in API-key mode.
No further OAuth step. The agent uses the API key directly.
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
API Reference
POST /UserAgentOAuth/OAuthConnect
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
credentialkey |
string | Yes | "mailchimp". |
redirecturl |
string | Yes | Any HTTPS URL you control; the browser returns there after consent. http://localhost and http://127.0.0.1 also work for development. |
authmethod |
string | No | "wiro" (default) or "own". |
GET /UserAgentOAuth/MailchimpCallback
Server-side endpoint invoked by Mailchimp with code and state. You don't call it. You only handle the final redirect back to your redirecturl, which carries mailchimp_connected=true&mailchimp_account=<name> or mailchimp_error=<code>. The callback path is per-provider: Mailchimp's stays MailchimpCallback.
POST /UserAgentOAuth/OAuthStatus
Body: { useragentguid, credentialkey: "mailchimp" }. Response: connected, accounts: [{id, name}] (1-element with the connected account name), connectedat. tokenexpiresat is empty because Mailchimp tokens don't expire.
API key-only mode caveat: connected is computed from authmethod in {wiro, own} and a non-empty accesstoken. If you set up Mailchimp via direct API key (no OAuth), authmethod is "api_key" and accesstoken is empty, so OAuthStatus.connected returns false, even though the agent runtime is fully functional (the int-mailchimp-email skill reads
the API key directly). Don't use OAuthStatus.connected as the source of truth for API key setups; instead, check that credentials.mailchimp.apikey is non-empty in POST /UserAgent/Detail.
POST /UserAgentOAuth/OAuthDisconnect
Body: { useragentguid, credentialkey: "mailchimp" }. Clears the token, the account name and the server prefix (no remote revoke, since Mailchimp doesn't expose a revoke endpoint for OAuth tokens). clientid and clientsecret stay saved. In API-key mode, Disconnect also clears apikey; an OAuth disconnect keeps it.
Token lifecycle
Mailchimp OAuth tokens do not expire. Reconnect only if the user revokes the authorization or the connection is otherwise invalidated.
Using the Skill
Once Mailchimp is connected (OAuth or API key), the agent's scheduled tasks use the int-mailchimp-email platform skill for audience and campaign operations. Adjust the cron of the built-in cs-cron-newsletter-subscriber-scanner task (Newsletter Manager) by calling POST /UserAgent/CustomSkillUpsert with enabled and interval only. Scheduled task bodies are template-controlled and value is silently ignored for bundled tasks:
curl -X POST "https://api.wiro.ai/v1/UserAgent/CustomSkillUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"skillkey": "cs-cron-newsletter-subscriber-scanner",
"enabled": true,
"interval": "0 10 * * *"
}'
To change what the scanner checks (target lists, bounce thresholds, tone, audience segments), edit the paired preference skill newsletter-strategy instead (see Agent Skills → Updating Preference Skills).
Troubleshooting
| Error code | Meaning | What to do |
|---|---|---|
authorization_denied |
User cancelled. | Retry. |
session_expired |
State cache expired (15 min). | Restart. |
flow_replaced |
A newer sign-in for the same agent and credential replaced this one, whoever started it, so nothing from it was saved. | Use the newer sign-in, or start again with OAuthConnect. |
token_exchange_failed |
Wrong Client Secret, a redirect URI mismatch, or no server prefix in the account details Mailchimp sent. Nothing is saved. | Re-copy; verify URL; connect again. |
useragent_not_found |
The agent was deleted, or is no longer owned by the account that started the flow, before Mailchimp returned. | Start again with OAuthConnect for an existing agent. |
Mailchimp credentials not configured |
Returned in OAuthConnect's errors[] when authmethod: "own" but clientid / clientsecret are missing. |
Update with POST /UserAgent/CredentialUpsert. |
internal_error |
Server error. | Retry; contact support. |
API calls fail with 401
- OAuth: stored token is invalid; disconnect and reconnect.
- API key: wrong key or datacenter suffix stripped. Paste the full key including
-us14.
Multi-Tenant Architecture
- One Mailchimp registered app per product in own-OAuth mode.
- API-key mode is simplest for tenants who prefer a single-purpose key.
- One Wiro agent instance per customer.
- Mailchimp rate limits are per-datacenter and per-account (~10 concurrent connections).
Related
Google Drive Integration
Connect your agent to Google Drive for reading, writing, and managing files in selected folders.
Overview
The Google Drive integration uses a Google Cloud service account with folder access delegated from your Drive. You create the service account in your own Google Cloud project, share your Drive folders with the service account email, and the agent accesses only those shared folders.
Skills that use this integration:
int-google-drive: Read files, write outputs, manage folders in selected Drive folders
Agents that typically enable this integration:
- Google Ads Manager (creative assets for campaigns)
- Meta Ads Manager (creative assets for campaigns)
- TikTok Ads Manager (creative assets for campaigns)
- Social Manager (post-ready media library)
Availability
| Mode | Status | Notes |
|---|---|---|
| Service Account JSON | Available | Google Cloud service account with Drive API access. Folders shared by the user. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- A Google account with a Drive you want the agent to access.
- A Google Cloud project to host the service account.
Setup
Step 1: Enable the Google Drive API
Google Cloud Console → select project → APIs & Services → Library → Google Drive API → Enable.
If your agent will also read/write Google Docs or Sheets, enable those APIs as well:
- Google Sheets API
- Google Docs API
Step 2: Create a service account
- IAM & Admin → Service accounts → Create service account.
- Name (e.g. "wiro-drive-agent").
- Skip role grant → Done.
- Open the service account → Keys → Add key → Create new key → JSON. Download.
- Note the service account email from the account details page (format:
wiro-drive-agent@YOUR-PROJECT.iam.gserviceaccount.com).
Tip: In My Agents → open your agent → Connectors, upload the JSON and your service account email will appear with a Copy button.
Step 3: Share your Drive folders with the service account
For each folder you want the agent to access:
- Open Google Drive.
- Right-click the folder → Share.
- Paste the service account email from Step 2.
- Set role to Editor (if the folder lives in your My Drive) or Content manager (if the folder lives in a Shared Drive).
- Click Send.
Copy each folder's ID from its Drive URL: the part after /folders/. Example: from https://drive.google.com/drive/folders/1BxiMVs0XRA5nFMdKvBd the ID is 1BxiMVs0XRA5nFMdKvBd.
Google Workspace users: If you use a Shared Drive (Team Drive), add the service account as a member of the shared drive instead of sharing individual folders. All folders within the shared drive become accessible.
Step 4: Base64-encode the JSON
# Linux
base64 -w 0 drive-service-account.json > drive-sa.b64
# macOS
base64 -b 0 drive-service-account.json > drive-sa.b64
Step 5: Save to Wiro
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "google-drive", "fieldname": "serviceaccountjson", "fieldvalue": "eyJ0eXBlIjoic2VydmljZV9hY2NvdW50Ii..." },
{ "credentialkey": "google-drive", "parentfield": "folders", "ordinal": 0, "fieldname": "id", "fieldvalue": "1BxiMVs0XRA5nFMdKvBd" },
{ "credentialkey": "google-drive", "parentfield": "folders", "ordinal": 0, "fieldname": "name", "fieldvalue": "Creatives" },
{ "credentialkey": "google-drive", "parentfield": "folders", "ordinal": 1, "fieldname": "id", "fieldvalue": "2CyiNWt1YSB6oGNeL" },
{ "credentialkey": "google-drive", "parentfield": "folders", "ordinal": 1, "fieldname": "name", "fieldvalue": "Ad Assets" }
]
}'
| Field | Type | Description |
|---|---|---|
serviceaccountjson |
string | Base64-encoded service account JSON key. |
folders |
array | Array of { "id": string, "name": string } objects the agent should scan. name is the human-readable label, which the agent uses when reporting back to the operator ("scanned the Creatives folder..."); id is the Drive folder ID used in API calls. Pass an empty array to clear. |
Step 5b (optional): Discover folders via API
If you don't already have folder IDs from Step 3, or you want to verify that the service account has access to the expected folders before saving them, call the folder discovery endpoint. This is the same endpoint the Wiro Dashboard uses for its folder picker.
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/GoogleDriveListFolders" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"serviceaccountjson": "eyJ0eXBlIjoic2VydmljZV9hY2NvdW50Ii..."
}'
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance GUID. |
serviceaccountjson |
string | No | Base64-encoded SA JSON. Useful for previewing before saving. If omitted, or sent as "••••••••" (how UserAgent/Detail shows a saved one), the endpoint uses whatever JSON was already saved to the agent via Step 5. |
parentid |
string | No | Parent folder ID for subfolder listing. Omit (or pass empty) to list folders shared at the root level with the service account (Drive's sharedWithMe filter). When provided, returns folders whose parent is the given id. Drive's permission cascade lets the service account see children of any root it has access to, even if those children aren't shared individually. |
Response:
{
"result": true,
"serviceAccountEmail": "wiro-drive-agent@your-project.iam.gserviceaccount.com",
"parentId": "",
"folders": [
{ "id": "1BxiMVs0XRA5nFMdKvBd", "name": "Creatives", "modifiedTime": "2026-04-10T12:34:00Z", "ownerName": "design@yourcompany.com" },
{ "id": "2CyiNWt1YSB6oGNeL", "name": "Ad Assets", "modifiedTime": "2026-04-12T09:12:00Z", "ownerName": "design@yourcompany.com" }
]
}
parentId echoes back whatever you passed in ("" for a root listing) so the caller can verify it landed on the level it expected. This is useful when the user navigates two levels deep quickly and you need to discard out-of-order responses. Only folders explicitly shared with the SA email (as Editor or Content manager, see Step 3) are returned at the root. Take the id values from the folders you want the agent to scan and pass them as the folders array in your final UserAgent/CredentialUpsert call (using parentfield: "folders" + ordinal per entry).
Listing subfolders
Use parentid to walk down the folder tree: first call without parentid to enumerate the roots the service account can see, then call again with parentid: "<root-id>" to list its children, and so on. The Wiro Dashboard's folder picker uses this exact pattern.
curl -X POST "https://api.wiro.ai/v1/UserAgentOAuth/GoogleDriveListFolders" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"parentid": "1BxiMVs0XRA5nFMdKvBd"
}'
The response shape is identical: folders[] now contains the immediate children of 1BxiMVs0XRA5nFMdKvBd, and parentId echoes back "1BxiMVs0XRA5nFMdKvBd" so you can keep the picker UI in sync if the user clicks between levels quickly.
Two equivalent ways to run Steps 5 and 5b
- Upfront: you already know the folder IDs from Step 3. Call
UserAgent/CredentialUpsertonce with bothserviceaccountjsonandfolders. - Discovery (matches the Dashboard flow): call
UserAgent/CredentialUpsertfirst with justserviceaccountjson(leavefoldersempty), then callUserAgentOAuth/GoogleDriveListFoldersto enumerate what the SA can see, then callUserAgent/CredentialUpsertagain with the pickedfoldersarray. The Dashboard uses this pattern: JSON upload renders the service account email, the user shares folders with it in Drive, and the folder picker lists the results. Through the API, read that email fromUserAgent/Detailonce the JSON is saved:credentials["google-drive"]._service_account_email.serviceaccountjson, returned to the agent's owner and team admins.
Step 6: Start the agent
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
Runtime Behavior
When the int-google-drive skill is enabled, the agent works only in the folders saved under folders[], each with its id and name; it can address a folder by either. With no folder saved, it has no Drive folder to work in.
Auth: the agent mints a short-lived OAuth access token from the service account you saved and sends it as Authorization: Bearer. Tokens expire after an hour, so a fresh one is minted before each API session.
Base URLs:
- Drive API:
https://www.googleapis.com/drive/v3/... - Sheets API:
https://sheets.googleapis.com/v4/... - Docs API:
https://docs.googleapis.com/v1/...
All list/get/upload calls pass supportsAllDrives=true + includeItemsFromAllDrives=true, so Shared Drives are supported automatically.
Files created by the agent
When the agent creates a file inside a user-shared folder, the file is owned by the service account, not the user. The user can see the file via folder permission inheritance, but may see it as "view only". To give the user write access on files the agent creates (role writer in the Drive API, shown as Editor in My Drive or Content manager in a Shared Drive), the skill grants permissions programmatically via POST /drive/v3/files/{fileId}/permissions. See the int-google-drive skill for details.
Troubleshooting
- 403 "The user does not have sufficient permissions for file": The folder hasn't been shared with the service account, or the service account was given a read-only role (Viewer / Commenter) instead of a write role. Go back to Google Drive → Share the folder with the SA email as Editor (My Drive) or Content manager (Shared Drive).
- 403 on specific file inside a shared folder: The file was added by someone else and hasn't inherited folder permissions yet. Force inheritance by resharing the folder, or share the specific file directly.
- "Invalid JWT token": Service account JSON corrupt or truncated. Re-encode (watch for line breaks: use
base64 -w 0on Linux,base64 -b 0on macOS). - Agent can't find new files: The agent only sees files inside folders listed in
folders. Add new folder IDs to the list and restart. - User sees files as "view only": Files created by the SA inside user folders are SA-owned. The skill should grant the user write access (role
writer: Editor in My Drive, Content manager in Shared Drive); if this step is skipped, the user sees view-only. Manual fix: right-click the file → Share → grant yourself write access.
Related
Google Calendar Integration
Connect your agent to Google Calendar for reading availability and drafting events. It is used primarily by appointment-booking and voice-receptionist agents.
Overview
The Google Calendar integration uses a Google Cloud service account with calendar access delegated by the operator. You create the service account in your own Google Cloud project, share the calendar(s) you want the agent to manage with the service account email, and the agent reads/writes events on those shared calendars only.
This is the same auth pattern as Google Drive and Google Play: service account JSON, no OAuth.
Skills that use this integration:
int-google-calendar: Read calendar availability, find open time slots, draft / create / modify events via Google Calendar API v3.
Agents that typically enable this integration:
- Voice Receptionist (appointment booking during inbound calls)
- Barber Booking and other small-business booking agents
- Custom agents that need calendar awareness (availability lookups, scheduling)
Availability
| Mode | Status | Notes |
|---|---|---|
| Service Account JSON | Available | Google Cloud service account with Google Calendar API enabled. Calendars shared by the operator. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- A Google account with the calendar(s) you want the agent to manage.
- A Google Cloud project to host the service account.
Setup
Step 1: Enable the Google Calendar API
Google Cloud Console → select project → APIs & Services → Library → Google Calendar API → Enable.
Step 2: Create a service account
- IAM & Admin → Service accounts → Create service account.
- Name it (e.g.
wiro-calendar-agent) → Create and continue. - Skip role grants → Done.
- Open the service account → Keys → Add key → Create new key → JSON. Download the JSON file.
- Note the service account email (format:
wiro-calendar-agent@YOUR-PROJECT.iam.gserviceaccount.com).
Tip: In My Agents → open your agent → Connectors, you can upload the JSON via the file picker; the service account email is detected and surfaced with a Copy button.
Step 3: Share the calendar with the service account
- Open Google Calendar.
- Hover the calendar in the left sidebar → ⋮ → Settings and sharing.
- Scroll to Share with specific people or groups → Add people or groups.
- Paste the service account email from Step 2.
- Set permissions to Make changes to events (read + write) → Send.
Which calendar?
- Personal: share your primary calendar (
primary) for solo operators. - Business / shared: create a dedicated calendar (e.g.
Bookings) so appointments stay separate from personal events. Copy its Calendar ID from Settings → Integrate calendar → Calendar ID (looks likeabcd1234@group.calendar.google.com).
Step 4: Save credentials to Wiro
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "google-calendar", "fieldname": "serviceaccountjson", "fieldvalue": "<base64-encoded service account JSON>" },
{ "credentialkey": "google-calendar", "fieldname": "calendarid", "fieldvalue": "primary" },
{ "credentialkey": "google-calendar", "fieldname": "timezone", "fieldvalue": "Europe/Istanbul" },
{ "credentialkey": "google-calendar", "fieldname": "slotdurationminutes", "fieldvalue": "30" }
]
}'
Or upload directly through the panel: My Agents → open agent → Connectors → Google Calendar.
Step 5: Start the agent
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
Credential Fields
| Field | Type | Required | Description |
|---|---|---|---|
serviceaccountjson |
string (base64-encoded JSON) | Yes | Service account credentials JSON, base64-encoded. Encrypted at rest. Max 50 KB. |
calendarid |
string | Yes | Which calendar to read/write. Use primary for the service account's own calendar, or a full Calendar ID like abcd1234@group.calendar.google.com for shared business calendars. |
timezone |
string | No | IANA timezone identifier (e.g. Europe/Istanbul, America/New_York, Asia/Tokyo). Used for slot suggestions, reminders, and event creation. Falls back to the calendar's own timezone if unset. |
slotdurationminutes |
number | No | Default appointment length in minutes when offering callers available slots. Common values: 15, 30, 45, 60. |
Credentials schema (as returned by POST /UserAgent/Detail)
"google-calendar": {
"_connected": true,
"optional": false,
"extra": false,
"serviceaccountjson": "••••••••",
"calendarid": "primary",
"timezone": "Europe/Istanbul",
"slotdurationminutes": 30
}
Combined Use: Appointment Booking via Voice
When paired with Twilio Voice on a Voice Receptionist agent, the typical flow is:
- Caller dials your Twilio number → agent answers.
- Caller asks "I'd like to book a haircut Tuesday at 3 PM" → agent checks availability against the configured calendar.
- If the slot is open → agent confirms → drafts the event.
- If conflicting → agent offers nearest free slots based on
slotdurationminutes. - Post-call, the agent can also draft a confirmation email via Brevo or SendGrid using the caller's email captured during the call.
Troubleshooting
- 403
notFound: The service account does not have access to the calendar. Re-share the calendar (Step 3) and confirm the email matches exactly (no trailing whitespace). - 403
accessNotConfigured: Google Calendar API isn't enabled in the Cloud project. Re-do Step 1. - 400
invalid_grant: Service account JSON is malformed or the private key was rotated. Generate a new key and re-upload. - Events appear in wrong timezone: Set
timezoneexplicitly. Without it, Google falls back to the calendar's own timezone, which may differ from your operator's expectations. - 403
forbiddenForServiceAccountson personal Gmail calendars: Some personal Google accounts restrict service-account writes. Use a dedicated Google Workspace calendar or a regular Google account that allows it.
Related
- Agent Credentials & OAuth
- Agent Skills
- Twilio Voice: pair for inbound voice booking
- Brevo Skills / SendGrid Skills: confirmation email drafts
- HubSpot Skills: log appointment as CRM activity
Serper Web Search Integration
Give your agent real Google search results as clean JSON via Serper.dev, so content, research, and marketing agents can find current sources before they write.
Overview
This integration returns Google's organic results as structured JSON (title, link, snippet) through Serper.dev. The agent gets ranked Google results, then reads the most relevant pages with its web_fetch tool, with no HTML scraping and no bot-blocking.
Why Serper and not Google's own API? Google's Custom Search JSON API is being retired (it shuts down on 2027-01-01) and no longer offers a whole-web mode for new engines. Serper returns the same Google results with none of the Google Cloud / cx setup, plus a generous free tier.
Skills that use this integration:
int-serper-search: Search the web via Serper's Google Search endpoint. Supports freshness (tbs) and locale (gl/hl); returnstitle/link/snippetfor downstreamweb_fetch.
Agents that typically enable this integration:
- Blog Content Editor: research trending models / news and find a fresh angle before drafting.
- Social Manager / Newsletter Manager: source current, on-topic material.
- Custom research or marketing agents that need the live public web.
Availability
| Mode | Status | Notes |
|---|---|---|
| API Key (Serper.dev) | Available | A Serper.dev API key. Returns real Google results as JSON. Free tier: 2,500 searches; then ~$1 per 1,000. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- A Serper.dev account (free, no credit card).
Setup
Step 1: Get a Serper.dev API key
- Sign up at serper.dev: no credit card; new accounts get 2,500 free searches.
- Open the dashboard and copy your API key from the API Key section.
No Google Cloud project, no Programmable Search Engine, and no cx: Serper handles whole-web Google search behind a single key.
Step 2: Save the credential to Wiro
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "serper", "fieldname": "apikey", "fieldvalue": "YOUR_SERPER_API_KEY" }
]
}'
Or fill it in the panel: My Agents → open agent → Connectors → Serper Web Search.
Step 3: Enable the skill
Serper Web Search ships available but off. Turn int-serper-search on for the agent:
curl -X POST "https://api.wiro.ai/v1/UserAgent/SkillsApply" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"skills": { "int-serper-search": true },
"idempotencyKey": "550e8400-e29b-41d4-a716-446655440000"
}'
Or flip the toggle in the panel under Skills.
Step 4: Start the agent
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
Credential Fields
| Field | Type | Required | Description |
|---|---|---|---|
apikey |
string (secret) | Yes | Serper.dev API key. Encrypted at rest. |
Credentials schema (as returned by POST /UserAgent/Detail)
"serper": {
"_connected": true,
"optional": true,
"extra": true,
"apikey": "••••••••"
}
optional and extra are true because Serper Web Search is an optional add-on: its connector card surfaces on the content presets even before the skill is toggled on.
Query options
The skill sends a single POST https://google.serper.dev/search with an X-API-KEY header and a JSON body. Beyond the required q, the useful fields are:
| Field | Description |
|---|---|
q | Query string (required). |
num | Results to return (default 10). More than 10 counts as 2 searches on the Serper quota. |
page | 1-based page number for pagination. |
gl / hl | Country bias / interface language (e.g. gl=us, hl=en). |
tbs | Freshness filter: qdr:d day, qdr:w week, qdr:m month, qdr:y year. |
autocorrect | true / false (default true). |
Results are in .organic[] (title, link, snippet, position); a response may also carry answerBox, knowledgeGraph, peopleAlsoAsk and relatedSearches. Other endpoints on the same host/header: /news, /images, /scholar, /places, /shopping.
Quota & billing
- Free tier: 2,500 searches per Serper account (no credit card).
- Beyond free: about $1 per 1,000 searches, dropping toward $0.30 at scale. Credits expire 6 months after purchase.
Serper's search quota and cost are billed by Serper to the operator's own account, separate from Wiro credits. The skill's own turns are billed by Wiro on real LLM token usage like any other skill.
Troubleshooting
- 401 / 403: API key missing or invalid. Re-copy it from the Serper dashboard.
- 400: Malformed JSON body or missing
q. - 429: Out of Serper credits or rate limited. Top up credits or slow down.
- Empty
organic: Zero results for the query. The agent reports "no results" rather than retrying. - Agent says "not connected" with the key filled: The agent restarts to pick up new credentials; give it a moment after saving, then retry.
Related
Gmail Integration
Connect your agent to a Gmail inbox using a Google App Password for IMAP access.
Overview
The Gmail integration uses IMAP with Basic authentication backed by a Google App Password. Agents can monitor the inbox, parse incoming messages, and trigger actions. It reads mail only: to send email, an agent uses an email Connector such as Brevo, SendGrid, Mailchimp, HubSpot or Lemlist.
Skills that use this integration:
int-gmail-check: Poll Gmail inbox on a schedule, parse messages, route to actions
Agents that typically enable this integration:
- Blog Content Editor (inbox-triggered workflows)
- Newsletter Manager
- Support / App Review agents (operator notifications)
Availability
| Mode | Status | Notes |
|---|---|---|
| App Password | Available | Works on any Gmail account with 2-Step Verification enabled. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- A Gmail account with 2-Step Verification enabled.
Setup
Step 1: Enable 2-Step Verification
- Sign in to the Google account.
- myaccount.google.com/security.
- Under How you sign in to Google, turn on 2-Step Verification.
Step 2: Create an App Password
- Same Security page → App passwords (appears once 2-Step Verification is on).
- Create a new App Password, label it "Wiro agent".
- Copy the 16-character password (format:
xxxx xxxx xxxx xxxx). Spaces are cosmetic, and Wiro accepts either form.
Step 3: Save to Wiro
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "gmail", "fieldname": "account", "fieldvalue": "agent@yourcompany.com" },
{ "credentialkey": "gmail", "fieldname": "apppassword", "fieldvalue": "xxxx xxxx xxxx xxxx" }
]
}'
Only account and apppassword are editable. credentials.gmail.interval (when present in some templates) is not used by the agent runtime. How often the inbox is read comes from the scheduled task that uses Gmail, cs-cron-blog-gmail-checker on the blog presets. To change it, update that task's interval via POST /UserAgent/CustomSkillUpsert (see Agent Skills).
Naming: the skill is int-gmail-check. The scheduled task that reads the inbox on the blog presets is cs-cron-blog-gmail-checker (cs-cron- marks a scheduled task). If int-gmail-check is off or Gmail is not connected, the task does nothing on its runs.
Step 4: Start the agent
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
Credential Fields
| Field | Type | Editable | Description |
|---|---|---|---|
account |
string | Yes | Full Gmail address (e.g. agent@company.com). |
apppassword |
string | Yes | 16-character Google App Password. Spaces allowed. |
interval |
cron string | No (template-controlled) | Polling frequency. Example: */8 * * * * (every 8 minutes). |
Credentials schema (as returned by POST /UserAgent/Detail)
"gmail": {
"_connected": false,
"optional": true,
"extra": false,
"account": "",
"apppassword": ""
}
Runtime Behavior
The int-gmail-check skill reads the inbox over IMAP:
- Host:
imaps://imap.gmail.com:993/INBOX - Auth: the Gmail address and app password you saved (
account/apppassword) - Runs on the schedule of the agent's Gmail scheduled task and processes new messages per the agent's rules
The skill is active only when it is enabled and account is set.
Troubleshooting
- "Invalid credentials" when IMAP connects: Wrong App Password, or 2-Step Verification was turned off (which invalidates all App Passwords). Regenerate.
- Agent can't see messages older than ~30 days: IMAP folder defaults. For broader scope, your agent may need to switch to "All Mail". Ask support.
- "Less Secure Apps" mentioned anywhere: Google removed that option in 2022. App Password is the only supported path for IMAP.
Related
Telegram Integration
Connect your agent to a Telegram bot as an optional extra messaging channel.
Overview
Telegram is optional on every Wiro agent. By default your agents already support two built-in messaging channels out of the box:
- Web chat: chat with the agent directly from the wiro.ai dashboard with no extra setup.
- Messaging API: your own application sends and receives messages programmatically via Agent Messaging, with real-time streaming over Agent WebSocket or HTTP callbacks via Agent Webhooks.
Adding a Telegram bot gives you a third, complementary channel, useful when you want to:
- Push operator notifications (campaign alerts, new leads, error reports) to a private chat or team group on your phone.
- Give off-dashboard access to team members who don't log into wiro.ai but still want to message the agent.
- Pipe scheduled status reports from scheduled tasks into a shared Telegram channel.
You can skip this integration entirely: agents keep working through web chat and the API regardless. Telegram activates automatically only after both bottoken and allowedusers are configured.
Availability
| Mode | Status | Notes |
|---|---|---|
| Bot Token | Available | Single Bot Token from BotFather. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- A Telegram account.
Setup
Step 1: Create a Telegram bot
- In Telegram, start a chat with @BotFather.
- Send
/newbot. - Choose a display name and a username (must end in
bot, e.g.@mycompany_agent_bot). - BotFather returns a Bot Token like
123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11. Copy it.
Step 2: Collect allowed user IDs
Each allowed user must message the bot first.
- User sends any message to the bot.
- Open
https://api.telegram.org/bot<BOT_TOKEN>/getUpdatesin a browser. - Find the
message.from.idvalue in the response: that's the Telegram user ID (numeric).
Alternative: each user can DM @userinfobot in Telegram to get their own ID.
Step 3: Save Telegram credentials on the UserAgent
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{
"credentialkey": "telegram",
"fieldname": "bottoken",
"fieldvalue": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
},
{
"credentialkey": "telegram",
"fieldname": "allowedusers",
"fieldvalue": ["123456789", "987654321"]
},
{
"credentialkey": "telegram",
"fieldname": "groups",
"fieldvalue": [
{
"chatid": "-1001234567890",
"allowedusers": ["123456789"]
}
]
}
]
}'
Send allowedusers and groups as native JSON arrays. groups is optional; omit it when the bot should be usable only in direct messages.
If you are deploying a new agent, place the complete telegram group in credentials. Do not send an enabledchannels switch or chat-mode field to POST /UserAgent/Deploy; change Chat Mode after deployment with POST /UserAgent/UpdateSettings.
Step 4: Verify the applied state
curl -X POST "https://api.wiro.ai/v1/UserAgent/Detail" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
Confirm that enabledChannels contains "telegram" and that its communicationChannels row reports enabled: true, configured: true, and an empty missingfields array.
Credential Fields
| Field | Type | Description |
|---|---|---|
bottoken |
string | BotFather token (<bot_id>:<secret>). |
allowedusers |
string[] | Array of Telegram user IDs (numeric strings) allowed to interact. Messages from IDs outside this list are ignored. |
groups |
object[] | Optional room allowlist. Each row is { "chatid": "-100...", "allowedusers": ["..."] }. Group IDs must be negative numeric strings. |
Chat Mode
teamsessionmode is the agent's single Chat Mode setting, not a Telegram credential. Set it after deployment with POST /UserAgent/UpdateSettings. The same value also controls team members' Wiro web-chat history.
| Mode | Behavior |
|---|---|
private |
Each allowed direct-message user has an isolated conversation with the agent. Personal deployments and team detachments use this default. |
collaborative |
Approved direct-message users share one conversation. Team deployments and transfers use this default. |
Group conversations remain scoped to their own group and never merge into the direct-message conversation.
Access Behavior
- Direct messages are accepted only from IDs in the top-level
allowedusers. - Group messages are accepted only in configured
groups[].chatidrooms and from that room's approved users. - Group turns must mention the bot.
- Usernames and display names are never authorization values.
- Clear either
bottokenoralloweduserswithCredentialUpsertto disable Telegram; completing both reactivates it.
Troubleshooting
- Bot doesn't respond: Verify
bottokenis correct and the sender's Telegram user ID is inallowedusers. - "Unauthorized" (401) from Telegram API: BotFather regenerated the token, invalidating the old one. Create a new token and update.
- Rate limits: Telegram bots are limited to ~30 messages/second globally. For burst broadcasts, plan around this.
- Bot works in DMs but not a group: Add the negative group chat ID and sender ID to the same
groups[]row, then mention the bot. - Collaborative mode confusion: Call
UserAgent/UpdateSettingswithteamsessionmode: "collaborative".
Related
Firebase Integration
Connect your agent to Firebase Cloud Messaging (FCM) to send targeted push notifications to iOS and Android apps.
Overview
The Firebase integration uses FCM HTTP v1 with an Admin SDK service account. A single agent can manage notifications for multiple Firebase projects.
Skills that use this integration:
int-firebase-push: Send push notifications by topic, device token, or condition
Agents that typically enable this integration:
- Push Notification Manager
Availability
| Mode | Status | Notes |
|---|---|---|
| Service account JSON | Available | Admin SDK service account with FCM permissions. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- A Firebase project with your iOS and/or Android apps registered and FCM enabled.
Setup
Step 1: Generate a Firebase Admin SDK service account
- console.firebase.google.com → select project.
- Project settings → Service accounts → Firebase Admin SDK → Generate new private key.
- Save the JSON file.
Step 2: Base64-encode the JSON
# Linux
base64 -w 0 firebase-service-account.json > firebase-sa.b64
# macOS
base64 -b 0 firebase-service-account.json > firebase-sa.b64
Step 3: Save to Wiro
Send the accounts list as one field row. Each account carries its own apps and topics lists.
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{
"credentialkey": "firebase",
"fieldname": "accounts",
"fieldvalue": [
{
"appname": "My App",
"serviceaccountjson": "eyJ0eXBlIjoic2VydmljZV9hY2NvdW50Ii...",
"apps": [
{ "platform": "ios", "id": "1234567890" },
{ "platform": "android", "id": "com.example.app" }
],
"topics": [
{ "topickey": "locale_en", "topicdesc": "English users" },
{ "topickey": "tier_paid", "topicdesc": "Paid subscribers" }
]
}
]
}
]
}'
Step 4: Start the agent
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
Credential Fields
credentials.firebase.accounts[] is an array. Each account object:
| Field | Type | Editable | Description |
|---|---|---|---|
appname |
string | Yes | Display name for this project. |
serviceaccountjson |
string | Yes | Base64-encoded service account JSON. |
apps |
object[] | Yes | { platform: "ios" | "android", id: string }, both required. id is App Store ID for iOS, package name for Android. |
topics |
object[] | Yes | { topickey: string, topicdesc?: string }. topickey is a topic you've subscribed clients to on the device side; topicdesc is an optional description of its audience. |
projectid |
string | No (derived from service account) | Read from the decoded JSON. |
Multi-project setups
Add more entries to accounts[] to manage multiple Firebase projects from one agent. Saving accounts replaces the stored list, so send every account you want to keep:
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{
"credentialkey": "firebase",
"fieldname": "accounts",
"fieldvalue": [
{
"appname": "Consumer App",
"serviceaccountjson": "eyJ0eXBlIjoic2VydmljZV9hY2NvdW50Ii...",
"apps": [{ "platform": "ios", "id": "1234567890" }],
"topics": [{ "topickey": "locale_en", "topicdesc": "English users" }]
},
{
"appname": "Business App",
"serviceaccountjson": "eyJ0eXBlIjoic2VydmljZV9hY2NvdW50Ii...",
"apps": [{ "platform": "android", "id": "com.example.business" }],
"topics": [{ "topickey": "tier_paid", "topicdesc": "Paid subscribers" }]
}
]
}
]
}'
To change one saved account and leave the others as they are, send a row with parentfield: "accounts" and that account's position as ordinal (from 0). Send its apps or topics the same way, each as one row holding the whole new list. This replaces the topics of the second account:
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{
"credentialkey": "firebase",
"parentfield": "accounts",
"ordinal": 1,
"fieldname": "topics",
"fieldvalue": [
{ "topickey": "tier_paid", "topicdesc": "Paid subscribers" },
{ "topickey": "tier_trial", "topicdesc": "Trial users" }
]
}
]
}'
Runtime Behavior
The int-firebase-push skill is active only when it is enabled and accounts is non-empty. For each saved account it uses the project ID from that account's service account, plus the app name, topics and apps you saved.
Auth: FCM HTTP v1 Authorization: Bearer <token>, with tokens minted from the account's service account.
Base URL: https://fcm.googleapis.com/v1/projects/<PROJECT_ID>/messages:send
Troubleshooting
- "invalid JWT signature": Service account JSON corrupt or truncated. Re-export from Firebase Console and re-encode.
- No devices receive notifications: Verify topics are subscribed on the client side and the topic name matches exactly. Check that the topic is listed in that account's
topics. - Rate limits: FCM supports up to 600,000 messages/minute per project for HTTP v1 API (see the
int-firebase-pushskill for topic/condition specifics). Higher volumes require a support request to Google Cloud.
Related
WordPress Integration
Connect your agent to a WordPress site (self-hosted or WordPress.com Business+) to publish posts and pages.
Overview
The WordPress integration uses the WordPress REST API with Basic Authentication backed by a WordPress Application Password.
Skills that use this integration:
int-wordpress-post: Publish blog posts, pages, categories, tags; upload media
Agents that typically enable this integration:
- Blog Content Editor
Availability
| Mode | Status | Notes |
|---|---|---|
| Application Password | Available | WordPress 5.6+ built-in Application Passwords. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- A WordPress site (self-hosted or WordPress.com Business/Commerce) running WordPress 5.6+.
- An admin or editor-level user on that site.
Setup
Step 1: Enable Application Passwords (if disabled)
Enabled by default in WP 5.6+. If your host or security plugin disabled them:
- In
wp-config.php, confirmWP_ENVIRONMENT_TYPEisn't restricting them. - Security plugins like Wordfence or iThemes Security sometimes disable Application Passwords, so check their settings.
Step 2: Create an Application Password
- Log in as the user the agent will post as.
- Users → Profile (or Users → All Users → Edit another user if you're admin).
- Scroll to Application Passwords.
- Name it "Wiro agent", Add New Application Password.
- Copy the 24-character password (spaces are cosmetic; both forms work).
Step 3: Save to Wiro
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "wordpress", "fieldname": "url", "fieldvalue": "https://blog.example.com" },
{ "credentialkey": "wordpress", "fieldname": "user", "fieldvalue": "your-wp-username" },
{ "credentialkey": "wordpress", "fieldname": "apppassword", "fieldvalue": "xxxx xxxx xxxx xxxx xxxx xxxx" }
]
}'
Step 4: Start the agent
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
Credential Fields
| Field | Type | Description |
|---|---|---|
url |
string | Site URL with https://, no trailing slash. |
user |
string | WordPress username the Application Password belongs to. |
apppassword |
string | 24-character Application Password. |
Credentials schema (as returned by POST /UserAgent/Detail)
"wordpress": {
"_connected": false,
"optional": false,
"extra": false,
"url": "",
"user": "",
"apppassword": ""
}
Runtime Behavior
The int-wordpress-post skill is active only when it is enabled and url is set.
Auth: Basic auth with your WordPress user and its Application Password (apppassword).
Base URL: <your site url>/wp-json/wp/v2/...
Troubleshooting
- 401 Unauthorized on REST API: Username mismatch (case-sensitive on some setups), or Application Password invalid. Regenerate.
-
REST API returns 404 at
/wp-json/: Permalinks set to Plain. Go to Settings → Permalinks and pick any pretty-permalink option. - WordPress.com Business plan: REST API access must be on via Jetpack settings.
- Cloudflare/WAF blocking writes: Whitelist Wiro's outbound IPs (contact support) or allow
/wp-json/wp/v2/postsendpoints.
Related
App Store Connect Integration
Connect your agent to App Store Connect for review monitoring, metadata management, and in-app events.
Overview
The App Store Connect integration uses ES256-signed JWT authentication with App Store Connect API keys.
Skills that use this integration:
int-appstore-reviews: Monitor and reply to App Store reviewsint-appstore-metadata: Read/update app metadata, localizations, screenshotsint-appstore-events: Create and manage in-app events
Agents that typically enable this integration:
- App Review Support
- App Event Manager
- Meta Ads Manager (uses a simpler
appsarray shape, see below) - TikTok Ads Manager (uses a simpler
appsarray shape, see below)
Availability
| Mode | Status | Notes |
|---|---|---|
| ES256 API Key | Available | Standard App Store Connect API keys. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- App Store Connect Admin access: only Admins can generate API keys.
Setup
Step 1: Create an API key
- Sign in to App Store Connect.
- Users and Access → Integrations → App Store Connect API.
- Click + to generate a new key.
-
Name (e.g. "Wiro agent") and role:
- Admin or App Manager for full capability
- Customer Support for reviews-only
- Download the
.p8file. It is only downloadable once. - Copy the Key ID (10-char like
ABC1234DEF) and Issuer ID (UUID at top).
Step 2: Base64-encode the private key
# Linux
base64 -w 0 AuthKey_ABC1234DEF.p8 > appstore-key.b64
# macOS
base64 -b 0 AuthKey_ABC1234DEF.p8 > appstore-key.b64
Step 3: Save to Wiro
The credential depends on which agent you're configuring. Review, events and metadata agents use apple-appstore: the API key (keyid, issuerid, privatekey) plus a positional apps[] array. Each app entry carries appname + appid. Ads-manager agents need no API key: they read the app list for attribution context from the separate apple-appstore-apps credential, which holds only the apps[] array. Send the same apps rows with "credentialkey": "apple-appstore-apps".
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "apple-appstore", "fieldname": "keyid", "fieldvalue": "ABC1234DEF" },
{ "credentialkey": "apple-appstore", "fieldname": "issuerid", "fieldvalue": "12345678-1234-1234-1234-123456789012" },
{ "credentialkey": "apple-appstore", "fieldname": "privatekey", "fieldvalue": "LS0tLS1CRUdJTi..." },
{ "credentialkey": "apple-appstore", "parentfield": "apps", "ordinal": 0, "fieldname": "appname", "fieldvalue": "My App" },
{ "credentialkey": "apple-appstore", "parentfield": "apps", "ordinal": 0, "fieldname": "appid", "fieldvalue": "1234567890" },
{ "credentialkey": "apple-appstore", "parentfield": "apps", "ordinal": 1, "fieldname": "appname", "fieldvalue": "Pro Version" },
{ "credentialkey": "apple-appstore", "parentfield": "apps", "ordinal": 1, "fieldname": "appid", "fieldvalue": "1234567890" }
]
}'
For multiple App Store IDs, append more apps-prefixed ordinal rows. Positional merge applies: sending no apps rows leaves the existing list untouched; to clear the list, send { "credentialkey": "apple-appstore", "fieldname": "apps", "fieldvalue": [] }.
Reply skills can also use a global support email. It is optional: without it, reply drafts leave out the contact line. Set it once via the dedicated var-support-email credential (shared across int-appstore-reviews and int-googleplay-reviews):
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "var-support-email", "fieldname": "value", "fieldvalue": "support@yourcompany.com" }
]
}'
| Field | Type | Required | Description |
|---|---|---|---|
keyid |
string | Yes (review/events/metadata) | 10-character App Store Connect Key ID. |
issuerid |
string | Yes (review/events/metadata) | UUID issuer ID. |
privatekey |
string | Yes (review/events/metadata) | Base64-encoded .p8 private key. Stored encrypted-at-rest in the DB (type: fileinput-base64). |
apps[].appname |
string | Yes | Friendly label the agent uses when reporting back ("scanned reviews on My iOS App"). |
apps[].appid |
string | Yes | Numeric App Store ID. |
var-support-email.value |
string | No | Global support email: surfaced when reviewers are pointed to direct contact. Lives on the dedicated var-support-email credential, not on apple-appstore. |
Step 4: Start the agent
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
Runtime Behavior
Wiro signs an ES256 JWT from keyid + issuerid + privatekey and calls App Store Connect at https://api.appstoreconnect.apple.com/v1/... with Authorization: Bearer <TOKEN>. Ads-manager agents (Meta Ads Manager / Google Ads Manager) consume the apps[] list for attribution context and do not need the API key fields filled.
Troubleshooting
- 401 Unauthorized on API: Wrong Key ID or Issuer ID, or base64 corrupted the
.p8key. Re-export and re-encode. Verify no newlines or whitespace were introduced. -
Key ID
NOT_ENABLED: The key was revoked. Generate a new one. - Reviews not appearing: Role of the API key lacks Customer Support permissions. Regenerate with a role that includes review access.
- Metadata updates fail: Role lacks Admin or App Manager permissions for the app in question.
Related
Google Play Integration
Connect your agent to the Google Play Developer API for review monitoring and app listing management.
Overview
The Google Play integration uses a Google Cloud service account with API access delegated from a Play Console project.
Skills that use this integration:
int-googleplay-reviews: Monitor and reply to Google Play reviewsint-googleplay-metadata: Read/update app listings and metadataint-googleplay-events: Prepare assets and copy for Google Play promotional content (LiveOps events); reads only the app list
Agents that typically enable this integration:
- App Review Support
- Meta Ads Manager (uses the simpler
appsarray shape) - TikTok Ads Manager (uses the simpler
appsarray shape)
Availability
| Mode | Status | Notes |
|---|---|---|
| Service Account JSON | Available | Google Cloud service account with Play Developer Reporting access. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- A Google Play Console account with Admin access.
- A Google Cloud project to host the service account.
Setup
Step 1: Enable the Google Play Android Developer API
Google Cloud Console → select project → APIs & Services → Library → Google Play Android Developer API → Enable.
Step 2: Create a service account
- IAM & Admin → Service accounts → Create service account.
- Name (e.g. "wiro-play-agent").
- Grant role:
Service Account Token Creator. - Skip user permissions → Done.
- Open the service account → Keys → Add key → Create new key → JSON. Download.
- Note the service account email from the account details page (format:
wiro-play-agent@YOUR-PROJECT.iam.gserviceaccount.com).
Tip: In My Agents → open your agent → Connectors, upload the JSON and your service account email will appear with a Copy button.
Step 3: Link the service account to Play Console
- Google Play Console → Users and permissions → Invite new users.
- Email: the service account email (
...@....iam.gserviceaccount.com). - Grant at least: View app information, Reply to reviews, and any others needed by your agent.
- Send invite: Play Console auto-accepts for service accounts.
Step 4: Base64-encode the JSON
# Linux
base64 -w 0 play-service-account.json > play-sa.b64
# macOS
base64 -b 0 play-service-account.json > play-sa.b64
Step 5: Save to Wiro
The credential depends on which agent you're configuring. Review and metadata agents use google-play: the service account JSON plus a positional apps[] array. Each app entry carries appname + packagename. The promotional-content skill and the ads-manager agents need no service account: they read the app list from the separate google-play-apps credential, which holds only the apps[] array. Send the same apps rows with "credentialkey": "google-play-apps".
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "google-play", "fieldname": "serviceaccountjson", "fieldvalue": "eyJ0eXBlIjoic2VydmljZV9hY2NvdW50Ii..." },
{ "credentialkey": "google-play", "parentfield": "apps", "ordinal": 0, "fieldname": "appname", "fieldvalue": "My App" },
{ "credentialkey": "google-play", "parentfield": "apps", "ordinal": 0, "fieldname": "packagename", "fieldvalue": "com.example.app" },
{ "credentialkey": "google-play", "parentfield": "apps", "ordinal": 1, "fieldname": "appname", "fieldvalue": "Pro Version" },
{ "credentialkey": "google-play", "parentfield": "apps", "ordinal": 1, "fieldname": "packagename", "fieldvalue": "com.example.other" }
]
}'
For multiple apps, append more apps-prefixed ordinal rows. Positional merge applies: sending no apps rows leaves the existing list untouched; to clear the list, send { "credentialkey": "google-play", "fieldname": "apps", "fieldvalue": [] }.
Reply skills can also use a global support email. It is optional: without it, reply drafts leave out the contact line. Set it once via the dedicated var-support-email credential (shared across int-appstore-reviews and int-googleplay-reviews):
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "var-support-email", "fieldname": "value", "fieldvalue": "support@yourcompany.com" }
]
}'
| Field | Type | Required | Description |
|---|---|---|---|
serviceaccountjson |
string | Yes | Base64-encoded service account JSON. Stored encrypted-at-rest in the DB (type: fileinput-base64). |
apps[].appname |
string | Yes | Friendly label the agent uses when reporting back ("scanned reviews on My Android App"). |
apps[].packagename |
string | Yes | Android package name (e.g. com.example.app). |
var-support-email.value |
string | No | Global support email: surfaced when reviewers are pointed to direct contact. Lives on the dedicated var-support-email credential, not on google-play. |
Step 6: Start the agent
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
Runtime Behavior
Wiro mints an OAuth access token from the service account JSON on demand and calls Google Play at https://androidpublisher.googleapis.com/androidpublisher/v3/... with Authorization: Bearer <TOKEN>. The apps[] list scopes which package names the agent operates on.
Troubleshooting
- 403 "The caller does not have permission": Service account is in Google Cloud but hasn't been invited in Play Console, or lacks the required permission. Return to Play Console → Users and permissions and adjust.
- "Invalid JWT token": Service account JSON corrupt or truncated. Re-encode.
- Review reply fails silently: Some reviews are >1 year old and can't be replied to via API. Google enforces this at the platform level.
Related
Apollo.io Integration
Connect your agent to Apollo.io for lead generation, prospecting, and email sequence enrollment.
Overview
The Apollo integration uses Apollo's x-api-key header authentication.
Skills that use this integration:
int-apollo-sales: Lead search, enrichment, sequence enrollment, reply handling
Agents that typically enable this integration:
- Lead Generation Manager
Availability
| Mode | Status | Notes |
|---|---|---|
| API Key | Available | Apollo REST API keys. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- An Apollo.io account on a plan that includes API access.
Setup
Step 1: Get an Apollo API key
- app.apollo.io → Settings → Integrations → API (or Account settings → API keys).
- Create new key, name "Wiro agent", copy value.
Step 2 (optional): Get a Master API Key
Some Apollo plans require a separate Master API Key for the mixed_people/api_search endpoint (people search) and for sequence management. Find it in Admin → API keys (workspace admins only). Enrichment, lookups, and basic read operations use the standard apikey.
Step 3: Save to Wiro
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "apollo", "fieldname": "apikey", "fieldvalue": "YOUR_APOLLO_API_KEY" },
{ "credentialkey": "apollo", "fieldname": "masterapikey", "fieldvalue": "YOUR_APOLLO_MASTER_API_KEY" }
]
}'
masterapikey is optional: omit if your agent only does enrichment and lookups. Required for people search (mixed_people/api_search) and sequence management.
Step 4: Start the agent
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
Credential Fields
| Field | Type | Description |
|---|---|---|
apikey |
string | Primary Apollo API key. |
masterapikey |
string (optional) | Master API key for people search + sequence management. |
Credentials schema (as returned by POST /UserAgent/Detail)
"apollo": {
"_connected": false,
"optional": true,
"extra": false,
"apikey": "",
"masterapikey": ""
}
Runtime Behavior
The int-apollo-sales skill is active only when it is enabled and apikey is set; masterapikey is optional.
Endpoint-based key selection. The int-apollo-sales skill picks the key per endpoint and sends it in the x-api-key header:
| Endpoint group | Key used | Requirement |
|---|---|---|
People Search (POST /mixed_people/api_search) | masterapikey | Requires masterapikey |
| Sequence management (create sequence, add contacts, start/pause) | masterapikey | Requires masterapikey |
People enrichment (POST /people/match) | apikey | apikey sufficient |
| Organization lookup | apikey | apikey sufficient |
| Email verification | apikey | apikey sufficient |
Base URL: https://api.apollo.io/api/v1.
Rate limits: Apollo enforces strict per-key limits; 429 responses require 60s backoff.
If masterapikey is missing: People search and sequence endpoints return 401 Unauthorized with "error": "Invalid Api Key". This is expected: even though apikey works for other endpoints, Apollo's master-only endpoints reject the regular key. Add masterapikey via POST /UserAgent/CredentialUpsert; saving restarts a running agent, and it can use the master-only endpoints from then on.
Troubleshooting
- 403 Forbidden: Plan doesn't include API access. Upgrade to Professional tier or higher.
- 429 Too Many Requests: Rate limit hit. Space prospecting runs or request higher tier from Apollo support.
-
401 on
mixed_people/api_search: Missingmasterapikey. Add it (workspace admins: Apollo → Admin → API keys). - Sequence enrollment fails: Missing
masterapikey. Same fix: master key is required for write operations on sequences.
Related
Lemlist Integration
Connect your agent to Lemlist for cold email outreach and campaign orchestration.
Overview
The Lemlist integration uses HTTP Basic Authentication with an empty username and the API key as the password.
Skills that use this integration:
int-lemlist-outreach: Campaign creation, lead uploads, pause/resume
Agents that typically enable this integration:
- Lead Generation Manager
Availability
| Mode | Status | Notes |
|---|---|---|
| API Key | Available | Lemlist API key (Gold tier or higher). |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- A Lemlist account on Gold tier or higher for full API access.
Setup
Step 1: Get an API key
- app.lemlist.com → Settings → Integrations → API.
- Click Generate (or copy existing). Keys look like
AbCdEfGhIjKlMnOp.
Step 2: Save to Wiro
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "lemlist", "fieldname": "apikey", "fieldvalue": "YOUR_LEMLIST_API_KEY" }
]
}'
Step 3: Start the agent
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
Credential Fields
| Field | Type | Description |
|---|---|---|
apikey |
string | Lemlist API key. |
Credentials schema (as returned by POST /UserAgent/Detail)
"lemlist": {
"_connected": false,
"optional": true,
"extra": false,
"apikey": ""
}
Runtime Behavior
The int-lemlist-outreach skill is active only when it is enabled and apikey is set.
Auth: Basic auth with an empty username and the API key as the password, as Lemlist documents.
Base URL: https://api.lemlist.com/api.
Rate limits: ~20 requests per 2 seconds; 429 requires backoff.
Troubleshooting
- 401 Unauthorized: API key revoked in Lemlist settings. Regenerate.
- 403 on campaign operations: Plan tier lacks API write access. Upgrade.
- Email address not found: Lead must exist in at least one campaign before some endpoints work, so upload leads first.
Related
Brevo Integration
Connect your agent to Brevo (formerly Sendinblue) for transactional and marketing email.
Overview
The Brevo integration uses Brevo API v3 with an api-key header (not Bearer).
Skills that use this integration:
int-brevo-email: Campaign, template, and contact management via Brevo API v3util-newsletter-compose: optional; uses Brevo as the ESP when enabled alongside. Newsletter Manager has it on; on other agents turn onutil-newsletter-composeyourself. Brevo alone adds no newsletter tasks.
Other: Custom agents can use Brevo from their own skills once the integration is connected.
Agents that typically enable this integration:
- Newsletter Manager
Availability
| Mode | Status | Notes |
|---|---|---|
| API Key (v3) | Available | Standard Brevo API v3 keys. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- A Brevo account (free tier works for low volume).
Setup
Step 1: Get an API key
- app.brevo.com → profile (top right) → SMTP & API → API Keys.
- Generate a new API key, name "Wiro agent".
- Copy the key (starts with
xkeysib-).
Step 2: Save to Wiro
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "brevo", "fieldname": "apikey", "fieldvalue": "xkeysib-xxxxxxxxxxxxxxxxxxxx" }
]
}'
Step 3: Start the agent
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
Credential Fields
| Field | Type | Description |
|---|---|---|
apikey |
string | Brevo v3 API key (starts with xkeysib-). |
Credentials schema (as returned by POST /UserAgent/Detail)
"brevo": {
"_connected": false,
"optional": true,
"extra": false,
"apikey": ""
}
Runtime Behavior
The int-brevo-email skill is active only when it is enabled and apikey is set.
Auth: Header api-key: <your API key>, not Bearer. This is Brevo's documented auth pattern.
Base URL: https://api.brevo.com/v3/.
Rate limits: ~10 req/s on free plan; higher on paid tiers.
Troubleshooting
- 401 Unauthorized: Key revoked or deleted. Generate a new one.
- Emails go to spam: Verify sending domain under Brevo → Senders & IP → Domains. Set up SPF, DKIM, DMARC.
- Rate limit (429): Free tier is 300 emails/day. Upgrade plan.
Related
SendGrid Integration
Connect your agent to Twilio SendGrid for transactional and marketing email delivery.
Overview
The SendGrid integration uses standard Bearer authentication with a SendGrid API key.
Skills that use this integration:
int-sendgrid-email: Marketing and transactional email via SendGrid v3 APIutil-newsletter-compose: optional; uses SendGrid as the ESP when enabled alongside. Newsletter Manager has it on; on other agents turn onutil-newsletter-composeyourself. SendGrid alone adds no newsletter tasks.
Other: Custom agents can use SendGrid from their own skills once the integration is connected.
Agents that typically enable this integration:
- Newsletter Manager
Availability
| Mode | Status | Notes |
|---|---|---|
| API Key | Available | Twilio SendGrid API keys. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (see Agent Overview).
- A SendGrid account.
Setup
Step 1: Create an API key
- app.sendgrid.com → Settings → API Keys → Create API Key.
- Name "Wiro agent".
-
Permissions:
- Full Access for maximum capability, or
- Restricted Access + enable at least Mail Send (and Marketing Campaigns if used).
- Create & View, copy the key once (starts with
SG.). It cannot be retrieved later.
Step 2: Save to Wiro
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "sendgrid", "fieldname": "apikey", "fieldvalue": "SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
]
}'
Step 3: Start the agent
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
Credential Fields
| Field | Type | Description |
|---|---|---|
apikey |
string | SendGrid API key (starts with SG.). |
Credentials schema (as returned by POST /UserAgent/Detail)
"sendgrid": {
"_connected": false,
"optional": true,
"extra": false,
"apikey": ""
}
Runtime Behavior
The int-sendgrid-email skill is active only when it is enabled and apikey is set.
Auth: Authorization: Bearer <your API key>.
Base URL: https://api.sendgrid.com/v3.
Rate limits: 600 req/min on most endpoints; higher on marketing endpoints.
Troubleshooting
- 401 Unauthorized: Key deleted or permissions changed. Create a new key with appropriate scopes.
- 403 Forbidden on send: Sender identity not verified. In SendGrid → Settings → Sender Authentication, verify single sender or domain.
- Emails flagged as spam: Complete Domain Authentication (SPF + DKIM + DMARC) in SendGrid sender settings.
Related
Twilio Voice Channel
Connect inbound phone calls (PSTN) to a Wiro agent. Used by the Voice Receptionist agent and any custom agent that needs to answer real phone calls.
Overview
Toggle int-twilio-channel on a useragent and Wiro auto-enables the bundled voice rules (util-voice-receptionist + util-voice-call-prep) via the registry's depends_on chain, so you don't need to enable them separately.
Skills that use this credential:
int-twilio-channel: Twilio Voice channel.
Agents that typically enable this integration:
- Voice Receptionist (phone-receptionist for SMBs)
- Custom agents that handle inbound calls
Twilio bills you separately on your Twilio account (per inbound minute + per number rental + per TTS character when hold uses TTS). Wiro doesn't proxy Twilio billing.
Availability
| Mode | Status | Notes |
|---|---|---|
| API Key (Account SID + Auth Token) | Available | Twilio Live Credentials. Wiro auto-configures each number's VoiceUrl on save. |
Webhook auto-configuration
You don't touch the Twilio Console's webhook fields manually. When you save this credential through POST /UserAgent/CredentialUpsert (or the panel), Wiro uses your Account SID + Auth Token to auto-configure each phone number's VoiceUrl and StatusCallback. No separate "Setup webhooks" step.
Important: the number's Configure with mode in the Twilio Console must be Webhook, TwiML Bin, Function, Studio Flow, Proxy Service (Twilio's default). Wiro does not drive TwiML App or SIP Trunk routing, so flip the number back to Webhook in the Twilio Console first if it's set to one of those.
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent (Voice Receptionist preset or any custom agent with
int-twilio-channelenabled), see Agent Overview. - A Twilio account with at least one purchased phone number.
Setup
Step 1: Get your Twilio Live Credentials
- Twilio Console → Account → Keys & Credentials → API keys & tokens.
- In the Live credentials section at the top of the page, copy:
- Account SID: 34 chars, starts with
AC. - Auth Token: click Show to reveal. 32-char secret.
- Account SID: 34 chars, starts with
Don't confuse with API Keys. The lower part of the same page lists API Keys, which are a different mechanism Wiro doesn't use. Use the Live Auth Token specifically. An API Key Secret pasted here will silently fail every call.
Step 2: Buy or import phone numbers
Twilio Console → Phone Numbers → Active numbers → Buy a number. Pick a number with Voice capability (toll-free, local, or international as desired).
Numbers must be in E.164 format when you save them to Wiro:
- Starts with
+ - Country code first (no leading
0) - Digits only: no spaces, dashes, or parentheses
- Max 15 digits total
Examples: +14155551234 (US), +447911123456 (UK), +905551234567 (Turkey), +5511900000000 (Brazil).
Step 3: Save credentials to Wiro
curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"fields": [
{ "credentialkey": "twilio-voice", "fieldname": "accountsid", "fieldvalue": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" },
{ "credentialkey": "twilio-voice", "fieldname": "authtoken", "fieldvalue": "your-32-character-auth-token" },
{ "credentialkey": "twilio-voice", "parentfield": "phonenumbers", "ordinal": 0, "fieldname": "value", "fieldvalue": "+14155551234" },
{ "credentialkey": "twilio-voice", "fieldname": "maxcallseconds", "fieldvalue": "600" },
{ "credentialkey": "twilio-voice", "fieldname": "holdstrategy", "fieldvalue": "text_then_music" },
{ "credentialkey": "twilio-voice", "fieldname": "holdtext", "fieldvalue": "Please hold while we connect you to our assistant." },
{ "credentialkey": "twilio-voice", "fieldname": "holdvoice", "fieldvalue": "Polly.Joanna-Neural" }
]
}'
Or save through the panel: My Agents → open agent → Connectors → Twilio Voice. The panel saves the card, and the same save sets up the number webhooks.
Step 4: Verify webhook configuration
After saving credentials, the response includes:
twilioWebhooksUpdated: numbers whoseVoiceUrlwas successfully written.twilioWebhookSkipped: a single reason string, returned instead oftwilioWebhooksUpdatedwhen theVoiceUrlstep was skipped (e.g. no matching IncomingPhoneNumber on Twilio account).twilioWebhooksFailed: Twilio API errors per number, if any.twilioWebhookError: present instead of the three fields above when the entire auto-webhook flow throws (e.g. Twilio API outage, invalid Account SID format, network error). Holds a single error string. Treat as "no numbers were configured this round; retry the save".
You can also confirm in the Twilio Console: open the number → Voice Configuration → A call comes in should show:
- Configure with → Webhook, TwiML Bin, Function, Studio Flow, Proxy Service
- Webhook URL → a Wiro voice handler URL
- HTTP → POST
Step 5: Start the agent and place a test call
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "your-useragent-guid" }'
Once the agent is in status 4 (running), dial your Twilio number from any phone. You should hear the configured hold experience for ~5-8 seconds, then the agent's greeting.
Credential Fields
| Field | Type | Required | Description |
|---|---|---|---|
accountsid |
string | Yes | Twilio Account SID: 34 chars starting with AC. |
authtoken |
string (secret) | Yes | Twilio Live Auth Token: 32-char secret. Stored encrypted at rest. |
phonenumbers |
string array | Yes | E.164-formatted phone numbers this agent will answer. All numbers share the same agent settings (hold media, persona, skills). |
maxcallseconds |
number | No | Hard cap per call in seconds. Default 600 (10 min). When reached, the call is force-ended and the caller hears a fallback message. Twilio still bills for the full duration up to this cap. |
whitelistedcallers |
string array | No | E.164-formatted caller-ID allowlist. Non-empty → only listed numbers reach the agent (others get a busy signal). Empty → all callers accepted (production default). Use to add only your own number while testing in production. |
holdstrategy |
enum | No | What the caller hears during the ~5-8 sec window it takes the agent to connect. Options: none, text, audio, music, audio_then_music, text_then_music. "X + background music" options are the most polished. |
holdtext |
string | Conditional | Required when holdstrategy ∈ {text, text_then_music}. TTS text: keep to 1 sentence (~5-8s spoken). Hard cap 3000 chars. Supports SSML tags (<break>, <prosody>, <say-as>). |
holdvoice |
enum | Conditional | TTS voice for holdtext. Empty string ("") = use Twilio account default. 20 named voices available (AWS Polly Neural / Generative + Google Chirp3-HD), each tied to a single language: Polly.Joanna-Neural (en-US), Polly.Burcu-Neural (tr-TR), Polly.Lea-Neural (fr-FR), etc. Generative tier is most human-like but priced higher per character. |
holdaudio |
file (MP3/WAV) | Conditional | Required when holdstrategy ∈ {audio, audio_then_music}. Short greeting (5-15 s recommended), mono, max 10 MB. |
holdmusic |
file (MP3/WAV) | Conditional | Required when holdstrategy ∈ {music, audio_then_music, text_then_music}. Background music that loops while the caller waits. Mono, max 10 MB. 30-60 s sweet spot. Use royalty-free music, since you are responsible for licensing. |
Twilio cannot mix speech over music simultaneously: for a voice-over-music intro, pre-mix both into a single audio file and use holdstrategy: audio (or audio_then_music if you also want the loop after).
Credentials schema (as returned by POST /UserAgent/Detail)
"twilio-voice": {
"_connected": true,
"optional": false,
"extra": false,
"accountsid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"authtoken": "••••••••",
"phonenumbers": ["+14155551234"],
"maxcallseconds": 600,
"whitelistedcallers": [],
"holdstrategy": "text_then_music",
"holdtext": "Please hold while we connect you to our assistant.",
"holdvoice": "Polly.Joanna-Neural",
"holdaudio": null,
"holdmusic": "https://cdn.wiro.ai/uploads/.../music.mp3"
}
Call History
Retrieve the last N realtime voice sessions for a useragent, regardless of which channel they came in on.
POST /UserAgent/TwilioCallHistory/List
Despite the Twilio-named path, this endpoint returns both Twilio and Web Channel sessions. Both are stored as agent messages (metadata.type starts with realtime_session in either case), so a single feed is enough to audit every voice exchange the agent had.
curl -X POST "https://api.wiro.ai/v1/UserAgent/TwilioCallHistory/List" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"limit": 50
}'
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Useragent instance guid. Owner / team-member access only. |
limit |
number | No | Max sessions to return. Default 50, hard-capped at 200. Sorted newest-first by message id. |
Response:
{
"result": true,
"errors": [],
"data": [
{
"messageguid": "5d6e7f80-9a1b-4c2d-8e3f-4a5b6c7d8e01",
"agenttoken": "8a5b9e2f-4d3c-4a01-9c2e-1b6d4e7a9c5d",
"channel": "twilio",
"callsid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"callerInfo": { "number": "+15551234567", "country": "US" },
"callerProfile": "Returning caller — last asked about pricing.",
"status": "realtime_session",
"endReason": "wiro_completed",
"durationSeconds": 137,
"modelSlug": "gpt-realtime-mini",
"startedAt": 1730473321000,
"endedAt": 1730473458000
},
{
"messageguid": "0f2a1c3d-9e8b-4c5a-bf42-3a7b6e1d0c8f",
"agenttoken": "1e7d3b9a-5c2f-4d6b-8e0a-2f4c7b5d9e1a",
"channel": "web",
"callsid": "voice-call-9d2d4b6e3f6b4c1a8a7e1f5a0b2c3d4e",
"callerInfo": { "page_url": "https://example.com/contact", "display_identifier": "+15551234567" },
"callerProfile": null,
"status": "realtime_session",
"endReason": "browser_disconnect",
"durationSeconds": 42,
"modelSlug": "gpt-realtime-mini",
"startedAt": 1730463668000,
"endedAt": 1730463710000
}
]
}
| Field | Type | Description |
|---|---|---|
messageguid |
string | The guid of the message that records this session. Use it with POST /UserAgent/Message/Detail to fetch the full transcript metadata. |
agenttoken |
string | The per-message agent token. Use it on Message/Detail / Message/Cancel like any other agent message. |
channel |
"twilio" | "web" |
Source channel. Determines the callerInfo shape and whether callsid is a Twilio Call SID or a Web session id. |
callsid |
string | null | Twilio Call SID (channel: "twilio") or internal voice-call-<id> session id (channel: "web"). |
callerInfo |
object | Channel-specific. Twilio: { number, country } (E.164 phone + ISO-2 country). Web: { page_url, display_identifier? }, where display_identifier is omitted unless the embedding page validated an identifier (session_metadata.display_identifier whose whole-string match passes the allowlist). |
callerProfile |
string | null | Free-text summary of the caller that the agent writes before the call. null until it is ready, and on rejected calls. |
status |
string | Mirrors the message's metadata.type verbatim. Values: realtime_session_incoming (call accepted, prep running), realtime_session_active (audio bridge live), realtime_session_rejected (rejected before audio, e.g. concurrent-limit), or realtime_session (no suffix: final/completed). The bare realtime_session is the only value that means "ended cleanly". It is not the string "completed". |
endReason |
string | null | Set on completed (realtime_session) rows only. One of: wiro_completed (graceful end), wiro_cancelled, wiro_disconnect, wiro_error, max_duration (the call reached its maximum length, maxcallseconds on Twilio), spend_limit (a spend limit was reached during the call), balance (the balance of the wallet that pays for the call ran out), browser_disconnect (Web only), twilio_disconnect (Twilio only). Rejected rows leave endReason: null and instead carry metadata.reason (concurrent_limit, agent_prep_timeout, realtime_ws_open_failed, realtime_stream_timeout). Fetch it via Message/Detail. |
durationSeconds |
number | null | Wall-clock duration. null while in-progress. |
modelSlug |
string | null | Realtime model used (e.g. gpt-realtime-mini). |
startedAt / endedAt |
number | null | Unix epoch ms. endedAt stays null while the call is in-progress or rejected. |
Live call audio is billed through the int-wiro-aimodels skill, the Wiro AI Models connector, against your own Wiro wallet: you bring your own Wiro API key, and the voice cost is charged to the wallet of the workspace that owns that key. It is not charged to the agent's platform credit pool and writes no POST /UserAgent/TransactionList row. The agent's text turns around the call (the prep turn that briefs the voice model before the voice session starts, and the post-call turn where the agent summarizes and acts on the call) are billed as normal token deducts (type: "deduct", action: "tokens") and show up in TransactionList. Audit call-audio cost from your Wiro AI Models usage (the workspace wallet behind your wiro key); TransactionList accounts only for those text turns.
Pairing With Other Skills
Pair this channel with skills that supply the conversation behavior:
int-google-calendar: read availability + draft appointments during the call.int-hubspot-crm: match caller phone number against CRM contacts and log call outcomes.int-brevo-email/int-sendgrid-email/int-mailchimp-email: draft post-call confirmation or follow-up emails.
The Voice Receptionist preset bundles this channel together with the voice rules and Brevo/HubSpot credentials by default. See Agent Use Cases for the full preset.
Troubleshooting
- All calls fail with signature error: You probably pasted an API Key Secret instead of the live Auth Token. Re-paste from the Live credentials section of the Twilio Console.
- Number isn't in
twilioWebhooksUpdated: The number isn't on the Twilio account whose Account SID you provided. Either buy the number on this account, or import it from the source account. The skip reasonno matching IncomingPhoneNumber on Twilio accountconfirms this. - Caller hears Twilio's default voicemail: The number's Configure with is set to TwiML App or SIP Trunk. Flip it back to Webhook in the Twilio Console, then re-save credentials in Wiro to re-write
VoiceUrl. - Calls cut off at exactly N seconds: That's
maxcallseconds. Raise it for longer use cases. - Caller hears that the call has to end, then the line drops: A spend limit was reached, or the balance of the wallet that pays for the call's audio ran out, during the call. The agent finishes the reply it is giving, a short notice plays, and the call ends. Call History shows
endReasonspend_limitorbalance. - Hold music plays forever, agent never speaks: The agent failed to start the realtime conversation. Check
POST /UserAgent/Logsfor errors. - Caller hears your fallback message but no agent:
maxcallsecondswas reached before the agent connected, or the agent crashed mid-call. CheckPOST /UserAgent/Logs. - Whitelisted caller still gets busy signal: Ensure E.164 format. Twilio normalizes inbound numbers, so if your test phone presents itself as
4155551234instead of+14155551234, the allowlist won't match. Add both forms while testing. - Rotated the Auth Token in Twilio Console: Re-paste the new token in Wiro and save again. The credential save also re-runs the webhook setup.
Related
- Agent Credentials & OAuth
- Agent Skills: toggle skills on/off, configure preferences and crons
- Agent Use Cases: Voice Receptionist preset
- Web Voice: browser-embedded voice for the same agent, shares this page's Call History feed
- Google Calendar Skills: pair for inbound voice booking
- HubSpot Skills: caller identification + CRM logging
- Twilio Voice docs
Web Voice Channel
Embed a real-time voice conversation with a Wiro agent into your own browser app. Used by the Voice Receptionist and Voice Sales Rep preset agents, and by any custom agent that needs an "Open mic" button on a website.
Overview
Toggle util-web-channel on a useragent and a single REST call (POST /UserAgent/Realtime/WebStart) returns everything the browser needs to open an authenticated WebSocket and stream microphone audio straight to the agent. The same agent can also pick up phone calls via Twilio Voice: the two channels share the same realtime runtime and end up in the same Call History.
Skill that powers this channel:
util-web-channel: browser voice channel. Bundled on the Voice Receptionist and Voice Sales Rep presets; toggle it on for any other agent viaPOST /UserAgent/SkillsApply.
Agents that typically enable this channel:
- Voice Receptionist: phone + browser receptionist.
- Voice Sales Rep: outbound sales rep with an "Open mic" CTA.
- Custom agents that need a voice button on a website or web app.
Web channel or Twilio channel? Pick by where the caller comes from:
| Channel | Caller comes from | When to use |
|---|---|---|
| Web (this page) | Browser mic on your site | "Open mic" button on a product / support / sales page. No phone number, no per-minute Twilio bill. |
| Twilio | Inbound PSTN phone call | A real phone number ringing. Twilio bills per inbound minute. |
No third-party billing on this channel. The live call audio is billed through the int-wiro-aimodels skill, the Wiro AI Models connector, against your own Wiro wallet (you bring your own Wiro API key). It is not charged to the agent's platform credit pool. The voice-prep turn and the post-call text turn are billed as normal token deducts (action: "tokens") on POST /UserAgent/TransactionList.
Availability
| Mode | Status | Notes |
|---|---|---|
| Bearer auth (wiro.ai dashboard session) | Available | Requests must come from wiro.ai. From your own site, call WebStart from your backend with an API key. |
x-api-key (project API key) |
Available | No Origin check. Use this when proxying through your own backend, or when embedding the voice button in a non-Wiro origin. |
Prerequisites
- A Wiro API key (see Authentication).
- A deployed agent in
status: 4(Running), see Agent Overview. Voice Receptionist / Voice Sales Rep presets work out of the box; for custom agents, enableutil-web-channelviaPOST /UserAgent/SkillsApply. - A browser that can capture microphone audio at 24 kHz mono PCM (every evergreen browser via
getUserMedia+ Web Audio).
Setup
Step 1: Start a session with POST /UserAgent/Realtime/WebStart
Issues two opaque, one-time handles, both valid until expiresAt (5 minutes after issue): a sessionToken the browser presents to the WebSocket on first connect, and a cancelToken for Realtime/Cancel. No API key ever needs to reach the browser.
curl -X POST "https://api.wiro.ai/v1/UserAgent/Realtime/WebStart" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "your-useragent-guid",
"session_metadata": {
"page_url": "https://yourapp.com/agents/sales-rep",
"display_identifier": "Acme Inc."
}
}'
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Useragent instance guid. Must be an agent you deployed (for a team agent, call with that team's project key or workspace, or remain an active member of the team), must be in status: 4 (Running), and must have util-web-channel enabled. |
session_metadata |
object | No | Optional caller context surfaced to the agent + later to Call History. |
session_metadata.page_url |
string | No | The page URL the caller opened the mic from. Up to 2048 chars. Echoed back as callerInfo.page_url. |
session_metadata.display_identifier |
string | No | Operator-supplied display name (e.g. logged-in customer name, account name). 1-100 chars matching ^[\p{L}\p{N} @._\-'+]+$ (Unicode letters / numbers / spaces / @ . _ - ' +). The check is whole-string: any character outside the allowlist (newlines, tabs, ampersands, backticks, $, etc.) silently rejects the entire field (callerInfo.display_identifier ends up null). Pre-sanitize on your side if you accept arbitrary input. |
Response:
{
"result": true,
"correlationId": "voice_3fK9xQ2LmVb7TzR1pWc8NdYa",
"wsUrl": "wss://socket.wiro.ai/v1/AgentRealtime/Web",
"sessionToken": "<opaque one-time session handle>",
"cancelToken": "<opaque one-time cancel handle>",
"expiresAt": 1748212800000,
"estimatedReadyMs": 8000
}
| Field | Description |
|---|---|
correlationId |
Random public identifier for this session. Use it as the audio frame prefix (Step 2); server audio frames and the Realtime/Cancel response carry it too. |
wsUrl |
Environment-specific WebSocket URL: pass it back to the browser verbatim, don't hardcode the host. Production lives at wss://socket.wiro.ai/v1/AgentRealtime/Web. |
sessionToken |
Opaque one-time handle, valid until expiresAt; don't parse it. Send it as the first WebSocket message ({ type: "session_start", sessionToken }); it works only once. |
cancelToken |
Opaque one-time handle for Realtime/Cancel (Step 3), valid until expiresAt. Only the user who called WebStart can use it. |
expiresAt |
Expiry of both handles, in ms since epoch (5 minutes after issue). After this point, call WebStart again for fresh handles. |
estimatedReadyMs |
Approximate time (ms) until the agent will be ready to speak after WS connect. The real "ready" signal is the { type: "ready" } frame on the WebSocket. |
The endpoint also gets the agent ready for the call, so it can answer as soon as the browser connects. If the browser never connects (mic permission denied, user changed their mind), call Realtime/Cancel to release the session right away.
Step 2: Connect the WebSocket
Open a WebSocket to the returned wsUrl and send the session_start JSON frame within 10 seconds. After that, frame microphone audio as 24 kHz mono PCM int16 with a <correlationId>| text prefix. Server-sent binary audio frames use the same prefix shape, so you must strip it before feeding the bytes to Web Audio.
The example below boots a working voice call end-to-end: it acquires the mic, mounts an AudioWorklet that emits 24 kHz Int16 PCM, opens the WebSocket, presents the token, handles every server frame the bridge actually sends, and plays the agent's audio back through AudioContext. Drop it into a page paired with the worklet at audio-processor.js shown below.
// ===== voice-client.js — runs in the browser =====
// 1. POST /UserAgent/Realtime/WebStart from YOUR backend, then pass the
// correlationId / wsUrl / sessionToken / cancelToken down to the page.
// Never expose your Wiro API key to the page.
const { correlationId, wsUrl, sessionToken, cancelToken } = await fetch("/api/voice/start").then((r) => r.json());
const audioCtx = new AudioContext({ sampleRate: 24000 });
await audioCtx.audioWorklet.addModule("/audio-processor.js");
let playbackCursor = 0;
const scheduledNodes = new Set();
let interruptActive = false;
function playPcmInt16(pcm) {
const f32 = new Float32Array(pcm.length);
for (let i = 0; i < pcm.length; i++) f32[i] = pcm[i] / 32768;
const buf = audioCtx.createBuffer(1, f32.length, 24000);
buf.copyToChannel(f32, 0);
const node = audioCtx.createBufferSource();
node.buffer = buf;
node.connect(audioCtx.destination);
const startAt = playbackCursor < audioCtx.currentTime ? audioCtx.currentTime : playbackCursor;
scheduledNodes.add(node);
node.onended = () => scheduledNodes.delete(node);
node.start(startAt);
playbackCursor = startAt + buf.duration;
}
function flushPlayback() {
for (const node of scheduledNodes) { try { node.stop(); } catch {} }
scheduledNodes.clear();
playbackCursor = audioCtx.currentTime;
}
// 2. Open the WebSocket and present the token as the first message.
const ws = new WebSocket(wsUrl);
ws.binaryType = "arraybuffer";
ws.addEventListener("open", () => {
ws.send(JSON.stringify({ type: "session_start", sessionToken }));
});
ws.addEventListener("message", async (event) => {
if (event.data instanceof ArrayBuffer) {
if (interruptActive) return;
const u8 = new Uint8Array(event.data);
const pipe = u8.indexOf(0x7c); // '|'
if (pipe < 0) return;
const pcmBytes = u8.subarray(pipe + 1);
const pcm = new Int16Array(pcmBytes.buffer, pcmBytes.byteOffset, pcmBytes.byteLength / 2);
playPcmInt16(pcm);
return;
}
const msg = JSON.parse(event.data);
switch (msg.type) {
case "connecting": onConnecting?.(); break;
case "ready": await startMicCapture(); break;
case "transcript":
appendTranscript(msg.role, msg.text, msg.ts); // role: "user"|"ai"
break;
case "clear":
flushPlayback();
interruptActive = true;
break;
case "resume":
interruptActive = false;
break;
case "session_end":
onEnded?.(msg.reason, msg.message || msg.error);
try { ws.close(); } catch {}
break;
}
});
// 3. Mic capture pipeline.
let micStream, workletNode;
async function startMicCapture() {
micStream = await navigator.mediaDevices.getUserMedia({
audio: { echoCancellation: true, noiseSuppression: true, sampleRate: 24000 },
});
const source = audioCtx.createMediaStreamSource(micStream);
workletNode = new AudioWorkletNode(audioCtx, "pcm-24k-processor");
source.connect(workletNode);
const sessionMarker = new TextEncoder().encode(correlationId);
workletNode.port.onmessage = (e) => {
const pcmBytes = new Uint8Array(e.data);
const frame = new Uint8Array(sessionMarker.length + 1 + pcmBytes.byteLength);
frame.set(sessionMarker, 0);
frame[sessionMarker.length] = 0x7c; // '|'
frame.set(pcmBytes, sessionMarker.length + 1);
if (ws.readyState === WebSocket.OPEN) ws.send(frame);
};
}
// 4. UI hooks.
function muteMic(on) {
// Mute is purely client-side — the bridge has no server-side mute handler.
micStream?.getAudioTracks().forEach((t) => (t.enabled = !on));
}
function bargeIn() { ws.send(JSON.stringify({ type: "interrupt" })); }
function endCall() { ws.send(JSON.stringify({ type: "end" })); }
// ===== audio-processor.js — served from your origin, registered above =====
class PCM24kProcessor extends AudioWorkletProcessor {
constructor() { super(); this.buffer = new Float32Array(0); }
process(inputs) {
const input = inputs[0]?.[0];
if (!input) return true;
const merged = new Float32Array(this.buffer.length + input.length);
merged.set(this.buffer);
merged.set(input, this.buffer.length);
this.buffer = merged;
while (this.buffer.length >= 4800) {
const chunk = this.buffer.slice(0, 4800);
this.buffer = this.buffer.slice(4800);
const i16 = new Int16Array(chunk.length);
for (let i = 0; i < chunk.length; i++) {
const s = Math.max(-1, Math.min(1, chunk[i]));
i16[i] = s < 0 ? s * 0x8000 : s * 0x7fff;
}
this.port.postMessage(i16.buffer, [i16.buffer]);
}
return true;
}
}
registerProcessor("pcm-24k-processor", PCM24kProcessor);
Sample rate trick. Browsers treat getUserMedia({audio:{sampleRate:24000}}) as a hint, not a guarantee, and most capture at 48 kHz. The AudioContext({sampleRate: 24000}) wrapper does the resampling for you on the MediaStreamSource → AudioWorkletNode graph, so the worklet always sees 24 kHz Float32 input. If you create the context at any other rate you'll ship the wrong sample rate and the agent will sound chipmunked or slowed.
Step 3 (optional): Cancel a stale session with POST /UserAgent/Realtime/Cancel
If the browser can't progress past WebStart (mic permission denied, user navigated away, tab crashed), call Realtime/Cancel to release the session right away; otherwise it is released after about 5 minutes. Send the cancelToken from WebStart, authenticated as the user who called WebStart; each cancel handle works once.
curl -X POST "https://api.wiro.ai/v1/UserAgent/Realtime/Cancel" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"cancelToken": "CANCEL_TOKEN_FROM_WEBSTART"
}'
| Parameter | Type | Required | Description |
|---|---|---|---|
cancelToken |
string | Yes | The cancelToken returned by WebStart. One-time, valid until expiresAt; only the user who called WebStart can use it. |
Response:
{ "result": true, "correlationId": "voice_3fK9xQ2LmVb7TzR1pWc8NdYa", "cancelled": true }
| HTTP | Error | When |
|---|---|---|
| 400 | cancelToken required |
cancelToken is missing. |
| 401 | invalid token |
Unknown, already used or expired handle. |
| 403 | access denied |
The handle was issued to another user. |
No-op when the session has already ended. The endpoint always returns cancelled: true on success, and there's no separate "already cleaned" signal. Reusing a cancel handle returns invalid token.
WebSocket Protocol
The browser bridge lives at wss://<env>/v1/AgentRealtime/Web.
First message (text frame)
{ "type": "session_start", "sessionToken": "<sessionToken-from-WebStart>" }
Must arrive within 10 seconds of the WebSocket open event. Late or malformed → the server closes the socket with no further messages. The handle works once and only until expiresAt; an unknown, used or expired handle closes the socket the same way. The URL carries no session identifier.
Audio frames (binary, both directions)
| Field | Format |
|---|---|
| Audio | PCM int16, 24 kHz, mono. |
| Frame | <correlationId>|<binary-pcm>: UTF-8 text prefix (the correlationId returned by WebStart) + | (0x7C) separator + raw PCM bytes. Same shape as the Realtime Voice Conversation channel. Both directions use this prefix: when you receive a binary frame from the server you must locate the first 0x7C byte and slice everything after it as Int16Array. |
The bridge transcodes server-side if a downstream model needs a different sample rate, so you always send 24 kHz from the browser.
Browser → server control frames (text)
| Body | Effect |
|---|---|
{ "type": "interrupt" } |
Cuts the agent mid-sentence (barge-in). Use this when the user starts speaking again before the agent finishes. The bridge confirms with a clear frame back. |
{ "type": "end" } |
Graceful disconnect: the bridge flushes its buffers, emits a final transcript + session_end frame, then closes. |
Mute is client-side, not a server frame. The bridge has no mute handler, so toggle the mic MediaStreamTrack.enabled = false (or stop posting audio frames from your worklet) instead. Sending {type:"mute"} is silently ignored.
Server → browser frames
| Body / type | Notes |
|---|---|
{ "type": "connecting" } |
Sent right after the bridge accepts your session_start. Handshake is in progress; the realtime model is being warmed up. UI can show a "connecting" state. |
{ "type": "ready" } |
Agent prep + model session are live; start the mic-capture pipeline and send audio frames from this point on. |
{ "type": "transcript", "role": "user"|"ai", "text": "…", "ts": <epoch-ms> } |
Live transcript pair, same content that goes into the operator panel chat. Note the field name is text (not content) and the agent role is "ai" (not "agent"). ts is server time in ms since epoch. |
{ "type": "clear" } |
Barge-in confirmation: the bridge has discarded the agent utterance still in flight. Drop every AudioBufferSourceNode you've already scheduled and stop appending new audio until you see resume. |
{ "type": "resume" } |
A new agent utterance is starting after a clear. Resume normal binary-frame playback. |
| Binary frame | Agent audio chunk: <correlationId>|<int16-pcm-24khz-mono>. Strip the prefix and feed the PCM tail to Web Audio. |
{ "type": "session_end", "reason": "...", "message"?: "..." } |
Terminal frame, immediately followed by a clean ws.close(1000, …). All errors and graceful ends arrive here. There is no separate error frame. reason is rejected (the call could not start or was turned away), spend_limit (a spend limit was reached during the call), balance (the balance ran out during the call) or ended (any other end; Call History has the detail in endReason). message, when present, is a short sentence you can show. With spend_limit and balance the bridge lets the reply that is playing finish first and sends no message, so show your own text. |
Session lifetime
- The
sessionTokenhandle is valid for 300 seconds from issue (untilexpiresAt) and works once, so the browser must sendsession_startbefore then. To connect again, callWebStartfor fresh handles, since there's no in-band refresh. - Once the bridge accepts your
session_startframe, the 5-minute release timer no longer applies to the call. Live call audio is billed throughint-wiro-aimodelsagainst your own Wiro wallet; the time before the browser connects carries no audio charge.
Rate Limits
- 60 sessions / hour per operator (fixed window).
- Sessions that fail to start are not counted.
- Origin check (Bearer auth only): browser requests must come from wiro.ai. API-key requests have no Origin check.
Common Errors
| HTTP | Error code | Message | When |
|---|---|---|---|
| 200 | none | useragentguid required |
Missing useragent reference. |
| 403 | 95 |
useragent-not-found |
The guid doesn't exist (note: returned as 403, not 404). |
| 403 | 96 |
useragent-access-denied |
Caller didn't deploy the useragent. |
| 200 | none | This agent belongs to a team. Switch to the team context to access it. |
Team agent called from a personal workspace or personal project key by a caller who is no longer a member of the agent's team. |
| 200 | none | This agent belongs to a different team. |
Team agent called from another team's workspace or project key by a caller who is no longer a member of the agent's team. |
| 200 | none | Agent is not running |
Useragent is not in status: 4. Start it via POST /UserAgent/Start first. |
| 200 | none | util-web-channel not enabled |
Toggle util-web-channel via POST /UserAgent/SkillsApply (custom agents) or pick a preset that bundles it (Voice Receptionist / Voice Sales Rep). |
| 403 | none | Web voice from this origin needs an API key. |
Bearer auth call with an Origin outside the Wiro allow-list. Either switch to API-key auth or call from an allow-listed origin. |
| 429 | none | Rate limit: max N web voice sessions per hour |
Operator burned through the per-hour cap. Wait for the fixed-window expiry. |
| 500 | none | internal error |
Unexpected backend failure: check POST /UserAgent/Logs for context. |
Session Handles
sessionToken and cancelToken are opaque, random and single-use, valid until expiresAt. Nothing readable travels in a handle or in the WebSocket URL. Call WebStart from your own backend with your API key, and pass only the handles to the browser.
Related
- Twilio Voice: pair the same agent with a real phone number for inbound PSTN calls. Both channels surface in the same Call History feed.
- Realtime Voice Conversation: the underlying model-level realtime protocol (used by
wiro.ai/models/openai/gpt-realtime-mini, etc.). Web Channel is the agent-aware wrapper around it. - Agent Overview: useragent statuses, token-based credit metering, and the rest of the agent surface.
- Agent Skills: toggling
util-web-channelon any agent. - Agent Use Cases: Voice Receptionist, the preset that ships Web + Twilio channels on by default.
Agent Use Cases
Build products with autonomous AI agents using the Wiro API.
See These Use Cases on the Web
Wiro publishes interactive, fullscreen showcases for the most common agent use cases. Each one walks through a real product story end-to-end (build, deploy, daily operation, brand-voice authoring, scheduled autopilot, and a self-healing climax under an upstream API break), so you can see what the patterns below look like before writing any code.
| Showcase | What you'll see |
|---|---|
| Ad Campaign Manager | Drape Studio (bespoke tailoring) running Google Ads + Meta Ads on autopilot: Brand Voice + Budget Control as plain-English skills, AI video ads, OAuth publish, Day-3 auto-pause, weekly review, and a self-heal under the Google Ads API v14 sunset. |
| App Event Manager | Nova (creative video + effects app): Calendarific holiday scan across 7 markets, Nano Banana Pro dual-aspect covers, multi-language event copy, App Store Connect publish, autonomous monthly briefing, self-heal under a 503. |
| App Review Replies | Prism (photo + video editor): App Store + Google Play replies, Brand Voice + Reply Policy markdown skills, multilingual drafts, dev-team Slack escalation for 1★ crashes, monthly sentiment report, self-heal under token expiry. |
| Barber Booking | Scissor Hands salon: WhatsApp + Google Calendar bookings, multi-staff routing with role-based privacy, customer memory, scheduled daily/monthly digests, self-heal under a Calendar API break. |
| Customer Win-Back | Swift Sweep (chimney + fireplace service): HubSpot CRM segmentation, Brand Voice + Customer Scorer + Seasonal Reminder as markdown skills, AI seasonal covers, batch WhatsApp send, scheduled autumn run, self-heal under a HubSpot v2 → v3 contacts API deprecation. |
| Ecommerce Listings | Coral & Crest (swimwear): 5 Wiro AI models (Virtual Try-On, Product-on-Model, Background Remover, Cover Image, Description), multilingual copy, auto-publish to WordPress + Instagram + Shopify, 84-product Google-Drive bulk-autonomy climax. |
| Restaurant Reviews | Green Bottle Coffee: daily chat-based approvals, scheduled reports, anomaly dispatch, self-heal under a Reviews API deprecation. The "no pitch deck required" demo. |
You can also browse every available pre-built agent at wiro.ai/agents/browse (the visual mirror of POST /Agent/List). Each agent template has its own marketing page at wiro.ai/agents/{slug} (for example wiro.ai/agents/social-manager, wiro.ai/agents/voice-receptionist, or wiro.ai/agents/blog-content-editor) with screenshots, default skills, credential requirements, and live tier pricing. The full URL for each agent in the Available Agents table below is https://wiro.ai/agents/{slug}.
Two Deployment Patterns
Every product built on Wiro agents follows one of two patterns. Choosing the right one depends on whether your users need to connect their own third-party accounts.
Pattern 1: Instance Per Customer
Most agents interact with external services: posting to social media, managing ad campaigns, sending emails. These require OAuth tokens or API keys that belong to the end user. Deploy a separate agent instance for each of your customers.
Why: Each customer connects their own accounts. Credentials are bound to the instance, isolated from other customers. Each instance also has its own computer and browser, so the Screen of a customer's agent shows only that customer's work.
How: Call POST /UserAgent/Deploy once per customer, then use the OAuth flow to connect their accounts.
Real-World Examples
| Your Product | Agent Type | Why Per-Customer |
|---|---|---|
| Digital marketing agency dashboard | Social Manager | Each client connects their own Twitter, Instagram, Facebook, TikTok, LinkedIn |
| Mobile app company | App Review Support | Each app has its own App Store / Google Play credentials |
| E-commerce platform | Google Ads Manager + Meta Ads Manager | Each advertiser connects their own ad accounts |
| Marketing SaaS | Newsletter Manager | Each customer connects their own Brevo/SendGrid/Mailchimp |
| Sales platform | Lead Generation Manager | Each sales team connects their own Apollo/Lemlist |
| Content agency tool | Blog Content Editor | Each client connects their own WordPress site |
| App publisher platform | App Event Manager | Each app has its own App Store credentials |
| Mobile app publisher | Push Notification Manager | Each app has its own Firebase service account |
| Customer engagement tool | Social Manager | Each brand manages their own social presence |
| Phone-receptionist platform for SMBs | Voice Receptionist | Each business has its own Twilio number, HubSpot CRM, and Google Calendar |
| Video marketing tool or agency | Video Creator | Each client brings its own site, brand and test logins, and pays its model runs from its own Wiro project |
Pattern 2: Session Per User
For conversational agents that don't need per-user credentials. One agent instance serves many users, each identified by a unique sessionkey that isolates their conversation history.
Why: No third-party accounts to connect. The agent answers questions using its built-in knowledge or pre-configured data sources.
How: Deploy one instance via POST /UserAgent/Deploy, then send messages with different sessionkey values per user. Deploy it with "chatsetup": "off": your users' messages go out with your API key, which carries your rights, so with setup from chat on, a yes from one of them could change the agent's setup. See Setup From Chat. If you show the agent's Screen in your app, show it only to people who may see every user's work, or turn it off with screen: "off": the agent's one computer shows all of their chats, and Take Control reaches every site its browser is signed in to (see Screen in Your Own App).
About sessionkey: This field is optional. If omitted, messages go into a shared "default" session. Reuse the same sessionkey to continue a conversation (the agent retrieves prior messages as context). Use a fresh UUID to start a new conversation. The common convention is one sessionkey per end-user (e.g. "user-456"), but you can also use it per-thread (e.g. "ticket-2025-0817")
for products that group conversations by topic. See the Agent Messaging guide for how sessions work. The session key is a label, not a WebSocket channel: you follow a turn with its agenttoken and a session with the sessiontoken from Message/History (see Agent WebSocket).
Real-World Examples
| Your Product | Use Case | Why Sessions |
|---|---|---|
| Knowledge base chatbot | Answer questions from documentation | No per-user credentials needed |
| Product recommendation advisor | Suggest products based on conversation | Same catalog for all users |
| Internal company assistant | HR policies, IT help, onboarding | Shared knowledge base |
| Customer support bot | Handle common support questions | No external service connections |
When to Use Which
| Question | Instance Per Customer | Session Per User |
|---|---|---|
| Does each user connect their own social/ad/email accounts? | Yes | No |
| Do credentials differ between users? | Yes | No |
| Is conversation the primary interaction? | Sometimes | Always |
| Does the agent perform actions on behalf of the user? | Yes | Rarely |
| How many instances do you need? | One per customer | One total (or a few) |
Hybrid Pattern
A single product can combine both: a per-customer action agent plus a shared conversational agent sit side by side in the same frontend. For example:
- One Social Manager instance per customer (Pattern 1) to publish posts with their own connected social accounts (System User or OAuth, depending on the provider).
- One shared knowledge-base chat agent (Pattern 2) that answers product, billing, or onboarding questions across all customers, using
sessionkeyto keep each user's chat separate.
The two agents are independent deployments with different useragentguid values. Route user actions to the per-customer instance, and chat questions to the shared instance. Your backend decides which agent handles each request.
Building Your Product
White-Label Chat
Build a fully branded chat experience with no Wiro UI visible to your users.
The deploy flow has three stages: Deploy, Setup (only when the agent has connectors to set up), and Start.
- Deploy an agent via
POST /UserAgent/Deploy: returnsuseragents[0].guidand starts the instance instatus: 6(setup-required). A prepaid Deploy then queues it (status: 2) once its subscription is provisioned. Send"chatsetup": "off"too, so your users' messages can't change the agent's setup; make setup changes from your own backend. -
Setup the connectors (only if the agent template requires them) via one or more
POST /UserAgent/CredentialUpsertcalls,POST /UserAgent/CredentialProjectBindfor the Wiro project, and the matching OAuth flows (see Agent Credentials & OAuth). These calls don't changestatus: on an agent still atstatus: 6, callPOST /UserAgent/Updatewith{ "guid": "<useragent-guid>" }after the last one and checksetuprequiredon its response. While it'strue, the agent cannot start. Once all required connectors are set up, that call flipssetuprequiredtofalseandstatusto0. For Pattern 2 (knowledge-base / chat-only agents) there are no connectors to set up, so this stage is skipped and the agent is ready to start right after Deploy. - Start: a prepaid Deploy already queued the agent, and it goes through
status: 3(starting) →status: 4(running). CallPOST /UserAgent/Startwhen it is stopped (status: 0, for example afterUpdatemoved it out ofstatus: 6) or errored (status: 5). - Build your own chat UI.
- Send messages via
POST /UserAgent/Message/Send. - Stream responses in real-time via Agent WebSocket using the
agenttoken. - Manage conversation history with
POST /UserAgent/Message/History.
See Agent Overview for the full lifecycle state table (status: 0, 1, 3, 4, 5, 6).
To let the people who manage an agent set it up from your chat, with setup cards, connect steps and restarts shown in your own UI, keep chatsetup at "all" and follow Agent Chat Integration.
To show the agent's live Screen in your UI, with Take Control for the people you choose, see Screen and Take Control in Your App.
# Deploy — prepaid + tier are required for API users (credits debit from your wallet)
curl -X POST "https://api.wiro.ai/v1/UserAgent/Deploy" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"agentguid": "agent-template-guid",
"title": "Customer Support Bot",
"useprepaid": true,
"tier": "starter",
"chatsetup": "off"
}'
# Pattern 1 only — fill any missing credentials, then verify setuprequired flipped to false
curl -X POST "https://api.wiro.ai/v1/UserAgent/Detail" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "deployed-useragent-guid" }'
# Start the agent when it is stopped (status 0) or errored (status 5): a prepaid Deploy already queues it
curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "guid": "deployed-useragent-guid" }'
# Send a message
curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/Send" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "deployed-useragent-guid",
"message": "How do I reset my password?",
"sessionkey": "user-456"
}'
Generative Media Studio
A richer variant of white-label chat: besides replying with text, the agent generates images, video, or audio through Wiro AI models and streams them into a live activity feed beside the conversation. This is the pattern behind Wiro's own Studio. It layers the realtime socket on top of the Session-Per-User model.
Shape:
- One deployed agent that has the
int-wiro-aimodelsskill enabled, with its Wiro AI Models connector set to your Wiro project (see Agent Credentials). Media the agent generates is billed to the wallet of the workspace that owns that project (your personal wallet, or the team wallet for a team project). - One
sessionkeyper end user (Pattern 2 above): the same agent instance serves everyone; each user's chat and media history is isolated by session. - A single WebSocket connection carries three things at once: the streaming chat reply, the per-turn token-usage report, and discovery of any model runs the agent launches.
End-to-end sequence an integrator replicates:
- Deploy once (prepaid):
POST /UserAgent/Deploywithuseprepaid: true+tier. Connect the agent's Wiro project withPOST /UserAgent/CredentialProjectBind, thenStart. - Open the socket: connect to
wss://socket.wiro.ai/v1and wait for theconnectedframe. - (Optional) name the session:
POST /UserAgent/Message/RenameSessionseeds a titled, empty session that shows up immediately inMessage/Sessions. - Send a message:
POST /UserAgent/Message/Sendwith the user'ssessionkey. Subscribe{ "type": "agent_info", "agenttoken": "<agenttoken-from-send>" }and streamagent_start → agent_output × N → agent_end. - Patch token usage: ~250-500 ms after
agent_end, anagent_usage_reportframe delivers the turn's token counts,tokencost, andremainingcredits; splice them onto the message bymessageguid. - Collect generated media: when the agent runs a model, an
agent_wiroai_runtaskframe arrives on the sameagenttokenwith asocketaccesstoken. Subscribe to it with{ "type": "task_info", "tasktoken": "<socketaccesstoken>" }and streamtask_queue → task_start → task_output → task_postprocess_end; the final frame carries the output media URLs. See Agent WebSocket → Model runs the agent triggers. - Manage sessions: list with
Message/Sessions, rename withMessage/RenameSession, clear/forget withMessage/DeleteSession(rotate: trueto wipe the agent's memory of the thread).
Either deployment shape works: run one media agent and separate users by sessionkey, or deploy separate agents per workspace/customer. Both use the exact same socket and messaging surface.
Webhook-Driven Pipelines
For backend-to-backend integrations where you don't need real-time streaming.
- Send a message with a
callbackurl - Continue processing other work
- Receive the agent's response via HTTP POST to your webhook endpoint
- Chain the result into your next workflow step
See Agent Webhooks for payload format and retry policy.
curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/Send" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"useragentguid": "deployed-useragent-guid",
"message": "Generate a weekly performance report",
"sessionkey": "pipeline-run-789",
"callbackurl": "https://your-server.com/webhooks/report-ready"
}'
Scheduled Automation
Combine agents with cron jobs for recurring tasks.
Cron (every Monday 9am)
→ POST /UserAgent/Message/Send (with callbackurl)
→ Agent processes the task
→ Webhook fires to your server
→ Your server emails the report / posts to Slack / updates dashboard
This pattern works well for weekly social media content planning, daily ad performance reviews, monthly newsletter generation, and automated lead enrichment pipelines.
Multi-Agent Orchestration
Deploy multiple specialized agents and coordinate them from your backend.
Your Backend
├── Research Agent → "Find trending topics in AI this week"
│ ↓ webhook response
├── Writing Agent → "Write a blog post about: {research results}"
│ ↓ webhook response
└── Publishing Agent → "Publish this post to WordPress and share on social media"
Each agent is an independent instance with its own credentials. Your backend passes output from one agent as input to the next.
Available Agents
Wiro provides pre-built agent templates you can deploy immediately. Each agent specializes in a specific domain and comes with the relevant skills and connectors pre-configured.
| Agent | What It Does | Connectors |
|---|---|---|
| Social Manager | Create, schedule, and publish social media content | Twitter/X, TikTok, LinkedIn (OAuth); Instagram and Facebook Pages (System User recommended or own OAuth) |
| Blog Content Editor | Write and publish blog posts (WordPress draft + publish workflow) | WordPress (App Password), Gmail (optional, for inbox requests) |
| Google Ads Manager | Create and optimize Google Ads campaigns, daily performance reports | Google Ads (OAuth), Calendarific (API key), Google Drive (optional, Service Account) |
| Meta Ads Manager | Manage Facebook and Instagram ad campaigns, audience analysis | Meta Ads (System User recommended or own OAuth), Calendarific (API key), Google Drive (optional, Service Account) |
| Newsletter Manager | Design and send email newsletters to subscriber lists | Brevo, SendGrid, Mailchimp, HubSpot (any one, API key or OAuth) |
| Lead Generation Manager | Find and enrich leads, run multi-channel outreach, analyze replies | Apollo (API key), Lemlist (API key), HubSpot (optional, for CRM sync) |
| App Review Support | Monitor app store reviews, draft responses in operator's tone | App Store Connect (private key JWT), Google Play (service account) |
| App Event Manager | Scan global holidays, suggest and create App Store + Google Play in-app events | App Store Connect (JWT), Google Play (service account), Calendarific (API key) |
| Push Notification Manager | Craft locale- and timezone-aware push notifications, queue dispatch | Firebase (service account JSON per app), Calendarific (API key) |
| Voice Receptionist | Answer phone calls 24/7 with a real-time AI receptionist: recognises callers from CRM, books from your calendar, drafts CRM notes + follow-up emails, streams a live transcript to chat | Twilio Voice (Account SID, Auth Token, phone number) for inbound phone; HubSpot (optional, caller recognition); Google Calendar (optional, slot lookup); Google Drive (optional); Brevo or HubSpot (any one, optional, follow-up email drafts); Telegram bot (optional, operator approvals) |
| Video Creator | Turn a website, web app, store listing, document or product photos into a share-ready video with real screens, voice-over, music and captions | Wiro project (the video's model runs are billed to its wallet); YouTube and Instagram (optional, to publish finished videos); Telegram bot (optional) |
The list above matches the agent templates currently deployed in production. The exact set evolves over time as new templates ship, so fetch POST /Agent/List for the live catalog. Each agent's full marketing page lives at https://wiro.ai/agents/{slug} (linked in the first column).
Deploying an Agent
import requests
headers = {
"x-api-key": "YOUR_API_KEY",
"Content-Type": "application/json"
}
# List available agents
agents = requests.post(
"https://api.wiro.ai/v1/Agent/List",
headers=headers,
json={}
)
print(agents.json())
# Deploy an instance (API users always use prepaid — credits debit from your wallet)
deploy = requests.post(
"https://api.wiro.ai/v1/UserAgent/Deploy",
headers=headers,
json={
"agentguid": "social-manager-agent-guid",
"title": "Acme Corp Social Media",
"useprepaid": True,
"tier": "starter"
}
)
useragent_guid = deploy.json()["useragents"][0]["guid"]
# Connect Twitter via the unified OAuth flow
connect = requests.post(
"https://api.wiro.ai/v1/UserAgentOAuth/OAuthConnect",
headers=headers,
json={
"useragentguid": useragent_guid,
"credentialkey": "twitter",
"redirecturl": "https://your-app.com/settings?connected=twitter"
}
)
authorize_url = connect.json()["authorizeUrl"]
# Redirect your user to authorize_url
# A prepaid Deploy already queued the agent: start it only when it is stopped (0) or errored (5)
instance = requests.post(
"https://api.wiro.ai/v1/UserAgent/Detail",
headers=headers,
json={"guid": useragent_guid}
).json()
if instance["useragents"][0]["status"] in (0, 5):
requests.post(
"https://api.wiro.ai/v1/UserAgent/Start",
headers=headers,
json={"guid": useragent_guid}
)
# Send a message
message = requests.post(
"https://api.wiro.ai/v1/UserAgent/Message/Send",
headers=headers,
json={
"useragentguid": useragent_guid,
"message": "Create a thread about our new product launch",
"sessionkey": "campaign-q2"
}
)
print(message.json())
Browse available agents and their capabilities via POST /Agent/List or in the Wiro dashboard.
Organizations & Teams
Collaborate with your team under a shared workspace with unified billing, access controls, and resource management.
Overview
Wiro supports three workspace contexts for organizing your resources:
- Personal: your default workspace. Projects, agents, and wallet are tied to your individual account.
- Organization: a parent entity that groups one or more teams. The organization owner controls the lifecycle of teams and their members.
- Team: a workspace under an organization with its own wallet, projects, agents, and member permissions. Team members share access to resources deployed within the team.
Personal Account
├── Personal Projects
├── Personal Agents
└── Personal Wallet
Organization (created by you)
├── Team A
│ ├── Team Wallet
│ ├── Team Projects
│ ├── Team Agents
│ └── Members (admins, members)
├── Team B
│ ├── Team Wallet
│ ├── Team Projects
│ ├── Team Agents
│ └── Members
└── ...
Every user always has a personal workspace. Organizations and teams are optional: you can use Wiro entirely in personal mode without ever creating an organization.
Key Concepts
Workspaces and Context
When you make an API request or use the dashboard, you operate in one of two contexts:
| Context | Resources you see | Wallet charged | How to activate |
|---|---|---|---|
| Personal | Your personal projects, agents, tasks | Your personal wallet | Default. In the dashboard, choose Personal with Switch Workspace (or Switch to Personal on the Organizations page); in the API, use a personal project API key |
| Team | Team projects, team agents, team tasks | Team wallet | In the dashboard, choose the team with Switch Workspace (or Switch on the Organizations page); in the API, use a team project API key |
Switching context changes which projects, agents, and wallet you interact with. Resources in one context are isolated from the other: personal agents cannot see team projects, and team agents cannot access personal resources.
Resource Isolation
Each workspace is fully isolated:
- Projects belong to either your personal workspace or a specific team. A project's API key automatically resolves the correct context.
- Agents are deployed into a workspace. Team agents are visible to all team members; personal agents are visible only to you.
- Wallet transactions are recorded against the workspace that initiated them. Team tasks deduct from the team wallet; personal tasks deduct from your personal wallet.
- Tasks are tagged with the workspace context and only appear in the matching project usage and statistics views.
Transferring Resources
Projects and agents can be transferred between workspaces:
- Personal → Team: move a project or agent from your personal workspace into a team you have admin access to
- Team → Personal: move a project you created, or an agent you deployed, from a team you have admin access to back to your personal workspace. Only the original creator or deployer can do this.
- Team → Team: move a project or agent between teams you have admin access to in the same or different organizations
When a resource is transferred, its billing context changes immediately. Future tasks on a transferred project will be billed to the new workspace's wallet. Transfer operations are available in the dashboard and via the API. An agent that has been in a team doesn't get Take Control after it moves back to a personal workspace until its owner resets its browser: the browser may still hold team members' sign-ins.
Important: Agents can only access projects in the same workspace. If you transfer a project out of a team, agents in that team can no longer use it.
Organizations vs Teams
An organization is a management container: it does not hold resources directly. All resources (projects, agents, wallets) live inside teams.
| Feature | Organization | Team |
|---|---|---|
| Holds projects and agents | No | Yes |
| Has a wallet | No | Yes |
| Has members | No (members belong to teams) | Yes |
| Can be created by | Any user | Organization owner |
| Can be deleted by | Organization owner | Organization owner |
| Can be restored | Yes, by the owner | No separate restore. Teams archived when their organization was deleted come back when it is restored |
Restoring an organization does not move projects or agents back into its teams. They stay in the personal workspaces of the people who created or deployed them until transferred back.
A single user can own multiple organizations, and each organization can contain multiple teams.
Roles
| Role | Scope | Permissions |
|---|---|---|
| Owner | Organization | Create and remove teams; edit, remove, and restore the organization. The owner is added as an admin of every team they create and can't be demoted to member, so they also have all Admin permissions there |
| Admin | Team | Edit team settings (name and description); set the team's spend limits, member limits included, and its Model Access rules; invite members and cancel invitations; change roles; remove members; deploy and manage team agents; edit and delete team projects; transfer agents, projects, and credit; redeem coupons into the team wallet; set up, change, and turn off the team wallet's auto-pay |
| Member | Team | Run models and create projects in the team workspace (billed to the team wallet), chat with team agents, and view the member list, the team's spend limits and Model Access rules, and every member's spending |
The organization creator is automatically the owner. When the owner creates a team, including the Default Team created with the organization, they are added to it as an admin member. Additional members are invited by email and join once they accept the invitation, signed in with the invited email address, within 72 hours.
On a team agent whose Chat Mode is "collaborative", the team's admins and the agent's owner can watch its Screen in the Wiro panel, and an app can show it through a team project's API key that one of them created; other members can't. Nobody can take control of a team agent's computer.
Getting Started
- Create an organization: go to your Dashboard and click "Create Organization". A team named "Default Team" is created automatically, with you as its admin.
- Add more teams (optional): as the organization owner, click "Create Team" on the organization card to add another team, for example one per project
- Invite members: send email invitations to your teammates
- Fund the team wallet: switch to the team workspace and add credit. Admins and the owner can also move credit from their personal wallet with Transfer Credit and redeem coupons into the team wallet
- Create projects: with the team workspace selected, create API projects. Their API keys run models on the team wallet
- Deploy agents: team admins can deploy agent instances within the team for shared access
For step-by-step instructions, see Managing Teams.
What's Next
- Managing Teams: Create organizations, invite members, manage roles and permissions
- Team Billing & Spending: Wallets, spend limits and their alert emails, and Model Access rules
- Team API Access: How workspace context works with API keys and context guards
Managing Teams
Create organizations, invite members, and manage roles and permissions.
Creating, changing, deleting or restoring organizations and teams, managing members and invitations, and moving projects, agents or credit all need a signed-in user, as in the dashboard. With an API key these calls fail with HTTP 401 (see Team API Access).
POST /Organization/Create
Creates a new organization. The caller automatically becomes the organization owner, and only the owner can create teams, delete the organization, or restore it after deletion. A team named Default Team is created with it automatically: the caller is added as its admin, and it gets its own wallet (starting at $0.00), no spend limits and no Model Access rules, so it can run every model. Use /Team/Create only for additional teams.
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Organization name |
Response
{
"result": true,
"errors": [],
"organization": [
{
"guid": "1b43089c-3b56-4638-b4ac-24268bb1d970",
"name": "Acme Corp",
"description": null,
"owneruuid": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"status": 1,
"teams": [
{
"guid": "7c1e5a90-2f3b-4d8e-a6c4-9b0d1e2f3a45",
"organizationguid": "1b43089c-3b56-4638-b4ac-24268bb1d970",
"name": "Default Team",
"status": 1
}
]
}
]
}
You can also create organizations from the Dashboard.
POST /Team/Create
Creates a team inside an organization. Only the organization owner can create teams. The team is created with its own wallet (starting at $0.00) and the caller is automatically added as an admin. To choose which models the team can run, add Model Access rules.
| Parameter | Type | Required | Description |
|---|---|---|---|
organizationguid |
string | Yes | Organization guid |
name |
string | Yes | Team name |
Response
{
"result": true,
"errors": [],
"team": [
{
"guid": "0d9aade4-d31b-4b97-88f3-a90482f080ea",
"organizationguid": "1b43089c-3b56-4638-b4ac-24268bb1d970",
"name": "Engineering",
"description": null,
"status": 1
}
]
}
POST /Team/Member/Invite
Sends an email invitation to add a new member to the team. Invitations expire after 72 hours. Organization owners and team admins can invite members.
Inviting an address that already has an unexpired invitation to the team, or that belongs to an active member who joined through an invitation, fails with This email is already invited or a member. To send a new invitation, cancel the current one with /Team/Member/CancelInvite (or wait until it expires) and invite the address again.
| Parameter | Type | Required | Description |
|---|---|---|---|
teamguid |
string | Yes | Team guid |
email |
string | Yes | Invitee email address |
role |
string | No | Role: "admin" or "member". Defaults to "member"; any other value is treated as "member" |
Response
{
"result": true,
"errors": [],
"member": [
{
"guid": "5f0c2b8e-7d4a-4e21-9c3b-2a6f1e8d9b10",
"teamguid": "0d9aade4-d31b-4b97-88f3-a90482f080ea",
"useruuid": null,
"role": "member",
"status": "pending",
"inviteemail": "teammate@example.com",
"inviteexpiry": "1757923200"
}
]
}
inviteexpiry is the invitation's expiry time as a Unix timestamp in seconds. The response doesn't include the invitation token, and neither does /Team/Member/List: the token is only sent to the invitee, in the invitation email.
Invitation States
| Status | Description |
|---|---|
pending |
Invitation sent, waiting for the user to accept. An expired invitation stays pending until it is cancelled or replaced by a new invitation |
active |
User accepted the invitation and is an active member |
removed |
Member was removed or invitation was cancelled |
POST /Team/Member/CancelInvite
Cancels a pending invitation. Organization owners and team admins can cancel invitations. The invitation link stops working and the entry changes to removed.
| Parameter | Type | Required | Description |
|---|---|---|---|
teammemberguid |
string | Yes | The pending invitation's guid from /Team/Member/List |
POST /Team/Member/Accept
The Accept Invite button in the invitation email opens the Team Invitation page on wiro.ai. If you are signed out, the page shows who invited you and the organization and team names; choose Sign In to Accept or Create Account, and you are brought back to the invitation afterwards. If you are already signed in, the invitation is accepted automatically and you are taken to the Organizations page.
The invitation can only be accepted by a Wiro account whose email address matches the invited address. When calling the endpoint directly, send the request as the signed-in invitee. When the organization owner accepts an invitation to one of their teams, they join as an admin, whatever role the invitation set.
| Parameter | Type | Required | Description |
|---|---|---|---|
invitetoken |
string | Yes | Invitation token: the value of the token query parameter in the invitation link |
| Error | Cause |
|---|---|
Please sign in or sign up to accept this invitation |
The request was not made by a signed-in user (error code 98) |
This invitation was sent to a different email address |
The signed-in account's email address does not match the invited address |
This invitation has expired or is no longer valid |
The invitation expired, was cancelled or already accepted, or its team was deleted |
Member Roles
| Role | Run models | Message agents | View spending | Manage settings | Invite members | Remove members | Delete team |
|---|---|---|---|---|---|---|---|
| Owner | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| Admin | Yes | Yes | Yes | Yes | Yes | Yes | No |
| Member | Yes | Yes | Yes | No | No | No | No |
The organization owner is added as an admin of every team they create, including the Default Team. The owner is always an admin of their teams: nobody, the owner included, can change the owner's role to member, and nobody but the owner can remove the owner from a team. The owner role cannot be transferred.
On a team agent whose Chat Mode is "collaborative", admins and the agent's owner can also watch the agent's Screen in the Wiro panel, or show it in an app through a team project's API key that one of them created; other members can't. Nobody can take control of a team agent's computer.
POST /Team/Member/List
Lists all members of a team, including pending invitations. Any active member of the team can call it. Use a member's guid as teammemberguid in /Team/Member/UpdateRole, /Team/Member/Remove and /Team/Member/CancelInvite.
| Parameter | Type | Required | Description |
|---|---|---|---|
teamguid |
string | Yes | Team guid |
Response
{
"result": true,
"errors": [],
"member": [
{
"guid": "a3c9e1f2-4b7d-4c1e-9f2a-6d8b0e5c7a91",
"teamguid": "0d9aade4-d31b-4b97-88f3-a90482f080ea",
"useruuid": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"role": "admin",
"status": "active",
"user": {
"firstname": "John",
"lastname": "Doe",
"email": "john@example.com",
"avatar": "https://cdn.wiro.ai/avatars/johndoe.webp",
"avatarinitials": "JD"
}
},
{
"guid": "5f0c2b8e-7d4a-4e21-9c3b-2a6f1e8d9b10",
"teamguid": "0d9aade4-d31b-4b97-88f3-a90482f080ea",
"useruuid": null,
"role": "member",
"status": "pending",
"inviteemail": "jane@example.com",
"inviteexpiry": "1757923200"
}
]
}
POST /Team/Member/Remove
Removes a member from the team. Organization owners and team admins can remove members. The removed member immediately loses access to the team workspace and is notified by email. Removed members can be re-invited later if needed.
- A team must always keep at least one admin. Removing the last admin fails with
Cannot remove the last admin of the team. Assign another admin first. - Regular members cannot remove themselves; a team admin or the organization owner has to remove them.
- Another admin can't remove the organization owner from a team: the request fails with
Only the organization owner can remove the owner from this team. The owner can remove themselves. - Only active members can be removed. To withdraw a pending invitation, use
/Team/Member/CancelInvite. - Team projects stay in the team. The API keys of the projects the removed member created stop working right away, unless that member is the organization owner. Apps and agents that use those keys lose access too, so move them to a key from another member's project before you remove someone. Keys of projects other members created keep working for anyone who has them: if the removed member had one, delete that project. Changing the project's IP whitelist issues a new API secret, so old signatures stop working on a Signature-Based project, but an API Key Only project's key keeps working from any IP still on its whitelist.
| Parameter | Type | Required | Description |
|---|---|---|---|
teammemberguid |
string | Yes | The member's guid from /Team/Member/List |
POST /Team/Member/UpdateRole
Updates a member's role in the team. Team admins and the organization owner can change a member's role between admin and member. A team must always keep at least one admin: demoting the last admin fails with Cannot demote the last admin. Assign another admin first. Nobody, the owner included, can change the organization owner's role to member: the request fails with The organization owner is always an admin of their teams and can't be made a member.
| Parameter | Type | Required | Description |
|---|---|---|---|
teammemberguid |
string | Yes | The member's guid from /Team/Member/List |
role |
string | Yes | New role: "admin" or "member" |
The call changes only the role. To cap what a member can spend in the team, add a member limit with /SpendLimit/Set (scope: "member", with the member's useruuid as target), or under Controls > Spend Limits in the dashboard.
POST /Team/Remove
Deletes a team. Only the organization owner can delete a team. Deleting a team:
- Soft-deletes the team (sets status to
0) - Removes all team members and cancels pending invitations
- Moves each team agent back to the personal workspace of the user who deployed it; its active subscriptions and credit purchases move with it, the agent is restarted, and future agent billing goes to that user's personal wallet; Take Control stays off for it until that user resets its browser, as for any agent that has been in a team
- Moves each team project back to the personal workspace of the user who created it; its API key keeps working and future tasks are billed to that user's personal wallet
The team's wallet balance is not automatically transferred. Move it out with Transfer Credit before deleting the team; after deletion, contact support to recover it.
| Parameter | Type | Required | Description |
|---|---|---|---|
teamguid |
string | Yes | Team guid |
POST /Organization/Remove
Deletes an organization. Only the organization owner can delete an organization. Deleting an organization soft-deletes it and archives the teams and members that are active at that moment, so /Organization/Restore can bring exactly those back. Each team is removed the same way as with /Team/Remove: members are removed, pending invitations are cancelled, agents go back to the personal workspace of the user who deployed them (with Take Control off until that user resets the agent's browser, as for any agent that has been in a team), and projects go back to the personal workspace of the user who created them. Team wallet balances are not moved.
| Parameter | Type | Required | Description |
|---|---|---|---|
organizationguid |
string | Yes | Organization guid |
POST /Organization/Restore
Restores a soft-deleted organization. Only the organization owner can restore it. Restoring an organization:
- Reactivates the organization and only the teams that were active when it was deleted. Teams deleted earlier with
/Team/Removestay deleted - Reactivates only the members who were active in those teams when the organization was deleted. Members removed earlier stay removed
- Invitations stay cancelled, including those that were pending when the organization was deleted; invite those people again
- Does not move projects or agents back into the teams: they stay in the personal workspaces they were returned to when the organization was deleted. The user who created a project or deployed an agent can move it back with
/Team/TransferProjector/Team/TransferAgent, provided they are an admin of the team or the organization owner
Some organizations can't be restored automatically: those deleted before Wiro started recording which teams and members were removed with them, and those whose teams had all been deleted before the organization was. For these, the call fails with This organization can't be restored automatically because we can't tell which of its teams and members were removed with it. Please contact support. and nothing changes. Contact support to have them restored.
| Parameter | Type | Required | Description |
|---|---|---|---|
organizationguid |
string | Yes | Organization guid |
POST /Organization/List
Returns all organizations you belong to, including active and deleted ones. Each organization lists the teams you are a member of, with your role and your own membership memberguid. You own an organization when its owneruuid is your user UUID.
Response
{
"result": true,
"errors": [],
"organizations": [
{
"guid": "1b43089c-3b56-4638-b4ac-24268bb1d970",
"name": "Acme Corp",
"avatar": null,
"owneruuid": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"status": 1,
"teams": [
{
"guid": "0d9aade4-d31b-4b97-88f3-a90482f080ea",
"name": "Engineering",
"status": 1,
"role": "admin",
"memberguid": "a3c9e1f2-4b7d-4c1e-9f2a-6d8b0e5c7a91",
"walletbalance": 142.50
}
]
}
]
}
POST /Team/TransferAgent
Transfers an agent instance between workspaces: personal to team, team to personal, or team to team. On the team side you must be an admin of that team or the organization owner. On the personal side you must be the user who originally deployed the agent: only the deployer can move an agent from their personal workspace into a team, and only the deployer can move it from a team to their personal workspace.
| Parameter | Type | Required | Description |
|---|---|---|---|
useragentguid |
string | Yes | Agent instance guid |
targetteamguid |
string | Yes | Target team guid, or empty string "" for personal |
When an agent is transferred:
- The agent's
teamguidis updated - Active subscriptions and credit purchases move with the agent
- Its chat history moves with it
- The agent is restarted with the new context
- Future billing is charged to the new workspace's wallet
- Take Control stays off for an agent that has been in a team after it moves back to a personal workspace, until its owner resets its browser: the browser goes with it, signed in wherever the team's chats signed in
POST /Team/TransferProject
Transfers a project between workspaces. Future tasks on the project are billed to the new workspace's wallet. On the team side you must be an admin of that team or the organization owner. On the personal side you must be the user who created the project: only the creator can move a project from their personal workspace into a team, and only the creator can move it from a team to their personal workspace.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectapikey |
string | Yes | Project API key |
targetteamguid |
string | Yes | Target team guid, or empty string "" for personal |
When a project is transferred:
- The project's
teamguidis updated - Future tasks using this project's API key are billed to the new workspace
- If the user who created the project is neither an active member of the new team nor the organization owner, the project's API key stops working
Important: Agents can only access projects in the same workspace. Transferring a project may break agent workflows that depend on it.
Transferring Credit
Credit can be transferred between your personal wallet and team wallets. Transfers preserve original deposit expiry dates and coupon tracking. See Team Billing & Spending → Credit Transfer for full details.
What's Next
- Organizations & Teams Overview: Concepts and workspace hierarchy
- Team Billing & Spending: Wallets, spend limits, and Model Access rules
- Team API Access: How context works in API requests
Team Billing & Spending
Manage team wallets, transfer credit, and track usage across members.
Team Wallets
Each team has its own wallet, independent of members' personal wallets. When a task runs in a team context, the cost is deducted from the team wallet, never from the individual member's personal wallet.
Funding a Team Wallet
Team wallets are funded the same way as personal wallets, plus credit transfers:
- Deposits: add credit via the dashboard or API while in the team context
- Coupons: team admins and the owner can redeem coupon codes while in the team context (see Coupons below)
- Auto-pay: configure automatic deposits when the balance drops below a threshold. In a team workspace, only team admins and the organization owner can set up, change or turn off auto-pay for the team wallet. Other members can view the settings; if they try to change them, they get
Only team admins can perform this action - Transfer Credit: organization owners and team admins can move balance from their personal wallet or from another team they administer (see
/Team/TransferCreditbelow)
To fund a team wallet, switch to the team workspace in the dashboard and open Credit Balance, then Add to Credit Balance, Automatic Payment, Coupons or Transfer Credit. All deposit and coupon operations target the active workspace.
Checking the Balance
The team wallet balance is visible on the Organization page next to each team, and on the Credit Balance page while the team workspace is selected. When calling /Wallet/List with a team project API key, this returns the team wallet balances instead of your personal wallet.
Balance Checks and Concurrency
In team context, the pre-run balance check and the concurrency limit use the team wallet, not the member's personal wallet. The minimum balance needed to start a task is checked against the team balance. While the team balance is $250 or less, the team can run concurrent tasks equal to 10% of that balance (minimum 1), counted across all members, dashboard runs and team project API keys together. Tasks in your Personal workspace are counted separately against your personal balance.
Spend Limits
Spend limits are not a team setting: they work the same way for a personal account's wallet and for a team's wallet. In a team, the organization owner and team admins can cap the whole team, one member, one API key, a surface such as the LLM gateway, or one agent, per month or per day, under Controls > Spend Limits in the dashboard or with the /SpendLimit endpoints, signed in or with the API key of a project they created. Other members can see the team's limits but can't change them, their own member limit included. See Spend Limits.
Tracking Team Spending
What the team has spent this month or today, by member, API key, surface and agent, comes from /SpendLimit/Usage. For other breakdowns, /Project/UsageSummary gives usage per project and /Task/Stat gives time-series task execution data. Both filter by the active workspace.
Model Access
Model Access is not a team setting: it works the same way for a personal account's wallet and for a team's wallet. In a team, the organization owner and team admins can allow or block single models and whole categories, such as video generation, for the whole team, one member, one API key, a surface such as the LLM gateway, or one agent, under Controls > Model Access in the dashboard or with the /ModelAccess endpoints, signed in or with the API key of a project they created. Other members can see the team's rules but can't change them. A model a rule blocks is refused with error code 92. See Model Access.
POST /Team/Update
Updates a team's name and description. Only the organization owner and team admins can call it, and only while signed in: with an API key it fails with HTTP 401. Spend limits and Model Access rules are not team settings: set them with /SpendLimit/Set and /ModelAccess/Set.
| Parameter | Type | Required | Description |
|---|---|---|---|
teamguid |
string | Yes | Team guid |
name |
string | No | New team name |
description |
string | No | Team description |
POST /Team/TransferCredit
Transfers credit between your personal wallet and team wallets. Useful for moving team budgets around or recovering personal funds. Only organization owners and team admins can transfer credit, and the same user must control both source and target workspaces. Transfers need a signed-in user: with an API key the call fails with HTTP 401.
| Parameter | Type | Required | Description |
|---|---|---|---|
amount |
number | Yes | Transfer amount in USD |
sourceteamguid |
string | No | Source team guid. Empty/omit for personal wallet |
targetteamguid |
string | No | Target team guid. Empty/omit for personal wallet |
Request (personal to team)
{
"amount": 100,
"sourceteamguid": "",
"targetteamguid": "0d9aade4-d31b-4b97-88f3-a90482f080ea"
}
Response
{
"result": true,
"errors": [],
"transferred": {
"total": 100,
"gifted": 50,
"store": 0,
"amount": 50
}
}
The transferred object shows how the amount was split across pools:
gifted: from coupon and checklist creditsstore: from marketplace store revenueamount: from regular deposits
Permissions:
- Personal to team: you must be admin/owner of the target team
- Team to personal: you must be admin/owner of the source team
- Team to team: you must be admin/owner of both teams
How It Works
Transfers preserve the original deposit structure: expiry dates, coupon tracking, and store revenue are all maintained. Every source deposit or coupon that the transfer draws from becomes its own deposit on the target wallet, with the same type and its original expiry time.
Consumption order (matches task billing):
- Coupons: model-specific coupons first, then other coupons, oldest first
- Checklist rewards
- Store revenue
- Deposits
Expiry is preserved: When you transfer $600 from a wallet containing a $500 coupon (30-day expiry) and a $500 deposit (365-day expiry), the target receives two separate deposits, a $500 coupon and a $100 deposit, each with its original expiry date.
Transaction History
Both wallets get a transaction row:
- Source:
TRANSFER OUTwith a description like "Transfer to Engineering (Acme Corp) - $100.00 (Coupons: $50.00 / Store: $0.00 / Deposits: $50.00)." - Target:
TRANSFER INwith a description like "Transfer from personal - $100.00 (Coupons: $50.00 / Store: $0.00 / Deposits: $50.00)."
TRANSFER OUT and TRANSFER IN rows record the transfer; moved credit keeps its original expiry.
Important Behaviors
- Auto-pay may trigger: If the source wallet (personal or team) has auto-pay enabled and the transfer takes its deposited balance below the auto-pay threshold, the next auto-pay check charges the saved card. The confirmation dialog doesn't warn about this, so check the source's auto-pay settings before a large transfer.
- Agent subscriptions may fail renewal: If the source has active prepaid agent subscriptions, transferring too much can leave insufficient balance for renewal. Agents will expire on their renewal date.
- Expired deposits are not transferred: Only credit that hasn't expired yet can be moved.
- Partial transfers preserve FIFO: When a deposit is partially transferred, the rest stays on the source wallet with its original expiry date.
Coupons
In a team workspace, only team admins and the organization owner can redeem coupons, and the credit goes to the team wallet. Other members get Only team admins can perform this action.
| Coupon Scope | Who can redeem | Wallet credited |
|---|---|---|
| Everyone | Any user in Personal; team admins and the owner in a team workspace | The active workspace's wallet (personal or team) |
| Team | Team admins and the owner, with that team's workspace selected | The team wallet |
| User | Only the specified user, in their Personal workspace | The user's personal wallet |
A person can redeem a code once, whether personally or for a team, and each team can redeem it once. Redeeming a user-scoped coupon in a team workspace, or a team-scoped coupon outside its team, returns Coupon not exists.
What's Next
- Organizations & Teams Overview: Concepts and workspace hierarchy
- Managing Teams: Create organizations, invite members, manage roles
- Team API Access: How context works in API requests
- Pricing: General pricing information
Team API Access
How workspace context is resolved in API requests, and how access controls protect cross-context operations.
Context Resolution
Every authenticated API request resolves to a workspace context: either personal or a specific team. When you authenticate with a project API key (x-api-key), the context is determined automatically by the project's assignment:
- If the project belongs to a team → team context is activated
- If the project is personal → personal context is activated
You do not need to send any additional headers. Team headers are ignored on API key requests, so a key always works in its own project's workspace. To work in another workspace, use a key from a project in that workspace. In the dashboard, requests use the workspace you pick with Switch Workspace.
# This project is assigned to a team — team context is automatic
curl -X POST "https://api.wiro.ai/v1/Run/google/nano-banana" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_TEAM_PROJECT_API_KEY" \
-d '{"prompt": "Hello"}'
# This project is personal — personal context is automatic
curl -X POST "https://api.wiro.ai/v1/Run/google/nano-banana" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_PERSONAL_API_KEY" \
-d '{"prompt": "Hello"}'
These examples use API-key-only authentication. For projects that use signature authentication, also send x-nonce and x-signature (see Authentication).
Create a project inside a team to get a team API key, or use a personal project for personal context. The same x-api-key header works for both, with no extra configuration needed.
A team project's API key works only while the user who created the project is an active member of the team or the owner of its organization. Once the creator is removed from the team, the key stops working right away, in your apps and in any agent that uses it. The project stays in the team. Requests with the key then fail with HTTP 401 and The person who created this API key is no longer in its team. Ask a team admin for a new key. Public endpoints such as Agent/List still answer, as if the request had no key. While the key works, runs made with it count toward the creator's member limit (see Spend Limits).
API keys can't change teams or organizations. Organization/Create, Organization/Remove, Organization/Restore, Team/Create, Team/Update, Team/Remove, Team/Member/Invite, Team/Member/CancelInvite, Team/Member/UpdateRole, Team/Member/Remove, Team/TransferAgent, Team/TransferProject and Team/TransferCredit need a signed-in user: use the dashboard, or send that user's Bearer token. With any API key, personal or team, they fail with HTTP 401 and API keys can't manage teams or organizations. Sign in and try again. Endpoints that only read, such as Organization/List, Team/Member/List, SpendLimit/List, SpendLimit/Usage, ModelAccess/List and ModelAccess/Check, work with an API key. Spend limits and Model Access rules are not team settings, and API keys can change them: SpendLimit/Set, SpendLimit/Remove, SpendLimit/Preview, ModelAccess/Set, ModelAccess/Remove and ModelAccess/Preview work with a personal project's key and with the key of a team project whose creator is a team admin or the organization owner. A key follows its creator's current role: while its creator is a member who is not an admin, it can only read them. See Spend Limits and Model Access.
What Gets Filtered by Context
When a workspace context is active, these list endpoints return only resources belonging to that context:
| Endpoint | Personal context returns | Team context returns |
|---|---|---|
Project/List |
Personal projects only | Team projects only |
UserAgent/MyAgents |
Personal agents only | Team agents only |
Task/List |
Personal tasks only | Team tasks only |
Task/Stat |
Personal task statistics | Team task statistics |
Project/UsageSummary |
Personal project usage | Team project usage |
Wallet/List |
Personal wallet | Team wallet |
Wallet/TransactionList |
Personal transactions | Team transactions |
Coupon/UserList |
Personal coupons | Team coupons |
In team context, Project/List returns a project's apikey only to the user who created the project, team admins and the organization owner. Other members get apikeymasked instead, which shows only the first and last four characters of the key. With an API key, this follows the user who created the key's project.
Model listings show the same models in every workspace (only favorites are kept per workspace). Model Access rules apply when a model runs, not when models are listed.
Agent Context Guards
Wiro enforces strict context isolation for agent operations. When you interact with an agent, your current workspace context must match the agent's workspace:
| Your context | Agent's workspace | Result |
|---|---|---|
| Personal | Personal | Allowed |
| Team A | Team A | Allowed |
| Personal | Team A | Blocked |
| Team A | Personal | Blocked |
| Team A | Team B | Blocked |
A matching context is required, but it is not always enough. Any active team member can message a team agent and use its conversation endpoints. Subscription and billing actions (CreateSubscriptionCheckout, RenewSubscription, CancelSubscription, UpgradeTier, CreateExtraCreditCheckout) are limited to the member who deployed the agent, team admins and the organization owner. The organization owner can pay for a team agent by card or from the team wallet. Cancelling a team agent's card plan needs a team admin or the organization owner. SkillsApply, SkillToggle and CredentialProjectBind are limited to the member who deployed the agent and team admins. Other members get code 97: "Only a team admin can perform this action on a team-owned agent." With an API key, these checks apply to the user who created the key's project. Card checkouts for a team agent are refused on that path: CreateSubscriptionCheckout, UpgradeTier and CreateExtraCreditCheckout would open the session on the key project creator's own saved billing details, so pay from the team wallet (useprepaid: true) or use the dashboard.
Protected Endpoints
The following agent endpoints enforce context guards:
UserAgent/Message/Send: send a message to an agentUserAgent/Message/History: view conversation historyUserAgent/Message/Sessions: list conversation sessionsUserAgent/Message/DeleteSession: delete a conversationUserAgent/Message/RenameSession: rename a conversationUserAgent/Message/Delete: hide your own messagesUserAgent/CreateExtraCreditCheckout: purchase extra creditsUserAgent/CancelSubscription: cancel subscriptionUserAgent/RenewSubscription: renew subscriptionUserAgent/UpgradeTier: change the plan (Starter, Pro or Max)UserAgent/CreateSubscriptionCheckout: subscribe a not-yet-subscribed useragentUserAgent/PricingPreview: preview a plan or skill change for an existing agentUserAgent/SkillsApply: change skill set (single or batch, never charged)UserAgent/SkillToggle: toggle a single skillUserAgent/CredentialProjectBind: connect the agent's Wiro projectUserAgent/Realtime/WebStart: start a web voice sessionUserAgent/Realtime/ScreenInfo,UserAgent/Realtime/ScreenStart: open the agent's Screen
Message/Delete, SkillsApply and SkillToggle enforce the context guard for team agents only; a personal agent's owner can call them from any workspace. Realtime/WebStart also checks team agents only: the member who deployed the agent can call it from any workspace while they are still an active member of the agent's team, so a website voice backend keeps working on a personal project key. Outside the team's context, a caller who has left the team gets the context mismatch error.
Realtime/ScreenInfo and Realtime/ScreenStart hold an API key to its own workspace: a team project's key opens only that team's agents, and for a personal agent or another team's agent ScreenStart is refused with code 96, This API key belongs to another workspace than this agent. Use a key of the agent's own workspace. (ScreenInfo answers reason: "not_allowed"). A personal project's key opens a team agent's Screen while its owner is still an active member of the team, as for Realtime/WebStart.
UserAgent/Deploy creates the agent in your current workspace. With a team project API key the agent is deployed into that team, and the user who created the project must be a team admin. Otherwise the call fails with code 97: "Only a team admin can perform this action on a team-owned agent."
Error Response
When a context mismatch is detected:
{
"result": false,
"errors": [
{
"code": 0,
"message": "This agent belongs to a team. Switch to the team context to access it."
}
]
}
Or for the reverse case:
{
"result": false,
"errors": [
{
"code": 0,
"message": "This agent is in your personal workspace. Switch to personal context to access it."
}
]
}
If the agent belongs to a different team than your current context:
{
"result": false,
"errors": [
{
"code": 0,
"message": "This agent belongs to a different team."
}
]
}
Practical Examples
Running a Model with a Team Project
Create a project inside a team, then use its API key. The team context is resolved automatically:
# 1. Create a project in team context (from dashboard or API)
# 2. Use the project's API key — billing goes to team wallet
curl -X POST "https://api.wiro.ai/v1/Run/google/nano-banana" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_TEAM_PROJECT_API_KEY" \
-d '{"prompt": "A mountain landscape"}'
The task is created with the team's teamguid. The cost is deducted from the team wallet. The task appears in the team's usage statistics. The team's Model Access rules and spend limits also apply. A run is refused with code 92 when a Model Access rule that covers it blocks the model, such as the team's rule, the key creator's member rule or the key's own rule, and with code 93 once a spend limit that covers it is reached, such as the team's limit, the key creator's member limit or the key's own limit. See Model Access and Spend Limits.
Listing Team Agents with API Key
Use a team project API key to list agents deployed in the team:
curl -X POST "https://api.wiro.ai/v1/UserAgent/MyAgents" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_TEAM_PROJECT_API_KEY" \
-d '{"limit": 10}'
This returns only agents with teamguid matching the project's team. Personal agents are not included.
Sending a Message to a Team Agent
The API key must belong to the same team as the agent:
# Works — team project + team agent in the same team
curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/Send" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_TEAM_PROJECT_API_KEY" \
-d '{"useragentguid": "agent-guid-here", "message": "Hello"}'
# Fails — personal project + team agent = context mismatch
curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/Send" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_PERSONAL_API_KEY" \
-d '{"useragentguid": "team-agent-guid-here", "message": "Hello"}'
# Returns: "This agent belongs to a team. Switch to the team context to access it."
Wallet Billing Flow
Runs made with a team project's key are charged to the team wallet and appear in the team's Wallet/TransactionList; personal project keys charge your personal wallet.
Best Practices
- Separate projects by environment: create distinct team projects for development, staging, and production. The team context is resolved automatically from the API key.
- Check agent context before messaging: if you build a multi-tenant application, ensure the project and agent belong to the same workspace
- Transfer resources carefully: agents can only access projects in the same workspace. Plan your resource layout before transferring
What's Next
- Organizations & Teams Overview: Concepts and workspace hierarchy
- Managing Teams: Create organizations, invite members, manage roles
- Team Billing & Spending: Wallets, spend limits, and Model Access rules
- Authentication: API key setup and authentication methods
- Projects: Project management and API credentials