Agent Routes

An Agent on its own is just a configuration — nobody can talk to it yet. A route is what turns an Agent into a public, always-on conversation page:

https://interactive.mirako.ai/r/<ROUTE_ID>

Anyone who opens that link in a browser can talk to your avatar immediately. There is no session to start, no warm-up step to trigger, and nothing to stop afterwards. The Interactive service is always running; a route simply admits a visitor to your Agent.

A Route Is a Bearer Capability

Treat a route ID like a password:

Anyone who has the full link can open it and talk to your Agent. Visitors do not need a Mirako account or an API key.
Conversation usage from that link is billed to your account by duration, whoever is talking.
If a link leaks, revoke it. Revoking is instant and permanent for that route — but it does not touch your Agent or any of its other routes.

This design is deliberate: create one route per place you share the link. A permanent route for your website, a short-lived route for a sales demo, another for a QR code at an event. Each can be labelled, expired, and revoked independently.

Create a Route

With the CLI

# Permanent route (never expires)
mirako agent routes create <MY_AGENT_ID> --label "Website"

# Temporary route that expires after 24 hours
mirako agent routes create <MY_AGENT_ID> --label "Customer demo" --valid-for 24h

--label is an optional owner-facing name (up to 100 characters) so you can recognise the route later. --valid-for accepts Go-style durations such as 30m, 24h, or 168h (whole seconds only). Omit it to create a permanent route.

The command prints the route ID. Your public link is:

https://interactive.mirako.ai/r/<ROUTE_ID>

With the API

python

import requests

API_KEY = "your_api_key_here"
BASE_URL = "https://mirako.co"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def create_route(agent_id, label=None, validity_seconds=None):
    """Create a route for an agent. Omit validity_seconds for a permanent route."""
    body = {}
    if label is not None:
        body["label"] = label
    if validity_seconds is not None:
        body["validity_seconds"] = validity_seconds

    response = requests.post(
        f"{BASE_URL}/v1/agents/{agent_id}/routes",
        headers=headers,
        json=body,
    )
    if response.status_code != 201:
        raise RuntimeError(
            f"Failed to create route: {response.status_code} {response.text}"
        )
    route = response.json()["data"]
    print(f"Share this link: https://interactive.mirako.ai/r/{route['id']}")
    return route


# Permanent route
route = create_route("MY_AGENT_ID", label="Website")

# Route that expires in 24 hours
demo_route = create_route("MY_AGENT_ID", label="Customer demo", validity_seconds=86400)

See the Create Agent Route API reference for the full schema. The response includes the route's status and, for temporary routes, its absolute expires_at time.

Route Lifecycle

Every route is in exactly one status:

Status	Meaning
`active`	The link works and admits visitors to the agent.
`expired`	A temporary route whose validity period has ended. The link no longer works.
`revoked`	You revoked the route manually. The link no longer works, permanently.

Expiry and revocation only affect that one route. Your Agent, and every other route pointing at it, keep working.

List and View Routes

# All routes you own, across every agent
mirako agent routes list

# Details for one route
mirako agent routes view <ROUTE_ID>

Use --json on either command for machine-readable output. Over the API, GET /v1/agents/{agent_id}/routes lists the routes of one agent, GET /v1/agent-routes lists all of yours, and GET /v1/agent-routes/{route_id} fetches a single route.

You can also rename a route's label without changing the link itself:

curl https://mirako.co/v1/agent-routes/<ROUTE_ID>/update \
  --request POST \
  --header "Authorization: Bearer MY_SECRET_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"label": "Production website"}'

Send "label": null to clear the label. Only the label can be updated — a route always points at the agent it was created for.

Revoke a Route

Revoke a route the moment a link should stop working — a demo is over, an employee leaves, or a link was shared in the wrong place:

mirako agent routes revoke <ROUTE_ID>

The CLI asks for confirmation; pass --force to skip it. Revocation is terminal and idempotent: a revoked route can never become active again, and revoking it twice is safe. If you need the link back, create a new route for the same agent and share the new link.