---
title: "Create Agent From Prompt"
method: POST
path: "/voice/agents/generation"
tags: ["Voice Agents"]
---

# Create Agent From Prompt

`POST /voice/agents/generation`

## Request

- Base URL: `https://api.speakai.co/v1`
- URL: `https://api.speakai.co/v1/voice/agents/generation`
- Auth: API key in header `x-speakai-key` and API key in header `x-access-token`

### Create Agent From Prompt

Requires the OWNER or ADMIN role. Prompt-first creation: creates a new agent server-side with placeholder config, then runs the same generation flow as Generate Agent Config against it. Response always includes the new agentId, plus either an agent key (generation succeeded) or needsFollowUp: true (prompt needs more detail) -- see Generate Agent Config for both shapes.

## Request body

- object
  - `prompt` string, required: Required. Describe the agent you want in a sentence or two.
  - `name` string
  - `manualInstructions` string: Skips the thin-prompt follow-up question and generates immediately, folding this in as additional context.

## Response `201`

Created

- object
  - `status` 'success'
  - `data` union
    - object: When the prompt still needs more detail after the follow-up.
      - `agentId` string: The newly created agent's id.
      - `needsFollowUp` true
      - `followUpQuestion` string
      - `extracted` object
    - object: When generation succeeded and the agent was updated.
      - `agentId` string: The newly created agent's id.
      - `agent` object: The updated agent. Full shape documented on the Voice Agents page.

## Other responses

- `400`: Validation failed
- `403`: Caller's role is not OWNER or ADMIN

---

[API](https://skmtc.dev/speakai/apis/speak-ai-api.md) · [All operations](https://skmtc.dev/speakai/apis/speak-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/speakai/apis/speak-ai-api/revisions/52d777e6d46e?raw)