register a call

POST /v1/register-call mints a call’s id and exchanges your api key for a short-lived token that starts exactly one call — a realtime socket or a web call. 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. because the id comes back before anything runs, it is also the way to know a call’s id before the agent’s before-call tools receive it as {call_id} — see knowing the call id first.

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, or as accessToken to POST /v1/webcall.

integer

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

integer

the audio sample rate a realtime session will use, in Hz. a web call negotiates its own and ignores this.

string

the call’s id, minted now so you hold it before anything runs. it is the same value session.created carries once a socket call is live and callId in a web call’s response, what shows up in conversations and your usage, and what your tools receive as {call_id} — including the before-call tools, which run when the call starts, not now.

{
  "access_token": "wct_9f8c2b1e4d5a4e6fa7b8c9d0e1f2a3b4",
  "expires_in": 300,
  "sample_rate": 24000,
  "call_id": "01a05b4e-2c1d-7a3e-9f10-5b6c7d8e9f01"
}

what it does not do

registering a call does not start one. nothing is billed, no capacity slot is taken, no before-call tool runs and no agent is spawned until the token is redeemed — the socket connects, or /v1/webcall is called with it — 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 at the start: the socket accepts, sends an error frame, and closes with code 4000 (see connection errors); the web call answers 429 — but unlike a one-hop start the token is already spent by then, so retrying means registering again, under a new call_id.

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
start_web_call(token)   # 401 — same token, same answer

one token is one call, whichever surface starts it: a token spent on /v1/webcall cannot open the socket, and vice versa. 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, call_id}

// 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