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:

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 run persistently in isolated containers. Unlike one-shot model runs, agents maintain conversation memory, connect to external services, and use tools to complete tasks on your behalf — all managed through the API.

The system has two layers:

• Agent templates (the catalog) — Pre-built agent definitions published by Wiro. Each template defines the agent's default skill set, required credentials, the per-tier credit multiplier, and a per-instance pricing recipe. 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 container with its own credentials, configuration, conversation history, billing, and per-model token-rate profile.

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 with custom: true (no template — you pick the skill set yourself). Both flows are documented under POST /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:

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 — Tiers, Skills & Token Billing

Agent pricing is fully derived from the agent's enabled skill set plus a per-template tiermultiplier. There is no fixed monthly base price per template and no per-agent rate override — both were dropped in favor of skill-driven pricing. The single source of truth is the skill registry, exposed via POST /Skills/List and POST /Skills/Detail.

Pricing has two layers: a monthly tier (price + credit pool, set by the enabled skills) and per-turn token billing (each message / cron / voice-prep turn deducts credits from that pool, metered by the tokens the agent's model consumes).

Tiers

Every agent ships with two tier presets: Starter and Pro. Each tier has its own price (USD/month) and credits (monthly credit allowance). The relationship between the two is fixed by the agent's tiermultiplier:

pro.price   = starter.price   × tiermultiplier
pro.credits = starter.credits × tiermultiplier

tiermultiplier defaults to 10 if the template omits it. Each agent template's tier numbers (and the tiermultiplier) appear on every catalog response under the tiers object:

"tiers": {
  "starter": { "priceUsd": 9, "credits": 900 },
  "pro":     { "priceUsd": 90, "credits": 9000 }
}

Every paid skill adds 100 monthly credits for each $1 it adds to the price, so a tier always carries 100 credits per dollar (1 credit = $0.01): the $9 Starter above comes with 900 credits a month, and its $90 Pro with 9,000.

Starter tier minimum: $4/month. Every agent pays at least $4/month on Starter. When the raw sum of enabled-skill weights would land below $4, the resolver bumps the Starter price up to $4 and scales the credit pool up by the same ratio — so the user gets a proportional credit increase, not a free upgrade. An agent made only of free (ZERO-tier) skills pays the floor too: $4/month with 400 credits. Default Pro = Starter × tiermultiplier (default 10), so an agent that lands on the $4 floor pays $40/month on Pro with the same credit pool × 10.

Token Billing

The monthly tier 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; it never infers a surcharge from a turn-level aggregate that lost call boundaries. You don't send anything — the agent runtime reports exact call-level usage after each turn, Wiro deducts the credits once, and records 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-receptionist agents) is not charged to the platform credit pool — it flows through the operator's own Wiro AI Models balance via the int-wiro-aimodels skill (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 commit a skill change or build a custom agent, fetch a live preview with POST /UserAgent/PricingPreview. The preview returns the post-toggle tiers, tokenRates, starterFloorUsd, and enabledSkills (with transitive depends_on resolved) without writing any state.

Agent Lifecycle

Deploying and running an agent follows this flow:

1. Browse — call POST /Agent/List to discover available agents in the catalog
2. Deploy — call POST /UserAgent/Deploy with useprepaid: true and tier ("starter" or "pro"). The selected tier price is debited from your prepaid wallet immediately and a 30-day subscription row is created.
3. Configure — set integration and optional Telegram, Slack, or Discord credentials with POST /UserAgent/CredentialUpsert, and preferences with POST /UserAgent/CustomSkillUpsert. See Agent Credentials for details
4. Start — call POST /UserAgent/Start to queue the agent for launch
5. Running — the agent's container starts and the agent becomes available for conversation
6. Chat — send messages via POST /UserAgent/Message/Send. See Agent Messaging for the full messaging API

UserAgent Statuses

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

Automatic Restart

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

Endpoints that auto-trigger a restart on success: CredentialUpsert, SkillsApply, CustomSkillUpsert (when functional fields change), CustomSkillRename, CustomSkillDelete, CustomSkillRevert, Update (scalar edits).

Endpoints

Browse the Catalog

POST /Agent/List

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

Response

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

Agent/List returns only catalog-header columns plus inlined tiers (so the catalog card can render the price without a per-row Agent/Detail round-trip). The id / totalrun / activerun columns are not returned. Call POST /Agent/Detail with type: "full" when you need the full template (skills map, credential schema, custom skills, scheduled skills).

POST /Agent/Detail

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

Note: You must provide either guid or slug. If both are provided, slug takes priority. Pass type: "full" when you need to preview custom skill keys and scheduled skill 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"],
      "tiermultiplier": 10,
      "tiers": {
        "starter": { "priceUsd": 9, "credits": 900 },
        "pro":     { "priceUsd": 90, "credits": 9000 }
      },
      "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",
          "additional_credential_keys": [],
          "requires_credentials": true,
          "user_invocable": true,
          "deprecated": false,
          "replacement": null,
          "description": "Post carousel feed and multi-story via Meta Graph API."
        },
        "int-wiro-aimodels": {
          "name": "int-wiro-aimodels",
          "title": "Wiro AI Models",
          "icon": "https://wiro.ai/images/icons/skills/wiro.svg",
          "brand_color": "#33F2BC",
          "brand_text_color": "#0F1A24",
          "brand_logo_filter": null,
          "category": "int",
          "docs_url": null,
          "credential_key": "wiro",
          "additional_credential_keys": [],
          "requires_credentials": true,
          "user_invocable": false,
          "deprecated": false,
          "replacement": null,
          "description": "Internal: lets the agent call Wiro's own image / video / LLM generation API. Other skills invoke it; users do not."
        }
      },
      "credentials": {
        "instagram": {
          "optional": false,
          "extra": false,
          "_editable": { "authmethod": true, "systemusertoken": true, "igusername": true },
          "_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,
            "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": "authmethod", "type": "select", "label": "Auth Method", "options": ["api_key", "own", "wiro"], "default": "api_key" },
              { "key": "systemusertoken", "type": "password", "label": "System User Token", "runtime_excluded": true, "only_in_modes": ["api_key"] },
              { "key": "accountId", "type": "text", "label": "Instagram Account ID", "auto_filled_by_oauth": true, "readonly_when_connected": true },
              { "key": "igusername", "type": "text", "label": "Connected Account", "auto_filled_by_oauth": true, "readonly_when_connected": true }
            ]
          },
          "authmethod": "",
          "igusername": "",
          "connectedat": ""
        }
      },
      "extracreditpacks": [],
      "status": 1,
      "createdat": "1711929600",
      "updatedat": "1714521600"
    }
  ]
}

