> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rumik.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# register a call

> mint a call id and exchange your api key for a single-use token that starts exactly one call — a realtime socket or a web call — so a browser never holds the key. the `call_id` is yours before anything runs, so a before-call tool that receives `{call_id}` can be matched to your own records. registering does not start a call: nothing is billed and no capacity is taken until the socket connects or the web call starts.



## OpenAPI

````yaml /openapi.json post /v1/register-call
openapi: 3.1.0
info:
  title: silk api
  version: 1.0.0
  description: >-
    rumik ai's speech api. synthesize speech with the expressive `muga` model,
    the faster `mulberry` model or the multilingual `mulberry-1.6` model over
    http or a streaming websocket session, run conversational voice agents over
    webrtc, a realtime pcm socket or the phone, and manage everything the agents
    playground does — agents, voices, variables, tools, phone numbers, sip
    trunks and outbound calls — with the same api key.
  contact:
    name: rumik ai
    url: https://rumik.ai
servers:
  - url: https://silk-api.rumik.ai
    description: production
security:
  - bearerAuth: []
tags:
  - name: speech
    description: text-to-speech over HTTP and WebSocket.
  - name: voice agents
    description: start calls with a deployed agent from your own app.
  - name: agents
    description: build, configure, deploy and inspect your agents.
  - name: calls
    description: place outbound phone calls and read call history.
  - name: voices
    description: the voices, languages and styles an agent may use.
  - name: variables
    description: account-wide `{name}` prompt variables and their defaults.
  - name: tools
    description: HTTP tools agents call before or during a call.
  - name: phone numbers
    description: 'numbers rented through rumik: search, rent, connect, release.'
  - name: sip trunks
    description: bring your own numbers over SIP.
paths:
  /v1/register-call:
    post:
      tags:
        - voice agents
      summary: register a call
      description: >-
        mint a call id and exchange your api key for a single-use token that
        starts exactly one call — a realtime socket or a web call — so a browser
        never holds the key. the `call_id` is yours before anything runs, so a
        before-call tool that receives `{call_id}` can be matched to your own
        records. registering does not start a call: nothing is billed and no
        capacity is taken until the socket connects or the web call starts.
      operationId: registerCall
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterCallRequest'
            examples:
              default:
                value:
                  agent_id: ua_fe3277d8
      responses:
        '201':
          description: the call's id and a single-use token to start it with.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterCallResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/AgentNotFound'
        '409':
          $ref: '#/components/responses/AgentNotDeployed'
        '422':
          $ref: '#/components/responses/ValidationError'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  schemas:
    RegisterCallRequest:
      type: object
      required:
        - agent_id
      properties:
        agent_id:
          type: string
          example: ua_fe3277d8
          description: >-
            the agent to run — its uuid or its `ua_…` handle. `agentId` is
            accepted too.
    RegisterCallResponse:
      type: object
      properties:
        access_token:
          type: string
          example: wct_9f8c2b1e4d5a4e6fa7b8c9d0e1f2a3b4
          description: >-
            single-use token, prefixed `wct_`. pass as `?token=` when opening
            the realtime socket, or as `accessToken` to `/v1/webcall`.
        expires_in:
          type: integer
          example: 300
          description: seconds the token stays redeemable.
        sample_rate:
          type: integer
          example: 24000
          description: >-
            audio sample rate for a realtime session, in hz. a web call
            negotiates its own.
        call_id:
          type: string
          format: uuid
          example: 01a05b4e-2c1d-7a3e-9f10-5b6c7d8e9f01
          description: >-
            the call's id, minted now. it is what `session.created` and the web
            call's `callId` carry once the call starts, what conversations and
            usage show, and what your tools receive as `{call_id}`.
    Error:
      type: object
      properties:
        error:
          type: string
          description: human-readable error message.
        code:
          type: string
          description: machine-readable error code.
  responses:
    Unauthorized:
      description: bearer token missing, invalid, or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: key revoked or account disabled.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    AgentNotFound:
      description: no such agent on this account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    AgentNotDeployed:
      description: >-
        the agent exists but has never been deployed, so no version is live to
        run.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: validation failed. check the error field.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unavailable:
      description: upstream temporarily unavailable. retry shortly.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        your rumik api key, e.g. `rk_live_...`. create one in the rumik
        dashboard.

````