register a call

POST /v1/register-call exchanges your api key for a short-lived token that opens exactly one realtime socket. the token is spent the moment it is redeemed, so leaking one costs you a single call rather than an account. call it from your server, hand the token to the client, and let the client connect.

request

string

required

the agent to run — its UUID or its ua_… handle. agentId is accepted too.

curl

curl -X POST https://silk-api.rumik.ai/v1/register-call \
  -H "Authorization: Bearer rk_live_•••••••••" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "ua_fe3277d8" }'

response

returns 201 Created.

string

the single-use token, prefixed wct_. pass it as the token query parameter when opening the socket.

integer

how many seconds the token stays redeemable. it only has to survive the trip from your server to the client opening the socket.

integer

the audio sample rate the session will use, in Hz.

{
  "access_token": "wct_9f8c2b1e4d5a4e6fa7b8c9d0e1f2a3b4",
  "expires_in": 300,
  "sample_rate": 24000
}

what it does not do

registering a call does not start one. nothing is billed, no capacity slot is taken, and no agent is spawned until the socket actually connects — so a token your user never redeems costs nothing and blocks nobody. that also means a 429 cannot happen here. if you are out of capacity, you find out when the socket opens: it accepts, sends an error frame, and closes with code 4000. see connection errors.

the agent must be deployed

registering checks that the agent has a live version and returns 409 agent_not_deployed if not. that check happens here rather than at the socket on purpose: the token is single-use, so a caller refused after redeeming one would have to come back for another.

single use

token = register_call(agent)["access_token"]

open_socket(token)   # works
open_socket(token)   # 4401 — the token was already spent

a redeemed, expired or unknown token are indistinguishable from one another, on purpose. mint a fresh token per call; they are cheap.

example

import requests

API_KEY = "rk_live_•••••••••"
BASE = "https://silk-api.rumik.ai"

def register_call(agent: str) -> dict:
    r = requests.post(
        f"{BASE}/v1/register-call",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"agent_id": agent},
        timeout=30,
    )
    r.raise_for_status()
    return r.json()      # {access_token, expires_in, sample_rate}

// Your endpoint: mint a token for the browser, keep the API key on the server.
app.post("/api/agent-token", async (req, res) => {
  const upstream = await fetch("https://silk-api.rumik.ai/v1/register-call", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.RUMIK_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ agent_id: "ua_fe3277d8" }),
  });
  res.status(upstream.status).json(await upstream.json());
});

next: open the socket.

documentation

sdk

integrations

cookbook

api reference

request

response

what it does not do

the agent must be deployed

single use

example

​request

​response

​what it does not do

​the agent must be deployed

​single use

​example

request

response

what it does not do

the agent must be deployed

single use

example