Agent/Detail describes the template, so its credentials block only carries the optional / extra meta flags plus the registry-driven _schema (field labels / types) and _editable map. The _connected flag is per-instance and appears on UserAgent/Detail / UserAgent/MyAgents, not on the catalog endpoint. extracreditpacks is always [] here — packs are derived from the deployed instance's actual monthly allocation (see Extra Credit Packs) and only appear on UserAgent/Detail.

Credential response flags (on UserAgent/Detail / UserAgent/MyAgents) — every credential object in the top-level credentials tree on the per-instance endpoints carries:

Field redaction in responses:

• fieldstatus: "oauth_session" fields (accesstoken, refreshtoken, tokenexpiresat, pageAccessToken, etc.) — always stripped from every response.
• Schema fields marked runtime_excluded: true — including Meta systemusertoken — are write-only setup secrets. They never enter the agent runtime and are not reflected to customer-facing credential responses.
• fieldstatus: "platform" fields (every sys-openai field, plus Reddit's three approval flags developerprofileverified, dataapiaccessapproved and commercialwrittenapproval) — stripped from every API response. The sys-openai credential entry itself is also dropped from the response. Only the daemon container ever sees the values. credentials.wiro.apikey and credentials.calendarific.apikey are operator-supplied user-input fields and appear in the response with fieldstatus: "user" like any other API-key credential.
• fieldstatus: "oauth_app" fields (clientid / clientsecret, appid / appsecret) — stripped from Detail responses, even after an own-mode OAuth setup writes them. History writes redact clientsecret to [REDACTED].
• Sentinel rows _isoptional / _isextra — never appear as fields; they're folded into the optional and extra flags above.

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

Communication channel fields are returned separately from skill and integration credentials:

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 tier 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; the daemon picks the row up 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.

Headers: Standard API authentication — 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/Deploy	A 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/RenameSession	The project's workspace must match the agent's workspace
UserAgent/Message/Delete	For 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	The project's workspace must match the agent's workspace
UserAgent/Message/Detail, Message/Cancel	No workspace match; they only return or cancel messages sent by the project's owner
UserAgent/Detail	No workspace match; the project's owner must own the agent or be a member of its team
UserAgent/Update, UserAgent/Start, UserAgent/Stop	No workspace match; the project's owner must own the agent or be an admin of its team (plain members get code 97)
UserAgent/Realtime/WebStart	The 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/MyAgents	Lists 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": "[email protected]", "apppassword": "xxxx xxxx xxxx xxxx" },
    "telegram": { "bottoken": "123456:ABC-DEF...", "allowedusers": ["761381461"] }
  }
}

Custom builds are skill-driven. There is no marketplace template behind a custom agent — the price + credit allowance is computed live from the skills you toggle on. Use POST /UserAgent/PricingPreview (with draft: true) to estimate the tier price before calling 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:

Response

{
  "result": true,
  "errors": [],
  "useragents": [
    {
      "guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
      "uuid": "your-user-uuid",
      "agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "teamguid": null,
      "title": "My Instagram Bot",
      "description": null,
      "tier": "starter",
      "tiermultiplier": 10,
      "credentials": {
        "instagram": {
          "_connected": false,
          "optional": false,
          "extra": false,
          "_editable": { "authmethod": true, "systemusertoken": true, "igusername": true },
          "_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": 900,
      "monthlypriceusd": 9,
      "extracredits": 0,
      "usedcredits": 0,
      "remainingcredits": 900,
      "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"
      },
      "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"],
        "tiermultiplier": 10,
        "tiers": {
          "starter": { "priceUsd": 9, "credits": 900 },
          "pro":     { "priceUsd": 90, "credits": 9000 }
        },
        "extracreditpacks": [
          { "packkey": "small",  "credits": 4500, "priceusd": 45,  "enabled": true },
          { "packkey": "medium", "credits": 9000, "priceusd": 90,  "enabled": true },
          { "packkey": "large",  "credits": 18000, "priceusd": 180, "enabled": true }
        ]
      },
      "createdat": 1714608000,
      "updatedat": 1714608000
    }
  ]
}

Status and setuprequired on deploy

The Deploy response reflects the same composed shape you get from UserAgent/Detail. Every fresh Deploy starts at status: 6 (Setup Required). From there, the prepaid path auto-queues the row to status: 2 after subscription provisioning:

Subscription on deploy: the subscription object is not included in the Deploy response. A prepaid subscription (plan: "agent", provider prepaid, tier matches what you passed) is created server-side during the Deploy call — call POST /UserAgent/Detail with the returned guid to read the subscription object back.

Next steps for the API integration flow:

