---
title: "Build a Roark-hosted agent"
method: POST
path: "/v1/agent/build"
tags: ["Agent"]
---

# Build a Roark-hosted agent

`POST /v1/agent/build`

## Request

- Base URL: `https://api.roark.ai`
- URL: `https://api.roark.ai/v1/agent/build`
- Auth: HTTP bearer

Creates a new Roark-hosted agent from a one-line job description. Roark authors the system prompt and hosts the config, so the agent is live and self-improvable from creation.

## Request body

- object: Input for building a new Roark-hosted agent
  - `name` string, required: Name of the agent
  - `jobDescription` string, required: One-line description of what the agent should do. Roark authors the system prompt from this.
  - `voice` string, nullable: Optional display name of the agent's voice. The authored prompt matches its delivery to it.
  - `tts` object, nullable: Optional provider voice the hosted agent speaks with
    - `provider` 'CARTESIA' | 'ELEVENLABS' | 'OPENAI' | 'RIME', required: Text-to-speech provider, for example ELEVENLABS
    - `voiceId` string, required: The provider's id for the voice
    - `model` string, nullable: The provider's voice model, for example eleven_flash_v2_5. Its current one when omitted
  - `stt` object, nullable: Optional transcriber the hosted agent hears with. Roark's default when omitted
    - `provider` 'DEEPGRAM' | 'OPENAI_WHISPER' | 'SPEECHMATICS' | 'ASSEMBLYAI' | 'ELEVENLABS', required: Speech-to-text provider, for example DEEPGRAM
    - `model` string, required: The provider's model id, for example nova-3
  - `llm` object, nullable: Optional text model the hosted agent thinks with. Roark's default when omitted
    - `provider` 'OPENAI' | 'ANTHROPIC' | 'GOOGLE' | 'XAI' | 'ULTRAVOX' | 'AWS' | 'ELEVENLABS', required: Text model provider, for example OPENAI
    - `model` string, required: The provider's model id, for example gpt-4.1

## Response `201`

The built agent

- object
  - `data` object, required
    - `id` string, uuid, required: Unique identifier of the agent
    - `name` string, required: Name of the agent
    - `description` string, nullable, required: Description of the agent
    - `customId` string, nullable, required: Custom identifier for the agent
    - `createdAt` string, required: Creation timestamp in ISO 8601 format
    - `updatedAt` string, required: Last update timestamp in ISO 8601 format

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `500`: Internal Server Error

## Changes

> 187 revisions in range; 1 not diffed.

- **2026-10-31** `08bd8a3ed869`: 4 info
  - added the new optional request property `llm`
  - added the new optional request property `stt`
  - added the new optional request property `tts/model`
  - added the non-success response with the status `403`
- **2026-10-28** `d82d66648ffd`: 1 breaking, 5 info
  - request property `tts/provider` was restricted to a list of enum values
  - added the new `CARTESIA` enum value to the request property `tts/provider`
  - added the new `ELEVENLABS` enum value to the request property `tts/provider`
  - added the new `OPENAI` enum value to the request property `tts/provider`
  - …2 more
- **2026-10-27** `0b187319498a`: 1 info
  - added the new optional request property `tts`
- **2026-09-23** `c1f2ac2da51d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/agent/build/post.md)

---

[API](https://skmtc.dev/roarkhq/apis/roark-analytics-api.md) - [All operations](https://skmtc.dev/roarkhq/apis/roark-analytics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roarkhq/apis/roark-analytics-api/revisions/1a91a5c90e44?raw)