---
title: "Start an agent chat"
method: POST
path: "/v1/agent-chats"
tags: ["Agent chats"]
---

# Start an agent chat

`POST /v1/agent-chats`

## Request

- Base URL: `https://api.tella.com`
- URL: `https://api.tella.com/v1/agent-chats`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/withchima/apis/tella-public-api/docs/v1/agent-chats/post.ts> (a function with typed inputs; its response is checked against the schema)

Start a chat with Tella's editor agent in a video you can edit, as if you had typed `prompt` in its agent chat; without `videoId` it first makes a new, empty video. The agent works in the background and spends the workspace's AI Credits. Follow it with `GET /v1/agent-chats?videoId=`.

## Request body

- StartAgentChatRequest
  - `name` string: The new video's name. Only used without `videoId`; left out, the prompt's start names it.
  - `prompt` string, required: What the agent should do, in full: it is all the agent knows. Sent as if the user had typed it in the video's agent chat.
  - `videoId` string: A video you can edit. Leave it out to start the chat in a new, empty video.

## Response `201`

Created

- StartAgentChatResponse
  - `chatId` string, required
  - `url` string, required: Opens the chat in the video's editor
  - `videoId` string, required

## Other responses

- `400`: The request was malformed or contained invalid parameters.
- `401`: Authentication is required. Provide a valid API key.
- `403`: You don't have permission to access this resource.
- `404`: The requested resource was not found.
- `409`: The request conflicts with the resource's current state, e.g. an Idempotency-Key whose first request is still in progress. Retry once it settles.
- `429`: You have exceeded the rate limit. Please slow down.
- `500`: An unexpected error occurred
- `501`: The requested operation is not implemented.
- `503`: A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay.

## Changes

> 65 revisions in range; 1 not diffed.

- **2026-10-27** `240a74ea0ff7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/agent-chats/post.md)

---

[API](https://skmtc.dev/withchima/apis/tella-public-api.md) - [All operations](https://skmtc.dev/withchima/apis/tella-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/withchima/apis/tella-public-api/revisions/0cc3fcd307ad?raw)