1. Inspect credentials in the Deploy response (or call POST /UserAgent/Detail) to see each provider's fields, the optional / extra flags, the registry-driven _schema, and the _connected OAuth status.
2. Call POST /UserAgent/CredentialUpsert per provider (or in bulk via the fields[] array) to write API keys, bot tokens, WordPress credentials, etc. For OAuth providers (Meta, Google Ads, HubSpot, …) use the unified /UserAgentOAuth/OAuthConnect flow with credentialkey — see Agent Credentials & OAuth.
3. Call POST /UserAgent/CustomSkillUpsert per skill to customize strategy text or cron intervals, if the template exposes any.
4. Once all non-optional credentials are filled, the row's setuprequired flag flips to false. If the prepaid subscription was already provisioned during Deploy, the daemon picks the row up from the queue automatically and the status progresses 2 → 3 (Starting) → 4 (Running).
5. If you want to re-launch a stopped agent (status 0) or recover an errored one (status 5), call POST /UserAgent/Start explicitly.

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. Open the existing one in your panel, or wait a few seconds and retry."
    }
  ],
  "existingUserAgentGuid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321"
}

This guards against double-tap CTAs, client-side retries, and ALB/CDN retries on transient 5xx responses creating duplicate subscriptions and double-charging the wallet. 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/Pin with { "useragentguid": "...", "pinned": false } immediately after the Deploy call resolves.

POST /UserAgent/MyAgents

Lists all agent instances deployed under your account.

Pagination: the response does not include a total count. To know if there are more pages, call with limit: 20 and inspect the returned array length — if it equals your limit, paginate further by incrementing start (e.g. start: 20, 40, 60, ...) until you get fewer rows than your limit.

Response

{
  "result": true,
  "errors": [],
  "useragents": [
    {
      "guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
      "uuid": "ada-uuid",
      "agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "teamguid": null,
      "title": "My Instagram Bot",
      "description": null,
      "cover": null,
      "categories": ["social-media", "marketing"],
      "tier": "pro",
      "tiermultiplier": 10,
      "monthlypriceusd": 90,
      "monthlycredits": 9000,
      "extracredits": 45000,
      "usedcredits": 1450,
      "creditperiod": "2026-05",
      "creditsyncat": 1714694410,
      "status": 4,
      "pinned": true,
      "teamsessionmode": "private",
      "setuprequired": false,
      "subscription": {
        "plan": "agent",
        "status": "active",
        "amount": 90,
        "currency": "usd",
        "currentperiodend": 1717200000,
        "renewaldate": "2026-06-01T00:00:00.000Z",
        "daysremaining": 62,
        "pendingdowngrade": null,
        "provider": "prepaid"
      },
      "agent": {
        "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "title": "Instagram Manager",
        "slug": "instagram-manager",
        "description": "An autonomous agent that manages your Instagram Business account.",
        "cover": "https://cdn.wiro.ai/uploads/agents/instagram-manager-cover.webp",
        "categories": ["social-media", "marketing"],
        "tiermultiplier": 10,
        "tiers": {
          "starter": { "priceUsd": 9, "credits": 900 },
          "pro":     { "priceUsd": 90, "credits": 9000 }
        }
      },
      "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
    }
  ]
}

MyAgents returns one row per useragent with its scalar fields, the trimmed agent template summary (no extracreditpacks), subscription, setuprequired (status-based check only), extracredits / extracreditsexpiry, the resolved enabledSkills (template defaults ∪ user overrides, including transitive depends_on closure), tokenRates (per-model token rates — same map as UserAgent/Detail.tokenRates), agentModel (the resolved chat / cron / voice-prep / voice-postcall model slugs), and enabledCommands (the slash-command allowlist, null when uncustomized). Heavier composed children (credentials, customskills, scheduledskills, skills, skillsmeta, remainingcredits) are not included — call UserAgent/Detail on a single guid for the full composed shape.

