---
title: "Create agent thread"
method: POST
path: "/project/{projectId}/agents/threads"
tags: ["Agent"]
---

# Create agent thread

`POST /project/{projectId}/agents/threads`

## Request

- Base URL: `https://api.takeshape.io`
- URL: `https://api.takeshape.io/project/{projectId}/agents/threads`
- Auth: HTTP bearer

Creates a new conversation thread/session for an AI agent. The thread maintains state across multiple messages.

## Path parameters

- `projectId` string, uuid, required

## Request body

- CreateThreadBody
  - `agentName` string, required: The name of the agent to create a thread for

## Response `200`

Thread created successfully

- ThreadResponse
  - `id` string, required: The unique session/thread ID
  - `agentName` string, required: The name of the agent
  - `status` 'created' | 'started' | 'suspended' | 'done', required: The status of the agent thread
  - `schemaId` string, required: The schema ID associated with the thread
  - `schemaHash` string, required: The schema hash for version tracking
  - `createdAt` string, required: ISO timestamp when the thread was created
  - `updatedAt` string, required: ISO timestamp when the thread was last updated
  - `firstMessageInput` union: The input of the first message in the thread, or empty if no messages yet
    - object
      - `type` 'string', required
      - `content` string, required
    - object
      - `type` 'unknown', required
      - `data` unknown
  - `duration` number: Duration of the thread in milliseconds, only set when status is done
  - `lastMessageOutput` union: The output of the last message in the thread, if available
    - object
      - `type` 'generate', required
      - `data` unknown
    - object
      - `type` 'graphql', required
      - `data` unknown
    - object
      - `type` 'chat', required
      - `data` object, required
        - `content` string, required: The text content of the chat message
        - `artifact` object: Optional artifacts associated with the chat message
        - `references` object[], required: References to other threads or messages
          - `_tid` string, required: The thread ID that this message references
    - object
      - `type` 'unknown', required
      - `data` unknown

## Other responses

- `400`: Invalid request - agent does not exist or has no inputs
- `401`: Unauthorized - invalid or missing authentication
- `404`: Project or schema not found

---

[API](https://skmtc.dev/takeshape/apis/takeshape-rest-api.md) - [All operations](https://skmtc.dev/takeshape/apis/takeshape-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/takeshape/apis/takeshape-rest-api/revisions/2e088f4d4c64?raw)