From be42d21842b667670fd7178359bab2215e2cedab Mon Sep 17 00:00:00 2001 From: Ed_ Date: Sun, 22 Feb 2026 09:17:32 -0500 Subject: [PATCH] docs --- MainContext.md | 9 +- Readme.md | 37 +- aggregate.py | 12 + ai_client.py | 12 + config_bootslop.toml | 28 - docs/Readme.md | 45 + docs/anthropic_api_files.md | 1149 ---- docs/anthropic_api_ref_create_message.md | 4691 ------------- docs/anthropic_api_ref_create_message_beta.md | 5906 ----------------- docs/anthropic_prompt_caching.md | 0 docs/guide_architecture.md | 85 + docs/guide_tools.md | 48 + gui.py | 12 +- manual_slop.toml | 28 +- mcp_client.py | 14 + project_manager.py | 6 + read_main_ctx.py | 8 - session_logger.py | 13 +- summarize.py | 13 +- 19 files changed, 312 insertions(+), 11804 deletions(-) delete mode 100644 config_bootslop.toml create mode 100644 docs/Readme.md delete mode 100644 docs/anthropic_api_files.md delete mode 100644 docs/anthropic_api_ref_create_message.md delete mode 100644 docs/anthropic_api_ref_create_message_beta.md delete mode 100644 docs/anthropic_prompt_caching.md create mode 100644 docs/guide_architecture.md create mode 100644 docs/guide_tools.md delete mode 100644 read_main_ctx.py diff --git a/MainContext.md b/MainContext.md index f23d8a4..9971b28 100644 --- a/MainContext.md +++ b/MainContext.md @@ -232,4 +232,11 @@ This allows you to choose the best viewing mode for either prose or wide code bl ### Maximizable Discussion Entries Each entry in the **Discussion History** now features a [+ Max] button. Clicking this button opens the full text of that entry in the large **Text Viewer** popup, making it easy to read or copy large blocks of text from the conversation history without being constrained by the small input box. -\n\n## Multi-Viewport & Docking\nThe application now supports Dear PyGui Viewport Docking. Windows can be dragged outside the main application area or docked together. A global 'Windows' menu in the viewport menu bar allows you to reopen any closed panels. \ No newline at end of file +\n\n## Multi-Viewport & Docking\nThe application now supports Dear PyGui Viewport Docking. Windows can be dragged outside the main application area or docked together. A global 'Windows' menu in the viewport menu bar allows you to reopen any closed panels. + +## Extensive Documentation (2026-02-22) + +Documentation has been completely rewritten matching the strict, structural format of `VEFontCache-Odin`. +- `docs/guide_architecture.md`: Details the Python implementation algorithms, queue management for UI rendering, the specific AST heuristics used for context aggregation, and the distinct algorithms for trimming Anthropic history vs Gemini state caching. +- `docs/Readme.md`: The core interface manual. +- `docs/guide_tools.md`: Security architecture for `_is_allowed` paths and definitions of the read-only vs destructive tool pipeline. diff --git a/Readme.md b/Readme.md index ecffe4c..93bbef1 100644 --- a/Readme.md +++ b/Readme.md @@ -1,22 +1,31 @@ # Manual Slop -Vibe coding.. but more manual +An AI coding assistant interface featuring multi-project management, rich discussion history, dynamic tool utilization, and a robust frontend. -![img](./gallery/python_2026-02-21_23-37-29.png) +This tool is designed to work as an auxiliary assistant that natively interacts with your codebase via PowerShell and MCP-like file tools, supporting both Anthropic and Gemini APIs. -## Instructions +Features: -1. Make a credentials.toml in the immediate directory of your clone: +* Multi-provider support (Anthropic & Gemini). +* Multi-project workspace management via TOML configuration. +* Rich discussion history with branching and timestamps. +* Real-time file context aggregation and summarization. +* Integrated tool execution: + * PowerShell scripting for file modifications. + * MCP-like filesystem tools (read, list, search, summarize). + * Web search and URL fetching. +* Extensive UI features: + * Word-wrap toggles. + * Popup text viewers for large script/output inspection. + * Color theming and UI scaling. -```toml -[gemini] -api_key = "****" -[anthropic] -api_key = "****" -``` +## Documentation -2. Have fun. This is experiemntal slop. +* [docs/Readme.md](docs/Readme.md) for the interface and usage guide +* [docs/guide_tools.md](docs/guide_tools.md) for information on the AI tooling capabilities +* [docs/guide_architecture.md](docs/guide_architecture.md) for an in-depth breakdown of the codebase architecture -```ps1 -uv run .\gui.py -``` +## Running + +Use `uv run gui.py` or `python gui.py` to launch the frontend. +Requires a `credentials.toml` file in the root directory containing `gemini` and `anthropic` API keys. diff --git a/aggregate.py b/aggregate.py index f64ea90..7351d1c 100644 --- a/aggregate.py +++ b/aggregate.py @@ -1,4 +1,16 @@ # aggregate.py +""" +Note(Gemini): +This module orchestrates the construction of the final Markdown context string. +Instead of sending every file to the AI raw (which blows up tokens), this uses a pipeline: +1. Resolve paths (handles globs and absolute paths). +2. Build file items (raw content). +3. If 'summary_only' is true (which is the default behavior now), it pipes the files through + summarize.py to generate a compacted view. + +This is essential for keeping prompt tokens low while giving the AI enough structural info +to use the MCP tools to fetch only what it needs. +""" import tomllib import re import glob diff --git a/ai_client.py b/ai_client.py index 89bb000..916959a 100644 --- a/ai_client.py +++ b/ai_client.py @@ -1,3 +1,15 @@ +# ai_client.py +""" +Note(Gemini): +Acts as the unified interface for multiple LLM providers (Anthropic, Gemini). +Abstracts away the differences in how they handle tool schemas, history, and caching. + +For Anthropic: aggressively manages the ~200k token limit by manually culling +stale [FILES UPDATED] entries and dropping the oldest message pairs. + +For Gemini: injects the initial context directly into system_instruction +during chat creation to avoid massive history bloat. +""" # ai_client.py import tomllib import json diff --git a/config_bootslop.toml b/config_bootslop.toml deleted file mode 100644 index b6b7e16..0000000 --- a/config_bootslop.toml +++ /dev/null @@ -1,28 +0,0 @@ -[output] -namespace = "colorforth_bootslop" -output_dir = "." - -[files] -base_dir = "C:/projects/forth/bootslop" -paths = [ - "./attempt_1/*", - "./scripts/*", - "./references/Architectural_Consolidation.md", - "./references/neokineogfx_in-depth.md", - "./references/blog_in-depth.md", - "./references/kyra_in-depth.md", - ".editorconfig", - "GEMINI.md", - "CONVENTIONS.md", -] - -[screenshots] -base_dir = "C:/Users/Ed/scoop/apps/sharex/current/ShareX/Screenshots/2026-02" -paths = [] - -[discussion] -history = [] - -[ai] -provider = "anthropic" -model = "claude-sonnet-4-6" diff --git a/docs/Readme.md b/docs/Readme.md new file mode 100644 index 0000000..76f8b55 --- /dev/null +++ b/docs/Readme.md @@ -0,0 +1,45 @@ +# Manual Slop + +A GUI orchestrator for local LLM-driven coding sessions, built to prevent the AI from running wild and to provide total transparency into the context and execution state. + +## Core Management Panels + +### Projects Panel +The heart of context management. +- **Configuration:** You specify the Git Directory (for commit tracking) and a Main Context File (the markdown file containing your project's notes and schema). +- **Word-Wrap Toggle:** Dynamically swaps text rendering in large read-only panels (Responses, Comms Log) between unwrapped (ideal for viewing precise code formatting) and wrapped (ideal for prose). +- **Project Switching:** Switch between different .toml profiles to instantly swap out your entire active file list, discussion history, and settings. + +### Discussion History +Manages your conversational branches, preventing context poisoning across different tasks. +- **Discussions Sub-Menu:** Allows you to create separate timelines for different tasks (e.g., "Refactoring Auth" vs. "Adding API Endpoints"). +- **Git Commit Tracking:** Clicking "Update Commit" reads HEAD from your project's git directory and stamps the discussion. +- **Entry Management:** Each turn has a Role (User, AI, System). You can toggle entries between **Read** and **Edit** modes, collapse them, or hit [+ Max] to open them in the Global Text Viewer. +- **Auto-Add:** If toggled, anything sent from the "Message" panel and returned to the "Response" panel is automatically appended to the current discussion history. + +### Files & Screenshots +Controls what is explicitly fed into the context compiler. +- **Base Dir:** Defines the root for path resolution and tool constraints. +- **Paths:** Explicit files or wildcard globs (e.g., src/**/*.rs). +- When generating a request, these files are summarized symbolically (summarize.py) to conserve tokens, unless the AI explicitly decides to read their full contents via its internal tools. + +## Interaction Panels + +### Provider +Switch between API backends (Gemini, Anthropic) on the fly. Clicking "Fetch Models" queries the active provider for the latest model list. + +### Message & Response +- **Message:** Your input field. +- **Gen + Send:** Compiles the markdown context and dispatches the background thread to the AI. +- **MD Only:** Dry-runs the compiler so you can inspect the generated _00N.md without triggering an API charge. +- **Response:** The read-only output. Flashes green when a new response arrives. + +### Global Text Viewer & Script Outputs +- **Last Script Output:** Whenever the AI executes a background script, this window pops up, flashing blue. It contains both the executed script and the stdout/stderr. +- **Text Viewer:** A large, resizable global popup invoked anytime you click a [+] or [+ Maximize] button in the UI. Used for deep-reading long logs, discussion entries, or script bodies. + +## System Prompts +Provides two text inputs for overriding default instructions: +1. **Global:** Applied across every project you load. +2. **Project:** Specific to the active workspace. +These are concatenated onto the strict tool-usage guidelines the agent is initialized with. diff --git a/docs/anthropic_api_files.md b/docs/anthropic_api_files.md deleted file mode 100644 index aec68d4..0000000 --- a/docs/anthropic_api_files.md +++ /dev/null @@ -1,1149 +0,0 @@ -# Files API - ---- - -The Files API lets you upload and manage files to use with the Claude API without re-uploading content with each request. This is particularly useful when using the [code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool) to provide inputs (e.g. datasets and documents) and then download outputs (e.g. charts). You can also use the Files API to prevent having to continually re-upload frequently used documents and images across multiple API calls. You can [explore the API reference directly](/docs/en/api/files-create), in addition to this guide. - - -The Files API is currently in beta. Please reach out through our [feedback form](https://forms.gle/tisHyierGwgN4DUE9) to share your experience with the Files API. - - - -This feature is in beta and is **not** covered by [Zero Data Retention (ZDR)](/docs/en/build-with-claude/zero-data-retention) arrangements. Beta features are excluded from ZDR. - - -## Supported models - -Referencing a `file_id` in a Messages request is supported in all models that support the given file type. For example, [images](/docs/en/build-with-claude/vision) are supported in all Claude 3+ models, [PDFs](/docs/en/build-with-claude/pdf-support) in all Claude 3.5+ models, and [various other file types](/docs/en/agents-and-tools/tool-use/code-execution-tool#supported-file-types) for the code execution tool in Claude Haiku 4.5 plus all Claude 3.7+ models. - -The Files API is currently not supported on Amazon Bedrock or Google Vertex AI. - -## How the Files API works - -The Files API provides a simple create-once, use-many-times approach for working with files: - -- **Upload files** to our secure storage and receive a unique `file_id` -- **Download files** that are created from skills or the code execution tool -- **Reference files** in [Messages](/docs/en/api/messages) requests using the `file_id` instead of re-uploading content -- **Manage your files** with list, retrieve, and delete operations - -## How to use the Files API - - -To use the Files API, you'll need to include the beta feature header: `anthropic-beta: files-api-2025-04-14`. - - -### Uploading a file - -Upload a file to be referenced in future API calls: - - -```bash Shell -curl -X POST https://api.anthropic.com/v1/files \ - -H "x-api-key: $ANTHROPIC_API_KEY" \ - -H "anthropic-version: 2023-06-01" \ - -H "anthropic-beta: files-api-2025-04-14" \ - -F "file=@/path/to/document.pdf" -``` - -```python Python -import anthropic - -client = anthropic.Anthropic() -client.beta.files.upload( - file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"), -) -``` - -```typescript TypeScript -import Anthropic, { toFile } from "@anthropic-ai/sdk"; -import fs from "fs"; - -const anthropic = new Anthropic(); - -await anthropic.beta.files.upload({ - file: await toFile(fs.createReadStream("/path/to/document.pdf"), undefined, { type: "application/pdf" }) -}, { - betas: ["files-api-2025-04-14"] -}); -``` - -```java Java -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import java.nio.file.Path; - -AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - -var file = client.beta().files().upload( - Path.of("/path/to/document.pdf") -); - -System.out.println(file.id()); -``` - -```go Go -package main - -import ( - "context" - "fmt" - "os" - - "github.com/anthropics/anthropic-sdk-go" -) - -func main() { - client := anthropic.NewClient() - - file, _ := os.Open("/path/to/document.pdf") - defer file.Close() - - response, _ := client.Beta.Files.Upload(context.Background(), - anthropic.BetaFileUploadParams{ - File: file, - }) - - fmt.Println(response.ID) -} -``` - -```ruby Ruby -require "anthropic" - -client = Anthropic::Client.new - -file = client.beta.files.upload( - file: File.open("/path/to/document.pdf", "rb") -) - -puts file.id -``` - -```csharp C# -using Anthropic; - -var client = new AnthropicClient(); - -var file = await client.Beta.Files.UploadAsync( - new FileUploadParams - { - File = File.OpenRead("/path/to/document.pdf") - }); - -Console.WriteLine(file.Id); -``` - -```php PHP -beta->files->upload([ - 'file' => fopen('/path/to/document.pdf', 'r') -]); - -echo $file->id; -``` - - -The response from uploading a file will include: - -```json -{ - "id": "file_011CNha8iCJcU1wXNR6q4V8w", - "type": "file", - "filename": "document.pdf", - "mime_type": "application/pdf", - "size_bytes": 1024000, - "created_at": "2025-01-01T00:00:00Z", - "downloadable": false -} -``` - -### Using a file in messages - -Once uploaded, reference the file using its `file_id`: - - -```bash Shell -curl -X POST https://api.anthropic.com/v1/messages \ - -H "x-api-key: $ANTHROPIC_API_KEY" \ - -H "anthropic-version: 2023-06-01" \ - -H "anthropic-beta: files-api-2025-04-14" \ - -H "content-type: application/json" \ - -d '{ - "model": "claude-opus-4-6", - "max_tokens": 1024, - "messages": [ - { - "role": "user", - "content": [ - { - "type": "text", - "text": "Please summarize this document for me." - }, - { - "type": "document", - "source": { - "type": "file", - "file_id": "file_011CNha8iCJcU1wXNR6q4V8w" - } - } - ] - } - ] - }' -``` - -```python Python -import anthropic - -client = anthropic.Anthropic() - -response = client.beta.messages.create( - model="claude-opus-4-6", - max_tokens=1024, - messages=[ - { - "role": "user", - "content": [ - {"type": "text", "text": "Please summarize this document for me."}, - { - "type": "document", - "source": { - "type": "file", - "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", - }, - }, - ], - } - ], - betas=["files-api-2025-04-14"], -) -print(response) -``` - -```typescript TypeScript -import { Anthropic } from "@anthropic-ai/sdk"; - -const anthropic = new Anthropic(); - -const response = await anthropic.beta.messages.create({ - model: "claude-opus-4-6", - max_tokens: 1024, - messages: [ - { - role: "user", - content: [ - { - type: "text", - text: "Please summarize this document for me." - }, - { - type: "document", - source: { - type: "file", - file_id: "file_011CNha8iCJcU1wXNR6q4V8w" - } - } - ] - } - ], - betas: ["files-api-2025-04-14"] -}); - -console.log(response); -``` - -```java Java -import com.anthropic.client.AnthropicClient; -import com.anthropic.client.okhttp.AnthropicOkHttpClient; -import com.anthropic.models.messages.*; - -AnthropicClient client = AnthropicOkHttpClient.fromEnv(); - -MessageCreateParams params = MessageCreateParams.builder() - .model(Model.CLAUDE_OPUS_4_6) - .maxTokens(1024) - .addMessage(MessageParam.builder() - .role(Role.USER) - .content(ContentBlockParam.ofText("Please summarize this document for me.")) - .content(ContentBlockParam.ofDocument(DocumentBlockParam.builder() - .source(DocumentBlockParam.Source.ofFile( - DocumentBlockParam.Source.File.builder() - .fileId("file_011CNha8iCJcU1wXNR6q4V8w") - .build())) - .build())) - .build()) - .build(); - -Message message = client.beta().messages().create(params); -System.out.println(message); -``` - -```go Go -package main - -import ( - "context" - "fmt" - - "github.com/anthropics/anthropic-sdk-go" -) - -func main() { - client := anthropic.NewClient() - - response, _ := client.Beta.Messages.New(context.Background(), - anthropic.BetaMessageNewParams{ - Model: anthropic.ModelClaudeOpus4_6, - MaxTokens: 1024, - Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaFilesAPI2025_04_14}, - Messages: []anthropic.BetaMessageParam{ - { - Role: "user", - Content: []anthropic.BetaContentBlockParam{ - anthropic.NewBetaTextBlock("Please summarize this document for me."), - { - Type: "document", - Source: &anthropic.BetaDocumentSourceParam{ - Type: "file", - FileID: "file_011CNha8iCJcU1wXNR6q4V8w", - }, - }, - }, - }, - }, - }) - - fmt.Println(response) -} -``` - -```ruby Ruby -require "anthropic" - -client = Anthropic::Client.new - -response = client.beta.messages.create( - model: "claude-opus-4-6", - max_tokens: 1024, - betas: ["files-api-2025-04-14"], - messages: [ - { - role: "user", - content: [ - { type: "text", text: "Please summarize this document for me." }, - { - type: "document", - source: { - type: "file", - file_id: "file_011CNha8iCJcU1wXNR6q4V8w" - } - } - ] - } - ] -) - -puts response -``` - -```csharp C# -using Anthropic; - -var client = new AnthropicClient(); - -var response = await client.Beta.Messages.CreateAsync( - new BetaMessageCreateParams - { - Model = "claude-opus-4-6", - MaxTokens = 1024, - Betas = new[] { "files-api-2025-04-14" }, - Messages = new[] - { - new BetaMessageParam - { - Role = "user", - Content = new object[] - { - new { type = "text", text = "Please summarize this document for me." }, - new - { - type = "document", - source = new - { - type = "file", - file_id = "file_011CNha8iCJcU1wXNR6q4V8w" - } - } - } - } - } - }); - -Console.WriteLine(response); -``` - -```php PHP -beta->messages->create([ - 'model' => 'claude-opus-4-6', - 'max_tokens' => 1024, - 'betas' => ['files-api-2025-04-14'], - 'messages' => [ - [ - 'role' => 'user', - 'content' => [ - ['type' => 'text', 'text' => 'Please summarize this document for me.'], - [ - 'type' => 'document', - 'source' => [ - 'type' => 'file', - 'file_id' => 'file_011CNha8iCJcU1wXNR6q4V8w' - ] - ] - ] - ] - ] -]); - -print_r($response); -``` - - -### File types and content blocks - -The Files API supports different file types that correspond to different content block types: - -| File Type | MIME Type | Content Block Type | Use Case | -| :--- | :--- | :--- | :--- | -| PDF | `application/pdf` | `document` | Text analysis, document processing | -| Plain text | `text/plain` | `document` | Text analysis, processing | -| Images | `image/jpeg`, `image/png`, `image/gif`, `image/webp` | `image` | Image analysis, visual tasks | -| [Datasets, others](/docs/en/agents-and-tools/tool-use/code-execution-tool#supported-file-types) | Varies | `container_upload` | Analyze data, create visualizations | - -### Working with other file formats - -For file types that are not supported as `document` blocks (.csv, .txt, .md, .docx, .xlsx), convert the files to plain text, and include the content directly in your message: - - -```bash Shell -# Example: Reading a text file and sending it as plain text -# Note: For files with special characters, consider base64 encoding -TEXT_CONTENT=$(cat document.txt | jq -Rs .) - -curl https://api.anthropic.com/v1/messages \ - -H "content-type: application/json" \ - -H "x-api-key: $ANTHROPIC_API_KEY" \ - -H "anthropic-version: 2023-06-01" \ - -d @- < - - -For .docx files containing images, convert them to PDF format first, then use [PDF support](/docs/en/build-with-claude/pdf-support) to take advantage of the built-in image parsing. This allows using citations from the PDF document. - - -#### Document blocks - -For PDFs and text files, use the `document` content block: - -```json -{ - "type": "document", - "source": { - "type": "file", - "file_id": "file_011CNha8iCJcU1wXNR6q4V8w" - }, - "title": "Document Title", // Optional - "context": "Context about the document", // Optional - "citations": {"enabled": true} // Optional, enables citations -} -``` - -#### Image blocks - -For images, use the `image` content block: - -```json -{ - "type": "image", - "source": { - "type": "file", - "file_id": "file_011CPMxVD3fHLUhvTqtsQA5w" - } -} -``` - -### Managing files - -#### List files - -Retrieve a list of your uploaded files: - - -```bash Shell -curl https://api.anthropic.com/v1/files \ - -H "x-api-key: $ANTHROPIC_API_KEY" \ - -H "anthropic-version: 2023-06-01" \ - -H "anthropic-beta: files-api-2025-04-14" -``` - -```python Python -import anthropic - -client = anthropic.Anthropic() -files = client.beta.files.list() -``` - -```typescript TypeScript -import { Anthropic } from "@anthropic-ai/sdk"; - -const anthropic = new Anthropic(); -const files = await anthropic.beta.files.list({ - betas: ["files-api-2025-04-14"] -}); -``` - - -#### Get file metadata - -Retrieve information about a specific file: - - -```bash Shell -curl https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w \ - -H "x-api-key: $ANTHROPIC_API_KEY" \ - -H "anthropic-version: 2023-06-01" \ - -H "anthropic-beta: files-api-2025-04-14" -``` - -```python Python -import anthropic - -client = anthropic.Anthropic() -file = client.beta.files.retrieve_metadata("file_011CNha8iCJcU1wXNR6q4V8w") -``` - -```typescript TypeScript -import { Anthropic } from "@anthropic-ai/sdk"; - -const anthropic = new Anthropic(); -const file = await anthropic.beta.files.retrieveMetadata( - "file_011CNha8iCJcU1wXNR6q4V8w", - { betas: ["files-api-2025-04-14"] } -); -``` - - -#### Delete a file - -Remove a file from your workspace: - - -```bash Shell -curl -X DELETE https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w \ - -H "x-api-key: $ANTHROPIC_API_KEY" \ - -H "anthropic-version: 2023-06-01" \ - -H "anthropic-beta: files-api-2025-04-14" -``` - -```python Python -import anthropic - -client = anthropic.Anthropic() -result = client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w") -``` - -```typescript TypeScript -import { Anthropic } from "@anthropic-ai/sdk"; - -const anthropic = new Anthropic(); -const result = await anthropic.beta.files.delete( - "file_011CNha8iCJcU1wXNR6q4V8w", - { betas: ["files-api-2025-04-14"] } -); -``` - - -### Downloading a file - -Download files that have been created by skills or the code execution tool: - - -```bash Shell -curl -X GET "https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w/content" \ - -H "x-api-key: $ANTHROPIC_API_KEY" \ - -H "anthropic-version: 2023-06-01" \ - -H "anthropic-beta: files-api-2025-04-14" \ - --output downloaded_file.txt -``` - -```python Python -import anthropic - -client = anthropic.Anthropic() -file_content = client.beta.files.download("file_011CNha8iCJcU1wXNR6q4V8w") - -# Save to file -with open("downloaded_file.txt", "w") as f: - f.write(file_content.decode("utf-8")) -``` - -```typescript TypeScript -import { Anthropic } from "@anthropic-ai/sdk"; -import fs from "fs/promises"; - -const anthropic = new Anthropic(); - -const fileContent = await anthropic.beta.files.download( - "file_011CNha8iCJcU1wXNR6q4V8w", - { betas: ["files-api-2025-04-14"] } -); - -// Save to file -await fs.writeFile("downloaded_file.txt", fileContent); -``` - - - -You can only download files that were created by [skills](/docs/en/build-with-claude/skills-guide) or the [code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool). Files that you uploaded cannot be downloaded. - - ---- - -## File storage and limits - -### Storage limits - -- **Maximum file size:** 500 MB per file -- **Total storage:** 100 GB per organization - -### File lifecycle - -- Files are scoped to the workspace of the API key. Other API keys can use files created by any other API key associated with the same workspace -- Files persist until you delete them -- Deleted files cannot be recovered -- Files are inaccessible via the API shortly after deletion, but they may persist in active `Messages` API calls and associated tool uses -- Files that users delete will be deleted in accordance with our [data retention policy](https://privacy.claude.com/en/articles/7996866-how-long-do-you-store-my-organization-s-data). - ---- - -## Error handling - -Common errors when using the Files API include: - -- **File not found (404):** The specified `file_id` doesn't exist or you don't have access to it -- **Invalid file type (400):** The file type doesn't match the content block type (e.g., using an image file in a document block) -- **Exceeds context window size (400):** The file is larger than the context window size (e.g. using a 500 MB plaintext file in a `/v1/messages` request) -- **Invalid filename (400):** Filename doesn't meet the length requirements (1-255 characters) or contains forbidden characters (`<`, `>`, `:`, `"`, `|`, `?`, `*`, `\`, `/`, or unicode characters 0-31) -- **File too large (413):** File exceeds the 500 MB limit -- **Storage limit exceeded (403):** Your organization has reached the 100 GB storage limit - -```json -{ - "type": "error", - "error": { - "type": "invalid_request_error", - "message": "File not found: file_011CNha8iCJcU1wXNR6q4V8w" - } -} -``` - -## Usage and billing - -File API operations are **free**: -- Uploading files -- Downloading files -- Listing files -- Getting file metadata -- Deleting files - -File content used in `Messages` requests are priced as input tokens. You can only download files created by [skills](/docs/en/build-with-claude/skills-guide) or the [code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool). - -### Rate limits - -During the beta period: -- File-related API calls are limited to approximately 100 requests per minute -- [Contact us](mailto:sales@anthropic.com) if you need higher limits for your use case - ---- - -## Upload - -**post** `/v1/files` - -Upload File - -### Header Parameters - -- `"anthropic-beta": optional array of AnthropicBeta` - - Optional header to specify the beta version(s) you want to use. - - - `UnionMember0 = string` - - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 17 more` - - - `"message-batches-2024-09-24"` - - - `"prompt-caching-2024-07-31"` - - - `"computer-use-2024-10-22"` - - - `"computer-use-2025-01-24"` - - - `"pdfs-2024-09-25"` - - - `"token-counting-2024-11-01"` - - - `"token-efficient-tools-2025-02-19"` - - - `"output-128k-2025-02-19"` - - - `"files-api-2025-04-14"` - - - `"mcp-client-2025-04-04"` - - - `"mcp-client-2025-11-20"` - - - `"dev-full-thinking-2025-05-14"` - - - `"interleaved-thinking-2025-05-14"` - - - `"code-execution-2025-05-22"` - - - `"extended-cache-ttl-2025-04-11"` - - - `"context-1m-2025-08-07"` - - - `"context-management-2025-06-27"` - - - `"model-context-window-exceeded-2025-08-26"` - - - `"skills-2025-10-02"` - - - `"fast-mode-2026-02-01"` - -### Returns - -- `FileMetadata = object { id, created_at, filename, 4 more }` - - - `id: string` - - Unique object identifier. - - The format and length of IDs may change over time. - - - `created_at: string` - - RFC 3339 datetime string representing when the file was created. - - - `filename: string` - - Original filename of the uploaded file. - - - `mime_type: string` - - MIME type of the file. - - - `size_bytes: number` - - Size of the file in bytes. - - - `type: "file"` - - Object type. - - For files, this is always `"file"`. - - - `"file"` - - - `downloadable: optional boolean` - - Whether the file can be downloaded. - -### Example - -```http -curl https://api.anthropic.com/v1/files?beta=true \ - -H 'Content-Type: multipart/form-data' \ - -H 'anthropic-version: 2023-06-01' \ - -H 'anthropic-beta: files-api-2025-04-14' \ - -H "X-Api-Key: $ANTHROPIC_API_KEY" \ - -F 'file=@/path/to/file' -``` - ---- - -## List - -**get** `/v1/files` - -List Files - -### Query Parameters - -- `after_id: optional string` - - ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. - -- `before_id: optional string` - - ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. - -- `limit: optional number` - - Number of items to return per page. - - Defaults to `20`. Ranges from `1` to `1000`. - -### Header Parameters - -- `"anthropic-beta": optional array of AnthropicBeta` - - Optional header to specify the beta version(s) you want to use. - - - `UnionMember0 = string` - - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 17 more` - - - `"message-batches-2024-09-24"` - - - `"prompt-caching-2024-07-31"` - - - `"computer-use-2024-10-22"` - - - `"computer-use-2025-01-24"` - - - `"pdfs-2024-09-25"` - - - `"token-counting-2024-11-01"` - - - `"token-efficient-tools-2025-02-19"` - - - `"output-128k-2025-02-19"` - - - `"files-api-2025-04-14"` - - - `"mcp-client-2025-04-04"` - - - `"mcp-client-2025-11-20"` - - - `"dev-full-thinking-2025-05-14"` - - - `"interleaved-thinking-2025-05-14"` - - - `"code-execution-2025-05-22"` - - - `"extended-cache-ttl-2025-04-11"` - - - `"context-1m-2025-08-07"` - - - `"context-management-2025-06-27"` - - - `"model-context-window-exceeded-2025-08-26"` - - - `"skills-2025-10-02"` - - - `"fast-mode-2026-02-01"` - -### Returns - -- `data: array of FileMetadata` - - List of file metadata objects. - - - `id: string` - - Unique object identifier. - - The format and length of IDs may change over time. - - - `created_at: string` - - RFC 3339 datetime string representing when the file was created. - - - `filename: string` - - Original filename of the uploaded file. - - - `mime_type: string` - - MIME type of the file. - - - `size_bytes: number` - - Size of the file in bytes. - - - `type: "file"` - - Object type. - - For files, this is always `"file"`. - - - `"file"` - - - `downloadable: optional boolean` - - Whether the file can be downloaded. - -- `first_id: optional string` - - ID of the first file in this page of results. - -- `has_more: optional boolean` - - Whether there are more results available. - -- `last_id: optional string` - - ID of the last file in this page of results. - -### Example - -```http -curl https://api.anthropic.com/v1/files?beta=true \ - -H 'anthropic-version: 2023-06-01' \ - -H 'anthropic-beta: files-api-2025-04-14' \ - -H "X-Api-Key: $ANTHROPIC_API_KEY" -``` - ---- - -## Download - -**get** `/v1/files/{file_id}/content` - -Download File - -### Path Parameters - -- `file_id: string` - - ID of the File. - -### Header Parameters - -- `"anthropic-beta": optional array of AnthropicBeta` - - Optional header to specify the beta version(s) you want to use. - - - `UnionMember0 = string` - - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 17 more` - - - `"message-batches-2024-09-24"` - - - `"prompt-caching-2024-07-31"` - - - `"computer-use-2024-10-22"` - - - `"computer-use-2025-01-24"` - - - `"pdfs-2024-09-25"` - - - `"token-counting-2024-11-01"` - - - `"token-efficient-tools-2025-02-19"` - - - `"output-128k-2025-02-19"` - - - `"files-api-2025-04-14"` - - - `"mcp-client-2025-04-04"` - - - `"mcp-client-2025-11-20"` - - - `"dev-full-thinking-2025-05-14"` - - - `"interleaved-thinking-2025-05-14"` - - - `"code-execution-2025-05-22"` - - - `"extended-cache-ttl-2025-04-11"` - - - `"context-1m-2025-08-07"` - - - `"context-management-2025-06-27"` - - - `"model-context-window-exceeded-2025-08-26"` - - - `"skills-2025-10-02"` - - - `"fast-mode-2026-02-01"` - -### Example - -```http -curl https://api.anthropic.com/v1/files/$FILE_ID/content?beta=true \ - -H 'anthropic-version: 2023-06-01' \ - -H 'anthropic-beta: files-api-2025-04-14' \ - -H "X-Api-Key: $ANTHROPIC_API_KEY" -``` - ---- - -## Download - -**get** `/v1/files/{file_id}/content` - -Download File - -### Path Parameters - -- `file_id: string` - - ID of the File. - -### Header Parameters - -- `"anthropic-beta": optional array of AnthropicBeta` - - Optional header to specify the beta version(s) you want to use. - - - `UnionMember0 = string` - - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 17 more` - - - `"message-batches-2024-09-24"` - - - `"prompt-caching-2024-07-31"` - - - `"computer-use-2024-10-22"` - - - `"computer-use-2025-01-24"` - - - `"pdfs-2024-09-25"` - - - `"token-counting-2024-11-01"` - - - `"token-efficient-tools-2025-02-19"` - - - `"output-128k-2025-02-19"` - - - `"files-api-2025-04-14"` - - - `"mcp-client-2025-04-04"` - - - `"mcp-client-2025-11-20"` - - - `"dev-full-thinking-2025-05-14"` - - - `"interleaved-thinking-2025-05-14"` - - - `"code-execution-2025-05-22"` - - - `"extended-cache-ttl-2025-04-11"` - - - `"context-1m-2025-08-07"` - - - `"context-management-2025-06-27"` - - - `"model-context-window-exceeded-2025-08-26"` - - - `"skills-2025-10-02"` - - - `"fast-mode-2026-02-01"` - -### Example - -```http -curl https://api.anthropic.com/v1/files/$FILE_ID/content?beta=true \ - -H 'anthropic-version: 2023-06-01' \ - -H 'anthropic-beta: files-api-2025-04-14' \ - -H "X-Api-Key: $ANTHROPIC_API_KEY" -``` - diff --git a/docs/anthropic_api_ref_create_message.md b/docs/anthropic_api_ref_create_message.md deleted file mode 100644 index 2be83e4..0000000 --- a/docs/anthropic_api_ref_create_message.md +++ /dev/null @@ -1,4691 +0,0 @@ -## Create - -**post** `/v1/messages` - -Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation. - -The Messages API can be used for either single queries or stateless multi-turn conversations. - -Learn more about the Messages API in our [user guide](https://docs.claude.com/en/docs/initial-setup) - -### Body Parameters - -- `max_tokens: number` - - The maximum number of tokens to generate before stopping. - - Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. - - Different models have different maximum values for this parameter. See [models](https://docs.claude.com/en/docs/models-overview) for details. - -- `messages: array of MessageParam` - - Input messages. - - Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. - - Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. - - If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. - - Example with a single `user` message: - - ```json - [{"role": "user", "content": "Hello, Claude"}] - ``` - - Example with multiple conversational turns: - - ```json - [ - {"role": "user", "content": "Hello there."}, - {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"}, - {"role": "user", "content": "Can you explain LLMs in plain English?"}, - ] - ``` - - Example with a partially-filled response from Claude: - - ```json - [ - {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, - {"role": "assistant", "content": "The best answer is ("}, - ] - ``` - - Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: - - ```json - {"role": "user", "content": "Hello, Claude"} - ``` - - ```json - {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]} - ``` - - See [input examples](https://docs.claude.com/en/api/messages-examples). - - Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. - - There is a limit of 100,000 messages in a single request. - - - `content: string or array of ContentBlockParam` - - - `UnionMember0 = string` - - - `UnionMember1 = array of ContentBlockParam` - - - `TextBlockParam = object { text, type, cache_control, citations }` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of TextCitationParam` - - - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `ImageBlockParam = object { source, type, cache_control }` - - - `source: Base64ImageSource or URLImageSource` - - - `Base64ImageSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` - - - `"image/jpeg"` - - - `"image/png"` - - - `"image/gif"` - - - `"image/webp"` - - - `type: "base64"` - - - `"base64"` - - - `URLImageSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `type: "image"` - - - `"image"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `DocumentBlockParam = object { source, type, cache_control, 3 more }` - - - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` - - - `Base64PDFSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "application/pdf"` - - - `"application/pdf"` - - - `type: "base64"` - - - `"base64"` - - - `PlainTextSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "text/plain"` - - - `"text/plain"` - - - `type: "text"` - - - `"text"` - - - `ContentBlockSource = object { content, type }` - - - `content: string or array of ContentBlockSourceContent` - - - `UnionMember0 = string` - - - `ContentBlockSourceContent = array of ContentBlockSourceContent` - - - `TextBlockParam = object { text, type, cache_control, citations }` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of TextCitationParam` - - - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `ImageBlockParam = object { source, type, cache_control }` - - - `source: Base64ImageSource or URLImageSource` - - - `Base64ImageSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` - - - `"image/jpeg"` - - - `"image/png"` - - - `"image/gif"` - - - `"image/webp"` - - - `type: "base64"` - - - `"base64"` - - - `URLImageSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `type: "image"` - - - `"image"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `type: "content"` - - - `"content"` - - - `URLPDFSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `type: "document"` - - - `"document"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional CitationsConfigParam` - - - `enabled: optional boolean` - - - `context: optional string` - - - `title: optional string` - - - `SearchResultBlockParam = object { content, source, title, 3 more }` - - - `content: array of TextBlockParam` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of TextCitationParam` - - - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `source: string` - - - `title: string` - - - `type: "search_result"` - - - `"search_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional CitationsConfigParam` - - - `enabled: optional boolean` - - - `ThinkingBlockParam = object { signature, thinking, type }` - - - `signature: string` - - - `thinking: string` - - - `type: "thinking"` - - - `"thinking"` - - - `RedactedThinkingBlockParam = object { data, type }` - - - `data: string` - - - `type: "redacted_thinking"` - - - `"redacted_thinking"` - - - `ToolUseBlockParam = object { id, input, name, 3 more }` - - - `id: string` - - - `input: map[unknown]` - - - `name: string` - - - `type: "tool_use"` - - - `"tool_use"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` - - Tool invocation directly from the model. - - - `DirectCaller = object { type }` - - Tool invocation directly from the model. - - - `type: "direct"` - - - `"direct"` - - - `ServerToolCaller = object { tool_id, type }` - - Tool invocation generated by a server-side tool. - - - `tool_id: string` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `ServerToolCaller20260120 = object { tool_id, type }` - - - `tool_id: string` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `ToolResultBlockParam = object { tool_use_id, type, cache_control, 2 more }` - - - `tool_use_id: string` - - - `type: "tool_result"` - - - `"tool_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `content: optional string or array of TextBlockParam or ImageBlockParam or SearchResultBlockParam or 2 more` - - - `UnionMember0 = string` - - - `UnionMember1 = array of TextBlockParam or ImageBlockParam or SearchResultBlockParam or 2 more` - - - `TextBlockParam = object { text, type, cache_control, citations }` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of TextCitationParam` - - - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `ImageBlockParam = object { source, type, cache_control }` - - - `source: Base64ImageSource or URLImageSource` - - - `Base64ImageSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` - - - `"image/jpeg"` - - - `"image/png"` - - - `"image/gif"` - - - `"image/webp"` - - - `type: "base64"` - - - `"base64"` - - - `URLImageSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `type: "image"` - - - `"image"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `SearchResultBlockParam = object { content, source, title, 3 more }` - - - `content: array of TextBlockParam` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of TextCitationParam` - - - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `source: string` - - - `title: string` - - - `type: "search_result"` - - - `"search_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional CitationsConfigParam` - - - `enabled: optional boolean` - - - `DocumentBlockParam = object { source, type, cache_control, 3 more }` - - - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` - - - `Base64PDFSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "application/pdf"` - - - `"application/pdf"` - - - `type: "base64"` - - - `"base64"` - - - `PlainTextSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "text/plain"` - - - `"text/plain"` - - - `type: "text"` - - - `"text"` - - - `ContentBlockSource = object { content, type }` - - - `content: string or array of ContentBlockSourceContent` - - - `UnionMember0 = string` - - - `ContentBlockSourceContent = array of ContentBlockSourceContent` - - - `TextBlockParam = object { text, type, cache_control, citations }` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of TextCitationParam` - - - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `ImageBlockParam = object { source, type, cache_control }` - - - `source: Base64ImageSource or URLImageSource` - - - `Base64ImageSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` - - - `"image/jpeg"` - - - `"image/png"` - - - `"image/gif"` - - - `"image/webp"` - - - `type: "base64"` - - - `"base64"` - - - `URLImageSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `type: "image"` - - - `"image"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `type: "content"` - - - `"content"` - - - `URLPDFSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `type: "document"` - - - `"document"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional CitationsConfigParam` - - - `enabled: optional boolean` - - - `context: optional string` - - - `title: optional string` - - - `ToolReferenceBlockParam = object { tool_name, type, cache_control }` - - Tool reference block that can be included in tool_result content. - - - `tool_name: string` - - - `type: "tool_reference"` - - - `"tool_reference"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `is_error: optional boolean` - - - `ServerToolUseBlockParam = object { id, input, name, 3 more }` - - - `id: string` - - - `input: map[unknown]` - - - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` - - - `"web_search"` - - - `"web_fetch"` - - - `"code_execution"` - - - `"bash_code_execution"` - - - `"text_editor_code_execution"` - - - `"tool_search_tool_regex"` - - - `"tool_search_tool_bm25"` - - - `type: "server_tool_use"` - - - `"server_tool_use"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` - - Tool invocation directly from the model. - - - `DirectCaller = object { type }` - - Tool invocation directly from the model. - - - `type: "direct"` - - - `"direct"` - - - `ServerToolCaller = object { tool_id, type }` - - Tool invocation generated by a server-side tool. - - - `tool_id: string` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `ServerToolCaller20260120 = object { tool_id, type }` - - - `tool_id: string` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `WebSearchToolResultBlockParam = object { content, tool_use_id, type, 2 more }` - - - `content: WebSearchToolResultBlockParamContent` - - - `WebSearchToolResultBlockItem = array of WebSearchResultBlockParam` - - - `encrypted_content: string` - - - `title: string` - - - `type: "web_search_result"` - - - `"web_search_result"` - - - `url: string` - - - `page_age: optional string` - - - `WebSearchToolRequestError = object { error_code, type }` - - - `error_code: WebSearchToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"max_uses_exceeded"` - - - `"too_many_requests"` - - - `"query_too_long"` - - - `"request_too_large"` - - - `type: "web_search_tool_result_error"` - - - `"web_search_tool_result_error"` - - - `tool_use_id: string` - - - `type: "web_search_tool_result"` - - - `"web_search_tool_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` - - Tool invocation directly from the model. - - - `DirectCaller = object { type }` - - Tool invocation directly from the model. - - - `type: "direct"` - - - `"direct"` - - - `ServerToolCaller = object { tool_id, type }` - - Tool invocation generated by a server-side tool. - - - `tool_id: string` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `ServerToolCaller20260120 = object { tool_id, type }` - - - `tool_id: string` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `WebFetchToolResultBlockParam = object { content, tool_use_id, type, 2 more }` - - - `content: WebFetchToolResultErrorBlockParam or WebFetchBlockParam` - - - `WebFetchToolResultErrorBlockParam = object { error_code, type }` - - - `error_code: WebFetchToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"url_too_long"` - - - `"url_not_allowed"` - - - `"url_not_accessible"` - - - `"unsupported_content_type"` - - - `"too_many_requests"` - - - `"max_uses_exceeded"` - - - `"unavailable"` - - - `type: "web_fetch_tool_result_error"` - - - `"web_fetch_tool_result_error"` - - - `WebFetchBlockParam = object { content, type, url, retrieved_at }` - - - `content: DocumentBlockParam` - - - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` - - - `Base64PDFSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "application/pdf"` - - - `"application/pdf"` - - - `type: "base64"` - - - `"base64"` - - - `PlainTextSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "text/plain"` - - - `"text/plain"` - - - `type: "text"` - - - `"text"` - - - `ContentBlockSource = object { content, type }` - - - `content: string or array of ContentBlockSourceContent` - - - `UnionMember0 = string` - - - `ContentBlockSourceContent = array of ContentBlockSourceContent` - - - `TextBlockParam = object { text, type, cache_control, citations }` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of TextCitationParam` - - - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `ImageBlockParam = object { source, type, cache_control }` - - - `source: Base64ImageSource or URLImageSource` - - - `Base64ImageSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` - - - `"image/jpeg"` - - - `"image/png"` - - - `"image/gif"` - - - `"image/webp"` - - - `type: "base64"` - - - `"base64"` - - - `URLImageSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `type: "image"` - - - `"image"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `type: "content"` - - - `"content"` - - - `URLPDFSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `type: "document"` - - - `"document"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional CitationsConfigParam` - - - `enabled: optional boolean` - - - `context: optional string` - - - `title: optional string` - - - `type: "web_fetch_result"` - - - `"web_fetch_result"` - - - `url: string` - - Fetched content URL - - - `retrieved_at: optional string` - - ISO 8601 timestamp when the content was retrieved - - - `tool_use_id: string` - - - `type: "web_fetch_tool_result"` - - - `"web_fetch_tool_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` - - Tool invocation directly from the model. - - - `DirectCaller = object { type }` - - Tool invocation directly from the model. - - - `type: "direct"` - - - `"direct"` - - - `ServerToolCaller = object { tool_id, type }` - - Tool invocation generated by a server-side tool. - - - `tool_id: string` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `ServerToolCaller20260120 = object { tool_id, type }` - - - `tool_id: string` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `CodeExecutionToolResultBlockParam = object { content, tool_use_id, type, cache_control }` - - - `content: CodeExecutionToolResultBlockParamContent` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `CodeExecutionToolResultErrorParam = object { error_code, type }` - - - `error_code: CodeExecutionToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"too_many_requests"` - - - `"execution_time_exceeded"` - - - `type: "code_execution_tool_result_error"` - - - `"code_execution_tool_result_error"` - - - `CodeExecutionResultBlockParam = object { content, return_code, stderr, 2 more }` - - - `content: array of CodeExecutionOutputBlockParam` - - - `file_id: string` - - - `type: "code_execution_output"` - - - `"code_execution_output"` - - - `return_code: number` - - - `stderr: string` - - - `stdout: string` - - - `type: "code_execution_result"` - - - `"code_execution_result"` - - - `EncryptedCodeExecutionResultBlockParam = object { content, encrypted_stdout, return_code, 2 more }` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `content: array of CodeExecutionOutputBlockParam` - - - `file_id: string` - - - `type: "code_execution_output"` - - - `"code_execution_output"` - - - `encrypted_stdout: string` - - - `return_code: number` - - - `stderr: string` - - - `type: "encrypted_code_execution_result"` - - - `"encrypted_code_execution_result"` - - - `tool_use_id: string` - - - `type: "code_execution_tool_result"` - - - `"code_execution_tool_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `BashCodeExecutionToolResultBlockParam = object { content, tool_use_id, type, cache_control }` - - - `content: BashCodeExecutionToolResultErrorParam or BashCodeExecutionResultBlockParam` - - - `BashCodeExecutionToolResultErrorParam = object { error_code, type }` - - - `error_code: BashCodeExecutionToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"too_many_requests"` - - - `"execution_time_exceeded"` - - - `"output_file_too_large"` - - - `type: "bash_code_execution_tool_result_error"` - - - `"bash_code_execution_tool_result_error"` - - - `BashCodeExecutionResultBlockParam = object { content, return_code, stderr, 2 more }` - - - `content: array of BashCodeExecutionOutputBlockParam` - - - `file_id: string` - - - `type: "bash_code_execution_output"` - - - `"bash_code_execution_output"` - - - `return_code: number` - - - `stderr: string` - - - `stdout: string` - - - `type: "bash_code_execution_result"` - - - `"bash_code_execution_result"` - - - `tool_use_id: string` - - - `type: "bash_code_execution_tool_result"` - - - `"bash_code_execution_tool_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `TextEditorCodeExecutionToolResultBlockParam = object { content, tool_use_id, type, cache_control }` - - - `content: TextEditorCodeExecutionToolResultErrorParam or TextEditorCodeExecutionViewResultBlockParam or TextEditorCodeExecutionCreateResultBlockParam or TextEditorCodeExecutionStrReplaceResultBlockParam` - - - `TextEditorCodeExecutionToolResultErrorParam = object { error_code, type, error_message }` - - - `error_code: TextEditorCodeExecutionToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"too_many_requests"` - - - `"execution_time_exceeded"` - - - `"file_not_found"` - - - `type: "text_editor_code_execution_tool_result_error"` - - - `"text_editor_code_execution_tool_result_error"` - - - `error_message: optional string` - - - `TextEditorCodeExecutionViewResultBlockParam = object { content, file_type, type, 3 more }` - - - `content: string` - - - `file_type: "text" or "image" or "pdf"` - - - `"text"` - - - `"image"` - - - `"pdf"` - - - `type: "text_editor_code_execution_view_result"` - - - `"text_editor_code_execution_view_result"` - - - `num_lines: optional number` - - - `start_line: optional number` - - - `total_lines: optional number` - - - `TextEditorCodeExecutionCreateResultBlockParam = object { is_file_update, type }` - - - `is_file_update: boolean` - - - `type: "text_editor_code_execution_create_result"` - - - `"text_editor_code_execution_create_result"` - - - `TextEditorCodeExecutionStrReplaceResultBlockParam = object { type, lines, new_lines, 3 more }` - - - `type: "text_editor_code_execution_str_replace_result"` - - - `"text_editor_code_execution_str_replace_result"` - - - `lines: optional array of string` - - - `new_lines: optional number` - - - `new_start: optional number` - - - `old_lines: optional number` - - - `old_start: optional number` - - - `tool_use_id: string` - - - `type: "text_editor_code_execution_tool_result"` - - - `"text_editor_code_execution_tool_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `ToolSearchToolResultBlockParam = object { content, tool_use_id, type, cache_control }` - - - `content: ToolSearchToolResultErrorParam or ToolSearchToolSearchResultBlockParam` - - - `ToolSearchToolResultErrorParam = object { error_code, type }` - - - `error_code: ToolSearchToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"too_many_requests"` - - - `"execution_time_exceeded"` - - - `type: "tool_search_tool_result_error"` - - - `"tool_search_tool_result_error"` - - - `ToolSearchToolSearchResultBlockParam = object { tool_references, type }` - - - `tool_references: array of ToolReferenceBlockParam` - - - `tool_name: string` - - - `type: "tool_reference"` - - - `"tool_reference"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `type: "tool_search_tool_search_result"` - - - `"tool_search_tool_search_result"` - - - `tool_use_id: string` - - - `type: "tool_search_tool_result"` - - - `"tool_search_tool_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `ContainerUploadBlockParam = object { file_id, type, cache_control }` - - A content block that represents a file to be uploaded to the container - Files uploaded via this block will be available in the container's input directory. - - - `file_id: string` - - - `type: "container_upload"` - - - `"container_upload"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `role: "user" or "assistant"` - - - `"user"` - - - `"assistant"` - -- `model: Model` - - The model that will complete your prompt. - - See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-opus-4-5-20251101" or 19 more` - - The model that will complete your prompt. - - See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - - `"claude-opus-4-6"` - - Most intelligent model for building agents and coding - - - `"claude-sonnet-4-6"` - - Frontier intelligence at scale — built for coding, agents, and enterprise workflows - - - `"claude-opus-4-5-20251101"` - - Premium model combining maximum intelligence with practical performance - - - `"claude-opus-4-5"` - - Premium model combining maximum intelligence with practical performance - - - `"claude-3-7-sonnet-latest"` - - High-performance model with early extended thinking - - - `"claude-3-7-sonnet-20250219"` - - High-performance model with early extended thinking - - - `"claude-3-5-haiku-latest"` - - Fastest and most compact model for near-instant responsiveness - - - `"claude-3-5-haiku-20241022"` - - Our fastest model - - - `"claude-haiku-4-5"` - - Hybrid model, capable of near-instant responses and extended thinking - - - `"claude-haiku-4-5-20251001"` - - Hybrid model, capable of near-instant responses and extended thinking - - - `"claude-sonnet-4-20250514"` - - High-performance model with extended thinking - - - `"claude-sonnet-4-0"` - - High-performance model with extended thinking - - - `"claude-4-sonnet-20250514"` - - High-performance model with extended thinking - - - `"claude-sonnet-4-5"` - - Our best model for real-world agents and coding - - - `"claude-sonnet-4-5-20250929"` - - Our best model for real-world agents and coding - - - `"claude-opus-4-0"` - - Our most capable model - - - `"claude-opus-4-20250514"` - - Our most capable model - - - `"claude-4-opus-20250514"` - - Our most capable model - - - `"claude-opus-4-1-20250805"` - - Our most capable model - - - `"claude-3-opus-latest"` - - Excels at writing and complex tasks - - - `"claude-3-opus-20240229"` - - Excels at writing and complex tasks - - - `"claude-3-haiku-20240307"` - - Our previous most fast and cost-effective - - - `UnionMember1 = string` - -- `cache_control: optional CacheControlEphemeral` - - Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - -- `container: optional string` - - Container identifier for reuse across requests. - -- `inference_geo: optional string` - - Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used. - -- `metadata: optional Metadata` - - An object describing metadata about the request. - - - `user_id: optional string` - - An external identifier for the user who is associated with the request. - - This should be a uuid, hash value, or other opaque identifier. Anthropic may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number. - -- `output_config: optional OutputConfig` - - Configuration options for the model's output, such as the output format. - - - `effort: optional "low" or "medium" or "high" or "max"` - - All possible effort levels. - - - `"low"` - - - `"medium"` - - - `"high"` - - - `"max"` - - - `format: optional JSONOutputFormat` - - A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) - - - `schema: map[unknown]` - - The JSON schema of the format - - - `type: "json_schema"` - - - `"json_schema"` - -- `service_tier: optional "auto" or "standard_only"` - - Determines whether to use priority capacity (if available) or standard capacity for this request. - - Anthropic offers different levels of service for your API requests. See [service-tiers](https://docs.claude.com/en/api/service-tiers) for details. - - - `"auto"` - - - `"standard_only"` - -- `stop_sequences: optional array of string` - - Custom text sequences that will cause the model to stop generating. - - Our models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `"end_turn"`. - - If you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `"stop_sequence"` and the response `stop_sequence` value will contain the matched stop sequence. - -- `stream: optional boolean` - - Whether to incrementally stream the response using server-sent events. - - See [streaming](https://docs.claude.com/en/api/messages-streaming) for details. - -- `system: optional string or array of TextBlockParam` - - System prompt. - - A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts). - - - `UnionMember0 = string` - - - `UnionMember1 = array of TextBlockParam` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of TextCitationParam` - - - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - -- `temperature: optional number` - - Amount of randomness injected into the response. - - Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks. - - Note that even with `temperature` of `0.0`, the results will not be fully deterministic. - -- `thinking: optional ThinkingConfigParam` - - Configuration for enabling Claude's extended thinking. - - When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. - - See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. - - - `ThinkingConfigEnabled = object { budget_tokens, type }` - - - `budget_tokens: number` - - Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. - - Must be ≥1024 and less than `max_tokens`. - - See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. - - - `type: "enabled"` - - - `"enabled"` - - - `ThinkingConfigDisabled = object { type }` - - - `type: "disabled"` - - - `"disabled"` - - - `ThinkingConfigAdaptive = object { type }` - - - `type: "adaptive"` - - - `"adaptive"` - -- `tool_choice: optional ToolChoice` - - How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. - - - `ToolChoiceAuto = object { type, disable_parallel_tool_use }` - - The model will automatically decide whether to use tools. - - - `type: "auto"` - - - `"auto"` - - - `disable_parallel_tool_use: optional boolean` - - Whether to disable parallel tool use. - - Defaults to `false`. If set to `true`, the model will output at most one tool use. - - - `ToolChoiceAny = object { type, disable_parallel_tool_use }` - - The model will use any available tools. - - - `type: "any"` - - - `"any"` - - - `disable_parallel_tool_use: optional boolean` - - Whether to disable parallel tool use. - - Defaults to `false`. If set to `true`, the model will output exactly one tool use. - - - `ToolChoiceTool = object { name, type, disable_parallel_tool_use }` - - The model will use the specified tool with `tool_choice.name`. - - - `name: string` - - The name of the tool to use. - - - `type: "tool"` - - - `"tool"` - - - `disable_parallel_tool_use: optional boolean` - - Whether to disable parallel tool use. - - Defaults to `false`. If set to `true`, the model will output exactly one tool use. - - - `ToolChoiceNone = object { type }` - - The model will not be allowed to use tools. - - - `type: "none"` - - - `"none"` - -- `tools: optional array of ToolUnion` - - Definitions of tools that the model may use. - - If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. - - There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). - - Each tool definition includes: - - * `name`: Name of the tool. - * `description`: Optional, but strongly-recommended description of the tool. - * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. - - For example, if you defined `tools` as: - - ```json - [ - { - "name": "get_stock_price", - "description": "Get the current stock price for a given ticker symbol.", - "input_schema": { - "type": "object", - "properties": { - "ticker": { - "type": "string", - "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." - } - }, - "required": ["ticker"] - } - } - ] - ``` - - And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: - - ```json - [ - { - "type": "tool_use", - "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", - "name": "get_stock_price", - "input": { "ticker": "^GSPC" } - } - ] - ``` - - You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: - - ```json - [ - { - "type": "tool_result", - "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", - "content": "259.75 USD" - } - ] - ``` - - Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. - - See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. - - - `Tool = object { input_schema, name, allowed_callers, 7 more }` - - - `input_schema: object { type, properties, required }` - - [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. - - This defines the shape of the `input` that your tool accepts and that the model will produce. - - - `type: "object"` - - - `"object"` - - - `properties: optional map[unknown]` - - - `required: optional array of string` - - - `name: string` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `description: optional string` - - Description of what this tool does. - - Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. - - - `eager_input_streaming: optional boolean` - - Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `type: optional "custom"` - - - `"custom"` - - - `ToolBash20250124 = object { name, type, allowed_callers, 4 more }` - - - `name: "bash"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"bash"` - - - `type: "bash_20250124"` - - - `"bash_20250124"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `CodeExecutionTool20250522 = object { name, type, allowed_callers, 3 more }` - - - `name: "code_execution"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"code_execution"` - - - `type: "code_execution_20250522"` - - - `"code_execution_20250522"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `CodeExecutionTool20250825 = object { name, type, allowed_callers, 3 more }` - - - `name: "code_execution"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"code_execution"` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `CodeExecutionTool20260120 = object { name, type, allowed_callers, 3 more }` - - Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). - - - `name: "code_execution"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"code_execution"` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `MemoryTool20250818 = object { name, type, allowed_callers, 4 more }` - - - `name: "memory"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"memory"` - - - `type: "memory_20250818"` - - - `"memory_20250818"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `ToolTextEditor20250124 = object { name, type, allowed_callers, 4 more }` - - - `name: "str_replace_editor"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"str_replace_editor"` - - - `type: "text_editor_20250124"` - - - `"text_editor_20250124"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `ToolTextEditor20250429 = object { name, type, allowed_callers, 4 more }` - - - `name: "str_replace_based_edit_tool"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"str_replace_based_edit_tool"` - - - `type: "text_editor_20250429"` - - - `"text_editor_20250429"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `ToolTextEditor20250728 = object { name, type, allowed_callers, 5 more }` - - - `name: "str_replace_based_edit_tool"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"str_replace_based_edit_tool"` - - - `type: "text_editor_20250728"` - - - `"text_editor_20250728"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `input_examples: optional array of map[unknown]` - - - `max_characters: optional number` - - Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `WebSearchTool20250305 = object { name, type, allowed_callers, 7 more }` - - - `name: "web_search"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"web_search"` - - - `type: "web_search_20250305"` - - - `"web_search_20250305"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `allowed_domains: optional array of string` - - If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - - - `blocked_domains: optional array of string` - - If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `max_uses: optional number` - - Maximum number of times the tool can be used in the API request. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `user_location: optional UserLocation` - - Parameters for the user's location. Used to provide more relevant search results. - - - `type: "approximate"` - - - `"approximate"` - - - `city: optional string` - - The city of the user. - - - `country: optional string` - - The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - - - `region: optional string` - - The region of the user. - - - `timezone: optional string` - - The [IANA timezone](https://nodatime.org/TimeZones) of the user. - - - `WebFetchTool20250910 = object { name, type, allowed_callers, 8 more }` - - - `name: "web_fetch"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"web_fetch"` - - - `type: "web_fetch_20250910"` - - - `"web_fetch_20250910"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `allowed_domains: optional array of string` - - List of domains to allow fetching from - - - `blocked_domains: optional array of string` - - List of domains to block fetching from - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional CitationsConfigParam` - - Citations configuration for fetched documents. Citations are disabled by default. - - - `enabled: optional boolean` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `max_content_tokens: optional number` - - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - - - `max_uses: optional number` - - Maximum number of times the tool can be used in the API request. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `WebSearchTool20260209 = object { name, type, allowed_callers, 7 more }` - - - `name: "web_search"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"web_search"` - - - `type: "web_search_20260209"` - - - `"web_search_20260209"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `allowed_domains: optional array of string` - - If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - - - `blocked_domains: optional array of string` - - If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `max_uses: optional number` - - Maximum number of times the tool can be used in the API request. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `user_location: optional UserLocation` - - Parameters for the user's location. Used to provide more relevant search results. - - - `type: "approximate"` - - - `"approximate"` - - - `city: optional string` - - The city of the user. - - - `country: optional string` - - The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - - - `region: optional string` - - The region of the user. - - - `timezone: optional string` - - The [IANA timezone](https://nodatime.org/TimeZones) of the user. - - - `WebFetchTool20260209 = object { name, type, allowed_callers, 8 more }` - - - `name: "web_fetch"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"web_fetch"` - - - `type: "web_fetch_20260209"` - - - `"web_fetch_20260209"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `allowed_domains: optional array of string` - - List of domains to allow fetching from - - - `blocked_domains: optional array of string` - - List of domains to block fetching from - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional CitationsConfigParam` - - Citations configuration for fetched documents. Citations are disabled by default. - - - `enabled: optional boolean` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `max_content_tokens: optional number` - - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - - - `max_uses: optional number` - - Maximum number of times the tool can be used in the API request. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `ToolSearchToolBm25_20251119 = object { name, type, allowed_callers, 3 more }` - - - `name: "tool_search_tool_bm25"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"tool_search_tool_bm25"` - - - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"` - - - `"tool_search_tool_bm25_20251119"` - - - `"tool_search_tool_bm25"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `ToolSearchToolRegex20251119 = object { name, type, allowed_callers, 3 more }` - - - `name: "tool_search_tool_regex"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"tool_search_tool_regex"` - - - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"` - - - `"tool_search_tool_regex_20251119"` - - - `"tool_search_tool_regex"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - -- `top_k: optional number` - - Only sample from the top K options for each subsequent token. - - Used to remove "long tail" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277). - - Recommended for advanced use cases only. You usually only need to use `temperature`. - -- `top_p: optional number` - - Use nucleus sampling. - - In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both. - - Recommended for advanced use cases only. You usually only need to use `temperature`. - -### Returns - -- `Message = object { id, container, content, 6 more }` - - - `id: string` - - Unique object identifier. - - The format and length of IDs may change over time. - - - `container: Container` - - Information about the container used in the request (for the code execution tool) - - - `id: string` - - Identifier for the container used in this request - - - `expires_at: string` - - The time at which the container will expire. - - - `content: array of ContentBlock` - - Content generated by the model. - - This is an array of content blocks, each of which has a `type` that determines its shape. - - Example: - - ```json - [{"type": "text", "text": "Hi, I'm Claude."}] - ``` - - If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. - - For example, if the input `messages` were: - - ```json - [ - {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, - {"role": "assistant", "content": "The best answer is ("} - ] - ``` - - Then the response `content` might be: - - ```json - [{"type": "text", "text": "B)"}] - ``` - - - `TextBlock = object { citations, text, type }` - - - `citations: array of TextCitation` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `CitationCharLocation = object { cited_text, document_index, document_title, 4 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `file_id: string` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocation = object { cited_text, document_index, document_title, 4 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `file_id: string` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocation = object { cited_text, document_index, document_title, 4 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `file_id: string` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationsWebSearchResultLocation = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationsSearchResultLocation = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `ThinkingBlock = object { signature, thinking, type }` - - - `signature: string` - - - `thinking: string` - - - `type: "thinking"` - - - `"thinking"` - - - `RedactedThinkingBlock = object { data, type }` - - - `data: string` - - - `type: "redacted_thinking"` - - - `"redacted_thinking"` - - - `ToolUseBlock = object { id, caller, input, 2 more }` - - - `id: string` - - - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` - - Tool invocation directly from the model. - - - `DirectCaller = object { type }` - - Tool invocation directly from the model. - - - `type: "direct"` - - - `"direct"` - - - `ServerToolCaller = object { tool_id, type }` - - Tool invocation generated by a server-side tool. - - - `tool_id: string` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `ServerToolCaller20260120 = object { tool_id, type }` - - - `tool_id: string` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `input: map[unknown]` - - - `name: string` - - - `type: "tool_use"` - - - `"tool_use"` - - - `ServerToolUseBlock = object { id, caller, input, 2 more }` - - - `id: string` - - - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` - - Tool invocation directly from the model. - - - `DirectCaller = object { type }` - - Tool invocation directly from the model. - - - `type: "direct"` - - - `"direct"` - - - `ServerToolCaller = object { tool_id, type }` - - Tool invocation generated by a server-side tool. - - - `tool_id: string` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `ServerToolCaller20260120 = object { tool_id, type }` - - - `tool_id: string` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `input: map[unknown]` - - - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` - - - `"web_search"` - - - `"web_fetch"` - - - `"code_execution"` - - - `"bash_code_execution"` - - - `"text_editor_code_execution"` - - - `"tool_search_tool_regex"` - - - `"tool_search_tool_bm25"` - - - `type: "server_tool_use"` - - - `"server_tool_use"` - - - `WebSearchToolResultBlock = object { caller, content, tool_use_id, type }` - - - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` - - Tool invocation directly from the model. - - - `DirectCaller = object { type }` - - Tool invocation directly from the model. - - - `type: "direct"` - - - `"direct"` - - - `ServerToolCaller = object { tool_id, type }` - - Tool invocation generated by a server-side tool. - - - `tool_id: string` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `ServerToolCaller20260120 = object { tool_id, type }` - - - `tool_id: string` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `content: WebSearchToolResultBlockContent` - - - `WebSearchToolResultError = object { error_code, type }` - - - `error_code: WebSearchToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"max_uses_exceeded"` - - - `"too_many_requests"` - - - `"query_too_long"` - - - `"request_too_large"` - - - `type: "web_search_tool_result_error"` - - - `"web_search_tool_result_error"` - - - `UnionMember1 = array of WebSearchResultBlock` - - - `encrypted_content: string` - - - `page_age: string` - - - `title: string` - - - `type: "web_search_result"` - - - `"web_search_result"` - - - `url: string` - - - `tool_use_id: string` - - - `type: "web_search_tool_result"` - - - `"web_search_tool_result"` - - - `WebFetchToolResultBlock = object { caller, content, tool_use_id, type }` - - - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` - - Tool invocation directly from the model. - - - `DirectCaller = object { type }` - - Tool invocation directly from the model. - - - `type: "direct"` - - - `"direct"` - - - `ServerToolCaller = object { tool_id, type }` - - Tool invocation generated by a server-side tool. - - - `tool_id: string` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `ServerToolCaller20260120 = object { tool_id, type }` - - - `tool_id: string` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `content: WebFetchToolResultErrorBlock or WebFetchBlock` - - - `WebFetchToolResultErrorBlock = object { error_code, type }` - - - `error_code: WebFetchToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"url_too_long"` - - - `"url_not_allowed"` - - - `"url_not_accessible"` - - - `"unsupported_content_type"` - - - `"too_many_requests"` - - - `"max_uses_exceeded"` - - - `"unavailable"` - - - `type: "web_fetch_tool_result_error"` - - - `"web_fetch_tool_result_error"` - - - `WebFetchBlock = object { content, retrieved_at, type, url }` - - - `content: DocumentBlock` - - - `citations: CitationsConfig` - - Citation configuration for the document - - - `enabled: boolean` - - - `source: Base64PDFSource or PlainTextSource` - - - `Base64PDFSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "application/pdf"` - - - `"application/pdf"` - - - `type: "base64"` - - - `"base64"` - - - `PlainTextSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "text/plain"` - - - `"text/plain"` - - - `type: "text"` - - - `"text"` - - - `title: string` - - The title of the document - - - `type: "document"` - - - `"document"` - - - `retrieved_at: string` - - ISO 8601 timestamp when the content was retrieved - - - `type: "web_fetch_result"` - - - `"web_fetch_result"` - - - `url: string` - - Fetched content URL - - - `tool_use_id: string` - - - `type: "web_fetch_tool_result"` - - - `"web_fetch_tool_result"` - - - `CodeExecutionToolResultBlock = object { content, tool_use_id, type }` - - - `content: CodeExecutionToolResultBlockContent` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `CodeExecutionToolResultError = object { error_code, type }` - - - `error_code: CodeExecutionToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"too_many_requests"` - - - `"execution_time_exceeded"` - - - `type: "code_execution_tool_result_error"` - - - `"code_execution_tool_result_error"` - - - `CodeExecutionResultBlock = object { content, return_code, stderr, 2 more }` - - - `content: array of CodeExecutionOutputBlock` - - - `file_id: string` - - - `type: "code_execution_output"` - - - `"code_execution_output"` - - - `return_code: number` - - - `stderr: string` - - - `stdout: string` - - - `type: "code_execution_result"` - - - `"code_execution_result"` - - - `EncryptedCodeExecutionResultBlock = object { content, encrypted_stdout, return_code, 2 more }` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `content: array of CodeExecutionOutputBlock` - - - `file_id: string` - - - `type: "code_execution_output"` - - - `"code_execution_output"` - - - `encrypted_stdout: string` - - - `return_code: number` - - - `stderr: string` - - - `type: "encrypted_code_execution_result"` - - - `"encrypted_code_execution_result"` - - - `tool_use_id: string` - - - `type: "code_execution_tool_result"` - - - `"code_execution_tool_result"` - - - `BashCodeExecutionToolResultBlock = object { content, tool_use_id, type }` - - - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` - - - `BashCodeExecutionToolResultError = object { error_code, type }` - - - `error_code: BashCodeExecutionToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"too_many_requests"` - - - `"execution_time_exceeded"` - - - `"output_file_too_large"` - - - `type: "bash_code_execution_tool_result_error"` - - - `"bash_code_execution_tool_result_error"` - - - `BashCodeExecutionResultBlock = object { content, return_code, stderr, 2 more }` - - - `content: array of BashCodeExecutionOutputBlock` - - - `file_id: string` - - - `type: "bash_code_execution_output"` - - - `"bash_code_execution_output"` - - - `return_code: number` - - - `stderr: string` - - - `stdout: string` - - - `type: "bash_code_execution_result"` - - - `"bash_code_execution_result"` - - - `tool_use_id: string` - - - `type: "bash_code_execution_tool_result"` - - - `"bash_code_execution_tool_result"` - - - `TextEditorCodeExecutionToolResultBlock = object { content, tool_use_id, type }` - - - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` - - - `TextEditorCodeExecutionToolResultError = object { error_code, error_message, type }` - - - `error_code: TextEditorCodeExecutionToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"too_many_requests"` - - - `"execution_time_exceeded"` - - - `"file_not_found"` - - - `error_message: string` - - - `type: "text_editor_code_execution_tool_result_error"` - - - `"text_editor_code_execution_tool_result_error"` - - - `TextEditorCodeExecutionViewResultBlock = object { content, file_type, num_lines, 3 more }` - - - `content: string` - - - `file_type: "text" or "image" or "pdf"` - - - `"text"` - - - `"image"` - - - `"pdf"` - - - `num_lines: number` - - - `start_line: number` - - - `total_lines: number` - - - `type: "text_editor_code_execution_view_result"` - - - `"text_editor_code_execution_view_result"` - - - `TextEditorCodeExecutionCreateResultBlock = object { is_file_update, type }` - - - `is_file_update: boolean` - - - `type: "text_editor_code_execution_create_result"` - - - `"text_editor_code_execution_create_result"` - - - `TextEditorCodeExecutionStrReplaceResultBlock = object { lines, new_lines, new_start, 3 more }` - - - `lines: array of string` - - - `new_lines: number` - - - `new_start: number` - - - `old_lines: number` - - - `old_start: number` - - - `type: "text_editor_code_execution_str_replace_result"` - - - `"text_editor_code_execution_str_replace_result"` - - - `tool_use_id: string` - - - `type: "text_editor_code_execution_tool_result"` - - - `"text_editor_code_execution_tool_result"` - - - `ToolSearchToolResultBlock = object { content, tool_use_id, type }` - - - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` - - - `ToolSearchToolResultError = object { error_code, error_message, type }` - - - `error_code: ToolSearchToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"too_many_requests"` - - - `"execution_time_exceeded"` - - - `error_message: string` - - - `type: "tool_search_tool_result_error"` - - - `"tool_search_tool_result_error"` - - - `ToolSearchToolSearchResultBlock = object { tool_references, type }` - - - `tool_references: array of ToolReferenceBlock` - - - `tool_name: string` - - - `type: "tool_reference"` - - - `"tool_reference"` - - - `type: "tool_search_tool_search_result"` - - - `"tool_search_tool_search_result"` - - - `tool_use_id: string` - - - `type: "tool_search_tool_result"` - - - `"tool_search_tool_result"` - - - `ContainerUploadBlock = object { file_id, type }` - - Response model for a file uploaded to the container. - - - `file_id: string` - - - `type: "container_upload"` - - - `"container_upload"` - - - `model: Model` - - The model that will complete your prompt. - - See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-opus-4-5-20251101" or 19 more` - - The model that will complete your prompt. - - See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - - `"claude-opus-4-6"` - - Most intelligent model for building agents and coding - - - `"claude-sonnet-4-6"` - - Frontier intelligence at scale — built for coding, agents, and enterprise workflows - - - `"claude-opus-4-5-20251101"` - - Premium model combining maximum intelligence with practical performance - - - `"claude-opus-4-5"` - - Premium model combining maximum intelligence with practical performance - - - `"claude-3-7-sonnet-latest"` - - High-performance model with early extended thinking - - - `"claude-3-7-sonnet-20250219"` - - High-performance model with early extended thinking - - - `"claude-3-5-haiku-latest"` - - Fastest and most compact model for near-instant responsiveness - - - `"claude-3-5-haiku-20241022"` - - Our fastest model - - - `"claude-haiku-4-5"` - - Hybrid model, capable of near-instant responses and extended thinking - - - `"claude-haiku-4-5-20251001"` - - Hybrid model, capable of near-instant responses and extended thinking - - - `"claude-sonnet-4-20250514"` - - High-performance model with extended thinking - - - `"claude-sonnet-4-0"` - - High-performance model with extended thinking - - - `"claude-4-sonnet-20250514"` - - High-performance model with extended thinking - - - `"claude-sonnet-4-5"` - - Our best model for real-world agents and coding - - - `"claude-sonnet-4-5-20250929"` - - Our best model for real-world agents and coding - - - `"claude-opus-4-0"` - - Our most capable model - - - `"claude-opus-4-20250514"` - - Our most capable model - - - `"claude-4-opus-20250514"` - - Our most capable model - - - `"claude-opus-4-1-20250805"` - - Our most capable model - - - `"claude-3-opus-latest"` - - Excels at writing and complex tasks - - - `"claude-3-opus-20240229"` - - Excels at writing and complex tasks - - - `"claude-3-haiku-20240307"` - - Our previous most fast and cost-effective - - - `UnionMember1 = string` - - - `role: "assistant"` - - Conversational role of the generated message. - - This will always be `"assistant"`. - - - `"assistant"` - - - `stop_reason: StopReason` - - The reason that we stopped. - - This may be one the following values: - - * `"end_turn"`: the model reached a natural stopping point - * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum - * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated - * `"tool_use"`: the model invoked one or more tools - * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. - * `"refusal"`: when streaming classifiers intervene to handle potential policy violations - - In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. - - - `"end_turn"` - - - `"max_tokens"` - - - `"stop_sequence"` - - - `"tool_use"` - - - `"pause_turn"` - - - `"refusal"` - - - `stop_sequence: string` - - Which custom stop sequence was generated, if any. - - This value will be a non-null string if one of your custom stop sequences was generated. - - - `type: "message"` - - Object type. - - For Messages, this is always `"message"`. - - - `"message"` - - - `usage: Usage` - - Billing and rate-limit usage. - - Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. - - Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. - - For example, `output_tokens` will be non-zero, even for an empty string response from Claude. - - Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - - - `cache_creation: CacheCreation` - - Breakdown of cached tokens by TTL - - - `ephemeral_1h_input_tokens: number` - - The number of input tokens used to create the 1 hour cache entry. - - - `ephemeral_5m_input_tokens: number` - - The number of input tokens used to create the 5 minute cache entry. - - - `cache_creation_input_tokens: number` - - The number of input tokens used to create the cache entry. - - - `cache_read_input_tokens: number` - - The number of input tokens read from the cache. - - - `inference_geo: string` - - The geographic region where inference was performed for this request. - - - `input_tokens: number` - - The number of input tokens which were used. - - - `output_tokens: number` - - The number of output tokens which were used. - - - `server_tool_use: ServerToolUsage` - - The number of server tool requests. - - - `web_fetch_requests: number` - - The number of web fetch tool requests. - - - `web_search_requests: number` - - The number of web search tool requests. - - - `service_tier: "standard" or "priority" or "batch"` - - If the request used the priority, standard, or batch tier. - - - `"standard"` - - - `"priority"` - - - `"batch"` - -### Example - -```http -curl https://api.anthropic.com/v1/messages \ - -H 'Content-Type: application/json' \ - -H 'anthropic-version: 2023-06-01' \ - -H "X-Api-Key: $ANTHROPIC_API_KEY" \ - --max-time 600 \ - -d '{ - "max_tokens": 1024, - "messages": [ - { - "content": "Hello, world", - "role": "user" - } - ], - "model": "claude-opus-4-6" - }' -``` \ No newline at end of file diff --git a/docs/anthropic_api_ref_create_message_beta.md b/docs/anthropic_api_ref_create_message_beta.md deleted file mode 100644 index 15f2b89..0000000 --- a/docs/anthropic_api_ref_create_message_beta.md +++ /dev/null @@ -1,5906 +0,0 @@ -## Create - -**post** `/v1/messages` - -Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation. - -The Messages API can be used for either single queries or stateless multi-turn conversations. - -Learn more about the Messages API in our [user guide](https://docs.claude.com/en/docs/initial-setup) - -### Header Parameters - -- `"anthropic-beta": optional array of AnthropicBeta` - - Optional header to specify the beta version(s) you want to use. - - - `UnionMember0 = string` - - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 17 more` - - - `"message-batches-2024-09-24"` - - - `"prompt-caching-2024-07-31"` - - - `"computer-use-2024-10-22"` - - - `"computer-use-2025-01-24"` - - - `"pdfs-2024-09-25"` - - - `"token-counting-2024-11-01"` - - - `"token-efficient-tools-2025-02-19"` - - - `"output-128k-2025-02-19"` - - - `"files-api-2025-04-14"` - - - `"mcp-client-2025-04-04"` - - - `"mcp-client-2025-11-20"` - - - `"dev-full-thinking-2025-05-14"` - - - `"interleaved-thinking-2025-05-14"` - - - `"code-execution-2025-05-22"` - - - `"extended-cache-ttl-2025-04-11"` - - - `"context-1m-2025-08-07"` - - - `"context-management-2025-06-27"` - - - `"model-context-window-exceeded-2025-08-26"` - - - `"skills-2025-10-02"` - - - `"fast-mode-2026-02-01"` - -### Body Parameters - -- `max_tokens: number` - - The maximum number of tokens to generate before stopping. - - Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. - - Different models have different maximum values for this parameter. See [models](https://docs.claude.com/en/docs/models-overview) for details. - -- `messages: array of BetaMessageParam` - - Input messages. - - Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. - - Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. - - If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. - - Example with a single `user` message: - - ```json - [{"role": "user", "content": "Hello, Claude"}] - ``` - - Example with multiple conversational turns: - - ```json - [ - {"role": "user", "content": "Hello there."}, - {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"}, - {"role": "user", "content": "Can you explain LLMs in plain English?"}, - ] - ``` - - Example with a partially-filled response from Claude: - - ```json - [ - {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, - {"role": "assistant", "content": "The best answer is ("}, - ] - ``` - - Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: - - ```json - {"role": "user", "content": "Hello, Claude"} - ``` - - ```json - {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]} - ``` - - See [input examples](https://docs.claude.com/en/api/messages-examples). - - Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. - - There is a limit of 100,000 messages in a single request. - - - `content: string or array of BetaContentBlockParam` - - - `UnionMember0 = string` - - - `UnionMember1 = array of BetaContentBlockParam` - - - `BetaTextBlockParam = object { text, type, cache_control, citations }` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of BetaTextCitationParam` - - - `BetaCitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `BetaCitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `BetaCitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `BetaCitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `BetaCitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `BetaImageBlockParam = object { source, type, cache_control }` - - - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` - - - `BetaBase64ImageSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` - - - `"image/jpeg"` - - - `"image/png"` - - - `"image/gif"` - - - `"image/webp"` - - - `type: "base64"` - - - `"base64"` - - - `BetaURLImageSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `BetaFileImageSource = object { file_id, type }` - - - `file_id: string` - - - `type: "file"` - - - `"file"` - - - `type: "image"` - - - `"image"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `BetaRequestDocumentBlock = object { source, type, cache_control, 3 more }` - - - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more` - - - `BetaBase64PDFSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "application/pdf"` - - - `"application/pdf"` - - - `type: "base64"` - - - `"base64"` - - - `BetaPlainTextSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "text/plain"` - - - `"text/plain"` - - - `type: "text"` - - - `"text"` - - - `BetaContentBlockSource = object { content, type }` - - - `content: string or array of BetaContentBlockSourceContent` - - - `UnionMember0 = string` - - - `BetaContentBlockSourceContent = array of BetaContentBlockSourceContent` - - - `BetaTextBlockParam = object { text, type, cache_control, citations }` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of BetaTextCitationParam` - - - `BetaCitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `BetaCitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `BetaCitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `BetaCitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `BetaCitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `BetaImageBlockParam = object { source, type, cache_control }` - - - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` - - - `BetaBase64ImageSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` - - - `"image/jpeg"` - - - `"image/png"` - - - `"image/gif"` - - - `"image/webp"` - - - `type: "base64"` - - - `"base64"` - - - `BetaURLImageSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `BetaFileImageSource = object { file_id, type }` - - - `file_id: string` - - - `type: "file"` - - - `"file"` - - - `type: "image"` - - - `"image"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `type: "content"` - - - `"content"` - - - `BetaURLPDFSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `BetaFileDocumentSource = object { file_id, type }` - - - `file_id: string` - - - `type: "file"` - - - `"file"` - - - `type: "document"` - - - `"document"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional BetaCitationsConfigParam` - - - `enabled: optional boolean` - - - `context: optional string` - - - `title: optional string` - - - `BetaSearchResultBlockParam = object { content, source, title, 3 more }` - - - `content: array of BetaTextBlockParam` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of BetaTextCitationParam` - - - `BetaCitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `BetaCitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `BetaCitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `BetaCitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `BetaCitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `source: string` - - - `title: string` - - - `type: "search_result"` - - - `"search_result"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional BetaCitationsConfigParam` - - - `enabled: optional boolean` - - - `BetaThinkingBlockParam = object { signature, thinking, type }` - - - `signature: string` - - - `thinking: string` - - - `type: "thinking"` - - - `"thinking"` - - - `BetaRedactedThinkingBlockParam = object { data, type }` - - - `data: string` - - - `type: "redacted_thinking"` - - - `"redacted_thinking"` - - - `BetaToolUseBlockParam = object { id, input, name, 3 more }` - - - `id: string` - - - `input: map[unknown]` - - - `name: string` - - - `type: "tool_use"` - - - `"tool_use"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` - - Tool invocation directly from the model. - - - `BetaDirectCaller = object { type }` - - Tool invocation directly from the model. - - - `type: "direct"` - - - `"direct"` - - - `BetaServerToolCaller = object { tool_id, type }` - - Tool invocation generated by a server-side tool. - - - `tool_id: string` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `BetaServerToolCaller20260120 = object { tool_id, type }` - - - `tool_id: string` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `BetaToolResultBlockParam = object { tool_use_id, type, cache_control, 2 more }` - - - `tool_use_id: string` - - - `type: "tool_result"` - - - `"tool_result"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `content: optional string or array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more` - - - `UnionMember0 = string` - - - `UnionMember1 = array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more` - - - `BetaTextBlockParam = object { text, type, cache_control, citations }` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of BetaTextCitationParam` - - - `BetaCitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `BetaCitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `BetaCitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `BetaCitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `BetaCitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `BetaImageBlockParam = object { source, type, cache_control }` - - - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` - - - `BetaBase64ImageSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` - - - `"image/jpeg"` - - - `"image/png"` - - - `"image/gif"` - - - `"image/webp"` - - - `type: "base64"` - - - `"base64"` - - - `BetaURLImageSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `BetaFileImageSource = object { file_id, type }` - - - `file_id: string` - - - `type: "file"` - - - `"file"` - - - `type: "image"` - - - `"image"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `BetaSearchResultBlockParam = object { content, source, title, 3 more }` - - - `content: array of BetaTextBlockParam` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of BetaTextCitationParam` - - - `BetaCitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `BetaCitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `BetaCitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `BetaCitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `BetaCitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `source: string` - - - `title: string` - - - `type: "search_result"` - - - `"search_result"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional BetaCitationsConfigParam` - - - `enabled: optional boolean` - - - `BetaRequestDocumentBlock = object { source, type, cache_control, 3 more }` - - - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more` - - - `BetaBase64PDFSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "application/pdf"` - - - `"application/pdf"` - - - `type: "base64"` - - - `"base64"` - - - `BetaPlainTextSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "text/plain"` - - - `"text/plain"` - - - `type: "text"` - - - `"text"` - - - `BetaContentBlockSource = object { content, type }` - - - `content: string or array of BetaContentBlockSourceContent` - - - `UnionMember0 = string` - - - `BetaContentBlockSourceContent = array of BetaContentBlockSourceContent` - - - `BetaTextBlockParam = object { text, type, cache_control, citations }` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of BetaTextCitationParam` - - - `BetaCitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `BetaCitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `BetaCitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `BetaCitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `BetaCitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `BetaImageBlockParam = object { source, type, cache_control }` - - - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` - - - `BetaBase64ImageSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` - - - `"image/jpeg"` - - - `"image/png"` - - - `"image/gif"` - - - `"image/webp"` - - - `type: "base64"` - - - `"base64"` - - - `BetaURLImageSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `BetaFileImageSource = object { file_id, type }` - - - `file_id: string` - - - `type: "file"` - - - `"file"` - - - `type: "image"` - - - `"image"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `type: "content"` - - - `"content"` - - - `BetaURLPDFSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `BetaFileDocumentSource = object { file_id, type }` - - - `file_id: string` - - - `type: "file"` - - - `"file"` - - - `type: "document"` - - - `"document"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional BetaCitationsConfigParam` - - - `enabled: optional boolean` - - - `context: optional string` - - - `title: optional string` - - - `BetaToolReferenceBlockParam = object { tool_name, type, cache_control }` - - Tool reference block that can be included in tool_result content. - - - `tool_name: string` - - - `type: "tool_reference"` - - - `"tool_reference"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `is_error: optional boolean` - - - `BetaServerToolUseBlockParam = object { id, input, name, 3 more }` - - - `id: string` - - - `input: map[unknown]` - - - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` - - - `"web_search"` - - - `"web_fetch"` - - - `"code_execution"` - - - `"bash_code_execution"` - - - `"text_editor_code_execution"` - - - `"tool_search_tool_regex"` - - - `"tool_search_tool_bm25"` - - - `type: "server_tool_use"` - - - `"server_tool_use"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` - - Tool invocation directly from the model. - - - `BetaDirectCaller = object { type }` - - Tool invocation directly from the model. - - - `type: "direct"` - - - `"direct"` - - - `BetaServerToolCaller = object { tool_id, type }` - - Tool invocation generated by a server-side tool. - - - `tool_id: string` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `BetaServerToolCaller20260120 = object { tool_id, type }` - - - `tool_id: string` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `BetaWebSearchToolResultBlockParam = object { content, tool_use_id, type, 2 more }` - - - `content: BetaWebSearchToolResultBlockParamContent` - - - `ResultBlock = array of BetaWebSearchResultBlockParam` - - - `encrypted_content: string` - - - `title: string` - - - `type: "web_search_result"` - - - `"web_search_result"` - - - `url: string` - - - `page_age: optional string` - - - `BetaWebSearchToolRequestError = object { error_code, type }` - - - `error_code: BetaWebSearchToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"max_uses_exceeded"` - - - `"too_many_requests"` - - - `"query_too_long"` - - - `"request_too_large"` - - - `type: "web_search_tool_result_error"` - - - `"web_search_tool_result_error"` - - - `tool_use_id: string` - - - `type: "web_search_tool_result"` - - - `"web_search_tool_result"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` - - Tool invocation directly from the model. - - - `BetaDirectCaller = object { type }` - - Tool invocation directly from the model. - - - `type: "direct"` - - - `"direct"` - - - `BetaServerToolCaller = object { tool_id, type }` - - Tool invocation generated by a server-side tool. - - - `tool_id: string` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `BetaServerToolCaller20260120 = object { tool_id, type }` - - - `tool_id: string` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `BetaWebFetchToolResultBlockParam = object { content, tool_use_id, type, 2 more }` - - - `content: BetaWebFetchToolResultErrorBlockParam or BetaWebFetchBlockParam` - - - `BetaWebFetchToolResultErrorBlockParam = object { error_code, type }` - - - `error_code: BetaWebFetchToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"url_too_long"` - - - `"url_not_allowed"` - - - `"url_not_accessible"` - - - `"unsupported_content_type"` - - - `"too_many_requests"` - - - `"max_uses_exceeded"` - - - `"unavailable"` - - - `type: "web_fetch_tool_result_error"` - - - `"web_fetch_tool_result_error"` - - - `BetaWebFetchBlockParam = object { content, type, url, retrieved_at }` - - - `content: BetaRequestDocumentBlock` - - - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more` - - - `BetaBase64PDFSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "application/pdf"` - - - `"application/pdf"` - - - `type: "base64"` - - - `"base64"` - - - `BetaPlainTextSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "text/plain"` - - - `"text/plain"` - - - `type: "text"` - - - `"text"` - - - `BetaContentBlockSource = object { content, type }` - - - `content: string or array of BetaContentBlockSourceContent` - - - `UnionMember0 = string` - - - `BetaContentBlockSourceContent = array of BetaContentBlockSourceContent` - - - `BetaTextBlockParam = object { text, type, cache_control, citations }` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of BetaTextCitationParam` - - - `BetaCitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `BetaCitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `BetaCitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `BetaCitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `BetaCitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `BetaImageBlockParam = object { source, type, cache_control }` - - - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` - - - `BetaBase64ImageSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` - - - `"image/jpeg"` - - - `"image/png"` - - - `"image/gif"` - - - `"image/webp"` - - - `type: "base64"` - - - `"base64"` - - - `BetaURLImageSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `BetaFileImageSource = object { file_id, type }` - - - `file_id: string` - - - `type: "file"` - - - `"file"` - - - `type: "image"` - - - `"image"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `type: "content"` - - - `"content"` - - - `BetaURLPDFSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `BetaFileDocumentSource = object { file_id, type }` - - - `file_id: string` - - - `type: "file"` - - - `"file"` - - - `type: "document"` - - - `"document"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional BetaCitationsConfigParam` - - - `enabled: optional boolean` - - - `context: optional string` - - - `title: optional string` - - - `type: "web_fetch_result"` - - - `"web_fetch_result"` - - - `url: string` - - Fetched content URL - - - `retrieved_at: optional string` - - ISO 8601 timestamp when the content was retrieved - - - `tool_use_id: string` - - - `type: "web_fetch_tool_result"` - - - `"web_fetch_tool_result"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` - - Tool invocation directly from the model. - - - `BetaDirectCaller = object { type }` - - Tool invocation directly from the model. - - - `type: "direct"` - - - `"direct"` - - - `BetaServerToolCaller = object { tool_id, type }` - - Tool invocation generated by a server-side tool. - - - `tool_id: string` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `BetaServerToolCaller20260120 = object { tool_id, type }` - - - `tool_id: string` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `BetaCodeExecutionToolResultBlockParam = object { content, tool_use_id, type, cache_control }` - - - `content: BetaCodeExecutionToolResultBlockParamContent` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `BetaCodeExecutionToolResultErrorParam = object { error_code, type }` - - - `error_code: BetaCodeExecutionToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"too_many_requests"` - - - `"execution_time_exceeded"` - - - `type: "code_execution_tool_result_error"` - - - `"code_execution_tool_result_error"` - - - `BetaCodeExecutionResultBlockParam = object { content, return_code, stderr, 2 more }` - - - `content: array of BetaCodeExecutionOutputBlockParam` - - - `file_id: string` - - - `type: "code_execution_output"` - - - `"code_execution_output"` - - - `return_code: number` - - - `stderr: string` - - - `stdout: string` - - - `type: "code_execution_result"` - - - `"code_execution_result"` - - - `BetaEncryptedCodeExecutionResultBlockParam = object { content, encrypted_stdout, return_code, 2 more }` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `content: array of BetaCodeExecutionOutputBlockParam` - - - `file_id: string` - - - `type: "code_execution_output"` - - - `"code_execution_output"` - - - `encrypted_stdout: string` - - - `return_code: number` - - - `stderr: string` - - - `type: "encrypted_code_execution_result"` - - - `"encrypted_code_execution_result"` - - - `tool_use_id: string` - - - `type: "code_execution_tool_result"` - - - `"code_execution_tool_result"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `BetaBashCodeExecutionToolResultBlockParam = object { content, tool_use_id, type, cache_control }` - - - `content: BetaBashCodeExecutionToolResultErrorParam or BetaBashCodeExecutionResultBlockParam` - - - `BetaBashCodeExecutionToolResultErrorParam = object { error_code, type }` - - - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"too_many_requests"` - - - `"execution_time_exceeded"` - - - `"output_file_too_large"` - - - `type: "bash_code_execution_tool_result_error"` - - - `"bash_code_execution_tool_result_error"` - - - `BetaBashCodeExecutionResultBlockParam = object { content, return_code, stderr, 2 more }` - - - `content: array of BetaBashCodeExecutionOutputBlockParam` - - - `file_id: string` - - - `type: "bash_code_execution_output"` - - - `"bash_code_execution_output"` - - - `return_code: number` - - - `stderr: string` - - - `stdout: string` - - - `type: "bash_code_execution_result"` - - - `"bash_code_execution_result"` - - - `tool_use_id: string` - - - `type: "bash_code_execution_tool_result"` - - - `"bash_code_execution_tool_result"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `BetaTextEditorCodeExecutionToolResultBlockParam = object { content, tool_use_id, type, cache_control }` - - - `content: BetaTextEditorCodeExecutionToolResultErrorParam or BetaTextEditorCodeExecutionViewResultBlockParam or BetaTextEditorCodeExecutionCreateResultBlockParam or BetaTextEditorCodeExecutionStrReplaceResultBlockParam` - - - `BetaTextEditorCodeExecutionToolResultErrorParam = object { error_code, type, error_message }` - - - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"too_many_requests"` - - - `"execution_time_exceeded"` - - - `"file_not_found"` - - - `type: "text_editor_code_execution_tool_result_error"` - - - `"text_editor_code_execution_tool_result_error"` - - - `error_message: optional string` - - - `BetaTextEditorCodeExecutionViewResultBlockParam = object { content, file_type, type, 3 more }` - - - `content: string` - - - `file_type: "text" or "image" or "pdf"` - - - `"text"` - - - `"image"` - - - `"pdf"` - - - `type: "text_editor_code_execution_view_result"` - - - `"text_editor_code_execution_view_result"` - - - `num_lines: optional number` - - - `start_line: optional number` - - - `total_lines: optional number` - - - `BetaTextEditorCodeExecutionCreateResultBlockParam = object { is_file_update, type }` - - - `is_file_update: boolean` - - - `type: "text_editor_code_execution_create_result"` - - - `"text_editor_code_execution_create_result"` - - - `BetaTextEditorCodeExecutionStrReplaceResultBlockParam = object { type, lines, new_lines, 3 more }` - - - `type: "text_editor_code_execution_str_replace_result"` - - - `"text_editor_code_execution_str_replace_result"` - - - `lines: optional array of string` - - - `new_lines: optional number` - - - `new_start: optional number` - - - `old_lines: optional number` - - - `old_start: optional number` - - - `tool_use_id: string` - - - `type: "text_editor_code_execution_tool_result"` - - - `"text_editor_code_execution_tool_result"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `BetaToolSearchToolResultBlockParam = object { content, tool_use_id, type, cache_control }` - - - `content: BetaToolSearchToolResultErrorParam or BetaToolSearchToolSearchResultBlockParam` - - - `BetaToolSearchToolResultErrorParam = object { error_code, type }` - - - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"too_many_requests"` - - - `"execution_time_exceeded"` - - - `type: "tool_search_tool_result_error"` - - - `"tool_search_tool_result_error"` - - - `BetaToolSearchToolSearchResultBlockParam = object { tool_references, type }` - - - `tool_references: array of BetaToolReferenceBlockParam` - - - `tool_name: string` - - - `type: "tool_reference"` - - - `"tool_reference"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `type: "tool_search_tool_search_result"` - - - `"tool_search_tool_search_result"` - - - `tool_use_id: string` - - - `type: "tool_search_tool_result"` - - - `"tool_search_tool_result"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `BetaMCPToolUseBlockParam = object { id, input, name, 3 more }` - - - `id: string` - - - `input: map[unknown]` - - - `name: string` - - - `server_name: string` - - The name of the MCP server - - - `type: "mcp_tool_use"` - - - `"mcp_tool_use"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `BetaRequestMCPToolResultBlockParam = object { tool_use_id, type, cache_control, 2 more }` - - - `tool_use_id: string` - - - `type: "mcp_tool_result"` - - - `"mcp_tool_result"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `content: optional string or array of BetaTextBlockParam` - - - `UnionMember0 = string` - - - `BetaMCPToolResultBlockParamContent = array of BetaTextBlockParam` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of BetaTextCitationParam` - - - `BetaCitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `BetaCitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `BetaCitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `BetaCitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `BetaCitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `is_error: optional boolean` - - - `BetaContainerUploadBlockParam = object { file_id, type, cache_control }` - - A content block that represents a file to be uploaded to the container - Files uploaded via this block will be available in the container's input directory. - - - `file_id: string` - - - `type: "container_upload"` - - - `"container_upload"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `BetaCompactionBlockParam = object { content, type, cache_control }` - - A compaction block containing summary of previous context. - - Users should round-trip these blocks from responses to subsequent requests - to maintain context across compaction boundaries. - - When content is None, the block represents a failed compaction. The server - treats these as no-ops. Empty string content is not allowed. - - - `content: string` - - Summary of previously compacted content, or null if compaction failed - - - `type: "compaction"` - - - `"compaction"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `role: "user" or "assistant"` - - - `"user"` - - - `"assistant"` - -- `model: Model` - - The model that will complete your prompt. - - See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-opus-4-5-20251101" or 19 more` - - The model that will complete your prompt. - - See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - - `"claude-opus-4-6"` - - Most intelligent model for building agents and coding - - - `"claude-sonnet-4-6"` - - Frontier intelligence at scale — built for coding, agents, and enterprise workflows - - - `"claude-opus-4-5-20251101"` - - Premium model combining maximum intelligence with practical performance - - - `"claude-opus-4-5"` - - Premium model combining maximum intelligence with practical performance - - - `"claude-3-7-sonnet-latest"` - - High-performance model with early extended thinking - - - `"claude-3-7-sonnet-20250219"` - - High-performance model with early extended thinking - - - `"claude-3-5-haiku-latest"` - - Fastest and most compact model for near-instant responsiveness - - - `"claude-3-5-haiku-20241022"` - - Our fastest model - - - `"claude-haiku-4-5"` - - Hybrid model, capable of near-instant responses and extended thinking - - - `"claude-haiku-4-5-20251001"` - - Hybrid model, capable of near-instant responses and extended thinking - - - `"claude-sonnet-4-20250514"` - - High-performance model with extended thinking - - - `"claude-sonnet-4-0"` - - High-performance model with extended thinking - - - `"claude-4-sonnet-20250514"` - - High-performance model with extended thinking - - - `"claude-sonnet-4-5"` - - Our best model for real-world agents and coding - - - `"claude-sonnet-4-5-20250929"` - - Our best model for real-world agents and coding - - - `"claude-opus-4-0"` - - Our most capable model - - - `"claude-opus-4-20250514"` - - Our most capable model - - - `"claude-4-opus-20250514"` - - Our most capable model - - - `"claude-opus-4-1-20250805"` - - Our most capable model - - - `"claude-3-opus-latest"` - - Excels at writing and complex tasks - - - `"claude-3-opus-20240229"` - - Excels at writing and complex tasks - - - `"claude-3-haiku-20240307"` - - Our previous most fast and cost-effective - - - `UnionMember1 = string` - -- `cache_control: optional BetaCacheControlEphemeral` - - Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - -- `container: optional BetaContainerParams or string` - - Container identifier for reuse across requests. - - - `BetaContainerParams = object { id, skills }` - - Container parameters with skills to be loaded. - - - `id: optional string` - - Container id - - - `skills: optional array of BetaSkillParams` - - List of skills to load in the container - - - `skill_id: string` - - Skill ID - - - `type: "anthropic" or "custom"` - - Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) - - - `"anthropic"` - - - `"custom"` - - - `version: optional string` - - Skill version or 'latest' for most recent version - - - `UnionMember1 = string` - -- `context_management: optional BetaContextManagementConfig` - - Context management configuration. - - This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not. - - - `edits: optional array of BetaClearToolUses20250919Edit or BetaClearThinking20251015Edit or BetaCompact20260112Edit` - - List of context management edits to apply - - - `BetaClearToolUses20250919Edit = object { type, clear_at_least, clear_tool_inputs, 3 more }` - - - `type: "clear_tool_uses_20250919"` - - - `"clear_tool_uses_20250919"` - - - `clear_at_least: optional BetaInputTokensClearAtLeast` - - Minimum number of tokens that must be cleared when triggered. Context will only be modified if at least this many tokens can be removed. - - - `type: "input_tokens"` - - - `"input_tokens"` - - - `value: number` - - - `clear_tool_inputs: optional boolean or array of string` - - Whether to clear all tool inputs (bool) or specific tool inputs to clear (list) - - - `UnionMember0 = boolean` - - - `UnionMember1 = array of string` - - - `exclude_tools: optional array of string` - - Tool names whose uses are preserved from clearing - - - `keep: optional BetaToolUsesKeep` - - Number of tool uses to retain in the conversation - - - `type: "tool_uses"` - - - `"tool_uses"` - - - `value: number` - - - `trigger: optional BetaInputTokensTrigger or BetaToolUsesTrigger` - - Condition that triggers the context management strategy - - - `BetaInputTokensTrigger = object { type, value }` - - - `type: "input_tokens"` - - - `"input_tokens"` - - - `value: number` - - - `BetaToolUsesTrigger = object { type, value }` - - - `type: "tool_uses"` - - - `"tool_uses"` - - - `value: number` - - - `BetaClearThinking20251015Edit = object { type, keep }` - - - `type: "clear_thinking_20251015"` - - - `"clear_thinking_20251015"` - - - `keep: optional BetaThinkingTurns or BetaAllThinkingTurns or "all"` - - Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed. - - - `BetaThinkingTurns = object { type, value }` - - - `type: "thinking_turns"` - - - `"thinking_turns"` - - - `value: number` - - - `BetaAllThinkingTurns = object { type }` - - - `type: "all"` - - - `"all"` - - - `UnionMember2 = "all"` - - - `"all"` - - - `BetaCompact20260112Edit = object { type, instructions, pause_after_compaction, trigger }` - - Automatically compact older context when reaching the configured trigger threshold. - - - `type: "compact_20260112"` - - - `"compact_20260112"` - - - `instructions: optional string` - - Additional instructions for summarization. - - - `pause_after_compaction: optional boolean` - - Whether to pause after compaction and return the compaction block to the user. - - - `trigger: optional BetaInputTokensTrigger` - - When to trigger compaction. Defaults to 150000 input tokens. - - - `type: "input_tokens"` - - - `"input_tokens"` - - - `value: number` - -- `inference_geo: optional string` - - Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used. - -- `mcp_servers: optional array of BetaRequestMCPServerURLDefinition` - - MCP servers to be utilized in this request - - - `name: string` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `authorization_token: optional string` - - - `tool_configuration: optional BetaRequestMCPServerToolConfiguration` - - - `allowed_tools: optional array of string` - - - `enabled: optional boolean` - -- `metadata: optional BetaMetadata` - - An object describing metadata about the request. - - - `user_id: optional string` - - An external identifier for the user who is associated with the request. - - This should be a uuid, hash value, or other opaque identifier. Anthropic may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number. - -- `output_config: optional BetaOutputConfig` - - Configuration options for the model's output, such as the output format. - - - `effort: optional "low" or "medium" or "high" or "max"` - - All possible effort levels. - - - `"low"` - - - `"medium"` - - - `"high"` - - - `"max"` - - - `format: optional BetaJSONOutputFormat` - - A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) - - - `schema: map[unknown]` - - The JSON schema of the format - - - `type: "json_schema"` - - - `"json_schema"` - -- `output_format: optional BetaJSONOutputFormat` - - Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) - - A schema to specify Claude's output format in responses. This parameter will be removed in a future release. - - - `schema: map[unknown]` - - The JSON schema of the format - - - `type: "json_schema"` - - - `"json_schema"` - -- `service_tier: optional "auto" or "standard_only"` - - Determines whether to use priority capacity (if available) or standard capacity for this request. - - Anthropic offers different levels of service for your API requests. See [service-tiers](https://docs.claude.com/en/api/service-tiers) for details. - - - `"auto"` - - - `"standard_only"` - -- `speed: optional "standard" or "fast"` - - The inference speed mode for this request. `"fast"` enables high output-tokens-per-second inference. - - - `"standard"` - - - `"fast"` - -- `stop_sequences: optional array of string` - - Custom text sequences that will cause the model to stop generating. - - Our models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `"end_turn"`. - - If you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `"stop_sequence"` and the response `stop_sequence` value will contain the matched stop sequence. - -- `stream: optional boolean` - - Whether to incrementally stream the response using server-sent events. - - See [streaming](https://docs.claude.com/en/api/messages-streaming) for details. - -- `system: optional string or array of BetaTextBlockParam` - - System prompt. - - A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts). - - - `UnionMember0 = string` - - - `UnionMember1 = array of BetaTextBlockParam` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of BetaTextCitationParam` - - - `BetaCitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `BetaCitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `BetaCitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `BetaCitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `BetaCitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - -- `temperature: optional number` - - Amount of randomness injected into the response. - - Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks. - - Note that even with `temperature` of `0.0`, the results will not be fully deterministic. - -- `thinking: optional BetaThinkingConfigParam` - - Configuration for enabling Claude's extended thinking. - - When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. - - See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. - - - `BetaThinkingConfigEnabled = object { budget_tokens, type }` - - - `budget_tokens: number` - - Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. - - Must be ≥1024 and less than `max_tokens`. - - See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. - - - `type: "enabled"` - - - `"enabled"` - - - `BetaThinkingConfigDisabled = object { type }` - - - `type: "disabled"` - - - `"disabled"` - - - `BetaThinkingConfigAdaptive = object { type }` - - - `type: "adaptive"` - - - `"adaptive"` - -- `tool_choice: optional BetaToolChoice` - - How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. - - - `BetaToolChoiceAuto = object { type, disable_parallel_tool_use }` - - The model will automatically decide whether to use tools. - - - `type: "auto"` - - - `"auto"` - - - `disable_parallel_tool_use: optional boolean` - - Whether to disable parallel tool use. - - Defaults to `false`. If set to `true`, the model will output at most one tool use. - - - `BetaToolChoiceAny = object { type, disable_parallel_tool_use }` - - The model will use any available tools. - - - `type: "any"` - - - `"any"` - - - `disable_parallel_tool_use: optional boolean` - - Whether to disable parallel tool use. - - Defaults to `false`. If set to `true`, the model will output exactly one tool use. - - - `BetaToolChoiceTool = object { name, type, disable_parallel_tool_use }` - - The model will use the specified tool with `tool_choice.name`. - - - `name: string` - - The name of the tool to use. - - - `type: "tool"` - - - `"tool"` - - - `disable_parallel_tool_use: optional boolean` - - Whether to disable parallel tool use. - - Defaults to `false`. If set to `true`, the model will output exactly one tool use. - - - `BetaToolChoiceNone = object { type }` - - The model will not be allowed to use tools. - - - `type: "none"` - - - `"none"` - -- `tools: optional array of BetaToolUnion` - - Definitions of tools that the model may use. - - If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. - - There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). - - Each tool definition includes: - - * `name`: Name of the tool. - * `description`: Optional, but strongly-recommended description of the tool. - * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. - - For example, if you defined `tools` as: - - ```json - [ - { - "name": "get_stock_price", - "description": "Get the current stock price for a given ticker symbol.", - "input_schema": { - "type": "object", - "properties": { - "ticker": { - "type": "string", - "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." - } - }, - "required": ["ticker"] - } - } - ] - ``` - - And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: - - ```json - [ - { - "type": "tool_use", - "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", - "name": "get_stock_price", - "input": { "ticker": "^GSPC" } - } - ] - ``` - - You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: - - ```json - [ - { - "type": "tool_result", - "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", - "content": "259.75 USD" - } - ] - ``` - - Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. - - See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. - - - `BetaTool = object { input_schema, name, allowed_callers, 7 more }` - - - `input_schema: object { type, properties, required }` - - [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. - - This defines the shape of the `input` that your tool accepts and that the model will produce. - - - `type: "object"` - - - `"object"` - - - `properties: optional map[unknown]` - - - `required: optional array of string` - - - `name: string` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `description: optional string` - - Description of what this tool does. - - Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. - - - `eager_input_streaming: optional boolean` - - Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `type: optional "custom"` - - - `"custom"` - - - `BetaToolBash20241022 = object { name, type, allowed_callers, 4 more }` - - - `name: "bash"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"bash"` - - - `type: "bash_20241022"` - - - `"bash_20241022"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `BetaToolBash20250124 = object { name, type, allowed_callers, 4 more }` - - - `name: "bash"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"bash"` - - - `type: "bash_20250124"` - - - `"bash_20250124"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `BetaCodeExecutionTool20250522 = object { name, type, allowed_callers, 3 more }` - - - `name: "code_execution"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"code_execution"` - - - `type: "code_execution_20250522"` - - - `"code_execution_20250522"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `BetaCodeExecutionTool20250825 = object { name, type, allowed_callers, 3 more }` - - - `name: "code_execution"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"code_execution"` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `BetaCodeExecutionTool20260120 = object { name, type, allowed_callers, 3 more }` - - Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). - - - `name: "code_execution"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"code_execution"` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `BetaToolComputerUse20241022 = object { display_height_px, display_width_px, name, 7 more }` - - - `display_height_px: number` - - The height of the display in pixels. - - - `display_width_px: number` - - The width of the display in pixels. - - - `name: "computer"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"computer"` - - - `type: "computer_20241022"` - - - `"computer_20241022"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `display_number: optional number` - - The X11 display number (e.g. 0, 1) for the display. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `BetaMemoryTool20250818 = object { name, type, allowed_callers, 4 more }` - - - `name: "memory"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"memory"` - - - `type: "memory_20250818"` - - - `"memory_20250818"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `BetaToolComputerUse20250124 = object { display_height_px, display_width_px, name, 7 more }` - - - `display_height_px: number` - - The height of the display in pixels. - - - `display_width_px: number` - - The width of the display in pixels. - - - `name: "computer"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"computer"` - - - `type: "computer_20250124"` - - - `"computer_20250124"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `display_number: optional number` - - The X11 display number (e.g. 0, 1) for the display. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `BetaToolTextEditor20241022 = object { name, type, allowed_callers, 4 more }` - - - `name: "str_replace_editor"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"str_replace_editor"` - - - `type: "text_editor_20241022"` - - - `"text_editor_20241022"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `BetaToolComputerUse20251124 = object { display_height_px, display_width_px, name, 8 more }` - - - `display_height_px: number` - - The height of the display in pixels. - - - `display_width_px: number` - - The width of the display in pixels. - - - `name: "computer"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"computer"` - - - `type: "computer_20251124"` - - - `"computer_20251124"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `display_number: optional number` - - The X11 display number (e.g. 0, 1) for the display. - - - `enable_zoom: optional boolean` - - Whether to enable an action to take a zoomed-in screenshot of the screen. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `BetaToolTextEditor20250124 = object { name, type, allowed_callers, 4 more }` - - - `name: "str_replace_editor"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"str_replace_editor"` - - - `type: "text_editor_20250124"` - - - `"text_editor_20250124"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `BetaToolTextEditor20250429 = object { name, type, allowed_callers, 4 more }` - - - `name: "str_replace_based_edit_tool"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"str_replace_based_edit_tool"` - - - `type: "text_editor_20250429"` - - - `"text_editor_20250429"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `BetaToolTextEditor20250728 = object { name, type, allowed_callers, 5 more }` - - - `name: "str_replace_based_edit_tool"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"str_replace_based_edit_tool"` - - - `type: "text_editor_20250728"` - - - `"text_editor_20250728"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `input_examples: optional array of map[unknown]` - - - `max_characters: optional number` - - Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `BetaWebSearchTool20250305 = object { name, type, allowed_callers, 7 more }` - - - `name: "web_search"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"web_search"` - - - `type: "web_search_20250305"` - - - `"web_search_20250305"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `allowed_domains: optional array of string` - - If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - - - `blocked_domains: optional array of string` - - If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `max_uses: optional number` - - Maximum number of times the tool can be used in the API request. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `user_location: optional BetaUserLocation` - - Parameters for the user's location. Used to provide more relevant search results. - - - `type: "approximate"` - - - `"approximate"` - - - `city: optional string` - - The city of the user. - - - `country: optional string` - - The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - - - `region: optional string` - - The region of the user. - - - `timezone: optional string` - - The [IANA timezone](https://nodatime.org/TimeZones) of the user. - - - `BetaWebFetchTool20250910 = object { name, type, allowed_callers, 8 more }` - - - `name: "web_fetch"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"web_fetch"` - - - `type: "web_fetch_20250910"` - - - `"web_fetch_20250910"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `allowed_domains: optional array of string` - - List of domains to allow fetching from - - - `blocked_domains: optional array of string` - - List of domains to block fetching from - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional BetaCitationsConfigParam` - - Citations configuration for fetched documents. Citations are disabled by default. - - - `enabled: optional boolean` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `max_content_tokens: optional number` - - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - - - `max_uses: optional number` - - Maximum number of times the tool can be used in the API request. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `BetaWebSearchTool20260209 = object { name, type, allowed_callers, 7 more }` - - - `name: "web_search"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"web_search"` - - - `type: "web_search_20260209"` - - - `"web_search_20260209"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `allowed_domains: optional array of string` - - If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - - - `blocked_domains: optional array of string` - - If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `max_uses: optional number` - - Maximum number of times the tool can be used in the API request. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `user_location: optional BetaUserLocation` - - Parameters for the user's location. Used to provide more relevant search results. - - - `type: "approximate"` - - - `"approximate"` - - - `city: optional string` - - The city of the user. - - - `country: optional string` - - The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - - - `region: optional string` - - The region of the user. - - - `timezone: optional string` - - The [IANA timezone](https://nodatime.org/TimeZones) of the user. - - - `BetaWebFetchTool20260209 = object { name, type, allowed_callers, 8 more }` - - - `name: "web_fetch"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"web_fetch"` - - - `type: "web_fetch_20260209"` - - - `"web_fetch_20260209"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `allowed_domains: optional array of string` - - List of domains to allow fetching from - - - `blocked_domains: optional array of string` - - List of domains to block fetching from - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional BetaCitationsConfigParam` - - Citations configuration for fetched documents. Citations are disabled by default. - - - `enabled: optional boolean` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `max_content_tokens: optional number` - - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - - - `max_uses: optional number` - - Maximum number of times the tool can be used in the API request. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `BetaToolSearchToolBm25_20251119 = object { name, type, allowed_callers, 3 more }` - - - `name: "tool_search_tool_bm25"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"tool_search_tool_bm25"` - - - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"` - - - `"tool_search_tool_bm25_20251119"` - - - `"tool_search_tool_bm25"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `BetaToolSearchToolRegex20251119 = object { name, type, allowed_callers, 3 more }` - - - `name: "tool_search_tool_regex"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"tool_search_tool_regex"` - - - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"` - - - `"tool_search_tool_regex_20251119"` - - - `"tool_search_tool_regex"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `BetaMCPToolset = object { mcp_server_name, type, cache_control, 2 more }` - - Configuration for a group of tools from an MCP server. - - Allows configuring enabled status and defer_loading for all tools - from an MCP server, with optional per-tool overrides. - - - `mcp_server_name: string` - - Name of the MCP server to configure tools for - - - `type: "mcp_toolset"` - - - `"mcp_toolset"` - - - `cache_control: optional BetaCacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `configs: optional map[BetaMCPToolConfig]` - - Configuration overrides for specific tools, keyed by tool name - - - `defer_loading: optional boolean` - - - `enabled: optional boolean` - - - `default_config: optional BetaMCPToolDefaultConfig` - - Default configuration applied to all tools from this server - - - `defer_loading: optional boolean` - - - `enabled: optional boolean` - -- `top_k: optional number` - - Only sample from the top K options for each subsequent token. - - Used to remove "long tail" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277). - - Recommended for advanced use cases only. You usually only need to use `temperature`. - -- `top_p: optional number` - - Use nucleus sampling. - - In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both. - - Recommended for advanced use cases only. You usually only need to use `temperature`. - -### Returns - -- `BetaMessage = object { id, container, content, 7 more }` - - - `id: string` - - Unique object identifier. - - The format and length of IDs may change over time. - - - `container: BetaContainer` - - Information about the container used in the request (for the code execution tool) - - - `id: string` - - Identifier for the container used in this request - - - `expires_at: string` - - The time at which the container will expire. - - - `skills: array of BetaSkill` - - Skills loaded in the container - - - `skill_id: string` - - Skill ID - - - `type: "anthropic" or "custom"` - - Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) - - - `"anthropic"` - - - `"custom"` - - - `version: string` - - Skill version or 'latest' for most recent version - - - `content: array of BetaContentBlock` - - Content generated by the model. - - This is an array of content blocks, each of which has a `type` that determines its shape. - - Example: - - ```json - [{"type": "text", "text": "Hi, I'm Claude."}] - ``` - - If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. - - For example, if the input `messages` were: - - ```json - [ - {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, - {"role": "assistant", "content": "The best answer is ("} - ] - ``` - - Then the response `content` might be: - - ```json - [{"type": "text", "text": "B)"}] - ``` - - - `BetaTextBlock = object { citations, text, type }` - - - `citations: array of BetaTextCitation` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `BetaCitationCharLocation = object { cited_text, document_index, document_title, 4 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `file_id: string` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `BetaCitationPageLocation = object { cited_text, document_index, document_title, 4 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `file_id: string` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `BetaCitationContentBlockLocation = object { cited_text, document_index, document_title, 4 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `file_id: string` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `BetaCitationsWebSearchResultLocation = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `BetaCitationSearchResultLocation = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `BetaThinkingBlock = object { signature, thinking, type }` - - - `signature: string` - - - `thinking: string` - - - `type: "thinking"` - - - `"thinking"` - - - `BetaRedactedThinkingBlock = object { data, type }` - - - `data: string` - - - `type: "redacted_thinking"` - - - `"redacted_thinking"` - - - `BetaToolUseBlock = object { id, input, name, 2 more }` - - - `id: string` - - - `input: map[unknown]` - - - `name: string` - - - `type: "tool_use"` - - - `"tool_use"` - - - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` - - Tool invocation directly from the model. - - - `BetaDirectCaller = object { type }` - - Tool invocation directly from the model. - - - `type: "direct"` - - - `"direct"` - - - `BetaServerToolCaller = object { tool_id, type }` - - Tool invocation generated by a server-side tool. - - - `tool_id: string` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `BetaServerToolCaller20260120 = object { tool_id, type }` - - - `tool_id: string` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `BetaServerToolUseBlock = object { id, input, name, 2 more }` - - - `id: string` - - - `input: map[unknown]` - - - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` - - - `"web_search"` - - - `"web_fetch"` - - - `"code_execution"` - - - `"bash_code_execution"` - - - `"text_editor_code_execution"` - - - `"tool_search_tool_regex"` - - - `"tool_search_tool_bm25"` - - - `type: "server_tool_use"` - - - `"server_tool_use"` - - - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` - - Tool invocation directly from the model. - - - `BetaDirectCaller = object { type }` - - Tool invocation directly from the model. - - - `type: "direct"` - - - `"direct"` - - - `BetaServerToolCaller = object { tool_id, type }` - - Tool invocation generated by a server-side tool. - - - `tool_id: string` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `BetaServerToolCaller20260120 = object { tool_id, type }` - - - `tool_id: string` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `BetaWebSearchToolResultBlock = object { content, tool_use_id, type, caller }` - - - `content: BetaWebSearchToolResultBlockContent` - - - `BetaWebSearchToolResultError = object { error_code, type }` - - - `error_code: BetaWebSearchToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"max_uses_exceeded"` - - - `"too_many_requests"` - - - `"query_too_long"` - - - `"request_too_large"` - - - `type: "web_search_tool_result_error"` - - - `"web_search_tool_result_error"` - - - `UnionMember1 = array of BetaWebSearchResultBlock` - - - `encrypted_content: string` - - - `page_age: string` - - - `title: string` - - - `type: "web_search_result"` - - - `"web_search_result"` - - - `url: string` - - - `tool_use_id: string` - - - `type: "web_search_tool_result"` - - - `"web_search_tool_result"` - - - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` - - Tool invocation directly from the model. - - - `BetaDirectCaller = object { type }` - - Tool invocation directly from the model. - - - `type: "direct"` - - - `"direct"` - - - `BetaServerToolCaller = object { tool_id, type }` - - Tool invocation generated by a server-side tool. - - - `tool_id: string` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `BetaServerToolCaller20260120 = object { tool_id, type }` - - - `tool_id: string` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `BetaWebFetchToolResultBlock = object { content, tool_use_id, type, caller }` - - - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` - - - `BetaWebFetchToolResultErrorBlock = object { error_code, type }` - - - `error_code: BetaWebFetchToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"url_too_long"` - - - `"url_not_allowed"` - - - `"url_not_accessible"` - - - `"unsupported_content_type"` - - - `"too_many_requests"` - - - `"max_uses_exceeded"` - - - `"unavailable"` - - - `type: "web_fetch_tool_result_error"` - - - `"web_fetch_tool_result_error"` - - - `BetaWebFetchBlock = object { content, retrieved_at, type, url }` - - - `content: BetaDocumentBlock` - - - `citations: BetaCitationConfig` - - Citation configuration for the document - - - `enabled: boolean` - - - `source: BetaBase64PDFSource or BetaPlainTextSource` - - - `BetaBase64PDFSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "application/pdf"` - - - `"application/pdf"` - - - `type: "base64"` - - - `"base64"` - - - `BetaPlainTextSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "text/plain"` - - - `"text/plain"` - - - `type: "text"` - - - `"text"` - - - `title: string` - - The title of the document - - - `type: "document"` - - - `"document"` - - - `retrieved_at: string` - - ISO 8601 timestamp when the content was retrieved - - - `type: "web_fetch_result"` - - - `"web_fetch_result"` - - - `url: string` - - Fetched content URL - - - `tool_use_id: string` - - - `type: "web_fetch_tool_result"` - - - `"web_fetch_tool_result"` - - - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` - - Tool invocation directly from the model. - - - `BetaDirectCaller = object { type }` - - Tool invocation directly from the model. - - - `type: "direct"` - - - `"direct"` - - - `BetaServerToolCaller = object { tool_id, type }` - - Tool invocation generated by a server-side tool. - - - `tool_id: string` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `BetaServerToolCaller20260120 = object { tool_id, type }` - - - `tool_id: string` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `BetaCodeExecutionToolResultBlock = object { content, tool_use_id, type }` - - - `content: BetaCodeExecutionToolResultBlockContent` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `BetaCodeExecutionToolResultError = object { error_code, type }` - - - `error_code: BetaCodeExecutionToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"too_many_requests"` - - - `"execution_time_exceeded"` - - - `type: "code_execution_tool_result_error"` - - - `"code_execution_tool_result_error"` - - - `BetaCodeExecutionResultBlock = object { content, return_code, stderr, 2 more }` - - - `content: array of BetaCodeExecutionOutputBlock` - - - `file_id: string` - - - `type: "code_execution_output"` - - - `"code_execution_output"` - - - `return_code: number` - - - `stderr: string` - - - `stdout: string` - - - `type: "code_execution_result"` - - - `"code_execution_result"` - - - `BetaEncryptedCodeExecutionResultBlock = object { content, encrypted_stdout, return_code, 2 more }` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `content: array of BetaCodeExecutionOutputBlock` - - - `file_id: string` - - - `type: "code_execution_output"` - - - `"code_execution_output"` - - - `encrypted_stdout: string` - - - `return_code: number` - - - `stderr: string` - - - `type: "encrypted_code_execution_result"` - - - `"encrypted_code_execution_result"` - - - `tool_use_id: string` - - - `type: "code_execution_tool_result"` - - - `"code_execution_tool_result"` - - - `BetaBashCodeExecutionToolResultBlock = object { content, tool_use_id, type }` - - - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` - - - `BetaBashCodeExecutionToolResultError = object { error_code, type }` - - - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"too_many_requests"` - - - `"execution_time_exceeded"` - - - `"output_file_too_large"` - - - `type: "bash_code_execution_tool_result_error"` - - - `"bash_code_execution_tool_result_error"` - - - `BetaBashCodeExecutionResultBlock = object { content, return_code, stderr, 2 more }` - - - `content: array of BetaBashCodeExecutionOutputBlock` - - - `file_id: string` - - - `type: "bash_code_execution_output"` - - - `"bash_code_execution_output"` - - - `return_code: number` - - - `stderr: string` - - - `stdout: string` - - - `type: "bash_code_execution_result"` - - - `"bash_code_execution_result"` - - - `tool_use_id: string` - - - `type: "bash_code_execution_tool_result"` - - - `"bash_code_execution_tool_result"` - - - `BetaTextEditorCodeExecutionToolResultBlock = object { content, tool_use_id, type }` - - - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` - - - `BetaTextEditorCodeExecutionToolResultError = object { error_code, error_message, type }` - - - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"too_many_requests"` - - - `"execution_time_exceeded"` - - - `"file_not_found"` - - - `error_message: string` - - - `type: "text_editor_code_execution_tool_result_error"` - - - `"text_editor_code_execution_tool_result_error"` - - - `BetaTextEditorCodeExecutionViewResultBlock = object { content, file_type, num_lines, 3 more }` - - - `content: string` - - - `file_type: "text" or "image" or "pdf"` - - - `"text"` - - - `"image"` - - - `"pdf"` - - - `num_lines: number` - - - `start_line: number` - - - `total_lines: number` - - - `type: "text_editor_code_execution_view_result"` - - - `"text_editor_code_execution_view_result"` - - - `BetaTextEditorCodeExecutionCreateResultBlock = object { is_file_update, type }` - - - `is_file_update: boolean` - - - `type: "text_editor_code_execution_create_result"` - - - `"text_editor_code_execution_create_result"` - - - `BetaTextEditorCodeExecutionStrReplaceResultBlock = object { lines, new_lines, new_start, 3 more }` - - - `lines: array of string` - - - `new_lines: number` - - - `new_start: number` - - - `old_lines: number` - - - `old_start: number` - - - `type: "text_editor_code_execution_str_replace_result"` - - - `"text_editor_code_execution_str_replace_result"` - - - `tool_use_id: string` - - - `type: "text_editor_code_execution_tool_result"` - - - `"text_editor_code_execution_tool_result"` - - - `BetaToolSearchToolResultBlock = object { content, tool_use_id, type }` - - - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` - - - `BetaToolSearchToolResultError = object { error_code, error_message, type }` - - - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"too_many_requests"` - - - `"execution_time_exceeded"` - - - `error_message: string` - - - `type: "tool_search_tool_result_error"` - - - `"tool_search_tool_result_error"` - - - `BetaToolSearchToolSearchResultBlock = object { tool_references, type }` - - - `tool_references: array of BetaToolReferenceBlock` - - - `tool_name: string` - - - `type: "tool_reference"` - - - `"tool_reference"` - - - `type: "tool_search_tool_search_result"` - - - `"tool_search_tool_search_result"` - - - `tool_use_id: string` - - - `type: "tool_search_tool_result"` - - - `"tool_search_tool_result"` - - - `BetaMCPToolUseBlock = object { id, input, name, 2 more }` - - - `id: string` - - - `input: map[unknown]` - - - `name: string` - - The name of the MCP tool - - - `server_name: string` - - The name of the MCP server - - - `type: "mcp_tool_use"` - - - `"mcp_tool_use"` - - - `BetaMCPToolResultBlock = object { content, is_error, tool_use_id, type }` - - - `content: string or array of BetaTextBlock` - - - `UnionMember0 = string` - - - `BetaMCPToolResultBlockContent = array of BetaTextBlock` - - - `citations: array of BetaTextCitation` - - Citations supporting the text block. - - The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - - `BetaCitationCharLocation = object { cited_text, document_index, document_title, 4 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `file_id: string` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `BetaCitationPageLocation = object { cited_text, document_index, document_title, 4 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `file_id: string` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `BetaCitationContentBlockLocation = object { cited_text, document_index, document_title, 4 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `file_id: string` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `BetaCitationsWebSearchResultLocation = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `BetaCitationSearchResultLocation = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `is_error: boolean` - - - `tool_use_id: string` - - - `type: "mcp_tool_result"` - - - `"mcp_tool_result"` - - - `BetaContainerUploadBlock = object { file_id, type }` - - Response model for a file uploaded to the container. - - - `file_id: string` - - - `type: "container_upload"` - - - `"container_upload"` - - - `BetaCompactionBlock = object { content, type }` - - A compaction block returned when autocompact is triggered. - - When content is None, it indicates the compaction failed to produce a valid - summary (e.g., malformed output from the model). Clients may round-trip - compaction blocks with null content; the server treats them as no-ops. - - - `content: string` - - Summary of compacted content, or null if compaction failed - - - `type: "compaction"` - - - `"compaction"` - - - `context_management: BetaContextManagementResponse` - - Context management response. - - Information about context management strategies applied during the request. - - - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` - - List of context management edits that were applied. - - - `BetaClearToolUses20250919EditResponse = object { cleared_input_tokens, cleared_tool_uses, type }` - - - `cleared_input_tokens: number` - - Number of input tokens cleared by this edit. - - - `cleared_tool_uses: number` - - Number of tool uses that were cleared. - - - `type: "clear_tool_uses_20250919"` - - The type of context management edit applied. - - - `"clear_tool_uses_20250919"` - - - `BetaClearThinking20251015EditResponse = object { cleared_input_tokens, cleared_thinking_turns, type }` - - - `cleared_input_tokens: number` - - Number of input tokens cleared by this edit. - - - `cleared_thinking_turns: number` - - Number of thinking turns that were cleared. - - - `type: "clear_thinking_20251015"` - - The type of context management edit applied. - - - `"clear_thinking_20251015"` - - - `model: Model` - - The model that will complete your prompt. - - See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - - `UnionMember0 = "claude-opus-4-6" or "claude-sonnet-4-6" or "claude-opus-4-5-20251101" or 19 more` - - The model that will complete your prompt. - - See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - - `"claude-opus-4-6"` - - Most intelligent model for building agents and coding - - - `"claude-sonnet-4-6"` - - Frontier intelligence at scale — built for coding, agents, and enterprise workflows - - - `"claude-opus-4-5-20251101"` - - Premium model combining maximum intelligence with practical performance - - - `"claude-opus-4-5"` - - Premium model combining maximum intelligence with practical performance - - - `"claude-3-7-sonnet-latest"` - - High-performance model with early extended thinking - - - `"claude-3-7-sonnet-20250219"` - - High-performance model with early extended thinking - - - `"claude-3-5-haiku-latest"` - - Fastest and most compact model for near-instant responsiveness - - - `"claude-3-5-haiku-20241022"` - - Our fastest model - - - `"claude-haiku-4-5"` - - Hybrid model, capable of near-instant responses and extended thinking - - - `"claude-haiku-4-5-20251001"` - - Hybrid model, capable of near-instant responses and extended thinking - - - `"claude-sonnet-4-20250514"` - - High-performance model with extended thinking - - - `"claude-sonnet-4-0"` - - High-performance model with extended thinking - - - `"claude-4-sonnet-20250514"` - - High-performance model with extended thinking - - - `"claude-sonnet-4-5"` - - Our best model for real-world agents and coding - - - `"claude-sonnet-4-5-20250929"` - - Our best model for real-world agents and coding - - - `"claude-opus-4-0"` - - Our most capable model - - - `"claude-opus-4-20250514"` - - Our most capable model - - - `"claude-4-opus-20250514"` - - Our most capable model - - - `"claude-opus-4-1-20250805"` - - Our most capable model - - - `"claude-3-opus-latest"` - - Excels at writing and complex tasks - - - `"claude-3-opus-20240229"` - - Excels at writing and complex tasks - - - `"claude-3-haiku-20240307"` - - Our previous most fast and cost-effective - - - `UnionMember1 = string` - - - `role: "assistant"` - - Conversational role of the generated message. - - This will always be `"assistant"`. - - - `"assistant"` - - - `stop_reason: BetaStopReason` - - The reason that we stopped. - - This may be one the following values: - - * `"end_turn"`: the model reached a natural stopping point - * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum - * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated - * `"tool_use"`: the model invoked one or more tools - * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. - * `"refusal"`: when streaming classifiers intervene to handle potential policy violations - - In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. - - - `"end_turn"` - - - `"max_tokens"` - - - `"stop_sequence"` - - - `"tool_use"` - - - `"pause_turn"` - - - `"compaction"` - - - `"refusal"` - - - `"model_context_window_exceeded"` - - - `stop_sequence: string` - - Which custom stop sequence was generated, if any. - - This value will be a non-null string if one of your custom stop sequences was generated. - - - `type: "message"` - - Object type. - - For Messages, this is always `"message"`. - - - `"message"` - - - `usage: BetaUsage` - - Billing and rate-limit usage. - - Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. - - Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. - - For example, `output_tokens` will be non-zero, even for an empty string response from Claude. - - Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - - - `cache_creation: BetaCacheCreation` - - Breakdown of cached tokens by TTL - - - `ephemeral_1h_input_tokens: number` - - The number of input tokens used to create the 1 hour cache entry. - - - `ephemeral_5m_input_tokens: number` - - The number of input tokens used to create the 5 minute cache entry. - - - `cache_creation_input_tokens: number` - - The number of input tokens used to create the cache entry. - - - `cache_read_input_tokens: number` - - The number of input tokens read from the cache. - - - `inference_geo: string` - - The geographic region where inference was performed for this request. - - - `input_tokens: number` - - The number of input tokens which were used. - - - `iterations: BetaIterationsUsage` - - Per-iteration token usage breakdown. - - Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - - - Determine which iterations exceeded long context thresholds (>=200k tokens) - - Calculate the true context window size from the last iteration - - Understand token accumulation across server-side tool use loops - - - `BetaMessageIterationUsage = object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` - - Token usage for a sampling iteration. - - - `cache_creation: BetaCacheCreation` - - Breakdown of cached tokens by TTL - - - `ephemeral_1h_input_tokens: number` - - The number of input tokens used to create the 1 hour cache entry. - - - `ephemeral_5m_input_tokens: number` - - The number of input tokens used to create the 5 minute cache entry. - - - `cache_creation_input_tokens: number` - - The number of input tokens used to create the cache entry. - - - `cache_read_input_tokens: number` - - The number of input tokens read from the cache. - - - `input_tokens: number` - - The number of input tokens which were used. - - - `output_tokens: number` - - The number of output tokens which were used. - - - `type: "message"` - - Usage for a sampling iteration - - - `"message"` - - - `BetaCompactionIterationUsage = object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }` - - Token usage for a compaction iteration. - - - `cache_creation: BetaCacheCreation` - - Breakdown of cached tokens by TTL - - - `ephemeral_1h_input_tokens: number` - - The number of input tokens used to create the 1 hour cache entry. - - - `ephemeral_5m_input_tokens: number` - - The number of input tokens used to create the 5 minute cache entry. - - - `cache_creation_input_tokens: number` - - The number of input tokens used to create the cache entry. - - - `cache_read_input_tokens: number` - - The number of input tokens read from the cache. - - - `input_tokens: number` - - The number of input tokens which were used. - - - `output_tokens: number` - - The number of output tokens which were used. - - - `type: "compaction"` - - Usage for a compaction iteration - - - `"compaction"` - - - `output_tokens: number` - - The number of output tokens which were used. - - - `server_tool_use: BetaServerToolUsage` - - The number of server tool requests. - - - `web_fetch_requests: number` - - The number of web fetch tool requests. - - - `web_search_requests: number` - - The number of web search tool requests. - - - `service_tier: "standard" or "priority" or "batch"` - - If the request used the priority, standard, or batch tier. - - - `"standard"` - - - `"priority"` - - - `"batch"` - - - `speed: "standard" or "fast"` - - The inference speed mode used for this request. - - - `"standard"` - - - `"fast"` - -### Example - -```http -curl https://api.anthropic.com/v1/messages?beta=true \ - -H 'Content-Type: application/json' \ - -H 'anthropic-version: 2023-06-01' \ - -H "X-Api-Key: $ANTHROPIC_API_KEY" \ - --max-time 600 \ - -d '{ - "max_tokens": 1024, - "messages": [ - { - "content": "Hello, world", - "role": "user" - } - ], - "model": "claude-opus-4-6" - }' -``` \ No newline at end of file diff --git a/docs/anthropic_prompt_caching.md b/docs/anthropic_prompt_caching.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/guide_architecture.md b/docs/guide_architecture.md new file mode 100644 index 0000000..a7d334b --- /dev/null +++ b/docs/guide_architecture.md @@ -0,0 +1,85 @@ +# Guide: Architecture + +Overview of the package design, state management, and code-path layout. + +--- + +The purpose of this software is to alleviate the pain points of using AI as a local co-pilot by encapsulating the workflow into a resilient, strictly controlled state machine. It manages context generation, API throttling, human-in-the-loop tool execution, and session-long logging. + +There are two primary state boundaries used: + +* The GUI State (Main Thread, Retained-Mode via Dear PyGui) +* The AI State (Daemon Thread, stateless execution loop) + +All synchronization between these boundaries is managed via lock-protected queues and events. + +## Code Paths + +### Lifetime & Application Boot + +The application lifetime is localized within App.run in gui.py. + +1. __init__ parses the global config.toml (which sets the active provider, theme, and project paths). +2. It immediately hands off to project_manager.py to deserialize the active .toml which hydrates the session's files, discussion histories, and prompts. +3. Dear PyGui's dpg contexts are bootstrapped with docking_viewport=True, allowing individual GUI panels to exist as native OS windows. +4. The main thread enters a blocking while dpg.is_dearpygui_running() render loop. +5. On shutdown (clean exit), it performs a dual-flush: _flush_to_project() commits the UI state back to the .toml, and _flush_to_config() commits the global state to config.toml. The viewport layout is automatically serialized to dpg_layout.ini. + +### Context Shaping & Aggregation + +Before making a call to an AI Provider, the current state of the workspace is resolved into a dense Markdown representation. +This occurs inside ggregate.run. + +If using the default workflow, ggregate.py hashes through the following process: +1. **Glob Resolution:** Iterates through config["files"]["paths"] and unpacks any wildcards (e.g., src/**/*.rs) against the designated ase_dir. +2. **Summarization Pass:** Instead of concatenating raw file bodies (which would quickly overwhelm the ~200k token limit over multiple rounds), the files are passed to summarize.py. +3. **AST Parsing:** summarize.py runs a heuristic pass. For Python files, it uses the standard st module to read structural nodes (Classes, Methods, Imports, Constants). It outputs a compact Markdown table. +4. **Markdown Generation:** The final _00N.md string is constructed, comprising the truncated AST summaries, the user's current project system prompt, and the active discussion branch. +5. The Markdown file is persisted to disk (./md_gen/ by default) for auditing. + +### AI Communication & The Tool Loop + +The communication model is unified under i_client.py, which normalizes the Gemini and Anthropic SDKs into a singular interface send(md_content, user_message, base_dir, file_items). + +The loop is defined as follows: + +1. **Prompt Injection:** The aggregated Markdown context and system prompt are injected. (Gemini injects this directly into system_instruction at chat instantiation to prevent history bloat; Anthropic chunks this into cache_control: ephemeral blocks). +2. **Execution Loop:** A MAX_TOOL_ROUNDS (default 10) bounded loop begins. +3. The AI provider is polled. +4. If the provider's stop_reason is ool_use: + 1. The loop parses the requested tool (either a read-only MCP tool or the destructive PowerShell tool). + 2. If PowerShell, it dispatches a blocking event to the Main Thread (see *On Tool Execution & Concurrency*). + 3. Once the result is retrieved, the loop executes a **Dynamic Refresh** (_reread_file_items). Any files currently tracked by the project are pulled from the disk fresh. + 4. The tool result, appended with the fresh [FILES UPDATED] block, is sent back to the provider. +5. Once the model outputs standard text, the loop terminates and yields the string back to the GUI callback. + +### On Tool Execution & Concurrency + +When the AI calls a safe MCP tool (like +ead_file or search_files), the daemon thread immediately executes it via mcp_client.py and returns the result. + +However, when the AI requests +un_powershell, the operation halts: + +1. The Daemon Thread instantiates a ConfirmDialog object containing the payload and calls .wait(). This blocks the thread on a hreading.Event(). +2. The ConfirmDialog instance is safely placed in a _pending_dialog_lock. +3. The Main Thread, during its next frame cycle, pops the dialog from the lock and renders an OS-level modal window using dpg.window(modal=True). +4. The user can inspect the script, modify it in the text box, or reject it entirely. +5. Upon the user clicking "Approve & Run", the main thread triggers the hreading.Event, unblocking the Daemon Thread. +6. The Daemon Thread passes the script to shell_runner.py, captures stdout, stderr, and exit_code, logs it to session_logger.py, and returns it to the LLM. + +### On Context History Pruning (Anthropic) + +Because the Anthropic API requires sending the entire conversation history on every request, long sessions will inevitably hit the invalid_request_error: prompt is too long. + +To solve this, i_client.py implements an aggressive pruning algorithm: +1. _strip_stale_file_refreshes: It recursively sweeps backward through the history dict and strips out large [FILES UPDATED] data blocks from old turns, preserving only the most recent snapshot. +2. _trim_anthropic_history: If the estimated token count still exceeds _ANTHROPIC_MAX_PROMPT_TOKENS (~180,000), it slices off the oldest user/assistant message pairs from the beginning of the history array. +3. The loop guarantees that at least the System prompt, Tool Definitions, and the final user prompt are preserved. + +### Session Persistence + +All I/O bound session data is recorded sequentially. session_logger.py hooks into the execution loops and records: +- logs/comms_.log: A JSON-L structured timeline of every raw payload sent/received. +- logs/toolcalls_.log: A sequential markdown record detailing every AI tool invocation and its exact stdout result. +- scripts/generated/: Every .ps1 script approved and executed by the shell runner is physically written to disk for version control transparency. diff --git a/docs/guide_tools.md b/docs/guide_tools.md new file mode 100644 index 0000000..81d66a0 --- /dev/null +++ b/docs/guide_tools.md @@ -0,0 +1,48 @@ +# Guide: Tooling + +Overview of the tool dispatch and execution model. + +--- + +The agent is provided two classes of tools: Read-Only MCP Tools, and a Destructive Execution Loop. + +## 1. Read-Only Context (MCP Tools) + +Implemented in mcp_client.py. These tools allow the AI to selectively expand its knowledge of the codebase without requiring the user to dump entire 10,000-line files into the static context prefix. + +### Security & Scope +Every filesystem MCP tool passes its arguments through _resolve_and_check. This function ensures that the requested path falls under one of the allowed directories defined in the GUI's Base Dir configurations. +If the AI attempts to read or search a path outside the project bounds, the tool safely catches the constraint violation and returns ACCESS DENIED. + +### Supplied Tools: +* +ead_file(path): Returns the raw UTF-8 text of a file. +* list_directory(path): Returns a formatted table of a directory's contents, showing file vs dir and byte sizes. +* search_files(path, pattern): Executes an absolute glob search (e.g., **/*.py) to find specific files. +* get_file_summary(path): Invokes the local summarize.py heuristic parser to get the AST structure of a file without reading the whole body. +* web_search(query): Queries DuckDuckGo's raw HTML endpoint and returns the top 5 results (Titles, URLs, Snippets) using a native HTMLParser to avoid heavy dependencies. +* etch_url(url): Downloads a target webpage and strips out all scripts, styling, and structural HTML, returning only the raw prose content (clamped to 40,000 characters). + +## 2. Destructive Execution ( +un_powershell) + +The core manipulation mechanism. This is a single, heavily guarded tool. + +### Flow +1. The AI generates a +un_powershell payload containing a PowerShell script. +2. The AI background thread calls confirm_and_run_callback (injected by gui.py). +3. The background thread blocks completely, creating a modal popup on the main GUI thread. +4. The user reads the script and chooses to Approve or Reject. +5. If Approved, shell_runner.py executes the script using -NoProfile -NonInteractive -Command within the specified ase_dir. +6. The combined stdout, stderr, and EXIT CODE are captured and returned to the AI in the tool result block. + +### AI Guidelines +The core system prompt explicitly guides the AI on how to use this tool safely: +* Prefer targeted replacements (using PowerShell's .Replace()) over full rewrites where possible. +* If a file is large and complex (requiring specific escape characters), do not attempt an inline python -c script. Instead, use a PowerShell here-string (@'...'@) to write a temporary python helper script to disk, execute the python script, and then delete it. + +### Synthetic Context Refresh +Immediately after **any** tool call turn finishes, i_client runs _reread_file_items. It fetches the latest disk state of all files in the current project context and appends them as a synthetic [FILES UPDATED] message to the tool result. +This means if the AI writes to a file, it instantly "sees" the modification in its next turn without having to waste a cycle calling +ead_file. diff --git a/gui.py b/gui.py index 243cab0..322e145 100644 --- a/gui.py +++ b/gui.py @@ -1,4 +1,14 @@ -# gui.py +# gui.py +""" +Note(Gemini): +The main DearPyGui interface orchestrator. +This is not a simple UI wrapper; it's a complex state machine that: +1. Handles multi-viewport docking (allowing panels to act as OS windows). +2. Manages background daemon threads for AI requests so the UI doesn't block. +3. Implements lock-protected comms queues for safe main-thread rendering. +4. Pauses AI execution to prompt the human for destructive PowerShell script approval. +""" +# gui.py import dearpygui.dearpygui as dpg import tomllib import tomli_w diff --git a/manual_slop.toml b/manual_slop.toml index c01f30d..1fb4416 100644 --- a/manual_slop.toml +++ b/manual_slop.toml @@ -23,9 +23,15 @@ paths = [ "C:/projects/manual_slop/file_cache.py", "C:/projects/manual_slop/theme.py", "C:/projects/manual_slop/project_manager.py", - "C:/projects/manual_slop/manual_slop.toml", "C:/projects/manual_slop/mcp_client.py", "C:/projects/manual_slop/summarize.py", + "C:/projects/VEFontCache-Odin/docs/guide_architecture.md", + "C:/projects/VEFontCache-Odin/docs/guide_backend.md", + "C:/projects/VEFontCache-Odin/docs/Readme.md", + "C:/projects/VEFontCache-Odin/scripts/Readme.md", + "C:/projects/VEFontCache-Odin/Readme.md", + "C:\\projects\\VEFontCache-Odin\\vefontcache\\**\\*", + "C:\\projects\\manual_slop\\docs\\**\\*", ] [screenshots] @@ -39,7 +45,7 @@ roles = [ "Vendor API", "System", ] -active = "Support multi-viewporting" +active = "docs writeup" auto_add = true [discussion.discussions.main] @@ -134,7 +140,7 @@ history = [ [discussion.discussions."Support multi-viewporting"] git_commit = "" -last_updated = "2026-02-22T01:42:32" +last_updated = "2026-02-22T08:53:04" history = [ "@2026-02-22T01:13:53\nUser:\nLets port this program to use https://github.com/pthom/hello_imgui or another imgui package (WEb search if you have to) that will allow us to do Multi-Viewporting (independent OS windows).\nSo far all my attempts to get dearpygui working with native os window multi-viewporting have failed. Which c++ imgui supports. I think there might be a python package that supports this.\n\nWorst case I might have to use a different language that has a dear imgui package with multi-viewporting support that may make ai codegen performance far worse.", "@2026-02-22T01:15:32\nAI:\nAlright, I've done extensive research on this. Here's my assessment:\n\n## The Multi-Viewport Situation in Python\n\n### The Problem with DearPyGui\nDearPyGui wraps Dear ImGui but **does not expose the multi-viewport feature** (dragging imgui windows out as independent OS windows). It has its own docking implementation but the C++ multi-viewport backend plumbing was never wired through to Python. You've already discovered this the hard way.\n\n### The Best Option: `imgui-bundle` (pip: `imgui-bundle`)\n\n**This is the package you want.** It's by Pascal Thomet (pthom) and wraps:\n- **Dear ImGui** (docking branch — which includes multi-viewport support)\n- **Hello ImGui** (application framework on top of Dear ImGui)\n- 20+ additional libraries (plots, markdown, node editors, etc.)\n\nKey facts:\n- `pip install imgui-bundle` — binary wheels for Windows/macOS/Linux\n- It tracks Dear ImGui's **docking branch** closely, which is the branch that contains `ImGuiConfigFlags_ViewportsEnable`\n- Full Python bindings with type hints\n- The API uses `imgui.config_flags` to set `ImGuiConfigFlags_ViewportsEnable`, then Dear ImGui handles creating/managing OS windows automatically when you drag an imgui window outside the main viewport\n- Has its own layout/docking system via Hello ImGui's dock spaces\n\n### What the Port Involves\n\nThis is a **massive** rewrite. The entire `gui.py` (2094 lines) and `theme.py` (415 lines) are completely DearPyGui-specific. Every single widget call, every tag system, every callback pattern is different. Here's the mapping:\n\n| DearPyGui | imgui-bundle |\n|---|---|\n| `dpg.add_text(...)` | `imgui.text(...)` |\n| `dpg.add_input_text(tag=..., ...)` | State variable + `imgui.input_text(...)` |\n| `dpg.add_button(label=..., callback=...)` | `if imgui.button(\"label\"): do_thing()` |\n| Tag-based widget identity | Immediate mode — no tags, state lives in your code |\n| `dpg.does_item_exist(tag)` | Not needed — immediate mode |\n| `dpg.configure_item(tag, ...)` | Just change the variable and it renders next frame |\n| `dpg.create_viewport()` + render loop | `hello_imgui.run(gui_func, params)` |\n| `dpg.enable_docking()` | `runner_params.imgui_window_params.enable_viewports = True` |\n| Theme via `dpg.add_theme_color()` | `imgui.push_style_color()` / `imgui.get_style()` |\n\nThe immediate-mode paradigm is actually **simpler** conceptually — no tags, no \"does item exist\" checks, no callback registration. But it means a full rewrite of all rendering code.\n\n### My Recommendation\n\n**Do the port to `imgui-bundle`.** Here's why:\n1. It definitively supports multi-viewporting (the whole point)\n2. The immediate-mode API is actually cleaner and more maintainable\n3. Better AI codegen compatibility (pthom specifically calls this out — readable code)\n4. You stay in Python — no language switch needed\n5. Active maintenance tracking upstream Dear ImGui\n\n### How I'd Structure the Port\n\n1. **Phase 1**: Install `imgui-bundle`, create a minimal proof-of-concept with multi-viewporting enabled (verify it works on your machine)\n2. **Phase 2**: Port `theme.py` → new imgui-bundle theming\n3. **Phase 3**: Port `gui.py` — the big one. Rewrite all panels as immediate-mode rendering functions\n4. **Phase 4**: Wire up the threading/callbacks (confirmation dialogs, background sends, etc.)\n\n**Want me to start with Phase 1 — a minimal proof-of-concept** that creates a window with viewports enabled, a couple of dockable panels, and verifies you can drag a panel out as an independent OS window? That way we confirm the foundation works before committing to the full rewrite.\n\nOr if you want me to just go all-in and start the full port, I can do that too. Your call.", @@ -142,6 +148,20 @@ history = [ "@2026-02-22T01:22:47\nAI:\nOK, this is a massive port. Let me first read the existing `theme.py` and `MainContext.md`, then I'll build both `theme_2.py` and `gui_2.py` as complete files.\nThis is a massive port. Let me start by understanding the full picture, then I'll write both `theme_2.py` and `gui_2.py` as complete files. First let me install `imgui-bundle` and verify it works, then write the files.\nLet me first check if imgui-bundle is installed:\nGood, `imgui-bundle` is installed and working with ImGui 1.92.5 (docking branch). Now let me build the two files. This is a massive port so I'll write them as Python helper scripts to disk.\nLet me start with `theme_2.py` since it's simpler and `gui_2.py` depends on it:\nGood, `theme_2.py` is written. Now I need to write the massive `gui_2.py`. This is the big one — a complete port from DearPyGui's retained-mode tag-based system to imgui-bundle's immediate-mode paradigm. I'll write it as a Python helper script since it's too large and complex for a PowerShell here-string.\nLet me write the helper script that creates `gui_2.py`:", "@2026-02-22T01:24:13\nUser:\nI had to swtich providers midway, were not on gemini 3.1 pro preview. Hi gemini!\n\nContinue where claude left off. we still need to do gui_2.py. It attempted theme_2.py.\nSee if you can finish this port!", "@2026-02-22T01:31:13\nAI:\nI encountered an error when attempting to write the file automatically: your system returned `ERROR: powershell executable not found`. It seems `powershell.exe` is missing from your PATH or you are using `pwsh`.\n\nBecause my only execution tool relies on PowerShell, I cannot write the file to your disk directly. Please save the following code manually as `gui_2.py` in your project folder. \n\nThis is the massive port completing the transition to `imgui-bundle`. It maps all of the DearPyGui logic (windows, callbacks, lists, dialogs, theming) into an immediate-mode ImGui rendering loop using `hello_imgui` and `immapp`.\n\n```python\n# gui_2.py\n[Omitted you can read it if you want yourself]\n```\n\nIf you rename `gui.py` and `theme.py`, you can test it by running `python gui_2.py`. Then you should be fully multi-viewport capable, allowing panels to dissolve into separate OS windows perfectly!", - "@2026-02-22T01:40:27\nUser:\nI saved the gui_2.py but we have the following error:\nPS C:\\projects\\manual_slop> uv run .\\gui_2.py\nInstalled 2 packages in 306ms\nTraceback (most recent call last):\n File \"C:\\projects\\manual_slop\\gui_2.py\", line 15, in \n import theme_2 as theme\n File \"C:\\projects\\manual_slop\\theme_2.py\", line 75, in \n imgui.Col_.nav_highlight: _c(126, 78, 14),\n ^^^^^^^^^^^^^^^^^^^^^^^^\n File \"C:\\Users\\Ed\\scoop\\apps\\python\\current\\Lib\\enum.py\", line 784, in __getattr__\n raise AttributeError(name) from None\nAttributeError: nav_highlight\n\nseems to be related to theme_2.py...\n\n", + "@2026-02-22T01:40:27\nUser:\nI saved the gui_2.py but we have the following error:\nPS C:\\projects\\manual_slop> uv run .\\gui_2.py\nInstalled 2 packages in 306ms\nTraceback (most recent call last):\n File \"C:\\projects\\manual_slop\\gui_2.py\", line 15, in \n import theme_2 as theme\n File \"C:\\projects\\manual_slop\\theme_2.py\", line 75, in \n imgui.Col_.nav_highlight: _c(126, 78, 14),\n ^^^^^^^^^^^^^^^^^^^^^^^^\n File \"C:\\Users\\Ed\\scoop\\apps\\python\\current\\Lib\\enum.py\", line 784, in __getattr__\n raise AttributeError(name) from None\nAttributeError: nav_highlight\n\nseems to be related to theme_2.py...", "@2026-02-22T01:41:47\nVendor API:\n[GEMINI QUOTA EXHAUSTED]\n\n429 RESOURCE_EXHAUSTED. {'error': {'code': 429, 'message': 'You exceeded your current quota, please check your plan and billing details. For more information on this error, head to: https://ai.google.dev/gemini-api/docs/rate-limits. To monitor your current usage, head to: https://ai.dev/rate-limit. \\n* Quota exceeded for metric: generativelanguage.googleapis.com/generate_content_paid_tier_input_token_count, limit: 1000000, model: gemini-3.1-pro\\nPlease retry in 10.735846057s.', 'status': 'RESOURCE_EXHAUSTED', 'details': [{'@type': 'type.googleapis.com/google.rpc.Help', 'links': [{'description': 'Learn more about Gemini API quotas', 'url': 'https://ai.google.dev/gemini-api/docs/rate-limits'}]}, {'@type': 'type.googleapis.com/google.rpc.QuotaFailure', 'violations': [{'quotaMetric': 'generativelanguage.googleapis.com/generate_content_paid_tier_input_token_count', 'quotaId': 'GenerateContentPaidTierInputTokensPerModelPerMinute', 'quotaDimensions': {'location': 'global', 'model': 'gemini-3.1-pro'}, 'quotaValue': '1000000'}]}, {'@type': 'type.googleapis.com/google.rpc.RetryInfo', 'retryDelay': '10s'}]}}", ] + +[discussion.discussions."docs writeup"] +git_commit = "" +last_updated = "2026-02-22T09:17:49" +history = [ + "@2026-02-22T08:56:39\nUser:\nLets write extensive documentation in the same style that I used for my VEFontCache-Oodin project.\nI added it's directories to your context.", + "@2026-02-22T08:56:58\nAI:\n(No text returned)", + "@2026-02-22T08:57:15\nUser:\ncontinue.", + "@2026-02-22T09:00:54\nAI:\nI will generate the documentation files following the same structure and tone you used for the `VEFontCache-Odin` project. I'll create a `docs` directory and populate it with the architecture guide, tooling guide, and interface readme, along with a primary `Readme.md` at the root of the project.\n\n\n\nI have generated the extensive documentation matching the `VEFontCache-Odin` style and structure.\n\nI have created a new `docs/` directory with the following content:\n* `docs/Readme.md`: The main interface and usage guide, explaining how to utilize the UI, discussions, and file contexts.\n* `docs/guide_architecture.md`: An in-depth breakdown of the codebase's main paths including `Lifetime`, `Context Aggregation`, `AI Communication`, and `Tool Dispatch`.\n* `docs/guide_tools.md`: Documentation detailing the internal toolset split between safe, read-only MCP file operations and the destructive `run_powershell` loop.\n\nI also created a primary `Readme.md` in the root of the project to serve as the landing page (detailing features and how to run it). Finally, I appended this addition to the bottom of the `MainContext.md` to ensure your AI memory state remains up-to-date.", + "@2026-02-22T09:02:18\nUser:\nnice make them more extensive/in-depth right now the architecture guide is rather small and brief compared to whats actually going on with everything, especially the gui...", + "@2026-02-22T09:04:02\nAI:\nI have completely rewritten the documentation to be much more extensive and in-depth.\n\nHere are the major changes:\n\n1. **`docs/guide_architecture.md`** was massively expanded to detail the actual internals of the Python application:\n * **The GUI Architecture:** Explains the multi-viewport Dear PyGui setup, the exact mechanism of the threading model (daemon background threads vs the main render loop), how Comms queues are lock-protected and flushed per frame, and how the rich renderer dynamically handles large text blocks with the Text Viewer popup.\n * **Context Aggregation:** Breaks down `summarize.py`'s heuristics (AST parsing for Python, regex for TOML/Markdown).\n * **AI Communication:** Details the difference between Gemini and Anthropic handling. It explains Gemini's `system_instruction` injection and Anthropic's complex history trimming (`_trim_anthropic_history`, ephemeral prompt caching, and `_strip_stale_file_refreshes`).\n * **Session Persistence:** Explains the timestamp-based rotation logic in `session_logger.py` and what exactly is logged (JSON-L comms log, `.ps1` code outputs, and markdown tool logs).\n\n2. **`docs/Readme.md` (Interface Guide)**:\n * Expanded the panel descriptions to explain *why* and *how* to use them (e.g., how the Word-Wrap toggle dynamically shifts GUI elements, how \"Update Commit\" snapshots discussion states, how the \"MD Only\" acts as a dry-run to save API costs).\n\n3. **`docs/guide_tools.md`**:\n * Detailed the security mechanics of the read-only MCP tools (`_is_allowed` check against base directories and active files).\n * Detailed the native HTML parsing mechanisms used for the web tools.\n * Broke down the exact execution flow of the destructive `run_powershell` tool, including how the GUI intercepts it, blocks the AI execution loop, forces human confirmation via modal, and returns the combined stdout/stderr/exit code.\n\nI also updated `MainContext.md` to note these new exhaustive documentation files so the AI retains knowledge of them for future sessions. Let me know if you want to dig deeper into any specific section!", + "@2026-02-22T09:11:01\nUser:\nThe docs aren't detailed enough, the code isn't commented like the vefontcache code is. etc. My docs were straight to the point, in-depth, old school provides extensive insight into what was done.", + "@2026-02-22T09:17:39\nVendor API:\n[GEMINI QUOTA EXHAUSTED]\n\n429 RESOURCE_EXHAUSTED. {'error': {'code': 429, 'message': 'You exceeded your current quota, please check your plan and billing details. For more information on this error, head to: https://ai.google.dev/gemini-api/docs/rate-limits. To monitor your current usage, head to: https://ai.dev/rate-limit. \\n* Quota exceeded for metric: generativelanguage.googleapis.com/generate_content_paid_tier_input_token_count, limit: 1000000, model: gemini-3.1-pro\\nPlease retry in 20.333361679s.', 'status': 'RESOURCE_EXHAUSTED', 'details': [{'@type': 'type.googleapis.com/google.rpc.Help', 'links': [{'description': 'Learn more about Gemini API quotas', 'url': 'https://ai.google.dev/gemini-api/docs/rate-limits'}]}, {'@type': 'type.googleapis.com/google.rpc.QuotaFailure', 'violations': [{'quotaMetric': 'generativelanguage.googleapis.com/generate_content_paid_tier_input_token_count', 'quotaId': 'GenerateContentPaidTierInputTokensPerModelPerMinute', 'quotaDimensions': {'location': 'global', 'model': 'gemini-3.1-pro'}, 'quotaValue': '1000000'}]}, {'@type': 'type.googleapis.com/google.rpc.RetryInfo', 'retryDelay': '20s'}]}}", +] diff --git a/mcp_client.py b/mcp_client.py index 5f9146a..66b4b03 100644 --- a/mcp_client.py +++ b/mcp_client.py @@ -1,3 +1,17 @@ +# mcp_client.py +""" +Note(Gemini): +MCP-style file context tools for manual_slop. +Exposes read-only filesystem tools the AI can call to selectively fetch file +content on demand, instead of having everything inlined into the context block. + +All access is restricted to paths that are either: + - Explicitly listed in the project's allowed_paths set, OR + - Contained within an allowed base_dir (must resolve to a subpath of it) + +This is heavily inspired by Claude's own tooling limits. We enforce safety here +so the AI doesn't wander outside the project workspace. +""" # mcp_client.py #MCP-style file context tools for manual_slop. diff --git a/project_manager.py b/project_manager.py index deb6c59..3e46f60 100644 --- a/project_manager.py +++ b/project_manager.py @@ -1,4 +1,10 @@ # project_manager.py +""" +Note(Gemini): +Handles loading/saving of project .toml configurations. +Also handles serializing the discussion history into the TOML format using a special +@timestamp prefix to preserve the exact sequence of events. +""" import subprocess import datetime import tomllib diff --git a/read_main_ctx.py b/read_main_ctx.py deleted file mode 100644 index 19186fa..0000000 --- a/read_main_ctx.py +++ /dev/null @@ -1,8 +0,0 @@ -import re - -with open("MainContext.md", "r", encoding="utf-8") as f: - text = f.read() - -# I don't know the exact structure of MainContext.md right now but I will just append a new section or update it. -# Actually I don't have MainContext.md loaded in context but the prompt told me to update it every time. -# Let's read MainContext.md first. diff --git a/session_logger.py b/session_logger.py index 58bab8d..c2e9616 100644 --- a/session_logger.py +++ b/session_logger.py @@ -1,4 +1,15 @@ -# session_logger.py +# session_logger.py +""" +Note(Gemini): +Opens timestamped log/script files at startup and keeps them open for the +lifetime of the process. + +File layout: +logs/comms_.log - every comms entry (direction/kind/payload) as JSON-L +logs/toolcalls_.log - sequential record of every tool invocation +scripts/generated/_.ps1 - each PowerShell script the AI generated +""" +# session_logger.py """ Opens timestamped log/script files at startup and keeps them open for the lifetime of the process. The next run of the GUI creates new files; the diff --git a/summarize.py b/summarize.py index f0fbdb5..bb63316 100644 --- a/summarize.py +++ b/summarize.py @@ -1,4 +1,15 @@ -# summarize.py +# summarize.py +""" +Note(Gemini): +Local heuristic summariser. Doesn't use any AI or network. +Uses Python's AST to reliably pull out classes, methods, and functions. +Regex is used for TOML and Markdown. + +The rationale here is simple: giving the AI the *structure* of a codebase is 90% +as good as giving it the full source, but costs 1% of the tokens. +If it needs the full source of a file after reading the summary, it can just call read_file. +""" +# summarize.py """ Local symbolic summariser — no AI calls, no network.