enabledSkills, tokenRates, and agentModel ride on each list row so the dock chat / pinned-agents UI can decide whether to show the realtime voice-call button (enabledSkills includes util-web-channel) and render the model picker + live token-rate card without round-tripping UserAgent/Detail per 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.

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",
      "tiermultiplier": 10,
      "status": 4,
      "pinned": true,
      "setuprequired": false,
      "teamsessionmode": "private",
      "credentials": {
        "instagram": {
          "_connected": true,
          "optional": false,
          "extra": false,
          "_editable": {
            "authmethod": true,
            "systemusertoken": true,
            "igusername": true
          },
          "_schema": {
            "title": "Instagram",
            "icon": "https://wiro.ai/images/icons/skills/instagram.svg",
            "brand_color": "#E4405F",
            "brand_text_color": "#FFFFFF",
            "brand_logo_filter": null,
            "docs_url": "/docs/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,
            "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": "authmethod",
                "label": "Authentication Method",
                "type": "select",
                "required": true,
                "options": [
                  { "label": "System User Token", "value": "api_key" },
                  { "label": "Own OAuth app",     "value": "own" },
                  { "label": "Wiro-managed",      "value": "wiro" }
                ],
                "default": "api_key"
              },
              {
                "key": "systemusertoken",
                "label": "System User Token",
                "type": "password",
                "required": true,
                "runtime_excluded": true,
                "only_in_modes": ["api_key"]
              },
              {
                "key": "accountId",
                "label": "Instagram Account ID",
                "type": "text",
                "required": true,
                "auto_filled_by_oauth": true,
                "readonly_when_connected": true
              },
              {
                "key": "igusername",
                "label": "Connected Account",
                "type": "text",
                "required": false,
                "auto_filled_by_oauth": true,
                "readonly_when_connected": true
              }
            ]
          },
          "_required_missing": false,
          "authmethod": "api_key",
          "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": "/docs/integration-telegram-skills",
            "credential_mode": "api_key",
            "connection_modes": [],
            "wiro_connect_pending": false,
            "oauth_provider": null,
            "fields": [
              {
                "key": "bottoken",
                "label": "Bot Token",
                "type": "password",
                "required": true,
                "placeholder": "123456789:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
                "help": "Issued by @BotFather when you create the bot."
              },
              {
                "key": "allowedusers",
                "label": "Allowed User IDs",
                "type": "string-array",
                "required": false,
                "pattern": "^\\d{5,}$"
              },
              {
                "key": "groups",
                "label": "Allowed Telegram Groups",
                "type": "object-array",
                "required": false,
                "item_schema": [
                  { "key": "chatid", "type": "text", "required": true, "pattern": "^-\\d{5,}$" },
                  { "key": "allowedusers", "type": "string-array", "required": true, "pattern": "^\\d{5,}$" }
                ]
              }
            ]
          },
          "_required_missing": false,
          "bottoken": "",
          "allowedusers": [],
          "groups": []
        },
        "wordpress": {
          "_connected": false,
          "optional": false,
          "extra": false,
          "_editable": {
            "siteurl":         true,
            "username":        true,
            "applicationpass": true
          },
          "_schema": {
            "title": "WordPress",
            "icon": "https://wiro.ai/images/icons/skills/wordpress.svg",
            "brand_color": "#21759B",
            "brand_text_color": "#FFFFFF",
            "brand_logo_filter": null,
            "docs_url": "/docs/integration-wordpress-skills",
            "credential_mode": "api_key",
            "connection_modes": ["api_key"],
            "wiro_connect_pending": false,
            "oauth_provider": null,
            "fields": [
              {
                "key": "siteurl",
                "label": "Site URL",
                "type": "text",
                "required": true,
                "placeholder": "https://blog.example.com",
                "pattern": "^https?://.+"
              },
              {
                "key": "username",
                "label": "Username",
                "type": "text",
                "required": true,
                "placeholder": "wp-editor"
              },
              {
                "key": "applicationpass",
                "label": "Application Password",
                "type": "password",
                "required": true,
                "placeholder": "xxxx xxxx xxxx xxxx xxxx xxxx",
                "help": "Generate from WP Admin → Users → Profile → Application Passwords."
              }
            ]
          },
          "_required_missing": true,
          "siteurl": "",
          "username": "",
          "applicationpass": ""
        }
      },
      "customskills": [
        {
          "key": "cs-content-tone",
          "description": "Brand voice + posting rules read by every content-generation skill on this agent.",
          "value": "## Brand Voice\nTone: friendly, casual, never salesy.\nTarget Audience: indie devs and side-project builders.\n\n## Hashtag Strategy\nMax 3 per post. Always include #BuildInPublic and #Indie.\n\n## Platform Rules\n- Instagram: square images only, carousels for tutorials.\n- Twitter: thread format for posts longer than 200 chars.",
          "enabled": true,
          "interval": null,
          "_source": "preset-strategy",
          "_editable": true,
          "_edited": true
        },
        {
          "key": "cs-content-sources",
          "description": "RSS / sitemap URLs the agent should poll for new content ideas.",
          "value": "## Primary Sources\nhttps://blog.example.com/feed.xml\nhttps://news.ycombinator.com/rss\n\n## CTA URL Pattern\nhttps://example.com/posts/{slug}",
          "enabled": true,
          "interval": null,
          "_source": "preset-strategy",
          "_editable": true,
          "_edited": false
        }
      ],
      "scheduledskills": [
        {
          "key": "cs-cron-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",
          "additional_credential_keys": [],
          "requires_credentials": true,
          "user_invocable": true,
          "deprecated": false,
          "replacement": null,
          "description": "Post carousel feed and multi-story via Meta Graph API."
        },
        "int-twitterx-post": {
          "name": "int-twitterx-post",
          "title": "X (Twitter) 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": "twitterx",
          "additional_credential_keys": [],
          "requires_credentials": true,
          "user_invocable": true,
          "deprecated": false,
          "replacement": null,
          "description": "Compose tweets, threads, and replies on a connected X (Twitter) account."
        },
        "int-wiro-aimodels": {
          "name": "int-wiro-aimodels",
          "title": "Wiro AI Models",
          "icon": "https://wiro.ai/images/icons/skills/wiro.svg",
          "brand_color": "#33f2bc",
          "brand_text_color": "#0f1a24",
          "brand_logo_filter": null,
          "category": "int",
          "docs_url": null,
          "credential_key": "wiro",
          "additional_credential_keys": [],
          "requires_credentials": true,
          "user_invocable": false,
          "deprecated": false,
          "replacement": null,
          "description": "Internal: lets the agent call Wiro's own image / video / LLM generation API. Other skills invoke it; users do not."
        }
      },
      "monthlycredits": 9000,
      "monthlypriceusd": 90,
      "extracredits": 45000,
      "usedcredits": 1450,
      "remainingcredits": 52550,
      "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"
      },
      "subscription": {
        "plan": "agent",
        "status": "active",
        "amount": 90,
        "currency": "usd",
        "currentperiodend": 1717200000,
        "renewaldate": "2026-06-01T00:00:00.000Z",
        "daysremaining": 28,
        "pendingdowngrade": null,
        "provider": "prepaid"
      },
      "agent": {
        "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "title": "Instagram Manager",
        "slug": "instagram-manager",
        "headline": "Automate your Instagram presence with AI",
        "description": "An autonomous agent that manages your Instagram Business account: drafts posts from your RSS feeds, schedules carousels, and replies to DMs.",
        "cover": "https://cdn.wiro.ai/uploads/agents/instagram-manager-cover.webp",
        "icon": "https://cdn.wiro.ai/uploads/agents/instagram-manager-icon.webp",
        "categories": ["social-media", "marketing"],
        "tiermultiplier": 10,
        "tiers": {
          "starter": { "priceUsd": 9,  "credits": 900 },
          "pro":     { "priceUsd": 90, "credits": 9000 }
        },
        "extracreditpacks": [
          { "packkey": "small",  "credits": 45000, "priceusd": 450, "enabled": true },
          { "packkey": "medium", "credits": 90000, "priceusd": 900, "enabled": true },
          { "packkey": "large",  "credits": 180000, "priceusd": 1800, "enabled": true }
        ]
      },
      "extracreditsexpiry": 1730419200,
      "createdat": 1714608000,
      "updatedat": 1714694400,
      "queuedat": 1714694395,
      "startedat": 1714694400,
      "runningat": 1714694410,
      "stoppingat": null,
      "stopdat": null,
      "errordat": null
    }
  ]
}

