---
title: "Create, update, or read a fi3 thread"
method: POST
path: "/v3/teams/{team_id}/users/{user_id}/fi3/thread"
tags: ["v3", "Fi3"]
---

# Create, update, or read a fi3 thread

`POST /v3/teams/{team_id}/users/{user_id}/fi3/thread`

Handle fi3 thread requests.

## Path parameters

- `team_id` string, required
- `user_id` string, required

## Request body

- Fi3ThreadRequest
  - `method` 'upsert' | 'delete' | 'stop' | 'marimo_start' | 'update_metadata' | 'show_artifacts' | 'warm_sandbox', required — Operation method
  - `thread_id` string — Thread id to use for the agent
  - `user_message` string — User message to the fi agent
  - `context_blocks` ContextBlock[] — List of context blocks to use for the agent
    - `id` string — Unique UUID identifier for the context block
    - `query` string — Query for the context block.
    - `didAgentChange` boolean — Whether the agent changed the query - determines if it gets applied or not
    - `results` object[], nullable — Result rows from the block, if available
    - `title` string, nullable — Title of the context block
  - `table_integration_id` string — Table integration id to use for the agent (DuckDB)
  - `cube_integration_id` string — Cube integration id to use for the agent
  - `application_context` string, nullable — Additional context about the application state
  - `model` string, nullable — Claude model to use (e.g., 'sonnet', 'opus')
  - `doc_id` string, nullable — ID of the doc currently being edited by the user
  - `doc_yaml_content` string, nullable — Current doc.yaml content from frontend Doc view to mount in sandbox
  - `thread_title` string, nullable — New title for the thread
  - `doc_discovery_mode` 'preload_recent' | 'preload_all' | 'lazy' — Document discovery mode for loading team docs
  - `preload_doc_ids` string[] — Optional explicit list of doc IDs to pre-load
  - `max_preload_docs` integer — Maximum number of docs to pre-load (default 50)
  - `max_files` integer — Maximum number of files to return with download URLs
  - `app_events` object[] — Application events like file uploads
  - `project_id` string, nullable — Project ID to associate the thread with
  - `sandboxTier` 'small' | 'medium' | 'large'

## Response `201`

Success

- Fi2BackgroundResponse
  - `success` boolean, required — Whether the background execution was successful
  - `message` string — Message from the background execution
  - `result` unknown
  - `raw_output` string — Raw output from Claude Code
  - `error` string, nullable — Error message if execution failed
  - `execution_time` number — Execution time in seconds
  - `sandbox_id` string, nullable — E2B sandbox ID used for execution
  - `html_files` object[] — Generated files (HTML and Python) with filename, content, and file_type

## Other responses

- `422` — Validation Error
- `500` — Server exception

---

[API](https://skmtc.dev/definite/apis/defapi.md) · [All operations](https://skmtc.dev/definite/apis/defapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/definite/defapi/revisions/5ea378187147/schema)