Field reference

Identity & profile

Tier & pricing

Lifecycle

Composed children

Subscription & template

Credential object shape

Every provider entry under credentials.<key> carries:

Subscription object

POST /UserAgent/Update

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

Scalar-only. Credentials, custom skills, skill toggles, and tier upgrades use dedicated endpoints:

What you want to change	Use
Provider credentials (API keys, OAuth settings)	POST /UserAgent/CredentialUpsert
Upload a credential fileinput field (multipart, e.g. Twilio voice MP3)	POST /UserAgent/CredentialFileUpload
Custom skill values (strategy text, cron intervals, enabled flag)	POST /UserAgent/CustomSkillUpsert
Rename a user-created custom skill (key + optional description)	POST /UserAgent/CustomSkillRename
Browse alternative templates for a custom skill	POST /UserAgent/CustomSkillAlternatives
Delete a user-created cron skill	POST /UserAgent/CustomSkillDelete
Toggle one or more integration skills on/off (with optional tier change)	POST /UserAgent/SkillsApply
Upgrade Starter → Pro	POST /UserAgent/UpgradeTier
Upload a cover image (multipart)	POST /UserAgent/Cover
Per-agent timezone or unified Chat Mode	POST /UserAgent/UpdateSettings
View / download / purge activity logs	POST /UserAgent/Logs · LogsList · LogsFile · LogsDelete
Soft-delete a useragent	POST /UserAgent/Delete

Note: CredentialUpsert writes credential fields but does not transition status: 6 on its own. After filling the missing credentials, call POST /UserAgent/Update once (any scalar body — even just { "guid": "<useragent-guid>" } — works) to trigger the setuprequired re-check; that's the call that flips status: 6 → 0 (Stopped) so the next Start succeeds.

Response

{
  "result": true,
  "errors": [],
  "useragents": [
    {
      "guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
      "uuid": "ada-uuid",
      "agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "teamguid": null,
      "title": "My Instagram Bot",
      "description": "Updated description after rename",
      "cover": "https://cdn.wiro.ai/uploads/useragents/f8e7d6c5-cover.webp",
      "categories": ["social-media", "marketing"],
      "tier": "starter",
      "tiermultiplier": 10,
      "monthlypriceusd": 9,
      "monthlycredits": 900,
      "extracredits": 0,
      "usedcredits": 80,
      "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"],
        "tiermultiplier": 10,
        "tiers": {
          "starter": { "priceUsd": 9,  "credits": 900 },
          "pro":     { "priceUsd": 90, "credits": 9000 }
        },
        "extracreditpacks": []
      },
      "createdat": 1714608000,
      "updatedat": 1714694500,
      "queuedat": 1714694498,
      "startedat": null,
      "runningat": null,
      "stoppingat": 1714694500,
      "stopdat": null,
      "errordat": null
    }
  ]
}

Update returns the full composed useragent shape — same composition path as UserAgent/Detail, so credentials, customskills, scheduledskills, skills, skillsmeta, tokenRates, agentModel, and the agent template summary (with tiers + extracreditpacks) are all included. The fields Update cannot safely populate without an extra round-trip (subscription, remainingcredits, extracreditsexpiry) stay omitted — call UserAgent/Detail next if you need them. Otherwise the response is suitable for an in-place panel re-render without a follow-up call.

Restart on running agents. When the call lands on a status 3/4 agent, the response shows the lifecycle transition mid-flight: status: 1 (Stopping) with a fresh stoppingat timestamp, runningat cleared, and queuedat set to the same instant — Wiro auto-queues the agent so it picks the new settings up after the next stop cycle.

POST /UserAgent/UpdateSettings

Writes per-agent preference toggles that are not credentials and not skill rows. Exposes timezone (operator-selected IANA zone, propagates into the agent container's TZ env, cron schedule.tz, and caller-facing voice prep), 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, and enabledcommands (the in-chat slash-command allowlist). Submit any subset in the same call — partial updates are supported and untouched fields keep their current value.

Permission: owner OR team admin (the same requireRole: "admin" gate as /UserAgent/Update). Team members cannot flip these knobs.

Restart: if the agent is starting (status 3) or running (status 4), the call auto-stops the container and schedules a restart so the daemon worker picks up the fresh settings.json (new timezone, session mode, and / or model selection) on the next launch cycle. Status 0/1/2/5/6 agents take effect on the next manual Start without a soft-stop.

Slash-command catalog. Valid enabledcommands keys 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 the enabledCommands field (camelCase) on UserAgent/Detail / MyAgents / PinnedAgents — null there means the operator never customized it (all commands available); 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 only timezone does not touch teamsessionmode or any model field, and vice versa. Sending an empty body (none of the recognised fields) is rejected with nothing-to-update to avoid charging a no-op container restart.

Read vs write casing. You read the current selection from the agentModel object on UserAgent/Detail / MyAgents / PinnedAgents in camelCase (chatModel, cronModel, voicePrepModel, voicePostcallModel); you write it here in lowercase (chatmodel, cronmodel, voiceprepmodel, voicepostcallmodel). The selectable set is exactly the models that tokenRates.models marks selectable: true — there is no separate "list models" endpoint, so read tokenRates to populate a picker.

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

# 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. UpdateSettings returns just result + errors — no full useragent shape. Pull the refreshed row with POST /UserAgent/Detail if you need to re-render the panel after the write.

Common errors

POST /UserAgent/Cover

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

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

Multipart fields:

Response

{
  "result": true,
  "errors": [],
  "cover": "https://cdn.wiro.ai/uploads/useragents/f8e7d6c5-b4a3-2190-fedc-ba0987654321-cover.webp",
  "useragents": [
    {
      "guid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
      "uuid": "ada-uuid",
      "agentguid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "teamguid": null,
      "title": "My Instagram Bot",
      "description": null,
      "cover": "https://cdn.wiro.ai/uploads/useragents/f8e7d6c5-b4a3-2190-fedc-ba0987654321-cover.webp",
      "categories": ["social-media", "marketing"],
      "tier": "starter",
      "tiermultiplier": 10,
      "monthlypriceusd": 9,
      "monthlycredits": 900,
      "extracredits": 0,
      "usedcredits": 80,
      "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"],
        "tiermultiplier": 10
      },
      "createdat": 1714608000,
      "updatedat": 1714694500,
      "queuedat": 1714694395,
      "startedat": 1714694400,
      "runningat": 1714694410,
      "stoppingat": null,
      "stopdat": null,
      "errordat": null
    }
  ]
}

Cover returns scalar useragent fields + the agent template summary only. It does not include setuprequired, tokenRates, agentModel, remainingcredits, or any composed children (credentials, customskills, scheduledskills, skills, skillsmeta, subscription). The endpoint is optimised for the cover refresh round-trip; call UserAgent/Detail afterwards 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, completing the upsert triggers an 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.

Each field row:

Request

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

Response

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

applied is the number of rows saved without an error; a row sent with its current value still counts. 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-voice field is touched, CredentialUpsert also auto-configures each Twilio phone number's VoiceUrl and surfaces the result on the response:

Field	Type	Meaning
twilioWebhooksUpdated	string[]	E.164 numbers whose VoiceUrl was just pointed at the Wiro Twilio webhook.
twilioWebhookSkipped	string	Returned instead of twilioWebhooksUpdated when the VoiceUrl step 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.
twilioWebhooksFailed	object[]	One { phoneNumber, error } entry per number whose update Twilio rejected.
twilioWebhookError	string	Top-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/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 triggers an automatic restart so the new URL flows into the daemon's settings.json on the next start.

Unlike CredentialUpsert, this endpoint expects multipart/form-data — pass the metadata as form fields and the blob in a file part.

fileinput vs fileinput-base64. This endpoint is the storage path for the fileinput type only — the binary lives in S3 and the credential row stores a reference. The companion fileinput-base64 type stays inline in the DB (encrypted at rest) and is written via the standard CredentialUpsert JSON fields[] array (e.g. serviceaccountjson on google-drive/google-calendar/google-play/firebase, privatekey on apple-appstore). Sending a base64 field through this endpoint returns Field 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, AES-keyed CDN URL the daemon will fetch at runtime. The credential row stores the raw <path>/<name> reference under the hood and recomposes the URL on every read, so the field stays valid across CDN domain rotation and AES key rotation.

Common errors

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 in the Scheduled Skills tab. 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.

Description-only edits skip the restart. If you only change description (and the row's functional fields — value, interval, enabled — stay the same), the agent is not restarted. Functional changes still trigger the standard auto-restart.

Request

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

Response

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

POST /UserAgent/CustomSkillRename

Renames a user-created custom skill, optionally updating its description in the same atomic write. Only rows with usercreated: true can be renamed — preset-owned rows reject with agent-customskill-rename-preset-forbidden.

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.

Restart. The renamed key surfaces in the container's settings.json, so the useragent is auto-restarted on success (same behaviour as CustomSkillUpsert functional edits).

Request

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

Response

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

Error cases

POST /UserAgent/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).

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, value, and — for cron-flavoured alternatives only — intervalexpr (a cron expression). 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:

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.

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.

Response

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

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_* and prev_* 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 (null for 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. null when operation: "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, email, username, avatar, avatarinitials). null when changedby is a sentinel like "system" / "backfill-*" (cron / migration writes) 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.

Response

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

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

POST /UserAgent/CredentialFieldHistory

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

• oauth_session fields (access / refresh tokens) never appear in history at all — they're stripped before persisting.
• clientsecret and similar oauth_app secret fields are stored as [REDACTED] in history rows (the live value stays server-side — UserAgent/Detail doesn't return it either).
• The platform-managed sys-openai credential short-circuits to an empty entries[] (no user-facing history to show).

Response

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

changedby_user is the resolved actor object (uuid, firstname, lastname, email, username, avatar, avatarinitials). It is null when changedby is a sentinel like "system" / "backfill-*" (cron / migration writes) or when the user record has been deleted.

POST /UserAgent/SkillsApply

Applies a batch of skill toggles + an optional tier change in a single transactional unit. This is the only skill-toggle endpoint API consumers should use — even when you're flipping a single skill, send it as a one-entry skills map. The single-skill SkillToggle endpoint also exists, but SkillsApply is the one to use from the API.

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

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

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",
    "tier": "pro",
    "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",
  "prepaidWalletDelta": 18.00,
  "restartTriggered": true,
  "restartedAt": 1714694520,
  "pricing": {
    "previousPriceUsd": 4,
    "newPriceUsd": 40,
    "deltaUsd": 36,
    "previousMonthlyCredits": 400,
    "newMonthlyCredits": 4000,
    "deltaCredits": 3600,
    "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 and the requested tier (if any) is unchanged, the endpoint returns a fast-path noOp: true reply with no DB writes, no wallet movement, 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
}

Common error codes

POST /UserAgent/PricingPreview

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

Two body shapes:

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

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

B. Existing useragent preview

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

Response

{
  "result": true,
  "errors": [],
  "tier": "pro",
  "tiermultiplier": 10,
  "totalPriceUsd": 40,
  "totalMonthlyCredits": 4000,
  "starterFloorUsd": 4,
  "skillBreakdown": [
    { "skill": "int-instagram-post", "priceUsd": 1, "credits": 100, "billing_model": "tokens" },
    { "skill": "int-wiro-aimodels",  "priceUsd": 1, "credits": 100, "billing_model": "tokens" }
  ],
  "enabledSkills": ["int-instagram-post", "int-wiro-aimodels"],
  "directSkills":  ["int-instagram-post"],
  "agentBase": { "priceUsd": 0, "credits": 0 },
  "tiers": {
    "starter": { "priceUsd": 4,  "credits": 400 },
    "pro":     { "priceUsd": 40, "credits": 4000 }
  },
  "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" }
    }
  }
}

enabledSkills is the full closure (including transitive depends_on); directSkills is just what the user explicitly toggled. agentBase is always { priceUsd: 0, credits: 0 } — pricing is fully skill-driven, and the field is kept on the response so callers don't have to null-check. skillBreakdown[].billing_model is always "tokens"; tokenRates carries the per-model rates used to meter each turn (see Token Billing).

$4 starter floor. When the raw weight sum lands below $4 (e.g. a single LIGHT skill at $1/100), the resolver bumps tiers.starter.priceUsd up to $4 and scales tiers.starter.credits up by the same ratio (100 → 400); the applied floor is echoed as starterFloorUsd. Pro derives from the post-floor starter via × tiermultiplier (default 10), so a $1-weight agent becomes Starter $4/400 and Pro $40/4000. See Pricing Model — Tiers, Skills & Token Billing for the full rules.

POST /UserAgent/CreateSubscriptionCheckout

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

Response

{
  "result": true,
  "errors": [],
  "subscriptionId": 8421,
  "monthlypriceusd": 90,
  "monthlycredits": 9000
}

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:

POST /UserAgent/Start

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

Response

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

useragents is always returned (empty array on Start) because Start returns the standard agent response shape — just result and errors carry 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 container is shut down gracefully.

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

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)

1. Access — owner of the row or a team admin of the UA's team. Members get useragent-team-admin-required (code 97); strangers get useragent-access-denied (code 96); unknown / already-deleted rows get useragent-not-found (code 95).
2. Status — must be in a clean terminal state: 0 (Stopped), 5 (Error), or 6 (Setup Required); 5 passes only once the agent no longer holds its runtime. Anything in flight (1 Stopping, 2 Queued, 3 Starting, 4 Running) is rejected with useragent-delete-running, and so is an errored agent that still holds its runtime — Stop the agent first and wait for status 0.
3. Active subscription — a subscription with status: "active" blocks delete (useragent-delete-sub-active). CancelSubscription doesn't lift this right away: the subscription stays active until 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

POST /UserAgent/Logs

Live activity feed for a useragent — what the agent did, when, and (post-rollout) which user triggered it. The daemon writes one JSONL row per skill invocation / cron tick / user message into the worker's per-day activity file; this endpoint tails the latest N rows for a given date and decorates each event with the resolved actor.

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

Rate limit

Calls are rate-limited via a 30-second server-side cache keyed on (useragentguid, date, lines). The first call within a 30s window hits the worker; subsequent calls within the window receive the cached payload. Tune your polling cadence to ≥30s to avoid serving stale data — the cache TTL was chosen to match the panel's lowest polling interval.

Response

{
  "result": true,
  "errors": [],
  "events": [
    {
      "ts": "2026-05-03T14:00:03.000Z",
      "kind": "token_usage",
      "title": "Turn billed — 5 credits",
      "summary": { "trigger": "chat" },
      "model": "openai/gpt-5.4",
      "tokens": { "input": 3450, "output": 820, "cacheRead": 2400, "cacheWrite": 0, "total": 6670 },
      "tokencost": 5,
      "durationMs": 4200,
      "calls": 2,
      "remainingcredits": 8995,
      "ok": true,
      "userUuid": "ada-uuid",
      "user": {
        "uuid": "ada-uuid",
        "firstname": "Ada",
        "lastname": "Lovelace",
        "email": "[email protected]",
        "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": "[email protected]",
        "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

Common errors

POST /UserAgent/LogsList

Lists the dates for which an activity log file exists on the worker host. Useful for building a date-picker UI before calling Logs / LogsFile for that day.

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": 71680,  "compressed": true  }
  ]
}

The host retains activity files for 180 days (rolling); older dates are pruned by a worker cron and won't appear here.

POST /UserAgent/LogsDelete

Removes one date's activity JSONL file (and its gzipped sibling if present) from the worker host. Useful for scrubbing a specific day without waiting for the 180-day rotation.

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 for cache hygiene). The response is the same events[] shape as Logs, plus a truncated flag.

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) — 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 worker's read buffer hit a hard ceiling (currently 250k rows / 50 MB). For typical agents this stays false; if you ever see true, fall back to streaming the file directly via the panel's download link.

POST /UserAgent/Pin

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

Response

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

POST /UserAgent/PinnedAgents

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

No request body fields are required — the 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",
      "tiermultiplier": 10,
      "monthlypriceusd": 90,
      "monthlycredits": 9000,
      "extracredits": 45000,
      "usedcredits": 1450,
      "creditperiod": "2026-05",
      "creditsyncat": 1714694410,
      "status": 4,
      "pinned": true,
      "teamsessionmode": "private",
      "setuprequired": false,
      "subscription": {
        "plan": "agent",
        "status": "active",
        "amount": 90,
        "currency": "usd",
        "currentperiodend": 1717200000,
        "renewaldate": "2026-06-01T00:00:00.000Z",
        "daysremaining": 28,
        "pendingdowngrade": null,
        "provider": "prepaid"
      },
      "agent": {
        "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "title": "Instagram Manager",
        "slug": "instagram-manager",
        "description": "An autonomous agent that manages your Instagram Business account.",
        "cover": "https://cdn.wiro.ai/uploads/agents/instagram-manager-cover.webp",
        "categories": ["social-media", "marketing"],
        "tiermultiplier": 10,
        "tiers": {
          "starter": { "priceUsd": 9,  "credits": 900 },
          "pro":     { "priceUsd": 90, "credits": 9000 }
        }
      },
      "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 — same pattern the Wiro dashboard uses for its global header.

Response

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

Voice & Realtime

Endpoints for browser-based realtime voice sessions plus the unified call history for both Web and Twilio channels. Per-channel setup, session handles, and the WebSocket protocol live on the dedicated pages:

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.

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 additionally enforce an Origin allow-list (https://wiro.ai, https://www.wiro.ai, plus http://localhost:* in non-production); API-key requests skip the Origin check.
• Rate limit — fixed 60 sessions/hour per operator (the operator identity is hashed and never logged raw). Fast-fail sessions are decremented back from the counter.
• Full WebSocket protocol, control frames, and JS snippet — Web Voice.

Common errors

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.

Response

{ "result": true, "correlationId": "voice_3fK9xQ2LmVb7TzR1pWc8NdYa", "cancelled": true }

Without this call, the server-side agent prep WebStart kicked off lingers for ~5 minutes (the fallback cleanup guard) before being released — calling Cancel immediately frees the prep state and releases the held realtime session slot.

POST /UserAgent/TwilioCallHistory/List

Returns the last N realtime voice sessions for a useragent — 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.

Response

{
  "result": true,
  "errors": [],
  "data": [
    {
      "messageguid": "5c41dabf-f2be-4aa8-a5a4-8c9e3d2f3f11",
      "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": "9d11baa2-7ce8-44b7-a3e0-2f8a31f6c4ee",
      "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
    }
  ]
}

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.

Extra Credit Packs

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

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

"extracreditpacks": [
  { "packkey": "small",  "credits": 45000, "priceusd": 450,  "enabled": true },
  { "packkey": "medium", "credits": 90000, "priceusd": 900,  "enabled": true },
  { "packkey": "large",  "credits": 180000, "priceusd": 1800, "enabled": true }
]

Each pack carries:

POST /UserAgent/CreateExtraCreditCheckout

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

Request

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

Response

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

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

POST /UserAgent/CancelSubscription

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

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

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

• cancelsAt is the end of the current period. The agent keeps running until then, and the subscription ends at that point.
• subscription.pendingdowngrade isn't set, and RenewSubscription can'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:

POST /UserAgent/UpgradeTier

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

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

Headers: 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.

API-deployed agents always upgrade through the prepaid path. The endpoint debits the prorated upgrade fee Math.max(0, ((P_pro − P_starter) / totalDays) × remainingDays) from your wallet synchronously, updates the subscription row + useragent snapshot to Pro pricing / credits inline, and restarts the daemon to refresh settings.json. Existing extra credits and usedcredits are preserved.

Response

{
  "result": true,
  "tier": "pro",
  "previousTier": "starter",
  "newPriceUsd": 90,
  "newMonthlyCredits": 9000,
  "proratedCharge": 45.90,
  "errors": []
}

POST /UserAgent/RenewSubscription

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

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

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

Headers: 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.

Renewal pricing is snapshot-driven — monthlypriceusd and monthlycredits are read straight off the useragent row (last touched by Deploy, SkillsApply, or UpgradeTier). Skill-registry weight changes between renewals do not propagate; the user keeps the price they last agreed to. To pick up new pricing, the user must explicitly call SkillsApply or UpgradeTier (both re-snapshot in the same transaction).

Response — undo-cancel

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

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

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

Response — renew

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

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

• Renews the subscription in place: status becomes "active", a new 30-day period starts now (currentperiodend moves to now + 30 days), and pendingdowngrade is cleared to null.
• Debits amount (the snapshot monthlypriceusd) from the wallet (caller's personal wallet, or the agent's team wallet if the agent is team-scoped).
• Zeroes usedcredits and stamps the new creditperiod. Existing extra credits are preserved.
• If the agent was in status: 0 (Stopped) or 5 (Error), it's auto-queued back to 2 (Queued) — the daemon picks it up on the next cycle, no extra Start call needed. Statuses 1/2/3/4 are mid-flight and the daemon settles them on its 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:

Full subscription lifecycle (prepaid)

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

Pricing Summary

Payment Method

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

Credit Consumption

Credits are consumed by the agent runtime (container) as it processes messages and generates content — not at Message/Send time. Each turn is billed by token usage: the runtime reports the input / output / cached token counts once the turn completes, Wiro meters them against the per-model tokenRates (1 credit = $0.01), writes an action: "tokens" deduct row, bumps usedcredits, and derives the live 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 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:

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 for an end user (unpinned, won't clutter your dashboard)
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"
  }'

# 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 }
  }'

# Live pricing preview before committing a skill change
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",
    "skillOverrides": { "int-twitterx-post": true }
  }'

# 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"}'

# Upgrade Starter → Pro (prepaid, prorated charge)
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']['price']}/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 tier)
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" }
        ]
    }
)

# Start the agent
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)

# Upgrade Starter → 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 (Pro tier — 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']} - tier: {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.price}/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 tier)
  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 }
  );

  // Start the agent
  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));
  }

  // Upgrade Starter → 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 tier)
$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 tier)
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);

// Start the agent
var startContent = new StringContent(
    JsonSerializer.Serialize(new {
        guid = "f8e7d6c5-b4a3-2190-fedc-ba0987654321"
    }),
    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 tier)
    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: 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 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