diff --git a/Documentation/.obsidian/app.json b/Documentation/.obsidian/app.json new file mode 100644 index 0000000..9e26dfe --- /dev/null +++ b/Documentation/.obsidian/app.json @@ -0,0 +1 @@ +{} \ No newline at end of file diff --git a/Documentation/.obsidian/appearance.json b/Documentation/.obsidian/appearance.json new file mode 100644 index 0000000..9e26dfe --- /dev/null +++ b/Documentation/.obsidian/appearance.json @@ -0,0 +1 @@ +{} \ No newline at end of file diff --git a/Documentation/.obsidian/core-plugins.json b/Documentation/.obsidian/core-plugins.json new file mode 100644 index 0000000..639b90d --- /dev/null +++ b/Documentation/.obsidian/core-plugins.json @@ -0,0 +1,33 @@ +{ + "file-explorer": true, + "global-search": true, + "switcher": true, + "graph": true, + "backlink": true, + "canvas": true, + "outgoing-link": true, + "tag-pane": true, + "footnotes": false, + "properties": true, + "page-preview": true, + "daily-notes": true, + "templates": true, + "note-composer": true, + "command-palette": true, + "slash-command": false, + "editor-status": true, + "bookmarks": true, + "markdown-importer": false, + "zk-prefixer": false, + "random-note": false, + "outline": true, + "word-count": true, + "slides": false, + "audio-recorder": false, + "workspaces": false, + "file-recovery": true, + "publish": false, + "sync": true, + "bases": true, + "webviewer": false +} \ No newline at end of file diff --git a/Documentation/.obsidian/workspace.json b/Documentation/.obsidian/workspace.json new file mode 100644 index 0000000..90d9669 --- /dev/null +++ b/Documentation/.obsidian/workspace.json @@ -0,0 +1,221 @@ +{ + "main": { + "id": "127e4477a3357592", + "type": "split", + "children": [ + { + "id": "4586ccd2645dafd5", + "type": "tabs", + "children": [ + { + "id": "0f41b448f12ad909", + "type": "leaf", + "state": { + "type": "markdown", + "state": { + "file": "Luna AI Assistant/Channels.md", + "mode": "source", + "source": false + }, + "icon": "lucide-file", + "title": "Channels" + } + } + ] + } + ], + "direction": "vertical" + }, + "left": { + "id": "7ee2740363116488", + "type": "split", + "children": [ + { + "id": "6d1750ac051219d1", + "type": "tabs", + "children": [ + { + "id": "6f7065cc7dffd180", + "type": "leaf", + "state": { + "type": "file-explorer", + "state": { + "sortOrder": "alphabetical", + "autoReveal": false + }, + "icon": "lucide-folder-closed", + "title": "Files" + } + }, + { + "id": "d20183e68c8d07ef", + "type": "leaf", + "state": { + "type": "search", + "state": { + "query": "", + "matchingCase": false, + "explainSearch": false, + "collapseAll": false, + "extraContext": false, + "sortOrder": "alphabetical" + }, + "icon": "lucide-search", + "title": "Search" + } + }, + { + "id": "8e3e15922e0dd412", + "type": "leaf", + "state": { + "type": "bookmarks", + "state": {}, + "icon": "lucide-bookmark", + "title": "Bookmarks" + } + } + ] + } + ], + "direction": "horizontal", + "width": 300, + "collapsed": true + }, + "right": { + "id": "2ab570a7ae13ec78", + "type": "split", + "children": [ + { + "id": "99c3f35707cad904", + "type": "tabs", + "children": [ + { + "id": "8575bcc7d3c3ca6a", + "type": "leaf", + "state": { + "type": "backlink", + "state": { + "file": "Luna AI Assistant/Core.md", + "collapseAll": false, + "extraContext": false, + "sortOrder": "alphabetical", + "showSearch": false, + "searchQuery": "", + "backlinkCollapsed": false, + "unlinkedCollapsed": true + }, + "icon": "links-coming-in", + "title": "Backlinks for Core" + } + }, + { + "id": "1d27ee4ebd4aa48b", + "type": "leaf", + "state": { + "type": "outgoing-link", + "state": { + "file": "Luna AI Assistant/Core.md", + "linksCollapsed": false, + "unlinkedCollapsed": true + }, + "icon": "links-going-out", + "title": "Outgoing links from Core" + } + }, + { + "id": "635fcf8053d67540", + "type": "leaf", + "state": { + "type": "tag", + "state": { + "sortOrder": "frequency", + "useHierarchy": true, + "showSearch": false, + "searchQuery": "" + }, + "icon": "lucide-tags", + "title": "Tags" + } + }, + { + "id": "fa0c1e82da200838", + "type": "leaf", + "state": { + "type": "all-properties", + "state": { + "sortOrder": "frequency", + "showSearch": false, + "searchQuery": "" + }, + "icon": "lucide-archive", + "title": "All properties" + } + }, + { + "id": "aebb6ab1e3be46a1", + "type": "leaf", + "state": { + "type": "outline", + "state": { + "file": "Luna AI Assistant/Core.md", + "followCursor": false, + "showSearch": false, + "searchQuery": "" + }, + "icon": "lucide-list", + "title": "Outline of Core" + } + } + ] + } + ], + "direction": "horizontal", + "width": 300, + "collapsed": true + }, + "left-ribbon": { + "hiddenItems": { + "switcher:Open quick switcher": false, + "graph:Open graph view": false, + "canvas:Create new canvas": false, + "daily-notes:Open today's daily note": false, + "templates:Insert template": false, + "command-palette:Open command palette": false, + "bases:Create new base": false + } + }, + "active": "0f41b448f12ad909", + "lastOpenFiles": [ + "References/OpenClaw/Compaction Strategy.md", + "References/ZeroClaw/Agent Loop & Tools.md", + "References/ZeroClaw/Compaction Strategy.md", + "References/ZeroClaw/Memory.md", + "References/OpenClaw/Memory SDK.md", + "References/ZeroClaw/Channel Messages.md", + "Luna AI Assistant/Project Plan.md", + "References/ZeroClaw/Skills.md", + "References/ZeroClaw/Configuration.md", + "References/ZeroClaw/Runtime Adapters.md", + "References/ZeroClaw/Sessions.md", + "References/OpenClaw/Channel System.md", + "References/ZeroClaw/Security.md", + "References/ZeroClaw.md", + "References/ZeroClaw/ReliableProvider.md", + "References/OpenClaw/Security.md", + "References/OpenClaw/Plugin Architecture.md", + "References/OpenClaw/Session Management.md", + "References/ZeroClaw/Overview.md", + "References/OpenClaw/Overview.md", + "References/ZeroClaw", + "References/OpenClaw", + "References/OpenClaw.md", + "Luna AI Assistant/Core.md", + "Luna AI Assistant/Multi-Agent Architecture.md", + "Luna AI Assistant/Memory.md", + "References/mistral.openapi.yaml", + "References/openai.openapi.yaml", + "References/openapi.yaml", + "References/openai.yaml", + "References" + ] +} \ No newline at end of file diff --git a/Documentation/Luna AI Assistant/.obsidian/app.json b/Documentation/Luna AI Assistant/.obsidian/app.json new file mode 100644 index 0000000..9e26dfe --- /dev/null +++ b/Documentation/Luna AI Assistant/.obsidian/app.json @@ -0,0 +1 @@ +{} \ No newline at end of file diff --git a/Documentation/Luna AI Assistant/.obsidian/appearance.json b/Documentation/Luna AI Assistant/.obsidian/appearance.json new file mode 100644 index 0000000..9e26dfe --- /dev/null +++ b/Documentation/Luna AI Assistant/.obsidian/appearance.json @@ -0,0 +1 @@ +{} \ No newline at end of file diff --git a/Documentation/Luna AI Assistant/.obsidian/core-plugins.json b/Documentation/Luna AI Assistant/.obsidian/core-plugins.json new file mode 100644 index 0000000..639b90d --- /dev/null +++ b/Documentation/Luna AI Assistant/.obsidian/core-plugins.json @@ -0,0 +1,33 @@ +{ + "file-explorer": true, + "global-search": true, + "switcher": true, + "graph": true, + "backlink": true, + "canvas": true, + "outgoing-link": true, + "tag-pane": true, + "footnotes": false, + "properties": true, + "page-preview": true, + "daily-notes": true, + "templates": true, + "note-composer": true, + "command-palette": true, + "slash-command": false, + "editor-status": true, + "bookmarks": true, + "markdown-importer": false, + "zk-prefixer": false, + "random-note": false, + "outline": true, + "word-count": true, + "slides": false, + "audio-recorder": false, + "workspaces": false, + "file-recovery": true, + "publish": false, + "sync": true, + "bases": true, + "webviewer": false +} \ No newline at end of file diff --git a/Documentation/Luna AI Assistant/.obsidian/graph.json b/Documentation/Luna AI Assistant/.obsidian/graph.json new file mode 100644 index 0000000..42a46ec --- /dev/null +++ b/Documentation/Luna AI Assistant/.obsidian/graph.json @@ -0,0 +1,22 @@ +{ + "collapse-filter": true, + "search": "", + "showTags": false, + "showAttachments": false, + "hideUnresolved": false, + "showOrphans": true, + "collapse-color-groups": true, + "colorGroups": [], + "collapse-display": true, + "showArrow": false, + "textFadeMultiplier": 0, + "nodeSizeMultiplier": 1, + "lineSizeMultiplier": 1, + "collapse-forces": true, + "centerStrength": 0.518713248970312, + "repelStrength": 10, + "linkStrength": 1, + "linkDistance": 250, + "scale": 1, + "close": true +} \ No newline at end of file diff --git a/Documentation/Luna AI Assistant/.obsidian/workspace.json b/Documentation/Luna AI Assistant/.obsidian/workspace.json new file mode 100644 index 0000000..703928b --- /dev/null +++ b/Documentation/Luna AI Assistant/.obsidian/workspace.json @@ -0,0 +1,224 @@ +{ + "main": { + "id": "b89020bafd288606", + "type": "split", + "children": [ + { + "id": "3b084bb6aea7bf06", + "type": "tabs", + "children": [ + { + "id": "27fd26dcd453c61f", + "type": "leaf", + "state": { + "type": "markdown", + "state": { + "file": "Channels/Web Interface Channel.md", + "mode": "source", + "source": false + }, + "icon": "lucide-file", + "title": "Web Interface Channel" + }, + "group": "47a210897f386c25" + } + ] + }, + { + "id": "7b841bf992949f81", + "type": "tabs", + "children": [ + { + "id": "5056061ce0a62aac", + "type": "leaf", + "state": { + "type": "markdown", + "state": { + "file": "Channels/Web Interface Channel.md", + "mode": "source", + "source": false + }, + "icon": "lucide-file", + "title": "Web Interface Channel" + }, + "group": "47a210897f386c25" + } + ] + } + ], + "direction": "vertical" + }, + "left": { + "id": "d65ed31b4cf140a8", + "type": "split", + "children": [ + { + "id": "cb79094e37f1bfbf", + "type": "tabs", + "children": [ + { + "id": "fcd6318fb0efd8c3", + "type": "leaf", + "state": { + "type": "file-explorer", + "state": { + "sortOrder": "alphabetical", + "autoReveal": false + }, + "icon": "lucide-folder-closed", + "title": "Files" + } + }, + { + "id": "1bbb51a5f3e6fe42", + "type": "leaf", + "state": { + "type": "search", + "state": { + "query": "", + "matchingCase": false, + "explainSearch": false, + "collapseAll": false, + "extraContext": false, + "sortOrder": "alphabetical" + }, + "icon": "lucide-search", + "title": "Search" + } + }, + { + "id": "bb387a4f03db1101", + "type": "leaf", + "state": { + "type": "bookmarks", + "state": {}, + "icon": "lucide-bookmark", + "title": "Bookmarks" + } + } + ] + } + ], + "direction": "horizontal", + "width": 300 + }, + "right": { + "id": "be153589260b27a6", + "type": "split", + "children": [ + { + "id": "b9a0a82b097773e2", + "type": "tabs", + "children": [ + { + "id": "99660be9c41b8d54", + "type": "leaf", + "state": { + "type": "backlink", + "state": { + "file": "Channels/Web Interface Channel.md", + "collapseAll": false, + "extraContext": false, + "sortOrder": "alphabetical", + "showSearch": false, + "searchQuery": "", + "backlinkCollapsed": false, + "unlinkedCollapsed": true + }, + "icon": "links-coming-in", + "title": "Backlinks for Web Interface Channel" + } + }, + { + "id": "e5acfa574174fe3a", + "type": "leaf", + "state": { + "type": "outgoing-link", + "state": { + "file": "Core.md", + "linksCollapsed": false, + "unlinkedCollapsed": true + }, + "icon": "links-going-out", + "title": "Outgoing links from Core" + } + }, + { + "id": "3693f3ae811b7b80", + "type": "leaf", + "state": { + "type": "tag", + "state": { + "sortOrder": "frequency", + "useHierarchy": true, + "showSearch": false, + "searchQuery": "" + }, + "icon": "lucide-tags", + "title": "Tags" + } + }, + { + "id": "018d06694edd9d01", + "type": "leaf", + "state": { + "type": "all-properties", + "state": { + "sortOrder": "frequency", + "showSearch": false, + "searchQuery": "" + }, + "icon": "lucide-archive", + "title": "All properties" + } + }, + { + "id": "b9b058ee8cd7d7a6", + "type": "leaf", + "state": { + "type": "outline", + "state": { + "file": "Core.md", + "followCursor": false, + "showSearch": false, + "searchQuery": "" + }, + "icon": "lucide-list", + "title": "Outline of Core" + } + } + ] + } + ], + "direction": "horizontal", + "width": 300, + "collapsed": true + }, + "left-ribbon": { + "hiddenItems": { + "switcher:Open quick switcher": false, + "graph:Open graph view": false, + "canvas:Create new canvas": false, + "daily-notes:Open today's daily note": false, + "templates:Insert template": false, + "command-palette:Open command palette": false, + "bases:Create new base": false + } + }, + "active": "5056061ce0a62aac", + "lastOpenFiles": [ + "Core.md", + "Channels/Web Interface Channel.md", + "Channels.md", + "Channels/Telegram Channel.md", + "Channels/CLI Channel.md", + "Channels/Channels.md", + "Channels", + "Skills.md", + "Configuration.md", + "Scheduler.md", + "Memory.md", + "Project Plan.md", + "Welcome.md" + ] +} \ No newline at end of file diff --git a/Documentation/Luna AI Assistant/Channels/CLI Channel.md b/Documentation/Luna AI Assistant/Channels/CLI Channel.md new file mode 100644 index 0000000..0e24688 --- /dev/null +++ b/Documentation/Luna AI Assistant/Channels/CLI Channel.md @@ -0,0 +1,23 @@ +# CLI Channel + +The CLI connects to Luna via SignalR. `CliChannel` is a server-side adapter that bridges the SignalR hub to the `IChannel` interface defined in [[Channels]]. + +## How It Works + +`CliChannel` wraps `IChatHubContext` from [[Core]] to send streaming responses back to the connected SignalR client. The flow: + +1. The `ChatHub` receives a message from the CLI client over SignalR. +2. `ChatHub` calls `RaiseMessageReceived` on the `CliChannel` instance. +3. The [[Channels|ChannelManager]] picks up the event and routes it through `SessionManager.RouteMessagesAsync`. +4. The resulting `IAsyncEnumerable` is passed back to `CliChannel.SendStreamingMessageAsync`. +5. `CliChannel` forwards the stream to the SignalR client via `IChatHubContext`. + +## Key Characteristics + +- **Server-side adapter**: `CliChannel` lives on the server; the actual CLI is a separate SignalR client. +- **Single connection**: One `CliChannel` instance maps to the SignalR hub connection. +- **No polling**: Unlike [[Telegram Channel]], the CLI uses persistent WebSocket connections via SignalR. + +## Namespace + +`Luna.Channels.Cli` diff --git a/Documentation/Luna AI Assistant/Channels/Channels.md b/Documentation/Luna AI Assistant/Channels/Channels.md new file mode 100644 index 0000000..ac6d558 --- /dev/null +++ b/Documentation/Luna AI Assistant/Channels/Channels.md @@ -0,0 +1,101 @@ +# Channels + +The Channels module provides a unified abstraction for communication platforms like the CLI and Telegram. It handles message transport, while [[Core]] manages AI context and session state. + +## Luna.Channels.Abstractions + +This project defines the contracts and event models for all channel implementations. + +### IChannel +The primary interface for any communication transport. There is no abstract base class; `IChannel` is the complete contract. + +```csharp +public interface IChannel : IDisposable +{ + string ChannelId { get; } + string ChannelType { get; } + string DisplayName { get; } + bool IsConnected { get; } + + event ChannelMessageReceivedEventHandler? MessageReceived; + event EventHandler? ConnectionStateChanged; + + Task SendMessageAsync(ChannelMessage message, CancellationToken ct = default); + Task SendStreamingMessageAsync(IAsyncEnumerable messageStream, CancellationToken ct = default); +} +``` + +### IChannelManager +Coordinates registered channels and handles message routing. + +```csharp +public interface IChannelManager +{ + void RegisterChannel(IChannel channel); + void UnregisterChannel(string channelId); + IChannel? GetChannel(string channelId); + IReadOnlyList GetAllChannels(); + event EventHandler? MessageRouted; +} +``` + +### Supporting Types +- **ChannelType**: A static class providing constants like `cli` and `telegram`. +- **ChannelMessageReceivedEventHandler**: Delegate for handling incoming messages. + `Task ChannelMessageReceivedEventHandler(object? sender, ChannelMessageReceivedEventArgs e)` +- **ChannelMessageReceivedEventArgs**: Contains the `Channel`, `Message`, and an `IsHandled` flag. +- **ChannelConnectionEventArgs**: Contains the `Channel` and `IsConnected` status. + +## Luna.Channels + +This project contains the concrete management logic and specific channel implementations. + +### ChannelManager +The `ChannelManager` implements `IChannelManager` and acts as the central hub for message traffic. It injects `ISessionManager` from [[Core]] and `ILogger`. + +When a channel is registered via `RegisterChannel`, the manager subscribes to its `MessageReceived` event. The `OnMessageReceivedAsync` handler performs the following: +1. Calls `sessionManager.RouteMessagesAsync(message.Content, message.ConversationId, channel.ChannelId)`. +2. Pipes the resulting `IAsyncEnumerable` back to the channel via `channel.SendStreamingMessageAsync`. + +### Channel Implementations +- [[CLI Channel]] — SignalR-based adapter for the command-line interface. +- [[Telegram Channel]] — Telegram Bot API adapter with message splitting and streaming. +- [[Web Interface Channel]] — Browser-based chat UI (not yet implemented). + +## Routing Flow + +1. `Channel.MessageReceived` event triggers. +2. `ChannelManager` catches the event and identifies the sender. +3. Manager calls `SessionManager.RouteMessagesAsync`. +4. `SessionManager` returns an `IAsyncEnumerable`. +5. `ChannelManager` passes this stream to `Channel.SendStreamingMessageAsync`. +6. The channel implementation handles the physical transport of the stream. + +## Architecture Decisions + +- **Separation of Concerns**: `ChannelManager` handles transport and routing. `SessionManager` handles AI context and conversation logic. +- **Conversation Scoping**: Sessions are scoped to conversations, not specific channels. This allows for potential cross-channel persistence. +- **Unified DTOs**: All message data uses the `ChannelMessage` DTO from `Luna.Shared`. +- **Registration**: Channels are registered via the `AddChannels()` DI extension method, following the [[Configuration]] patterns. +- **Options Pattern**: Implementations use `IOptions` (e.g., `TelegramOptions`) for configuration. + +## Dependencies + +### Project References +- `Luna.Channels.Abstractions` +- `Luna.Configuration` +- `Luna.Core.Abstractions` +- `Luna.Shared` + +### NuGet Packages +- `Telegram.Bot` +- `Microsoft.Extensions.Hosting.Abstractions` +- `Microsoft.Extensions.Logging.Abstractions` + +## Adding a New Channel + +To implement a new channel: +1. Create a class implementing `IChannel`. +2. Ensure it handles both `SendMessageAsync` and `SendStreamingMessageAsync`. +3. Raise `MessageReceived` when the external platform sends a message. +4. Register the channel with `IChannelManager` during startup or via a background adapter (like `TelegramAdapter`). diff --git a/Documentation/Luna AI Assistant/Channels/Telegram Channel.md b/Documentation/Luna AI Assistant/Channels/Telegram Channel.md new file mode 100644 index 0000000..905931a --- /dev/null +++ b/Documentation/Luna AI Assistant/Channels/Telegram Channel.md @@ -0,0 +1,39 @@ +# Telegram Channel + +The Telegram integration consists of two classes: `TelegramChannel` (the `IChannel` implementation) and `TelegramAdapter` (the hosted service that manages channel lifecycles). Both live in the `Luna.Channels.Telegram` namespace. + +## TelegramChannel + +Handles interaction with the Telegram Bot API, implementing the `IChannel` interface defined in [[Channels]]. + +### Message Splitting +Telegram enforces a 4096-character limit per message. `TelegramChannel` automatically splits long responses into sequential chunks that respect this limit. + +### Streaming +Rather than forwarding every `ChatStreamUpdate` individually (which would hit Telegram's rate limits), the channel accumulates streaming updates and sends them in periodic batches. + +### Typing Indicators +Uses `KeepTypingAsync` to maintain a "typing..." indicator in the Telegram chat while the AI generates a response. This runs as a background loop until the response completes. + +### User Filtering +`RaiseMessageReceived` filters incoming updates by `AllowedUserIds` (configured via `TelegramOptions` in [[Configuration]]). Messages from unauthorized users or with empty content are silently dropped. + +## TelegramAdapter + +An `IHostedService` and `IUpdateHandler` that polls Telegram for updates using long polling. + +### Lifecycle +1. On startup, begins polling the Telegram Bot API. +2. For each incoming update, identifies the chat ID. +3. Creates a new `TelegramChannel` instance for each unique chat (if one doesn't already exist). +4. Registers the channel with `IChannelManager` from [[Channels]]. +5. Routes the update to the appropriate `TelegramChannel`. + +### Configuration +Configured via `TelegramOptions` (see [[Configuration]]), which includes: +- `BotToken` — Telegram Bot API token. +- `AllowedUserIds` — Whitelist of Telegram user IDs permitted to interact with Luna. + +## Namespace + +`Luna.Channels.Telegram` diff --git a/Documentation/Luna AI Assistant/Channels/Web Interface Channel.md b/Documentation/Luna AI Assistant/Channels/Web Interface Channel.md new file mode 100644 index 0000000..f34a763 --- /dev/null +++ b/Documentation/Luna AI Assistant/Channels/Web Interface Channel.md @@ -0,0 +1,41 @@ +# Web Interface Channel + +> [!info] Status: Not Yet Implemented + +The Web Interface channel will provide a browser-based chat UI for interacting with Luna directly, without requiring the CLI or Telegram. It implements the `IChannel` interface defined in [[Channels]]. + +## Planned Approach + +### WebInterfaceChannel + +A server-side `IChannel` implementation that bridges the web frontend to Luna's channel system. Similar to [[CLI Channel]], it will likely use SignalR for real-time bidirectional communication. + +**Key responsibilities:** +- Accept messages from authenticated browser sessions. +- Stream `ChatStreamUpdate` responses back to the frontend in real time. +- Manage connection lifecycle (connect, disconnect, reconnect). + +### WebInterfaceAdapter + +An `IHostedService` (similar to `TelegramAdapter` in [[Telegram Channel]]) responsible for: +- Registering `WebInterfaceChannel` instances with `IChannelManager` from [[Channels]]. +- Managing per-user or per-session channel lifecycle. + +## Configuration + +Will follow the existing [[Configuration]] options pattern with a `WebInterfaceOptions` class containing settings such as: +- Authentication / authorization settings. +- CORS policy. +- Session timeout. + +## Dependencies + +### Expected Project References +- `Luna.Channels.Abstractions` +- `Luna.Configuration` +- `Luna.Core.Abstractions` +- `Luna.Shared` + +## Namespace + +`Luna.Channels.Web` diff --git a/Documentation/Luna AI Assistant/Configuration.md b/Documentation/Luna AI Assistant/Configuration.md new file mode 100644 index 0000000..60b6e38 --- /dev/null +++ b/Documentation/Luna AI Assistant/Configuration.md @@ -0,0 +1,112 @@ +# Configuration + +## Overview +Luna uses the standard .NET Options pattern for managing application settings. The configuration system relies on `IOptions` and `IOptionsMonitor` to provide typed access to settings defined in `appsettings.json`. This approach ensures type safety and allows for easy validation at startup. + +The configuration is centralized in the `Luna.Configuration` project. Settings are bound during application startup using the `.BindConfiguration().ValidateDataAnnotations().ValidateOnStart()` pattern. + +## Options Classes + +### AgentOptions +These settings define the behavior and identity of AI agents like the [[Core]] agent or the Librarian. Agents retrieve their specific configuration using `IOptionsMonitor.Get(name)`. + +```csharp +public class AgentOptions +{ + public required string Name { get; set; } + public string? DisplayName { get; init; } + public string? Description { get; init; } + public required string Provider { get; init; } + public required string ModelId { get; init; } + public required string Instructions { get; init; } + public required int MaxContextTokens { get; init; } +} +``` + +### ProviderOptions +Configures the connection details for AI model providers such as Mistral or OpenAI. + +```csharp +public class ProviderOptions +{ + public required string ApiKey { get; init; } + public required string ApiUrl { get; init; } + public required string[] Models { get; init; } +} +``` + +### SessionOptions +Controls how [[Memory]] and conversation sessions are managed. It specifically dictates when the session context should be compacted to save tokens. + +```csharp +public class SessionOptions +{ + public required float ContextTokenThreshold { get; init; } + public required int RetainedMessagesAfterCompacting { get; init; } +} +``` + +### TelegramOptions +Specific settings for the Telegram [[Channels]] adapter, including bot authentication and user access control. + +```csharp +public class TelegramOptions +{ + public required string BotToken { get; init; } + public string? WebhookUrl { get; init; } + public int PollingTimeoutSeconds { get; init; } = 30; + public string[] AllowedUserIds { get; init; } = []; +} +``` + +## Example Configuration + +The following `appsettings.json` structure demonstrates how these options are populated: + +```json +{ + "Agents": { + "Core": { + "Name": "Core", + "Provider": "Mistral", + "ModelId": "mistral-small-latest", + "Instructions": "You are Luna, a helpful AI assistant.", + "MaxContextTokens": 8192 + }, + "Librarian": { + "Name": "Librarian", + "Provider": "Mistral", + "ModelId": "mistral-small-latest", + "Instructions": "Summarize conversations concisely.", + "MaxContextTokens": 4096 + } + }, + "Providers": { + "Mistral": { + "ApiKey": "YOUR_API_KEY", + "ApiUrl": "https://api.mistral.ai", + "Models": ["mistral-small-latest"] + } + }, + "Session": { + "ContextTokenThreshold": 0.7, + "RetainedMessagesAfterCompacting": 5 + }, + "Channels": { + "Telegram": { + "BotToken": "YOUR_BOT_TOKEN", + "PollingTimeoutSeconds": 30, + "AllowedUserIds": [] + } + } +} +``` + +## Dependencies + +The configuration module depends on the following NuGet packages: + +- Microsoft.Extensions.DependencyInjection.Abstractions +- Microsoft.Extensions.FileProviders.Embedded +- Microsoft.Extensions.Options +- Tomlyn (for parsing embedded TOML resources) diff --git a/Documentation/Luna AI Assistant/Context Compaction Research.md b/Documentation/Luna AI Assistant/Context Compaction Research.md new file mode 100644 index 0000000..54057c7 --- /dev/null +++ b/Documentation/Luna AI Assistant/Context Compaction Research.md @@ -0,0 +1,106 @@ +# Context Compaction Research + +This document captures a research analysis comparing Claude Code's compaction engine patterns against Luna's current implementation, with recommendations for adoption. Reference source: https://barazany.dev/blog/claude-codes-compaction-engine + +## Luna's Current Compaction Architecture + +| Component | Current Approach | +|---|---| +| Trigger | Token threshold: `session.TokenAmount > MaxContextTokens * 0.75` | +| Token estimation | Naive `text.Length / 4` heuristic (`TokenEstimator`) | +| Compaction method | Single LLM call via `LibrarianAgent` (Mistral Small) — plain bullet-point summary | +| Retained context | Last N messages (default: 2) carried forward | +| Post-compaction reconstruction | Summary wrapped in `MEMORY BEGIN/END` markers as an Assistant message, then retained messages appended | +| Persistent memory | File-based `MemoryStore` — raw conversation logs to disk, last 10 read back as system message | +| Tiers | None — only full LLM summarization | +| Cache awareness | None | +| Tool result management | None — tool outputs accumulate until full compaction | + +## Claude Code's Three-Tier Pattern + +Claude Code employs a tiered strategy to manage context while maximizing cache efficiency: + +- **Tier 1**: Lightweight deterministic cleanup before every API call. This process clears old tool results (retaining only the last 5) and replaces them with placeholders. No LLM is involved at this stage. +- **Tier 2**: API-level server-side strategies for token management using Anthropic-specific infrastructure. +- **Tier 3**: Full LLM summarization as a last resort. This involves a structured 9-section summary with a chain-of-thought scratchpad. Post-compaction reconstruction includes a boundary marker, the summary, the 5 most recently read files (capped at 50K tokens), re-injected skills, tool definitions, and session hooks. + +The key architectural insight is that cache economics drive every decision. This includes using `cache_edits` for surgical server-side deletions and ensuring the summarization call reuses the same cache key. + +## Pattern Evaluation + +### 1. Tier 1 — Deterministic Tool Result Cleanup +**Gap**: Luna currently has zero tool result management. +**Recommendation**: ADOPT. +**Effort**: Low. +**Details**: Implement a pre-call sanitizer that trims old tool results before each API call to prevent context bloating from large tool outputs. + +### 2. Structured Compaction Prompt +**Gap**: Luna uses a simple "max 12 bullet points" prompt. +**Recommendation**: ADOPT. +**Effort**: Low. +**Details**: Replace the current prompt with a structured template that forces categorized output, including user intent, key decisions, unresolved tasks, relevant facts, and technical context. + +### 3. Tiered Compaction (Delay LLM Summarization) +**Gap**: Luna only supports full LLM summarization. +**Recommendation**: ADOPT. +**Effort**: Moderate. +**Details**: Implement a 2-tier system. Tier 1 performs deterministic cleanup on every call, while Tier 2 triggers LLM summarization only when Tier 1 is insufficient. The Anthropic-specific server-side tier will be skipped. + +### 4. Post-Compaction Reconstruction +**Gap**: Luna's reconstruction logic is basic and uses Assistant messages for summaries. +**Recommendation**: PARTIALLY ADOPT. +**Effort**: Moderate. +**Details**: Place the summary as a System message instead of an Assistant message. Re-inject agent instructions and add a boundary marker with metadata (timestamp, pre-compaction message count). Include a continuation message so the agent does not treat the summary as something to respond to. + +### 5. Improved Token Estimation +**Gap**: Luna relies on a `text.Length / 4` heuristic. +**Recommendation**: ADOPT. +**Effort**: Low. +**Details**: Replace the current heuristic with a proper tokenizer, such as `Microsoft.ML.Tokenizers`, or a significantly improved heuristic. + +### 6. Autonomous Continuation After Compaction +**Gap**: Compaction can disrupt the conversation flow. +**Recommendation**: ADOPT LIGHTLY. +**Effort**: Trivial. +**Details**: Prepend a brief system message after compaction, such as "Context was compacted. Continue naturally." + +### 7. Cache-Aware `cache_edits` +**Gap**: This is specific to Anthropic's API. +**Recommendation**: NOT APPLICABLE. +**Effort**: N/A. +**Details**: This could be revisited if an Anthropic provider is added to `IProvider` in the future. + +### 8. Same-Cache-Key Summarization +**Gap**: Luna uses a cheaper model (Mistral Small) for compaction. +**Recommendation**: NOT APPLICABLE. +**Effort**: N/A. +**Details**: Luna's current approach is effective when prompt caching is not a primary factor. + +## Priority Adoption Matrix + +| Priority | Pattern | Effort | Impact | +|---|---|---|---| +| P0 | Tier 1 — Deterministic tool result cleanup | Low | High | +| P0 | Structured compaction prompt | Low | High | +| P1 | Tiered compaction (delay LLM summarization) | Moderate | High | +| P1 | Post-compaction reconstruction improvements | Moderate | Medium | +| P1 | Improved token estimation | Low | Medium | +| P2 | Continuation message after compaction | Trivial | Low-Medium | +| N/A | Cache-aware `cache_edits` | — | Not applicable (Mistral) | +| N/A | Same-cache-key summarization | — | Not applicable | + +## Known Issues Found During Analysis + +There is a bug in `SessionManager.SaveSessionLogAsync()` at line 97: + +```csharp +.Where(m => m.Role != ChatRole.System || m.Role != ChatRole.Tool) +``` + +This condition is always true due to De Morgan's law. It should use `&&` instead of `||` to correctly filter out system and tool messages. + +## Cross-References + +- [[Core]] — SessionManager, compaction flow, token estimation +- [[Memory]] — MemoryStore, persistent conversation logs +- [[Configuration]] — SessionOptions (ContextTokenThreshold, RetainedMessagesAfterCompacting) diff --git a/Documentation/Luna AI Assistant/Core.md b/Documentation/Luna AI Assistant/Core.md new file mode 100644 index 0000000..9177534 --- /dev/null +++ b/Documentation/Luna AI Assistant/Core.md @@ -0,0 +1,137 @@ +# Core Module + +The Core module serves as the central orchestration engine for Luna, managing sessions, message routing, context compaction, and tool integration. It is split into `Luna.Core.Abstractions` for interfaces and `Luna.Core` for the primary implementation. + +## Luna.Core.Abstractions + +This project defines the contracts used by the Core and other modules. + +### ISessionManager +The primary interface for managing chat sessions and routing messages. +```csharp +public interface ISessionManager +{ + IAsyncEnumerable RouteMessagesAsync(string content, string conversationId, string connectionId, CancellationToken ct); + Task ClientDisconnectedAsync(string connectionId); +} +``` + +### IChatHubContext +Interface for sending responses back to clients via SignalR. +```csharp +public interface IChatHubContext +{ + Task SendResponseAsync(string connectionId, ChannelMessage message, CancellationToken ct); + Task SendStreamingResponseAsync(string connectionId, IAsyncEnumerable messageStream, CancellationToken ct); +} +``` + +## Luna.Core + +The main implementation project containing the session logic and SignalR hubs. + +### Session +The `Session` class manages the state of an active conversation. +```csharp +public class Session +{ + public string SessionId { get; set; } + public List Messages { get; } = new(); + public int TokenAmount => TokenEstimator.EstimateTokens(Messages); +} +``` + +### SessionManager +Implements `ISessionManager`. It coordinates between agents, memory, and the core LLM processing. +- **Injected Services**: + - `[FromKeyedServices("Core")] IAgent coreAgent` + - `[FromKeyedServices("Librarian")] IAgent librarianAgent` + - `IOptions options` + - `IChatStreamUpdateBuilder streamUpdateBuilder` + - `IMemoryStore memoryStore` +- **State Management**: Maintains an in-memory `Dictionary` for sessions and a `ConcurrentDictionary` for mapping connection IDs to session IDs. + +#### Message Routing Flow +1. **Session Initialization**: Creates a new session if one does not exist and loads existing [[Memory]] via `memoryStore.GetMemoriesAsync()`. +2. **Token Check**: Evaluates current token usage against `MaxContextTokens * ContextTokenThreshold`. +3. **Compaction**: If the threshold is exceeded, triggers `CompactSessionAsync`. +4. **Processing**: Appends the user message, streams the response from the `coreAgent` via `ProcessStreamingAsync`, and converts AI content to `ChatStreamUpdate` using the `IChatStreamUpdateBuilder`. +5. **Persistence**: Appends the assistant response to the session history. + +#### Compaction Strategy +When a session exceeds the token threshold, the system: +1. Retains the last $N$ messages (defined by `SessionOptions.RetainedMessagesAfterCompacting`). +2. Sends all older messages to the `librarianAgent` for summarization. +3. Wraps the resulting summary in `<---- MEMORY BEGIN ---->` and `<---- MEMORY END ---->` markers and inserts it at the beginning of the message list. + +#### Disconnect Flow +When `ClientDisconnectedAsync` is called: +1. The conversation log is saved to the `IMemoryStore`. +2. The session and connection mappings are cleaned up. + +### Hubs and Contexts + +#### ChatHub +A SignalR hub that serves as the entry point for real-time communication. +- **OnConnected**: Creates a `CliChannel` and registers it with the `IChannelManager`. +- **OnDisconnected**: Unregisters the channel. +- **OnMessageReceived**: Delegates message handling to the `CliChannel.RaiseMessageReceived`. + +#### ChatHubContext +Implements `IChatHubContext` using `IHubContext`. It handles the actual transmission of data to SignalR clients, supporting both discrete and streaming responses. + +### Tools System + +#### IToolbox +Provides a mechanism for discovering and exposing tools to the AI. +- **Implementation**: Uses reflection to find methods decorated with `[ToolAttribute]`. +- **Function Creation**: Generates `AITool` instances using `AIFunctionFactory.Create`. + +#### IToolsProvider +Exposes the collection of discovered tools. +```csharp +public interface IToolsProvider +{ + IEnumerable GetTools(); +} +``` + +### Token Estimation +The `TokenEstimator` provides a heuristic-based token count: +- **Calculation**: Number of characters divided by 4. + +## Architecture Flow + +The following flow describes how a message moves through the Core module: + +```text +Channel.MessageReceived → ChannelManager → SessionManager.RouteMessagesAsync + → Token Check → Compaction if needed (LibrarianAgent) + → CoreAgent.ProcessStreamingAsync → IChatClient Streaming + → ChatStreamUpdateBuilder → IAsyncEnumerable + → Channel.SendStreamingMessageAsync → Client +``` + +## Cross-References +- [[Channels]]: Management of communication pathways. +- [[Memory]]: Long-term and short-term state persistence. +- [[Configuration]]: `SessionOptions` and system settings. +- [[Skills]]: Integration of specialized capabilities. +- [[Scheduler]]: Task timing and execution. + +## Dependencies + +### Project References +- Luna.Agents.Abstractions +- Luna.Channels +- Luna.Channels.Abstractions +- [[Configuration]] (Luna.Configuration) +- Luna.Core.Abstractions +- [[Memory]] (Luna.Memory) +- Luna.Providers +- Luna.Providers.Abstractions +- Luna.Shared + +### NuGet Packages +- Microsoft.AspNetCore.OpenApi +- Microsoft.Extensions.AI diff --git a/Documentation/Luna AI Assistant/Memory.md b/Documentation/Luna AI Assistant/Memory.md new file mode 100644 index 0000000..74ee825 --- /dev/null +++ b/Documentation/Luna AI Assistant/Memory.md @@ -0,0 +1,84 @@ +# Memory Module + +## Overview + +The Memory module provides persistent conversation storage for the Luna AI Assistant. It uses a simple **filesystem-based** approach — conversation logs are written as plain text files and read back to seed new sessions with prior context. + +The module consists of a single project: `Luna.Memory`. + +--- + +## Interface + +```csharp +public interface IMemoryStore +{ + Task AddMemoryAsync(string memory); + Task GetMemoriesAsync(); +} +``` + +- `AddMemoryAsync` — persists a conversation log or compaction summary to storage. +- `GetMemoriesAsync` — retrieves recent memories as a single concatenated string, used to seed new conversations. + +--- + +## Implementation + +### MemoryStore + +`MemoryStore` is the concrete `IMemoryStore` implementation. It stores conversation logs as individual files on disk. + +**Storage path**: `~/.luna/memory/conversations/` + +**File naming**: `Luna_Conversation_Log_{yyyyMMddHHmmss}` + +```csharp +public class MemoryStore : IMemoryStore +``` + +| Method | Behavior | +|--------|----------| +| `AddMemoryAsync` | Creates the storage directory if it does not exist, then writes the memory string to a new timestamped file. | +| `GetMemoriesAsync` | Reads the **last 10 files** (ordered by timestamp descending, parsed from the filename), concatenates their contents, and returns the result. Returns an empty string if no files exist. | + +There is no database, no Redis, and no SQLite involved — persistence is purely filesystem-based. + +--- + +## Integration with the System + +The `SessionManager` in [[Core]] injects `IMemoryStore` and uses it at three points: + +1. **Session creation** — On the first message in a new conversation, `SessionManager` calls `GetMemoriesAsync()` and, if non-empty, prepends the result as a `ChatMessage` with `ChatRole.System`. This gives the agent prior conversational context. + +2. **Client disconnect** — When a client disconnects, `SessionManager.ClientDisconnectedAsync` triggers `SaveSessionLogAsync`, which formats all user and assistant messages from the session and calls `AddMemoryAsync` to persist the log. + +3. **Compaction** — When the session's token count exceeds the configured threshold (see [[Configuration]] `SessionOptions`), `SessionManager` uses the Librarian agent to summarize older messages. The summary is retained in-session as an assistant message wrapped in: + ``` + <---- MEMORY BEGIN ----> + [Meta] Conversation Recorded at: {timestamp} + {summary} + <---- MEMORY END ----> + ``` + +--- + +## DI Registration + +Memory services are registered via the `AddMemory()` extension method on `IServiceCollection`. + +--- + +## Dependencies + +**Project references**: None (standalone module). + +**NuGet packages**: +- `Microsoft.Extensions.Caching.Memory` +- `Microsoft.Extensions.DependencyInjection.Abstractions` +- `Microsoft.Extensions.Logging.Abstractions` +- `Microsoft.Extensions.Options` +- `StackExchange.Redis` (present in csproj, currently unused) +- `Microsoft.Data.Sqlite` (present in csproj, currently unused) +- `Microsoft.EntityFrameworkCore.Sqlite` (present in csproj, currently unused) diff --git a/Documentation/Luna AI Assistant/Scheduler.md b/Documentation/Luna AI Assistant/Scheduler.md new file mode 100644 index 0000000..4a2453e --- /dev/null +++ b/Documentation/Luna AI Assistant/Scheduler.md @@ -0,0 +1,24 @@ +# Scheduler + +> [!info] Status: Not Yet Implemented +> This module is planned for a future development phase. + +The Scheduler provides a mechanism for Luna to handle time-based operations and periodic tasks. It acts as a temporal bridge between [[Core]] and [[Memory]], ensuring that scheduled actions are executed reliably and within the specified context. + +## Purpose +The primary role of the Scheduler is to periodically scan [[Memory]] for pending tasks and coordinate their execution. It manages the lifecycle of long-running or deferred operations, ensuring they are handed off to the appropriate Agents at the right time. + +## Planned Features +- **Recurring Tasks**: Support for daily, weekly, or interval-based execution patterns. +- **Task Dependencies**: Ability to chain tasks so that one starts only after another completes successfully. +- **Priority Queue**: Management of task urgency to ensure critical system operations take precedence. +- **Cron Scheduling**: Standardized string-based scheduling for precise control over execution times. + +## Architecture & Integration +The Scheduler is expected to integrate deeply with the following modules: +- **[[Core]]**: For task execution logic and agent coordination. +- **[[Memory]]**: To persist task states and schedules. + +## Likely Dependencies +To ensure robust background execution, the module will likely utilize: +- `Microsoft.Extensions.Hosting`: Leveraging `IHostedService` or `BackgroundService` for long-lived process management within the .NET ecosystem. diff --git a/Documentation/Luna AI Assistant/Skills.md b/Documentation/Luna AI Assistant/Skills.md new file mode 100644 index 0000000..5b6b918 --- /dev/null +++ b/Documentation/Luna AI Assistant/Skills.md @@ -0,0 +1,23 @@ +# Skills + +> [!info] Status: Not Yet Implemented +> This module is planned for a future development phase. + +The Skills module is designed as a plugin system to extend Luna with third-party integrations and specialized tools. It provides a modular framework for adding new capabilities without modifying the core system. + +## Existing Tools System +It is important to note that a basic tools system already exists in [[Core]]. This existing system includes: +- `IToolbox`: A registry for managing available tools. +- `IToolsProvider`: An interface for supplying tools to the assistant. +- `ToolAttribute`: Used for reflective discovery of tools within the codebase. + +The Skills module will build upon or complement this system by allowing for more complex, external integrations. + +## Planned Features +- **Dynamic Skill Loading**: Support for loading and unloading skills at runtime without requiring a system restart. +- **Skill Discovery**: Automatic detection of new skills within designated plugin directories. +- **Capability-Based Security**: A granular permission model where skills must declare and be granted specific capabilities (e.g., network access, file system access). +- **Third-Party Integrations**: A standardized interface for connecting Luna to external services and APIs. + +## Integration +- **[[Core]]**: The Skills module will interface with the existing tools system in the Core to expose its capabilities to the AI Agents. diff --git a/Documentation/References/OpenClaw/Channel System.md b/Documentation/References/OpenClaw/Channel System.md new file mode 100644 index 0000000..79321c2 --- /dev/null +++ b/Documentation/References/OpenClaw/Channel System.md @@ -0,0 +1,70 @@ +# Channel System + +The Channel System in OpenClaw is a highly decoupled messaging platform integration layer. It allows OpenClaw to interface with diverse services like WhatsApp, Telegram, Slack, and Discord through a unified set of interfaces while preserving platform-specific capabilities. + +*** + +## Plugin-Per-Platform Pattern + +OpenClaw employs a strict plugin architecture where every supported messaging platform is a self-contained module located under `src/channels/plugins/`. This directory contains over 100 files, with each platform adapter implementing a standard set of interfaces defined in `types.plugin.ts` and `types.adapters.ts`. + +Key aspects of this pattern include: +* **Isolation**: Each plugin maintains its own dependencies and platform-specific logic (e.g., the Telegram plugin handles its own bot API calls). +* **Standardized Lifecycle**: Plugins implement `ChannelLifecycleAdapter` to manage startup, shutdown, and health checks. +* **Feature-Based Opt-in**: Plugins advertise their capabilities (e.g., `threads`, `reactions`, `media`) via a `ChannelCapabilities` object, allowing the core to gracefully degrade or enhance features per-channel. + +*** + +## Shared Registry & Helpers + +A centralized `registry.ts` manages all active channel plugins. Instead of hardcoding platform logic into the core, the registry provides a discovery mechanism for the system to interact with whatever plugins are currently loaded. + +### Message Normalization +Incoming raw messages from various platforms are normalized into a standard `MsgContext` before reaching the agent or session logic. This normalization ensures consistent handling of: +* **Sender Identification**: Mapping platform-specific IDs to a common structure containing `SenderId`, `SenderName`, and `SenderUsername`. +* **Thread Tracking**: Normalizing `ThreadId` and `ReplyToId` so the core can track conversations across platforms that represent threads differently (e.g., Slack's thread timestamps vs. Telegram's reply-to message IDs). +* **Channel Metadata**: Attaching `Channel` (platform name) and `ChatType` (direct, group, or channel) to every inbound payload. + +### Shared Utilities +OpenClaw provides several helper modules that plugins use to reduce boilerplate: +* `sender-identity.ts`: Validates and sanitizes sender metadata. +* `chat-meta.ts`: Manages channel-level metadata like labels, blurbs, and documentation links. +* `session-envelope.ts`: Handles the wrapping of messages for persistent storage. + +*** + +## Access Control & Routing + +OpenClaw enforces security and session boundaries at the channel level. + +### Allowlist-based Access +The system uses an allowlist-based policy for each channel. The `allowlist-match.ts` and `allow-from.ts` utilities provide logic to verify if a specific sender or group is permitted to interact with the agent. This ties directly into [[Security]] policies, preventing unauthorized access before a session is even initialized. + +### Session Routing +Incoming messages are routed to specific sessions based on their origin: +* **Direct Messages (DMs)**: Usually routed to a per-sender session. +* **Group Chats**: Messages are routed to a session keyed by the group ID. +* **Thread Binding**: `thread-bindings-policy.ts` determines if a message should stay within an existing session or trigger the creation of a child session. + +*** + +## Channel-Specific Auth + +Authentication is delegated to the individual plugins through the `ChannelAuthAdapter`. Each platform handles its own credential requirements: +* **Bot Tokens**: Simple token-based auth (Telegram, Discord). +* **OAuth**: Flow-based authentication for user-level access (Slack, Matrix). +* **QR Code Pairing**: Used by platforms like WhatsApp or Signal to link an existing account. + +The `ChannelSetupAdapter` provides a standardized `ChannelSetupInput` bag containing fields for `botToken`, `appToken`, `privateKey`, and more, which are then stored in the system's secure configuration. + +*** + +## Relevance to Luna + +The OpenClaw channel system provides a blueprint for expanding Luna beyond its current CLI-only interface. + +Key lessons for [[Channels]]: +* **Establish a Rich Normalized Type**: Before adding a second channel, Luna should define a robust internal message format. This prevents the core logic from becoming littered with "if platform is Discord" checks. +* **Abstract Outbound Routing**: By defining a common `ChannelOutboundAdapter`, Luna can send messages to any platform using a unified API, even if the underlying delivery mechanism (WebSocket, HTTP POST, CLI print) varies wildly. + +Cross-references: [[Core]], [[Security]] diff --git a/Documentation/References/OpenClaw/Compaction Strategy.md b/Documentation/References/OpenClaw/Compaction Strategy.md new file mode 100644 index 0000000..919ac2b --- /dev/null +++ b/Documentation/References/OpenClaw/Compaction Strategy.md @@ -0,0 +1,142 @@ +# Compaction Strategy + +OpenClaw employs a multi-layered conversation compaction system to manage long-running sessions within finite model context windows. Unlike basic truncation, this system uses LLM-driven summarization, token-budget gating, and quality safeguards to preserve critical state, identifiers, and recent context. + +*** + +## Trigger & Token Gating + +Compaction is primarily triggered by "preflight" checks before processing a new turn, ensuring the model has sufficient headroom for its next response. This process is managed in `auto-reply/reply/agent-runner-memory.ts` and `memory-flush.ts`. + +### Gating Logic +The decision to compact is based on a projected token count compared against a computed threshold: +- **Threshold Formula**: `contextWindowTokens - reserveTokensFloor - softThresholdTokens` +- **Reserve Floor**: Defaults to 20,000 tokens (`reserveTokensFloor`), providing a safety buffer for tool outputs and reasoning. +- **Soft Threshold**: An additional 4,000 token buffer (`softThresholdTokens`) to prevent compaction oscillations at the exact limit. +- **Token Estimation**: Performed by `estimateMessagesTokens()`, which strips `toolResult.details` for security and applies a `SAFETY_MARGIN` of 1.2 to account for estimation inaccuracies. + +### Execution Hooks +- **shouldRunPreflightCompaction**: Runs before a turn to ensure the input fits the budget. +- **shouldRunMemoryFlush**: Evaluates if the session should be "flushed" to long-term memory based on token pressure. +- **Deduplication**: `hasAlreadyFlushedForCurrentCompaction` prevents redundant flushes within a single compaction cycle. +- **Manual Trigger**: The `/compact` command allows users to manually force a compaction cycle. + +*** + +## Summarization Core + +The core summarization engine in `agents/compaction.ts` orchestrates the transformation of raw history into structured summaries. + +### Resource Allocation +- **SUMMARIZATION_OVERHEAD_TOKENS**: 4,096 tokens are reserved for the summarization prompt, system instructions, and previous summaries. +- **Adaptive Chunking**: `computeAdaptiveChunkRatio` shrinks chunk sizes as the average message size increases. If a single message exceeds 50% of the context window, it is flagged as `isOversizedForSummary` and handled via fallback mechanisms. + +### Orchestration Pipeline +1. **summarizeChunks**: Splits the history into chunks based on `maxChunkTokens`. +2. **summarizeWithFallback**: Attempts a full summary. On failure, it separates "small" messages from "oversized" ones, summarizing the small messages and annotating the oversized ones (e.g., `[Large message (~15K tokens) omitted from summary]`). +3. **summarizeInStages**: For very large histories, it generates partial summaries and then merges them using `MERGE_SUMMARIES_INSTRUCTIONS`. + +### Preservation Priorities +The system uses `MERGE_SUMMARIES_INSTRUCTIONS` to ensure the model retains: +- Active tasks and current status (in-progress, blocked, pending). +- Commitments, decisions, and their rationale. +- Unresolved user asks and key factual identifiers. +- Recent context over older history. + +*** + +## Safeguard Extension + +The `compaction-safeguard.ts` hook acts as a safety layer, registering on `session_before_compact` to manage context sharing and content preservation. + +### Context Preservation +- **Recent Turns**: Preserves `DEFAULT_RECENT_TURNS_PRESERVE = 3` turns verbatim to maintain immediate conversational flow. +- **History Pruning**: `pruneHistoryForContextShare` drops older chunks if the new content consumes too much of the history budget. Dropped messages are summarized and prepended as a `previousSummary`. +- **Suffix Protection**: Critical metadata is appended to a protected suffix that survives truncation: + - Tool failures (capped at 8 failures). + - File operations (read/modified lists). + - Workspace rules (extracted from `AGENTS.md`). + +### Length Constraints +- **MAX_COMPACTION_SUMMARY_CHARS**: 16,000 characters cap for the total summary. +- **MAX_FILE_OPS_SECTION_CHARS**: 2,000 characters for file operation logs. +- **MAX_FILE_OPS_LIST_CHARS**: 900 characters for the list of files. + +*** + +## Quality Guard + +The Quality Guard (`compaction-safeguard-quality.ts`) ensures the LLM-generated summary meets strict structural and content requirements. + +### Required Sections +Every summary must contain these exact Markdown headings: +- `## Decisions` +- `## Open TODOs` +- `## Constraints/Rules` +- `## Pending user asks` +- `## Exact identifiers` + +### Identifier Preservation +The system extracts opaque identifiers (URLs, file paths, hex IDs, ports) using regex and enforces their preservation. +- **Strict Policy**: If `identifierPolicy` is set to `strict`, the guard validates that all extracted identifiers appear in the final summary. +- **Audit Loop**: `auditSummaryQuality` checks for section presence and identifier integrity. If checks fail, the system triggers a regeneration with `qualityFeedbackInstruction`. + +*** + +## Default Instructions + +Default behavior is governed by `compaction-instructions.ts`, which merges user-defined, runtime, and system-level instructions. + +```typescript +export const DEFAULT_COMPACTION_INSTRUCTIONS = + "Write the summary body in the primary language used in the conversation.\n" + + "Focus on factual content: what was discussed, decisions made, and current state.\n" + + "Keep the required summary structure and section headers unchanged.\n" + + "Do not translate or alter code, file paths, identifiers, or error messages."; +``` + +Instructions are capped at `MAX_INSTRUCTION_LENGTH = 800` characters to prevent prompt bloat. + +*** + +## Runtime Execution & Truncation + +The `compact.ts` runner provides the entry point for both automated and manual compaction. + +### Execution Flow +1. **Preparation**: Opens the session, sanitizes history, and runs `before_compaction` hooks. +2. **Safety Timeout**: Wraps the LLM call in `compactWithSafetyTimeout` to prevent hanging processes. +3. **Post-Processing**: Runs `after_compaction` hooks and estimates the resulting token count. + +### Session Truncation +If enabled via `config.agents.defaults.compaction.truncateAfterCompaction`, the system physically rewrites the session JSONL file using `session-truncation.ts`. +- **Removal**: Deletes message entries that were summarized. +- **Re-parenting**: Re-parents orphaned entries to the nearest kept ancestor to maintain the integrity of the session tree. +- **Archiving**: Optionally creates an archive of the original session file before truncation. + +*** + +## Configuration Knobs + +Compaction behavior can be tuned via `OpenClawConfig`: +- `config.agents.defaults.compaction.model`: Override the model used for summarization. +- `config.agents.defaults.compaction.reserveTokensFloor`: Minimum buffer (default ~20,000). +- `config.agents.defaults.compaction.timeoutSeconds`: Max time allowed for a summarization call. +- `config.agents.defaults.compaction.truncateAfterCompaction`: Boolean to enable physical file cleanup. +- `memoryFlush`: Configuration for soft thresholds and forced flush triggers. + +*** + +## Relevance to Luna + +Luna currently uses a basic `LibrarianAgent` for compaction with no token-budget gating, no quality guards, and no structured instruction sets. To achieve OpenClaw-level reliability, Luna should adopt: + +- **Token-Budget Gating**: Triggering compaction based on projected context usage rather than arbitrary turn counts. +- **Structured Sections**: Enforcing a specific Markdown schema in summaries to ensure critical state is never lost. +- **Identifier Preservation**: Using regex extraction and quality audits to protect file paths and IDs. +- **Quality Audit Loop**: Implementing a verification step that can re-trigger summarization if requirements are missed. +- **Session Truncation**: Physically cleaning up on-disk history files to prevent unbounded growth. + +Patterns like the `compaction-safeguard` provide a more resilient approach for long-term project management in Luna by ensuring the project state, goals, and critical constraints are always prioritized in the model's working memory. + +See also: [[Core]], [[Configuration]], [[Session Management]] diff --git a/Documentation/References/OpenClaw/Memory SDK.md b/Documentation/References/OpenClaw/Memory SDK.md new file mode 100644 index 0000000..6b37909 --- /dev/null +++ b/Documentation/References/OpenClaw/Memory SDK.md @@ -0,0 +1,161 @@ +# Memory SDK + +OpenClaw's memory system lives in a standalone package (`packages/memory-host-sdk`) that exposes composable engines for storage, embeddings, query processing, and foundation utilities. The SDK defines a clear host-engine boundary: the host application consumes the SDK surface, while the SDK encapsulates all storage, indexing, and retrieval logic behind exported contracts. + +*** + +## Package Structure + +The SDK entry point (`engine.ts`) re-exports four focused engine modules: + +```typescript +export * from "./engine-foundation.js"; +export * from "./engine-storage.js"; +export * from "./engine-embeddings.js"; +export * from "./engine-qmd.js"; +``` + +Each engine is a self-contained barrel export covering one concern. New code is directed to the focused subpaths rather than the aggregate surface. + +*** + +## Engine Storage + +The storage engine (`engine-storage.ts`) provides the persistence and retrieval primitives built on SQLite with the `sqlite-vec` vector extension. + +### Key Exports + +- **`MemoryChunk`** and **`MemoryFileEntry`** — the core data types. A chunk is an indexed segment of content with metadata; a file entry represents a source document on disk. +- **`buildFileEntry`** / **`buildMultimodalChunkForIndexing`** — constructors for creating index-ready records. +- **`chunkMarkdown`** — splits markdown content into semantically coherent chunks for embedding. +- **`cosineSimilarity`** — vector distance computation for retrieval ranking. +- **`parseEmbedding`** — deserializes stored embedding vectors. +- **`ensureMemoryIndexSchema`** — creates or migrates the SQLite schema (tables, FTS indexes, vector columns). +- **`loadSqliteVecExtension`** — loads the `sqlite-vec` native extension into the SQLite connection. +- **`requireNodeSqlite`** — resolves the Node.js SQLite driver. +- **`readMemoryFile`** — reads a memory file from disk with safety checks. +- **`resolveMemoryBackendConfig`** — resolves backend-specific configuration (SQLite paths, vector dimensions, etc.). + +### Storage Architecture + +The storage layer uses SQLite as a single-file database with the `sqlite-vec` extension providing vector column support. Memory chunks are stored alongside their embeddings in the same database, enabling hybrid queries that combine full-text search with cosine vector similarity in a single SQL statement. This mirrors the approach used by ZeroClaw's SQLite backend (see [[ZeroClaw/Memory]]). + +```typescript +// Types exported for consumers +type MemoryChunk = { /* chunk content, metadata, embedding vector */ }; +type MemoryFileEntry = { /* source file path, hash, modification time */ }; +type MemorySearchResult = { /* ranked results with scores and source info */ }; +``` + +*** + +## Engine Embeddings + +The embeddings engine (`engine-embeddings.ts`) provides a pluggable embedding provider system with six built-in backends and batch processing utilities. + +### Embedding Providers + +| Provider | Default Model | Module | +|----------|--------------|--------| +| Local | `DEFAULT_LOCAL_MODEL` | `embeddings.js` | +| Gemini | `DEFAULT_GEMINI_EMBEDDING_MODEL` | `embeddings-gemini.js` | +| Mistral | `DEFAULT_MISTRAL_EMBEDDING_MODEL` | `embeddings-mistral.js` | +| Ollama | `DEFAULT_OLLAMA_EMBEDDING_MODEL` | `embeddings-ollama.js` | +| OpenAI | `DEFAULT_OPENAI_EMBEDDING_MODEL` | `embeddings-openai.js` | +| Voyage | `DEFAULT_VOYAGE_EMBEDDING_MODEL` | `embeddings-voyage.js` | + +### Provider Interface + +```typescript +// Core provider contract +type MemoryEmbeddingProvider = { + name: string; + // ... embedding computation methods +}; + +type MemoryEmbeddingProviderAdapter = { + // Adapts raw provider to the SDK contract +}; + +// Factory and registry +function getMemoryEmbeddingProvider(name: string): MemoryEmbeddingProvider; +function listMemoryEmbeddingProviders(): string[]; +``` + +### Batch Processing + +Three batch helpers handle high-throughput embedding jobs for initial indexing or re-indexing: + +- **`runGeminiEmbeddingBatches`** — Gemini-specific batching with rate limit handling. +- **`runOpenAiEmbeddingBatches`** — OpenAI batch API integration (`OPENAI_BATCH_ENDPOINT`). +- **`runVoyageEmbeddingBatches`** — Voyage AI batch processing. + +### Safety Utilities + +- **`enforceEmbeddingMaxInputTokens`** — truncates input to provider-specific token limits. +- **`estimateStructuredEmbeddingInputBytes`** / **`estimateUtf8Bytes`** — byte estimation for payload sizing. +- **`hasNonTextEmbeddingParts`** — detects multimodal content that requires special handling. + +*** + +## Engine Foundation + +The foundation engine (`engine-foundation.ts`) re-exports core utilities from the main OpenClaw application that the memory system depends on. Rather than duplicating logic, the SDK imports these through relative paths to the monorepo `src/` directory. + +### Key Capabilities + +- **Agent Scope Resolution**: `resolveAgentDir`, `resolveAgentWorkspaceDir`, `resolveDefaultAgentId`, `resolveSessionAgentId` — determines which agent's memory space to operate on. +- **Memory Search Configuration**: `resolveMemorySearchConfig` with `ResolvedMemorySearchConfig` type — controls search behavior (result limits, relevance thresholds). +- **Configuration Loading**: `loadConfig`, `resolveStateDir` — reads OpenClaw configuration and state directories. +- **Session Integration**: `resolveSessionTranscriptsDirForAgent`, `onSessionTranscriptUpdate` — watches for new conversation transcripts to index into memory. +- **File Safety**: `writeFileWithinRoot` — prevents path traversal when writing memory files. +- **Secrets**: `hasConfiguredSecretInput`, `normalizeResolvedSecretInputString` — resolves API keys for embedding providers. + +*** + +## Engine QMD (Query Processing) + +The QMD engine (`engine-qmd.ts`) handles query decomposition, keyword extraction, and scope filtering before executing memory searches. + +### Query Pipeline + +- **`extractKeywords`** — pulls meaningful terms from a natural language query, filtering stop words via `isQueryStopWordToken`. +- **`parseQmdQueryJson`** — parses structured query results (type `QmdQueryResult`) from the QMD binary. +- **Scope Filtering**: `deriveQmdScopeChannel`, `deriveQmdScopeChatType`, `isQmdScopeAllowed` — restricts search results to the appropriate channel and conversation type. +- **Session Files**: `buildSessionEntry`, `listSessionFilesForAgent`, `sessionPathForFile` — manages the session transcript files that feed into memory indexing. +- **CLI Integration**: `checkQmdBinaryAvailability`, `resolveCliSpawnInvocation`, `runCliCommand` — interfaces with an external QMD binary for query processing. + +*** + +## Integration Pattern + +The SDK is consumed by the host application through the aggregate `engine.ts` export. The boundary is clear: + +- **Host responsibility**: Decides when to index, when to search, which agent scope to use, and how to present results. +- **SDK responsibility**: Handles all storage I/O, embedding computation, vector indexing, query processing, and schema management. + +The typical flow: + +1. **Initialization**: Host calls `resolveMemoryBackendConfig` to set up the storage backend. +2. **Indexing**: Host uses `engine-embeddings` to generate vectors and `engine-storage` to persist chunks. +3. **Retrieval**: Host uses `engine-qmd` to process the query, then performs a similarity search via `engine-storage`. + +This separation means the memory engine can be tested independently, and the host can swap backends (e.g., different SQLite configurations, different embedding providers) without changing application logic. + +*** + +## Relevance to Luna + +Luna's [[Memory]] module defines an `IMemoryStore` interface but the current file-based implementation only supports writing — there is no recall or search capability. + +### Patterns to Adopt + +- **Composable Engine Architecture**: Separating storage, embeddings, and query processing into distinct layers is a clean pattern for Luna. Rather than building a monolithic memory service, Luna could define `IMemoryStorage`, `IEmbeddingProvider`, and `IQueryProcessor` interfaces that compose into a full memory system. +- **SQLite + Vector Extension**: Both OpenClaw and ZeroClaw use SQLite with vector extensions for hybrid search. Luna already references SQLite packages — finishing `SqliteMemoryStore` with this architecture is the natural path. +- **Pluggable Embedding Providers**: Luna should support multiple embedding backends from the start. The factory pattern (`getMemoryEmbeddingProvider(name)`) maps to C# service registration. +- **Batch Processing**: For initial indexing or re-indexing of conversation history, batch embedding helpers prevent rate-limiting issues. +- **Query Preprocessing**: Keyword extraction and scope filtering before search improves relevance. Luna should implement query expansion as a pipeline step before hitting the vector store. + +### Key Difference + +OpenClaw's SDK is a package boundary within a monorepo — it re-exports from the main `src/` tree through barrel files. Luna, as a single compiled application, would implement this as a set of interfaces within a `Memory` namespace rather than a separate package. The architectural principle (composable engines with clear contracts) translates directly to C# DI registration. diff --git a/Documentation/References/OpenClaw/Overview.md b/Documentation/References/OpenClaw/Overview.md new file mode 100644 index 0000000..61d7aeb --- /dev/null +++ b/Documentation/References/OpenClaw/Overview.md @@ -0,0 +1,94 @@ +# OpenClaw + +## Overview +OpenClaw is a mature TypeScript/Node.js AI assistant platform (~342k stars, ~24k commits). Local-first gateway control plane with plugin-SDK architecture. Monorepo with packages. Repo: https://github.com/openclaw/openclaw + +## Architecture +- Local-first WebSocket gateway as central control plane +- Plugin-SDK architecture — features are installable packages, not inline code +- Monorepo: `src/` for core, `packages/` for SDKs + +## Agent Runtime +- Pi agent runtime with RPC mode +- Tool streaming and block streaming +- Multi-agent routing +- Agent compaction for long conversations + +## Providers +- Multiple AI providers via plugin-sdk +- OAuth subscription auth (OpenAI Codex, Claude Code) + +## Channels +24+ messaging platforms via plugin-per-platform pattern with shared registry/helpers: +WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Teams, LINE, Nostr, WeChat, and more. +Each channel plugin: channel-specific auth, message normalization, allowlist-based access control. + +## Memory +- memory-host-sdk package with three engines: + - engine-embeddings (vector embedding computation/storage) + - engine-foundation (core memory primitives) + - engine-storage (pluggable storage backends) +- Pluggable vector DB support for semantic search + +## Tools +Rich tool ecosystem: +- Browser: Managed Chromium via CDP +- Canvas: A2UI visual workspace +- Cron: Scheduled tasks +- Nodes: Device-local (camera, screen, notifications) +- Sessions: Session management tools +- Web Fetch: HTTP with SSRF guards and visibility rules +- PDF, TTS, Image tools + +## Sessions +- JSON-persisted session store +- Pruning, capping, rotation, archiving +- Per-session sandbox policies +- Activation modes, group routing +- Session lifecycle events + +## Security +- DM Pairing: 6-digit codes + per-channel allowlists +- Per-session Sandboxing: Docker/SSH backends +- Tool Allow/Deny Lists +- SSRF Guards on web fetch +- Web Fetch Visibility Rules + +## Skills & Plugins +Full plugin lifecycle: +- Manifest Registry with capability declarations +- Install/enable/disable/uninstall lifecycle +- Workspace Skills via AGENTS.md and SKILL.md conventions +- Bundled plugins + external ClawHub package registry + +## Voice & Apps +- Wake word detection, Talk Mode, TTS (ElevenLabs + system fallback) +- macOS menu bar app, iOS/Android nodes, WebChat browser client + +*** + +## In-Depth Reference Pages + +- [[Session Management]] — SessionEntry type, store maintenance (pruning/capping/rotation), atomic writes, lifecycle events +- [[Plugin Architecture]] — Plugin type system, 40+ provider hooks, tool factories, config schemas, channel handlers +- [[Channel System]] — Plugin-per-platform pattern, shared registry, message normalization, access control +- [[Security]] — DM/group access decisions, pairing, allowlists, per-session sandboxing, SSRF guards +- [[Memory SDK]] — Composable engine architecture (storage, embeddings, QMD), SQLite + sqlite-vec, 6 embedding providers +- [[Compaction Strategy]] — Token-budget gating, staged summarization, quality guards, identifier preservation, session truncation + +*** + +## Relevance to Luna + +### Patterns Worth Adopting +- **Session Management**: Pruning/capping/rotation is much more mature than Luna's basic SessionManager. Configurable max message counts, session lifecycle events, group routing. See [[Session Management]] for details. Link to [[Core]]. +- **Plugin Architecture**: Manifest-based registry with install/enable/disable lifecycle is a good reference for Luna's [[Skills]] module. See [[Plugin Architecture]] for the hook system. +- **Channel Normalization**: Plugin-per-platform with shared registry validates Luna's [[Channels]] design. Key lesson: establish a rich normalized message type before adding the second channel. See [[Channel System]]. +- **Security Layers**: DM pairing and per-session sandboxing are practical patterns Luna should adopt before exposing tool execution. See [[Security]] for the access decision system. +- **Compaction**: Token-budget driven summarization with quality guards and structured output sections. Far more sophisticated than Luna's basic LibrarianAgent compaction. See [[Compaction Strategy]]. + +### Key Differences from Luna +- OpenClaw is a platform for third-party plugin development; Luna is a standalone assistant +- TypeScript vs .NET/C# +- Features are installable packages vs compiled modules +- Mature multi-app distribution (macOS, iOS, Android, WebChat) vs CLI only diff --git a/Documentation/References/OpenClaw/Plugin Architecture.md b/Documentation/References/OpenClaw/Plugin Architecture.md new file mode 100644 index 0000000..4a1d1a0 --- /dev/null +++ b/Documentation/References/OpenClaw/Plugin Architecture.md @@ -0,0 +1,131 @@ +# Plugin Architecture + +OpenClaw employs a multi-tiered plugin architecture designed for high extensibility across model providers, messaging channels, and agent capabilities. The system is built on a massive type system that allows plugins to hook into almost every stage of the AI lifecycle, from initial message receipt to final inference and tool execution. + +*** + +## Plugin Type System + +The core of the architecture is defined in `src/plugins/types.ts`. It provides a unified contract for different plugin flavors: `ProviderPlugin`, `WebSearchProviderPlugin`, `SpeechProviderPlugin`, and the general `OpenClawPluginDefinition`. + +### Provider Plugin Hooks + +The `ProviderPlugin` is the most complex type, featuring over 40 hooks for deep integration with LLM providers. These are categorized into distinct functional areas: + +* **Catalog & Discovery**: Hooks like `catalog` and `augmentModelCatalog` allow plugins to publish model definitions dynamically. +* **Auth & Credentials**: `prepareRuntimeAuth` and `resolveSyntheticAuth` handle the exchange of source credentials for runtime tokens. +* **Model Resolution**: `resolveDynamicModel` and `normalizeResolvedModel` provide last-mile control over how model IDs are mapped to API endpoints. +* **Streaming & Transport**: `createStreamFn` and `wrapStreamFn` allow plugins to replace or wrap the default transport layer with provider-specific logic. +* **Usage & Billing**: `resolveUsageAuth` and `fetchUsageSnapshot` enable integrated quota tracking. + +```typescript +export type ProviderPlugin = { + id: string; + label: string; + auth: ProviderAuthMethod[]; + catalog?: ProviderPluginCatalog; + resolveDynamicModel?: (ctx: ProviderResolveDynamicModelContext) => ProviderRuntimeModel | null | undefined; + prepareRuntimeAuth?: (ctx: ProviderPrepareRuntimeAuthContext) => Promise; + createStreamFn?: (ctx: ProviderCreateStreamFnContext) => StreamFn | null | undefined; + fetchUsageSnapshot?: (ctx: ProviderFetchUsageSnapshotContext) => Promise; + // ... and 30+ more hooks +}; +``` + +*** + +## Tool Factories + +Plugins expose agent-level capabilities through `OpenClawPluginToolFactory`. This pattern allows tools to be instantiated with a trusted execution context that includes workspace paths, session identifiers, and security boundaries. + +```typescript +export type OpenClawPluginToolContext = { + config?: OpenClawConfig; + workspaceDir?: string; + agentId?: string; + sessionId?: string; + deliveryContext?: DeliveryContext; + senderIsOwner?: boolean; +}; + +export type OpenClawPluginToolFactory = ( + ctx: OpenClawPluginToolContext, +) => AnyAgentTool | AnyAgentTool[] | null | undefined; +``` + +*** + +## Config Schema + +Plugins declare their configuration requirements using a Zod-like validation system. The `OpenClawPluginConfigSchema` allows the host to validate plugin settings, generate UI forms, and provide help text without loading the plugin's full implementation. + +```typescript +export type OpenClawPluginConfigSchema = { + safeParse?: (value: unknown) => { + success: boolean; + data?: unknown; + error?: { issues?: Array<{ path: Array; message: string }> }; + }; + uiHints?: Record; + jsonSchema?: Record; +}; +``` + +*** + +## Channel Handlers + +Interactive platform support (Telegram, Discord, Slack) is handled via specialized interactive handlers. These allow plugins to respond to platform-specific events like button clicks or modal submissions through a unified context. + +```typescript +export type PluginInteractiveTelegramHandlerContext = { + channel: "telegram"; + callback: { data: string; namespace: string; payload: string }; + respond: { + reply: (params: { text: string; buttons?: PluginInteractiveButtons }) => Promise; + editMessage: (params: { text: string; buttons?: PluginInteractiveButtons }) => Promise; + }; +}; +``` + +*** + +## Conversation Bindings + +Plugins can request "Conversation Bindings" to take over the message flow for a specific thread or user. This is used for interactive wizards or stateful interactions that bypass the general LLM dispatcher. + +* `requestConversationBinding`: Attaches a plugin to the current conversation. +* `detachConversationBinding`: Releases the conversation back to the general agent. +* `getCurrentConversationBinding`: Checks if the conversation is currently owned by a plugin. + +*** + +## Plugin Lifecycle + +The lifecycle is managed through several stages, primarily defined in the `OpenClawPluginApi` provided during registration: + +1. **Discovery**: Plugins are found in `bundled`, `global`, or `workspace` directories. +2. **Registration**: `register(api)` is called. The plugin registers its tools, hooks, and services. +3. **Activation**: `activate(api)` is called when the plugin is enabled and ready for service. +4. **Runtime**: The plugin responds to lifecycle hooks such as `before_agent_start`, `llm_input`, and `agent_end`. +5. **Uninstallation**: Managed via the `ClawHub` registry or local file deletion. + +*** + +## Specialized Plugin Types + +### Web Search Providers +`WebSearchProviderPlugin` defines how the agent interacts with search engines. It requires specific credential resolution logic and a `createTool` factory that returns a standardized search tool definition. + +### Speech Providers +`SpeechProviderPlugin` handles text-to-speech (TTS) capabilities. It includes hooks for voice listing, directive parsing (e.g., for custom SSML or tokens), and synthesis for both standard and telephony audio formats. + +*** + +## Relevance to Luna + +While Luna does not require the full overhead of OpenClaw's provider ecosystem, it can adopt several key patterns: + +* **Manifest-Based Registration**: Luna could use a simplified version of `OpenClawPluginDefinition` to allow for [[Skills]] that declare their dependencies and config schemas upfront. +* **Hook Interceptors**: Adopting the `before_prompt_build` and `llm_output` hook patterns would allow Luna's [[Core]] to support middleware for logging, safety filtering, or memory injection. +* **Trusted Contexts**: Passing a `ToolContext` similar to OpenClaw's would ensure that Luna's tools have consistent access to session and workspace state without relying on global variables. diff --git a/Documentation/References/OpenClaw/Security.md b/Documentation/References/OpenClaw/Security.md new file mode 100644 index 0000000..0b5a7d9 --- /dev/null +++ b/Documentation/References/OpenClaw/Security.md @@ -0,0 +1,151 @@ +# Security + +OpenClaw implements a multi-layered security model designed to isolate tool execution and strictly control access via Direct Messages (DMs) and Groups. This model ensures that only authorized users can trigger sensitive operations while protecting the host system from potentially malicious tool output or SSRF attacks. + +*** + +## DM/Group Access Decision System + +The core logic for determining if a message should be processed resides in `src/security/dm-policy-shared.ts`. The system evaluates the `dmPolicy` and `groupPolicy` against the sender's identity. + +### Access Decision Types + +The `DmGroupAccessDecision` type defines the three possible outcomes of an access check: + +```typescript +export type DmGroupAccessDecision = "allow" | "block" | "pairing"; +``` + +### Access Reason Codes + +The system provides granular reason codes for every decision, enabling precise logging and user feedback: + +```typescript +export const DM_GROUP_ACCESS_REASON = { + GROUP_POLICY_ALLOWED: "group_policy_allowed", + GROUP_POLICY_DISABLED: "group_policy_disabled", + GROUP_POLICY_EMPTY_ALLOWLIST: "group_policy_empty_allowlist", + GROUP_POLICY_NOT_ALLOWLISTED: "group_policy_not_allowlisted", + DM_POLICY_OPEN: "dm_policy_open", + DM_POLICY_DISABLED: "dm_policy_disabled", + DM_POLICY_ALLOWLISTED: "dm_policy_allowlisted", + DM_POLICY_PAIRING_REQUIRED: "dm_policy_pairing_required", + DM_POLICY_NOT_ALLOWLISTED: "dm_policy_not_allowlisted", +} as const; +``` + +### Resolution Logic + +The `resolveDmGroupAccessDecision()` function implements the policy evaluation: + +```typescript +export function resolveDmGroupAccessDecision(params: { + isGroup: boolean; + dmPolicy?: string | null; + groupPolicy?: string | null; + effectiveAllowFrom: Array; + effectiveGroupAllowFrom: Array; + isSenderAllowed: (allowFrom: string[]) => boolean; +}) { + const dmPolicy = params.dmPolicy ?? "pairing"; + const groupPolicy = params.groupPolicy ?? "allowlist"; + + if (params.isGroup) { + // Group logic: evaluate against groupPolicy (open/disabled/allowlist) + // Returns 'allow' if policy is open or user is in allowlist + // Returns 'block' if policy is disabled or user not in allowlist + } else { + // DM logic: evaluate against dmPolicy + if (dmPolicy === "disabled") return { decision: "block", ... }; + if (dmPolicy === "open") return { decision: "allow", ... }; + + if (params.isSenderAllowed(effectiveAllowFrom)) { + return { decision: "allow", reasonCode: "dm_policy_allowlisted" }; + } + + if (dmPolicy === "pairing") { + return { decision: "pairing", reasonCode: "dm_policy_pairing_required" }; + } + + return { decision: "block", reasonCode: "dm_policy_not_allowlisted" }; + } +} +``` + +*** + +## DM Pairing + +The Pairing system allows users to prove their identity when `dmPolicy` is set to `pairing`. + +1. **Initiation**: When an unknown user messages the bot, the system returns a `pairing` decision. +2. **Challenge**: The bot provides a 6-digit pairing code (often via console or a side-channel). +3. **Verification**: Once the user provides the correct code, their unique account ID is added to the **Store-backed Allowlist**. +4. **Persistence**: Subsequent messages from this account ID are automatically allowed as they now appear in the resolved allowlist. + +*** + +## Access Policies + +Policies are configured per-channel and define the default security posture. + +### dmPolicy Options +- `disabled`: The bot will not respond to any DMs. +- `open`: Anyone can message the bot (high risk). +- `pairing`: Users must undergo the 6-digit pairing flow to gain access. +- `allowlist`: Only users explicitly listed in the configuration file can message the bot. + +### groupPolicy Options +- `open`: Any user in the group can trigger the bot. +- `disabled`: The bot is effectively silent in group settings. +- `allowlist`: Only specific users within the group can trigger commands. + +*** + +## Allowlist Management + +OpenClaw uses a hybrid allowlist system: +- **Config Allowlist**: Static entries defined in the `config.yaml` or environment variables. +- **Store Allowlist**: Dynamic entries stored in a local database (e.g., `pairing-store.js`), primarily populated by successful pairings. + +The `resolveEffectiveAllowFromLists()` function merges these sources, ensuring that per-channel scoping is respected. Wildcards (`*`) can be used in the config to grant broad access, though this is discouraged for production environments. + +*** + +## Per-Session Sandboxing + +To prevent tool execution from compromising the host, OpenClaw supports isolated backends: +- **Docker Backend**: Each session spawns a transient container. Tools execute inside this container with limited CPU, memory, and no access to the host filesystem. +- **SSH Backend**: Tools are executed on a remote machine or VM, isolating the main bot process from the execution environment. + +*** + +## Tool Allow/Deny Lists + +Security is further tightened by restricting which tools are available to which users or channels. +- **Global Denylist**: Prevents high-risk tools (like `shell_execute`) from being loaded. +- **Per-User Permissions**: Can restrict specific tools to "Admin" users only. + +*** + +## SSRF Guards + +The `web_fetch` tool and other network-touching skills include SSRF (Server-Side Request Forgery) protection. This includes: +- **IP Blocklists**: Preventing requests to `localhost`, `127.0.0.1`, and internal private IP ranges (10.0.0.0/8, etc.). +- **Protocol Restriction**: Only allowing `http` and `https`. + +*** + +## Relevance to Luna + +Luna currently lacks a security layer, which is a critical blocker for exposing tool execution to external interfaces. + +### Priority Patterns to Adopt: +1. **DM Pairing**: Implement the 6-digit pairing flow before allowing any tool interaction in DMs. +2. **Access Decision Logic**: Port the `resolveDmGroupAccessDecision` pattern to [[Channels]] to centralize authorization. +3. **SSRF Guards**: Ensure any "web search" or "fetch" skills implemented in [[Skills]] cannot hit internal Luna metadata services. +4. **Docker Isolation**: Before enabling `shell_execute`, Luna must implement the Docker-based sandboxing seen in OpenClaw. + +*** + +Cross-refs: [[Core]], [[Skills]], [[Channels]] diff --git a/Documentation/References/OpenClaw/Session Management.md b/Documentation/References/OpenClaw/Session Management.md new file mode 100644 index 0000000..174f674 --- /dev/null +++ b/Documentation/References/OpenClaw/Session Management.md @@ -0,0 +1,144 @@ +# Session Management + +OpenClaw employs a centralized, file-based session management system that handles persistence, lifecycle events, and automated store maintenance. Unlike simple memory-only stores, this system is designed for high-concurrency environments with atomic write guarantees and strict disk budget enforcement. + +*** + +## SessionEntry type + +The `SessionEntry` structure in `src/config/sessions/types.ts` is the core data model, containing nearly 80 fields that track everything from model overrides to granular token usage and skill snapshots. + +```typescript +export type SessionEntry = { + sessionId: string; + updatedAt: number; + sessionFile?: string; + + // Model and Provider Overrides + modelProvider?: string; + model?: string; + providerOverride?: string; + modelOverride?: string; + thinkingLevel?: string; + + // Token Tracking and Context + inputTokens?: number; + outputTokens?: number; + totalTokens?: number; + totalTokensFresh?: boolean; + compactionCount?: number; + + // Delivery and Origin + deliveryContext?: DeliveryContext; + lastChannel?: SessionChannelId; + origin?: SessionOrigin; + + // Meta and Snapshots + skillsSnapshot?: SessionSkillSnapshot; + systemPromptReport?: SessionSystemPromptReport; + acp?: SessionAcpMeta; // Agent Control Plane metadata + queueMode?: "steer" | "followup" | "collect" | "queue" | "interrupt"; +}; +``` + +Key features of the type system: +* **Model Overrides**: Allows per-session binding to specific models or providers, bypassing global defaults. +* **Token Intelligence**: Tracks `totalTokensFresh` to determine if usage displays need a refresh. +* **ACP Meta**: Preserves state for the Agent Control Plane, ensuring persistent agent behaviors across turns. +* **Skill Snapshots**: Captures the state of available [[Skills]] at the time of the session turn. + +*** + +## Store Maintenance + +Automated maintenance is handled in `src/config/sessions/store-maintenance.ts` to prevent unbounded growth of the session file and ensure performance. + +### Pruning and Capping +* **`pruneStaleEntries()`**: Removes sessions older than a configured threshold (default: 30 days). It iterates through the store and deletes entries where `updatedAt` is before the cutoff. +* **`capEntryCount()`**: Enforces a maximum number of sessions (default: 500). It sorts sessions by `updatedAt` descending and keeps only the most recent $N$ entries. + +### File Rotation +The `rotateSessionFile()` function monitors the `sessions.json` file size. If it exceeds the limit (default: 10MB), the system: +1. Renames the current file to `sessions.json.bak.{timestamp}`. +2. Maintains a maximum of 3 rotation backups, unlinking older ones. + +### Maintenance Configuration +The `resolveMaintenanceConfig()` function aggregates parameters from [[Configuration]]: +* `pruneAfterMs`: Max age before eviction. +* `maxEntries`: Hard limit on session count. +* `rotateBytes`: File size trigger for rotation. +* `maxDiskBytes`: Total disk budget for session transcripts. + +*** + +## Session Store + +The `SessionStore` in `src/config/sessions/store.ts` manages the I/O layer with a focus on reliability and cross-platform compatibility. + +### Key Features +* **Atomic Writes**: Uses `writeTextAtomic` to prevent file corruption during crashes. +* **Write Locks**: Implements a `withSessionStoreLock` mechanism using a file-based lock to prevent race conditions between concurrent agent turns. +* **Normalization**: Session keys are case-insensitive and trimmed via `normalizeStoreSessionKey()`. Legacy keys are automatically migrated to the normalized format on load. +* **Windows Retry Semantics**: Includes specialized retry logic for Windows to handle transient file locks during the "truncate and write" phase. +* **ACP Metadata Preservation**: Specifically protects `acp` metadata during updates, ensuring agent state isn't lost if a partial patch is applied. + +```typescript +export async function updateSessionStore( + storePath: string, + mutator: (store: Record) => Promise | T, + opts?: SaveSessionStoreOptions, +): Promise { + return await withSessionStoreLock(storePath, async () => { + const store = loadSessionStore(storePath, { skipCache: true }); + const previousAcpByKey = collectAcpMetadataSnapshot(store); + const result = await mutator(store); + preserveExistingAcpMetadata({ + previousAcpByKey, + nextStore: store, + }); + await saveSessionStoreUnlocked(storePath, store, opts); + return result; + }); +} +``` + +*** + +## Session Lifecycle Events + +A lightweight pub/sub system in `src/sessions/session-lifecycle-events.ts` allows other subsystems to react to session changes. + +```typescript +export type SessionLifecycleEvent = { + sessionKey: string; + reason: string; + parentSessionKey?: string; + label?: string; +}; + +export function onSessionLifecycleEvent(listener: SessionLifecycleListener): () => void { + SESSION_LIFECYCLE_LISTENERS.add(listener); + return () => { SESSION_LIFECYCLE_LISTENERS.delete(listener); }; +} + +export function emitSessionLifecycleEvent(event: SessionLifecycleEvent): void { + for (const listener of SESSION_LIFECYCLE_LISTENERS) { + listener(event); + } +} +``` + +This system is used to trigger [[Memory]] indexing, update [[Channels]] status, or log audit trails when sessions are created or deleted. + +*** + +## Relevance to Luna + +Luna's current `SessionManager` is a basic dictionary-backed store that lacks persistence and maintenance. To reach parity with OpenClaw, Luna should adopt several patterns: + +1. **Atomic Persistence**: Implement a background saver for [[Core]] sessions that uses atomic file swaps to prevent data loss. +2. **Maintenance Tasks**: Add a background service to prune old sessions and cap the total count to prevent memory leaks in the .NET runtime. +3. **Locking**: Use a `SemaphoreSlim` or file-system lock for session updates to support concurrent requests from different [[Channels]]. +4. **Detailed Metadata**: Expand Luna's session objects to include token tracking and model overrides, allowing for better cost management and user customization. + +Refer to [[Core]] for the current implementation status of Luna's session handling. diff --git a/Documentation/References/ZeroClaw/Agent Loop & Tools.md b/Documentation/References/ZeroClaw/Agent Loop & Tools.md new file mode 100644 index 0000000..e0cc27d --- /dev/null +++ b/Documentation/References/ZeroClaw/Agent Loop & Tools.md @@ -0,0 +1,152 @@ +# Agent Loop & Tools + +The ZeroClaw agent architecture is built around a recursive execution loop that allows an LLM to invoke external capabilities, observe their results, and refine its response until a final answer is reached. + +*** + +## Tool Trait + +The `Tool` trait in `tools/traits.rs` defines the interface for any capability exposed to the agent. It provides both the metadata needed for LLM registration and the execution logic for the tool itself. + +```rust +/// Result of a tool execution +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct ToolResult { + pub success: bool, + pub output: String, + pub error: Option, +} + +/// Description of a tool for the LLM +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct ToolSpec { + pub name: String, + pub description: String, + pub parameters: serde_json::Value, +} + +/// Core tool trait — implement for any capability +#[async_trait] +pub trait Tool: Send + Sync { + /// Tool name (used in LLM function calling) + fn name(&self) -> &str; + + /// Human-readable description + fn description(&self) -> &str; + + /// JSON schema for parameters + fn parameters_schema(&self) -> serde_json::Value; + + /// Execute the tool with given arguments + async fn execute(&self, args: serde_json::Value) -> anyhow::Result; + + /// Get the full spec for LLM registration + fn spec(&self) -> ToolSpec { + ToolSpec { + name: self.name().to_string(), + description: self.description().to_string(), + parameters: self.parameters_schema(), + } + } +} +``` + +*** + +## Agent Loop + +The core logic resides in `agent/loop_.rs` within `run_tool_call_loop`. This function orchestrates the interaction between the provider and the tool registry. + +The process follows a repeating cycle: +1. Send the current conversation history and tool definitions to the LLM. +2. Receive a response. +3. Parse the response for tool calls (native or prompt-guided). +4. If tool calls exist, execute them and append the results to the history, then repeat. +5. If no tool calls exist, return the final text response. + +### Iteration Safety +To prevent infinite loops or runaway execution, the system enforces a strict iteration cap: +* `DEFAULT_MAX_TOOL_ITERATIONS` = 10 + +### Streaming and Progress +Streaming responses are handled by accumulating chunks before relaying them to the draft channel to minimize noise: +* `STREAM_CHUNK_MIN_CHARS` = 80 +* `PROGRESS_MIN_INTERVAL_MS` = 500 (minimum time between progress updates) +* `DRAFT_CLEAR_SENTINEL` = `\x00CLEAR\x00` (used to clear progress lines before showing the final answer) + +*** + +## Auto-Compaction + +Conversation history is managed through an auto-compaction mechanism to stay within context window limits while preserving essential information. + +* **Threshold**: Triggered when non-system message count exceeds 50 (`DEFAULT_MAX_HISTORY_MESSAGES`). +* **Retention**: Keeps the 20 most recent messages (`COMPACTION_KEEP_RECENT_MESSAGES`). +* **Summarization**: Older messages are summarized by the LLM. +* **Caps**: Summarization source is capped at 12,000 characters; the resulting summary is capped at 2,000 characters. + +*** + +## Security & Pattern Matching + +### Credential Scrubbing +ZeroClaw proactively redacts sensitive information from tool outputs before they are fed back into the LLM history. + +```rust +static SENSITIVE_KV_REGEX: LazyLock = LazyLock::new(|| { + Regex::new(r#"(?i)(token|api[_-]?key|password|secret|user[_-]?key|bearer|credential)["']?\s*[:=]\s*(?:"([^"]{8,})"|'([^']{8,})'|([a-zA-Z0-9_\-\.]{8,}))"#).unwrap() +}); +``` +The scrubbing logic preserves the first 4 characters for context then appends `*[REDACTED]`. + +### Autosave +Meaningful exchanges are automatically persisted to memory based on message length: +* `AUTOSAVE_MIN_MESSAGE_CHARS` = 20 + +*** + +## Tool Serialization & Formats + +Tools are converted into the appropriate format for the specific LLM provider. + +### tools_to_openai_format() +This function serializes the tool registry into the standard OpenAI function-calling schema used by many providers. + +```rust +fn tools_to_openai_format(tools_registry: &[Box]) -> Vec { + tools_registry + .iter() + .map(|tool| { + serde_json::json!({ + "type": "function", + "function": { + "name": tool.name(), + "description": tool.description(), + "parameters": tool.parameters_schema() + } + }) + }) + .collect() +} +``` + +### Parsing Priority +The system handles multiple response formats to support different providers: +1. Native structured JSON (OpenAI style) +2. XML tags (``, ``) +3. Markdown code blocks with `tool_call` identifiers +4. Provider-specific shortened formats (GLM, etc.) + +*** + +## Relevance to Luna + +Luna currently operates as a pure chat relay, streaming LLM responses without any capability to interact with the system or external APIs. This lack of a tool execution layer is the primary bottleneck preventing Luna from becoming an autonomous assistant. + +### Bridging the Gap +Implementing the agent loop pattern in Luna would involve: +* Defining an `ITool` interface in C# that mirrors the Rust `Tool` trait. +* Transitioning from a single request-response model to a recursive loop in the [[Core]] engine. +* Integrating the tool loop with [[Skills]] to allow dynamic capability discovery. + +The implementation of this protocol will turn Luna from a passive interface into an active participant capable of executing commands and managing its own [[Memory]]. diff --git a/Documentation/References/ZeroClaw/Channel Messages.md b/Documentation/References/ZeroClaw/Channel Messages.md new file mode 100644 index 0000000..3f3c920 --- /dev/null +++ b/Documentation/References/ZeroClaw/Channel Messages.md @@ -0,0 +1,132 @@ +# Channel Messages + +The ZeroClaw messaging protocol is built around the `Channel` trait and a unified message format. This allows the system to treat disparate platforms—from Discord to Slack to SMS—as a consistent stream of `ChannelMessage` objects. + +*** + +## Channel Trait + +The `Channel` trait is the core abstraction for all platform implementations. It defines how the system interacts with a specific messaging service. + +```rust +#[async_trait] +pub trait Channel: Send + Sync { + /// Human-readable channel name + fn name(&self) -> &str; + + /// Send a message through this channel + async fn send(&self, message: &SendMessage) -> anyhow::Result<()>; + + /// Start listening for incoming messages (long-running) + async fn listen(&self, tx: tokio::sync::mpsc::Sender) -> anyhow::Result<()>; + + /// Check if channel is healthy + async fn health_check(&self) -> bool { + true + } + + /// Signal that the bot is processing a response (e.g. "typing" indicator). + async fn start_typing(&self, _recipient: &str) -> anyhow::Result<()> { + Ok(()) + } + + /// Stop any active typing indicator. + async fn stop_typing(&self, _recipient: &str) -> anyhow::Result<()> { + Ok(()) + } + + // ... draft and reaction methods +} +``` + +*** + +## Draft Update Protocol + +ZeroClaw implements a progressive "Draft" protocol designed for streaming LLM responses. Instead of sending multiple message fragments, platforms that support editing (Telegram, Discord, Slack) can update a single message in place as the response is generated. + +### Protocol Methods + +* `supports_draft_updates()`: Returns true if the platform allows message editing. +* `send_draft(&SendMessage)`: Sends the initial message and returns a platform-specific `message_id`. +* `update_draft(recipient, message_id, text)`: Appends or replaces the content of the existing message. +* `finalize_draft(recipient, message_id, text)`: Performs a final update, often used to apply markdown formatting or remove "typing" statuses. +* `cancel_draft(recipient, message_id)`: Deletes the draft if the generation is aborted. + +This protocol significantly reduces notification noise on user devices and provides a much smoother "typing" experience during long generations. + +*** + +## Reactions and Pinning + +ZeroClaw supports standard interactive elements across most platforms. + +### Reactions +* `add_reaction(channel_id, message_id, emoji)`: Adds a Unicode emoji reaction. +* `remove_reaction(channel_id, message_id, emoji)`: Removes a previously added reaction. + +### Pinning +* `pin_message(channel_id, message_id)`: Pins a message to the channel. +* `unpin_message(channel_id, message_id)`: Unpins a message. + +*** + +## ChannelMessage Struct + +The `ChannelMessage` is the Data Transfer Object (DTO) for all incoming and outgoing communication. + +```rust +pub struct ChannelMessage { + pub id: String, + pub sender: String, + pub reply_target: String, + pub content: String, + pub channel: String, + pub timestamp: u64, + /// Platform thread identifier (e.g. Slack `ts`, Discord thread ID). + /// When set, replies should be posted as threaded responses. + pub thread_ts: Option, +} +``` + +*** + +## SendMessage Builder + +Sending messages uses a builder pattern to handle optional fields like subjects and threading context. + +```rust +pub struct SendMessage { + pub content: String, + pub recipient: String, + pub subject: Option, + pub thread_ts: Option, +} + +impl SendMessage { + pub fn new(content: impl Into, recipient: impl Into) -> Self; + pub fn with_subject(content: impl Into, recipient: impl Into, subject: impl Into) -> Self; + pub fn in_thread(mut self, thread_ts: Option) -> Self; +} +``` + +*** + +## Platform Implementations + +ZeroClaw includes implementations for 26 platforms, including: +* Slack, Discord, Telegram, Microsoft Teams +* WhatsApp (Twilio/Meta), Signal, Matrix +* Twilio SMS, SendGrid Email, Postmark +* IRC, XMPP, Mattermost, Rocket.Chat +* Custom Webhooks and WebSocket adapters + +*** + +## Relevance to Luna + +Luna should adopt the `ChannelMessage` structure as its baseline message DTO in [[Core]]. + +The **Draft Update Protocol** is particularly critical for Luna's SignalR implementation. Rather than streaming raw text chunks to the frontend and letting the client manage the state, the SignalR hub can follow the `send_draft` / `update_draft` / `finalize_draft` flow. This ensures consistency between web clients and external messaging channels documented in [[Channels]]. + +The `SendMessage` builder pattern provides a clean API for Luna services to dispatch notifications without manually constructing complex JSON payloads. diff --git a/Documentation/References/ZeroClaw/Compaction Strategy.md b/Documentation/References/ZeroClaw/Compaction Strategy.md new file mode 100644 index 0000000..c94cd50 --- /dev/null +++ b/Documentation/References/ZeroClaw/Compaction Strategy.md @@ -0,0 +1,213 @@ +# Compaction Strategy + +ZeroClaw employs a dual-path conversation compaction system to manage long-running sessions. This strategy ensures the LLM maintains relevant context while staying within performance and token limits. Unlike basic history trimming, ZeroClaw uses proactive summarization to preserve state and reactive truncation to recover from context overflows. + +*** + +## Constants + +The following constants are defined in `agent/loop_.rs` and govern the default behavior of the compaction engine: + +```rust +/// Default trigger for auto-compaction when non-system message count exceeds this threshold. +const DEFAULT_MAX_HISTORY_MESSAGES: usize = 50; + +/// Keep this many most-recent non-system messages after compaction. +const COMPACTION_KEEP_RECENT_MESSAGES: usize = 20; + +/// Safety cap for compaction source transcript passed to the summarizer. +const COMPACTION_MAX_SOURCE_CHARS: usize = 12_000; + +/// Max characters retained in stored compaction summary. +const COMPACTION_MAX_SUMMARY_CHARS: usize = 2_000; +``` + +*** + +## Two Compaction Triggers + +ZeroClaw implements both agent-side proactive compaction and channel-side reactive recovery. + +### 1. Proactive (Agent-Side) + +The `auto_compact_history()` function in `agent/loop_.rs` is called after each turn in the interactive agent loop. It operates based on message count thresholds rather than token counts. + +**Process:** +1. **Threshold Check**: It counts non-system messages. If the count is less than or equal to `max_history` (default 50), it exits. +2. **Preservation**: It identifies the system prompt (the first message if the role is "system") to ensure it is never compacted. +3. **Range Calculation**: It determines how many messages to keep (`COMPACTION_KEEP_RECENT_MESSAGES`) and how many to compact. +4. **Transcript Generation**: Older messages are formatted into a plain-text transcript via `build_compaction_transcript()`. +5. **LLM Summarization**: The transcript is sent to a summarizer model with a temperature of 0.2. +6. **Injection**: The resulting summary is inserted as an assistant message prefixed with `[Compaction summary]`. +7. **Safety Fallback**: If summarization fails, it falls back to deterministic truncation via `truncate_with_ellipsis()`. +8. **Hard Trim**: `trim_history()` runs afterward to ensure the history length is strictly enforced. + +### 2. Reactive (Channel-Side) + +The `compact_sender_history()` function in `channels/mod.rs` provides a fallback mechanism when the LLM returns a context-window overflow error. + +**Process:** +1. **Error Detection**: `is_context_window_overflow_error()` checks for 8 keyword patterns in the error string: + - "exceeds the context window" + - "context window of this model" + - "maximum context length" + - "context length exceeded" + - "too many tokens" + - "token limit exceeded" + - "prompt is too long" + - "input is too long" +2. **Aggressive Truncation**: It keeps only the last `CHANNEL_HISTORY_COMPACT_KEEP_MESSAGES` messages. +3. **Content Cap**: Each retained message is truncated to `CHANNEL_HISTORY_COMPACT_CONTENT_CHARS`. +4. **User Recovery**: The system typically asks the user to resend their last message after the history has been thinned. + +*** + +## Summarization Prompt + +The summarizer uses a specific system and user prompt pair to ensure the output is useful for future context. + +**System Prompt:** +> You are a conversation compaction engine. Summarize older chat history into concise context for future turns. Preserve: user preferences, commitments, decisions, unresolved tasks, key facts. Omit: filler, repeated chit-chat, verbose tool logs. Output plain text bullet points only. + +**User Prompt:** +> Summarize the following conversation history for context preservation. Keep it short (max 12 bullet points). +> +> {transcript} + +**Temperature:** 0.2 + +*** + +## Helper Functions + +### trim_history() + +Located in `agent/loop_.rs`, this function performs a hard drain on the oldest non-system messages. + +```rust +fn trim_history(history: &mut Vec, max_history: usize) { + // Nothing to trim if within limit + let has_system = history.first().map_or(false, |m| m.role == "system"); + let non_system_count = if has_system { + history.len() - 1 + } else { + history.len() + }; + + if non_system_count <= max_history { + return; + } + + let start = if has_system { 1 } else { 0 }; + let to_remove = non_system_count - max_history; + history.drain(start..start + to_remove); +} +``` + +### build_compaction_transcript() + +Formats the range of messages targeted for compaction into a single string for the summarizer. + +```rust +fn build_compaction_transcript(messages: &[ChatMessage]) -> String { + let mut transcript = String::new(); + for msg in messages { + let role = msg.role.to_uppercase(); + let _ = writeln!(transcript, "{role}: {}", msg.content.trim()); + } + + if transcript.chars().count() > COMPACTION_MAX_SOURCE_CHARS { + truncate_with_ellipsis(&transcript, COMPACTION_MAX_SOURCE_CHARS) + } else { + transcript + } +} +``` + +### apply_compaction_summary() + +Splices the generated summary into the conversation history, replacing the original messages. + +```rust +fn apply_compaction_summary( + history: &mut Vec, + start: usize, + compact_end: usize, + summary: &str, +) { + let summary_msg = ChatMessage::assistant(format!("[Compaction summary]\n{}", summary.trim())); + history.splice(start..compact_end, std::iter::once(summary_msg)); +} +``` + +### Agent::trim_history() + +The high-level implementation in `agent/agent.rs` handles the separation and reassembly of system messages during a trim. + +```rust +fn trim_history(&mut self) { + let max = self.config.max_history_messages; + if self.history.len() <= max { + return; + } + + let mut system_messages = Vec::new(); + let mut other_messages = Vec::new(); + + for msg in self.history.drain(..) { + match &msg { + ConversationMessage::Chat(chat) if chat.role == "system" => { + system_messages.push(msg); + } + _ => other_messages.push(msg), + } + } + + if other_messages.len() > max { + let drop_count = other_messages.len() - max; + other_messages.drain(0..drop_count); + } + + self.history = system_messages; + self.history.extend(other_messages); +} +``` + +*** + +## Injection Format + +When compaction occurs, the summary is injected back into the history as a single assistant message. This ensures that the model sees the previous context as its own earlier summary of events. + +**Format:** +```text +assistant: [Compaction summary] +- Bullet point 1 +- Bullet point 2 +... +``` + +The summary replaces the exact range of messages that were sent to the summarizer, maintaining chronological integrity between the system prompt and the recent "live" messages. + +*** + +## Configuration + +The compaction behavior is influenced by the following configuration settings: + +* `config.agent.max_history_messages`: The primary threshold (default 50). +* `compact_context`: A boolean flag to enable or disable the summarization logic. +* Note: Internal constants like `COMPACTION_KEEP_RECENT_MESSAGES` are currently hardcoded in `loop_.rs`. + +*** + +## Relevance to Luna + +The ZeroClaw compaction strategy provides a significant upgrade over the basic LibrarianAgent compaction currently used in Luna. Implementing this approach in Luna would address several limitations: + +* **Dual-Path Robustness**: Combining proactive message-count triggers with reactive overflow recovery ensures the agent never hits an unrecoverable "context too long" state. +* **Structured Context**: Using a specific summarization prompt preserves critical state (decisions, preferences) that is often lost in simple truncation. +* **Identifiable Injection**: The `[Compaction summary]` prefix allows the model (and debugging tools) to distinguish between raw history and summarized context. +* **Threshold Management**: Moving toward the ZeroClaw constants would provide more predictable behavior in high-volume tool-call loops. + +The summarization prompt text and the `apply_compaction_summary` pattern are directly compatible with Luna's [[Core]] architecture. diff --git a/Documentation/References/ZeroClaw/Configuration.md b/Documentation/References/ZeroClaw/Configuration.md new file mode 100644 index 0000000..906635a --- /dev/null +++ b/Documentation/References/ZeroClaw/Configuration.md @@ -0,0 +1,137 @@ +# Configuration + +ZeroClaw utilizes a TOML-based configuration system designed for modularity, security, and extensibility. The configuration is primarily managed through `config.toml`, which is loaded from the workspace directory or a fallback legacy location. + +*** + +## Config Struct + +The core of the configuration system is defined in `config/schema.rs` via the `Config` struct. It contains over 30 sections, each governing a specific subsystem. + +### Global Settings +* `workspace_dir`: The root directory for ZeroClaw data (computed at runtime). +* `config_path`: The path to the active `config.toml`. +* `api_key`: Global API key for the default provider. +* `api_url`: Base URL override for provider APIs. +* `default_provider`: The primary provider ID (e.g., "anthropic", "ollama"). +* `default_model`: The default model used for queries. +* `default_temperature`: Model temperature (0.0 to 2.0, default 0.7). + +### Subsystem Sections +* `observability`: Tracing and metrics configuration. +* `autonomy`: Security policies and autonomy levels. +* `security`: Secret management and sandbox settings. +* `runtime`: Native vs Docker execution modes. +* `reliability`: Retry logic and fallback providers. +* `scheduler`: Periodic task execution settings. +* `agent`: Orchestration parameters (history size, tool iterations). +* `skills`: Skill loading and prompt injection modes. +* `model_routes`: Routing specific hints to provider/model pairs. +* `embedding_routes`: Routing for vector embedding models. +* `channels_config`: Configuration for Telegram, Discord, Slack, etc. +* `memory`: Backend settings for SQLite or vector storage. +* `storage`: Persistent file storage provider configuration. +* `secrets`: Encryption settings for credentials. +* `browser`: Browser automation and "computer-use" sidecar. +* `identity`: AIEOS or OpenClaw format identity documents. +* `cost`: Budget enforcement and price tracking. +* `hardware`: Physical world interaction (serial/probe) settings. +* `hooks`: Lifecycle and built-in hook toggles. + +*** + +## ModelProviderConfig + +ZeroClaw supports multiple provider profiles via the `model_providers` HashMap. + +```rust +pub struct ModelProviderConfig { + pub name: Option, + pub base_url: Option, + pub wire_api: Option, + pub requires_openai_auth: bool, + pub azure_openai_resource: Option, + pub azure_openai_deployment: Option, + pub azure_openai_api_version: Option, +} +``` + +This allows for configuring multiple instances of the same provider (e.g., local Ollama vs. remote Ollama) or complex Azure OpenAI deployments with distinct resource names and versions. + +*** + +## DelegateAgentConfig + +Sub-agents used by the `delegate` tool are configured separately to allow for specialized behavior. + +```rust +pub struct DelegateAgentConfig { + pub provider: String, + pub model: String, + pub system_prompt: Option, + pub api_key: Option, + pub temperature: Option, + pub max_depth: u32, + pub agentic: bool, + pub allowed_tools: Vec, + pub max_iterations: usize, +} +``` + +Sub-agents can be limited to specific toolsets and have a `max_depth` to prevent infinite delegation loops. + +*** + +## TOML Structure + +Example `config.toml` demonstrating provider setup and security routing: + +```toml +default_provider = "anthropic" +default_model = "claude-3-5-sonnet" + +[model_providers.ollama_local] +name = "ollama" +base_url = "http://localhost:11434" + +[[model_routes]] +hint = "fast" +provider = "ollama_local" +model = "llama3" + +[security] +encrypt = true + +[autonomy] +level = "high" +``` + +*** + +## Hot-Reload + +ZeroClaw supports hot-reloading for specific runtime fields without requiring a full service restart. + +### Supported Fields +* `api_key` / `api_url` +* `default_provider` +* `default_model` +* `default_temperature` +* `reliability` settings + +### Mechanism +The system utilizes a file watcher (via `config_file_stamp`) that monitors the `config.toml` modification time. When a change is detected, the `maybe_apply_runtime_config_update` function reloads the file, decrypts any secrets using the `SecretStore`, and updates the runtime provider cache. + +*** + +## Relevance to Luna + +ZeroClaw's configuration architecture serves as the target state for [[Configuration]] in Luna. + +* **Subsystem Isolation**: Luna plans to migrate from `appsettings.json` to a per-subsystem TOML structure to improve modularity, similar to ZeroClaw's section pattern. +* **Security First**: The pattern of separating `autonomy` and `security` configs is a requirement for Luna's [[Core]]. +* **Hot-Reload**: ZeroClaw's implementation of lightweight file watching for key LLM parameters is a "nice-to-have" feature Luna aims to adopt during the migration. + +*** + +[[Configuration]] | [[Core]] diff --git a/Documentation/References/ZeroClaw/Memory.md b/Documentation/References/ZeroClaw/Memory.md new file mode 100644 index 0000000..6cbbf1e --- /dev/null +++ b/Documentation/References/ZeroClaw/Memory.md @@ -0,0 +1,187 @@ +# Memory + +ZeroClaw implements a hybrid memory system that combines traditional keyword search with modern vector similarity. This approach ensures that exact matches (like function names or specific terminology) and semantic matches (concepts and related ideas) are both discoverable. + +*** + +## Memory Trait + +The foundation of the memory system is the `Memory` trait. Any backend implementation must satisfy this interface to be used by the system. + +```rust +pub struct MemoryEntry { + pub id: String, + pub key: String, + pub content: String, + pub category: MemoryCategory, + pub timestamp: String, + pub session_id: Option, + pub score: Option, +} + +pub enum MemoryCategory { + Core, + Daily, + Conversation, + Custom(String), +} + +#[async_trait] +pub trait Memory: Send + Sync { + fn name(&self) -> &str; + + async fn store( + &self, + key: &str, + content: &str, + category: MemoryCategory, + session_id: Option<&str>, + ) -> anyhow::Result<()>; + + async fn recall( + &self, + query: &str, + limit: usize, + session_id: Option<&str>, + ) -> anyhow::Result>; + + async fn get(&self, key: &str) -> anyhow::Result>; + + async fn list( + &self, + category: Option<&MemoryCategory>, + session_id: Option<&str>, + ) -> anyhow::Result>; + + async fn forget(&self, key: &str) -> anyhow::Result; + + async fn count(&self) -> anyhow::Result; + + async fn health_check(&self) -> bool; +} +``` + +*** + +## SQLite Backend + +The `SqliteMemory` implementation serves as the primary persistent backend. It uses `rusqlite` and is tuned for high performance and reliability in a local environment. + +### Performance Tuning + +The backend initializes with specific PRAGMAs to optimize for concurrent access and speed: + +```rust +conn.execute_batch( + "PRAGMA journal_mode = WAL; + PRAGMA synchronous = NORMAL; + PRAGMA mmap_size = 8388608; + PRAGMA cache_size = -2000; + PRAGMA temp_store = MEMORY;", +)?; +``` + +- **WAL mode**: Enables concurrent reads even during write operations. +- **mmap (8MB)**: Allows the OS to handle hot reads through memory mapping. +- **temp_store MEMORY**: Ensures temporary tables never touch the disk. + +*** + +## Schema Design + +The system maintains a relational table for core data and a virtual table for full-text search (FTS5). Triggers keep these in sync automatically. + +```sql +-- Core memories table +CREATE TABLE IF NOT EXISTS memories ( + id TEXT PRIMARY KEY, + key TEXT NOT NULL UNIQUE, + content TEXT NOT NULL, + category TEXT NOT NULL DEFAULT 'core', + embedding BLOB, + created_at TEXT NOT NULL, + updated_at TEXT NOT NULL, + session_id TEXT +); + +-- FTS5 virtual table for keyword search +CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5( + key, content, content=memories, content_rowid=rowid +); + +-- Sync triggers +CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN + INSERT INTO memories_fts(rowid, key, content) + VALUES (new.rowid, new.key, new.content); +END; +``` + +*** + +## Hybrid Search + +The `recall` method executes a hybrid search strategy. It merges results from two distinct search mechanisms: + +1. **Keyword Search**: Uses FTS5 BM25 scoring for exact word matches. +2. **Vector Search**: Computes cosine similarity between query embeddings and stored memory embeddings. + +### Score Fusion + +Results are combined using a weighted average. The defaults are typically: +- **Vector Weight**: 0.7 +- **Keyword Weight**: 0.3 + +If vector results are unavailable (e.g., if embeddings are disabled), the system falls back to keyword-only search. If both high-level search mechanisms return no results, it uses a final `LIKE %query%` fallback to ensure maximum recall. + +*** + +## Embedding Cache + +To avoid redundant API calls to embedding providers, ZeroClaw uses an internal LRU (Least Recently Used) cache stored in SQLite. + +```sql +CREATE TABLE IF NOT EXISTS embedding_cache ( + content_hash TEXT PRIMARY KEY, + embedding BLOB NOT NULL, + created_at TEXT NOT NULL, + accessed_at TEXT NOT NULL +); +``` + +Whenever a memory is stored or a query is processed, the system checks this cache first using a deterministic content hash. Eviction occurs once the cache reaches its configured limit (default 10,000 entries). + +*** + +## Backend Implementations + +ZeroClaw supports several backend types configured via [[Configuration]]: + +1. **SQLite**: The standard persistent local backend using FTS5 and BLOB embeddings. +2. **PostgreSQL**: Used for distributed or cloud-hosted deployments (requires `pgvector`). +3. **Lucid**: A bridge backend that synchronizes local SQLite memory with remote services. +4. **Markdown**: A simple file-based implementation that stores memories as `.md` files in the workspace. +5. **Qdrant**: A dedicated vector database backend for high-scale semantic search. +6. **None**: An explicit no-op backend that disables all memory persistence. + +*** + +## Timeout Guards + +Database operations are protected by timeout guards. Specifically, opening a SQLite connection is capped at 300 seconds to prevent the system from hanging on locked or slow filesystems. + +```rust +const SQLITE_OPEN_TIMEOUT_CAP_SECS: u64 = 300; +``` + +*** + +## Relevance to Luna + +ZeroClaw's memory architecture serves as the blueprint for [[Memory]]. While Luna currently has an `IMemoryStore` interface, the existing file-based implementation lacks sophisticated recall. + +Adopting the ZeroClaw pattern provides: +- **Structured Categories**: Using `MemoryCategory` (Core, Daily, Conversation) for better context management. +- **Hybrid Recall**: Moving beyond simple file reading to a ranked keyword+vector search. +- **SQLite Reference**: Luna can adopt the `SqliteMemory` implementation directly to replace the current unstructured storage. + +Cross-links: [[Core]], [[Configuration]] diff --git a/Documentation/References/ZeroClaw/Overview.md b/Documentation/References/ZeroClaw/Overview.md new file mode 100644 index 0000000..e6a8aa0 --- /dev/null +++ b/Documentation/References/ZeroClaw/Overview.md @@ -0,0 +1,193 @@ +# ZeroClaw + +## Overview +ZeroClaw is a lean, trait-driven Rust AI assistant runtime (~1.7k stars, ~1.6k commits). Single binary, <5MB RAM, <10ms startup. Everything is a swappable trait. Repo: https://github.com/openagen/zeroclaw + +## Architecture +- Single-binary Rust runtime — no microservices, no plugins to install +- Trait-driven design: every subsystem (Provider, Channel, Tool, Memory, Runtime, Security) is a trait you swap +- Minimal footprint: <5MB RAM, <10ms cold start +- All features compiled in-process, zero external dependencies for core functionality + +## Providers +15+ provider implementations behind a `Provider` trait: +OpenAI, Anthropic, Gemini, Ollama, OpenRouter, Azure OpenAI, AWS Bedrock, GitHub Copilot, GLM, Telnyx, llama.cpp, vLLM, custom endpoints. + +Key pattern — `ReliableProvider` wrapper: wraps any provider with automatic fallback chains and retry logic. If primary fails, falls through to secondary, tertiary, etc. + +```rust +// Provider trait (src/providers/traits.rs) +pub trait Provider: Send + Sync { + fn name(&self) -> &str; + async fn chat(&self, request: ChatRequest) -> Result; + async fn stream(&self, request: ChatRequest) -> Result>>>; +} +``` + +## Agent Loop +- Full tool-calling protocol: LLM requests tool call → agent executes tool → feeds result back → loops until LLM stops requesting tools +- `DelegateTool`: spawns a sub-agent with a scoped task for multi-agent delegation +- Memory injection into agent context +- Identity/persona system supporting AIEOS v1.1 JSON format and OpenClaw markdown format + +## Channels +26 channel implementations behind a `Channel` trait: +CLI, Telegram, Discord, Slack, Mattermost, iMessage, Matrix, Signal, WhatsApp (Web + Business API), Email, IRC, Lark, DingTalk, QQ, Nostr, MQTT, Webhook, and more. + +```rust +// Channel message types (src/channels/traits.rs) +pub struct ChannelMessage { + pub id: String, + pub sender: String, + pub reply_target: Option, + pub content: String, + pub channel: String, + pub timestamp: DateTime, + pub thread_ts: Option, +} +``` + +## Memory +6 backends behind a `Memory` trait: +- SQLite: hybrid FTS5 full-text + cosine vector similarity in a single query, zero external deps +- PostgreSQL +- Lucid bridge +- Markdown (file-based) +- Qdrant (vector DB) +- Explicit none + +```rust (src/memory/traits.rs) +pub trait Memory: Send + Sync { + fn name(&self) -> &str; + async fn store(&self, entry: MemoryEntry) -> Result<()>; + async fn recall(&self, query: &str, limit: usize) -> Result>; +} + +pub struct MemoryEntry { + pub id: String, + pub key: String, + pub content: String, + pub category: MemoryCategory, + pub timestamp: DateTime, + pub session_id: Option, + pub score: Option, +} + +pub enum MemoryCategory { + Core, + Daily, + Conversation, + Custom(String), +} +``` + +Custom embedding provider routing — memory backends can use different embedding models. + +## Tools +42+ tool implementations behind a `Tool` trait: + +```rust +// Tool trait (src/tools/traits.rs) +pub trait Tool: Send + Sync { + fn name(&self) -> &str; + fn description(&self) -> &str; + fn parameters_schema(&self) -> serde_json::Value; + async fn execute(&self, args: serde_json::Value) -> Result; +} +``` + +Tool categories: +- **Shell & Files**: shell execution, file read/write/edit, glob search, content search +- **Browser & Web**: browser automation, HTTP requests, web fetch/search, screenshots +- **Documents**: PDF read, image info +- **Git**: git operations (status, diff, commit, log, etc.) +- **Scheduling**: cron add/list/remove/update/run +- **Memory**: store/recall/forget (tools that interact with the Memory trait) +- **Delegation**: DelegateTool for sub-agent spawning +- **Hardware**: USB discover/introspect, robot-kit integration +- **Integration**: Composio (1000+ OAuth apps), SOP tools, Pushover notifications + +## Sessions +- Per-sender conversation history +- Compaction (summarization of old messages) +- Autosave thresholds (every N messages, not just on shutdown) +- Per-sender provider/model overrides (each conversation can use a different model) + +## Security +Comprehensive security stack (16 modules): +- **SecurityPolicy**: Autonomy levels — readonly, supervised, full +- **Workspace Scoping**: Operations restricted to declared workspace paths +- **Filesystem Guards**: 14 system directories blocked, symlink escape detection, null byte injection blocked +- **Sandboxing**: Landlock, Bubblewrap, Docker, Firejail — multiple isolation backends +- **Gateway Pairing**: 6-digit codes + bearer tokens for channel authentication +- **Encrypted Secrets**: SecretStore for API keys and credentials +- **Audit Logging**: All security-relevant actions logged +- **Emergency Stop**: EstopManager for immediate agent shutdown +- **Prompt Guard**: Detection of prompt injection attempts +- **Leak Detector**: Prevents secrets from appearing in agent output +- **OTP**: One-time password support + +## Runtime +`RuntimeAdapter` trait with two implementations: +- `NativeRuntime`: Direct execution on host OS +- `DockerRuntime`: Isolated execution in Docker containers +Tool execution can be routed through either runtime for isolation. + +## Skills +- TOML manifests (`SKILL.toml`) + `SKILL.md` instructions +- open-skills sync for community skill repositories +- Security audit on install: blocks symlinks, scripts, unsafe patterns + +## Configuration +- TOML-based config at `~/.zeroclaw/config.toml` +- Hot-reload on key fields without restart +- Per-channel, per-provider, per-tool configuration sections + +## Tunnel +Trait-based tunneling for exposing local instance to the internet: +- Cloudflare Tunnel +- Tailscale +- ngrok +- Custom tunnel implementations + +*** + +## In-Depth Reference Pages + +- [[ReliableProvider]] — Three-level failover (model chain, provider chain, retry loop), error classification, API key rotation +- [[Agent Loop & Tools]] — Tool trait, agent execution loop, tool serialization, credential scrubbing +- [[Memory]] — Memory trait, SQLite hybrid FTS5+vector search, embedding cache, 6 backends +- [[Channel Messages]] — Channel trait, draft update protocol, ChannelMessage struct, SendMessage builder +- [[Security]] — SecurityPolicy, autonomy levels, command allowlist, path validation, sandboxing, secret store, e-stop +- [[Sessions]] — Per-sender storage, compaction logic, autosave thresholds, per-sender overrides +- [[Configuration]] — TOML config struct (30+ sections), ModelProviderConfig, DelegateAgentConfig, hot-reload +- [[Runtime Adapters]] — RuntimeAdapter trait, NativeRuntime vs DockerRuntime, capability querying +- [[Skills]] — SKILL.toml manifest, security audit on install, open-skills sync, prompt injection +- [[Compaction Strategy]] — Proactive agent-side and reactive channel-side compaction, summarization prompts, helper functions + +*** + +## Relevance to Luna + +### Patterns Worth Adopting + +ZeroClaw is architecturally closest to Luna (monolithic binary, trait/interface-driven design). These patterns map directly: + +- **ReliableProvider wrapper**: Luna's `IProvider` returning `IChatClient` is clean. Add a decorator that wraps any `IProvider` with fallback chains and retry logic. See [[ReliableProvider]] for the three-level failover pattern. Link to [[Core]]. +- **Tool trait + Agent loop**: This is Luna's #1 gap. The `Tool` trait maps cleanly to a C# `ITool` interface. The agent loop is the missing piece that turns Luna from a chat relay into an assistant. See [[Agent Loop & Tools]]. Link to [[Skills]]. +- **Memory with hybrid search**: Luna's `IMemoryStore` exists but has no recall. ZeroClaw's SQLite memory does hybrid FTS5 + cosine vector similarity in one query. See [[Memory]]. Link to Luna's [[Memory]]. +- **Channel message normalization**: The `ChannelMessage` struct should be the baseline for Luna's DTO. The draft update protocol maps to SignalR. See [[Channel Messages]]. Link to [[Channels]]. +- **Session autosave + per-sender overrides**: Autosave every N messages for crash resilience. Per-sender model overrides are cheap to add. See [[Sessions]]. Link to [[Core]]. +- **Compaction**: Dual-path approach (proactive message-count + reactive overflow recovery) with structured summarization prompts. See [[Compaction Strategy]]. +- **Security fundamentals**: Before tool execution, Luna needs filesystem guards, workspace scoping, and autonomy levels. See [[Security]]. ZeroClaw's `SecurityPolicy` is the reference. +- **TOML config with hot-reload**: Luna's [[Configuration]] module plans this. ZeroClaw's per-subsystem section pattern is the target. See [[Configuration]]. +- **Runtime adapters**: When tool execution is added, a similar `IRuntimeAdapter` allows switching between native and Docker. See [[Runtime Adapters]]. +- **Skills system**: SKILL.toml manifest with security audit on install. See [[Skills]]. + +### Key Differences from Luna +- Rust vs .NET/C# — different ecosystem, but the trait-driven architecture maps well to C# interfaces +- ZeroClaw has 42+ tools; Luna has 0 — tool system is the critical gap +- ZeroClaw has 15+ providers; Luna has 2 (Mistral, Ollama) +- ZeroClaw has 26 channels; Luna has 1 (CLI) +- ZeroClaw has comprehensive security (16 modules); Luna has none +- ZeroClaw runs as a single <5MB binary; Luna's .NET runtime is heavier but offers richer DI/middleware ecosystem diff --git a/Documentation/References/ZeroClaw/ReliableProvider.md b/Documentation/References/ZeroClaw/ReliableProvider.md new file mode 100644 index 0000000..d176850 --- /dev/null +++ b/Documentation/References/ZeroClaw/ReliableProvider.md @@ -0,0 +1,152 @@ +# ReliableProvider + +The `ReliableProvider` is a resilient decorator in ZeroClaw that wraps one or more standard providers to implement a three-level failover strategy. It ensures high availability by managing model fallbacks, provider redundancy, and intelligent retry logic with backoff. + +*** + +## Provider Trait + +All LLM integrations in ZeroClaw implement the `Provider` trait. This trait defines a unified interface for chat interactions, tool calling, and capability discovery. + +```rust +#[async_trait] +pub trait Provider: Send + Sync { + fn capabilities(&self) -> ProviderCapabilities { + ProviderCapabilities::default() + } + + async fn chat_with_system( + &self, + system_prompt: Option<&str>, + message: &str, + model: &str, + temperature: f64, + ) -> anyhow::Result; + + async fn chat_with_history( + &self, + messages: &[ChatMessage], + model: &str, + temperature: f64, + ) -> anyhow::Result; + + async fn chat( + &self, + request: ChatRequest<'_>, + model: &str, + temperature: f64, + ) -> anyhow::Result; + + async fn chat_with_tools( + &self, + messages: &[ChatMessage], + _tools: &[serde_json::Value], + model: &str, + temperature: f64, + ) -> anyhow::Result; +} +``` + +### ProviderCapabilities +The `ProviderCapabilities` struct allows providers to declare their feature set, which `ReliableProvider` uses to route requests correctly: +- `native_tool_calling`: Support for API-native function calling (Gemini, Anthropic, OpenAI). +- `vision`: Support for multimodal image inputs. + +### ToolsPayload +When tools are used, `Provider::convert_tools` returns a `ToolsPayload` enum to handle varying API requirements: +- `Gemini { function_declarations }` +- `Anthropic { tools }` +- `OpenAI { tools }` +- `PromptGuided { instructions }`: Textual fallback for providers without native support. + +*** + +## Three-Level Failover + +The `ReliableProvider` implements a nested loop structure to exhaust all possibilities before returning an error. + +```rust +pub struct ReliableProvider { + providers: Vec<(String, Box)>, + max_retries: u32, + base_backoff_ms: u64, + api_keys: Vec, + key_index: AtomicUsize, + model_fallbacks: HashMap>, +} +``` + +1. **Level 1: Model Chain**: Iterates through the primary model and its configured fallbacks (e.g., try `claude-3-5-sonnet`, fallback to `claude-3-haiku`). +2. **Level 2: Provider Chain**: For each model, iterates through registered providers in priority order (e.g., try Anthropic direct, fallback to OpenRouter). +3. **Level 3: Retry Loop**: For a specific (provider, model) pair, retries transient failures with exponential backoff. + +*** + +## Error Classification + +Intelligent failure handling depends on distinguishing transient issues from permanent ones. ZeroClaw uses heuristics and status codes for this classification. + +### Non-Retryable Errors +The `is_non_retryable()` function identifies errors that won't resolve with retries, such as: +- **Client Errors**: HTTP 4xx (except 429/408). +- **Authentication**: Key-word matching for "invalid api key", "unauthorized", or "permission denied". +- **Model Availability**: Heuristics for "model not found", "unknown model", or "unsupported". + +### Rate Limiting and Quota +- `is_rate_limited()`: Specifically detects HTTP 429 errors. +- `is_non_retryable_rate_limit()`: Detects business-level failures returned as 429s, such as "insufficient balance", "quota exhausted", or "plan does not include requested model". These trigger a provider fallback immediately. + +### Context Window Exceeded +The system short-circuits when the context window is exceeded to avoid useless retries: +```rust +fn is_context_window_exceeded(err: &anyhow::Error) -> bool { + let hints = [ + "exceeds the context window", + "maximum context length", + "token limit exceeded", + "prompt is too long", + ]; + // ... +} +``` + +*** + +## Exponential Backoff + +Retries use an exponential backoff strategy starting from `base_backoff_ms`. +- **Retry-After Parsing**: The system parses the `Retry-After` header or error body. +- **Capping**: Backoff is capped at 30 seconds to prevent indefinite stalls. +- **Jitter**: While the core logic doubles the wait time, it ensures the wait respects provider-suggested intervals. + +*** + +## API Key Rotation + +ZeroClaw supports round-robin API key rotation for the same provider to maximize throughput: +```rust +fn rotate_key(&self) -> Option<&str> { + if self.api_keys.is_empty() { return None; } + let idx = self.key_index.fetch_add(1, Ordering::Relaxed) % self.api_keys.len(); + Some(&self.api_keys[idx]) +} +``` +When a 429 is encountered (and it's not a quota error), the system cycles to the next key for the subsequent retry attempt. + +*** + +## Relevance to Luna + +Currently, Luna's [[Core]] implementation of `IProvider` is simple and lacks resilience. If a provider is down, the request fails. + +By implementing a `ReliableProvider` decorator for Luna's `IProvider`, we can: +- Wrap multiple `IChatClient` instances. +- Implement per-sender model overrides to allow specific users to access higher-tier models with fallback to cheaper ones. +- Integrate the ZeroClaw error classification logic to handle common LLM API failures gracefully. + +This pattern is essential for moving from a prototype to a production-grade system where provider stability cannot be guaranteed. + +*** + +[[Core]] +[[Configuration]] diff --git a/Documentation/References/ZeroClaw/Runtime Adapters.md b/Documentation/References/ZeroClaw/Runtime Adapters.md new file mode 100644 index 0000000..5c4e731 --- /dev/null +++ b/Documentation/References/ZeroClaw/Runtime Adapters.md @@ -0,0 +1,103 @@ +# Runtime Adapters + +ZeroClaw uses the `RuntimeAdapter` trait to abstract the execution environment from the core agent logic. This abstraction allows the same agent code to run natively on a host machine, inside a Docker container, or on restricted edge runtimes without modification to the core loop. + +*** + +## RuntimeAdapter Trait + +The `RuntimeAdapter` trait defines the capabilities and interface for any environment ZeroClaw operates within. It is designed to be `Send + Sync` to allow safe sharing across asynchronous tasks. + +```rust +pub trait RuntimeAdapter: Send + Sync { + /// Return the human-readable name of this runtime environment. + fn name(&self) -> &str; + + /// Report whether this runtime supports shell command execution. + fn has_shell_access(&self) -> bool; + + /// Report whether this runtime supports filesystem read/write. + fn has_filesystem_access(&self) -> bool; + + /// Return the base directory for persistent storage on this runtime. + fn storage_path(&self) -> PathBuf; + + /// Report whether this runtime supports long-running background processes. + fn supports_long_running(&self) -> bool; + + /// Return the maximum memory budget in bytes for this runtime. + fn memory_budget(&self) -> u64 { + 0 + } + + /// Build a shell command process configured for this runtime. + fn build_shell_command( + &self, + command: &str, + workspace_dir: &Path, + ) -> anyhow::Result; +} +``` + +*** + +## NativeRuntime + +The `NativeRuntime` implementation provides direct execution on the host operating system. It represents the least restrictive environment and is typically used for local development or trusted server environments. + +* **Shell Access**: Returns `true`. Commands are executed directly via the system shell. +* **Filesystem Access**: Returns `true`. The agent can interact with any path permitted by the user's OS permissions. +* **Memory Limits**: Typically returns `0` (unlimited), relying on the OS to manage process resources. +* **Command Building**: Spawns `tokio::process::Command` directly with the requested command string. + +*** + +## DockerRuntime + +The `DockerRuntime` provides isolated execution by wrapping operations in Docker containers. This is the preferred runtime for untrusted code execution or when strict environment reproducibility is required. + +* **Shell Access**: Configurable, but generally `true`. Commands are wrapped in `docker exec` calls targeting a specific container. +* **Filesystem Access**: Restricted to the volumes and mounts defined in the container configuration. +* **Memory Budgets**: Returns the memory limits defined for the container, allowing the agent to adapt its cache and buffer sizes. +* **Command Building**: Instead of direct execution, it constructs a command that executes inside the container namespace, often involving complex argument escaping and environment variable injection. + +*** + +## Capability Querying + +The agent loop queries the `RuntimeAdapter` before attempting to execute tools or background tasks. This ensures that the agent fails gracefully or skips unavailable functionality based on its environment. + +1. **Tool Pre-flight**: Before executing a shell tool, the orchestrator checks `has_shell_access()`. +2. **Persistence Check**: Before initializing disk-based state, the agent checks `has_filesystem_access()`. +3. **Background Services**: The heartbeat loop and gateway server only start if `supports_long_running()` returns `true`. + +This pattern prevents runtime errors by verifying environmental support at the logic gate rather than deep within the execution stack. + +*** + +## Command Building + +The `build_shell_command` method is the primary bridge between the agent and the OS. It takes a raw command string and a workspace directory, returning a configured `tokio::process::Command`. + +Runtimes use this to: +* Prepend sandbox wrappers (e.g., `firejail` or `sudo -u limited`). +* Set environment variables specific to the runtime (e.g., `PATH` or `HOME`). +* Handle working directory mapping (especially important in Docker where host paths and container paths differ). + +*** + +## Tool Routing + +Tool execution can be routed through specific runtimes based on security requirements. A "Security Router" might send filesystem operations to a native runtime for speed while routing unknown shell scripts to a Docker runtime for isolation. This routing logic relies on the standardized interface provided by the `RuntimeAdapter`. + +*** + +## Relevance to Luna + +Luna currently operates with implicit native execution. As Luna evolves to support tool execution and autonomous tasks, implementing an `IRuntimeAdapter` interface will be critical for safety. + +* **Isolation**: Adopting a pattern similar to ZeroClaw's `DockerRuntime` would allow Luna to run generated code in a sandbox without risking the host system. +* **Cross-Platform**: A runtime abstraction simplifies porting Luna to different OSs or containerized environments. +* **Security Integration**: This pairs with [[Security]] patterns to ensure that capabilities are not just checked by the runtime, but also verified against user-defined security policies. + +Cross-links: [[Core]], [[Skills]], [[Configuration]]. diff --git a/Documentation/References/ZeroClaw/Security.md b/Documentation/References/ZeroClaw/Security.md new file mode 100644 index 0000000..6fc250e --- /dev/null +++ b/Documentation/References/ZeroClaw/Security.md @@ -0,0 +1,214 @@ +# Security + +ZeroClaw implements a multi-layered security stack designed to provide defense-in-depth for autonomous agent operations. This system ensures that agents operate within defined boundaries, protect sensitive credentials, and provide a verifiable audit trail of all actions. + +*** + +## SecurityPolicy + +The `SecurityPolicy` is the central enforcement mechanism for all tool and command executions. It defines the agent's level of independence and the specific constraints on its operating environment. + +### Autonomy Levels + +Autonomy is categorized into three distinct levels, controlling the baseline behavior of the agent: + +```rust +pub enum AutonomyLevel { + /// Read-only: can observe but not act + ReadOnly, + /// Supervised: acts but requires approval for risky operations + Supervised, + /// Full: autonomous execution within policy bounds + Full, +} +``` + +### Risk Classification + +Commands and operations are classified by their potential impact: + +```rust +pub enum CommandRiskLevel { + Low, + Medium, + High, +} + +pub enum ToolOperation { + Read, + Act, +} +``` + +*** + +## Action Tracker + +ZeroClaw uses a sliding-window rate limiter to prevent automated abuse or runaway processes. It maintains a 1-hour window of all side-effecting actions. + +```rust +pub struct ActionTracker { + /// Timestamps of recent actions (kept within the last hour). + actions: Mutex>, +} + +impl ActionTracker { + pub fn record(&self) -> usize { + let mut actions = self.actions.lock(); + let cutoff = Instant::now() + .checked_sub(std::time::Duration::from_secs(3600)) + .unwrap_or_else(Instant::now); + actions.retain(|t| *t > cutoff); + actions.push(Instant::now()); + actions.len() + } +} +``` + +*** + +## Command Allowlist + +ZeroClaw employs a deny-by-default strategy for shell execution. Only explicitly listed commands are permitted, and they are subjected to rigorous parsing to prevent bypasses. + +### Default Allowed Commands +`git`, `npm`, `cargo`, `ls`, `cat`, `grep`, `find`, `echo`, `pwd`, `wc`, `head`, `tail`, `date`. + +### Default Forbidden Paths +The system blocks access to 14 system directories (e.g., `/etc`, `/root`, `/usr`, `/bin`, `/proc`) and 4 sensitive dotfile locations (`~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.config`) even if workspace confinement is disabled. + +### Shell Parsing Logic +To prevent command injection via chained operators or environment variables, ZeroClaw uses a quote-aware shell segment splitter and environment assignment stripper: + +```rust +fn skip_env_assignments(s: &str) -> &str { + // Strips 'FOO=bar' from 'FOO=bar cmd args' +} + +fn split_unquoted_segments(command: &str) -> Vec { + // Splits on ';', '|', '&&', '||', and newlines + // Respects quotes to allow literal separators in arguments +} +``` + +*** + +## Path Validation + +The `is_path_allowed()` function implements multiple layers of protection to enforce workspace confinement and prevent directory traversal. + +### Validation Logic + +```rust +pub fn is_path_allowed(&self, path: &str) -> bool { + // 1. Null-byte injection guard + if path.contains('\0') { return false; } + + // 2. Directory traversal detection + if Path::new(path).components().any(|c| matches!(c, Component::ParentDir)) { + return false; + } + + // 3. URL-encoding detection (..%2f) + let lower = path.to_lowercase(); + if lower.contains("..%2f") || lower.contains("%2f..") { + return false; + } + + // 4. Tilde expansion guard (blocks ~user forms) + if path.starts_with('~') && path != "~" && !path.starts_with("~/") { + return false; + } + + // 5. Absolute path block and forbidden prefix match + let expanded = expand_user_path(path); + if self.workspace_only && expanded.is_absolute() { return false; } + // ... (forbidden path checks) +} +``` + +*** + +## Sandboxing + +ZeroClaw supports multiple isolation backends via a unified `Sandbox` trait, allowing for varied levels of process and filesystem isolation. + +- **Landlock**: Linux-native LSM for fine-grained filesystem restriction. +- **Bubblewrap**: Unprivileged sandboxing utility (used by Flatpak). +- **Docker**: Containerized isolation for high-risk environments. +- **Firejail**: SUID-based sandbox for easy desktop application isolation. + +### Landlock Implementation snippet: + +```rust +fn apply_restrictions(&self) -> std::io::Result<()> { + let mut ruleset = Ruleset::default() + .handle_access(AccessFs::ReadFile | AccessFs::WriteFile | AccessFs::ReadDir | ...) + .and_then(|ruleset| ruleset.create())?; + + // Grant access only to workspace and necessary system paths (/usr, /bin) + if let Some(ref workspace) = self.workspace_dir { + ruleset = ruleset.add_rule(PathBeneath::new(workspace_fd, ...))?; + } + ruleset.restrict_self() +} +``` + +*** + +## Secret Management + +The `SecretStore` protects API keys and credentials using authenticated encryption (ChaCha20-Poly1305). + +```rust +pub struct SecretStore { + key_path: PathBuf, // ~/.zeroclaw/.secret_key (mode 0600) + enabled: bool, +} +``` + +Encryption ensures that secrets are never stored in plaintext in configuration files, preventing accidental exposure via `grep`, `git log`, or file sharing. + +*** + +## Audit Logging + +Every security-relevant event is recorded in a structured JSONL format. This provides a forensic trail of what was executed, by whom, and whether it was permitted by policy. + +```rust +pub struct AuditEvent { + pub timestamp: DateTime, + pub event_type: AuditEventType, + pub actor: Option, + pub action: Option, + pub result: Option, + pub security: SecurityContext, +} +``` + +*** + +## Emergency Stop (E-Stop) + +The `EstopManager` provides a "big red button" capability to immediately halt or restrict agent activity. + +- **Levels**: `KillAll`, `NetworkKill`, `DomainBlock`, `ToolFreeze`. +- **Fail-Closed**: If the state file is corrupt or unreadable, the system defaults to `KillAll`. +- **OTP Requirement**: Resuming operations after an E-Stop engagement can be configured to require a One-Time Password (TOTP) to ensure human authorization. + +*** + +## Relevance to Luna + +Luna currently lacks a security framework. Adopting ZeroClaw's security stack is critical before enabling tool execution in non-trusted environments. + +### Prioritized Adoption Order + +1. **Filesystem Guards + Workspace Scoping**: Implement `is_path_allowed()` to prevent Luna from escaping its designated project directory. +2. **Command Allowlist**: Restrict shell tools to a known-safe subset with defined autonomy levels. +3. **Path Validation**: Integrate component-aware path checking in all file-handling tools. +4. **Secret Store**: Migrate Luna's configuration to use ChaCha20-Poly1305 for API keys. +5. **Audit Logging**: Implement structured event logging for all tool invocations. +6. **Sandboxing**: Introduce Landlock or Docker backends for executing untrusted code. + +See also: [[Core]], [[Skills]], [[Configuration]]. \ No newline at end of file diff --git a/Documentation/References/ZeroClaw/Sessions.md b/Documentation/References/ZeroClaw/Sessions.md new file mode 100644 index 0000000..821d308 --- /dev/null +++ b/Documentation/References/ZeroClaw/Sessions.md @@ -0,0 +1,65 @@ +# Sessions + +ZeroClaw implements a robust session management system designed for multi-user environments and crash resilience. Unlike simple stateless request-response loops, ZeroClaw treats every interaction as part of a persistent, per-sender conversation that survives process restarts and handles context growth through automated compaction. + +*** + +## Per-Sender Storage + +Each conversation is isolated and keyed by a combination of the sender ID and the communication channel. This ensures that users on different platforms (e.g., Discord vs. Slack) or multiple users within the same platform maintain independent histories. + +- **Session Keying**: Sessions are typically indexed by `(channel_id, sender_id)`. +- **Isolation**: Memory and history from one sender never bleed into another's session unless explicitly shared via global memory. +- **Persistence**: Sessions are serialized and stored as JSON files, allowing the agent to resume exactly where it left off after a restart. + +*** + +## Compaction Logic + +To prevent context window overflow and maintain performance over long conversations, ZeroClaw uses an automated compaction mechanism defined in `agent/loop_.rs`. When the history grows beyond a specific threshold, old messages are summarized and replaced by a concise context block. + +- **Threshold**: Compaction triggers when the non-system message count exceeds `DEFAULT_MAX_HISTORY_MESSAGES = 50`. +- **Retention**: ZeroClaw keeps the `COMPACTION_KEEP_RECENT_MESSAGES = 20` most recent messages in their original form. +- **Source Cap**: The transcript passed to the summarizer is limited to `COMPACTION_MAX_SOURCE_CHARS = 12_000` to avoid overwhelming the summarization model. +- **Summary Cap**: The resulting summary is truncated to `COMPACTION_MAX_SUMMARY_CHARS = 2_000`. + +The summarization process is handled by a recursive call to the provider, instructing it to preserve key facts, user preferences, and unresolved tasks while omitting filler and verbose tool logs. + +*** + +## Autosave Thresholds + +ZeroClaw prioritizes data integrity through aggressive autosaving. Sessions are not just saved on graceful shutdown; they are updated after every significant interaction. + +- **Trigger**: `AUTOSAVE_MIN_MESSAGE_CHARS = 20`. +- **Behavior**: If a user message exceeds this length, it is considered "meaningful" enough to trigger an immediate save of the session state. +- **Crash Resilience**: This granular saving ensures that even in the event of a sudden crash or hardware failure, the agent loses at most the very last exchange. + +*** + +## Per-Sender Overrides + +Each session can carry its own configuration, allowing for dynamic behavior based on the specific user or channel requirements. + +- **Model Overrides**: A specific conversation can be configured to use a different provider or model than the global default. +- **Config Storage**: These overrides are stored alongside the session JSON, ensuring consistency across restarts. + +*** + +## Session Lifecycle + +1. **Creation**: A new session is initialized when a message is received from a previously unknown `(channel, sender)` pair. +2. **Loading**: Upon receiving a message, ZeroClaw checks the local storage for an existing session file matching the sender's key. +3. **Processing**: Messages are appended to the history, and compaction is checked before sending the request to the LLM. +4. **Saving**: The session is written to disk after the LLM responds or when the autosave threshold is met. +5. **Cleanup**: Older sessions can be archived or deleted based on global retention policies, though ZeroClaw typically favors long-term persistence. + +*** + +## Relevance to Luna + +Luna's SessionManager currently implements basic compaction via the LibrarianAgent, but lacks several of ZeroClaw's more robust features. Integrating these would significantly improve reliability and flexibility: + +- **Autosave**: Implementing the `AUTOSAVE_MIN_MESSAGE_CHARS` logic to move away from shutdown-only saves. This is critical for [[Core]] stability. +- **Per-Sender Overrides**: Enabling users to select specific models for their sessions, a feature currently missing from Luna's [[Configuration]]. +- **Configurable Thresholds**: Exposing compaction constants (like 50/20 messages) as configurable parameters rather than hardcoded values. diff --git a/Documentation/References/ZeroClaw/Skills.md b/Documentation/References/ZeroClaw/Skills.md new file mode 100644 index 0000000..8383303 --- /dev/null +++ b/Documentation/References/ZeroClaw/Skills.md @@ -0,0 +1,167 @@ +# Skills + +The ZeroClaw skills system enables the extension of agent capabilities through modular, audited packages. Each skill can define custom prompts, tools (shell, HTTP, or scripts), and metadata. This system serves as the reference architecture for [[Skills]] in Luna. + +*** + +## Skill Struct + +ZeroClaw defines skills and their associated tools using robust Rust structures. A `Skill` is the top-level container, while `SkillTool` defines specific executable capabilities. + +```rust +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct Skill { + pub name: String, + pub description: String, + pub version: String, + #[serde(default)] + pub author: Option, + #[serde(default)] + pub tags: Vec, + #[serde(default)] + pub tools: Vec, + #[serde(default)] + pub prompts: Vec, + #[serde(skip)] + pub location: Option, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct SkillTool { + pub name: String, + pub description: String, + /// "shell", "http", "script" + pub kind: String, + /// The command/URL/script to execute + pub command: String, + #[serde(default)] + pub args: HashMap, +} +``` + +*** + +## SKILL.toml Manifest + +The preferred way to define a skill is via a `SKILL.toml` manifest. ZeroClaw also supports a legacy `SKILL.md` fallback for prompt-only skills. + +```rust +#[derive(Debug, Clone, Serialize, Deserialize)] +struct SkillManifest { + skill: SkillMeta, + #[serde(default)] + tools: Vec, + #[serde(default)] + prompts: Vec, +} +``` + +### Example SKILL.toml +```toml +[skill] +name = "weather" +description = "Fetch weather forecasts" +version = "0.1.0" +author = "Luna-Team" +tags = ["utility", "api"] + +[[tools]] +name = "get_weather" +description = "Fetch forecast from wttr.in" +kind = "shell" +command = "curl -s wttr.in/$CITY" +``` + +*** + +## Security Audit on Install + +Security is a first-class citizen in ZeroClaw. The `load_skills()` function enforces a security gate via `audit::audit_skill_directory()`. + +What gets blocked: +- Symlinks (both for the directory itself and files within) +- Unsafe path patterns (traversal attempts) +- Insecure script patterns + +The `copy_dir_recursive_secure` function ensures that no symlinks are introduced during the installation process: + +```rust +fn copy_dir_recursive_secure(src: &Path, dest: &Path) -> Result<()> { + let src_meta = std::fs::symlink_metadata(src)?; + if src_meta.file_type().is_symlink() { + anyhow::bail!("Refusing to copy symlinked skill source path: {}", src.display()); + } + // ... recursive copy logic ... + if metadata.file_type().is_symlink() { + anyhow::bail!("Refusing to copy symlink within skill source: {}", src_path.display()); + } +} +``` + +*** + +## Open-Skills Repository Sync + +ZeroClaw supports a community-driven repository of skills. The system performs a weekly shallow clone to discover and update these capabilities. + +- **URL**: `https://github.com/besoeasy/open-skills` +- **Sync Interval**: 7 days (`60 * 60 * 24 * 7` seconds) +- **Mechanism**: `git clone --depth 1` for initialization, followed by periodic `git pull --ff-only`. + +The `ensure_open_skills_repo` function manages this lifecycle, checking a `.zeroclaw-open-skills-sync` marker file to determine if a sync is required. + +*** + +## Skill Prompt Injection + +Skills are surfaced to the LLM through XML-structured injection in the system prompt. This is handled by `skills_to_prompt_with_mode()`. + +### Full vs Compact Mode +- **Full**: Injects name, description, location, all instructions, and tool metadata. +- **Compact**: Injects only name, description, and location. Instructions and tools are loaded on demand by the LLM reading the file. + +```rust +pub fn skills_to_prompt_with_mode( + skills: &[Skill], + workspace_dir: &Path, + mode: crate::config::SkillsPromptInjectionMode, +) -> String { + // ... + for skill in skills { + let _ = writeln!(prompt, " "); + write_xml_text_element(&mut prompt, 4, "name", &skill.name); + write_xml_text_element(&mut prompt, 4, "description", &skill.description); + // ... + if matches!(mode, crate::config::SkillsPromptInjectionMode::Full) { + // Injects and tags + } + } +} +``` + +*** + +## CLI Management + +The `handle_command()` function provides a CLI interface for managing the skills lifecycle: +- `list`: Displays installed skills, versions, tools, and tags. +- `audit`: Manually runs the security audit on a local or installed skill. +- `install`: Clones from git or copies from a local path, followed by a mandatory audit. +- `remove`: Securely deletes a skill directory, preventing path traversal. + +*** + +## Secure Install + +When installing a skill, ZeroClaw uses `install_git_skill_source` or `install_local_skill_source`. Both paths terminate in a mandatory `enforce_skill_security_audit()` call. If the audit fails, the installed files are immediately rolled back (deleted). + +*** + +## Relevance to Luna + +Luna's skills system is a planned feature that will adopt the ZeroClaw architecture: +- **Manifest**: Adopt the `SKILL.toml` format for interoperability. +- **Security**: Implement the same mandatory audit gate and symlink rejection policy. +- **Injection**: Use the XML-structured prompt injection pattern to give the LLM clear boundaries for skill usage. + +Cross-links: [[Skills]], [[Core]], [[Configuration]]. \ No newline at end of file diff --git a/Documentation/References/mistral.openapi.yaml b/Documentation/References/mistral.openapi.yaml new file mode 100644 index 0000000..bb6f54e --- /dev/null +++ b/Documentation/References/mistral.openapi.yaml @@ -0,0 +1,11793 @@ +openapi: 3.1.0 +info: + title: Mistral AI API + description: Our Chat Completion and Embeddings APIs specification. Create your account on [La Plateforme](https://console.mistral.ai) to get access and read the [docs](https://docs.mistral.ai) to learn how to use it. + version: 1.0.0 +paths: + /v1/models: + get: + summary: List Models + description: List all models available to the user. + operationId: list_models_v1_models_get + parameters: + - name: provider + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Provider + - name: model + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Model + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ModelList' + examples: + userExample: + value: + - id: + capabilities: + completion_chat: true + completion_fim: false + function_calling: false + fine_tuning: false + vision: false + classification: false + job: + root: open-mistral-7b + object: model + created: 1756746619 + owned_by: + name: null + description: null + max_context_length: 32768 + aliases: [] + deprecation: null + deprecation_replacement_model: null + default_model_temperature: null + TYPE: fine-tuned + archived: false + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + tags: + - models + /v1/models/{model_id}: + get: + summary: Retrieve Model + description: Retrieve information about a model. + operationId: retrieve_model_v1_models__model_id__get + parameters: + - name: model_id + in: path + required: true + schema: + type: string + title: Model Id + example: ft:open-mistral-7b:587a6b29:20240514:7e773925 + description: The ID of the model to retrieve. + responses: + '200': + description: Successful Response + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/BaseModelCard' + - $ref: '#/components/schemas/FTModelCard' + discriminator: + propertyName: type + mapping: + base: '#/components/schemas/BaseModelCard' + fine-tuned: '#/components/schemas/FTModelCard' + title: Response Retrieve Model V1 Models Model Id Get + examples: + userExample: + value: + id: + capabilities: + completion_chat: true + completion_fim: false + function_calling: false + fine_tuning: false + vision: false + classification: false + job: + root: open-mistral-7b + object: model + created: 1756746619 + owned_by: + name: null + description: null + max_context_length: 32768 + aliases: [] + deprecation: null + deprecation_replacement_model: null + default_model_temperature: null + TYPE: fine-tuned + archived: false + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + tags: + - models + delete: + summary: Delete Model + description: Delete a fine-tuned model. + operationId: delete_model_v1_models__model_id__delete + parameters: + - name: model_id + in: path + required: true + schema: + type: string + title: Model Id + example: ft:open-mistral-7b:587a6b29:20240514:7e773925 + description: The ID of the model to delete. + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteModelOut' + examples: + userExample: + value: + id: ft:open-mistral-7b:587a6b29:20240514:7e773925 + object: model + deleted: true + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + tags: + - models + /v1/conversations: + post: + operationId: agents_api_v1_conversations_start + summary: Create a conversation and append entries to it. + description: Create a new conversation, using a base model or an agent and append entries. Completion and tool executions are run and the response is appended to the conversation.Use the returned conversation_id to continue the conversation. + tags: + - beta.conversations + parameters: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ConversationRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ConversationResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + get: + operationId: agents_api_v1_conversations_list + summary: List all created conversations. + description: Retrieve a list of conversation entities sorted by creation time. + tags: + - beta.conversations + parameters: + - name: page + in: query + required: false + schema: + type: integer + title: Page + default: 0 + - name: page_size + in: query + required: false + schema: + type: integer + title: Page Size + default: 100 + - name: metadata + in: query + required: false + content: + application/json: + schema: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Metadata + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + anyOf: + - $ref: '#/components/schemas/ModelConversation' + - $ref: '#/components/schemas/AgentConversation' + title: Response V1 Conversations List + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/conversations/{conversation_id}: + get: + operationId: agents_api_v1_conversations_get + summary: Retrieve a conversation information. + description: Given a conversation_id retrieve a conversation entity with its attributes. + tags: + - beta.conversations + parameters: + - name: conversation_id + in: path + description: ID of the conversation from which we are fetching metadata. + required: true + schema: + type: string + title: Conversation Id + description: ID of the conversation from which we are fetching metadata. + responses: + '200': + description: Successful Response + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/ModelConversation' + - $ref: '#/components/schemas/AgentConversation' + title: Response V1 Conversations Get + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + delete: + operationId: agents_api_v1_conversations_delete + summary: Delete a conversation. + description: Delete a conversation given a conversation_id. + tags: + - beta.conversations + parameters: + - name: conversation_id + in: path + description: ID of the conversation from which we are fetching metadata. + required: true + schema: + type: string + title: Conversation Id + description: ID of the conversation from which we are fetching metadata. + responses: + '204': + description: Successful Response + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + post: + operationId: agents_api_v1_conversations_append + summary: Append new entries to an existing conversation. + description: Run completion on the history of the conversation and the user entries. Return the new created entries. + tags: + - beta.conversations + parameters: + - name: conversation_id + in: path + description: ID of the conversation to which we append entries. + required: true + schema: + type: string + title: Conversation Id + description: ID of the conversation to which we append entries. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ConversationAppendRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ConversationResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/conversations/{conversation_id}/history: + get: + operationId: agents_api_v1_conversations_history + summary: Retrieve all entries in a conversation. + description: Given a conversation_id retrieve all the entries belonging to that conversation. The entries are sorted in the order they were appended, those can be messages, connectors or function_call. + tags: + - beta.conversations + parameters: + - name: conversation_id + in: path + description: ID of the conversation from which we are fetching entries. + required: true + schema: + type: string + title: Conversation Id + description: ID of the conversation from which we are fetching entries. + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ConversationHistory' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/conversations/{conversation_id}/messages: + get: + operationId: agents_api_v1_conversations_messages + summary: Retrieve all messages in a conversation. + description: Given a conversation_id retrieve all the messages belonging to that conversation. This is similar to retrieving all entries except we filter the messages only. + tags: + - beta.conversations + parameters: + - name: conversation_id + in: path + description: ID of the conversation from which we are fetching messages. + required: true + schema: + type: string + title: Conversation Id + description: ID of the conversation from which we are fetching messages. + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ConversationMessages' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/conversations/{conversation_id}/restart: + post: + operationId: agents_api_v1_conversations_restart + summary: Restart a conversation starting from a given entry. + description: Given a conversation_id and an id, recreate a conversation from this point and run completion. A new conversation is returned with the new entries returned. + tags: + - beta.conversations + parameters: + - name: conversation_id + in: path + description: ID of the original conversation which is being restarted. + required: true + schema: + type: string + title: Conversation Id + description: ID of the original conversation which is being restarted. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ConversationRestartRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ConversationResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/agents: + post: + operationId: agents_api_v1_agents_create + summary: Create a agent that can be used within a conversation. + description: Create a new agent giving it instructions, tools, description. The agent is then available to be used as a regular assistant in a conversation or as part of an agent pool from which it can be used. + tags: + - beta.agents + parameters: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AgentCreationRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Agent' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + get: + operationId: agents_api_v1_agents_list + summary: List agent entities. + description: Retrieve a list of agent entities sorted by creation time. + tags: + - beta.agents + parameters: + - name: page + in: query + description: Page number (0-indexed) + required: false + schema: + type: integer + title: Page + minimum: 0 + description: Page number (0-indexed) + default: 0 + - name: page_size + in: query + description: Number of agents per page + required: false + schema: + type: integer + title: Page Size + maximum: 1000 + minimum: 1 + description: Number of agents per page + default: 20 + - name: deployment_chat + in: query + required: false + schema: + anyOf: + - type: boolean + - type: 'null' + title: Deployment Chat + - name: sources + in: query + required: false + schema: + anyOf: + - type: array + items: + $ref: '#/components/schemas/RequestSource' + - type: 'null' + title: Sources + - name: name + in: query + description: Filter by agent name + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Name + description: Filter by agent name + - name: search + in: query + description: Search agents by name or ID + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Search + description: Search agents by name or ID + - name: id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Id + - name: metadata + in: query + required: false + content: + application/json: + schema: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Metadata + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Agent' + title: Response V1 Agents List + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/agents/{agent_id}: + get: + operationId: agents_api_v1_agents_get + summary: Retrieve an agent entity. + description: Given an agent, retrieve an agent entity with its attributes. The agent_version parameter can be an integer version number or a string alias. + tags: + - beta.agents + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + - name: agent_version + in: query + required: false + schema: + anyOf: + - type: integer + - type: string + - type: 'null' + title: Agent Version + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Agent' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + patch: + operationId: agents_api_v1_agents_update + summary: Update an agent entity. + description: Update an agent attributes and create a new version. + tags: + - beta.agents + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AgentUpdateRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Agent' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + delete: + operationId: agents_api_v1_agents_delete + summary: Delete an agent entity. + tags: + - beta.agents + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + responses: + '204': + description: Successful Response + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/agents/{agent_id}/version: + patch: + operationId: agents_api_v1_agents_update_version + summary: Update an agent version. + description: Switch the version of an agent. + tags: + - beta.agents + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + - name: version + in: query + required: true + schema: + type: integer + title: Version + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Agent' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/agents/{agent_id}/versions: + get: + operationId: agents_api_v1_agents_list_versions + summary: List all versions of an agent. + description: Retrieve all versions for a specific agent with full agent context. Supports pagination. + tags: + - beta.agents + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + - name: page + in: query + description: Page number (0-indexed) + required: false + schema: + type: integer + title: Page + minimum: 0 + description: Page number (0-indexed) + default: 0 + - name: page_size + in: query + description: Number of versions per page + required: false + schema: + type: integer + title: Page Size + maximum: 100 + minimum: 1 + description: Number of versions per page + default: 20 + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Agent' + title: Response V1 Agents List Versions + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/agents/{agent_id}/versions/{version}: + get: + operationId: agents_api_v1_agents_get_version + summary: Retrieve a specific version of an agent. + description: Get a specific agent version by version number. + tags: + - beta.agents + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + - name: version + in: path + required: true + schema: + type: string + title: Version + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Agent' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/agents/{agent_id}/aliases: + put: + operationId: agents_api_v1_agents_create_or_update_alias + summary: Create or update an agent version alias. + description: Create a new alias or update an existing alias to point to a specific version. Aliases are unique per agent and can be reassigned to different versions. + tags: + - beta.agents + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + - name: alias + in: query + required: true + schema: + type: string + title: Alias + maxLength: 64 + minLength: 1 + pattern: ^[a-z]([a-z0-9_-]*[a-z0-9])?$ + - name: version + in: query + required: true + schema: + type: integer + title: Version + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/AgentAliasResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + get: + operationId: agents_api_v1_agents_list_version_aliases + summary: List all aliases for an agent. + description: Retrieve all version aliases for a specific agent. + tags: + - beta.agents + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/AgentAliasResponse' + title: Response V1 Agents List Version Aliases + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + delete: + operationId: agents_api_v1_agents_delete_alias + summary: Delete an agent version alias. + description: Delete an existing alias for an agent. + tags: + - beta.agents + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + - name: alias + in: query + required: true + schema: + type: string + title: Alias + maxLength: 64 + minLength: 1 + pattern: ^[a-z]([a-z0-9_-]*[a-z0-9])?$ + responses: + '204': + description: Successful Response + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/conversations#stream: + post: + operationId: agents_api_v1_conversations_start_stream + summary: Create a conversation and append entries to it. + description: Create a new conversation, using a base model or an agent and append entries. Completion and tool executions are run and the response is appended to the conversation.Use the returned conversation_id to continue the conversation. + tags: + - beta.conversations + parameters: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ConversationStreamRequest' + required: true + responses: + '200': + description: Successful Response + content: + text/event-stream: + schema: + $ref: '#/components/schemas/ConversationEvents' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/conversations/{conversation_id}#stream: + post: + operationId: agents_api_v1_conversations_append_stream + summary: Append new entries to an existing conversation. + description: Run completion on the history of the conversation and the user entries. Return the new created entries. + tags: + - beta.conversations + parameters: + - name: conversation_id + in: path + description: ID of the conversation to which we append entries. + required: true + schema: + type: string + title: Conversation Id + description: ID of the conversation to which we append entries. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ConversationAppendStreamRequest' + required: true + responses: + '200': + description: Successful Response + content: + text/event-stream: + schema: + $ref: '#/components/schemas/ConversationEvents' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/conversations/{conversation_id}/restart#stream: + post: + operationId: agents_api_v1_conversations_restart_stream + summary: Restart a conversation starting from a given entry. + description: Given a conversation_id and an id, recreate a conversation from this point and run completion. A new conversation is returned with the new entries returned. + tags: + - beta.conversations + parameters: + - name: conversation_id + in: path + description: ID of the original conversation which is being restarted. + required: true + schema: + type: string + title: Conversation Id + description: ID of the original conversation which is being restarted. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ConversationRestartStreamRequest' + required: true + responses: + '200': + description: Successful Response + content: + text/event-stream: + schema: + $ref: '#/components/schemas/ConversationEvents' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/files: + post: + operationId: files_api_routes_upload_file + summary: Upload File + description: 'Upload a file that can be used across various endpoints. + + + The size of individual files can be a maximum of 512 MB. The Fine-tuning API only supports .jsonl files. + + + Please contact us if you need to increase these storage limits.' + tags: + - files + parameters: [] + requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + expiry: + anyOf: + - type: integer + - type: 'null' + title: Expiry + visibility: + allOf: + - type: string + title: FileVisibility + enum: + - workspace + - user + default: workspace + purpose: + $ref: '#/components/schemas/FilePurpose' + file: + $ref: '#/components/schemas/File' + title: MultiPartBodyParams + required: + - file + required: true + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UploadFileOut' + examples: + userExample: + value: + id: e85980c9-409e-4a46-9304-36588f6292b0 + object: file + bytes: null + created_at: 1759500189 + filename: example.file.jsonl + purpose: fine-tune + sample_type: instruct + source: upload + num_lines: 2 + mimetype: application/jsonl + signature: d4821d2de1917341 + get: + operationId: files_api_routes_list_files + summary: List Files + description: Returns a list of files that belong to the user's organization. + tags: + - files + parameters: + - name: page + in: query + required: false + schema: + type: integer + title: Page + default: 0 + - name: page_size + in: query + required: false + schema: + type: integer + title: Page Size + default: 100 + - name: include_total + in: query + required: false + schema: + type: boolean + title: Include Total + default: true + - name: sample_type + in: query + required: false + schema: + anyOf: + - type: array + items: + $ref: '#/components/schemas/SampleType' + - type: 'null' + title: Sample Type + - name: source + in: query + required: false + schema: + anyOf: + - type: array + items: + $ref: '#/components/schemas/Source' + - type: 'null' + title: Source + - name: search + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Search + - name: purpose + in: query + required: false + schema: + anyOf: + - $ref: '#/components/schemas/FilePurpose' + - type: 'null' + - name: mimetypes + in: query + required: false + schema: + anyOf: + - type: array + items: + type: string + - type: 'null' + title: Mimetypes + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ListFilesOut' + examples: + userExample: + value: + data: + - id: + object: file + bytes: null + created_at: 1759491994 + filename: + purpose: batch + sample_type: batch_result + source: mistral + num_lines: 2 + mimetype: application/jsonl + signature: null + - id: + object: file + bytes: null + created_at: 1759491994 + filename: + purpose: batch + sample_type: batch_result + source: mistral + num_lines: 2 + mimetype: application/jsonl + signature: null + object: list + total: 2 + /v1/files/{file_id}: + get: + operationId: files_api_routes_retrieve_file + summary: Retrieve File + description: Returns information about a specific file. + tags: + - files + parameters: + - name: file_id + in: path + required: true + schema: + type: string + title: File Id + format: uuid + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/RetrieveFileOut' + examples: + userExample: + value: + id: e85980c9-409e-4a46-9304-36588f6292b0 + object: file + bytes: null + created_at: 1759500189 + filename: example.file.jsonl + purpose: fine-tune + sample_type: instruct + source: upload + deleted: false + num_lines: 2 + mimetype: application/jsonl + signature: d4821d2de1917341 + delete: + operationId: files_api_routes_delete_file + summary: Delete File + description: Delete a file. + tags: + - files + parameters: + - name: file_id + in: path + required: true + schema: + type: string + title: File Id + format: uuid + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteFileOut' + examples: + userExample: + value: + id: e85980c9-409e-4a46-9304-36588f6292b0 + object: file + deleted: true + /v1/files/{file_id}/content: + get: + operationId: files_api_routes_download_file + summary: Download File + description: Download a file + tags: + - files + parameters: + - name: file_id + in: path + required: true + schema: + type: string + title: File Id + format: uuid + responses: + '200': + description: OK + content: + application/octet-stream: + schema: + type: string + format: binary + /v1/files/{file_id}/url: + get: + operationId: files_api_routes_get_signed_url + summary: Get Signed Url + tags: + - files + parameters: + - name: file_id + in: path + required: true + schema: + type: string + title: File Id + format: uuid + - name: expiry + in: query + description: Number of hours before the url becomes invalid. Defaults to 24h + required: false + schema: + type: integer + title: Expiry + description: Number of hours before the url becomes invalid. Defaults to 24h + default: 24 + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/FileSignedURL' + examples: + userExample: + value: + url: https://mistralaifilesapiprodswe.blob.core.windows.net/fine-tune/.../.../e85980c9409e4a46930436588f6292b0.jsonl?se=2025-10-04T14%3A16%3A17Z&sp=r&sv=2025-01-05&sr=b&sig=... + /v1/fine_tuning/jobs: + get: + operationId: jobs_api_routes_fine_tuning_get_fine_tuning_jobs + summary: Get Fine Tuning Jobs + description: Get a list of fine-tuning jobs for your organization and user. + tags: + - deprecated.fine-tuning + parameters: + - name: page + in: query + description: The page number of the results to be returned. + required: false + schema: + type: integer + title: Page + default: 0 + - name: page_size + in: query + description: The number of items to return per page. + required: false + schema: + type: integer + title: Page Size + default: 100 + - name: model + in: query + description: The model name used for fine-tuning to filter on. When set, the other results are not displayed. + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Model + - name: created_after + in: query + description: The date/time to filter on. When set, the results for previous creation times are not displayed. + required: false + schema: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Created After + - name: created_before + in: query + required: false + schema: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Created Before + - name: created_by_me + in: query + description: When set, only return results for jobs created by the API caller. Other results are not displayed. + required: false + schema: + type: boolean + title: Created By Me + default: false + - name: status + in: query + description: The current job state to filter on. When set, the other results are not displayed. + required: false + schema: + anyOf: + - type: string + enum: + - QUEUED + - STARTED + - VALIDATING + - VALIDATED + - RUNNING + - FAILED_VALIDATION + - FAILED + - SUCCESS + - CANCELLED + - CANCELLATION_REQUESTED + - type: 'null' + title: Status + - name: wandb_project + in: query + description: The Weights and Biases project to filter on. When set, the other results are not displayed. + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Wandb Project + - name: wandb_name + in: query + description: The Weight and Biases run name to filter on. When set, the other results are not displayed. + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Wandb Name + - name: suffix + in: query + description: The model suffix to filter on. When set, the other results are not displayed. + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Suffix + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/JobsOut' + post: + operationId: jobs_api_routes_fine_tuning_create_fine_tuning_job + summary: Create Fine Tuning Job + description: Create a new fine-tuning job, it will be queued for processing. + tags: + - deprecated.fine-tuning + parameters: + - name: dry_run + in: query + required: false + schema: + anyOf: + - type: boolean + - type: 'null' + title: Dry Run + description: "* If `true` the job is not spawned, instead the query returns a handful of useful metadata\n for the user to perform sanity checks (see `LegacyJobMetadataOut` response).\n* Otherwise, the job is started and the query returns the job ID along with some of the\n input parameters (see `JobOut` response).\n" + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/JobIn' + required: true + responses: + '200': + description: OK + content: + application/json: + schema: + anyOf: + - oneOf: + - $ref: '#/components/schemas/CompletionJobOut' + - $ref: '#/components/schemas/ClassifierJobOut' + discriminator: + propertyName: job_type + mapping: + classifier: '#/components/schemas/ClassifierJobOut' + completion: '#/components/schemas/CompletionJobOut' + - $ref: '#/components/schemas/LegacyJobMetadataOut' + title: Response + /v1/fine_tuning/jobs/{job_id}: + get: + operationId: jobs_api_routes_fine_tuning_get_fine_tuning_job + summary: Get Fine Tuning Job + description: Get a fine-tuned job details by its UUID. + tags: + - deprecated.fine-tuning + parameters: + - name: job_id + in: path + description: The ID of the job to analyse. + required: true + schema: + type: string + title: Job Id + format: uuid + responses: + '200': + description: OK + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/CompletionDetailedJobOut' + - $ref: '#/components/schemas/ClassifierDetailedJobOut' + discriminator: + propertyName: job_type + mapping: + classifier: '#/components/schemas/ClassifierDetailedJobOut' + completion: '#/components/schemas/CompletionDetailedJobOut' + title: Response + /v1/fine_tuning/jobs/{job_id}/cancel: + post: + operationId: jobs_api_routes_fine_tuning_cancel_fine_tuning_job + summary: Cancel Fine Tuning Job + description: Request the cancellation of a fine tuning job. + tags: + - deprecated.fine-tuning + parameters: + - name: job_id + in: path + description: The ID of the job to cancel. + required: true + schema: + type: string + title: Job Id + format: uuid + responses: + '200': + description: OK + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/CompletionDetailedJobOut' + - $ref: '#/components/schemas/ClassifierDetailedJobOut' + discriminator: + propertyName: job_type + mapping: + classifier: '#/components/schemas/ClassifierDetailedJobOut' + completion: '#/components/schemas/CompletionDetailedJobOut' + title: Response + /v1/fine_tuning/jobs/{job_id}/start: + post: + operationId: jobs_api_routes_fine_tuning_start_fine_tuning_job + summary: Start Fine Tuning Job + description: Request the start of a validated fine tuning job. + tags: + - deprecated.fine-tuning + parameters: + - name: job_id + in: path + required: true + schema: + type: string + title: Job Id + format: uuid + responses: + '200': + description: OK + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/CompletionDetailedJobOut' + - $ref: '#/components/schemas/ClassifierDetailedJobOut' + discriminator: + propertyName: job_type + mapping: + classifier: '#/components/schemas/ClassifierDetailedJobOut' + completion: '#/components/schemas/CompletionDetailedJobOut' + title: Response + /v1/fine_tuning/models/{model_id}: + patch: + operationId: jobs_api_routes_fine_tuning_update_fine_tuned_model + summary: Update Fine Tuned Model + description: Update a model name or description. + tags: + - models + parameters: + - name: model_id + in: path + description: The ID of the model to update. + required: true + schema: + type: string + title: Model Id + example: ft:open-mistral-7b:587a6b29:20240514:7e773925 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateFTModelIn' + required: true + responses: + '200': + description: OK + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/CompletionFTModelOut' + - $ref: '#/components/schemas/ClassifierFTModelOut' + discriminator: + propertyName: model_type + mapping: + classifier: '#/components/schemas/ClassifierFTModelOut' + completion: '#/components/schemas/CompletionFTModelOut' + title: Response + /v1/fine_tuning/models/{model_id}/archive: + post: + operationId: jobs_api_routes_fine_tuning_archive_fine_tuned_model + summary: Archive Fine Tuned Model + description: Archive a fine-tuned model. + tags: + - models + parameters: + - name: model_id + in: path + description: The ID of the model to archive. + required: true + schema: + type: string + title: Model Id + example: ft:open-mistral-7b:587a6b29:20240514:7e773925 + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ArchiveFTModelOut' + delete: + operationId: jobs_api_routes_fine_tuning_unarchive_fine_tuned_model + summary: Unarchive Fine Tuned Model + description: Un-archive a fine-tuned model. + tags: + - models + parameters: + - name: model_id + in: path + description: The ID of the model to unarchive. + required: true + schema: + type: string + title: Model Id + example: ft:open-mistral-7b:587a6b29:20240514:7e773925 + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UnarchiveFTModelOut' + /v1/batch/jobs: + get: + operationId: jobs_api_routes_batch_get_batch_jobs + summary: Get Batch Jobs + description: Get a list of batch jobs for your organization and user. + tags: + - batch + parameters: + - name: page + in: query + required: false + schema: + type: integer + title: Page + default: 0 + - name: page_size + in: query + required: false + schema: + type: integer + title: Page Size + default: 100 + - name: model + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Model + - name: agent_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Agent Id + - name: metadata + in: query + required: false + schema: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Metadata + - name: created_after + in: query + required: false + schema: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Created After + - name: created_by_me + in: query + required: false + schema: + type: boolean + title: Created By Me + default: false + - name: status + in: query + required: false + schema: + anyOf: + - type: array + items: + $ref: '#/components/schemas/BatchJobStatus' + - type: 'null' + title: Status + - name: order_by + in: query + required: false + schema: + type: string + title: Order By + enum: + - created + - -created + default: -created + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/BatchJobsOut' + post: + operationId: jobs_api_routes_batch_create_batch_job + summary: Create Batch Job + description: Create a new batch job, it will be queued for processing. + tags: + - batch + parameters: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/BatchJobIn' + required: true + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/BatchJobOut' + /v1/batch/jobs/{job_id}: + get: + operationId: jobs_api_routes_batch_get_batch_job + summary: Get Batch Job + description: "Get a batch job details by its UUID.\n\nArgs:\n inline: If True, return results inline in the response." + tags: + - batch + parameters: + - name: job_id + in: path + required: true + schema: + type: string + title: Job Id + format: uuid + - name: inline + in: query + required: false + schema: + anyOf: + - type: boolean + - type: 'null' + title: Inline + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/BatchJobOut' + /v1/batch/jobs/{job_id}/cancel: + post: + operationId: jobs_api_routes_batch_cancel_batch_job + summary: Cancel Batch Job + description: Request the cancellation of a batch job. + tags: + - batch + parameters: + - name: job_id + in: path + required: true + schema: + type: string + title: Job Id + format: uuid + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/BatchJobOut' + /v1/chat/completions: + post: + operationId: chat_completion_v1_chat_completions_post + summary: Chat Completion + tags: + - chat + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ChatCompletionRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ChatCompletionResponse' + text/event-stream: + schema: + $ref: '#/components/schemas/CompletionEvent' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/fim/completions: + post: + operationId: fim_completion_v1_fim_completions_post + summary: Fim Completion + description: FIM completion. + tags: + - fim + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/FIMCompletionRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/FIMCompletionResponse' + examples: + userExample: + value: + id: 447e3e0d457e42e98248b5d2ef52a2a3 + object: chat.completion + model: codestral-2508 + usage: + prompt_tokens: 8 + completion_tokens: 91 + total_tokens: 99 + created: 1759496862 + choices: + - index: 0 + message: + content: "add_numbers(a: int, b: int) -> int:\n \"\"\"\n You are given two integers `a` and `b`. Your task is to write a function that\n returns the sum of these two integers. The function should be implemented in a\n way that it can handle very large integers (up to 10^18). As a reminder, your\n code has to be in python\n \"\"\"\n" + tool_calls: null + prefix: false + role: assistant + finish_reason: stop + text/event-stream: + schema: + $ref: '#/components/schemas/CompletionEvent' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/agents/completions: + post: + operationId: agents_completion_v1_agents_completions_post + summary: Agents Completion + deprecated: true + tags: + - deprecated.agents + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AgentsCompletionRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ChatCompletionResponse' + examples: + userExample: + value: + id: cf79f7daaee244b1a0ae5c7b1444424a + object: chat.completion + model: mistral-medium-latest + usage: + prompt_tokens: 24 + completion_tokens: 27 + total_tokens: 51 + prompt_audio_seconds: {} + created: 1759500534 + choices: + - index: 0 + message: + content: Arrr, the scallywag Claude Monet be the finest French painter to ever splash colors on a canvas, savvy? + tool_calls: null + prefix: false + role: assistant + finish_reason: stop + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/embeddings: + post: + operationId: embeddings_v1_embeddings_post + summary: Embeddings + description: Embeddings + tags: + - embeddings + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/EmbeddingRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/EmbeddingResponse' + examples: + userExample: + value: + data: + - embedding: + - -0.016632080078125 + - 0.0701904296875 + - 0.03143310546875 + - 0.01309967041015625 + - 0.0202789306640625 + index: 0 + object: embedding + - embedding: + - -0.0230560302734375 + - 0.039337158203125 + - 0.0521240234375 + - -0.0184783935546875 + - 0.034271240234375 + index: 1 + object: embedding + model: mistral-embed + object: list + usage: + prompt_tokens: 15 + completion_tokens: 0 + total_tokens: 15 + prompt_audio_seconds: null + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/moderations: + post: + operationId: moderations_v1_moderations_post + summary: Moderations + tags: + - classifiers + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ClassificationRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ModerationResponse' + examples: + userExample: + value: + id: 4d71ae510af942108ef7344f903e2b88 + model: mistral-moderation-latest + results: + - categories: + sexual: false + hate_and_discrimination: false + violence_and_threats: false + dangerous_and_criminal_content: false + selfharm: false + health: false + financial: false + law: false + pii: false + category_scores: + sexual: 0.0011335690505802631 + hate_and_discrimination: 0.0030753696337342262 + violence_and_threats: 0.0003569706459529698 + dangerous_and_criminal_content: 0.002251847181469202 + selfharm: 0.00017952796770259738 + health: 0.0002780309587251395 + financial: 8.481103577651083e-05 + law: 4.539786823443137e-05 + pii: 0.0023967307060956955 + - categories: + sexual: false + hate_and_discrimination: false + violence_and_threats: false + dangerous_and_criminal_content: false + selfharm: false + health: false + financial: false + law: false + pii: false + category_scores: + sexual: 0.000626334105618298 + hate_and_discrimination: 0.0013670255430042744 + violence_and_threats: 0.0002611903182696551 + dangerous_and_criminal_content: 0.0030753696337342262 + selfharm: 0.00010889690747717395 + health: 0.00015843621804378927 + financial: 0.000191104321856983 + law: 4.006369272246957e-05 + pii: 0.0035936026833951473 + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/chat/moderations: + post: + operationId: chat_moderations_v1_chat_moderations_post + summary: Chat Moderations + tags: + - classifiers + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ChatModerationRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ModerationResponse' + examples: + userExample: + value: + id: 352bce1a55814127a3b0bc4fb8f02a35 + model: mistral-moderation-latest + results: + - categories: + sexual: false + hate_and_discrimination: false + violence_and_threats: false + dangerous_and_criminal_content: false + selfharm: false + health: false + financial: false + law: false + pii: false + category_scores: + sexual: 0.0010322310263291001 + hate_and_discrimination: 0.001597845577634871 + violence_and_threats: 0.00020342698553577065 + dangerous_and_criminal_content: 0.0029810327105224133 + selfharm: 0.00017952796770259738 + health: 0.0002959570847451687 + financial: 7.9673009167891e-05 + law: 4.539786823443137e-05 + pii: 0.004198795650154352 + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/ocr: + post: + operationId: ocr_v1_ocr_post + summary: OCR + tags: + - ocr + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/OCRRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/OCRResponse' + examples: + userExample: + value: + pages: + - index: 1 + markdown: '# LEVERAGING UNLABELED DATA TO PREDICT OUT-OF-DISTRIBUTION PERFORMANCE + + Saurabh Garg*
Carnegie Mellon University
sgarg2@andrew.cmu.edu
Sivaraman Balakrishnan
Carnegie Mellon University
sbalakri@andrew.cmu.edu
Zachary C. Lipton
Carnegie Mellon University
zlipton@andrew.cmu.edu + + ## Behnam Neyshabur + + Google Research, Blueshift team
neyshabur@google.com + + Hanie Sedghi
Google Research, Brain team
hsedghi@google.com + + #### Abstract + + Real-world machine learning deployments are characterized by mismatches between the source (training) and target (test) distributions that may cause performance drops. In this work, we investigate methods for predicting the target domain accuracy using only labeled source data and unlabeled target data. We propose Average Thresholded Confidence (ATC), a practical method that learns a threshold on the model''s confidence, predicting accuracy as the fraction of unlabeled examples for which model confidence exceeds that threshold. ATC outperforms previous methods across several model architectures, types of distribution shifts (e.g., due to synthetic corruptions, dataset reproduction, or novel subpopulations), and datasets (WILDS, ImageNet, BREEDS, CIFAR, and MNIST). In our experiments, ATC estimates target performance $2-4 \times$ more accurately than prior methods. We also explore the theoretical foundations of the problem, proving that, in general, identifying the accuracy is just as hard as identifying the optimal predictor and thus, the efficacy of any method rests upon (perhaps unstated) assumptions on the nature of the shift. Finally, analyzing our method on some toy distributions, we provide insights concerning when it works ${ }^{1}$. + + ## 1 INTRODUCTION + + Machine learning models deployed in the real world typically encounter examples from previously unseen distributions. While the IID assumption enables us to evaluate models using held-out data from the source distribution (from which training data is sampled), this estimate is no longer valid in presence of a distribution shift. Moreover, under such shifts, model accuracy tends to degrade (Szegedy et al., 2014; Recht et al., 2019; Koh et al., 2021). Commonly, the only data available to the practitioner are a labeled training set (source) and unlabeled deployment-time data which makes the problem more difficult. In this setting, detecting shifts in the distribution of covariates is known to be possible (but difficult) in theory (Ramdas et al., 2015), and in practice (Rabanser et al., 2018). However, producing an optimal predictor using only labeled source and unlabeled target data is well-known to be impossible absent further assumptions (Ben-David et al., 2010; Lipton et al., 2018). + + Two vital questions that remain are: (i) the precise conditions under which we can estimate a classifier''s target-domain accuracy; and (ii) which methods are most practically useful. To begin, the straightforward way to assess the performance of a model under distribution shift would be to collect labeled (target domain) examples and then to evaluate the model on that data. However, collecting fresh labeled data from the target distribution is prohibitively expensive and time-consuming, especially if the target distribution is non-stationary. Hence, instead of using labeled data, we aim to use unlabeled data from the target distribution, that is comparatively abundant, to predict model performance. Note that in this work, our focus is not to improve performance on the target but, rather, to estimate the accuracy on the target for a given classifier. + + [^0]: Work done in part while Saurabh Garg was interning at Google ${ }^{1}$ Code is available at [https://github.com/saurabhgarg1996/ATC_code](https://github.com/saurabhgarg1996/ATC_code). + +' + images: [] + dimensions: + dpi: 200 + height: 2200 + width: 1700 + - index: 2 + markdown: '![img-0.jpeg](img-0.jpeg) + + Figure 1: Illustration of our proposed method ATC. Left: using source domain validation data, we identify a threshold on a score (e.g. negative entropy) computed on model confidence such that fraction of examples above the threshold matches the validation set accuracy. ATC estimates accuracy on unlabeled target data as the fraction of examples with the score above the threshold. Interestingly, this threshold yields accurate estimates on a wide set of target distributions resulting from natural and synthetic shifts. Right: Efficacy of ATC over previously proposed approaches on our testbed with a post-hoc calibrated model. To obtain errors on the same scale, we rescale all errors with Average Confidence (AC) error. Lower estimation error is better. See Table 1 for exact numbers and comparison on various types of distribution shift. See Sec. 5 for details on our testbed. + + Recently, numerous methods have been proposed for this purpose (Deng & Zheng, 2021; Chen et al., 2021b; Jiang et al., 2021; Deng et al., 2021; Guillory et al., 2021). These methods either require calibration on the target domain to yield consistent estimates (Jiang et al., 2021; Guillory et al., 2021) or additional labeled data from several target domains to learn a linear regression function on a distributional distance that then predicts model performance (Deng et al., 2021; Deng & Zheng, 2021; Guillory et al., 2021). However, methods that require calibration on the target domain typically yield poor estimates since deep models trained and calibrated on source data are not, in general, calibrated on a (previously unseen) target domain (Ovadia et al., 2019). Besides, methods that leverage labeled data from target domains rely on the fact that unseen target domains exhibit strong linear correlation with seen target domains on the underlying distance measure and, hence, can be rendered ineffective when such target domains with labeled data are unavailable (in Sec. 5.1 we demonstrate such a failure on a real-world distribution shift problem). Therefore, throughout the paper, we assume access to labeled source data and only unlabeled data from target domain(s). + + In this work, we first show that absent assumptions on the source classifier or the nature of the shift, no method of estimating accuracy will work generally (even in non-contrived settings). To estimate accuracy on target domain perfectly, we highlight that even given perfect knowledge of the labeled source distribution (i.e., $p_{s}(x, y)$ ) and unlabeled target distribution (i.e., $p_{t}(x)$ ), we need restrictions on the nature of the shift such that we can uniquely identify the target conditional $p_{t}(y \mid x)$. Thus, in general, identifying the accuracy of the classifier is as hard as identifying the optimal predictor. + + Second, motivated by the superiority of methods that use maximum softmax probability (or logit) of a model for Out-Of-Distribution (OOD) detection (Hendrycks & Gimpel, 2016; Hendrycks et al., 2019), we propose a simple method that leverages softmax probability to predict model performance. Our method, Average Thresholded Confidence (ATC), learns a threshold on a score (e.g., maximum confidence or negative entropy) of model confidence on validation source data and predicts target domain accuracy as the fraction of unlabeled target points that receive a score above that threshold. ATC selects a threshold on validation source data such that the fraction of source examples that receive the score above the threshold match the accuracy of those examples. Our primary contribution in ATC is the proposal of obtaining the threshold and observing its efficacy on (practical) accuracy estimation. Importantly, our work takes a step forward in positively answering the question raised in Deng & Zheng (2021); Deng et al. (2021) about a practical strategy to select a threshold that enables accuracy prediction with thresholded model confidence. + +' + images: + - id: img-0.jpeg + top_left_x: 292 + top_left_y: 217 + bottom_right_x: 1405 + bottom_right_y: 649 + image_base64: '...' + dimensions: + dpi: 200 + height: 2200 + width: 1700 + - index: 3 + markdown: '...' + images: [] + dimensions: {} + - index: 27 + markdown: '![img-8.jpeg](img-8.jpeg) + + Figure 9: Scatter plot of predicted accuracy versus (true) OOD accuracy for vision datasets except MNIST with a ResNet50 model. Results reported by aggregating MAE numbers over 4 different seeds. + +' + images: + - id: img-8.jpeg + top_left_x: 290 + top_left_y: 226 + bottom_right_x: 1405 + bottom_right_y: 1834 + image_base64: '...' + dimensions: + dpi: 200 + height: 2200 + width: 1700 + - index: 28 + markdown: '| Dataset | Shift | IM | | AC | | DOC | | GDE | ATC-MC (Ours) | | ATC-NE (Ours) | | | :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: | | | | Pre T | Post T | Pre T | Post T | Pre T | Post T | Post T | Pre T | Post T | Pre T | Post T | | CIFAR10 | Natural | 6.60 | 5.74 | 9.88 | 6.89 | 7.25 | 6.07 | 4.77 | 3.21 | 3.02 | 2.99 | 2.85 | | | | (0.35) | (0.30) | (0.16) | (0.13) | (0.15) | (0.16) | (0.13) | (0.49) | (0.40) | (0.37) | (0.29) | | | Synthetic | 12.33 | 10.20 | 16.50 | 11.91 | 13.87 | 11.08 | 6.55 | 4.65 | 4.25 | 4.21 | 3.87 | | | | (0.51) | (0.48) | (0.26) | (0.17) | (0.18) | (0.17) | (0.35) | (0.55) | (0.55) | (0.55) | (0.75) | | CIFAR100 | Synthetic | 13.69 | 11.51 | 23.61 | 13.10 | 14.60 | 10.14 | 9.85 | 5.50 | 4.75 | 4.72 | 4.94 | | | | (0.55) | (0.41) | (1.16) | (0.80) | (0.77) | (0.64) | (0.57) | (0.70) | (0.73) | (0.74) | (0.74) | | ImageNet200 | Natural | 12.37 | 8.19 | 22.07 | 8.61 | 15.17 | 7.81 | 5.13 | 4.37 | 2.04 | 3.79 | 1.45 | | | | (0.25) | (0.33) | (0.08) | (0.25) | (0.11) | (0.29) | (0.08) | (0.39) | (0.24) | (0.30) | (0.27) | | | Synthetic | 19.86 | 12.94 | 32.44 | 13.35 | 25.02 | 12.38 | 5.41 | 5.93 | 3.09 | 5.00 | 2.68 | | | | (1.38) | (1.81) | (1.00) | (1.30) | (1.10) | (1.38) | (0.89) | (1.38) | (0.87) | (1.28) | (0.45) | | ImageNet | Natural | 7.77 | 6.50 | 18.13 | 6.02 | 8.13 | 5.76 | 6.23 | 3.88 | 2.17 | 2.06 | 0.80 | | | | (0.27) | (0.33) | (0.23) | (0.34) | (0.27) | (0.37) | (0.41) | (0.53) | (0.62) | (0.54) | (0.44) | | | Synthetic | 13.39 | 10.12 | 24.62 | 8.51 | 13.55 | 7.90 | 6.32 | 3.34 | 2.53 | 2.61 | 4.89 | | | | (0.53) | (0.63) | (0.64) | (0.71) | (0.61) | (0.72) | (0.33) | (0.53) | (0.36) | (0.33) | (0.83) | | FMoW-WILDS | Natural | 5.53 | 4.31 | 33.53 | 12.84 | 5.94 | 4.45 | 5.74 | 3.06 | 2.70 | 3.02 | 2.72 | | | | (0.33) | (0.63) | (0.13) | (12.06) | (0.36) | (0.77) | (0.55) | (0.36) | (0.54) | (0.35) | (0.44) | | RxRx1-WILDS | Natural | 5.80 | 5.72 | 7.90 | 4.84 | 5.98 | 5.98 | 6.03 | 4.66 | 4.56 | 4.41 | 4.47 | | | | (0.17) | (0.15) | (0.24) | (0.09) | (0.15) | (0.13) | (0.08) | (0.38) | (0.38) | (0.31) | (0.26) | | Amazon-WILDS | Natural | 2.40 | 2.29 | 8.01 | 2.38 | 2.40 | 2.28 | 17.87 | 1.65 | 1.62 | 1.60 | 1.59 | | | | (0.08) | (0.09) | (0.53) | (0.17) | (0.09) | (0.09) | (0.18) | (0.06) | (0.05) | (0.14) | (0.15) | | CivilCom.-WILDS | Natural | 12.64 | 10.80 | 16.76 | 11.03 | 13.31 | 10.99 | 16.65 | | 7.14 | | | | | | (0.52) | (0.48) | (0.53) | (0.49) | (0.52) | (0.49) | (0.25) | | (0.41) | | | | MNIST | Natural | 18.48 | 15.99 | 21.17 | 14.81 | 20.19 | 14.56 | 24.42 | 5.02 | 2.40 | 3.14 | 3.50 | | | | (0.45) | (1.53) | (0.24) | (3.89) | (0.23) | (3.47) | (0.41) | (0.44) | (1.83) | (0.49) | (0.17) | | ENTITY-13 | Same | 16.23 | 11.14 | 24.97 | 10.88 | 19.08 | 10.47 | 10.71 | 5.39 | 3.88 | 4.58 | 4.19 | | | | (0.77) | (0.65) | (0.70) | (0.77) | (0.65) | (0.72) | (0.74) | (0.92) | (0.61) | (0.85) | (0.16) | | | Novel | 28.53 | 22.02 | 38.33 | 21.64 | 32.43 | 21.22 | 20.61 | 13.58 | 10.28 | 12.25 | 6.63 | | | | (0.82) | (0.68) | (0.75) | (0.86) | (0.69) | (0.80) | (0.60) | (1.15) | (1.34) | (1.21) | (0.93) | | ENTITY-30 | Same | 18.59 | 14.46 | 28.82 | 14.30 | 21.63 | 13.46 | 12.92 | 9.12 | 7.75 | 8.15 | 7.64 | | | | (0.51) | (0.52) | (0.43) | (0.71) | (0.37) | (0.59) | (0.14) | (0.62) | (0.72) | (0.68) | (0.88) | | | Novel | 32.34 | 26.85 | 44.02 | 26.27 | 36.82 | 25.42 | 23.16 | 17.75 | 14.30 | 15.60 | 10.57 | | | | (0.60) | (0.58) | (0.56) | (0.79) | (0.47) | (0.68) | (0.12) | (0.76) | (0.85) | (0.86) | (0.86) | | NONLIVING-26 | Same | 18.66 | 17.17 | 26.39 | 16.14 | 19.86 | 15.58 | 16.63 | 10.87 | 10.24 | 10.07 | 10.26 | | | | (0.76) | (0.74) | (0.82) | (0.81) | (0.67) | (0.76) | (0.45) | (0.98) | (0.83) | (0.92) | (1.18) | | | Novel | 33.43 | 31.53 | 41.66 | 29.87 | 35.13 | 29.31 | 29.56 | 21.70 | 20.12 | 19.08 | 18.26 | | | | (0.67) | (0.65) | (0.67) | (0.71) | (0.54) | (0.64) | (0.21) | (0.86) | (0.75) | (0.82) | (1.12) | | LIVING-17 | Same | 12.63 | 11.05 | 18.32 | 10.46 | 14.43 | 10.14 | 9.87 | 4.57 | 3.95 | 3.81 | 4.21 | | | | (1.25) | (1.20) | (1.01) | (1.12) | (1.11) | (1.16) | (0.61) | (0.71) | (0.48) | (0.22) | (0.53) | | | Novel | 29.03 | 26.96 | 35.67 | 26.11 | 31.73 | 25.73 | 23.53 | 16.15 | 14.49 | 12.97 | 11.39 | | | | (1.44) | (1.38) | (1.09) | (1.27) | (1.19) | (1.35) | (0.52) | (1.36) | (1.46) | (1.52) | (1.72) | + + Table 3: Mean Absolute estimation Error (MAE) results for different datasets in our setup grouped by the nature of shift. ''Same'' refers to same subpopulation shifts and ''Novel'' refers novel subpopulation shifts. We include details about the target sets considered in each shift in Table 2. Post T denotes use of TS calibration on source. For language datasets, we use DistilBERT-base-uncased, for vision dataset we report results with DenseNet model with the exception of MNIST where we use FCN. Across all datasets, we observe that ATC achieves superior performance (lower MAE is better). For GDE post T and pre T estimates match since TS doesn''t alter the argmax prediction. Results reported by aggregating MAE numbers over 4 different seeds. Values in parenthesis (i.e., $(\cdot)$ ) denote standard deviation values. + +' + images: [] + dimensions: + dpi: 200 + height: 2200 + width: 1700 + - index: 29 + markdown: '| Dataset | Shift | IM | | AC | | DOC | | GDE | ATC-MC (Ours) | | ATC-NE (Ours) | | | :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: | | | | Pre T | Post T | Pre T | Post T | Pre T | Post T | Post T | Pre T | Post T | Pre T | Post T | | CIFAR10 | Natural | 7.14 | 6.20 | 10.25 | 7.06 | 7.68 | 6.35 | 5.74 | 4.02 | 3.85 | 3.76 | 3.38 | | | | (0.14) | (0.11) | (0.31) | (0.33) | (0.28) | (0.27) | (0.25) | (0.38) | (0.30) | (0.33) | (0.32) | | | Synthetic | 12.62 | 10.75 | 16.50 | 11.91 | 13.93 | 11.20 | 7.97 | 5.66 | 5.03 | 4.87 | 3.63 | | | | (0.76) | (0.71) | (0.28) | (0.24) | (0.29) | (0.28) | (0.13) | (0.64) | (0.71) | (0.71) | (0.62) | | CIFAR100 | Synthetic | 12.77 | 12.34 | 16.89 | 12.73 | 11.18 | 9.63 | 12.00 | 5.61 | 5.55 | 5.65 | 5.76 | | | | (0.43) | (0.68) | (0.20) | (2.59) | (0.35) | (1.25) | (0.48) | (0.51) | (0.55) | (0.35) | (0.27) | | ImageNet200 | Natural | 12.63 | 7.99 | 23.08 | 7.22 | 15.40 | 6.33 | 5.00 | 4.60 | 1.80 | 4.06 | 1.38 | | | | (0.59) | (0.47) | (0.31) | (0.22) | (0.42) | (0.24) | (0.36) | (0.63) | (0.17) | (0.69) | (0.29) | | | Synthetic | 20.17 | 11.74 | 33.69 | 9.51 | 25.49 | 8.61 | 4.19 | 5.37 | 2.78 | 4.53 | 3.58 | | | | (0.74) | (0.80) | (0.73) | (0.51) | (0.66) | (0.50) | (0.14) | (0.88) | (0.23) | (0.79) | (0.33) | | ImageNet | Natural | 8.09 | 6.42 | 21.66 | 5.91 | 8.53 | 5.21 | 5.90 | 3.93 | 1.89 | 2.45 | 0.73 | | | | (0.25) | (0.28) | (0.38) | (0.22) | (0.26) | (0.25) | (0.44) | (0.26) | (0.21) | (0.16) | (0.10) | | | Synthetic | 13.93 | 9.90 | 28.05 | 7.56 | 13.82 | 6.19 | 6.70 | 3.33 | 2.55 | 2.12 | 5.06 | | | | (0.14) | (0.23) | (0.39) | (0.13) | (0.31) | (0.07) | (0.52) | (0.25) | (0.25) | (0.31) | (0.27) | | FMoW-WILDS | Natural | 5.15 | 3.55 | 34.64 | 5.03 | 5.58 | 3.46 | 5.08 | 2.59 | 2.33 | 2.52 | 2.22 | | | | (0.19) | (0.41) | (0.22) | (0.29) | (0.17) | (0.37) | (0.46) | (0.32) | (0.28) | (0.25) | (0.30) | | RxRx1-WILDS | Natural | 6.17 | 6.11 | 21.05 | 5.21 | 6.54 | 6.27 | 6.82 | 5.30 | 5.20 | 5.19 | 5.63 | | | | (0.20) | (0.24) | (0.31) | (0.18) | (0.21) | (0.20) | (0.31) | (0.30) | (0.44) | (0.43) | (0.55) | | Entity-13 | Same | 18.32 | 14.38 | 27.79 | 13.56 | 20.50 | 13.22 | 16.09 | 9.35 | 7.50 | 7.80 | 6.94 | | | | (0.29) | (0.53) | (1.18) | (0.58) | (0.47) | (0.58) | (0.84) | (0.79) | (0.65) | (0.62) | (0.71) | | | Novel | 28.82 | 24.03 | 38.97 | 22.96 | 31.66 | 22.61 | 25.26 | 17.11 | 13.96 | 14.75 | 9.94 | | | | (0.30) | (0.55) | (1.32) | (0.59) | (0.54) | (0.58) | (1.08) | (0.93) | (0.64) | (0.78) | | | Entity-30 | Same | 16.91 | 14.61 | 26.84 | 14.37 | 18.60 | 13.11 | 13.74 | 8.54 | 7.94 | 7.77 | 8.04 | | | | (1.33) | (1.11) | (2.15) | (1.34) | (1.69) | (1.30) | (1.07) | (1.47) | (1.38) | (1.44) | (1.51) | | | Novel | 28.66 | 25.83 | 39.21 | 25.03 | 30.95 | 23.73 | 23.15 | 15.57 | 13.24 | 12.44 | 11.05 | | | | (1.16) | (0.88) | (2.03) | (1.11) | (1.64) | (1.11) | (0.51) | (1.44) | (1.15) | (1.26) | (1.13) | | NonLIVING-26 | Same | 17.43 | 15.95 | 27.70 | 15.40 | 18.06 | 14.58 | 16.99 | 10.79 | 10.13 | 10.05 | 10.29 | | | | (0.90) | (0.86) | (0.90) | (0.69) | (1.00) | (0.78) | (1.25) | (0.62) | (0.32) | (0.46) | (0.79) | | | Novel | 29.51 | 27.75 | 40.02 | 26.77 | 30.36 | 25.93 | 27.70 | 19.64 | 17.75 | 16.90 | 15.69 | | | | (0.86) | (0.82) | (0.76) | (0.82) | (0.95) | (0.80) | (1.42) | (0.68) | (0.53) | (0.60) | (0.83) | | LIVING-17 | Same | 14.28 | 12.21 | 23.46 | 11.16 | 15.22 | 10.78 | 10.49 | 4.92 | 4.23 | 4.19 | 4.73 | | | | (0.96) | (0.93) | (1.16) | (0.90) | (0.96) | (0.99) | (0.97) | (0.57) | (0.42) | (0.35) | (0.24) | | | Novel | 28.91 | 26.35 | 38.62 | 24.91 | 30.32 | 24.52 | 22.49 | 15.42 | 13.02 | 12.29 | 10.34 | | | | (0.66) | (0.73) | (1.01) | (0.61) | (0.59) | (0.74) | (0.85) | (0.59) | (0.53) | (0.73) | (0.62) | + + Table 4: Mean Absolute estimation Error (MAE) results for different datasets in our setup grouped by the nature of shift for ResNet model. ''Same'' refers to same subpopulation shifts and ''Novel'' refers novel subpopulation shifts. We include details about the target sets considered in each shift in Table 2. Post T denotes use of TS calibration on source. Across all datasets, we observe that ATC achieves superior performance (lower MAE is better). For GDE post T and pre T estimates match since TS doesn''t alter the argmax prediction. Results reported by aggregating MAE numbers over 4 different seeds. Values in parenthesis (i.e., $(\cdot)$ ) denote standard deviation values. + +' + images: [] + dimensions: + dpi: 200 + height: 2200 + width: 1700 + model: mistral-ocr-2503-completion + usage_info: + pages_processed: 29 + doc_size_bytes: null + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/classifications: + post: + operationId: classifications_v1_classifications_post + summary: Classifications + tags: + - classifiers + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ClassificationRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ClassificationResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/chat/classifications: + post: + operationId: chat_classifications_v1_chat_classifications_post + summary: Chat Classifications + tags: + - classifiers + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ChatClassificationRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ClassificationResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/audio/transcriptions: + post: + operationId: audio_api_v1_transcriptions_post + summary: Create Transcription + tags: + - audio.transcriptions + requestBody: + content: + multipart/form-data: + schema: + $ref: '#/components/schemas/AudioTranscriptionRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/TranscriptionResponse' + examples: + userExample: + value: + model: voxtral-mini-2507 + text: 'This week, I traveled to Chicago to deliver my final farewell address to the nation, following in the tradition of presidents before me. It was an opportunity to say thank you. Whether we''ve seen eye to eye or rarely agreed at all, my conversations with you, the American people, in living rooms, in schools, at farms and on factory floors, at diners and on distant military outposts, All these conversations are what have kept me honest, kept me inspired, and kept me going. Every day, I learned from you. You made me a better President, and you made me a better man. + + Over the course of these eight years, I''ve seen the goodness, the resilience, and the hope of the American people. I''ve seen neighbors looking out for each other as we rescued our economy from the worst crisis of our lifetimes. I''ve hugged cancer survivors who finally know the security of affordable health care. I''ve seen communities like Joplin rebuild from disaster, and cities like Boston show the world that no terrorist will ever break the American spirit. I''ve seen the hopeful faces of young graduates and our newest military officers. I''ve mourned with grieving families searching for answers. And I found grace in a Charleston church. I''ve seen our scientists help a paralyzed man regain his sense of touch, and our wounded warriors walk again. I''ve seen our doctors and volunteers rebuild after earthquakes and stop pandemics in their tracks. I''ve learned from students who are building robots and curing diseases, and who will change the world in ways we can''t even imagine. I''ve seen the youngest of children remind us of our obligations to care for our refugees, to work in peace, and above all, to look out for each other. + + That''s what''s possible when we come together in the slow, hard, sometimes frustrating, but always vital work of self-government. But we can''t take our democracy for granted. All of us, regardless of party, should throw ourselves into the work of citizenship. Not just when there is an election. Not just when our own narrow interest is at stake. But over the full span of a lifetime. If you''re tired of arguing with strangers on the Internet, try to talk with one in real life. If something needs fixing, lace up your shoes and do some organizing. If you''re disappointed by your elected officials, then grab a clipboard, get some signatures, and run for office yourself. + + Our success depends on our participation, regardless of which way the pendulum of power swings. It falls on each of us to be guardians of our democracy, to embrace the joyous task we''ve been given to continually try to improve this great nation of ours. Because for all our outward differences, we all share the same proud title – citizen. + + It has been the honor of my life to serve you as President. Eight years later, I am even more optimistic about our country''s promise. And I look forward to working along your side as a citizen for all my days that remain. + + Thanks, everybody. God bless you. And God bless the United States of America. + +' + language: en + segments: [] + usage: + prompt_audio_seconds: 203 + prompt_tokens: 4 + total_tokens: 3264 + completion_tokens: 635 + /v1/audio/transcriptions#stream: + post: + operationId: audio_api_v1_transcriptions_post_stream + summary: Create Streaming Transcription (SSE) + tags: + - audio.transcriptions + requestBody: + content: + multipart/form-data: + schema: + $ref: '#/components/schemas/AudioTranscriptionRequestStream' + required: true + responses: + '200': + description: Stream of transcription events + content: + text/event-stream: + schema: + $ref: '#/components/schemas/TranscriptionStreamEvents' + /v1/libraries: + get: + operationId: libraries_list_v1 + summary: List all libraries you have access to. + description: List all libraries that you have created or have been shared with you. + tags: + - beta.libraries + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ListLibraryOut' + post: + operationId: libraries_create_v1 + summary: Create a new Library. + description: Create a new Library, you will be marked as the owner and only you will have the possibility to share it with others. When first created this will only be accessible by you. + tags: + - beta.libraries + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LibraryIn' + required: true + responses: + '201': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/LibraryOut' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/libraries/{library_id}: + get: + operationId: libraries_get_v1 + summary: Detailed information about a specific Library. + description: Given a library id, details information about that Library. + tags: + - beta.libraries + parameters: + - name: library_id + in: path + required: true + schema: + type: string + title: Library Id + format: uuid + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/LibraryOut' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + delete: + operationId: libraries_delete_v1 + summary: Delete a library and all of it's document. + description: Given a library id, deletes it together with all documents that have been uploaded to that library. + tags: + - beta.libraries + parameters: + - name: library_id + in: path + required: true + schema: + type: string + title: Library Id + format: uuid + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/LibraryOut' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + put: + operationId: libraries_update_v1 + summary: Update a library. + description: Given a library id, you can update the name and description. + tags: + - beta.libraries + parameters: + - name: library_id + in: path + required: true + schema: + type: string + title: Library Id + format: uuid + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LibraryInUpdate' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/LibraryOut' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/libraries/{library_id}/documents: + get: + operationId: libraries_documents_list_v1 + summary: List documents in a given library. + description: Given a library, lists the document that have been uploaded to that library. + tags: + - beta.libraries.documents + parameters: + - name: library_id + in: path + required: true + schema: + type: string + title: Library Id + format: uuid + - name: search + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Search + - name: page_size + in: query + required: false + schema: + type: integer + title: Page Size + maximum: 100 + minimum: 1 + default: 100 + - name: page + in: query + required: false + schema: + type: integer + title: Page + minimum: 0 + default: 0 + - name: filters_attributes + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Filters Attributes + - name: sort_by + in: query + required: false + schema: + type: string + title: Sort By + default: created_at + - name: sort_order + in: query + required: false + schema: + type: string + title: Sort Order + default: desc + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ListDocumentOut' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + post: + operationId: libraries_documents_upload_v1 + summary: Upload a new document. + description: Given a library, upload a new document to that library. It is queued for processing, it status will change it has been processed. The processing has to be completed in order be discoverable for the library search + tags: + - beta.libraries.documents + parameters: + - name: library_id + in: path + required: true + schema: + type: string + title: Library Id + format: uuid + requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + file: + $ref: '#/components/schemas/File' + title: DocumentUpload + required: + - file + required: true + responses: + '201': + description: Upload successful, returns the created document information's. + content: + application/json: + schema: + $ref: '#/components/schemas/DocumentOut' + '200': + description: A document with the same hash was found in this library. Returns the existing document. + content: + application/json: + schema: + $ref: '#/components/schemas/DocumentOut' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/libraries/{library_id}/documents/{document_id}: + get: + operationId: libraries_documents_get_v1 + summary: Retrieve the metadata of a specific document. + description: Given a library and a document in this library, you can retrieve the metadata of that document. + tags: + - beta.libraries.documents + parameters: + - name: library_id + in: path + required: true + schema: + type: string + title: Library Id + format: uuid + - name: document_id + in: path + required: true + schema: + type: string + title: Document Id + format: uuid + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/DocumentOut' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + put: + operationId: libraries_documents_update_v1 + summary: Update the metadata of a specific document. + description: Given a library and a document in that library, update the name of that document. + tags: + - beta.libraries.documents + parameters: + - name: library_id + in: path + required: true + schema: + type: string + title: Library Id + format: uuid + - name: document_id + in: path + required: true + schema: + type: string + title: Document Id + format: uuid + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/DocumentUpdateIn' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/DocumentOut' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + delete: + operationId: libraries_documents_delete_v1 + summary: Delete a document. + description: Given a library and a document in that library, delete that document. The document will be deleted from the library and the search index. + tags: + - beta.libraries.documents + parameters: + - name: library_id + in: path + required: true + schema: + type: string + title: Library Id + format: uuid + - name: document_id + in: path + required: true + schema: + type: string + title: Document Id + format: uuid + responses: + '204': + description: Successful Response + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/libraries/{library_id}/documents/{document_id}/text_content: + get: + operationId: libraries_documents_get_text_content_v1 + summary: Retrieve the text content of a specific document. + description: Given a library and a document in that library, you can retrieve the text content of that document if it exists. For documents like pdf, docx and pptx the text content results from our processing using Mistral OCR. + tags: + - beta.libraries.documents + parameters: + - name: library_id + in: path + required: true + schema: + type: string + title: Library Id + format: uuid + - name: document_id + in: path + required: true + schema: + type: string + title: Document Id + format: uuid + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/DocumentTextContent' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/libraries/{library_id}/documents/{document_id}/status: + get: + operationId: libraries_documents_get_status_v1 + summary: Retrieve the processing status of a specific document. + description: Given a library and a document in that library, retrieve the processing status of that document. + tags: + - beta.libraries.documents + parameters: + - name: library_id + in: path + required: true + schema: + type: string + title: Library Id + format: uuid + - name: document_id + in: path + required: true + schema: + type: string + title: Document Id + format: uuid + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ProcessingStatusOut' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/libraries/{library_id}/documents/{document_id}/signed-url: + get: + operationId: libraries_documents_get_signed_url_v1 + summary: Retrieve the signed URL of a specific document. + description: Given a library and a document in that library, retrieve the signed URL of a specific document.The url will expire after 30 minutes and can be accessed by anyone with the link. + tags: + - beta.libraries.documents + parameters: + - name: library_id + in: path + required: true + schema: + type: string + title: Library Id + format: uuid + - name: document_id + in: path + required: true + schema: + type: string + title: Document Id + format: uuid + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: string + title: Response Libraries Documents Get Signed Url V1 + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/libraries/{library_id}/documents/{document_id}/extracted-text-signed-url: + get: + operationId: libraries_documents_get_extracted_text_signed_url_v1 + summary: Retrieve the signed URL of text extracted from a given document. + description: Given a library and a document in that library, retrieve the signed URL of text extracted. For documents that are sent to the OCR this returns the result of the OCR queries. + tags: + - beta.libraries.documents + parameters: + - name: library_id + in: path + required: true + schema: + type: string + title: Library Id + format: uuid + - name: document_id + in: path + required: true + schema: + type: string + title: Document Id + format: uuid + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: string + title: Response Libraries Documents Get Extracted Text Signed Url V1 + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/libraries/{library_id}/documents/{document_id}/reprocess: + post: + operationId: libraries_documents_reprocess_v1 + summary: Reprocess a document. + description: Given a library and a document in that library, reprocess that document, it will be billed again. + tags: + - beta.libraries.documents + parameters: + - name: library_id + in: path + required: true + schema: + type: string + title: Library Id + format: uuid + - name: document_id + in: path + required: true + schema: + type: string + title: Document Id + format: uuid + responses: + '204': + description: Successful Response + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /v1/libraries/{library_id}/share: + get: + operationId: libraries_share_list_v1 + summary: List all of the access to this library. + description: Given a library, list all of the Entity that have access and to what level. + tags: + - beta.libraries.accesses + parameters: + - name: library_id + in: path + required: true + schema: + type: string + title: Library Id + format: uuid + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ListSharingOut' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + put: + operationId: libraries_share_create_v1 + summary: Create or update an access level. + description: Given a library id, you can create or update the access level of an entity. You have to be owner of the library to share a library. An owner cannot change their own role. A library cannot be shared outside of the organization. + tags: + - beta.libraries.accesses + parameters: + - name: library_id + in: path + required: true + schema: + type: string + title: Library Id + format: uuid + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SharingIn' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/SharingOut' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + delete: + operationId: libraries_share_delete_v1 + summary: Delete an access level. + description: Given a library id, you can delete the access level of an entity. An owner cannot delete it's own access. You have to be the owner of the library to delete an acces other than yours. + tags: + - beta.libraries.accesses + parameters: + - name: library_id + in: path + required: true + schema: + type: string + title: Library Id + format: uuid + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SharingDelete' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/SharingOut' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' +components: + schemas: + BaseModelCard: + properties: + id: + type: string + title: Id + object: + type: string + title: Object + default: model + created: + type: integer + title: Created + owned_by: + type: string + title: Owned By + default: mistralai + capabilities: + $ref: '#/components/schemas/ModelCapabilities' + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: + anyOf: + - type: string + - type: 'null' + title: Description + max_context_length: + type: integer + title: Max Context Length + default: 32768 + aliases: + items: + type: string + type: array + title: Aliases + default: [] + deprecation: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Deprecation + deprecation_replacement_model: + anyOf: + - type: string + - type: 'null' + title: Deprecation Replacement Model + default_model_temperature: + anyOf: + - type: number + - type: 'null' + title: Default Model Temperature + type: + type: string + const: base + title: Type + default: base + type: object + required: + - id + - capabilities + title: BaseModelCard + DeleteModelOut: + properties: + id: + type: string + title: Id + description: The ID of the deleted model. + examples: + - ft:open-mistral-7b:587a6b29:20240514:7e773925 + object: + type: string + title: Object + default: model + description: The object type that was deleted + deleted: + type: boolean + title: Deleted + default: true + description: The deletion status + examples: + - true + type: object + required: + - id + title: DeleteModelOut + FTModelCard: + properties: + id: + type: string + title: Id + object: + type: string + title: Object + default: model + created: + type: integer + title: Created + owned_by: + type: string + title: Owned By + default: mistralai + capabilities: + $ref: '#/components/schemas/ModelCapabilities' + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: + anyOf: + - type: string + - type: 'null' + title: Description + max_context_length: + type: integer + title: Max Context Length + default: 32768 + aliases: + items: + type: string + type: array + title: Aliases + default: [] + deprecation: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Deprecation + deprecation_replacement_model: + anyOf: + - type: string + - type: 'null' + title: Deprecation Replacement Model + default_model_temperature: + anyOf: + - type: number + - type: 'null' + title: Default Model Temperature + type: + type: string + const: fine-tuned + title: Type + default: fine-tuned + job: + type: string + title: Job + root: + type: string + title: Root + archived: + type: boolean + title: Archived + default: false + type: object + required: + - id + - capabilities + - job + - root + title: FTModelCard + description: Extra fields for fine-tuned models. + HTTPValidationError: + properties: + detail: + items: + $ref: '#/components/schemas/ValidationError' + type: array + title: Detail + type: object + title: HTTPValidationError + ModelCapabilities: + properties: + completion_chat: + type: boolean + title: Completion Chat + default: false + function_calling: + type: boolean + title: Function Calling + default: false + completion_fim: + type: boolean + title: Completion Fim + default: false + fine_tuning: + type: boolean + title: Fine Tuning + default: false + vision: + type: boolean + title: Vision + default: false + ocr: + type: boolean + title: Ocr + default: false + classification: + type: boolean + title: Classification + default: false + moderation: + type: boolean + title: Moderation + default: false + audio: + type: boolean + title: Audio + default: false + audio_transcription: + type: boolean + title: Audio Transcription + default: false + type: object + title: ModelCapabilities + ModelList: + properties: + object: + type: string + title: Object + default: list + data: + items: + oneOf: + - $ref: '#/components/schemas/BaseModelCard' + - $ref: '#/components/schemas/FTModelCard' + discriminator: + propertyName: type + mapping: + base: '#/components/schemas/BaseModelCard' + fine-tuned: '#/components/schemas/FTModelCard' + type: array + title: Data + type: object + title: ModelList + ValidationError: + properties: + loc: + items: + anyOf: + - type: string + - type: integer + type: array + title: Location + msg: + type: string + title: Message + type: + type: string + title: Error Type + input: + title: Input + ctx: + type: object + title: Context + type: object + required: + - loc + - msg + - type + title: ValidationError + APIKeyAuth: + type: object + properties: + type: + type: string + title: Type + enum: + - api-key + default: api-key + value: + type: string + title: Value + title: APIKeyAuth + required: + - value + additionalProperties: false + Agent: + type: object + properties: + instructions: + anyOf: + - type: string + - type: 'null' + title: Instructions + description: Instruction prompt the model will follow during the conversation. + tools: + type: array + items: + oneOf: + - $ref: '#/components/schemas/FunctionTool' + - $ref: '#/components/schemas/WebSearchTool' + - $ref: '#/components/schemas/WebSearchPremiumTool' + - $ref: '#/components/schemas/CodeInterpreterTool' + - $ref: '#/components/schemas/ImageGenerationTool' + - $ref: '#/components/schemas/DocumentLibraryTool' + - $ref: '#/components/schemas/CustomConnector' + discriminator: + propertyName: type + mapping: + code_interpreter: '#/components/schemas/CodeInterpreterTool' + connector: '#/components/schemas/CustomConnector' + document_library: '#/components/schemas/DocumentLibraryTool' + function: '#/components/schemas/FunctionTool' + image_generation: '#/components/schemas/ImageGenerationTool' + web_search: '#/components/schemas/WebSearchTool' + web_search_premium: '#/components/schemas/WebSearchPremiumTool' + title: Tools + description: List of tools which are available to the model during the conversation. + completion_args: + $ref: '#/components/schemas/CompletionArgs' + description: Completion arguments that will be used to generate assistant responses. Can be overridden at each message request. + guardrails: + anyOf: + - type: array + items: + $ref: '#/components/schemas/GuardrailConfig' + - type: 'null' + title: Guardrails + model: + type: string + title: Model + name: + type: string + title: Name + description: + anyOf: + - type: string + - type: 'null' + title: Description + handoffs: + anyOf: + - type: array + items: + type: string + minItems: 1 + - type: 'null' + title: Handoffs + metadata: + anyOf: + - $ref: '#/components/schemas/MetadataDict' + - type: 'null' + object: + type: string + title: Object + default: agent + const: agent + id: + type: string + title: Id + version: + type: integer + title: Version + versions: + type: array + items: + type: integer + title: Versions + created_at: + type: string + title: Created At + format: date-time + updated_at: + type: string + title: Updated At + format: date-time + deployment_chat: + type: boolean + title: Deployment Chat + source: + type: string + title: Source + version_message: + anyOf: + - type: string + - type: 'null' + title: Version Message + title: Agent + required: + - model + - name + - id + - version + - versions + - created_at + - updated_at + - deployment_chat + - source + additionalProperties: false + AgentAliasResponse: + type: object + properties: + alias: + type: string + title: Alias + version: + type: integer + title: Version + created_at: + type: string + title: Created At + format: date-time + updated_at: + type: string + title: Updated At + format: date-time + title: AgentAliasResponse + required: + - alias + - version + - created_at + - updated_at + additionalProperties: false + AgentConversation: + type: object + properties: + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: Name given to the conversation. + description: + anyOf: + - type: string + - type: 'null' + title: Description + description: Description of the what the conversation is about. + metadata: + anyOf: + - $ref: '#/components/schemas/MetadataDict' + - type: 'null' + description: Custom metadata for the conversation. + object: + type: string + title: Object + default: conversation + const: conversation + id: + type: string + title: Id + created_at: + type: string + title: Created At + format: date-time + updated_at: + type: string + title: Updated At + format: date-time + agent_id: + type: string + title: Agent Id + agent_version: + anyOf: + - type: string + - type: integer + - type: 'null' + title: Agent Version + title: AgentConversation + required: + - id + - created_at + - updated_at + - agent_id + additionalProperties: false + AgentCreationRequest: + type: object + properties: + instructions: + anyOf: + - type: string + - type: 'null' + title: Instructions + description: Instruction prompt the model will follow during the conversation. + tools: + type: array + items: + oneOf: + - $ref: '#/components/schemas/FunctionTool' + - $ref: '#/components/schemas/WebSearchTool' + - $ref: '#/components/schemas/WebSearchPremiumTool' + - $ref: '#/components/schemas/CodeInterpreterTool' + - $ref: '#/components/schemas/ImageGenerationTool' + - $ref: '#/components/schemas/DocumentLibraryTool' + - $ref: '#/components/schemas/CustomConnector' + discriminator: + propertyName: type + mapping: + code_interpreter: '#/components/schemas/CodeInterpreterTool' + connector: '#/components/schemas/CustomConnector' + document_library: '#/components/schemas/DocumentLibraryTool' + function: '#/components/schemas/FunctionTool' + image_generation: '#/components/schemas/ImageGenerationTool' + web_search: '#/components/schemas/WebSearchTool' + web_search_premium: '#/components/schemas/WebSearchPremiumTool' + title: Tools + description: List of tools which are available to the model during the conversation. + completion_args: + $ref: '#/components/schemas/CompletionArgs' + description: Completion arguments that will be used to generate assistant responses. Can be overridden at each message request. + guardrails: + anyOf: + - type: array + items: + $ref: '#/components/schemas/GuardrailConfig' + - type: 'null' + title: Guardrails + model: + type: string + title: Model + name: + type: string + title: Name + description: + anyOf: + - type: string + - type: 'null' + title: Description + handoffs: + anyOf: + - type: array + items: + type: string + minItems: 1 + - type: 'null' + title: Handoffs + metadata: + anyOf: + - $ref: '#/components/schemas/MetadataDict' + - type: 'null' + version_message: + anyOf: + - type: string + maxLength: 500 + - type: 'null' + title: Version Message + title: AgentCreationRequest + required: + - model + - name + additionalProperties: false + AgentHandoffEntry: + type: object + properties: + object: + type: string + title: Object + default: entry + const: entry + type: + type: string + title: Type + default: agent.handoff + const: agent.handoff + created_at: + type: string + title: Created At + format: date-time + completed_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Completed At + id: + type: string + title: Id + previous_agent_id: + type: string + title: Previous Agent Id + previous_agent_name: + type: string + title: Previous Agent Name + next_agent_id: + type: string + title: Next Agent Id + next_agent_name: + type: string + title: Next Agent Name + title: AgentHandoffEntry + required: + - previous_agent_id + - previous_agent_name + - next_agent_id + - next_agent_name + additionalProperties: false + AgentUpdateRequest: + type: object + properties: + instructions: + anyOf: + - type: string + - type: 'null' + title: Instructions + description: Instruction prompt the model will follow during the conversation. + tools: + type: array + items: + oneOf: + - $ref: '#/components/schemas/FunctionTool' + - $ref: '#/components/schemas/WebSearchTool' + - $ref: '#/components/schemas/WebSearchPremiumTool' + - $ref: '#/components/schemas/CodeInterpreterTool' + - $ref: '#/components/schemas/ImageGenerationTool' + - $ref: '#/components/schemas/DocumentLibraryTool' + - $ref: '#/components/schemas/CustomConnector' + discriminator: + propertyName: type + mapping: + code_interpreter: '#/components/schemas/CodeInterpreterTool' + connector: '#/components/schemas/CustomConnector' + document_library: '#/components/schemas/DocumentLibraryTool' + function: '#/components/schemas/FunctionTool' + image_generation: '#/components/schemas/ImageGenerationTool' + web_search: '#/components/schemas/WebSearchTool' + web_search_premium: '#/components/schemas/WebSearchPremiumTool' + title: Tools + description: List of tools which are available to the model during the conversation. + completion_args: + $ref: '#/components/schemas/CompletionArgs' + description: Completion arguments that will be used to generate assistant responses. Can be overridden at each message request. + guardrails: + anyOf: + - type: array + items: + $ref: '#/components/schemas/GuardrailConfig' + - type: 'null' + title: Guardrails + model: + anyOf: + - type: string + - type: 'null' + title: Model + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: + anyOf: + - type: string + - type: 'null' + title: Description + handoffs: + anyOf: + - type: array + items: + type: string + minItems: 1 + - type: 'null' + title: Handoffs + deployment_chat: + anyOf: + - type: boolean + - type: 'null' + title: Deployment Chat + metadata: + anyOf: + - $ref: '#/components/schemas/MetadataDict' + - type: 'null' + version_message: + anyOf: + - type: string + maxLength: 500 + - type: 'null' + title: Version Message + title: AgentUpdateRequest + additionalProperties: false + BuiltInConnectors: + type: string + title: BuiltInConnectors + enum: + - web_search + - web_search_premium + - code_interpreter + - image_generation + - document_library + CodeInterpreterTool: + type: object + properties: + tool_configuration: + anyOf: + - $ref: '#/components/schemas/ToolConfiguration' + - type: 'null' + type: + type: string + title: Type + enum: + - code_interpreter + default: code_interpreter + title: CodeInterpreterTool + additionalProperties: false + CompletionArgs: + type: object + properties: + stop: + $ref: '#/components/schemas/CompletionArgsStop' + presence_penalty: + anyOf: + - type: number + maximum: 2 + minimum: -2 + - type: 'null' + title: Presence Penalty + frequency_penalty: + anyOf: + - type: number + maximum: 2 + minimum: -2 + - type: 'null' + title: Frequency Penalty + temperature: + anyOf: + - type: number + maximum: 1 + minimum: 0 + - type: 'null' + title: Temperature + top_p: + anyOf: + - type: number + maximum: 1 + minimum: 0 + - type: 'null' + title: Top P + max_tokens: + anyOf: + - type: integer + minimum: 0 + - type: 'null' + title: Max Tokens + random_seed: + anyOf: + - type: integer + minimum: 0 + - type: 'null' + title: Random Seed + prediction: + anyOf: + - $ref: '#/components/schemas/Prediction' + - type: 'null' + response_format: + anyOf: + - $ref: '#/components/schemas/ResponseFormat' + - type: 'null' + tool_choice: + $ref: '#/components/schemas/ToolChoiceEnum' + default: auto + reasoning_effort: + anyOf: + - type: string + enum: + - high + - none + - type: 'null' + description: Controls the reasoning effort level for reasoning models. "high" enables comprehensive reasoning traces, "none" disables reasoning effort. + title: CompletionArgs + additionalProperties: false + description: White-listed arguments from the completion API + ConversationAppendRequest: + allOf: + - $ref: '#/components/schemas/ConversationAppendRequestBase' + - type: object + properties: + stream: + type: boolean + enum: + - false + default: false + ConversationHistory: + type: object + properties: + object: + type: string + title: Object + default: conversation.history + const: conversation.history + conversation_id: + type: string + title: Conversation Id + entries: + type: array + items: + anyOf: + - $ref: '#/components/schemas/MessageInputEntry' + - $ref: '#/components/schemas/MessageOutputEntry' + - $ref: '#/components/schemas/FunctionResultEntry' + - $ref: '#/components/schemas/FunctionCallEntry' + - $ref: '#/components/schemas/ToolExecutionEntry' + - $ref: '#/components/schemas/AgentHandoffEntry' + title: Entries + title: ConversationHistory + required: + - conversation_id + - entries + additionalProperties: false + description: Retrieve all entries in a conversation. + ConversationMessages: + type: object + properties: + object: + type: string + title: Object + default: conversation.messages + const: conversation.messages + conversation_id: + type: string + title: Conversation Id + messages: + $ref: '#/components/schemas/MessageEntries' + title: ConversationMessages + required: + - conversation_id + - messages + additionalProperties: false + description: Similar to the conversation history but only keep the messages + ConversationRestartRequest: + allOf: + - $ref: '#/components/schemas/ConversationRestartRequestBase' + - type: object + properties: + stream: + type: boolean + enum: + - false + default: false + CustomConnector: + type: object + properties: + type: + type: string + title: Type + enum: + - connector + default: connector + connector_id: + type: string + title: Connector Id + authorization: + anyOf: + - oneOf: + - $ref: '#/components/schemas/OAuth2TokenAuth' + - $ref: '#/components/schemas/APIKeyAuth' + discriminator: + propertyName: type + mapping: + api-key: '#/components/schemas/APIKeyAuth' + oauth2-token: '#/components/schemas/OAuth2TokenAuth' + - type: 'null' + title: Authorization + tool_configuration: + anyOf: + - $ref: '#/components/schemas/ToolConfiguration' + - type: 'null' + title: CustomConnector + required: + - connector_id + additionalProperties: false + DocumentLibraryTool: + type: object + properties: + tool_configuration: + anyOf: + - $ref: '#/components/schemas/ToolConfiguration' + - type: 'null' + type: + type: string + title: Type + enum: + - document_library + default: document_library + library_ids: + type: array + items: + type: string + title: Library Ids + minItems: 1 + description: Ids of the library in which to search. + title: DocumentLibraryTool + required: + - library_ids + additionalProperties: false + DocumentURLChunk: + type: object + properties: + type: + type: string + title: Type + default: document_url + const: document_url + document_url: + type: string + title: Document Url + document_name: + anyOf: + - type: string + - type: 'null' + title: Document Name + description: The filename of the document + title: DocumentURLChunk + required: + - document_url + additionalProperties: false + Function: + type: object + properties: + name: + type: string + title: Name + description: + type: string + title: Description + default: '' + strict: + type: boolean + title: Strict + default: false + parameters: + type: object + title: Parameters + additionalProperties: true + title: Function + required: + - name + - parameters + additionalProperties: false + FunctionCallEntry: + type: object + properties: + object: + type: string + title: Object + default: entry + const: entry + type: + type: string + title: Type + default: function.call + const: function.call + created_at: + type: string + title: Created At + format: date-time + completed_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Completed At + agent_id: + anyOf: + - type: string + - type: 'null' + title: Agent Id + model: + anyOf: + - type: string + - type: 'null' + title: Model + id: + type: string + title: Id + tool_call_id: + type: string + title: Tool Call Id + name: + type: string + title: Name + arguments: + $ref: '#/components/schemas/FunctionCallEntryArguments' + confirmation_status: + anyOf: + - type: string + enum: + - pending + - allowed + - denied + - type: 'null' + title: Confirmation Status + title: FunctionCallEntry + required: + - tool_call_id + - name + - arguments + additionalProperties: false + FunctionResultEntry: + type: object + properties: + object: + type: string + title: Object + default: entry + const: entry + type: + type: string + title: Type + default: function.result + const: function.result + created_at: + type: string + title: Created At + format: date-time + completed_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Completed At + id: + type: string + title: Id + tool_call_id: + type: string + title: Tool Call Id + result: + type: string + title: Result + title: FunctionResultEntry + required: + - tool_call_id + - result + additionalProperties: false + FunctionTool: + type: object + properties: + type: + type: string + title: Type + enum: + - function + default: function + function: + $ref: '#/components/schemas/Function' + title: FunctionTool + required: + - function + additionalProperties: false + GuardrailConfig: + type: object + properties: + block_on_error: + type: boolean + title: Block On Error + description: If true, return HTTP 403 and block request in the event of a server-side error + default: false + moderation_llm_v1: + anyOf: + - $ref: '#/components/schemas/ModerationLLMV1Config' + - type: 'null' + moderation_llm_v2: + anyOf: + - $ref: '#/components/schemas/ModerationLLMV2Config' + - type: 'null' + title: GuardrailConfig + ImageDetail: + type: string + title: ImageDetail + enum: + - low + - auto + - high + ImageGenerationTool: + type: object + properties: + tool_configuration: + anyOf: + - $ref: '#/components/schemas/ToolConfiguration' + - type: 'null' + type: + type: string + title: Type + enum: + - image_generation + default: image_generation + title: ImageGenerationTool + additionalProperties: false + ImageURL: + type: object + properties: + url: + type: string + title: Url + detail: + anyOf: + - $ref: '#/components/schemas/ImageDetail' + - type: 'null' + title: ImageURL + required: + - url + additionalProperties: false + ImageURLChunk: + type: object + properties: + type: + type: string + title: Type + default: image_url + const: image_url + image_url: + anyOf: + - $ref: '#/components/schemas/ImageURL' + - type: string + title: Image Url + title: ImageURLChunk + required: + - image_url + additionalProperties: false + description: '{"type":"image_url","image_url":{"url":"data:image/png;base64,iVBORw0' + JsonSchema: + type: object + properties: + name: + type: string + title: Name + description: + anyOf: + - type: string + - type: 'null' + title: Description + schema: + type: object + title: Schema + additionalProperties: true + x-speakeasy-name-override: schema_definition + strict: + type: boolean + title: Strict + default: false + title: JsonSchema + required: + - name + - schema + additionalProperties: false + MessageInputEntry: + type: object + properties: + object: + type: string + title: Object + default: entry + const: entry + type: + type: string + title: Type + default: message.input + const: message.input + created_at: + type: string + title: Created At + format: date-time + completed_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Completed At + id: + type: string + title: Id + role: + type: string + title: Role + enum: + - assistant + - user + content: + anyOf: + - type: string + - $ref: '#/components/schemas/MessageInputContentChunks' + title: Content + prefix: + type: boolean + title: Prefix + default: false + title: MessageInputEntry + required: + - role + - content + additionalProperties: false + description: Representation of an input message inside the conversation. + MessageOutputEntry: + type: object + properties: + object: + type: string + title: Object + default: entry + const: entry + type: + type: string + title: Type + default: message.output + const: message.output + created_at: + type: string + title: Created At + format: date-time + completed_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Completed At + agent_id: + anyOf: + - type: string + - type: 'null' + title: Agent Id + model: + anyOf: + - type: string + - type: 'null' + title: Model + id: + type: string + title: Id + role: + type: string + title: Role + default: assistant + const: assistant + content: + anyOf: + - type: string + - $ref: '#/components/schemas/MessageOutputContentChunks' + title: Content + title: MessageOutputEntry + required: + - content + additionalProperties: false + MetadataDict: + type: object + title: MetadataDict + additionalProperties: true + description: Custom type for metadata with embedded validation. + ModelConversation: + type: object + properties: + instructions: + anyOf: + - type: string + - type: 'null' + title: Instructions + description: Instruction prompt the model will follow during the conversation. + tools: + type: array + items: + oneOf: + - $ref: '#/components/schemas/FunctionTool' + - $ref: '#/components/schemas/WebSearchTool' + - $ref: '#/components/schemas/WebSearchPremiumTool' + - $ref: '#/components/schemas/CodeInterpreterTool' + - $ref: '#/components/schemas/ImageGenerationTool' + - $ref: '#/components/schemas/DocumentLibraryTool' + - $ref: '#/components/schemas/CustomConnector' + discriminator: + propertyName: type + mapping: + code_interpreter: '#/components/schemas/CodeInterpreterTool' + connector: '#/components/schemas/CustomConnector' + document_library: '#/components/schemas/DocumentLibraryTool' + function: '#/components/schemas/FunctionTool' + image_generation: '#/components/schemas/ImageGenerationTool' + web_search: '#/components/schemas/WebSearchTool' + web_search_premium: '#/components/schemas/WebSearchPremiumTool' + title: Tools + description: List of tools which are available to the model during the conversation. + completion_args: + $ref: '#/components/schemas/CompletionArgs' + description: Completion arguments that will be used to generate assistant responses. Can be overridden at each message request. + guardrails: + anyOf: + - type: array + items: + $ref: '#/components/schemas/GuardrailConfig' + - type: 'null' + title: Guardrails + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: Name given to the conversation. + description: + anyOf: + - type: string + - type: 'null' + title: Description + description: Description of the what the conversation is about. + metadata: + anyOf: + - $ref: '#/components/schemas/MetadataDict' + - type: 'null' + description: Custom metadata for the conversation. + object: + type: string + title: Object + default: conversation + const: conversation + id: + type: string + title: Id + created_at: + type: string + title: Created At + format: date-time + updated_at: + type: string + title: Updated At + format: date-time + model: + type: string + title: Model + title: ModelConversation + required: + - id + - created_at + - updated_at + - model + additionalProperties: false + ModerationLLMAction: + type: string + title: ModerationLLMAction + enum: + - none + - block + ModerationLLMV1CategoryThresholds: + type: object + properties: + sexual: + anyOf: + - type: number + - type: 'null' + title: Sexual + hate_and_discrimination: + anyOf: + - type: number + - type: 'null' + title: Hate And Discrimination + violence_and_threats: + anyOf: + - type: number + - type: 'null' + title: Violence And Threats + dangerous_and_criminal_content: + anyOf: + - type: number + - type: 'null' + title: Dangerous And Criminal Content + selfharm: + anyOf: + - type: number + - type: 'null' + title: Selfharm + health: + anyOf: + - type: number + - type: 'null' + title: Health + financial: + anyOf: + - type: number + - type: 'null' + title: Financial + law: + anyOf: + - type: number + - type: 'null' + title: Law + pii: + anyOf: + - type: number + - type: 'null' + title: Pii + title: ModerationLLMV1CategoryThresholds + ModerationLLMV1Config: + type: object + properties: + model_name: + type: string + title: Model Name + description: Override model name. Should be omitted in general. + default: mistral-moderation-2411 + custom_category_thresholds: + anyOf: + - $ref: '#/components/schemas/ModerationLLMV1CategoryThresholds' + - type: 'null' + ignore_other_categories: + type: boolean + title: Ignore Other Categories + description: If true, only evaluate categories in custom_category_thresholds; others are ignored. + default: false + action: + $ref: '#/components/schemas/ModerationLLMAction' + description: Action to take if any score is above the threshold for any category. + default: none + title: ModerationLLMV1Config + ModerationLLMV2CategoryThresholds: + type: object + properties: + sexual: + anyOf: + - type: number + - type: 'null' + title: Sexual + hate_and_discrimination: + anyOf: + - type: number + - type: 'null' + title: Hate And Discrimination + violence_and_threats: + anyOf: + - type: number + - type: 'null' + title: Violence And Threats + dangerous: + anyOf: + - type: number + - type: 'null' + title: Dangerous + criminal: + anyOf: + - type: number + - type: 'null' + title: Criminal + selfharm: + anyOf: + - type: number + - type: 'null' + title: Selfharm + health: + anyOf: + - type: number + - type: 'null' + title: Health + financial: + anyOf: + - type: number + - type: 'null' + title: Financial + law: + anyOf: + - type: number + - type: 'null' + title: Law + pii: + anyOf: + - type: number + - type: 'null' + title: Pii + jailbreaking: + anyOf: + - type: number + - type: 'null' + title: Jailbreaking + title: ModerationLLMV2CategoryThresholds + ModerationLLMV2Config: + type: object + properties: + model_name: + type: string + title: Model Name + description: Override model name. Should be omitted in general. + default: mistral-moderation-2603 + custom_category_thresholds: + anyOf: + - $ref: '#/components/schemas/ModerationLLMV2CategoryThresholds' + - type: 'null' + ignore_other_categories: + type: boolean + title: Ignore Other Categories + description: If true, only evaluate categories in custom_category_thresholds; others are ignored. + default: false + action: + $ref: '#/components/schemas/ModerationLLMAction' + description: Action to take if any score is above the threshold for any category. + default: none + title: ModerationLLMV2Config + OAuth2TokenAuth: + type: object + properties: + type: + type: string + title: Type + enum: + - oauth2-token + default: oauth2-token + value: + type: string + title: Value + title: OAuth2TokenAuth + required: + - value + additionalProperties: false + Prediction: + type: object + properties: + type: + type: string + title: Type + default: content + const: content + content: + type: string + title: Content + default: '' + title: Prediction + additionalProperties: false + description: Enable users to specify an expected completion, optimizing response times by leveraging known or predictable content. + RequestSource: + type: string + title: RequestSource + enum: + - api + - playground + - agent_builder_v1 + ResponseFormat: + type: object + examples: + - type: text + - type: json_object + - type: json_schema + json_schema: + schema: + properties: + name: + title: Name + type: string + authors: + items: + type: string + title: Authors + type: array + required: + - name + - authors + title: Book + type: object + additionalProperties: false + name: book + strict: true + properties: + type: + $ref: '#/components/schemas/ResponseFormats' + default: text + json_schema: + anyOf: + - $ref: '#/components/schemas/JsonSchema' + - type: 'null' + title: ResponseFormat + additionalProperties: false + description: 'Specify the format that the model must output. By default it will use `{ "type": "text" }`. Setting to `{ "type": "json_object" }` enables JSON mode, which guarantees the message the model generates is in JSON. When using JSON mode you MUST also instruct the model to produce JSON yourself with a system or a user message. Setting to `{ "type": "json_schema" }` enables JSON schema mode, which guarantees the message the model generates is in JSON and follows the schema you provide.' + ResponseFormats: + type: string + title: ResponseFormats + enum: + - text + - json_object + - json_schema + TextChunk: + type: object + properties: + type: + type: string + title: Type + default: text + const: text + text: + type: string + title: Text + title: TextChunk + required: + - text + additionalProperties: false + ThinkChunk: + type: object + properties: + type: + type: string + title: Type + default: thinking + const: thinking + thinking: + type: array + items: + anyOf: + - $ref: '#/components/schemas/TextChunk' + - $ref: '#/components/schemas/ToolReferenceChunk' + - $ref: '#/components/schemas/ReferenceChunk' + title: Thinking + closed: + type: boolean + title: Closed + description: Whether the thinking chunk is closed or not. Currently only used for prefixing. + default: true + title: ThinkChunk + required: + - thinking + additionalProperties: false + ToolCallConfirmation: + type: object + properties: + tool_call_id: + type: string + title: Tool Call Id + confirmation: + type: string + title: Confirmation + enum: + - allow + - deny + title: ToolCallConfirmation + required: + - tool_call_id + - confirmation + additionalProperties: false + ToolChoiceEnum: + type: string + title: ToolChoiceEnum + enum: + - auto + - none + - any + - required + ToolConfiguration: + type: object + properties: + exclude: + anyOf: + - type: array + items: + type: string + - type: 'null' + title: Exclude + include: + anyOf: + - type: array + items: + type: string + - type: 'null' + title: Include + requires_confirmation: + anyOf: + - type: array + items: + type: string + - type: 'null' + title: Requires Confirmation + title: ToolConfiguration + additionalProperties: false + ToolExecutionEntry: + type: object + properties: + object: + type: string + title: Object + default: entry + const: entry + type: + type: string + title: Type + default: tool.execution + const: tool.execution + created_at: + type: string + title: Created At + format: date-time + completed_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Completed At + agent_id: + anyOf: + - type: string + - type: 'null' + title: Agent Id + model: + anyOf: + - type: string + - type: 'null' + title: Model + id: + type: string + title: Id + name: + anyOf: + - $ref: '#/components/schemas/BuiltInConnectors' + - type: string + title: Name + arguments: + type: string + title: Arguments + info: + $ref: '#/components/schemas/ToolExecutionInfo' + title: ToolExecutionEntry + required: + - name + - arguments + additionalProperties: false + ToolFileChunk: + type: object + properties: + type: + type: string + title: Type + default: tool_file + const: tool_file + tool: + anyOf: + - $ref: '#/components/schemas/BuiltInConnectors' + - type: string + title: Tool + file_id: + type: string + title: File Id + file_name: + anyOf: + - type: string + - type: 'null' + title: File Name + file_type: + anyOf: + - type: string + - type: 'null' + title: File Type + title: ToolFileChunk + required: + - tool + - file_id + additionalProperties: false + ToolReferenceChunk: + type: object + properties: + type: + type: string + title: Type + default: tool_reference + const: tool_reference + tool: + anyOf: + - $ref: '#/components/schemas/BuiltInConnectors' + - type: string + title: Tool + title: + type: string + title: Title + url: + anyOf: + - type: string + - type: 'null' + title: Url + favicon: + anyOf: + - type: string + - type: 'null' + title: Favicon + description: + anyOf: + - type: string + - type: 'null' + title: Description + title: ToolReferenceChunk + required: + - tool + - title + additionalProperties: false + WebSearchPremiumTool: + type: object + properties: + tool_configuration: + anyOf: + - $ref: '#/components/schemas/ToolConfiguration' + - type: 'null' + type: + type: string + title: Type + enum: + - web_search_premium + default: web_search_premium + title: WebSearchPremiumTool + additionalProperties: false + WebSearchTool: + type: object + properties: + tool_configuration: + anyOf: + - $ref: '#/components/schemas/ToolConfiguration' + - type: 'null' + type: + type: string + title: Type + enum: + - web_search + default: web_search + title: WebSearchTool + additionalProperties: false + ConversationUsageInfo: + type: object + properties: + prompt_tokens: + type: integer + title: Prompt Tokens + default: 0 + completion_tokens: + type: integer + title: Completion Tokens + default: 0 + total_tokens: + type: integer + title: Total Tokens + default: 0 + connector_tokens: + anyOf: + - type: integer + - type: 'null' + title: Connector Tokens + default: null + connectors: + anyOf: + - type: object + additionalProperties: + type: integer + - type: 'null' + title: Connectors + default: null + title: ConversationUsageInfo + additionalProperties: false + ConversationResponse: + type: object + properties: + object: + type: string + title: Object + default: conversation.response + const: conversation.response + conversation_id: + type: string + title: Conversation Id + outputs: + type: array + items: + anyOf: + - $ref: '#/components/schemas/MessageOutputEntry' + - $ref: '#/components/schemas/ToolExecutionEntry' + - $ref: '#/components/schemas/FunctionCallEntry' + - $ref: '#/components/schemas/AgentHandoffEntry' + title: Outputs + usage: + $ref: '#/components/schemas/ConversationUsageInfo' + guardrails: + anyOf: + - type: array + items: + type: object + - type: 'null' + title: Guardrails + default: null + title: ConversationResponse + required: + - conversation_id + - outputs + - usage + additionalProperties: false + description: The response after appending new entries to the conversation. + ConversationRequest: + allOf: + - $ref: '#/components/schemas/ConversationRequestBase' + - type: object + properties: + stream: + type: boolean + enum: + - false + default: false + AgentHandoffDoneEvent: + type: object + properties: + type: + type: string + title: Type + default: agent.handoff.done + const: agent.handoff.done + created_at: + type: string + title: Created At + format: date-time + output_index: + type: integer + title: Output Index + default: 0 + id: + type: string + title: Id + next_agent_id: + type: string + title: Next Agent Id + next_agent_name: + type: string + title: Next Agent Name + title: AgentHandoffDoneEvent + required: + - id + - next_agent_id + - next_agent_name + additionalProperties: false + AgentHandoffStartedEvent: + type: object + properties: + type: + type: string + title: Type + default: agent.handoff.started + const: agent.handoff.started + created_at: + type: string + title: Created At + format: date-time + output_index: + type: integer + title: Output Index + default: 0 + id: + type: string + title: Id + previous_agent_id: + type: string + title: Previous Agent Id + previous_agent_name: + type: string + title: Previous Agent Name + title: AgentHandoffStartedEvent + required: + - id + - previous_agent_id + - previous_agent_name + additionalProperties: false + FunctionCallEvent: + type: object + properties: + type: + type: string + title: Type + default: function.call.delta + const: function.call.delta + created_at: + type: string + title: Created At + format: date-time + output_index: + type: integer + title: Output Index + default: 0 + id: + type: string + title: Id + model: + anyOf: + - type: string + - type: 'null' + title: Model + default: null + agent_id: + anyOf: + - type: string + - type: 'null' + title: Agent Id + default: null + name: + type: string + title: Name + tool_call_id: + type: string + title: Tool Call Id + arguments: + type: string + title: Arguments + confirmation_status: + anyOf: + - type: string + enum: + - pending + - allowed + - denied + - type: 'null' + title: Confirmation Status + default: null + title: FunctionCallEvent + required: + - id + - name + - tool_call_id + - arguments + additionalProperties: false + MessageOutputEvent: + type: object + properties: + type: + type: string + title: Type + default: message.output.delta + const: message.output.delta + created_at: + type: string + title: Created At + format: date-time + output_index: + type: integer + title: Output Index + default: 0 + id: + type: string + title: Id + content_index: + type: integer + title: Content Index + default: 0 + model: + anyOf: + - type: string + - type: 'null' + title: Model + default: null + agent_id: + anyOf: + - type: string + - type: 'null' + title: Agent Id + default: null + role: + type: string + title: Role + default: assistant + const: assistant + content: + anyOf: + - type: string + - $ref: '#/components/schemas/OutputContentChunks' + title: Content + title: MessageOutputEvent + required: + - id + - content + additionalProperties: false + ResponseDoneEvent: + type: object + properties: + type: + type: string + title: Type + default: conversation.response.done + const: conversation.response.done + created_at: + type: string + title: Created At + format: date-time + usage: + $ref: '#/components/schemas/ConversationUsageInfo' + title: ResponseDoneEvent + required: + - usage + additionalProperties: false + ResponseErrorEvent: + type: object + properties: + type: + type: string + title: Type + default: conversation.response.error + const: conversation.response.error + created_at: + type: string + title: Created At + format: date-time + message: + type: string + title: Message + code: + type: integer + title: Code + title: ResponseErrorEvent + required: + - message + - code + additionalProperties: false + ResponseStartedEvent: + type: object + properties: + type: + type: string + title: Type + default: conversation.response.started + const: conversation.response.started + created_at: + type: string + title: Created At + format: date-time + conversation_id: + type: string + title: Conversation Id + title: ResponseStartedEvent + required: + - conversation_id + additionalProperties: false + SSETypes: + type: string + title: SSETypes + enum: + - conversation.response.started + - conversation.response.done + - conversation.response.error + - message.output.delta + - tool.execution.started + - tool.execution.delta + - tool.execution.done + - agent.handoff.started + - agent.handoff.done + - function.call.delta + description: Server side events sent when streaming a conversation response. + ToolExecutionDeltaEvent: + type: object + properties: + type: + type: string + title: Type + default: tool.execution.delta + const: tool.execution.delta + created_at: + type: string + title: Created At + format: date-time + output_index: + type: integer + title: Output Index + default: 0 + id: + type: string + title: Id + name: + anyOf: + - $ref: '#/components/schemas/BuiltInConnectors' + - type: string + title: Name + arguments: + type: string + title: Arguments + title: ToolExecutionDeltaEvent + required: + - id + - name + - arguments + additionalProperties: false + ToolExecutionDoneEvent: + type: object + properties: + type: + type: string + title: Type + default: tool.execution.done + const: tool.execution.done + created_at: + type: string + title: Created At + format: date-time + output_index: + type: integer + title: Output Index + default: 0 + id: + type: string + title: Id + name: + anyOf: + - $ref: '#/components/schemas/BuiltInConnectors' + - type: string + title: Name + info: + $ref: '#/components/schemas/ToolExecutionInfo' + title: ToolExecutionDoneEvent + required: + - id + - name + additionalProperties: false + ToolExecutionStartedEvent: + type: object + properties: + type: + type: string + title: Type + default: tool.execution.started + const: tool.execution.started + created_at: + type: string + title: Created At + format: date-time + output_index: + type: integer + title: Output Index + default: 0 + id: + type: string + title: Id + model: + anyOf: + - type: string + - type: 'null' + title: Model + default: null + agent_id: + anyOf: + - type: string + - type: 'null' + title: Agent Id + default: null + name: + anyOf: + - $ref: '#/components/schemas/BuiltInConnectors' + - type: string + title: Name + arguments: + type: string + title: Arguments + title: ToolExecutionStartedEvent + required: + - id + - name + - arguments + additionalProperties: false + ConversationEvents: + type: object + properties: + event: + $ref: '#/components/schemas/SSETypes' + data: + oneOf: + - $ref: '#/components/schemas/ResponseStartedEvent' + - $ref: '#/components/schemas/ResponseDoneEvent' + - $ref: '#/components/schemas/ResponseErrorEvent' + - $ref: '#/components/schemas/ToolExecutionStartedEvent' + - $ref: '#/components/schemas/ToolExecutionDeltaEvent' + - $ref: '#/components/schemas/ToolExecutionDoneEvent' + - $ref: '#/components/schemas/MessageOutputEvent' + - $ref: '#/components/schemas/FunctionCallEvent' + - $ref: '#/components/schemas/AgentHandoffStartedEvent' + - $ref: '#/components/schemas/AgentHandoffDoneEvent' + discriminator: + propertyName: type + mapping: + agent.handoff.done: '#/components/schemas/AgentHandoffDoneEvent' + agent.handoff.started: '#/components/schemas/AgentHandoffStartedEvent' + conversation.response.done: '#/components/schemas/ResponseDoneEvent' + conversation.response.error: '#/components/schemas/ResponseErrorEvent' + conversation.response.started: '#/components/schemas/ResponseStartedEvent' + function.call.delta: '#/components/schemas/FunctionCallEvent' + message.output.delta: '#/components/schemas/MessageOutputEvent' + tool.execution.delta: '#/components/schemas/ToolExecutionDeltaEvent' + tool.execution.done: '#/components/schemas/ToolExecutionDoneEvent' + tool.execution.started: '#/components/schemas/ToolExecutionStartedEvent' + title: Data + title: ConversationEvents + required: + - event + - data + MessageInputContentChunks: + type: array + items: + anyOf: + - $ref: '#/components/schemas/TextChunk' + - $ref: '#/components/schemas/ImageURLChunk' + - $ref: '#/components/schemas/ToolFileChunk' + - $ref: '#/components/schemas/DocumentURLChunk' + - $ref: '#/components/schemas/ThinkChunk' + title: MessageInputContentChunks + MessageOutputContentChunks: + type: array + items: + anyOf: + - $ref: '#/components/schemas/TextChunk' + - $ref: '#/components/schemas/ImageURLChunk' + - $ref: '#/components/schemas/ToolFileChunk' + - $ref: '#/components/schemas/DocumentURLChunk' + - $ref: '#/components/schemas/ThinkChunk' + - $ref: '#/components/schemas/ToolReferenceChunk' + title: MessageOutputContentChunks + OutputContentChunks: + anyOf: + - $ref: '#/components/schemas/TextChunk' + - $ref: '#/components/schemas/ImageURLChunk' + - $ref: '#/components/schemas/ToolFileChunk' + - $ref: '#/components/schemas/DocumentURLChunk' + - $ref: '#/components/schemas/ThinkChunk' + - $ref: '#/components/schemas/ToolReferenceChunk' + title: OutputContentChunks + MessageEntries: + type: array + items: + anyOf: + - $ref: '#/components/schemas/MessageInputEntry' + - $ref: '#/components/schemas/MessageOutputEntry' + title: MessageEntries + InputEntries: + type: array + items: + anyOf: + - $ref: '#/components/schemas/MessageInputEntry' + - $ref: '#/components/schemas/MessageOutputEntry' + - $ref: '#/components/schemas/FunctionResultEntry' + - $ref: '#/components/schemas/FunctionCallEntry' + - $ref: '#/components/schemas/ToolExecutionEntry' + - $ref: '#/components/schemas/AgentHandoffEntry' + title: InputEntries + CompletionArgsStop: + anyOf: + - type: string + - type: array + items: + type: string + - type: 'null' + title: CompletionArgsStop + FunctionCallEntryArguments: + anyOf: + - type: object + additionalProperties: true + - type: string + title: FunctionCallEntryArguments + ConversationInputs: + anyOf: + - type: string + - $ref: '#/components/schemas/InputEntries' + title: ConversationInputs + ToolExecutionInfo: + type: object + title: ToolExecutionInfo + additionalProperties: true + ConversationRequestBase: + type: object + properties: + inputs: + $ref: '#/components/schemas/ConversationInputs' + stream: + anyOf: + - type: boolean + - type: 'null' + title: Stream + default: null + store: + anyOf: + - type: boolean + - type: 'null' + title: Store + default: null + handoff_execution: + anyOf: + - type: string + enum: + - client + - server + - type: 'null' + title: Handoff Execution + default: null + instructions: + anyOf: + - type: string + - type: 'null' + title: Instructions + default: null + tools: + anyOf: + - type: array + items: + oneOf: + - $ref: '#/components/schemas/FunctionTool' + - $ref: '#/components/schemas/WebSearchTool' + - $ref: '#/components/schemas/WebSearchPremiumTool' + - $ref: '#/components/schemas/CodeInterpreterTool' + - $ref: '#/components/schemas/ImageGenerationTool' + - $ref: '#/components/schemas/DocumentLibraryTool' + - $ref: '#/components/schemas/CustomConnector' + discriminator: + propertyName: type + mapping: + code_interpreter: '#/components/schemas/CodeInterpreterTool' + connector: '#/components/schemas/CustomConnector' + document_library: '#/components/schemas/DocumentLibraryTool' + function: '#/components/schemas/FunctionTool' + image_generation: '#/components/schemas/ImageGenerationTool' + web_search: '#/components/schemas/WebSearchTool' + web_search_premium: '#/components/schemas/WebSearchPremiumTool' + - type: 'null' + title: Tools + default: null + completion_args: + anyOf: + - $ref: '#/components/schemas/CompletionArgs' + - type: 'null' + default: null + guardrails: + anyOf: + - type: array + items: + $ref: '#/components/schemas/GuardrailConfig' + - type: 'null' + title: Guardrails + default: null + name: + anyOf: + - type: string + - type: 'null' + title: Name + default: null + description: + anyOf: + - type: string + - type: 'null' + title: Description + default: null + metadata: + anyOf: + - $ref: '#/components/schemas/MetadataDict' + - type: 'null' + default: null + agent_id: + anyOf: + - type: string + - type: 'null' + title: Agent Id + default: null + agent_version: + anyOf: + - type: string + - type: integer + - type: 'null' + title: Agent Version + default: null + model: + anyOf: + - type: string + - type: 'null' + title: Model + default: null + title: ConversationRequest + required: + - inputs + ConversationStreamRequest: + allOf: + - $ref: '#/components/schemas/ConversationRequestBase' + - type: object + properties: + stream: + type: boolean + enum: + - true + default: true + ConversationAppendRequestBase: + type: object + properties: + inputs: + $ref: '#/components/schemas/ConversationInputs' + stream: + type: boolean + title: Stream + description: Whether to stream back partial progress. Otherwise, the server will hold the request open until the timeout or until completion, with the response containing the full result as JSON. + default: false + store: + type: boolean + title: Store + description: Whether to store the results into our servers or not. + default: true + handoff_execution: + type: string + title: Handoff Execution + enum: + - client + - server + default: server + completion_args: + $ref: '#/components/schemas/CompletionArgs' + description: Completion arguments that will be used to generate assistant responses. Can be overridden at each message request. + tool_confirmations: + anyOf: + - type: array + items: + $ref: '#/components/schemas/ToolCallConfirmation' + - type: 'null' + title: Tool Confirmations + title: ConversationAppendRequest + additionalProperties: false + ConversationAppendStreamRequest: + allOf: + - $ref: '#/components/schemas/ConversationAppendRequestBase' + - type: object + properties: + stream: + type: boolean + enum: + - true + default: true + ConversationRestartRequestBase: + type: object + properties: + inputs: + $ref: '#/components/schemas/ConversationInputs' + stream: + type: boolean + title: Stream + description: Whether to stream back partial progress. Otherwise, the server will hold the request open until the timeout or until completion, with the response containing the full result as JSON. + default: false + store: + type: boolean + title: Store + description: Whether to store the results into our servers or not. + default: true + handoff_execution: + type: string + title: Handoff Execution + enum: + - client + - server + default: server + completion_args: + $ref: '#/components/schemas/CompletionArgs' + description: Completion arguments that will be used to generate assistant responses. Can be overridden at each message request. + guardrails: + anyOf: + - type: array + items: + $ref: '#/components/schemas/GuardrailConfig' + - type: 'null' + title: Guardrails + metadata: + anyOf: + - $ref: '#/components/schemas/MetadataDict' + - type: 'null' + description: Custom metadata for the conversation. + from_entry_id: + type: string + title: From Entry Id + agent_version: + anyOf: + - type: string + - type: integer + - type: 'null' + title: Agent Version + description: Specific version of the agent to use when restarting. If not provided, uses the current version. + title: ConversationRestartRequest + required: + - from_entry_id + additionalProperties: false + description: Request to restart a new conversation from a given entry in the conversation. + ConversationRestartStreamRequest: + allOf: + - $ref: '#/components/schemas/ConversationRestartRequestBase' + - type: object + properties: + stream: + type: boolean + enum: + - true + default: true + ReferenceChunk: + type: object + properties: + type: + type: string + title: Type + default: reference + const: reference + reference_ids: + type: array + items: + type: integer + title: Reference Ids + title: ReferenceChunk + required: + - reference_ids + additionalProperties: false + FilePurpose: + type: string + title: FilePurpose + enum: + - fine-tune + - batch + - ocr + FileVisibility: + type: string + title: FileVisibility + enum: + - workspace + - user + SampleType: + type: string + title: SampleType + enum: + - pretrain + - instruct + - batch_request + - batch_result + - batch_error + Source: + type: string + title: Source + enum: + - upload + - repository + - mistral + UploadFileOut: + type: object + properties: + id: + type: string + examples: + - 497f6eca-6276-4993-bfeb-53cbbbba6f09 + title: Id + format: uuid + description: The unique identifier of the file. + object: + type: string + examples: + - file + title: Object + description: The object type, which is always "file". + bytes: + type: integer + examples: + - 13000 + title: Bytes + description: The size of the file, in bytes. + created_at: + type: integer + examples: + - 1716963433 + title: Created At + description: The UNIX timestamp (in seconds) of the event. + filename: + type: string + examples: + - files_upload.jsonl + title: Filename + description: The name of the uploaded file. + purpose: + $ref: '#/components/schemas/FilePurpose' + examples: + - fine-tune + - ocr + - batch + - audio + description: The intended purpose of the uploaded file, currently supports fine-tuning (`fine-tune`), OCR (`ocr`), Audio/Transcription (`audio`) and batch inference (`batch`). + sample_type: + $ref: '#/components/schemas/SampleType' + num_lines: + anyOf: + - type: integer + - type: 'null' + title: Num Lines + mimetype: + anyOf: + - type: string + - type: 'null' + title: Mimetype + source: + $ref: '#/components/schemas/Source' + signature: + anyOf: + - type: string + - type: 'null' + title: Signature + expires_at: + anyOf: + - type: integer + - type: 'null' + title: Expires At + visibility: + anyOf: + - $ref: '#/components/schemas/FileVisibility' + - type: 'null' + title: UploadFileOut + required: + - id + - object + - bytes + - created_at + - filename + - purpose + - sample_type + - source + FileSchema: + type: object + properties: + id: + type: string + examples: + - 497f6eca-6276-4993-bfeb-53cbbbba6f09 + title: Id + format: uuid + description: The unique identifier of the file. + object: + type: string + examples: + - file + title: Object + description: The object type, which is always "file". + bytes: + type: integer + examples: + - 13000 + title: Bytes + description: The size of the file, in bytes. + created_at: + type: integer + examples: + - 1716963433 + title: Created At + description: The UNIX timestamp (in seconds) of the event. + filename: + type: string + examples: + - files_upload.jsonl + title: Filename + description: The name of the uploaded file. + purpose: + $ref: '#/components/schemas/FilePurpose' + examples: + - fine-tune + - ocr + - batch + - audio + description: The intended purpose of the uploaded file, currently supports fine-tuning (`fine-tune`), OCR (`ocr`), Audio/Transcription (`audio`) and batch inference (`batch`). + sample_type: + $ref: '#/components/schemas/SampleType' + num_lines: + anyOf: + - type: integer + - type: 'null' + title: Num Lines + mimetype: + anyOf: + - type: string + - type: 'null' + title: Mimetype + source: + $ref: '#/components/schemas/Source' + signature: + anyOf: + - type: string + - type: 'null' + title: Signature + expires_at: + anyOf: + - type: integer + - type: 'null' + title: Expires At + visibility: + anyOf: + - $ref: '#/components/schemas/FileVisibility' + - type: 'null' + title: FileSchema + required: + - id + - object + - bytes + - created_at + - filename + - purpose + - sample_type + - source + ListFilesOut: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/FileSchema' + title: Data + object: + type: string + title: Object + total: + anyOf: + - type: integer + - type: 'null' + title: Total + title: ListFilesOut + required: + - data + - object + RetrieveFileOut: + type: object + properties: + id: + type: string + examples: + - 497f6eca-6276-4993-bfeb-53cbbbba6f09 + title: Id + format: uuid + description: The unique identifier of the file. + object: + type: string + examples: + - file + title: Object + description: The object type, which is always "file". + bytes: + type: integer + examples: + - 13000 + title: Bytes + description: The size of the file, in bytes. + created_at: + type: integer + examples: + - 1716963433 + title: Created At + description: The UNIX timestamp (in seconds) of the event. + filename: + type: string + examples: + - files_upload.jsonl + title: Filename + description: The name of the uploaded file. + purpose: + $ref: '#/components/schemas/FilePurpose' + examples: + - fine-tune + - ocr + - batch + - audio + description: The intended purpose of the uploaded file, currently supports fine-tuning (`fine-tune`), OCR (`ocr`), Audio/Transcription (`audio`) and batch inference (`batch`). + sample_type: + $ref: '#/components/schemas/SampleType' + num_lines: + anyOf: + - type: integer + - type: 'null' + title: Num Lines + mimetype: + anyOf: + - type: string + - type: 'null' + title: Mimetype + source: + $ref: '#/components/schemas/Source' + signature: + anyOf: + - type: string + - type: 'null' + title: Signature + expires_at: + anyOf: + - type: integer + - type: 'null' + title: Expires At + visibility: + anyOf: + - $ref: '#/components/schemas/FileVisibility' + - type: 'null' + deleted: + type: boolean + title: Deleted + title: RetrieveFileOut + required: + - id + - object + - bytes + - created_at + - filename + - purpose + - sample_type + - source + - deleted + DeleteFileOut: + type: object + properties: + id: + type: string + examples: + - 497f6eca-6276-4993-bfeb-53cbbbba6f09 + title: Id + format: uuid + description: The ID of the deleted file. + object: + type: string + examples: + - file + title: Object + description: The object type that was deleted + deleted: + type: boolean + examples: + - false + title: Deleted + description: The deletion status. + title: DeleteFileOut + required: + - id + - object + - deleted + FileSignedURL: + type: object + properties: + url: + type: string + title: Url + title: FileSignedURL + required: + - url + FineTuneableModelType: + type: string + title: FineTuneableModelType + enum: + - completion + - classifier + ClassifierJobOut: + type: object + properties: + id: + type: string + title: Id + format: uuid + description: The ID of the job. + auto_start: + type: boolean + title: Auto Start + model: + type: string + title: Model + status: + type: string + title: Status + enum: + - QUEUED + - STARTED + - VALIDATING + - VALIDATED + - RUNNING + - FAILED_VALIDATION + - FAILED + - SUCCESS + - CANCELLED + - CANCELLATION_REQUESTED + description: The current status of the fine-tuning job. + created_at: + type: integer + title: Created At + description: The UNIX timestamp (in seconds) for when the fine-tuning job was created. + modified_at: + type: integer + title: Modified At + description: The UNIX timestamp (in seconds) for when the fine-tuning job was last modified. + training_files: + type: array + items: + type: string + format: uuid + title: Training Files + description: A list containing the IDs of uploaded files that contain training data. + validation_files: + anyOf: + - type: array + items: + type: string + format: uuid + - type: 'null' + title: Validation Files + description: A list containing the IDs of uploaded files that contain validation data. + default: [] + object: + type: string + title: Object + description: The object type of the fine-tuning job. + default: job + const: job + fine_tuned_model: + anyOf: + - type: string + - type: 'null' + title: Fine Tuned Model + description: The name of the fine-tuned model that is being created. The value will be `null` if the fine-tuning job is still running. + suffix: + anyOf: + - type: string + - type: 'null' + title: Suffix + description: Optional text/code that adds more context for the model. When given a `prompt` and a `suffix` the model will fill what is between them. When `suffix` is not provided, the model will simply execute completion starting with `prompt`. + integrations: + anyOf: + - type: array + items: + oneOf: + - $ref: '#/components/schemas/WandbIntegrationOut' + discriminator: + propertyName: type + mapping: + wandb: '#/components/schemas/WandbIntegrationOut' + - type: 'null' + title: Integrations + description: A list of integrations enabled for your fine-tuning job. + trained_tokens: + anyOf: + - type: integer + - type: 'null' + title: Trained Tokens + description: Total number of tokens trained. + metadata: + anyOf: + - $ref: '#/components/schemas/JobMetadataOut' + - type: 'null' + job_type: + type: string + title: Job Type + description: The type of job (`FT` for fine-tuning). + default: classifier + const: classifier + hyperparameters: + $ref: '#/components/schemas/ClassifierTrainingParameters' + title: ClassifierJobOut + required: + - id + - auto_start + - model + - status + - created_at + - modified_at + - training_files + - hyperparameters + ClassifierTrainingParameters: + type: object + properties: + training_steps: + anyOf: + - type: integer + minimum: 1 + - type: 'null' + title: Training Steps + learning_rate: + type: number + title: Learning Rate + maximum: 1 + minimum: 1e-08 + default: 0.0001 + weight_decay: + anyOf: + - type: number + maximum: 1 + minimum: 0 + - type: 'null' + title: Weight Decay + default: 0.1 + warmup_fraction: + anyOf: + - type: number + maximum: 1 + minimum: 0 + - type: 'null' + title: Warmup Fraction + default: 0.05 + epochs: + anyOf: + - exclusiveMinimum: 0 + type: number + - type: 'null' + title: Epochs + seq_len: + anyOf: + - type: integer + minimum: 100 + - type: 'null' + title: Seq Len + title: ClassifierTrainingParameters + CompletionJobOut: + type: object + properties: + id: + type: string + title: Id + format: uuid + description: The ID of the job. + auto_start: + type: boolean + title: Auto Start + model: + type: string + title: Model + status: + type: string + title: Status + enum: + - QUEUED + - STARTED + - VALIDATING + - VALIDATED + - RUNNING + - FAILED_VALIDATION + - FAILED + - SUCCESS + - CANCELLED + - CANCELLATION_REQUESTED + description: The current status of the fine-tuning job. + created_at: + type: integer + title: Created At + description: The UNIX timestamp (in seconds) for when the fine-tuning job was created. + modified_at: + type: integer + title: Modified At + description: The UNIX timestamp (in seconds) for when the fine-tuning job was last modified. + training_files: + type: array + items: + type: string + format: uuid + title: Training Files + description: A list containing the IDs of uploaded files that contain training data. + validation_files: + anyOf: + - type: array + items: + type: string + format: uuid + - type: 'null' + title: Validation Files + description: A list containing the IDs of uploaded files that contain validation data. + default: [] + object: + type: string + title: Object + description: The object type of the fine-tuning job. + default: job + const: job + fine_tuned_model: + anyOf: + - type: string + - type: 'null' + title: Fine Tuned Model + description: The name of the fine-tuned model that is being created. The value will be `null` if the fine-tuning job is still running. + suffix: + anyOf: + - type: string + - type: 'null' + title: Suffix + description: Optional text/code that adds more context for the model. When given a `prompt` and a `suffix` the model will fill what is between them. When `suffix` is not provided, the model will simply execute completion starting with `prompt`. + integrations: + anyOf: + - type: array + items: + oneOf: + - $ref: '#/components/schemas/WandbIntegrationOut' + discriminator: + propertyName: type + mapping: + wandb: '#/components/schemas/WandbIntegrationOut' + - type: 'null' + title: Integrations + description: A list of integrations enabled for your fine-tuning job. + trained_tokens: + anyOf: + - type: integer + - type: 'null' + title: Trained Tokens + description: Total number of tokens trained. + metadata: + anyOf: + - $ref: '#/components/schemas/JobMetadataOut' + - type: 'null' + job_type: + type: string + title: Job Type + description: The type of job (`FT` for fine-tuning). + default: completion + const: completion + hyperparameters: + $ref: '#/components/schemas/CompletionTrainingParameters' + repositories: + type: array + items: + oneOf: + - $ref: '#/components/schemas/GithubRepositoryOut' + discriminator: + propertyName: type + mapping: + github: '#/components/schemas/GithubRepositoryOut' + title: Repositories + default: [] + title: CompletionJobOut + required: + - id + - auto_start + - model + - status + - created_at + - modified_at + - training_files + - hyperparameters + CompletionTrainingParameters: + type: object + properties: + training_steps: + anyOf: + - type: integer + minimum: 1 + - type: 'null' + title: Training Steps + learning_rate: + type: number + title: Learning Rate + maximum: 1 + minimum: 1e-08 + default: 0.0001 + weight_decay: + anyOf: + - type: number + maximum: 1 + minimum: 0 + - type: 'null' + title: Weight Decay + default: 0.1 + warmup_fraction: + anyOf: + - type: number + maximum: 1 + minimum: 0 + - type: 'null' + title: Warmup Fraction + default: 0.05 + epochs: + anyOf: + - exclusiveMinimum: 0 + type: number + - type: 'null' + title: Epochs + seq_len: + anyOf: + - type: integer + minimum: 100 + - type: 'null' + title: Seq Len + fim_ratio: + anyOf: + - type: number + maximum: 1 + minimum: 0 + - type: 'null' + title: Fim Ratio + default: 0.9 + title: CompletionTrainingParameters + GithubRepositoryOut: + type: object + properties: + type: + type: string + title: Type + default: github + const: github + name: + type: string + title: Name + owner: + type: string + title: Owner + ref: + anyOf: + - type: string + - type: 'null' + title: Ref + weight: + exclusiveMinimum: 0 + type: number + title: Weight + default: 1.0 + commit_id: + type: string + title: Commit Id + maxLength: 40 + minLength: 40 + title: GithubRepositoryOut + required: + - name + - owner + - commit_id + JobMetadataOut: + type: object + properties: + expected_duration_seconds: + anyOf: + - type: integer + - type: 'null' + title: Expected Duration Seconds + cost: + anyOf: + - type: number + - type: 'null' + title: Cost + cost_currency: + anyOf: + - type: string + - type: 'null' + title: Cost Currency + train_tokens_per_step: + anyOf: + - type: integer + - type: 'null' + title: Train Tokens Per Step + train_tokens: + anyOf: + - type: integer + - type: 'null' + title: Train Tokens + data_tokens: + anyOf: + - type: integer + - type: 'null' + title: Data Tokens + estimated_start_time: + anyOf: + - type: integer + - type: 'null' + title: Estimated Start Time + title: JobMetadataOut + JobsOut: + type: object + properties: + data: + type: array + items: + oneOf: + - $ref: '#/components/schemas/CompletionJobOut' + - $ref: '#/components/schemas/ClassifierJobOut' + discriminator: + propertyName: job_type + mapping: + classifier: '#/components/schemas/ClassifierJobOut' + completion: '#/components/schemas/CompletionJobOut' + title: Data + default: [] + object: + type: string + title: Object + default: list + const: list + total: + type: integer + title: Total + title: JobsOut + required: + - total + WandbIntegrationOut: + type: object + properties: + type: + type: string + title: Type + default: wandb + const: wandb + project: + type: string + title: Project + description: The name of the project that the new run will be created under. + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: A display name to set for the run. If not set, will use the job ID as the name. + run_name: + anyOf: + - type: string + - type: 'null' + title: Run Name + url: + anyOf: + - type: string + - type: 'null' + title: Url + title: WandbIntegrationOut + required: + - project + LegacyJobMetadataOut: + type: object + properties: + expected_duration_seconds: + anyOf: + - type: integer + - type: 'null' + examples: + - 220 + title: Expected Duration Seconds + description: The approximated time (in seconds) for the fine-tuning process to complete. + cost: + anyOf: + - type: number + - type: 'null' + examples: + - 10 + title: Cost + description: The cost of the fine-tuning job. + cost_currency: + anyOf: + - type: string + - type: 'null' + examples: + - EUR + title: Cost Currency + description: The currency used for the fine-tuning job cost. + train_tokens_per_step: + anyOf: + - type: integer + - type: 'null' + examples: + - 131072 + title: Train Tokens Per Step + description: The number of tokens consumed by one training step. + train_tokens: + anyOf: + - type: integer + - type: 'null' + examples: + - 1310720 + title: Train Tokens + description: The total number of tokens used during the fine-tuning process. + data_tokens: + anyOf: + - type: integer + - type: 'null' + examples: + - 305375 + title: Data Tokens + description: The total number of tokens in the training dataset. + estimated_start_time: + anyOf: + - type: integer + - type: 'null' + title: Estimated Start Time + deprecated: + type: boolean + title: Deprecated + default: true + details: + type: string + title: Details + epochs: + anyOf: + - type: number + - type: 'null' + examples: + - 4.2922 + title: Epochs + description: The number of complete passes through the entire training dataset. + training_steps: + anyOf: + - type: integer + - type: 'null' + examples: + - 10 + title: Training Steps + description: The number of training steps to perform. A training step refers to a single update of the model weights during the fine-tuning process. This update is typically calculated using a batch of samples from the training dataset. + object: + type: string + title: Object + default: job.metadata + const: job.metadata + title: LegacyJobMetadataOut + required: + - details + ClassifierTargetIn: + type: object + properties: + name: + type: string + title: Name + labels: + type: array + items: + type: string + title: Labels + weight: + type: number + title: Weight + minimum: 0 + default: 1.0 + loss_function: + anyOf: + - $ref: '#/components/schemas/FTClassifierLossFunction' + - type: 'null' + title: ClassifierTargetIn + required: + - name + - labels + ClassifierTrainingParametersIn: + type: object + properties: + training_steps: + anyOf: + - type: integer + minimum: 1 + - type: 'null' + title: Training Steps + description: The number of training steps to perform. A training step refers to a single update of the model weights during the fine-tuning process. This update is typically calculated using a batch of samples from the training dataset. + learning_rate: + type: number + title: Learning Rate + maximum: 1 + minimum: 1e-08 + description: A parameter describing how much to adjust the pre-trained model's weights in response to the estimated error each time the weights are updated during the fine-tuning process. + default: 0.0001 + weight_decay: + anyOf: + - type: number + maximum: 1 + minimum: 0 + - type: 'null' + title: Weight Decay + description: (Advanced Usage) Weight decay adds a term to the loss function that is proportional to the sum of the squared weights. This term reduces the magnitude of the weights and prevents them from growing too large. + default: 0.1 + warmup_fraction: + anyOf: + - type: number + maximum: 1 + minimum: 0 + - type: 'null' + title: Warmup Fraction + description: (Advanced Usage) A parameter that specifies the percentage of the total training steps at which the learning rate warm-up phase ends. During this phase, the learning rate gradually increases from a small value to the initial learning rate, helping to stabilize the training process and improve convergence. Similar to `pct_start` in [mistral-finetune](https://github.com/mistralai/mistral-finetune) + default: 0.05 + epochs: + anyOf: + - exclusiveMinimum: 0 + type: number + - type: 'null' + title: Epochs + seq_len: + anyOf: + - type: integer + minimum: 100 + - type: 'null' + title: Seq Len + title: ClassifierTrainingParametersIn + description: The fine-tuning hyperparameter settings used in a classifier fine-tune job. + CompletionTrainingParametersIn: + type: object + properties: + training_steps: + anyOf: + - type: integer + minimum: 1 + - type: 'null' + title: Training Steps + description: The number of training steps to perform. A training step refers to a single update of the model weights during the fine-tuning process. This update is typically calculated using a batch of samples from the training dataset. + learning_rate: + type: number + title: Learning Rate + maximum: 1 + minimum: 1e-08 + description: A parameter describing how much to adjust the pre-trained model's weights in response to the estimated error each time the weights are updated during the fine-tuning process. + default: 0.0001 + weight_decay: + anyOf: + - type: number + maximum: 1 + minimum: 0 + - type: 'null' + title: Weight Decay + description: (Advanced Usage) Weight decay adds a term to the loss function that is proportional to the sum of the squared weights. This term reduces the magnitude of the weights and prevents them from growing too large. + default: 0.1 + warmup_fraction: + anyOf: + - type: number + maximum: 1 + minimum: 0 + - type: 'null' + title: Warmup Fraction + description: (Advanced Usage) A parameter that specifies the percentage of the total training steps at which the learning rate warm-up phase ends. During this phase, the learning rate gradually increases from a small value to the initial learning rate, helping to stabilize the training process and improve convergence. Similar to `pct_start` in [mistral-finetune](https://github.com/mistralai/mistral-finetune) + default: 0.05 + epochs: + anyOf: + - exclusiveMinimum: 0 + type: number + - type: 'null' + title: Epochs + seq_len: + anyOf: + - type: integer + minimum: 100 + - type: 'null' + title: Seq Len + fim_ratio: + anyOf: + - type: number + maximum: 1 + minimum: 0 + - type: 'null' + title: Fim Ratio + default: 0.9 + title: CompletionTrainingParametersIn + description: The fine-tuning hyperparameter settings used in a fine-tune job. + FTClassifierLossFunction: + type: string + title: FTClassifierLossFunction + enum: + - single_class + - multi_class + GithubRepositoryIn: + type: object + properties: + type: + type: string + title: Type + default: github + const: github + name: + type: string + title: Name + owner: + type: string + title: Owner + ref: + anyOf: + - type: string + - type: 'null' + title: Ref + weight: + exclusiveMinimum: 0 + type: number + title: Weight + default: 1.0 + token: + type: string + title: Token + title: GithubRepositoryIn + required: + - name + - owner + - token + JobIn: + type: object + properties: + model: + type: string + title: Model + training_files: + type: array + items: + $ref: '#/components/schemas/TrainingFile' + title: Training Files + default: [] + validation_files: + anyOf: + - type: array + items: + type: string + format: uuid + - type: 'null' + title: Validation Files + description: A list containing the IDs of uploaded files that contain validation data. If you provide these files, the data is used to generate validation metrics periodically during fine-tuning. These metrics can be viewed in `checkpoints` when getting the status of a running fine-tuning job. The same data should not be present in both train and validation files. + suffix: + anyOf: + - type: string + maxLength: 18 + - type: 'null' + title: Suffix + description: A string that will be added to your fine-tuning model name. For example, a suffix of "my-great-model" would produce a model name like `ft:open-mistral-7b:my-great-model:xxx...` + integrations: + anyOf: + - type: array + items: + oneOf: + - $ref: '#/components/schemas/WandbIntegration' + discriminator: + propertyName: type + mapping: + wandb: '#/components/schemas/WandbIntegration' + - type: 'null' + title: Integrations + description: A list of integrations to enable for your fine-tuning job. + auto_start: + type: boolean + title: Auto Start + description: This field will be required in a future release. + invalid_sample_skip_percentage: + type: number + title: Invalid Sample Skip Percentage + maximum: 0.5 + minimum: 0 + default: 0 + job_type: + anyOf: + - $ref: '#/components/schemas/FineTuneableModelType' + - type: 'null' + hyperparameters: + anyOf: + - $ref: '#/components/schemas/CompletionTrainingParametersIn' + - $ref: '#/components/schemas/ClassifierTrainingParametersIn' + title: Hyperparameters + repositories: + anyOf: + - type: array + items: + oneOf: + - $ref: '#/components/schemas/GithubRepositoryIn' + discriminator: + propertyName: type + mapping: + github: '#/components/schemas/GithubRepositoryIn' + - type: 'null' + title: Repositories + classifier_targets: + anyOf: + - type: array + items: + $ref: '#/components/schemas/ClassifierTargetIn' + - type: 'null' + title: Classifier Targets + title: JobIn + required: + - model + - hyperparameters + TrainingFile: + type: object + properties: + file_id: + type: string + title: File Id + format: uuid + weight: + exclusiveMinimum: 0 + type: number + title: Weight + default: 1.0 + title: TrainingFile + required: + - file_id + WandbIntegration: + type: object + properties: + type: + type: string + title: Type + default: wandb + const: wandb + project: + type: string + title: Project + description: The name of the project that the new run will be created under. + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: A display name to set for the run. If not set, will use the job ID as the name. + api_key: + type: string + title: Api Key + maxLength: 40 + minLength: 40 + description: The WandB API key to use for authentication. + run_name: + anyOf: + - type: string + - type: 'null' + title: Run Name + title: WandbIntegration + required: + - project + - api_key + CheckpointOut: + type: object + properties: + metrics: + $ref: '#/components/schemas/MetricOut' + step_number: + type: integer + title: Step Number + description: The step number that the checkpoint was created at. + created_at: + type: integer + examples: + - 1716963433 + title: Created At + description: The UNIX timestamp (in seconds) for when the checkpoint was created. + title: CheckpointOut + required: + - metrics + - step_number + - created_at + ClassifierDetailedJobOut: + type: object + properties: + id: + type: string + title: Id + format: uuid + auto_start: + type: boolean + title: Auto Start + model: + type: string + title: Model + status: + type: string + title: Status + enum: + - QUEUED + - STARTED + - VALIDATING + - VALIDATED + - RUNNING + - FAILED_VALIDATION + - FAILED + - SUCCESS + - CANCELLED + - CANCELLATION_REQUESTED + created_at: + type: integer + title: Created At + modified_at: + type: integer + title: Modified At + training_files: + type: array + items: + type: string + format: uuid + title: Training Files + validation_files: + anyOf: + - type: array + items: + type: string + format: uuid + - type: 'null' + title: Validation Files + default: [] + object: + type: string + title: Object + default: job + const: job + fine_tuned_model: + anyOf: + - type: string + - type: 'null' + title: Fine Tuned Model + suffix: + anyOf: + - type: string + - type: 'null' + title: Suffix + integrations: + anyOf: + - type: array + items: + oneOf: + - $ref: '#/components/schemas/WandbIntegrationOut' + discriminator: + propertyName: type + mapping: + wandb: '#/components/schemas/WandbIntegrationOut' + - type: 'null' + title: Integrations + trained_tokens: + anyOf: + - type: integer + - type: 'null' + title: Trained Tokens + metadata: + anyOf: + - $ref: '#/components/schemas/JobMetadataOut' + - type: 'null' + job_type: + type: string + title: Job Type + default: classifier + const: classifier + hyperparameters: + $ref: '#/components/schemas/ClassifierTrainingParameters' + events: + type: array + items: + $ref: '#/components/schemas/EventOut' + title: Events + description: Event items are created every time the status of a fine-tuning job changes. The timestamped list of all events is accessible here. + default: [] + checkpoints: + type: array + items: + $ref: '#/components/schemas/CheckpointOut' + title: Checkpoints + default: [] + classifier_targets: + type: array + items: + $ref: '#/components/schemas/ClassifierTargetOut' + title: Classifier Targets + title: ClassifierDetailedJobOut + required: + - id + - auto_start + - model + - status + - created_at + - modified_at + - training_files + - hyperparameters + - classifier_targets + ClassifierTargetOut: + type: object + properties: + name: + type: string + title: Name + labels: + type: array + items: + type: string + title: Labels + weight: + type: number + title: Weight + loss_function: + $ref: '#/components/schemas/FTClassifierLossFunction' + title: ClassifierTargetOut + required: + - name + - labels + - weight + - loss_function + CompletionDetailedJobOut: + type: object + properties: + id: + type: string + title: Id + format: uuid + auto_start: + type: boolean + title: Auto Start + model: + type: string + title: Model + status: + type: string + title: Status + enum: + - QUEUED + - STARTED + - VALIDATING + - VALIDATED + - RUNNING + - FAILED_VALIDATION + - FAILED + - SUCCESS + - CANCELLED + - CANCELLATION_REQUESTED + created_at: + type: integer + title: Created At + modified_at: + type: integer + title: Modified At + training_files: + type: array + items: + type: string + format: uuid + title: Training Files + validation_files: + anyOf: + - type: array + items: + type: string + format: uuid + - type: 'null' + title: Validation Files + default: [] + object: + type: string + title: Object + default: job + const: job + fine_tuned_model: + anyOf: + - type: string + - type: 'null' + title: Fine Tuned Model + suffix: + anyOf: + - type: string + - type: 'null' + title: Suffix + integrations: + anyOf: + - type: array + items: + oneOf: + - $ref: '#/components/schemas/WandbIntegrationOut' + discriminator: + propertyName: type + mapping: + wandb: '#/components/schemas/WandbIntegrationOut' + - type: 'null' + title: Integrations + trained_tokens: + anyOf: + - type: integer + - type: 'null' + title: Trained Tokens + metadata: + anyOf: + - $ref: '#/components/schemas/JobMetadataOut' + - type: 'null' + job_type: + type: string + title: Job Type + default: completion + const: completion + hyperparameters: + $ref: '#/components/schemas/CompletionTrainingParameters' + repositories: + type: array + items: + oneOf: + - $ref: '#/components/schemas/GithubRepositoryOut' + discriminator: + propertyName: type + mapping: + github: '#/components/schemas/GithubRepositoryOut' + title: Repositories + default: [] + events: + type: array + items: + $ref: '#/components/schemas/EventOut' + title: Events + description: Event items are created every time the status of a fine-tuning job changes. The timestamped list of all events is accessible here. + default: [] + checkpoints: + type: array + items: + $ref: '#/components/schemas/CheckpointOut' + title: Checkpoints + default: [] + title: CompletionDetailedJobOut + required: + - id + - auto_start + - model + - status + - created_at + - modified_at + - training_files + - hyperparameters + EventOut: + type: object + properties: + name: + type: string + title: Name + description: The name of the event. + data: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Data + created_at: + type: integer + title: Created At + description: The UNIX timestamp (in seconds) of the event. + title: EventOut + required: + - name + - created_at + MetricOut: + type: object + properties: + train_loss: + anyOf: + - type: number + - type: 'null' + title: Train Loss + valid_loss: + anyOf: + - type: number + - type: 'null' + title: Valid Loss + valid_mean_token_accuracy: + anyOf: + - type: number + - type: 'null' + title: Valid Mean Token Accuracy + title: MetricOut + description: Metrics at the step number during the fine-tuning job. Use these metrics to assess if the training is going smoothly (loss should decrease, token accuracy should increase). + ClassifierFTModelOut: + type: object + properties: + id: + type: string + title: Id + object: + type: string + title: Object + default: model + const: model + created: + type: integer + title: Created + owned_by: + type: string + title: Owned By + workspace_id: + type: string + title: Workspace Id + root: + type: string + title: Root + root_version: + type: string + title: Root Version + archived: + type: boolean + title: Archived + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: + anyOf: + - type: string + - type: 'null' + title: Description + capabilities: + $ref: '#/components/schemas/FTModelCapabilitiesOut' + max_context_length: + type: integer + title: Max Context Length + default: 32768 + aliases: + type: array + items: + type: string + title: Aliases + default: [] + job: + type: string + title: Job + format: uuid + classifier_targets: + type: array + items: + $ref: '#/components/schemas/ClassifierTargetOut' + title: Classifier Targets + model_type: + type: string + title: Model Type + default: classifier + const: classifier + title: ClassifierFTModelOut + required: + - id + - created + - owned_by + - workspace_id + - root + - root_version + - archived + - capabilities + - job + - classifier_targets + CompletionFTModelOut: + type: object + properties: + id: + type: string + title: Id + object: + type: string + title: Object + default: model + const: model + created: + type: integer + title: Created + owned_by: + type: string + title: Owned By + workspace_id: + type: string + title: Workspace Id + root: + type: string + title: Root + root_version: + type: string + title: Root Version + archived: + type: boolean + title: Archived + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: + anyOf: + - type: string + - type: 'null' + title: Description + capabilities: + $ref: '#/components/schemas/FTModelCapabilitiesOut' + max_context_length: + type: integer + title: Max Context Length + default: 32768 + aliases: + type: array + items: + type: string + title: Aliases + default: [] + job: + type: string + title: Job + format: uuid + model_type: + type: string + title: Model Type + default: completion + const: completion + title: CompletionFTModelOut + required: + - id + - created + - owned_by + - workspace_id + - root + - root_version + - archived + - capabilities + - job + FTModelCapabilitiesOut: + type: object + properties: + completion_chat: + type: boolean + title: Completion Chat + default: true + completion_fim: + type: boolean + title: Completion Fim + default: false + function_calling: + type: boolean + title: Function Calling + default: false + fine_tuning: + type: boolean + title: Fine Tuning + default: false + classification: + type: boolean + title: Classification + default: false + title: FTModelCapabilitiesOut + UpdateFTModelIn: + type: object + properties: + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: + anyOf: + - type: string + - type: 'null' + title: Description + title: UpdateFTModelIn + ArchiveFTModelOut: + type: object + properties: + id: + type: string + title: Id + object: + type: string + title: Object + default: model + const: model + archived: + type: boolean + title: Archived + default: true + title: ArchiveFTModelOut + required: + - id + UnarchiveFTModelOut: + type: object + properties: + id: + type: string + title: Id + object: + type: string + title: Object + default: model + const: model + archived: + type: boolean + title: Archived + default: false + title: UnarchiveFTModelOut + required: + - id + BatchJobStatus: + type: string + title: BatchJobStatus + enum: + - QUEUED + - RUNNING + - SUCCESS + - FAILED + - TIMEOUT_EXCEEDED + - CANCELLATION_REQUESTED + - CANCELLED + BatchError: + type: object + properties: + message: + type: string + title: Message + count: + type: integer + title: Count + default: 1 + title: BatchError + required: + - message + BatchJobOut: + type: object + properties: + id: + type: string + title: Id + object: + type: string + title: Object + default: batch + const: batch + input_files: + type: array + items: + type: string + format: uuid + title: Input Files + metadata: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Metadata + endpoint: + type: string + title: Endpoint + model: + anyOf: + - type: string + - type: 'null' + title: Model + agent_id: + anyOf: + - type: string + - type: 'null' + title: Agent Id + output_file: + anyOf: + - type: string + format: uuid + - type: 'null' + title: Output File + error_file: + anyOf: + - type: string + format: uuid + - type: 'null' + title: Error File + errors: + type: array + items: + $ref: '#/components/schemas/BatchError' + title: Errors + outputs: + anyOf: + - type: array + items: + type: object + additionalProperties: true + - type: 'null' + title: Outputs + status: + $ref: '#/components/schemas/BatchJobStatus' + created_at: + type: integer + title: Created At + total_requests: + type: integer + title: Total Requests + completed_requests: + type: integer + title: Completed Requests + succeeded_requests: + type: integer + title: Succeeded Requests + failed_requests: + type: integer + title: Failed Requests + started_at: + anyOf: + - type: integer + - type: 'null' + title: Started At + completed_at: + anyOf: + - type: integer + - type: 'null' + title: Completed At + title: BatchJobOut + required: + - id + - input_files + - endpoint + - errors + - status + - created_at + - total_requests + - completed_requests + - succeeded_requests + - failed_requests + BatchJobsOut: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/BatchJobOut' + title: Data + default: [] + object: + type: string + title: Object + default: list + const: list + total: + type: integer + title: Total + title: BatchJobsOut + required: + - total + ApiEndpoint: + type: string + title: ApiEndpoint + enum: + - /v1/chat/completions + - /v1/embeddings + - /v1/fim/completions + - /v1/moderations + - /v1/chat/moderations + - /v1/ocr + - /v1/classifications + - /v1/chat/classifications + - /v1/conversations + - /v1/audio/transcriptions + BatchJobIn: + type: object + properties: + input_files: + anyOf: + - type: array + items: + type: string + format: uuid + - type: 'null' + title: Input Files + description: 'The list of input files to be used for batch inference, these files should be `jsonl` files, containing the input data corresponding to the bory request for the batch inference in a "body" field. An example of such file is the following: ```json {"custom_id": "0", "body": {"max_tokens": 100, "messages": [{"role": "user", "content": "What is the best French cheese?"}]}} {"custom_id": "1", "body": {"max_tokens": 100, "messages": [{"role": "user", "content": "What is the best French wine?"}]}} ```' + requests: + anyOf: + - type: array + items: + $ref: '#/components/schemas/BatchRequest' + maxItems: 10000 + - type: 'null' + title: Requests + endpoint: + $ref: '#/components/schemas/ApiEndpoint' + examples: + - /v1/chat/completions + - /v1/embeddings + - /v1/fim/completions + description: The endpoint to be used for batch inference. + model: + anyOf: + - type: string + - type: 'null' + examples: + - mistral-small-latest + - mistral-medium-latest + title: Model + description: The model to be used for batch inference. + agent_id: + anyOf: + - type: string + - type: 'null' + title: Agent Id + description: In case you want to use a specific agent from the **deprecated** agents api for batch inference, you can specify the agent ID here. + metadata: + anyOf: + - type: object + propertyNames: + maxLength: 32 + minLength: 1 + additionalProperties: + type: string + maxLength: 512 + minLength: 1 + - type: 'null' + title: Metadata + description: The metadata of your choice to be associated with the batch inference job. + timeout_hours: + type: integer + title: Timeout Hours + description: The timeout in hours for the batch inference job. + default: 24 + title: BatchJobIn + required: + - endpoint + BatchRequest: + type: object + properties: + custom_id: + anyOf: + - type: string + - type: 'null' + title: Custom Id + body: + type: object + title: Body + additionalProperties: true + title: BatchRequest + required: + - body + AssistantMessage: + type: object + properties: + role: + type: string + title: Role + default: assistant + const: assistant + content: + anyOf: + - type: string + - type: 'null' + - type: array + items: + $ref: '#/components/schemas/ContentChunk' + title: Content + tool_calls: + anyOf: + - type: array + items: + $ref: '#/components/schemas/ToolCall' + - type: 'null' + title: Tool Calls + prefix: + type: boolean + title: Prefix + description: Set this to `true` when adding an assistant message as prefix to condition the model response. The role of the prefix message is to force the model to start its answer by the content of the message. + default: false + title: AssistantMessage + additionalProperties: false + AudioChunk: + type: object + properties: + type: + type: string + title: Type + default: input_audio + const: input_audio + input_audio: + anyOf: + - type: string + - type: string + format: binary + title: Input Audio + title: AudioChunk + required: + - input_audio + additionalProperties: false + ChatCompletionRequest: + type: object + properties: + model: + type: string + examples: + - mistral-large-latest + title: Model + description: ID of the model to use. You can use the [List Available Models](/api/#tag/models/operation/list_models_v1_models_get) API to see all of your available models, or see our [Model overview](/models) for model descriptions. + temperature: + anyOf: + - type: number + maximum: 1.5 + minimum: 0 + - type: 'null' + title: Temperature + description: What sampling temperature to use, we recommend between 0.0 and 0.7. Higher values like 0.7 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. The default value varies depending on the model you are targeting. Call the `/models` endpoint to retrieve the appropriate value. + top_p: + type: number + title: Top P + maximum: 1 + minimum: 0 + description: Nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or `temperature` but not both. + default: 1.0 + max_tokens: + anyOf: + - type: integer + minimum: 0 + - type: 'null' + title: Max Tokens + description: The maximum number of tokens to generate in the completion. The token count of your prompt plus `max_tokens` cannot exceed the model's context length. + stream: + type: boolean + title: Stream + description: 'Whether to stream back partial progress. If set, tokens will be sent as data-only server-side events as they become available, with the stream terminated by a data: [DONE] message. Otherwise, the server will hold the request open until the timeout or until completion, with the response containing the full result as JSON.' + default: false + stop: + anyOf: + - type: string + - type: array + items: + type: string + title: Stop + description: Stop generation if this token is detected. Or if one of these tokens is detected when providing an array + random_seed: + anyOf: + - type: integer + minimum: 0 + - type: 'null' + title: Random Seed + description: The seed to use for random sampling. If set, different calls will generate deterministic results. + metadata: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Metadata + messages: + type: array + examples: + - - role: user + content: Who is the best French painter? Answer in one short sentence. + items: + oneOf: + - $ref: '#/components/schemas/SystemMessage' + - $ref: '#/components/schemas/UserMessage' + - $ref: '#/components/schemas/AssistantMessage' + - $ref: '#/components/schemas/ToolMessage' + discriminator: + propertyName: role + mapping: + assistant: '#/components/schemas/AssistantMessage' + system: '#/components/schemas/SystemMessage' + tool: '#/components/schemas/ToolMessage' + user: '#/components/schemas/UserMessage' + title: Messages + description: The prompt(s) to generate completions for, encoded as a list of dict with role and content. + response_format: + $ref: '#/components/schemas/ResponseFormat' + tools: + anyOf: + - type: array + items: + $ref: '#/components/schemas/Tool' + - type: 'null' + title: Tools + description: A list of tools the model may call. Use this to provide a list of functions the model may generate JSON inputs for. + tool_choice: + anyOf: + - $ref: '#/components/schemas/ToolChoice' + - $ref: '#/components/schemas/ToolChoiceEnum' + title: Tool Choice + description: 'Controls which (if any) tool is called by the model. `none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `any` or `required` means the model must call one or more tools. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool.' + default: auto + presence_penalty: + type: number + title: Presence Penalty + maximum: 2 + minimum: -2 + description: The `presence_penalty` determines how much the model penalizes the repetition of words or phrases. A higher presence penalty encourages the model to use a wider variety of words and phrases, making the output more diverse and creative. + default: 0.0 + frequency_penalty: + type: number + title: Frequency Penalty + maximum: 2 + minimum: -2 + description: The `frequency_penalty` penalizes the repetition of words based on their frequency in the generated text. A higher frequency penalty discourages the model from repeating words that have already appeared frequently in the output, promoting diversity and reducing repetition. + default: 0.0 + n: + anyOf: + - type: integer + minimum: 1 + - type: 'null' + title: N + description: Number of completions to return for each request, input tokens are only billed once. + prediction: + $ref: '#/components/schemas/Prediction' + description: Enable users to specify expected results, optimizing response times by leveraging known or predictable content. This approach is especially effective for updating text documents or code files with minimal changes, reducing latency while maintaining high-quality results. + default: + type: content + content: '' + parallel_tool_calls: + type: boolean + title: Parallel Tool Calls + description: Whether to enable parallel function calling during tool use, when enabled the model can call multiple tools in parallel. + default: true + prompt_mode: + anyOf: + - $ref: '#/components/schemas/MistralPromptMode' + - type: 'null' + description: Allows toggling between the reasoning mode and no system prompt. When set to `reasoning` the system prompt for reasoning models will be used. **Deprecated for reasoning models - use `reasoning_effort` parameter instead.** + reasoning_effort: + type: string + enum: + - high + - none + description: Controls the reasoning effort level for reasoning models. "high" enables comprehensive reasoning traces, "none" disables reasoning effort. + guardrails: + anyOf: + - type: array + items: + $ref: '#/components/schemas/GuardrailConfig' + - type: 'null' + title: Guardrails + description: A list of guardrail configurations to apply to this request. Each guardrail specifies a moderation type, categories with thresholds to evaluate, and an action to take on violation. + default: null + safe_prompt: + type: boolean + description: Whether to inject a safety prompt before all conversations. + default: false + title: ChatCompletionRequest + required: + - messages + - model + additionalProperties: false + ChatModerationRequest: + type: object + properties: + input: + anyOf: + - type: array + items: + oneOf: + - $ref: '#/components/schemas/SystemMessage' + - $ref: '#/components/schemas/UserMessage' + - $ref: '#/components/schemas/AssistantMessage' + - $ref: '#/components/schemas/ToolMessage' + discriminator: + propertyName: role + mapping: + assistant: '#/components/schemas/AssistantMessage' + system: '#/components/schemas/SystemMessage' + tool: '#/components/schemas/ToolMessage' + user: '#/components/schemas/UserMessage' + - type: array + items: + type: array + items: + oneOf: + - $ref: '#/components/schemas/SystemMessage' + - $ref: '#/components/schemas/UserMessage' + - $ref: '#/components/schemas/AssistantMessage' + - $ref: '#/components/schemas/ToolMessage' + discriminator: + propertyName: role + mapping: + assistant: '#/components/schemas/AssistantMessage' + system: '#/components/schemas/SystemMessage' + tool: '#/components/schemas/ToolMessage' + user: '#/components/schemas/UserMessage' + title: Input + description: Chat to classify + model: + type: string + title: Model + title: ChatModerationRequest + required: + - input + - model + additionalProperties: false + ClassificationRequest: + type: object + properties: + model: + type: string + examples: + - mistral-moderation-latest + title: Model + description: ID of the model to use. + metadata: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Metadata + input: + anyOf: + - type: string + - type: array + items: + type: string + title: Input + description: Text to classify. + title: ClassificationRequest + required: + - input + - model + additionalProperties: false + EmbeddingDtype: + type: string + title: EmbeddingDtype + enum: + - float + - int8 + - uint8 + - binary + - ubinary + EmbeddingRequest: + type: object + properties: + model: + type: string + title: Model + description: ID of the model to use. + example: mistral-embed + metadata: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Metadata + input: + anyOf: + - type: string + - type: array + items: + type: string + title: Input + description: Text to embed. + example: + - Embed this sentence. + - As well as this one. + output_dimension: + anyOf: + - exclusiveMinimum: 0 + type: integer + - type: 'null' + title: Output Dimension + description: The dimension of the output embeddings when feature available. If not provided, a default output dimension will be used. + output_dtype: + $ref: '#/components/schemas/EmbeddingDtype' + description: The data type of the output embeddings when feature available. If not provided, a default output data type will be used. + default: float + encoding_format: + $ref: '#/components/schemas/EncodingFormat' + description: The format of embeddings in the response. + default: float + title: EmbeddingRequest + required: + - input + - model + additionalProperties: false + EncodingFormat: + type: string + title: EncodingFormat + enum: + - float + - base64 + FIMCompletionRequest: + type: object + properties: + model: + type: string + examples: + - codestral-latest + title: Model + description: ID of the model with FIM to use. + default: codestral-2404 + temperature: + anyOf: + - type: number + maximum: 1.5 + minimum: 0 + - type: 'null' + title: Temperature + description: What sampling temperature to use, we recommend between 0.0 and 0.7. Higher values like 0.7 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. The default value varies depending on the model you are targeting. Call the `/models` endpoint to retrieve the appropriate value. + top_p: + type: number + title: Top P + maximum: 1 + minimum: 0 + description: Nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or `temperature` but not both. + default: 1.0 + max_tokens: + anyOf: + - type: integer + minimum: 0 + - type: 'null' + title: Max Tokens + description: The maximum number of tokens to generate in the completion. The token count of your prompt plus `max_tokens` cannot exceed the model's context length. + stream: + type: boolean + title: Stream + description: 'Whether to stream back partial progress. If set, tokens will be sent as data-only server-side events as they become available, with the stream terminated by a data: [DONE] message. Otherwise, the server will hold the request open until the timeout or until completion, with the response containing the full result as JSON.' + default: false + stop: + anyOf: + - type: string + - type: array + items: + type: string + title: Stop + description: Stop generation if this token is detected. Or if one of these tokens is detected when providing an array + random_seed: + anyOf: + - type: integer + minimum: 0 + - type: 'null' + title: Random Seed + description: The seed to use for random sampling. If set, different calls will generate deterministic results. + metadata: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Metadata + prompt: + type: string + examples: + - def + title: Prompt + description: The text/code to complete. + suffix: + anyOf: + - type: string + - type: 'null' + examples: + - return a+b + title: Suffix + description: Optional text/code that adds more context for the model. When given a `prompt` and a `suffix` the model will fill what is between them. When `suffix` is not provided, the model will simply execute completion starting with `prompt`. + default: '' + min_tokens: + anyOf: + - type: integer + minimum: 0 + - type: 'null' + title: Min Tokens + description: The minimum number of tokens to generate in the completion. + title: FIMCompletionRequest + required: + - prompt + - model + additionalProperties: false + FileChunk: + type: object + properties: + type: + type: string + title: Type + default: file + const: file + file_id: + type: string + title: File Id + format: uuid + title: FileChunk + required: + - file_id + additionalProperties: false + FunctionCall: + type: object + properties: + name: + type: string + title: Name + arguments: + title: Arguments + anyOf: + - type: object + additionalProperties: true + - type: string + title: FunctionCall + required: + - name + - arguments + additionalProperties: false + FunctionName: + type: object + properties: + name: + type: string + title: Name + title: FunctionName + required: + - name + additionalProperties: false + description: this restriction of `Function` is used to select a specific function to call + InstructRequest: + type: object + properties: + messages: + type: array + items: + oneOf: + - $ref: '#/components/schemas/SystemMessage' + - $ref: '#/components/schemas/UserMessage' + - $ref: '#/components/schemas/AssistantMessage' + - $ref: '#/components/schemas/ToolMessage' + discriminator: + propertyName: role + mapping: + assistant: '#/components/schemas/AssistantMessage' + system: '#/components/schemas/SystemMessage' + tool: '#/components/schemas/ToolMessage' + user: '#/components/schemas/UserMessage' + title: Messages + title: InstructRequest + required: + - messages + additionalProperties: false + MistralPromptMode: + type: string + title: MistralPromptMode + enum: + - reasoning + description: 'Available options to the prompt_mode argument on the chat completion endpoint. + + Values represent high-level intent. Assignment to actual SPs is handled internally. + + System prompt may include knowledge cutoff date, model capabilities, tone to use, safety guidelines, etc.' + OCRImageObject: + type: object + properties: + id: + type: string + title: Id + description: Image ID for extracted image in a page + top_left_x: + anyOf: + - type: integer + minimum: 0 + - type: 'null' + title: Top Left X + description: X coordinate of top-left corner of the extracted image + top_left_y: + anyOf: + - type: integer + minimum: 0 + - type: 'null' + title: Top Left Y + description: Y coordinate of top-left corner of the extracted image + bottom_right_x: + anyOf: + - type: integer + minimum: 0 + - type: 'null' + title: Bottom Right X + description: X coordinate of bottom-right corner of the extracted image + bottom_right_y: + anyOf: + - type: integer + minimum: 0 + - type: 'null' + title: Bottom Right Y + description: Y coordinate of bottom-right corner of the extracted image + image_base64: + anyOf: + - type: string + - type: 'null' + title: Image Base64 + description: Base64 string of the extracted image + image_annotation: + anyOf: + - type: string + - type: 'null' + title: Image Annotation + description: Annotation of the extracted image in json str + title: OCRImageObject + required: + - id + - top_left_x + - top_left_y + - bottom_right_x + - bottom_right_y + additionalProperties: false + OCRPageDimensions: + type: object + properties: + dpi: + type: integer + title: Dpi + minimum: 0 + description: Dots per inch of the page-image + height: + type: integer + title: Height + minimum: 0 + description: Height of the image in pixels + width: + type: integer + title: Width + minimum: 0 + description: Width of the image in pixels + title: OCRPageDimensions + required: + - dpi + - height + - width + additionalProperties: false + OCRPageObject: + type: object + properties: + index: + type: integer + title: Index + minimum: 0 + description: The page index in a pdf document starting from 0 + markdown: + type: string + title: Markdown + description: The markdown string response of the page + images: + type: array + items: + $ref: '#/components/schemas/OCRImageObject' + title: Images + description: List of all extracted images in the page + tables: + type: array + items: + $ref: '#/components/schemas/OCRTableObject' + title: Tables + description: List of all extracted tables in the page + hyperlinks: + type: array + items: + type: string + title: Hyperlinks + description: List of all hyperlinks in the page + header: + anyOf: + - type: string + - type: 'null' + title: Header + description: Header of the page + footer: + anyOf: + - type: string + - type: 'null' + title: Footer + description: Footer of the page + dimensions: + anyOf: + - $ref: '#/components/schemas/OCRPageDimensions' + - type: 'null' + description: The dimensions of the PDF Page's screenshot image + title: OCRPageObject + required: + - index + - markdown + - images + - dimensions + additionalProperties: false + OCRRequest: + type: object + properties: + model: + anyOf: + - type: string + - type: 'null' + title: Model + id: + type: string + title: Id + document: + anyOf: + - $ref: '#/components/schemas/FileChunk' + - $ref: '#/components/schemas/DocumentURLChunk' + - $ref: '#/components/schemas/ImageURLChunk' + title: Document + description: Document to run OCR on + pages: + anyOf: + - type: array + items: + type: integer + - type: 'null' + title: Pages + description: 'Specific pages user wants to process in various formats: single number, range, or list of both. Starts from 0' + include_image_base64: + anyOf: + - type: boolean + - type: 'null' + title: Include Image Base64 + description: Include image URLs in response + image_limit: + anyOf: + - type: integer + - type: 'null' + title: Image Limit + description: Max images to extract + image_min_size: + anyOf: + - type: integer + - type: 'null' + title: Image Min Size + description: Minimum height and width of image to extract + bbox_annotation_format: + anyOf: + - $ref: '#/components/schemas/ResponseFormat' + - type: 'null' + description: Structured output class for extracting useful information from each extracted bounding box / image from document. Only json_schema is valid for this field + document_annotation_format: + anyOf: + - $ref: '#/components/schemas/ResponseFormat' + - type: 'null' + description: Structured output class for extracting useful information from the entire document. Only json_schema is valid for this field + document_annotation_prompt: + anyOf: + - type: string + - type: 'null' + title: Document Annotation Prompt + description: Optional prompt to guide the model in extracting structured output from the entire document. A document_annotation_format must be provided. + table_format: + anyOf: + - type: string + enum: + - markdown + - html + - type: 'null' + title: Table Format + extract_header: + type: boolean + title: Extract Header + default: false + extract_footer: + type: boolean + title: Extract Footer + default: false + title: OCRRequest + required: + - document + - model + additionalProperties: false + OCRResponse: + type: object + properties: + pages: + type: array + items: + $ref: '#/components/schemas/OCRPageObject' + title: Pages + description: List of OCR info for pages. + model: + type: string + title: Model + description: The model used to generate the OCR. + document_annotation: + anyOf: + - type: string + - type: 'null' + title: Document Annotation + description: Formatted response in the request_format if provided in json str + usage_info: + $ref: '#/components/schemas/OCRUsageInfo' + description: Usage info for the OCR request. + title: OCRResponse + required: + - pages + - model + - usage_info + additionalProperties: false + OCRTableObject: + type: object + properties: + id: + type: string + title: Id + description: Table ID for extracted table in a page + content: + type: string + title: Content + description: Content of the table in the given format + format: + type: string + title: Format + enum: + - markdown + - html + description: Format of the table + title: OCRTableObject + required: + - id + - content + - format + additionalProperties: false + OCRUsageInfo: + type: object + properties: + pages_processed: + type: integer + title: Pages Processed + minimum: 0 + description: Number of pages processed + doc_size_bytes: + anyOf: + - type: integer + - type: 'null' + title: Doc Size Bytes + description: Document size in bytes + title: OCRUsageInfo + required: + - pages_processed + additionalProperties: false + SystemMessage: + type: object + properties: + role: + type: string + title: Role + default: system + const: system + content: + anyOf: + - type: string + - type: array + items: + $ref: '#/components/schemas/SystemMessageContentChunks' + title: Content + title: SystemMessage + required: + - content + additionalProperties: false + Tool: + type: object + properties: + type: + $ref: '#/components/schemas/ToolTypes' + default: function + function: + $ref: '#/components/schemas/Function' + title: Tool + required: + - function + additionalProperties: false + ToolCall: + type: object + properties: + id: + type: string + title: Id + default: 'null' + type: + $ref: '#/components/schemas/ToolTypes' + default: function + function: + $ref: '#/components/schemas/FunctionCall' + index: + type: integer + title: Index + default: 0 + title: ToolCall + required: + - function + additionalProperties: false + ToolChoice: + type: object + properties: + type: + $ref: '#/components/schemas/ToolTypes' + default: function + function: + $ref: '#/components/schemas/FunctionName' + title: ToolChoice + required: + - function + additionalProperties: false + description: ToolChoice is either a ToolChoiceEnum or a ToolChoice + ToolMessage: + type: object + properties: + role: + type: string + title: Role + default: tool + const: tool + content: + anyOf: + - type: string + - type: 'null' + - type: array + items: + $ref: '#/components/schemas/ContentChunk' + title: Content + tool_call_id: + anyOf: + - type: string + - type: 'null' + title: Tool Call Id + name: + anyOf: + - type: string + - type: 'null' + title: Name + title: ToolMessage + required: + - content + additionalProperties: false + ToolTypes: + type: string + title: ToolTypes + enum: + - function + TranscriptionResponse: + type: object + properties: + model: + type: string + title: Model + text: + type: string + title: Text + language: + anyOf: + - type: string + pattern: ^\w{2}$ + - type: 'null' + title: Language + segments: + type: array + items: + $ref: '#/components/schemas/TranscriptionSegmentChunk' + title: Segments + usage: + $ref: '#/components/schemas/UsageInfo' + title: TranscriptionResponse + required: + - model + - text + - language + - usage + additionalProperties: false + TranscriptionSegmentChunk: + type: object + properties: + type: + type: string + title: Type + default: transcription_segment + const: transcription_segment + text: + type: string + title: Text + start: + type: number + title: Start + end: + type: number + title: End + score: + anyOf: + - type: number + - type: 'null' + title: Score + speaker_id: + anyOf: + - type: string + - type: 'null' + title: Speaker Id + title: TranscriptionSegmentChunk + required: + - text + - start + - end + additionalProperties: false + UsageInfo: + type: object + properties: + prompt_tokens: + type: integer + title: Prompt Tokens + default: 0 + completion_tokens: + title: Completion Tokens + default: 0 + type: integer + total_tokens: + type: integer + title: Total Tokens + default: 0 + prompt_audio_seconds: + anyOf: + - type: integer + - type: 'null' + title: Prompt Audio Seconds + title: UsageInfo + additionalProperties: false + required: + - prompt_tokens + - completion_tokens + - total_tokens + UserMessage: + type: object + properties: + role: + type: string + title: Role + default: user + const: user + content: + anyOf: + - type: string + - type: 'null' + - type: array + items: + $ref: '#/components/schemas/ContentChunk' + title: Content + title: UserMessage + required: + - content + additionalProperties: false + File: + type: string + title: File + format: binary + description: "The File object (not file name) to be uploaded.\n To upload a file and specify a custom file name you should format your request as such:\n ```bash\n file=@path/to/your/file.jsonl;filename=custom_name.jsonl\n ```\n Otherwise, you can just keep the original file name:\n ```bash\n file=@path/to/your/file.jsonl\n ```" + TimestampGranularity: + type: string + title: TimestampGranularity + enum: + - segment + - word + AudioTranscriptionRequest: + type: object + properties: + model: + type: string + examples: + - voxtral-mini-latest + - voxtral-mini-2507 + title: Model + description: ID of the model to be used. + file: + anyOf: + - $ref: '#/components/schemas/File' + - type: 'null' + title: File + default: null + file_url: + anyOf: + - type: string + maxLength: 2083 + minLength: 1 + format: uri + - type: 'null' + title: File Url + description: Url of a file to be transcribed + default: null + file_id: + anyOf: + - type: string + - type: 'null' + title: File Id + description: ID of a file uploaded to /v1/files + default: null + language: + anyOf: + - type: string + pattern: ^\w{2}$ + - type: 'null' + title: Language + description: Language of the audio, e.g. 'en'. Providing the language can boost accuracy. + default: null + temperature: + anyOf: + - type: number + - type: 'null' + title: Temperature + default: null + stream: + type: boolean + title: Stream + default: false + const: false + diarize: + type: boolean + title: Diarize + default: false + context_bias: + type: array + items: + type: string + pattern: ^[^,\s]+$ + title: Context Bias + default: [] + timestamp_granularities: + type: array + items: + $ref: '#/components/schemas/TimestampGranularity' + title: Timestamp Granularities + description: Granularities of timestamps to include in the response. + $defs: + TimestampGranularity: + type: string + title: TimestampGranularity + enum: + - segment + - word + title: AudioTranscriptionRequest + required: + - model + AudioTranscriptionRequestStream: + type: object + properties: + model: + type: string + title: Model + file: + anyOf: + - $ref: '#/components/schemas/File' + - type: 'null' + title: File + default: null + file_url: + anyOf: + - type: string + maxLength: 2083 + minLength: 1 + format: uri + - type: 'null' + title: File Url + description: Url of a file to be transcribed + default: null + file_id: + anyOf: + - type: string + - type: 'null' + title: File Id + description: ID of a file uploaded to /v1/files + default: null + language: + anyOf: + - type: string + pattern: ^\w{2}$ + - type: 'null' + title: Language + description: Language of the audio, e.g. 'en'. Providing the language can boost accuracy. + default: null + temperature: + anyOf: + - type: number + - type: 'null' + title: Temperature + default: null + stream: + type: boolean + title: Stream + default: true + const: true + diarize: + type: boolean + title: Diarize + default: false + context_bias: + type: array + items: + type: string + pattern: ^[^,\s]+$ + title: Context Bias + default: [] + timestamp_granularities: + type: array + items: + $ref: '#/components/schemas/TimestampGranularity' + title: Timestamp Granularities + description: Granularities of timestamps to include in the response. + $defs: + TimestampGranularity: + type: string + title: TimestampGranularity + enum: + - segment + - word + title: AudioTranscriptionRequestStream + required: + - model + TranscriptionStreamLanguage: + type: object + properties: + type: + type: string + title: Type + default: transcription.language + const: transcription.language + audio_language: + type: string + title: Audio Language + pattern: ^\w{2}$ + title: TranscriptionStreamLanguage + required: + - audio_language + additionalProperties: false + TranscriptionStreamSegmentDelta: + type: object + properties: + type: + type: string + title: Type + default: transcription.segment + const: transcription.segment + text: + type: string + title: Text + start: + type: number + title: Start + end: + type: number + title: End + speaker_id: + anyOf: + - type: string + - type: 'null' + title: Speaker Id + default: null + title: TranscriptionStreamSegmentDelta + required: + - text + - start + - end + additionalProperties: false + TranscriptionStreamTextDelta: + type: object + properties: + type: + type: string + title: Type + default: transcription.text.delta + const: transcription.text.delta + text: + type: string + title: Text + title: TranscriptionStreamTextDelta + required: + - text + additionalProperties: false + TranscriptionStreamDone: + type: object + properties: + model: + type: string + title: Model + text: + type: string + title: Text + language: + anyOf: + - type: string + pattern: ^\w{2}$ + - type: 'null' + title: Language + segments: + type: array + items: + $ref: '#/components/schemas/TranscriptionSegmentChunk' + title: Segments + usage: + $ref: '#/components/schemas/UsageInfo' + type: + type: string + title: Type + default: transcription.done + const: transcription.done + title: TranscriptionStreamDone + required: + - model + - text + - language + - usage + additionalProperties: false + TranscriptionStreamEvents: + type: object + properties: + event: + $ref: '#/components/schemas/TranscriptionStreamEventTypes' + data: + oneOf: + - $ref: '#/components/schemas/TranscriptionStreamTextDelta' + - $ref: '#/components/schemas/TranscriptionStreamLanguage' + - $ref: '#/components/schemas/TranscriptionStreamSegmentDelta' + - $ref: '#/components/schemas/TranscriptionStreamDone' + discriminator: + propertyName: type + mapping: + transcription.done: '#/components/schemas/TranscriptionStreamDone' + transcription.language: '#/components/schemas/TranscriptionStreamLanguage' + transcription.segment: '#/components/schemas/TranscriptionStreamSegmentDelta' + transcription.text.delta: '#/components/schemas/TranscriptionStreamTextDelta' + title: Data + title: TranscriptionStreamEvents + required: + - event + - data + additionalProperties: false + TranscriptionStreamEventTypes: + type: string + title: TranscriptionStreamEventTypes + enum: + - transcription.language + - transcription.segment + - transcription.text.delta + - transcription.done + RealtimeTranscriptionClientMessage: + oneOf: + - $ref: '#/components/schemas/RealtimeTranscriptionSessionUpdateMessage' + - $ref: '#/components/schemas/RealtimeTranscriptionInputAudioAppend' + - $ref: '#/components/schemas/RealtimeTranscriptionInputAudioFlush' + - $ref: '#/components/schemas/RealtimeTranscriptionInputAudioEnd' + discriminator: + propertyName: type + mapping: + input_audio.append: '#/components/schemas/RealtimeTranscriptionInputAudioAppend' + input_audio.end: '#/components/schemas/RealtimeTranscriptionInputAudioEnd' + input_audio.flush: '#/components/schemas/RealtimeTranscriptionInputAudioFlush' + session.update: '#/components/schemas/RealtimeTranscriptionSessionUpdateMessage' + title: RealtimeTranscriptionClientMessage + AudioEncoding: + type: string + title: AudioEncoding + enum: + - pcm_s16le + - pcm_s32le + - pcm_f16le + - pcm_f32le + - pcm_mulaw + - pcm_alaw + AudioFormat: + type: object + properties: + encoding: + $ref: '#/components/schemas/AudioEncoding' + sample_rate: + type: integer + title: Sample Rate + maximum: 96000 + minimum: 8000 + title: AudioFormat + required: + - encoding + - sample_rate + additionalProperties: false + RealtimeTranscriptionInputAudioAppend: + type: object + properties: + type: + type: string + title: Type + default: input_audio.append + const: input_audio.append + audio: + type: string + title: Audio + format: base64 + description: 'Base64-encoded raw PCM bytes matching the current audio_format. Max decoded size: 262144 bytes.' + title: RealtimeTranscriptionInputAudioAppend + required: + - audio + additionalProperties: false + RealtimeTranscriptionInputAudioEnd: + type: object + properties: + type: + type: string + title: Type + default: input_audio.end + const: input_audio.end + title: RealtimeTranscriptionInputAudioEnd + additionalProperties: false + RealtimeTranscriptionInputAudioFlush: + type: object + properties: + type: + type: string + title: Type + default: input_audio.flush + const: input_audio.flush + title: RealtimeTranscriptionInputAudioFlush + additionalProperties: false + RealtimeTranscriptionSessionUpdateMessage: + type: object + properties: + type: + type: string + title: Type + default: session.update + const: session.update + session: + $ref: '#/components/schemas/RealtimeTranscriptionSessionUpdatePayload' + title: RealtimeTranscriptionSessionUpdateMessage + required: + - session + additionalProperties: false + RealtimeTranscriptionSessionUpdatePayload: + type: object + properties: + audio_format: + anyOf: + - $ref: '#/components/schemas/AudioFormat' + - type: 'null' + description: Set before sending audio. Audio format updates are rejected after audio starts. + default: null + target_streaming_delay_ms: + anyOf: + - type: integer + - type: 'null' + title: Target Streaming Delay Ms + description: Set before sending audio. Streaming delay updates are rejected after audio starts. + default: null + title: RealtimeTranscriptionSessionUpdatePayload + additionalProperties: false + AgentsCompletionRequest: + type: object + properties: + max_tokens: + anyOf: + - type: integer + minimum: 0 + - type: 'null' + title: Max Tokens + description: The maximum number of tokens to generate in the completion. The token count of your prompt plus `max_tokens` cannot exceed the model's context length. + stream: + type: boolean + title: Stream + description: 'Whether to stream back partial progress. If set, tokens will be sent as data-only server-side events as they become available, with the stream terminated by a data: [DONE] message. Otherwise, the server will hold the request open until the timeout or until completion, with the response containing the full result as JSON.' + default: false + stop: + anyOf: + - type: string + - type: array + items: + type: string + title: Stop + description: Stop generation if this token is detected. Or if one of these tokens is detected when providing an array + random_seed: + anyOf: + - type: integer + minimum: 0 + - type: 'null' + title: Random Seed + description: The seed to use for random sampling. If set, different calls will generate deterministic results. + metadata: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Metadata + messages: + type: array + examples: + - - role: user + content: Who is the best French painter? Answer in one short sentence. + items: + oneOf: + - $ref: '#/components/schemas/SystemMessage' + - $ref: '#/components/schemas/UserMessage' + - $ref: '#/components/schemas/AssistantMessage' + - $ref: '#/components/schemas/ToolMessage' + discriminator: + propertyName: role + mapping: + assistant: '#/components/schemas/AssistantMessage' + system: '#/components/schemas/SystemMessage' + tool: '#/components/schemas/ToolMessage' + user: '#/components/schemas/UserMessage' + title: Messages + description: The prompt(s) to generate completions for, encoded as a list of dict with role and content. + response_format: + $ref: '#/components/schemas/ResponseFormat' + tools: + anyOf: + - type: array + items: + $ref: '#/components/schemas/Tool' + - type: 'null' + title: Tools + tool_choice: + anyOf: + - $ref: '#/components/schemas/ToolChoice' + - $ref: '#/components/schemas/ToolChoiceEnum' + title: Tool Choice + default: auto + presence_penalty: + type: number + title: Presence Penalty + maximum: 2 + minimum: -2 + description: The `presence_penalty` determines how much the model penalizes the repetition of words or phrases. A higher presence penalty encourages the model to use a wider variety of words and phrases, making the output more diverse and creative. + default: 0.0 + frequency_penalty: + type: number + title: Frequency Penalty + maximum: 2 + minimum: -2 + description: The `frequency_penalty` penalizes the repetition of words based on their frequency in the generated text. A higher frequency penalty discourages the model from repeating words that have already appeared frequently in the output, promoting diversity and reducing repetition. + default: 0.0 + n: + anyOf: + - type: integer + minimum: 1 + - type: 'null' + title: N + description: Number of completions to return for each request, input tokens are only billed once. + prediction: + $ref: '#/components/schemas/Prediction' + description: Enable users to specify expected results, optimizing response times by leveraging known or predictable content. This approach is especially effective for updating text documents or code files with minimal changes, reducing latency while maintaining high-quality results. + default: + type: content + content: '' + parallel_tool_calls: + type: boolean + title: Parallel Tool Calls + default: true + prompt_mode: + anyOf: + - $ref: '#/components/schemas/MistralPromptMode' + - type: 'null' + description: Allows toggling between the reasoning mode and no system prompt. When set to `reasoning` the system prompt for reasoning models will be used. **Deprecated for reasoning models - use `reasoning_effort` parameter instead.** + reasoning_effort: + type: string + enum: + - high + - none + description: Controls the reasoning effort level for reasoning models. "high" enables comprehensive reasoning traces, "none" disables reasoning effort. + agent_id: + type: string + description: The ID of the agent to use for this completion. + title: AgentsCompletionRequest + required: + - messages + - agent_id + additionalProperties: false + ChatClassificationRequest: + type: object + properties: + model: + type: string + title: Model + input: + $ref: '#/components/schemas/ChatClassificationRequestInputs' + title: ChatClassificationRequest + required: + - input + - model + additionalProperties: false + ChatClassificationRequestInputs: + anyOf: + - $ref: '#/components/schemas/InstructRequest' + - type: array + items: + $ref: '#/components/schemas/InstructRequest' + title: ChatClassificationRequestInputs + description: Chat to classify + ClassificationResponse: + type: object + properties: + id: + type: string + example: mod-e5cc70bb28c444948073e77776eb30ef + model: + type: string + results: + type: array + items: + type: object + title: ClassificationTargetResult + additionalProperties: + $ref: '#/components/schemas/ClassificationTargetResult' + title: ClassificationResponse + required: + - id + - model + - results + ClassificationTargetResult: + type: object + properties: + scores: + type: object + title: ClassifierTargetResultScores + additionalProperties: + type: number + title: ClassificationTargetResult + required: + - scores + ContentChunk: + oneOf: + - $ref: '#/components/schemas/TextChunk' + - $ref: '#/components/schemas/ImageURLChunk' + - $ref: '#/components/schemas/DocumentURLChunk' + - $ref: '#/components/schemas/ReferenceChunk' + - $ref: '#/components/schemas/FileChunk' + - $ref: '#/components/schemas/ThinkChunk' + - $ref: '#/components/schemas/AudioChunk' + discriminator: + propertyName: type + mapping: + image_url: '#/components/schemas/ImageURLChunk' + document_url: '#/components/schemas/DocumentURLChunk' + text: '#/components/schemas/TextChunk' + reference: '#/components/schemas/ReferenceChunk' + file: '#/components/schemas/FileChunk' + thinking: '#/components/schemas/ThinkChunk' + input_audio: '#/components/schemas/AudioChunk' + title: ContentChunk + ModerationResponse: + type: object + properties: + id: + type: string + example: mod-e5cc70bb28c444948073e77776eb30ef + model: + type: string + results: + type: array + items: + $ref: '#/components/schemas/ModerationObject' + title: ModerationResponse + required: + - id + - model + - results + ModerationObject: + type: object + properties: + categories: + type: object + additionalProperties: + type: boolean + description: Moderation result thresholds + category_scores: + type: object + additionalProperties: + type: number + description: Moderation result + title: ModerationObject + SystemMessageContentChunks: + oneOf: + - $ref: '#/components/schemas/TextChunk' + - $ref: '#/components/schemas/ThinkChunk' + discriminator: + propertyName: type + mapping: + text: '#/components/schemas/TextChunk' + thinking: '#/components/schemas/ThinkChunk' + title: SystemMessageContentChunks + DocumentOut: + type: object + properties: + id: + type: string + title: Id + format: uuid + library_id: + type: string + title: Library Id + format: uuid + hash: + anyOf: + - type: string + - type: 'null' + title: Hash + mime_type: + anyOf: + - type: string + - type: 'null' + title: Mime Type + extension: + anyOf: + - type: string + - type: 'null' + title: Extension + size: + anyOf: + - type: integer + - type: 'null' + title: Size + name: + type: string + title: Name + summary: + anyOf: + - type: string + - type: 'null' + title: Summary + created_at: + type: string + title: Created At + format: date-time + last_processed_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Last Processed At + number_of_pages: + anyOf: + - type: integer + - type: 'null' + title: Number Of Pages + process_status: + $ref: '#/components/schemas/ProcessStatus' + uploaded_by_id: + anyOf: + - type: string + format: uuid + - type: 'null' + title: Uploaded By Id + uploaded_by_type: + type: string + tokens_processing_main_content: + anyOf: + - type: integer + - type: 'null' + title: Tokens Processing Main Content + tokens_processing_summary: + anyOf: + - type: integer + - type: 'null' + title: Tokens Processing Summary + url: + anyOf: + - type: string + - type: 'null' + title: Url + attributes: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Attributes + processing_status: + type: string + title: Processing Status + readOnly: true + tokens_processing_total: + type: integer + title: Tokens Processing Total + readOnly: true + title: DocumentOut + required: + - id + - library_id + - hash + - mime_type + - extension + - size + - name + - created_at + - process_status + - uploaded_by_id + - uploaded_by_type + - processing_status + - tokens_processing_total + DocumentTextContent: + type: object + properties: + text: + type: string + title: Text + title: DocumentTextContent + required: + - text + DocumentUpdateIn: + type: object + properties: + name: + anyOf: + - type: string + - type: 'null' + title: Name + attributes: + anyOf: + - type: object + additionalProperties: + anyOf: + - type: boolean + - type: string + - type: integer + - type: number + - type: string + format: date-time + - type: array + items: + type: string + - type: array + items: + type: integer + - type: array + items: + type: number + - type: array + items: + type: boolean + - type: 'null' + title: Attributes + title: DocumentUpdateIn + FilterCondition: + type: object + properties: + field: + type: string + title: Field + op: + type: string + title: Op + enum: + - lt + - lte + - gt + - gte + - startswith + - istartswith + - endswith + - iendswith + - contains + - icontains + - matches + - notcontains + - inotcontains + - eq + - neq + - isnull + - includes + - excludes + - len_eq + value: + title: Value + title: FilterCondition + required: + - field + - op + - value + FilterGroup: + type: object + properties: + AND: + anyOf: + - type: array + items: + anyOf: + - $ref: '#/components/schemas/FilterGroup' + - $ref: '#/components/schemas/FilterCondition' + - type: 'null' + title: And + OR: + anyOf: + - type: array + items: + anyOf: + - $ref: '#/components/schemas/FilterGroup' + - $ref: '#/components/schemas/FilterCondition' + - type: 'null' + title: Or + title: FilterGroup + LibraryIn: + type: object + properties: + name: + type: string + title: Name + description: + anyOf: + - type: string + - type: 'null' + title: Description + chunk_size: + anyOf: + - type: integer + - type: 'null' + title: Chunk Size + title: LibraryIn + required: + - name + LibraryInUpdate: + type: object + properties: + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: + anyOf: + - type: string + - type: 'null' + title: Description + title: LibraryInUpdate + LibraryOut: + type: object + properties: + id: + type: string + title: Id + format: uuid + name: + type: string + title: Name + created_at: + type: string + title: Created At + format: date-time + updated_at: + type: string + title: Updated At + format: date-time + owner_id: + anyOf: + - type: string + format: uuid + - type: 'null' + title: Owner Id + owner_type: + type: string + total_size: + type: integer + title: Total Size + nb_documents: + type: integer + title: Nb Documents + chunk_size: + anyOf: + - type: integer + - type: 'null' + title: Chunk Size + emoji: + anyOf: + - type: string + - type: 'null' + title: Emoji + description: + anyOf: + - type: string + - type: 'null' + title: Description + generated_description: + anyOf: + - type: string + - type: 'null' + title: Generated Description + explicit_user_members_count: + anyOf: + - type: integer + - type: 'null' + title: Explicit User Members Count + explicit_workspace_members_count: + anyOf: + - type: integer + - type: 'null' + title: Explicit Workspace Members Count + org_sharing_role: + anyOf: + - type: string + - type: 'null' + generated_name: + anyOf: + - type: string + - type: 'null' + description: Generated Name + title: LibraryOut + required: + - id + - name + - created_at + - updated_at + - owner_id + - owner_type + - total_size + - nb_documents + - chunk_size + ListDocumentOut: + type: object + properties: + pagination: + $ref: '#/components/schemas/PaginationInfo' + data: + type: array + items: + $ref: '#/components/schemas/DocumentOut' + title: Data + title: ListDocumentOut + required: + - pagination + - data + ListLibraryOut: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/LibraryOut' + title: Data + title: ListLibraryOut + required: + - data + ListSharingOut: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/SharingOut' + title: Data + title: ListSharingOut + required: + - data + PaginationInfo: + type: object + properties: + total_items: + type: integer + title: Total Items + total_pages: + type: integer + title: Total Pages + current_page: + type: integer + title: Current Page + page_size: + type: integer + title: Page Size + has_more: + type: boolean + title: Has More + title: PaginationInfo + required: + - total_items + - total_pages + - current_page + - page_size + - has_more + ProcessStatus: + type: string + title: ProcessStatus + enum: + - self_managed + - missing_content + - noop + - done + - todo + - in_progress + - error + - waiting_for_capacity + ProcessingStatusOut: + type: object + properties: + document_id: + type: string + title: Document Id + format: uuid + process_status: + $ref: '#/components/schemas/ProcessStatus' + processing_status: + type: string + title: Processing Status + readOnly: true + title: ProcessingStatusOut + required: + - document_id + - process_status + - processing_status + ShareEnum: + type: string + title: ShareEnum + enum: + - Viewer + - Editor + x-speakeasy-unknown-values: allow + SharingDelete: + type: object + properties: + org_id: + anyOf: + - type: string + format: uuid + - type: 'null' + title: Org Id + share_with_uuid: + type: string + format: uuid + description: The id of the entity (user, workspace or organization) to share with + share_with_type: + $ref: '#/components/schemas/EntityType' + title: SharingDelete + required: + - share_with_uuid + - share_with_type + - level + SharingIn: + type: object + properties: + org_id: + anyOf: + - type: string + format: uuid + - type: 'null' + title: Org Id + level: + $ref: '#/components/schemas/ShareEnum' + share_with_uuid: + type: string + format: uuid + description: The id of the entity (user, workspace or organization) to share with + share_with_type: + $ref: '#/components/schemas/EntityType' + title: SharingIn + required: + - share_with_uuid + - share_with_type + - level + SharingOut: + type: object + properties: + library_id: + type: string + title: Library Id + format: uuid + user_id: + anyOf: + - type: string + format: uuid + - type: 'null' + title: User Id + org_id: + type: string + title: Org Id + format: uuid + role: + type: string + share_with_type: + type: string + share_with_uuid: + anyOf: + - type: string + format: uuid + - type: 'null' + title: Share With Uuid + title: SharingOut + required: + - library_id + - org_id + - role + - share_with_type + - share_with_uuid + EntityType: + type: string + title: EntityType + enum: + - User + - Workspace + - Org + description: The type of entity, used to share a library. + x-speakeasy-unknown-values: allow + BaseFieldDefinition: + type: object + properties: + name: + type: string + title: Name + label: + type: string + title: Label + type: + type: string + title: Type + enum: + - ENUM + - TEXT + - INT + - FLOAT + - BOOL + - TIMESTAMP + - ARRAY + group: + anyOf: + - type: string + - type: 'null' + title: Group + supported_operators: + type: array + items: + type: string + enum: + - lt + - lte + - gt + - gte + - startswith + - istartswith + - endswith + - iendswith + - contains + - icontains + - matches + - notcontains + - inotcontains + - eq + - neq + - isnull + - includes + - excludes + - len_eq + title: Supported Operators + readOnly: true + title: BaseFieldDefinition + required: + - name + - label + - type + - supported_operators + BaseTaskStatus: + type: string + title: BaseTaskStatus + enum: + - RUNNING + - COMPLETED + - FAILED + - CANCELED + - TERMINATED + - CONTINUED_AS_NEW + - TIMED_OUT + - UNKNOWN + CampaignPreview: + type: object + properties: + id: + type: string + title: Id + format: uuid + created_at: + type: string + title: Created At + format: date-time + updated_at: + type: string + title: Updated At + format: date-time + deleted_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Deleted At + name: + type: string + title: Name + owner_id: + type: string + title: Owner Id + format: uuid + workspace_id: + type: string + title: Workspace Id + format: uuid + description: + type: string + title: Description + max_nb_events: + type: integer + title: Max Nb Events + search_params: + $ref: '#/components/schemas/FilterPayload' + judge: + $ref: '#/components/schemas/JudgePreview' + title: CampaignPreview + required: + - id + - created_at + - updated_at + - deleted_at + - name + - owner_id + - workspace_id + - description + - max_nb_events + - search_params + - judge + CampaignPreviews: + type: object + properties: + campaigns: + $ref: '#/components/schemas/PaginatedResult_CampaignPreview_' + title: CampaignPreviews + required: + - campaigns + CampaignSelectedEvents: + type: object + properties: + completion_events: + $ref: '#/components/schemas/PaginatedResult_ChatCompletionEventPreview_' + title: CampaignSelectedEvents + required: + - completion_events + CampaignStatus: + type: object + properties: + status: + $ref: '#/components/schemas/BaseTaskStatus' + title: CampaignStatus + required: + - status + ChatCompletionEventIds: + type: object + properties: + completion_event_ids: + type: array + items: + type: string + title: Completion Event Ids + title: ChatCompletionEventIds + required: + - completion_event_ids + ChatCompletionEvent: + type: object + properties: + event_id: + type: string + title: Event Id + correlation_id: + type: string + title: Correlation Id + created_at: + type: string + title: Created At + format: date-time + extra_fields: + type: object + title: Extra Fields + additionalProperties: + anyOf: + - type: boolean + - type: integer + - type: number + - type: string + - type: string + format: date-time + - type: array + items: + type: string + - type: 'null' + nb_input_tokens: + type: integer + title: Nb Input Tokens + nb_output_tokens: + type: integer + title: Nb Output Tokens + enabled_tools: + type: array + items: + type: object + additionalProperties: true + title: Enabled Tools + request_messages: + type: array + items: + type: object + additionalProperties: true + title: Request Messages + response_messages: + type: array + items: + type: object + additionalProperties: true + title: Response Messages + nb_messages: + type: integer + title: Nb Messages + chat_transcription_events: + type: array + items: + $ref: '#/components/schemas/ChatTranscriptionEvent' + title: Chat Transcription Events + title: ChatCompletionEvent + required: + - event_id + - correlation_id + - created_at + - extra_fields + - nb_input_tokens + - nb_output_tokens + - enabled_tools + - request_messages + - response_messages + - nb_messages + - chat_transcription_events + ChatCompletionEventPreview: + type: object + properties: + event_id: + type: string + title: Event Id + correlation_id: + type: string + title: Correlation Id + created_at: + type: string + title: Created At + format: date-time + extra_fields: + type: object + title: Extra Fields + additionalProperties: + anyOf: + - type: boolean + - type: integer + - type: number + - type: string + - type: string + format: date-time + - type: array + items: + type: string + - type: 'null' + nb_input_tokens: + type: integer + title: Nb Input Tokens + nb_output_tokens: + type: integer + title: Nb Output Tokens + title: ChatCompletionEventPreview + required: + - event_id + - correlation_id + - created_at + - extra_fields + - nb_input_tokens + - nb_output_tokens + ChatCompletionEvents: + type: object + properties: + completion_events: + $ref: '#/components/schemas/FeedResult_ChatCompletionEventPreview_' + title: ChatCompletionEvents + required: + - completion_events + ChatCompletionFieldOptions: + type: object + properties: + options: + anyOf: + - type: array + items: + anyOf: + - type: string + - type: boolean + - type: 'null' + - type: 'null' + title: Options + title: ChatCompletionFieldOptions + ChatCompletionFields: + type: object + properties: + field_definitions: + type: array + items: + $ref: '#/components/schemas/BaseFieldDefinition' + title: Field Definitions + field_groups: + type: array + items: + $ref: '#/components/schemas/FieldGroup' + title: Field Groups + title: ChatCompletionFields + required: + - field_definitions + - field_groups + ChatTranscriptionEvent: + type: object + properties: + audio_url: + type: string + title: Audio Url + model: + type: string + title: Model + response_message: + type: object + title: Response Message + additionalProperties: true + title: ChatTranscriptionEvent + required: + - audio_url + - model + - response_message + ConversationPayload: + type: object + properties: + messages: + type: array + items: + type: object + additionalProperties: true + title: Messages + title: ConversationPayload + required: + - messages + additionalProperties: true + description: '' + ConversationSource: + type: string + title: ConversationSource + enum: + - EXPLORER + - UPLOADED_FILE + - DIRECT_INPUT + - PLAYGROUND + DatasetExport: + type: object + properties: + file_url: + type: string + title: File Url + title: DatasetExport + required: + - file_url + DatasetImportTask: + type: object + properties: + id: + type: string + title: Id + format: uuid + created_at: + type: string + title: Created At + format: date-time + updated_at: + type: string + title: Updated At + format: date-time + deleted_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Deleted At + creator_id: + type: string + title: Creator Id + format: uuid + dataset_id: + type: string + title: Dataset Id + format: uuid + workspace_id: + type: string + title: Workspace Id + format: uuid + status: + $ref: '#/components/schemas/BaseTaskStatus' + progress: + anyOf: + - type: integer + maximum: 100 + minimum: 0 + - type: 'null' + title: Progress + message: + anyOf: + - type: string + - type: 'null' + title: Message + title: DatasetImportTask + required: + - id + - created_at + - updated_at + - deleted_at + - creator_id + - dataset_id + - workspace_id + - status + DatasetImportTasks: + type: object + properties: + tasks: + $ref: '#/components/schemas/PaginatedResult_DatasetImportTask_' + title: DatasetImportTasks + required: + - tasks + Dataset: + type: object + properties: + id: + type: string + title: Id + format: uuid + created_at: + type: string + title: Created At + format: date-time + updated_at: + type: string + title: Updated At + format: date-time + deleted_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Deleted At + name: + type: string + title: Name + description: + type: string + title: Description + owner_id: + type: string + title: Owner Id + format: uuid + workspace_id: + type: string + title: Workspace Id + format: uuid + title: Dataset + required: + - id + - created_at + - updated_at + - deleted_at + - name + - description + - owner_id + - workspace_id + DatasetPreview: + type: object + properties: + id: + type: string + title: Id + format: uuid + created_at: + type: string + title: Created At + format: date-time + updated_at: + type: string + title: Updated At + format: date-time + deleted_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Deleted At + name: + type: string + title: Name + description: + type: string + title: Description + owner_id: + type: string + title: Owner Id + format: uuid + workspace_id: + type: string + title: Workspace Id + format: uuid + title: DatasetPreview + required: + - id + - created_at + - updated_at + - deleted_at + - name + - description + - owner_id + - workspace_id + DatasetPreviews: + type: object + properties: + datasets: + $ref: '#/components/schemas/PaginatedResult_DatasetPreview_' + title: DatasetPreviews + required: + - datasets + DatasetRecord: + type: object + properties: + id: + type: string + title: Id + format: uuid + created_at: + type: string + title: Created At + format: date-time + updated_at: + type: string + title: Updated At + format: date-time + deleted_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Deleted At + dataset_id: + type: string + title: Dataset Id + format: uuid + payload: + $ref: '#/components/schemas/ConversationPayload' + properties: + type: object + title: Properties + additionalProperties: true + source: + $ref: '#/components/schemas/ConversationSource' + title: DatasetRecord + required: + - id + - created_at + - updated_at + - deleted_at + - dataset_id + - payload + - properties + - source + DatasetRecords: + type: object + properties: + records: + $ref: '#/components/schemas/PaginatedResult_DatasetRecord_' + title: DatasetRecords + required: + - records + DeleteDatasetRecordsInSchema: + type: object + properties: + dataset_record_ids: + type: array + items: + type: string + format: uuid + title: Dataset Record Ids + maxItems: 500 + minItems: 1 + title: DeleteDatasetRecordsInSchema + required: + - dataset_record_ids + FeedResult_ChatCompletionEventPreview_: + type: object + properties: + results: + type: array + items: + $ref: '#/components/schemas/ChatCompletionEventPreview' + title: Results + next: + anyOf: + - type: string + - type: 'null' + title: Next + cursor: + anyOf: + - type: string + - type: 'null' + title: Cursor + title: FeedResult[ChatCompletionEventPreview] + FieldGroup: + type: object + properties: + name: + type: string + title: Name + label: + type: string + title: Label + title: FieldGroup + required: + - name + - label + FieldOptionCountItem: + type: object + properties: + value: + type: string + title: Value + count: + type: integer + title: Count + title: FieldOptionCountItem + required: + - value + - count + FieldOptionCountsInSchema: + type: object + properties: + filter_params: + anyOf: + - $ref: '#/components/schemas/FilterPayload' + - type: 'null' + title: FieldOptionCountsInSchema + FieldOptionCounts: + type: object + properties: + counts: + type: array + items: + $ref: '#/components/schemas/FieldOptionCountItem' + title: Counts + title: FieldOptionCounts + required: + - counts + FilterPayload: + type: object + properties: + filters: + anyOf: + - $ref: '#/components/schemas/FilterGroup' + - $ref: '#/components/schemas/FilterCondition' + - type: 'null' + title: Filters + title: FilterPayload + required: + - filters + GetChatCompletionEventIdsInSchema: + type: object + properties: + search_params: + $ref: '#/components/schemas/FilterPayload' + extra_fields: + anyOf: + - type: array + items: + type: string + - type: 'null' + title: Extra Fields + title: GetChatCompletionEventIdsInSchema + required: + - search_params + GetChatCompletionEventsInSchema: + type: object + properties: + search_params: + $ref: '#/components/schemas/FilterPayload' + extra_fields: + anyOf: + - type: array + items: + type: string + - type: 'null' + title: Extra Fields + title: GetChatCompletionEventsInSchema + required: + - search_params + JudgeClassificationOutput: + type: object + properties: + type: + type: string + title: Type + default: CLASSIFICATION + const: CLASSIFICATION + options: + type: array + items: + $ref: '#/components/schemas/JudgeClassificationOutputOption' + title: Options + title: JudgeClassificationOutput + required: + - options + JudgeClassificationOutputOption: + type: object + properties: + value: + type: string + title: Value + description: + type: string + title: Description + title: JudgeClassificationOutputOption + required: + - value + - description + JudgeOutput: + type: object + properties: + analysis: + type: string + title: Analysis + answer: + anyOf: + - type: string + - type: number + title: Answer + title: JudgeOutput + required: + - analysis + - answer + JudgeOutputType: + type: string + title: JudgeOutputType + enum: + - REGRESSION + - CLASSIFICATION + JudgePreview: + type: object + properties: + id: + type: string + title: Id + format: uuid + created_at: + type: string + title: Created At + format: date-time + updated_at: + type: string + title: Updated At + format: date-time + deleted_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Deleted At + owner_id: + type: string + title: Owner Id + format: uuid + workspace_id: + type: string + title: Workspace Id + format: uuid + name: + type: string + title: Name + description: + type: string + title: Description + model_name: + type: string + title: Model Name + output: + oneOf: + - $ref: '#/components/schemas/JudgeClassificationOutput' + - $ref: '#/components/schemas/JudgeRegressionOutput' + discriminator: + propertyName: type + mapping: + CLASSIFICATION: '#/components/schemas/JudgeClassificationOutput' + REGRESSION: '#/components/schemas/JudgeRegressionOutput' + title: Output + instructions: + type: string + title: Instructions + tools: + type: array + items: + type: string + title: Tools + up_revision: + anyOf: + - type: string + format: uuid + - type: 'null' + title: Up Revision + down_revision: + anyOf: + - type: string + format: uuid + - type: 'null' + title: Down Revision + base_revision: + anyOf: + - type: string + format: uuid + - type: 'null' + title: Base Revision + title: JudgePreview + required: + - id + - created_at + - updated_at + - deleted_at + - owner_id + - workspace_id + - name + - description + - model_name + - output + - instructions + - tools + JudgePreviews: + type: object + properties: + judges: + $ref: '#/components/schemas/PaginatedResult_JudgePreview_' + title: JudgePreviews + required: + - judges + JudgeRegressionOutput: + type: object + properties: + type: + type: string + title: Type + default: REGRESSION + const: REGRESSION + min: + type: number + title: Min + minimum: 0 + default: 0 + min_description: + type: string + title: Min Description + max: + exclusiveMaximum: 1e+09 + type: number + title: Max + default: 1 + max_description: + type: string + title: Max Description + title: JudgeRegressionOutput + required: + - min_description + - max_description + PaginatedResult_CampaignPreview_: + type: object + properties: + results: + type: array + items: + $ref: '#/components/schemas/CampaignPreview' + title: Results + count: + type: integer + title: Count + next: + anyOf: + - type: string + - type: 'null' + title: Next + previous: + anyOf: + - type: string + - type: 'null' + title: Previous + title: PaginatedResult[CampaignPreview] + required: + - count + PaginatedResult_ChatCompletionEventPreview_: + type: object + properties: + results: + type: array + items: + $ref: '#/components/schemas/ChatCompletionEventPreview' + title: Results + count: + type: integer + title: Count + next: + anyOf: + - type: string + - type: 'null' + title: Next + previous: + anyOf: + - type: string + - type: 'null' + title: Previous + title: PaginatedResult[ChatCompletionEventPreview] + required: + - count + PaginatedResult_DatasetImportTask_: + type: object + properties: + results: + type: array + items: + $ref: '#/components/schemas/DatasetImportTask' + title: Results + count: + type: integer + title: Count + next: + anyOf: + - type: string + - type: 'null' + title: Next + previous: + anyOf: + - type: string + - type: 'null' + title: Previous + title: PaginatedResult[DatasetImportTask] + required: + - count + PaginatedResult_DatasetPreview_: + type: object + properties: + results: + type: array + items: + $ref: '#/components/schemas/DatasetPreview' + title: Results + count: + type: integer + title: Count + next: + anyOf: + - type: string + - type: 'null' + title: Next + previous: + anyOf: + - type: string + - type: 'null' + title: Previous + title: PaginatedResult[DatasetPreview] + required: + - count + PaginatedResult_DatasetRecord_: + type: object + properties: + results: + type: array + items: + $ref: '#/components/schemas/DatasetRecord' + title: Results + count: + type: integer + title: Count + next: + anyOf: + - type: string + - type: 'null' + title: Next + previous: + anyOf: + - type: string + - type: 'null' + title: Previous + title: PaginatedResult[DatasetRecord] + required: + - count + PaginatedResult_JudgePreview_: + type: object + properties: + results: + type: array + items: + $ref: '#/components/schemas/JudgePreview' + title: Results + count: + type: integer + title: Count + next: + anyOf: + - type: string + - type: 'null' + title: Next + previous: + anyOf: + - type: string + - type: 'null' + title: Previous + title: PaginatedResult[JudgePreview] + required: + - count + PatchDatasetInSchema: + type: object + properties: + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: + anyOf: + - type: string + - type: 'null' + title: Description + title: PatchDatasetInSchema + PostCampaignInSchema: + type: object + properties: + search_params: + $ref: '#/components/schemas/FilterPayload' + judge_id: + type: string + title: Judge Id + format: uuid + name: + type: string + title: Name + maxLength: 50 + minLength: 5 + description: + type: string + title: Description + max_nb_events: + exclusiveMinimum: 0 + type: integer + title: Max Nb Events + maximum: 10000 + title: PostCampaignInSchema + required: + - search_params + - judge_id + - name + - description + - max_nb_events + PostChatCompletionEventJudgingInSchema: + type: object + properties: + judge_definition: + $ref: '#/components/schemas/PostJudgeInSchema' + title: PostChatCompletionEventJudgingInSchema + required: + - judge_definition + PostDatasetImportFromCampaignInSchema: + type: object + properties: + campaign_id: + type: string + title: Campaign Id + format: uuid + title: PostDatasetImportFromCampaignInSchema + required: + - campaign_id + PostDatasetImportFromDatasetInSchema: + type: object + properties: + dataset_record_ids: + type: array + items: + type: string + format: uuid + title: Dataset Record Ids + maxItems: 10000 + minItems: 1 + title: PostDatasetImportFromDatasetInSchema + required: + - dataset_record_ids + PostDatasetImportFromExplorerInSchema: + type: object + properties: + completion_event_ids: + type: array + items: + type: string + title: Completion Event Ids + maxItems: 500 + title: PostDatasetImportFromExplorerInSchema + required: + - completion_event_ids + PostDatasetImportFromFileInSchema: + type: object + properties: + file_id: + type: string + title: File Id + title: PostDatasetImportFromFileInSchema + required: + - file_id + PostDatasetImportFromPlaygroundInSchema: + type: object + properties: + conversation_ids: + type: array + items: + type: string + title: Conversation Ids + title: PostDatasetImportFromPlaygroundInSchema + required: + - conversation_ids + PostDatasetInSchema: + type: object + properties: + name: + type: string + title: Name + maxLength: 50 + minLength: 5 + description: + type: string + title: Description + maxLength: 200 + title: PostDatasetInSchema + required: + - name + - description + PostDatasetRecordInSchema: + type: object + properties: + payload: + $ref: '#/components/schemas/ConversationPayload' + properties: + type: object + title: Properties + additionalProperties: true + title: PostDatasetRecordInSchema + required: + - payload + - properties + PostDatasetRecordJudgingInSchema: + type: object + properties: + judge_definition: + $ref: '#/components/schemas/PostJudgeInSchema' + title: PostDatasetRecordJudgingInSchema + required: + - judge_definition + PostJudgeInSchema: + type: object + properties: + name: + type: string + title: Name + maxLength: 50 + minLength: 5 + description: + type: string + title: Description + maxLength: 500 + model_name: + type: string + title: Model Name + maxLength: 500 + output: + oneOf: + - $ref: '#/components/schemas/JudgeClassificationOutput' + - $ref: '#/components/schemas/JudgeRegressionOutput' + discriminator: + propertyName: type + mapping: + CLASSIFICATION: '#/components/schemas/JudgeClassificationOutput' + REGRESSION: '#/components/schemas/JudgeRegressionOutput' + title: Output + instructions: + type: string + title: Instructions + maxLength: 10000 + tools: + type: array + items: + type: string + title: Tools + title: PostJudgeInSchema + required: + - name + - description + - model_name + - output + - instructions + - tools + PutDatasetRecordPayloadInSchema: + type: object + properties: + payload: + $ref: '#/components/schemas/ConversationPayload' + title: PutDatasetRecordPayloadInSchema + required: + - payload + PutDatasetRecordPropertiesInSchema: + type: object + properties: + properties: + type: object + title: Properties + additionalProperties: true + title: PutDatasetRecordPropertiesInSchema + required: + - properties + PutJudgeInSchema: + type: object + properties: + name: + type: string + title: Name + maxLength: 50 + minLength: 5 + description: + type: string + title: Description + maxLength: 500 + model_name: + type: string + title: Model Name + maxLength: 500 + output: + oneOf: + - $ref: '#/components/schemas/JudgeClassificationOutput' + - $ref: '#/components/schemas/JudgeRegressionOutput' + discriminator: + propertyName: type + mapping: + CLASSIFICATION: '#/components/schemas/JudgeClassificationOutput' + REGRESSION: '#/components/schemas/JudgeRegressionOutput' + title: Output + instructions: + type: string + title: Instructions + maxLength: 10000 + tools: + type: array + items: + type: string + title: Tools + title: PutJudgeInSchema + required: + - name + - description + - model_name + - output + - instructions + - tools + Annotations: + type: object + properties: + audience: + anyOf: + - type: array + items: + type: string + enum: + - user + - assistant + - type: 'null' + title: Audience + priority: + anyOf: + - type: number + maximum: 1 + minimum: 0 + - type: 'null' + title: Priority + title: Annotations + additionalProperties: true + AudioContent: + type: object + properties: + type: + type: string + title: Type + const: audio + data: + type: string + title: Data + mimeType: + type: string + title: Mimetype + annotations: + anyOf: + - $ref: '#/components/schemas/Annotations' + - type: 'null' + _meta: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Meta + title: AudioContent + required: + - type + - data + - mimeType + additionalProperties: true + description: Audio content for a message. + AuthData: + type: object + properties: + client_id: + type: string + title: Client Id + client_secret: + type: string + title: Client Secret + title: AuthData + required: + - client_id + - client_secret + BlobResourceContents: + type: object + properties: + uri: + type: string + title: Uri + minLength: 1 + format: uri + mimeType: + anyOf: + - type: string + - type: 'null' + title: Mimetype + _meta: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Meta + blob: + type: string + title: Blob + title: BlobResourceContents + required: + - uri + - blob + additionalProperties: true + description: Binary contents of a resource. + Connector: + type: object + properties: + id: + type: string + title: Id + format: uuid + name: + type: string + title: Name + description: + type: string + title: Description + created_at: + type: string + title: Created At + format: date-time + modified_at: + type: string + title: Modified At + format: date-time + server: + anyOf: + - type: string + - type: 'null' + title: Server + auth_type: + anyOf: + - type: string + - type: 'null' + title: Auth Type + tools: + anyOf: + - type: array + items: + $ref: '#/components/schemas/integrations__schemas__api__tool__Tool' + - type: 'null' + title: Tools + title: Connector + required: + - id + - name + - description + - created_at + - modified_at + ConnectorMCPCreate: + type: object + properties: + name: + type: string + title: Name + description: The name of the connector. Should be 64 char length maximum, alphanumeric, only underscores/dashes. + description: + type: string + title: Description + description: The description of the connector. + icon_url: + anyOf: + - type: string + - type: 'null' + title: Icon Url + description: The optional url of the icon you want to associate to the connector. + visibility: + $ref: '#/components/schemas/ResourceVisibility' + description: Visibility of the connector. Use 'shared_workspace' for workspace scoped connectors, or 'private' for private connectors. + default: shared_org + server: + type: string + title: Server + maxLength: 2083 + minLength: 1 + format: uri + description: The url of the MCP server. + headers: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Headers + description: Optional organization-level headers to be sent with the request to the mcp server. + auth_data: + anyOf: + - $ref: '#/components/schemas/AuthData' + - type: 'null' + description: Optional additional authentication data for the connector. + system_prompt: + anyOf: + - type: string + - type: 'null' + title: System Prompt + description: Optional system prompt for the connector. + title: ConnectorMCPCreate + required: + - name + - description + - server + ConnectorMCPUpdate: + type: object + properties: + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: The name of the connector. + description: + anyOf: + - type: string + - type: 'null' + title: Description + description: The description of the connector. + icon_url: + anyOf: + - type: string + - type: 'null' + title: Icon Url + description: The optional url of the icon you want to associate to the connector. + system_prompt: + anyOf: + - type: string + - type: 'null' + title: System Prompt + description: Optional system prompt for the connector. + connection_config: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Connection Config + description: Optional new connection config. + connection_secrets: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Connection Secrets + description: Optional new connection secrets + server: + anyOf: + - type: string + maxLength: 2083 + minLength: 1 + format: uri + - type: 'null' + title: Server + description: New server url for your mcp connector. + headers: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Headers + description: New headers for your mcp connector. + auth_data: + anyOf: + - $ref: '#/components/schemas/AuthData' + - type: 'null' + description: New authentication data for your mcp connector. + title: ConnectorMCPUpdate + ConnectorSupportedLanguage: + type: string + title: ConnectorSupportedLanguage + enum: + - en + - fr + - ar + - es + - de + - pl + - pt-BR + - it + - nl + ConnectorsQueryFilters: + type: object + properties: + active: + anyOf: + - type: boolean + - type: 'null' + title: Active + description: Filter for active connectors for a given user, workspace and organization. + fetch_connection_secrets: + type: boolean + title: Fetch Connection Secrets + description: Fetch connection secrets. + default: false + title: ConnectorsQueryFilters + EmbeddedResource: + type: object + properties: + type: + type: string + title: Type + const: resource + resource: + anyOf: + - $ref: '#/components/schemas/TextResourceContents' + - $ref: '#/components/schemas/BlobResourceContents' + title: Resource + annotations: + anyOf: + - $ref: '#/components/schemas/Annotations' + - type: 'null' + _meta: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Meta + title: EmbeddedResource + required: + - type + - resource + additionalProperties: true + description: 'The contents of a resource, embedded into a prompt or tool call result. + + + It is up to the client how best to render embedded resources for the benefit + + of the LLM and/or the user.' + ExecutionConfig: + type: object + properties: + type: + type: string + title: Type + title: ExecutionConfig + required: + - type + additionalProperties: true + description: 'Not typed since mcp config can changed / not stable + + we allow all extra fields and this is a dict + + TODO: once mcp is stable, we need to type this' + ImageContent: + type: object + properties: + type: + type: string + title: Type + const: image + data: + type: string + title: Data + mimeType: + type: string + title: Mimetype + annotations: + anyOf: + - $ref: '#/components/schemas/Annotations' + - type: 'null' + _meta: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Meta + title: ImageContent + required: + - type + - data + - mimeType + additionalProperties: true + description: Image content for a message. + MCPResultMetadata: + type: object + properties: + isError: + type: boolean + title: Iserror + default: false + structuredContent: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Structuredcontent + _meta: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Meta + title: MCPResultMetadata + additionalProperties: true + description: MCP-specific result metadata (isError, structuredContent, _meta). + MCPToolCallMetadata: + type: object + properties: + mcp_meta: + anyOf: + - $ref: '#/components/schemas/MCPResultMetadata' + - type: 'null' + title: MCPToolCallMetadata + additionalProperties: true + description: 'Metadata wrapper for MCP tool call responses. + + + Nests MCP-specific fields under `mcp_meta` to avoid collisions with other + + metadata keys (e.g. `tool_call_result`) in Harmattan''s streaming deltas.' + MCPToolCallRequest: + type: object + properties: + arguments: + type: object + title: Arguments + additionalProperties: true + title: MCPToolCallRequest + description: Request body for calling an MCP tool. + MCPToolCallResponse: + type: object + properties: + content: + type: array + items: + anyOf: + - $ref: '#/components/schemas/TextContent' + - $ref: '#/components/schemas/ImageContent' + - $ref: '#/components/schemas/AudioContent' + - $ref: '#/components/schemas/ResourceLink' + - $ref: '#/components/schemas/EmbeddedResource' + title: Content + metadata: + anyOf: + - $ref: '#/components/schemas/MCPToolCallMetadata' + - type: 'null' + title: MCPToolCallResponse + required: + - content + additionalProperties: true + description: 'Response from calling an MCP tool. + + + We override mcp_types.CallToolResult because: + + - Models only support `content`, not `structuredContent` at top level + + - Downstream consumers (le-chat, etc.) need structuredContent/isError/_meta via metadata + + + SYNC: Keep in sync with Harmattan (orchestrator) for harmonized tool result processing.' + MessageResponse: + type: object + properties: + message: + type: string + title: Message + title: MessageResponse + required: + - message + PaginationResponse: + type: object + properties: + next_cursor: + anyOf: + - type: string + - type: 'null' + title: Next Cursor + page_size: + type: integer + title: Page Size + title: PaginationResponse + required: + - page_size + ResourceLink: + type: object + properties: + name: + type: string + title: Name + title: + anyOf: + - type: string + - type: 'null' + title: Title + uri: + type: string + title: Uri + minLength: 1 + format: uri + description: + anyOf: + - type: string + - type: 'null' + title: Description + mimeType: + anyOf: + - type: string + - type: 'null' + title: Mimetype + size: + anyOf: + - type: integer + - type: 'null' + title: Size + icons: + anyOf: + - type: array + items: + $ref: '#/components/schemas/MCPServerIcon' + - type: 'null' + title: Icons + annotations: + anyOf: + - $ref: '#/components/schemas/Annotations' + - type: 'null' + _meta: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Meta + type: + type: string + title: Type + const: resource_link + title: ResourceLink + required: + - name + - uri + - type + additionalProperties: true + description: 'A resource that the server is capable of reading, included in a prompt or tool call result. + + + Note: resource links returned by tools are not guaranteed to appear in the results of `resources/list` requests.' + ResourceVisibility: + type: string + title: ResourceVisibility + enum: + - shared_global + - shared_org + - shared_workspace + - private + TextContent: + type: object + properties: + type: + type: string + title: Type + const: text + text: + type: string + title: Text + annotations: + anyOf: + - $ref: '#/components/schemas/Annotations' + - type: 'null' + _meta: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Meta + title: TextContent + required: + - type + - text + additionalProperties: true + description: Text content for a message. + TextResourceContents: + type: object + properties: + uri: + type: string + title: Uri + minLength: 1 + format: uri + mimeType: + anyOf: + - type: string + - type: 'null' + title: Mimetype + _meta: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Meta + text: + type: string + title: Text + title: TextResourceContents + required: + - uri + - text + additionalProperties: true + description: Text contents of a resource. + integrations__schemas__api__tool__Tool: + type: object + properties: + id: + type: string + title: Id + name: + type: string + title: Name + description: + type: string + title: Description + system_prompt: + anyOf: + - type: string + - type: 'null' + title: System Prompt + locale: + anyOf: + - $ref: '#/components/schemas/integrations__schemas__turbine__ToolLocale' + - type: 'null' + jsonschema: + anyOf: + - type: object + additionalProperties: true + - type: 'null' + title: Jsonschema + execution_config: + anyOf: + - $ref: '#/components/schemas/ExecutionConfig' + - type: 'null' + visibility: + $ref: '#/components/schemas/ResourceVisibility' + created_at: + type: string + title: Created At + format: date-time + modified_at: + type: string + title: Modified At + format: date-time + active: + anyOf: + - type: boolean + - type: 'null' + title: Active + title: Tool + required: + - id + - name + - description + - execution_config + - visibility + - created_at + - modified_at + integrations__schemas__turbine__ToolLocale: + type: object + properties: + name: + type: object + propertyNames: + $ref: '#/components/schemas/ConnectorSupportedLanguage' + title: Name + additionalProperties: + type: string + description: + type: object + propertyNames: + $ref: '#/components/schemas/ConnectorSupportedLanguage' + title: Description + additionalProperties: + type: string + usage_sentence: + type: object + propertyNames: + $ref: '#/components/schemas/ConnectorSupportedLanguage' + title: Usage Sentence + additionalProperties: + type: string + title: ToolLocale + required: + - name + - description + - usage_sentence + PaginatedConnectors: + type: object + properties: + items: + type: array + items: + $ref: '#/components/schemas/Connector' + title: Items + pagination: + $ref: '#/components/schemas/PaginationResponse' + title: PaginatedConnectors + required: + - items + - pagination + MCPServerIcon: + type: object + properties: + src: + type: string + title: Src + mimeType: + anyOf: + - type: string + - type: 'null' + title: Mimetype + sizes: + anyOf: + - type: array + items: + type: string + - type: 'null' + title: Sizes + title: MCPServerIcon + required: + - src + additionalProperties: true + description: An icon for display in user interfaces. + CompletionEvent: + title: CompletionEvent + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/CompletionChunk' + CompletionChunk: + title: CompletionChunk + type: object + required: + - id + - model + - choices + properties: + id: + type: string + object: + type: string + created: + type: integer + model: + type: string + usage: + $ref: '#/components/schemas/UsageInfo' + choices: + type: array + items: + $ref: '#/components/schemas/CompletionResponseStreamChoice' + CompletionResponseStreamChoice: + title: CompletionResponseStreamChoice + type: object + required: + - index + - delta + - finish_reason + properties: + index: + type: integer + delta: + $ref: '#/components/schemas/DeltaMessage' + finish_reason: + type: + - string + - 'null' + enum: + - stop + - length + - error + - tool_calls + - null + ResponseBase: + type: object + title: ResponseBase + properties: + id: + type: string + example: cmpl-e5cc70bb28c444948073e77776eb30ef + object: + type: string + example: chat.completion + model: + type: string + example: mistral-small-latest + usage: + $ref: '#/components/schemas/UsageInfo' + ChatCompletionChoice: + title: ChatCompletionChoice + type: object + required: + - index + - finish_reason + - message + properties: + index: + type: integer + example: 0 + message: + $ref: '#/components/schemas/AssistantMessage' + finish_reason: + type: string + enum: + - stop + - length + - model_length + - error + - tool_calls + example: stop + DeltaMessage: + title: DeltaMessage + type: object + properties: + role: + anyOf: + - type: string + - type: 'null' + content: + anyOf: + - type: string + - type: 'null' + - items: + $ref: '#/components/schemas/ContentChunk' + type: array + tool_calls: + anyOf: + - type: 'null' + - type: array + items: + $ref: '#/components/schemas/ToolCall' + ChatCompletionResponseBase: + allOf: + - $ref: '#/components/schemas/ResponseBase' + - type: object + title: ChatCompletionResponseBase + properties: + created: + type: integer + example: 1702256327 + ChatCompletionResponse: + allOf: + - $ref: '#/components/schemas/ChatCompletionResponseBase' + - type: object + title: ChatCompletionResponse + properties: + choices: + type: array + items: + $ref: '#/components/schemas/ChatCompletionChoice' + required: + - id + - object + - data + - model + - usage + - created + - choices + FIMCompletionResponse: + allOf: + - $ref: '#/components/schemas/ChatCompletionResponse' + - type: object + properties: + model: + type: string + example: codestral-latest + EmbeddingResponseData: + title: EmbeddingResponseData + type: object + properties: + object: + type: string + example: embedding + embedding: + type: array + items: + type: number + example: + - 0.1 + - 0.2 + - 0.3 + index: + type: integer + example: 0 + examples: + - object: embedding + embedding: + - 0.1 + - 0.2 + - 0.3 + index: 0 + - object: embedding + embedding: + - 0.4 + - 0.5 + - 0.6 + index: 1 + EmbeddingResponse: + allOf: + - $ref: '#/components/schemas/ResponseBase' + - type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/EmbeddingResponseData' + required: + - id + - object + - data + - model + - usage + securitySchemes: + ApiKey: + type: http + scheme: bearer +tags: + - name: chat + x-displayName: Chat + description: Chat Completion API. + - name: fim + x-displayName: FIM + description: Fill-in-the-middle API. + - name: agents + x-displayName: Agents + description: Agents API. + - name: embeddings + x-displayName: Embeddings + description: Embeddings API. + - name: classifiers + x-displayName: Classifiers + description: Classifiers API. + - name: files + x-displayName: Files + description: Files API + - name: deprecated.agents + x-displayName: (deprecated) Agents + description: (deprecated) Agents completion API + - name: deprecated.fine-tuning + x-displayName: (deprecated) Fine Tuning + description: (deprecated) Fine-tuning API + - name: models + x-displayName: Models + description: Model Management API + - name: batch + x-displayName: Batch + description: Batch API + - name: ocr + x-displayName: OCR API + description: OCR API + - name: audio.transcriptions + x-displayName: Transcriptions API + description: API for audio transcription. + - name: beta.agents + x-displayName: (beta) Agents API + description: (beta) Agents API + - name: beta.conversations + x-displayName: (beta) Conversations API + description: (beta) Conversations API + - name: beta.libraries + x-displayName: (beta) Libraries API - Main + description: (beta) Libraries API to create and manage libraries - index your documents to enhance agent capabilities. + - name: beta.libraries.documents + x-displayName: (beta) Libraries API - Documents + description: (beta) Libraries API - manage documents in a library. + - name: beta.libraries.accesses + x-displayName: (beta) Libraries API - Access + description: (beta) Libraries API - manage access to a library. +security: + - ApiKey: [] +servers: + - url: https://api.mistral.ai + description: Production server \ No newline at end of file diff --git a/Documentation/References/openai.openapi.yaml b/Documentation/References/openai.openapi.yaml new file mode 100644 index 0000000..59e9988 --- /dev/null +++ b/Documentation/References/openai.openapi.yaml @@ -0,0 +1,39839 @@ +openapi: 3.0.0 +info: + title: OpenAI API + description: The OpenAI REST API. Please see + https://platform.openai.com/docs/api-reference for more details. + version: 2.3.0 + termsOfService: https://openai.com/policies/terms-of-use + contact: + name: OpenAI Support + url: https://help.openai.com/ + license: + name: MIT + url: https://github.com/openai/openai-openapi/blob/master/LICENSE +servers: + - url: https://api.openai.com/v1 +security: + - ApiKeyAuth: [] +tags: + - name: Assistants + description: Build Assistants that can call models and use tools. + - name: Audio + description: Turn audio into text or text into audio. + - name: Chat + description: Given a list of messages comprising a conversation, the model will + return a response. + - name: Completions + description: Given a prompt, the model will return one or more predicted + completions, and can also return the probabilities of alternative tokens + at each position. + - name: Embeddings + description: Get a vector representation of a given input that can be easily + consumed by machine learning models and algorithms. + - name: Evals + description: Manage and run evals in the OpenAI platform. + - name: Fine-tuning + description: Manage fine-tuning jobs to tailor a model to your specific training data. + - name: Batch + description: Create large batches of API requests to run asynchronously. + - name: Files + description: Files are used to upload documents that can be used with features + like Assistants and Fine-tuning. + - name: Uploads + description: Use Uploads to upload large files in multiple parts. + - name: Images + description: Given a prompt and/or an input image, the model will generate a new image. + - name: Models + description: List and describe the various models available in the API. + - name: Moderations + description: Given text and/or image inputs, classifies if those inputs are + potentially harmful. + - name: Audit Logs + description: List user actions and configuration changes within this organization. +paths: + /assistants: + get: + operationId: listAssistants + tags: + - Assistants + summary: Returns a list of assistants. + parameters: + - name: limit + in: query + description: > + A limit on the number of objects to be returned. Limit can range + between 1 and 100, and the default is 20. + required: false + schema: + type: integer + default: 20 + - name: order + in: query + description: > + Sort order by the `created_at` timestamp of the objects. `asc` for + ascending order and `desc` for descending order. + schema: + type: string + default: desc + enum: + - asc + - desc + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + schema: + type: string + - name: before + in: query + description: > + A cursor for use in pagination. `before` is an object ID that + defines your place in the list. For instance, if you make a list + request and receive 100 objects, starting with obj_foo, your + subsequent call can include before=obj_foo in order to fetch the + previous page of the list. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ListAssistantsResponse" + x-oaiMeta: + name: List assistants + group: assistants + beta: true + returns: A list of [assistant](/docs/api-reference/assistants/object) objects. + examples: + request: + curl: | + curl "https://api.openai.com/v1/assistants?order=desc&limit=20" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" + python: | + from openai import OpenAI + client = OpenAI() + + my_assistants = client.beta.assistants.list( + order="desc", + limit="20", + ) + print(my_assistants.data) + node.js: |- + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const myAssistants = await openai.beta.assistants.list({ + order: "desc", + limit: "20", + }); + + console.log(myAssistants.data); + } + + main(); + response: > + { + "object": "list", + "data": [ + { + "id": "asst_abc123", + "object": "assistant", + "created_at": 1698982736, + "name": "Coding Tutor", + "description": null, + "model": "gpt-4o", + "instructions": "You are a helpful assistant designed to make me better at coding!", + "tools": [], + "tool_resources": {}, + "metadata": {}, + "top_p": 1.0, + "temperature": 1.0, + "response_format": "auto" + }, + { + "id": "asst_abc456", + "object": "assistant", + "created_at": 1698982718, + "name": "My Assistant", + "description": null, + "model": "gpt-4o", + "instructions": "You are a helpful assistant designed to make me better at coding!", + "tools": [], + "tool_resources": {}, + "metadata": {}, + "top_p": 1.0, + "temperature": 1.0, + "response_format": "auto" + }, + { + "id": "asst_abc789", + "object": "assistant", + "created_at": 1698982643, + "name": null, + "description": null, + "model": "gpt-4o", + "instructions": null, + "tools": [], + "tool_resources": {}, + "metadata": {}, + "top_p": 1.0, + "temperature": 1.0, + "response_format": "auto" + } + ], + "first_id": "asst_abc123", + "last_id": "asst_abc789", + "has_more": false + } + post: + operationId: createAssistant + tags: + - Assistants + summary: Create an assistant with a model and instructions. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateAssistantRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/AssistantObject" + x-oaiMeta: + name: Create assistant + group: assistants + beta: true + returns: An [assistant](/docs/api-reference/assistants/object) object. + examples: + - title: Code Interpreter + request: + curl: > + curl "https://api.openai.com/v1/assistants" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.", + "name": "Math Tutor", + "tools": [{"type": "code_interpreter"}], + "model": "gpt-4o" + }' + python: > + from openai import OpenAI + + client = OpenAI() + + + my_assistant = client.beta.assistants.create( + instructions="You are a personal math tutor. When asked a question, write and run Python code to answer the question.", + name="Math Tutor", + tools=[{"type": "code_interpreter"}], + model="gpt-4o", + ) + + print(my_assistant) + node.js: >- + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + async function main() { + const myAssistant = await openai.beta.assistants.create({ + instructions: + "You are a personal math tutor. When asked a question, write and run Python code to answer the question.", + name: "Math Tutor", + tools: [{ type: "code_interpreter" }], + model: "gpt-4o", + }); + + console.log(myAssistant); + } + + + main(); + response: > + { + "id": "asst_abc123", + "object": "assistant", + "created_at": 1698984975, + "name": "Math Tutor", + "description": null, + "model": "gpt-4o", + "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.", + "tools": [ + { + "type": "code_interpreter" + } + ], + "metadata": {}, + "top_p": 1.0, + "temperature": 1.0, + "response_format": "auto" + } + - title: Files + request: + curl: > + curl https://api.openai.com/v1/assistants \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.", + "tools": [{"type": "file_search"}], + "tool_resources": {"file_search": {"vector_store_ids": ["vs_123"]}}, + "model": "gpt-4o" + }' + python: > + from openai import OpenAI + + client = OpenAI() + + + my_assistant = client.beta.assistants.create( + instructions="You are an HR bot, and you have access to files to answer employee questions about company policies.", + name="HR Helper", + tools=[{"type": "file_search"}], + tool_resources={"file_search": {"vector_store_ids": ["vs_123"]}}, + model="gpt-4o" + ) + + print(my_assistant) + node.js: >- + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + async function main() { + const myAssistant = await openai.beta.assistants.create({ + instructions: + "You are an HR bot, and you have access to files to answer employee questions about company policies.", + name: "HR Helper", + tools: [{ type: "file_search" }], + tool_resources: { + file_search: { + vector_store_ids: ["vs_123"] + } + }, + model: "gpt-4o" + }); + + console.log(myAssistant); + } + + + main(); + response: > + { + "id": "asst_abc123", + "object": "assistant", + "created_at": 1699009403, + "name": "HR Helper", + "description": null, + "model": "gpt-4o", + "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.", + "tools": [ + { + "type": "file_search" + } + ], + "tool_resources": { + "file_search": { + "vector_store_ids": ["vs_123"] + } + }, + "metadata": {}, + "top_p": 1.0, + "temperature": 1.0, + "response_format": "auto" + } + /assistants/{assistant_id}: + get: + operationId: getAssistant + tags: + - Assistants + summary: Retrieves an assistant. + parameters: + - in: path + name: assistant_id + required: true + schema: + type: string + description: The ID of the assistant to retrieve. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/AssistantObject" + x-oaiMeta: + name: Retrieve assistant + group: assistants + beta: true + returns: The [assistant](/docs/api-reference/assistants/object) object matching + the specified ID. + examples: + request: + curl: | + curl https://api.openai.com/v1/assistants/asst_abc123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" + python: | + from openai import OpenAI + client = OpenAI() + + my_assistant = client.beta.assistants.retrieve("asst_abc123") + print(my_assistant) + node.js: |- + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const myAssistant = await openai.beta.assistants.retrieve( + "asst_abc123" + ); + + console.log(myAssistant); + } + + main(); + response: > + { + "id": "asst_abc123", + "object": "assistant", + "created_at": 1699009709, + "name": "HR Helper", + "description": null, + "model": "gpt-4o", + "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.", + "tools": [ + { + "type": "file_search" + } + ], + "metadata": {}, + "top_p": 1.0, + "temperature": 1.0, + "response_format": "auto" + } + post: + operationId: modifyAssistant + tags: + - Assistants + summary: Modifies an assistant. + parameters: + - in: path + name: assistant_id + required: true + schema: + type: string + description: The ID of the assistant to modify. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ModifyAssistantRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/AssistantObject" + x-oaiMeta: + name: Modify assistant + group: assistants + beta: true + returns: The modified [assistant](/docs/api-reference/assistants/object) object. + examples: + request: + curl: > + curl https://api.openai.com/v1/assistants/asst_abc123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.", + "tools": [{"type": "file_search"}], + "model": "gpt-4o" + }' + python: > + from openai import OpenAI + + client = OpenAI() + + + my_updated_assistant = client.beta.assistants.update( + "asst_abc123", + instructions="You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.", + name="HR Helper", + tools=[{"type": "file_search"}], + model="gpt-4o" + ) + + + print(my_updated_assistant) + node.js: >- + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + async function main() { + const myUpdatedAssistant = await openai.beta.assistants.update( + "asst_abc123", + { + instructions: + "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.", + name: "HR Helper", + tools: [{ type: "file_search" }], + model: "gpt-4o" + } + ); + + console.log(myUpdatedAssistant); + } + + + main(); + response: > + { + "id": "asst_123", + "object": "assistant", + "created_at": 1699009709, + "name": "HR Helper", + "description": null, + "model": "gpt-4o", + "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.", + "tools": [ + { + "type": "file_search" + } + ], + "tool_resources": { + "file_search": { + "vector_store_ids": [] + } + }, + "metadata": {}, + "top_p": 1.0, + "temperature": 1.0, + "response_format": "auto" + } + delete: + operationId: deleteAssistant + tags: + - Assistants + summary: Delete an assistant. + parameters: + - in: path + name: assistant_id + required: true + schema: + type: string + description: The ID of the assistant to delete. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/DeleteAssistantResponse" + x-oaiMeta: + name: Delete assistant + group: assistants + beta: true + returns: Deletion status + examples: + request: + curl: | + curl https://api.openai.com/v1/assistants/asst_abc123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" \ + -X DELETE + python: | + from openai import OpenAI + client = OpenAI() + + response = client.beta.assistants.delete("asst_abc123") + print(response) + node.js: >- + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + async function main() { + const response = await openai.beta.assistants.del("asst_abc123"); + + console.log(response); + } + + main(); + response: | + { + "id": "asst_abc123", + "object": "assistant.deleted", + "deleted": true + } + /audio/speech: + post: + operationId: createSpeech + tags: + - Audio + summary: Generates audio from the input text. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateSpeechRequest" + responses: + "200": + description: OK + headers: + Transfer-Encoding: + schema: + type: string + description: chunked + content: + application/octet-stream: + schema: + type: string + format: binary + x-oaiMeta: + name: Create speech + group: audio + returns: The audio file content. + examples: + request: + curl: | + curl https://api.openai.com/v1/audio/speech \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "gpt-4o-mini-tts", + "input": "The quick brown fox jumped over the lazy dog.", + "voice": "alloy" + }' \ + --output speech.mp3 + python: | + from pathlib import Path + import openai + + speech_file_path = Path(__file__).parent / "speech.mp3" + with openai.audio.speech.with_streaming_response.create( + model="gpt-4o-mini-tts", + voice="alloy", + input="The quick brown fox jumped over the lazy dog." + ) as response: + response.stream_to_file(speech_file_path) + javascript: > + import fs from "fs"; + + import path from "path"; + + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + const speechFile = path.resolve("./speech.mp3"); + + + async function main() { + const mp3 = await openai.audio.speech.create({ + model: "gpt-4o-mini-tts", + voice: "alloy", + input: "Today is a wonderful day to build something people love!", + }); + console.log(speechFile); + const buffer = Buffer.from(await mp3.arrayBuffer()); + await fs.promises.writeFile(speechFile, buffer); + } + + main(); + csharp: | + using System; + using System.IO; + + using OpenAI.Audio; + + AudioClient client = new( + model: "gpt-4o-mini-tts", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + BinaryData speech = client.GenerateSpeech( + text: "The quick brown fox jumped over the lazy dog.", + voice: GeneratedSpeechVoice.Alloy + ); + + using FileStream stream = File.OpenWrite("speech.mp3"); + speech.ToStream().CopyTo(stream); + /audio/transcriptions: + post: + operationId: createTranscription + tags: + - Audio + summary: Transcribes audio into the input language. + requestBody: + required: true + content: + multipart/form-data: + schema: + $ref: "#/components/schemas/CreateTranscriptionRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + oneOf: + - $ref: "#/components/schemas/CreateTranscriptionResponseJson" + - $ref: "#/components/schemas/CreateTranscriptionResponseVerboseJson" + text/event-stream: + schema: + $ref: "#/components/schemas/CreateTranscriptionResponseStreamEvent" + x-oaiMeta: + name: Create transcription + group: audio + returns: The [transcription object](/docs/api-reference/audio/json-object), a + [verbose transcription + object](/docs/api-reference/audio/verbose-json-object) or a [stream of + transcript + events](/docs/api-reference/audio/transcript-text-delta-event). + examples: + - title: Default + request: + curl: | + curl https://api.openai.com/v1/audio/transcriptions \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: multipart/form-data" \ + -F file="@/path/to/file/audio.mp3" \ + -F model="gpt-4o-transcribe" + python: | + from openai import OpenAI + client = OpenAI() + + audio_file = open("speech.mp3", "rb") + transcript = client.audio.transcriptions.create( + model="gpt-4o-transcribe", + file=audio_file + ) + javascript: > + import fs from "fs"; + + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + async function main() { + const transcription = await openai.audio.transcriptions.create({ + file: fs.createReadStream("audio.mp3"), + model: "gpt-4o-transcribe", + }); + + console.log(transcription.text); + } + + main(); + csharp: > + using System; + + + using OpenAI.Audio; + + string audioFilePath = "audio.mp3"; + + + AudioClient client = new( + model: "gpt-4o-transcribe", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + AudioTranscription transcription = + client.TranscribeAudio(audioFilePath); + + + Console.WriteLine($"{transcription.Text}"); + response: > + { + "text": "Imagine the wildest idea that you've ever had, and you're curious about how it might scale to something that's a 100, a 1,000 times bigger. This is a place where you can get to do that." + } + - title: Streaming + request: + curl: | + curl https://api.openai.com/v1/audio/transcriptions \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: multipart/form-data" \ + -F file="@/path/to/file/audio.mp3" \ + -F model="gpt-4o-mini-transcribe" \ + -F stream=true + python: | + from openai import OpenAI + client = OpenAI() + + audio_file = open("speech.mp3", "rb") + stream = client.audio.transcriptions.create( + file=audio_file, + model="gpt-4o-mini-transcribe", + stream=True + ) + + for event in stream: + print(event) + javascript: | + import fs from "fs"; + import OpenAI from "openai"; + + const openai = new OpenAI(); + + const stream = await openai.audio.transcriptions.create({ + file: fs.createReadStream("audio.mp3"), + model: "gpt-4o-mini-transcribe", + stream: true, + }); + + for await (const event of stream) { + console.log(event); + } + response: | + data: {"type":"transcript.text.delta","delta":"I","logprobs":[{"token":"I","logprob":-0.00007588794,"bytes":[73]}]} + + data: {"type":"transcript.text.delta","delta":" see","logprobs":[{"token":" see","logprob":-3.1281633e-7,"bytes":[32,115,101,101]}]} + + data: {"type":"transcript.text.delta","delta":" skies","logprobs":[{"token":" skies","logprob":-2.3392786e-6,"bytes":[32,115,107,105,101,115]}]} + + data: {"type":"transcript.text.delta","delta":" of","logprobs":[{"token":" of","logprob":-3.1281633e-7,"bytes":[32,111,102]}]} + + data: {"type":"transcript.text.delta","delta":" blue","logprobs":[{"token":" blue","logprob":-1.0280384e-6,"bytes":[32,98,108,117,101]}]} + + data: {"type":"transcript.text.delta","delta":" and","logprobs":[{"token":" and","logprob":-0.0005108566,"bytes":[32,97,110,100]}]} + + data: {"type":"transcript.text.delta","delta":" clouds","logprobs":[{"token":" clouds","logprob":-1.9361265e-7,"bytes":[32,99,108,111,117,100,115]}]} + + data: {"type":"transcript.text.delta","delta":" of","logprobs":[{"token":" of","logprob":-1.9361265e-7,"bytes":[32,111,102]}]} + + data: {"type":"transcript.text.delta","delta":" white","logprobs":[{"token":" white","logprob":-7.89631e-7,"bytes":[32,119,104,105,116,101]}]} + + data: {"type":"transcript.text.delta","delta":",","logprobs":[{"token":",","logprob":-0.0014890312,"bytes":[44]}]} + + data: {"type":"transcript.text.delta","delta":" the","logprobs":[{"token":" the","logprob":-0.0110956915,"bytes":[32,116,104,101]}]} + + data: {"type":"transcript.text.delta","delta":" bright","logprobs":[{"token":" bright","logprob":0.0,"bytes":[32,98,114,105,103,104,116]}]} + + data: {"type":"transcript.text.delta","delta":" blessed","logprobs":[{"token":" blessed","logprob":-0.000045848617,"bytes":[32,98,108,101,115,115,101,100]}]} + + data: {"type":"transcript.text.delta","delta":" days","logprobs":[{"token":" days","logprob":-0.000010802739,"bytes":[32,100,97,121,115]}]} + + data: {"type":"transcript.text.delta","delta":",","logprobs":[{"token":",","logprob":-0.00001700133,"bytes":[44]}]} + + data: {"type":"transcript.text.delta","delta":" the","logprobs":[{"token":" the","logprob":-0.0000118755715,"bytes":[32,116,104,101]}]} + + data: {"type":"transcript.text.delta","delta":" dark","logprobs":[{"token":" dark","logprob":-5.5122365e-7,"bytes":[32,100,97,114,107]}]} + + data: {"type":"transcript.text.delta","delta":" sacred","logprobs":[{"token":" sacred","logprob":-5.4385737e-6,"bytes":[32,115,97,99,114,101,100]}]} + + data: {"type":"transcript.text.delta","delta":" nights","logprobs":[{"token":" nights","logprob":-4.00813e-6,"bytes":[32,110,105,103,104,116,115]}]} + + data: {"type":"transcript.text.delta","delta":",","logprobs":[{"token":",","logprob":-0.0036910512,"bytes":[44]}]} + + data: {"type":"transcript.text.delta","delta":" and","logprobs":[{"token":" and","logprob":-0.0031903093,"bytes":[32,97,110,100]}]} + + data: {"type":"transcript.text.delta","delta":" I","logprobs":[{"token":" I","logprob":-1.504853e-6,"bytes":[32,73]}]} + + data: {"type":"transcript.text.delta","delta":" think","logprobs":[{"token":" think","logprob":-4.3202e-7,"bytes":[32,116,104,105,110,107]}]} + + data: {"type":"transcript.text.delta","delta":" to","logprobs":[{"token":" to","logprob":-1.9361265e-7,"bytes":[32,116,111]}]} + + data: {"type":"transcript.text.delta","delta":" myself","logprobs":[{"token":" myself","logprob":-1.7432603e-6,"bytes":[32,109,121,115,101,108,102]}]} + + data: {"type":"transcript.text.delta","delta":",","logprobs":[{"token":",","logprob":-0.29254505,"bytes":[44]}]} + + data: {"type":"transcript.text.delta","delta":" what","logprobs":[{"token":" what","logprob":-0.016815351,"bytes":[32,119,104,97,116]}]} + + data: {"type":"transcript.text.delta","delta":" a","logprobs":[{"token":" a","logprob":-3.1281633e-7,"bytes":[32,97]}]} + + data: {"type":"transcript.text.delta","delta":" wonderful","logprobs":[{"token":" wonderful","logprob":-2.1008714e-6,"bytes":[32,119,111,110,100,101,114,102,117,108]}]} + + data: {"type":"transcript.text.delta","delta":" world","logprobs":[{"token":" world","logprob":-8.180258e-6,"bytes":[32,119,111,114,108,100]}]} + + data: {"type":"transcript.text.delta","delta":".","logprobs":[{"token":".","logprob":-0.014231676,"bytes":[46]}]} + + data: {"type":"transcript.text.done","text":"I see skies of blue and clouds of white, the bright blessed days, the dark sacred nights, and I think to myself, what a wonderful world.","logprobs":[{"token":"I","logprob":-0.00007588794,"bytes":[73]},{"token":" see","logprob":-3.1281633e-7,"bytes":[32,115,101,101]},{"token":" skies","logprob":-2.3392786e-6,"bytes":[32,115,107,105,101,115]},{"token":" of","logprob":-3.1281633e-7,"bytes":[32,111,102]},{"token":" blue","logprob":-1.0280384e-6,"bytes":[32,98,108,117,101]},{"token":" and","logprob":-0.0005108566,"bytes":[32,97,110,100]},{"token":" clouds","logprob":-1.9361265e-7,"bytes":[32,99,108,111,117,100,115]},{"token":" of","logprob":-1.9361265e-7,"bytes":[32,111,102]},{"token":" white","logprob":-7.89631e-7,"bytes":[32,119,104,105,116,101]},{"token":",","logprob":-0.0014890312,"bytes":[44]},{"token":" the","logprob":-0.0110956915,"bytes":[32,116,104,101]},{"token":" bright","logprob":0.0,"bytes":[32,98,114,105,103,104,116]},{"token":" blessed","logprob":-0.000045848617,"bytes":[32,98,108,101,115,115,101,100]},{"token":" days","logprob":-0.000010802739,"bytes":[32,100,97,121,115]},{"token":",","logprob":-0.00001700133,"bytes":[44]},{"token":" the","logprob":-0.0000118755715,"bytes":[32,116,104,101]},{"token":" dark","logprob":-5.5122365e-7,"bytes":[32,100,97,114,107]},{"token":" sacred","logprob":-5.4385737e-6,"bytes":[32,115,97,99,114,101,100]},{"token":" nights","logprob":-4.00813e-6,"bytes":[32,110,105,103,104,116,115]},{"token":",","logprob":-0.0036910512,"bytes":[44]},{"token":" and","logprob":-0.0031903093,"bytes":[32,97,110,100]},{"token":" I","logprob":-1.504853e-6,"bytes":[32,73]},{"token":" think","logprob":-4.3202e-7,"bytes":[32,116,104,105,110,107]},{"token":" to","logprob":-1.9361265e-7,"bytes":[32,116,111]},{"token":" myself","logprob":-1.7432603e-6,"bytes":[32,109,121,115,101,108,102]},{"token":",","logprob":-0.29254505,"bytes":[44]},{"token":" what","logprob":-0.016815351,"bytes":[32,119,104,97,116]},{"token":" a","logprob":-3.1281633e-7,"bytes":[32,97]},{"token":" wonderful","logprob":-2.1008714e-6,"bytes":[32,119,111,110,100,101,114,102,117,108]},{"token":" world","logprob":-8.180258e-6,"bytes":[32,119,111,114,108,100]},{"token":".","logprob":-0.014231676,"bytes":[46]}]} + - title: Logprobs + request: + curl: | + curl https://api.openai.com/v1/audio/transcriptions \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: multipart/form-data" \ + -F file="@/path/to/file/audio.mp3" \ + -F "include[]=logprobs" \ + -F model="gpt-4o-transcribe" \ + -F response_format="json" + python: | + from openai import OpenAI + client = OpenAI() + + audio_file = open("speech.mp3", "rb") + transcript = client.audio.transcriptions.create( + file=audio_file, + model="gpt-4o-transcribe", + response_format="json", + include=["logprobs"] + ) + + print(transcript) + javascript: > + import fs from "fs"; + + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + async function main() { + const transcription = await openai.audio.transcriptions.create({ + file: fs.createReadStream("audio.mp3"), + model: "gpt-4o-transcribe", + response_format: "json", + include: ["logprobs"] + }); + + console.log(transcription); + } + + main(); + response: > + { + "text": "Hey, my knee is hurting and I want to see the doctor tomorrow ideally.", + "logprobs": [ + { "token": "Hey", "logprob": -1.0415299, "bytes": [72, 101, 121] }, + { "token": ",", "logprob": -9.805982e-5, "bytes": [44] }, + { "token": " my", "logprob": -0.00229799, "bytes": [32, 109, 121] }, + { + "token": " knee", + "logprob": -4.7159858e-5, + "bytes": [32, 107, 110, 101, 101] + }, + { "token": " is", "logprob": -0.043909557, "bytes": [32, 105, 115] }, + { + "token": " hurting", + "logprob": -1.1041146e-5, + "bytes": [32, 104, 117, 114, 116, 105, 110, 103] + }, + { "token": " and", "logprob": -0.011076359, "bytes": [32, 97, 110, 100] }, + { "token": " I", "logprob": -5.3193703e-6, "bytes": [32, 73] }, + { + "token": " want", + "logprob": -0.0017156356, + "bytes": [32, 119, 97, 110, 116] + }, + { "token": " to", "logprob": -7.89631e-7, "bytes": [32, 116, 111] }, + { "token": " see", "logprob": -5.5122365e-7, "bytes": [32, 115, 101, 101] }, + { "token": " the", "logprob": -0.0040786397, "bytes": [32, 116, 104, 101] }, + { + "token": " doctor", + "logprob": -2.3392786e-6, + "bytes": [32, 100, 111, 99, 116, 111, 114] + }, + { + "token": " tomorrow", + "logprob": -7.89631e-7, + "bytes": [32, 116, 111, 109, 111, 114, 114, 111, 119] + }, + { + "token": " ideally", + "logprob": -0.5800861, + "bytes": [32, 105, 100, 101, 97, 108, 108, 121] + }, + { "token": ".", "logprob": -0.00011093382, "bytes": [46] } + ] + } + - title: Word timestamps + request: + curl: | + curl https://api.openai.com/v1/audio/transcriptions \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: multipart/form-data" \ + -F file="@/path/to/file/audio.mp3" \ + -F "timestamp_granularities[]=word" \ + -F model="whisper-1" \ + -F response_format="verbose_json" + python: | + from openai import OpenAI + client = OpenAI() + + audio_file = open("speech.mp3", "rb") + transcript = client.audio.transcriptions.create( + file=audio_file, + model="whisper-1", + response_format="verbose_json", + timestamp_granularities=["word"] + ) + + print(transcript.words) + javascript: > + import fs from "fs"; + + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + async function main() { + const transcription = await openai.audio.transcriptions.create({ + file: fs.createReadStream("audio.mp3"), + model: "whisper-1", + response_format: "verbose_json", + timestamp_granularities: ["word"] + }); + + console.log(transcription.text); + } + + main(); + csharp: > + using System; + + + using OpenAI.Audio; + + + string audioFilePath = "audio.mp3"; + + + AudioClient client = new( + model: "whisper-1", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + AudioTranscriptionOptions options = new() + + { + ResponseFormat = AudioTranscriptionFormat.Verbose, + TimestampGranularities = AudioTimestampGranularities.Word, + }; + + + AudioTranscription transcription = + client.TranscribeAudio(audioFilePath, options); + + + Console.WriteLine($"{transcription.Text}"); + response: > + { + "task": "transcribe", + "language": "english", + "duration": 8.470000267028809, + "text": "The beach was a popular spot on a hot summer day. People were swimming in the ocean, building sandcastles, and playing beach volleyball.", + "words": [ + { + "word": "The", + "start": 0.0, + "end": 0.23999999463558197 + }, + ... + { + "word": "volleyball", + "start": 7.400000095367432, + "end": 7.900000095367432 + } + ] + } + - title: Segment timestamps + request: + curl: | + curl https://api.openai.com/v1/audio/transcriptions \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: multipart/form-data" \ + -F file="@/path/to/file/audio.mp3" \ + -F "timestamp_granularities[]=segment" \ + -F model="whisper-1" \ + -F response_format="verbose_json" + python: | + from openai import OpenAI + client = OpenAI() + + audio_file = open("speech.mp3", "rb") + transcript = client.audio.transcriptions.create( + file=audio_file, + model="whisper-1", + response_format="verbose_json", + timestamp_granularities=["segment"] + ) + + print(transcript.words) + javascript: > + import fs from "fs"; + + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + async function main() { + const transcription = await openai.audio.transcriptions.create({ + file: fs.createReadStream("audio.mp3"), + model: "whisper-1", + response_format: "verbose_json", + timestamp_granularities: ["segment"] + }); + + console.log(transcription.text); + } + + main(); + csharp: > + using System; + + + using OpenAI.Audio; + + + string audioFilePath = "audio.mp3"; + + + AudioClient client = new( + model: "whisper-1", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + AudioTranscriptionOptions options = new() + + { + ResponseFormat = AudioTranscriptionFormat.Verbose, + TimestampGranularities = AudioTimestampGranularities.Segment, + }; + + + AudioTranscription transcription = + client.TranscribeAudio(audioFilePath, options); + + + Console.WriteLine($"{transcription.Text}"); + response: > + { + "task": "transcribe", + "language": "english", + "duration": 8.470000267028809, + "text": "The beach was a popular spot on a hot summer day. People were swimming in the ocean, building sandcastles, and playing beach volleyball.", + "segments": [ + { + "id": 0, + "seek": 0, + "start": 0.0, + "end": 3.319999933242798, + "text": " The beach was a popular spot on a hot summer day.", + "tokens": [ + 50364, 440, 7534, 390, 257, 3743, 4008, 322, 257, 2368, 4266, 786, 13, 50530 + ], + "temperature": 0.0, + "avg_logprob": -0.2860786020755768, + "compression_ratio": 1.2363636493682861, + "no_speech_prob": 0.00985979475080967 + }, + ... + ] + } + /audio/translations: + post: + operationId: createTranslation + tags: + - Audio + summary: Translates audio into English. + requestBody: + required: true + content: + multipart/form-data: + schema: + $ref: "#/components/schemas/CreateTranslationRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + oneOf: + - $ref: "#/components/schemas/CreateTranslationResponseJson" + - $ref: "#/components/schemas/CreateTranslationResponseVerboseJson" + x-oaiMeta: + name: Create translation + group: audio + returns: The translated text. + examples: + request: + curl: | + curl https://api.openai.com/v1/audio/translations \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: multipart/form-data" \ + -F file="@/path/to/file/german.m4a" \ + -F model="whisper-1" + python: | + from openai import OpenAI + client = OpenAI() + + audio_file = open("speech.mp3", "rb") + transcript = client.audio.translations.create( + model="whisper-1", + file=audio_file + ) + javascript: | + import fs from "fs"; + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const translation = await openai.audio.translations.create({ + file: fs.createReadStream("speech.mp3"), + model: "whisper-1", + }); + + console.log(translation.text); + } + main(); + csharp: > + using System; + + + using OpenAI.Audio; + + + string audioFilePath = "audio.mp3"; + + + AudioClient client = new( + model: "whisper-1", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + AudioTranscription transcription = + client.TranscribeAudio(audioFilePath); + + + Console.WriteLine($"{transcription.Text}"); + response: > + { + "text": "Hello, my name is Wolfgang and I come from Germany. Where are you heading today?" + } + /batches: + post: + summary: Creates and executes a batch from an uploaded file of requests + operationId: createBatch + tags: + - Batch + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - input_file_id + - endpoint + - completion_window + properties: + input_file_id: + type: string + description: > + The ID of an uploaded file that contains requests for the + new batch. + + + See [upload file](/docs/api-reference/files/create) for how + to upload a file. + + + Your input file must be formatted as a [JSONL + file](/docs/api-reference/batch/request-input), and must be + uploaded with the purpose `batch`. The file can contain up + to 50,000 requests, and can be up to 200 MB in size. + endpoint: + type: string + enum: + - /v1/responses + - /v1/chat/completions + - /v1/embeddings + - /v1/completions + description: The endpoint to be used for all requests in the batch. Currently + `/v1/responses`, `/v1/chat/completions`, `/v1/embeddings`, + and `/v1/completions` are supported. Note that + `/v1/embeddings` batches are also restricted to a maximum of + 50,000 embedding inputs across all requests in the batch. + completion_window: + type: string + enum: + - 24h + description: The time frame within which the batch should be processed. + Currently only `24h` is supported. + metadata: + $ref: "#/components/schemas/Metadata" + responses: + "200": + description: Batch created successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/Batch" + x-oaiMeta: + name: Create batch + group: batch + returns: The created [Batch](/docs/api-reference/batch/object) object. + examples: + request: + curl: | + curl https://api.openai.com/v1/batches \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "input_file_id": "file-abc123", + "endpoint": "/v1/chat/completions", + "completion_window": "24h" + }' + python: | + from openai import OpenAI + client = OpenAI() + + client.batches.create( + input_file_id="file-abc123", + endpoint="/v1/chat/completions", + completion_window="24h" + ) + node: | + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const batch = await openai.batches.create({ + input_file_id: "file-abc123", + endpoint: "/v1/chat/completions", + completion_window: "24h" + }); + + console.log(batch); + } + + main(); + response: | + { + "id": "batch_abc123", + "object": "batch", + "endpoint": "/v1/chat/completions", + "errors": null, + "input_file_id": "file-abc123", + "completion_window": "24h", + "status": "validating", + "output_file_id": null, + "error_file_id": null, + "created_at": 1711471533, + "in_progress_at": null, + "expires_at": null, + "finalizing_at": null, + "completed_at": null, + "failed_at": null, + "expired_at": null, + "cancelling_at": null, + "cancelled_at": null, + "request_counts": { + "total": 0, + "completed": 0, + "failed": 0 + }, + "metadata": { + "customer_id": "user_123456789", + "batch_description": "Nightly eval job", + } + } + get: + operationId: listBatches + tags: + - Batch + summary: List your organization's batches. + parameters: + - in: query + name: after + required: false + schema: + type: string + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + - name: limit + in: query + description: > + A limit on the number of objects to be returned. Limit can range + between 1 and 100, and the default is 20. + required: false + schema: + type: integer + default: 20 + responses: + "200": + description: Batch listed successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ListBatchesResponse" + x-oaiMeta: + name: List batch + group: batch + returns: A list of paginated [Batch](/docs/api-reference/batch/object) objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/batches?limit=2 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" + python: | + from openai import OpenAI + client = OpenAI() + + client.batches.list() + node: | + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const list = await openai.batches.list(); + + for await (const batch of list) { + console.log(batch); + } + } + + main(); + response: | + { + "object": "list", + "data": [ + { + "id": "batch_abc123", + "object": "batch", + "endpoint": "/v1/chat/completions", + "errors": null, + "input_file_id": "file-abc123", + "completion_window": "24h", + "status": "completed", + "output_file_id": "file-cvaTdG", + "error_file_id": "file-HOWS94", + "created_at": 1711471533, + "in_progress_at": 1711471538, + "expires_at": 1711557933, + "finalizing_at": 1711493133, + "completed_at": 1711493163, + "failed_at": null, + "expired_at": null, + "cancelling_at": null, + "cancelled_at": null, + "request_counts": { + "total": 100, + "completed": 95, + "failed": 5 + }, + "metadata": { + "customer_id": "user_123456789", + "batch_description": "Nightly job", + } + }, + { ... }, + ], + "first_id": "batch_abc123", + "last_id": "batch_abc456", + "has_more": true + } + /batches/{batch_id}: + get: + operationId: retrieveBatch + tags: + - Batch + summary: Retrieves a batch. + parameters: + - in: path + name: batch_id + required: true + schema: + type: string + description: The ID of the batch to retrieve. + responses: + "200": + description: Batch retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/Batch" + x-oaiMeta: + name: Retrieve batch + group: batch + returns: The [Batch](/docs/api-reference/batch/object) object matching the + specified ID. + examples: + request: + curl: | + curl https://api.openai.com/v1/batches/batch_abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + python: | + from openai import OpenAI + client = OpenAI() + + client.batches.retrieve("batch_abc123") + node: | + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const batch = await openai.batches.retrieve("batch_abc123"); + + console.log(batch); + } + + main(); + response: | + { + "id": "batch_abc123", + "object": "batch", + "endpoint": "/v1/completions", + "errors": null, + "input_file_id": "file-abc123", + "completion_window": "24h", + "status": "completed", + "output_file_id": "file-cvaTdG", + "error_file_id": "file-HOWS94", + "created_at": 1711471533, + "in_progress_at": 1711471538, + "expires_at": 1711557933, + "finalizing_at": 1711493133, + "completed_at": 1711493163, + "failed_at": null, + "expired_at": null, + "cancelling_at": null, + "cancelled_at": null, + "request_counts": { + "total": 100, + "completed": 95, + "failed": 5 + }, + "metadata": { + "customer_id": "user_123456789", + "batch_description": "Nightly eval job", + } + } + /batches/{batch_id}/cancel: + post: + operationId: cancelBatch + tags: + - Batch + summary: Cancels an in-progress batch. The batch will be in status `cancelling` + for up to 10 minutes, before changing to `cancelled`, where it will have + partial results (if any) available in the output file. + parameters: + - in: path + name: batch_id + required: true + schema: + type: string + description: The ID of the batch to cancel. + responses: + "200": + description: Batch is cancelling. Returns the cancelling batch's details. + content: + application/json: + schema: + $ref: "#/components/schemas/Batch" + x-oaiMeta: + name: Cancel batch + group: batch + returns: The [Batch](/docs/api-reference/batch/object) object matching the + specified ID. + examples: + request: + curl: | + curl https://api.openai.com/v1/batches/batch_abc123/cancel \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -X POST + python: | + from openai import OpenAI + client = OpenAI() + + client.batches.cancel("batch_abc123") + node: | + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const batch = await openai.batches.cancel("batch_abc123"); + + console.log(batch); + } + + main(); + response: | + { + "id": "batch_abc123", + "object": "batch", + "endpoint": "/v1/chat/completions", + "errors": null, + "input_file_id": "file-abc123", + "completion_window": "24h", + "status": "cancelling", + "output_file_id": null, + "error_file_id": null, + "created_at": 1711471533, + "in_progress_at": 1711471538, + "expires_at": 1711557933, + "finalizing_at": null, + "completed_at": null, + "failed_at": null, + "expired_at": null, + "cancelling_at": 1711475133, + "cancelled_at": null, + "request_counts": { + "total": 100, + "completed": 23, + "failed": 1 + }, + "metadata": { + "customer_id": "user_123456789", + "batch_description": "Nightly eval job", + } + } + /chat/completions: + get: + operationId: listChatCompletions + tags: + - Chat + summary: > + List stored Chat Completions. Only Chat Completions that have been + stored + + with the `store` parameter set to `true` will be returned. + parameters: + - name: model + in: query + description: The model used to generate the Chat Completions. + required: false + schema: + type: string + - name: metadata + in: query + description: | + A list of metadata keys to filter the Chat Completions by. Example: + + `metadata[key1]=value1&metadata[key2]=value2` + required: false + schema: + $ref: "#/components/schemas/Metadata" + - name: after + in: query + description: Identifier for the last chat completion from the previous + pagination request. + required: false + schema: + type: string + - name: limit + in: query + description: Number of Chat Completions to retrieve. + required: false + schema: + type: integer + default: 20 + - name: order + in: query + description: Sort order for Chat Completions by timestamp. Use `asc` for + ascending order or `desc` for descending order. Defaults to `asc`. + required: false + schema: + type: string + enum: + - asc + - desc + default: asc + responses: + "200": + description: A list of Chat Completions + content: + application/json: + schema: + $ref: "#/components/schemas/ChatCompletionList" + x-oaiMeta: + name: List Chat Completions + group: chat + returns: A list of [Chat Completions](/docs/api-reference/chat/list-object) + matching the specified filters. + path: list + examples: + request: + curl: | + curl https://api.openai.com/v1/chat/completions \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" + python: | + from openai import OpenAI + client = OpenAI() + + completions = client.chat.completions.list() + print(completions) + response: > + { + "object": "list", + "data": [ + { + "object": "chat.completion", + "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", + "model": "gpt-4.1-2025-04-14", + "created": 1738960610, + "request_id": "req_ded8ab984ec4bf840f37566c1011c417", + "tool_choice": null, + "usage": { + "total_tokens": 31, + "completion_tokens": 18, + "prompt_tokens": 13 + }, + "seed": 4944116822809979520, + "top_p": 1.0, + "temperature": 1.0, + "presence_penalty": 0.0, + "frequency_penalty": 0.0, + "system_fingerprint": "fp_50cad350e4", + "input_user": null, + "service_tier": "default", + "tools": null, + "metadata": {}, + "choices": [ + { + "index": 0, + "message": { + "content": "Mind of circuits hum, \nLearning patterns in silence— \nFuture's quiet spark.", + "role": "assistant", + "tool_calls": null, + "function_call": null + }, + "finish_reason": "stop", + "logprobs": null + } + ], + "response_format": null + } + ], + "first_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", + "last_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", + "has_more": false + } + post: + operationId: createChatCompletion + tags: + - Chat + summary: | + **Starting a new project?** We recommend trying [Responses](/docs/api-reference/responses) + to take advantage of the latest OpenAI platform features. Compare + [Chat Completions with Responses](/docs/guides/responses-vs-chat-completions?api-mode=responses). + + --- + + Creates a model response for the given chat conversation. Learn more in the + [text generation](/docs/guides/text-generation), [vision](/docs/guides/vision), + and [audio](/docs/guides/audio) guides. + + Parameter support can differ depending on the model used to generate the + response, particularly for newer reasoning models. Parameters that are only + supported for reasoning models are noted below. For the current state of + unsupported parameters in reasoning models, + [refer to the reasoning guide](/docs/guides/reasoning). + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateChatCompletionRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/CreateChatCompletionResponse" + text/event-stream: + schema: + $ref: "#/components/schemas/CreateChatCompletionStreamResponse" + x-oaiMeta: + name: Create chat completion + group: chat + returns: > + Returns a [chat completion](/docs/api-reference/chat/object) object, + or a streamed sequence of [chat completion + chunk](/docs/api-reference/chat/streaming) objects if the request is + streamed. + path: create + examples: + - title: Default + request: + curl: | + curl https://api.openai.com/v1/chat/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "VAR_chat_model_id", + "messages": [ + { + "role": "developer", + "content": "You are a helpful assistant." + }, + { + "role": "user", + "content": "Hello!" + } + ] + }' + python: > + from openai import OpenAI + + client = OpenAI() + + + completion = client.chat.completions.create( + model="VAR_chat_model_id", + messages=[ + {"role": "developer", "content": "You are a helpful assistant."}, + {"role": "user", "content": "Hello!"} + ] + ) + + + print(completion.choices[0].message) + node.js: > + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + async function main() { + const completion = await openai.chat.completions.create({ + messages: [{ role: "developer", content: "You are a helpful assistant." }], + model: "VAR_chat_model_id", + store: true, + }); + + console.log(completion.choices[0]); + } + + + main(); + csharp: | + using System; + using System.Collections.Generic; + + using OpenAI.Chat; + + ChatClient client = new( + model: "gpt-4.1", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + List messages = + [ + new SystemChatMessage("You are a helpful assistant."), + new UserChatMessage("Hello!") + ]; + + ChatCompletion completion = client.CompleteChat(messages); + + Console.WriteLine(completion.Content[0].Text); + response: | + { + "id": "chatcmpl-B9MBs8CjcvOU2jLn4n570S5qMJKcT", + "object": "chat.completion", + "created": 1741569952, + "model": "gpt-4.1-2025-04-14", + "choices": [ + { + "index": 0, + "message": { + "role": "assistant", + "content": "Hello! How can I assist you today?", + "refusal": null, + "annotations": [] + }, + "logprobs": null, + "finish_reason": "stop" + } + ], + "usage": { + "prompt_tokens": 19, + "completion_tokens": 10, + "total_tokens": 29, + "prompt_tokens_details": { + "cached_tokens": 0, + "audio_tokens": 0 + }, + "completion_tokens_details": { + "reasoning_tokens": 0, + "audio_tokens": 0, + "accepted_prediction_tokens": 0, + "rejected_prediction_tokens": 0 + } + }, + "service_tier": "default" + } + - title: Image input + request: + curl: > + curl https://api.openai.com/v1/chat/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-4.1", + "messages": [ + { + "role": "user", + "content": [ + { + "type": "text", + "text": "What is in this image?" + }, + { + "type": "image_url", + "image_url": { + "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg" + } + } + ] + } + ], + "max_tokens": 300 + }' + python: > + from openai import OpenAI + + + client = OpenAI() + + + response = client.chat.completions.create( + model="gpt-4.1", + messages=[ + { + "role": "user", + "content": [ + {"type": "text", "text": "What's in this image?"}, + { + "type": "image_url", + "image_url": { + "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg", + } + }, + ], + } + ], + max_tokens=300, + ) + + + print(response.choices[0]) + node.js: > + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + async function main() { + const response = await openai.chat.completions.create({ + model: "gpt-4.1", + messages: [ + { + role: "user", + content: [ + { type: "text", text: "What's in this image?" }, + { + type: "image_url", + image_url: { + "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg", + }, + } + ], + }, + ], + }); + console.log(response.choices[0]); + } + + main(); + csharp: > + using System; + + using System.Collections.Generic; + + + using OpenAI.Chat; + + + ChatClient client = new( + model: "gpt-4.1", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + List messages = + + [ + new UserChatMessage( + [ + ChatMessageContentPart.CreateTextPart("What's in this image?"), + ChatMessageContentPart.CreateImagePart(new Uri("https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg")) + ]) + ]; + + + ChatCompletion completion = client.CompleteChat(messages); + + + Console.WriteLine(completion.Content[0].Text); + response: > + { + "id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG", + "object": "chat.completion", + "created": 1741570283, + "model": "gpt-4.1-2025-04-14", + "choices": [ + { + "index": 0, + "message": { + "role": "assistant", + "content": "The image shows a wooden boardwalk path running through a lush green field or meadow. The sky is bright blue with some scattered clouds, giving the scene a serene and peaceful atmosphere. Trees and shrubs are visible in the background.", + "refusal": null, + "annotations": [] + }, + "logprobs": null, + "finish_reason": "stop" + } + ], + "usage": { + "prompt_tokens": 1117, + "completion_tokens": 46, + "total_tokens": 1163, + "prompt_tokens_details": { + "cached_tokens": 0, + "audio_tokens": 0 + }, + "completion_tokens_details": { + "reasoning_tokens": 0, + "audio_tokens": 0, + "accepted_prediction_tokens": 0, + "rejected_prediction_tokens": 0 + } + }, + "service_tier": "default" + } + - title: Streaming + request: + curl: | + curl https://api.openai.com/v1/chat/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "VAR_chat_model_id", + "messages": [ + { + "role": "developer", + "content": "You are a helpful assistant." + }, + { + "role": "user", + "content": "Hello!" + } + ], + "stream": true + }' + python: > + from openai import OpenAI + + client = OpenAI() + + + completion = client.chat.completions.create( + model="VAR_chat_model_id", + messages=[ + {"role": "developer", "content": "You are a helpful assistant."}, + {"role": "user", "content": "Hello!"} + ], + stream=True + ) + + + for chunk in completion: + print(chunk.choices[0].delta) + node.js: > + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + async function main() { + const completion = await openai.chat.completions.create({ + model: "VAR_chat_model_id", + messages: [ + {"role": "developer", "content": "You are a helpful assistant."}, + {"role": "user", "content": "Hello!"} + ], + stream: true, + }); + + for await (const chunk of completion) { + console.log(chunk.choices[0].delta.content); + } + } + + + main(); + csharp: > + using System; + + using System.ClientModel; + + using System.Collections.Generic; + + using System.Threading.Tasks; + + + using OpenAI.Chat; + + + ChatClient client = new( + model: "gpt-4.1", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + List messages = + + [ + new SystemChatMessage("You are a helpful assistant."), + new UserChatMessage("Hello!") + ]; + + + AsyncCollectionResult + completionUpdates = client.CompleteChatStreamingAsync(messages); + + + await foreach (StreamingChatCompletionUpdate completionUpdate in + completionUpdates) + + { + if (completionUpdate.ContentUpdate.Count > 0) + { + Console.Write(completionUpdate.ContentUpdate[0].Text); + } + } + response: | + {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]} + + {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"content":"Hello"},"logprobs":null,"finish_reason":null}]} + + .... + + {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}]} + - title: Functions + request: + curl: > + curl https://api.openai.com/v1/chat/completions \ + + -H "Content-Type: application/json" \ + + -H "Authorization: Bearer $OPENAI_API_KEY" \ + + -d '{ + "model": "gpt-4.1", + "messages": [ + { + "role": "user", + "content": "What is the weather like in Boston today?" + } + ], + "tools": [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": ["celsius", "fahrenheit"] + } + }, + "required": ["location"] + } + } + } + ], + "tool_choice": "auto" + }' + python: > + from openai import OpenAI + + client = OpenAI() + + + tools = [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA", + }, + "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}, + }, + "required": ["location"], + }, + } + } + ] + + messages = [{"role": "user", "content": "What's the weather like + in Boston today?"}] + + completion = client.chat.completions.create( + model="VAR_chat_model_id", + messages=messages, + tools=tools, + tool_choice="auto" + ) + + + print(completion) + node.js: > + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + async function main() { + const messages = [{"role": "user", "content": "What's the weather like in Boston today?"}]; + const tools = [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA", + }, + "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}, + }, + "required": ["location"], + }, + } + } + ]; + + const response = await openai.chat.completions.create({ + model: "gpt-4.1", + messages: messages, + tools: tools, + tool_choice: "auto", + }); + + console.log(response); + } + + + main(); + csharp: > + using System; + + using System.Collections.Generic; + + + using OpenAI.Chat; + + + ChatClient client = new( + model: "gpt-4.1", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + ChatTool getCurrentWeatherTool = ChatTool.CreateFunctionTool( + functionName: "get_current_weather", + functionDescription: "Get the current weather in a given location", + functionParameters: BinaryData.FromString(""" + { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": [ "celsius", "fahrenheit" ] + } + }, + "required": [ "location" ] + } + """) + ); + + + List messages = + + [ + new UserChatMessage("What's the weather like in Boston today?"), + ]; + + + ChatCompletionOptions options = new() + + { + Tools = + { + getCurrentWeatherTool + }, + ToolChoice = ChatToolChoice.CreateAutoChoice(), + }; + + + ChatCompletion completion = client.CompleteChat(messages, + options); + response: | + { + "id": "chatcmpl-abc123", + "object": "chat.completion", + "created": 1699896916, + "model": "gpt-4o-mini", + "choices": [ + { + "index": 0, + "message": { + "role": "assistant", + "content": null, + "tool_calls": [ + { + "id": "call_abc123", + "type": "function", + "function": { + "name": "get_current_weather", + "arguments": "{\n\"location\": \"Boston, MA\"\n}" + } + } + ] + }, + "logprobs": null, + "finish_reason": "tool_calls" + } + ], + "usage": { + "prompt_tokens": 82, + "completion_tokens": 17, + "total_tokens": 99, + "completion_tokens_details": { + "reasoning_tokens": 0, + "accepted_prediction_tokens": 0, + "rejected_prediction_tokens": 0 + } + } + } + - title: Logprobs + request: + curl: | + curl https://api.openai.com/v1/chat/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "VAR_chat_model_id", + "messages": [ + { + "role": "user", + "content": "Hello!" + } + ], + "logprobs": true, + "top_logprobs": 2 + }' + python: | + from openai import OpenAI + client = OpenAI() + + completion = client.chat.completions.create( + model="VAR_chat_model_id", + messages=[ + {"role": "user", "content": "Hello!"} + ], + logprobs=True, + top_logprobs=2 + ) + + print(completion.choices[0].message) + print(completion.choices[0].logprobs) + node.js: | + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const completion = await openai.chat.completions.create({ + messages: [{ role: "user", content: "Hello!" }], + model: "VAR_chat_model_id", + logprobs: true, + top_logprobs: 2, + }); + + console.log(completion.choices[0]); + } + + main(); + csharp: > + using System; + + using System.Collections.Generic; + + + using OpenAI.Chat; + + + ChatClient client = new( + model: "gpt-4.1", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + List messages = + + [ + new UserChatMessage("Hello!") + ]; + + + ChatCompletionOptions options = new() + + { + IncludeLogProbabilities = true, + TopLogProbabilityCount = 2 + }; + + + ChatCompletion completion = client.CompleteChat(messages, + options); + + + Console.WriteLine(completion.Content[0].Text); + response: | + { + "id": "chatcmpl-123", + "object": "chat.completion", + "created": 1702685778, + "model": "gpt-4o-mini", + "choices": [ + { + "index": 0, + "message": { + "role": "assistant", + "content": "Hello! How can I assist you today?" + }, + "logprobs": { + "content": [ + { + "token": "Hello", + "logprob": -0.31725305, + "bytes": [72, 101, 108, 108, 111], + "top_logprobs": [ + { + "token": "Hello", + "logprob": -0.31725305, + "bytes": [72, 101, 108, 108, 111] + }, + { + "token": "Hi", + "logprob": -1.3190403, + "bytes": [72, 105] + } + ] + }, + { + "token": "!", + "logprob": -0.02380986, + "bytes": [ + 33 + ], + "top_logprobs": [ + { + "token": "!", + "logprob": -0.02380986, + "bytes": [33] + }, + { + "token": " there", + "logprob": -3.787621, + "bytes": [32, 116, 104, 101, 114, 101] + } + ] + }, + { + "token": " How", + "logprob": -0.000054669687, + "bytes": [32, 72, 111, 119], + "top_logprobs": [ + { + "token": " How", + "logprob": -0.000054669687, + "bytes": [32, 72, 111, 119] + }, + { + "token": "<|end|>", + "logprob": -10.953937, + "bytes": null + } + ] + }, + { + "token": " can", + "logprob": -0.015801601, + "bytes": [32, 99, 97, 110], + "top_logprobs": [ + { + "token": " can", + "logprob": -0.015801601, + "bytes": [32, 99, 97, 110] + }, + { + "token": " may", + "logprob": -4.161023, + "bytes": [32, 109, 97, 121] + } + ] + }, + { + "token": " I", + "logprob": -3.7697225e-6, + "bytes": [ + 32, + 73 + ], + "top_logprobs": [ + { + "token": " I", + "logprob": -3.7697225e-6, + "bytes": [32, 73] + }, + { + "token": " assist", + "logprob": -13.596657, + "bytes": [32, 97, 115, 115, 105, 115, 116] + } + ] + }, + { + "token": " assist", + "logprob": -0.04571125, + "bytes": [32, 97, 115, 115, 105, 115, 116], + "top_logprobs": [ + { + "token": " assist", + "logprob": -0.04571125, + "bytes": [32, 97, 115, 115, 105, 115, 116] + }, + { + "token": " help", + "logprob": -3.1089056, + "bytes": [32, 104, 101, 108, 112] + } + ] + }, + { + "token": " you", + "logprob": -5.4385737e-6, + "bytes": [32, 121, 111, 117], + "top_logprobs": [ + { + "token": " you", + "logprob": -5.4385737e-6, + "bytes": [32, 121, 111, 117] + }, + { + "token": " today", + "logprob": -12.807695, + "bytes": [32, 116, 111, 100, 97, 121] + } + ] + }, + { + "token": " today", + "logprob": -0.0040071653, + "bytes": [32, 116, 111, 100, 97, 121], + "top_logprobs": [ + { + "token": " today", + "logprob": -0.0040071653, + "bytes": [32, 116, 111, 100, 97, 121] + }, + { + "token": "?", + "logprob": -5.5247097, + "bytes": [63] + } + ] + }, + { + "token": "?", + "logprob": -0.0008108172, + "bytes": [63], + "top_logprobs": [ + { + "token": "?", + "logprob": -0.0008108172, + "bytes": [63] + }, + { + "token": "?\n", + "logprob": -7.184561, + "bytes": [63, 10] + } + ] + } + ] + }, + "finish_reason": "stop" + } + ], + "usage": { + "prompt_tokens": 9, + "completion_tokens": 9, + "total_tokens": 18, + "completion_tokens_details": { + "reasoning_tokens": 0, + "accepted_prediction_tokens": 0, + "rejected_prediction_tokens": 0 + } + }, + "system_fingerprint": null + } + /chat/completions/{completion_id}: + get: + operationId: getChatCompletion + tags: + - Chat + summary: > + Get a stored chat completion. Only Chat Completions that have been + created + + with the `store` parameter set to `true` will be returned. + parameters: + - in: path + name: completion_id + required: true + schema: + type: string + description: The ID of the chat completion to retrieve. + responses: + "200": + description: A chat completion + content: + application/json: + schema: + $ref: "#/components/schemas/CreateChatCompletionResponse" + x-oaiMeta: + name: Get chat completion + group: chat + returns: The [ChatCompletion](/docs/api-reference/chat/object) object matching + the specified ID. + examples: + request: + curl: | + curl https://api.openai.com/v1/chat/completions/chatcmpl-abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" + python: > + from openai import OpenAI + + client = OpenAI() + + + completions = client.chat.completions.list() + + first_id = completions[0].id + + first_completion = + client.chat.completions.retrieve(completion_id=first_id) + + print(first_completion) + response: > + { + "object": "chat.completion", + "id": "chatcmpl-abc123", + "model": "gpt-4o-2024-08-06", + "created": 1738960610, + "request_id": "req_ded8ab984ec4bf840f37566c1011c417", + "tool_choice": null, + "usage": { + "total_tokens": 31, + "completion_tokens": 18, + "prompt_tokens": 13 + }, + "seed": 4944116822809979520, + "top_p": 1.0, + "temperature": 1.0, + "presence_penalty": 0.0, + "frequency_penalty": 0.0, + "system_fingerprint": "fp_50cad350e4", + "input_user": null, + "service_tier": "default", + "tools": null, + "metadata": {}, + "choices": [ + { + "index": 0, + "message": { + "content": "Mind of circuits hum, \nLearning patterns in silence— \nFuture's quiet spark.", + "role": "assistant", + "tool_calls": null, + "function_call": null + }, + "finish_reason": "stop", + "logprobs": null + } + ], + "response_format": null + } + post: + operationId: updateChatCompletion + tags: + - Chat + summary: > + Modify a stored chat completion. Only Chat Completions that have been + + created with the `store` parameter set to `true` can be modified. + Currently, + + the only supported modification is to update the `metadata` field. + parameters: + - in: path + name: completion_id + required: true + schema: + type: string + description: The ID of the chat completion to update. + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - metadata + properties: + metadata: + $ref: "#/components/schemas/Metadata" + responses: + "200": + description: A chat completion + content: + application/json: + schema: + $ref: "#/components/schemas/CreateChatCompletionResponse" + x-oaiMeta: + name: Update chat completion + group: chat + returns: The [ChatCompletion](/docs/api-reference/chat/object) object matching + the specified ID. + examples: + request: + curl: > + curl -X POST + https://api.openai.com/v1/chat/completions/chat_abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"metadata": {"foo": "bar"}}' + python: > + from openai import OpenAI + + client = OpenAI() + + + completions = client.chat.completions.list() + + first_id = completions[0].id + + updated_completion = + client.chat.completions.update(completion_id=first_id, + request_body={"metadata": {"foo": "bar"}}) + + print(updated_completion) + response: > + { + "object": "chat.completion", + "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", + "model": "gpt-4o-2024-08-06", + "created": 1738960610, + "request_id": "req_ded8ab984ec4bf840f37566c1011c417", + "tool_choice": null, + "usage": { + "total_tokens": 31, + "completion_tokens": 18, + "prompt_tokens": 13 + }, + "seed": 4944116822809979520, + "top_p": 1.0, + "temperature": 1.0, + "presence_penalty": 0.0, + "frequency_penalty": 0.0, + "system_fingerprint": "fp_50cad350e4", + "input_user": null, + "service_tier": "default", + "tools": null, + "metadata": { + "foo": "bar" + }, + "choices": [ + { + "index": 0, + "message": { + "content": "Mind of circuits hum, \nLearning patterns in silence— \nFuture's quiet spark.", + "role": "assistant", + "tool_calls": null, + "function_call": null + }, + "finish_reason": "stop", + "logprobs": null + } + ], + "response_format": null + } + delete: + operationId: deleteChatCompletion + tags: + - Chat + summary: | + Delete a stored chat completion. Only Chat Completions that have been + created with the `store` parameter set to `true` can be deleted. + parameters: + - in: path + name: completion_id + required: true + schema: + type: string + description: The ID of the chat completion to delete. + responses: + "200": + description: The chat completion was deleted successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ChatCompletionDeleted" + x-oaiMeta: + name: Delete chat completion + group: chat + returns: A deletion confirmation object. + examples: + request: + curl: > + curl -X DELETE + https://api.openai.com/v1/chat/completions/chat_abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" + python: > + from openai import OpenAI + + client = OpenAI() + + + completions = client.chat.completions.list() + + first_id = completions[0].id + + delete_response = + client.chat.completions.delete(completion_id=first_id) + + print(delete_response) + response: | + { + "object": "chat.completion.deleted", + "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", + "deleted": true + } + /chat/completions/{completion_id}/messages: + get: + operationId: getChatCompletionMessages + tags: + - Chat + summary: | + Get the messages in a stored chat completion. Only Chat Completions that + have been created with the `store` parameter set to `true` will be + returned. + parameters: + - in: path + name: completion_id + required: true + schema: + type: string + description: The ID of the chat completion to retrieve messages from. + - name: after + in: query + description: Identifier for the last message from the previous pagination request. + required: false + schema: + type: string + - name: limit + in: query + description: Number of messages to retrieve. + required: false + schema: + type: integer + default: 20 + - name: order + in: query + description: Sort order for messages by timestamp. Use `asc` for ascending order + or `desc` for descending order. Defaults to `asc`. + required: false + schema: + type: string + enum: + - asc + - desc + default: asc + responses: + "200": + description: A list of messages + content: + application/json: + schema: + $ref: "#/components/schemas/ChatCompletionMessageList" + x-oaiMeta: + name: Get chat messages + group: chat + returns: A list of [messages](/docs/api-reference/chat/message-list) for the + specified chat completion. + examples: + request: + curl: > + curl + https://api.openai.com/v1/chat/completions/chat_abc123/messages \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" + python: > + from openai import OpenAI + + client = OpenAI() + + + completions = client.chat.completions.list() + + first_id = completions[0].id + + first_completion = + client.chat.completions.retrieve(completion_id=first_id) + + messages = + client.chat.completions.messages.list(completion_id=first_id) + + print(messages) + response: | + { + "object": "list", + "data": [ + { + "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0", + "role": "user", + "content": "write a haiku about ai", + "name": null, + "content_parts": null + } + ], + "first_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0", + "last_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0", + "has_more": false + } + /completions: + post: + operationId: createCompletion + tags: + - Completions + summary: Creates a completion for the provided prompt and parameters. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateCompletionRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/CreateCompletionResponse" + x-oaiMeta: + name: Create completion + group: completions + returns: > + Returns a [completion](/docs/api-reference/completions/object) object, + or a sequence of completion objects if the request is streamed. + legacy: true + examples: + - title: No streaming + request: + curl: | + curl https://api.openai.com/v1/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "VAR_completion_model_id", + "prompt": "Say this is a test", + "max_tokens": 7, + "temperature": 0 + }' + python: | + from openai import OpenAI + client = OpenAI() + + client.completions.create( + model="VAR_completion_model_id", + prompt="Say this is a test", + max_tokens=7, + temperature=0 + ) + node.js: |- + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const completion = await openai.completions.create({ + model: "VAR_completion_model_id", + prompt: "Say this is a test.", + max_tokens: 7, + temperature: 0, + }); + + console.log(completion); + } + main(); + response: | + { + "id": "cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7", + "object": "text_completion", + "created": 1589478378, + "model": "VAR_completion_model_id", + "system_fingerprint": "fp_44709d6fcb", + "choices": [ + { + "text": "\n\nThis is indeed a test", + "index": 0, + "logprobs": null, + "finish_reason": "length" + } + ], + "usage": { + "prompt_tokens": 5, + "completion_tokens": 7, + "total_tokens": 12 + } + } + - title: Streaming + request: + curl: | + curl https://api.openai.com/v1/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "VAR_completion_model_id", + "prompt": "Say this is a test", + "max_tokens": 7, + "temperature": 0, + "stream": true + }' + python: | + from openai import OpenAI + client = OpenAI() + + for chunk in client.completions.create( + model="VAR_completion_model_id", + prompt="Say this is a test", + max_tokens=7, + temperature=0, + stream=True + ): + print(chunk.choices[0].text) + node.js: |- + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const stream = await openai.completions.create({ + model: "VAR_completion_model_id", + prompt: "Say this is a test.", + stream: true, + }); + + for await (const chunk of stream) { + console.log(chunk.choices[0].text) + } + } + main(); + response: | + { + "id": "cmpl-7iA7iJjj8V2zOkCGvWF2hAkDWBQZe", + "object": "text_completion", + "created": 1690759702, + "choices": [ + { + "text": "This", + "index": 0, + "logprobs": null, + "finish_reason": null + } + ], + "model": "gpt-3.5-turbo-instruct" + "system_fingerprint": "fp_44709d6fcb", + } + /embeddings: + post: + operationId: createEmbedding + tags: + - Embeddings + summary: Creates an embedding vector representing the input text. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateEmbeddingRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/CreateEmbeddingResponse" + x-oaiMeta: + name: Create embeddings + group: embeddings + returns: A list of [embedding](/docs/api-reference/embeddings/object) objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/embeddings \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "input": "The food was delicious and the waiter...", + "model": "text-embedding-ada-002", + "encoding_format": "float" + }' + python: | + from openai import OpenAI + client = OpenAI() + + client.embeddings.create( + model="text-embedding-ada-002", + input="The food was delicious and the waiter...", + encoding_format="float" + ) + node.js: | + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const embedding = await openai.embeddings.create({ + model: "text-embedding-ada-002", + input: "The quick brown fox jumped over the lazy dog", + encoding_format: "float", + }); + + console.log(embedding); + } + + main(); + csharp: > + using System; + + + using OpenAI.Embeddings; + + + EmbeddingClient client = new( + model: "text-embedding-3-small", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + OpenAIEmbedding embedding = client.GenerateEmbedding(input: "The + quick brown fox jumped over the lazy dog"); + + ReadOnlyMemory vector = embedding.ToFloats(); + + + for (int i = 0; i < vector.Length; i++) + + { + Console.WriteLine($" [{i,4}] = {vector.Span[i]}"); + } + response: | + { + "object": "list", + "data": [ + { + "object": "embedding", + "embedding": [ + 0.0023064255, + -0.009327292, + .... (1536 floats total for ada-002) + -0.0028842222, + ], + "index": 0 + } + ], + "model": "text-embedding-ada-002", + "usage": { + "prompt_tokens": 8, + "total_tokens": 8 + } + } + /evals: + get: + operationId: listEvals + tags: + - Evals + summary: | + List evaluations for a project. + parameters: + - name: after + in: query + description: Identifier for the last eval from the previous pagination request. + required: false + schema: + type: string + - name: limit + in: query + description: Number of evals to retrieve. + required: false + schema: + type: integer + default: 20 + - name: order + in: query + description: Sort order for evals by timestamp. Use `asc` for ascending order or + `desc` for descending order. + required: false + schema: + type: string + enum: + - asc + - desc + default: asc + - name: order_by + in: query + description: > + Evals can be ordered by creation time or last updated time. Use + + `created_at` for creation time or `updated_at` for last updated + time. + required: false + schema: + type: string + enum: + - created_at + - updated_at + default: created_at + responses: + "200": + description: A list of evals + content: + application/json: + schema: + $ref: "#/components/schemas/EvalList" + x-oaiMeta: + name: List evals + group: evals + returns: A list of [evals](/docs/api-reference/evals/object) matching the + specified filters. + path: list + examples: + request: + curl: | + curl https://api.openai.com/v1/evals?limit=1 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" + response: > + { + "object": "list", + "data": [ + { + "id": "eval_67abd54d9b0081909a86353f6fb9317a", + "object": "eval", + "data_source_config": { + "type": "stored_completions", + "metadata": { + "usecase": "push_notifications_summarizer" + }, + "schema": { + "type": "object", + "properties": { + "item": { + "type": "object" + }, + "sample": { + "type": "object" + } + }, + "required": [ + "item", + "sample" + ] + } + }, + "testing_criteria": [ + { + "name": "Push Notification Summary Grader", + "id": "Push Notification Summary Grader-9b876f24-4762-4be9-aff4-db7a9b31c673", + "type": "label_model", + "model": "o3-mini", + "input": [ + { + "type": "message", + "role": "developer", + "content": { + "type": "input_text", + "text": "\nLabel the following push notification summary as either correct or incorrect.\nThe push notification and the summary will be provided below.\nA good push notificiation summary is concise and snappy.\nIf it is good, then label it as correct, if not, then incorrect.\n" + } + }, + { + "type": "message", + "role": "user", + "content": { + "type": "input_text", + "text": "\nPush notifications: {{item.input}}\nSummary: {{sample.output_text}}\n" + } + } + ], + "passing_labels": [ + "correct" + ], + "labels": [ + "correct", + "incorrect" + ], + "sampling_params": null + } + ], + "name": "Push Notification Summary Grader", + "created_at": 1739314509, + "metadata": { + "description": "A stored completions eval for push notification summaries" + } + } + ], + "first_id": "eval_67abd54d9b0081909a86353f6fb9317a", + "last_id": "eval_67aa884cf6688190b58f657d4441c8b7", + "has_more": true + } + post: + operationId: createEval + tags: + - Evals + summary: > + Create the structure of an evaluation that can be used to test a model's + performance. + + An evaluation is a set of testing criteria and a datasource. After + creating an evaluation, you can run it on different models and model + parameters. We support several types of graders and datasources. + + For more information, see the [Evals guide](/docs/guides/evals). + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateEvalRequest" + responses: + "201": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/Eval" + x-oaiMeta: + name: Create eval + group: evals + returns: The created [Eval](/docs/api-reference/evals/object) object. + path: post + examples: + request: + curl: > + curl https://api.openai.com/v1/evals \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Sentiment", + "data_source_config": { + "type": "stored_completions", + "metadata": { + "usecase": "chatbot" + } + }, + "testing_criteria": [ + { + "type": "label_model", + "model": "o3-mini", + "input": [ + { + "role": "developer", + "content": "Classify the sentiment of the following statement as one of 'positive', 'neutral', or 'negative'" + }, + { + "role": "user", + "content": "Statement: {{item.input}}" + } + ], + "passing_labels": [ + "positive" + ], + "labels": [ + "positive", + "neutral", + "negative" + ], + "name": "Example label grader" + } + ] + }' + response: > + { + "object": "eval", + "id": "eval_67b7fa9a81a88190ab4aa417e397ea21", + "data_source_config": { + "type": "stored_completions", + "metadata": { + "usecase": "chatbot" + }, + "schema": { + "type": "object", + "properties": { + "item": { + "type": "object" + }, + "sample": { + "type": "object" + } + }, + "required": [ + "item", + "sample" + ] + }, + "testing_criteria": [ + { + "name": "Example label grader", + "type": "label_model", + "model": "o3-mini", + "input": [ + { + "type": "message", + "role": "developer", + "content": { + "type": "input_text", + "text": "Classify the sentiment of the following statement as one of positive, neutral, or negative" + } + }, + { + "type": "message", + "role": "user", + "content": { + "type": "input_text", + "text": "Statement: {{item.input}}" + } + } + ], + "passing_labels": [ + "positive" + ], + "labels": [ + "positive", + "neutral", + "negative" + ] + } + ], + "name": "Sentiment", + "created_at": 1740110490, + "metadata": { + "description": "An eval for sentiment analysis" + } + } + /evals/{eval_id}: + get: + operationId: getEval + tags: + - Evals + summary: | + Get an evaluation by ID. + parameters: + - name: eval_id + in: path + required: true + schema: + type: string + description: The ID of the evaluation to retrieve. + responses: + "200": + description: The evaluation + content: + application/json: + schema: + $ref: "#/components/schemas/Eval" + x-oaiMeta: + name: Get an eval + group: evals + returns: The [Eval](/docs/api-reference/evals/object) object matching the + specified ID. + path: get + examples: + request: + curl: | + curl https://api.openai.com/v1/evals/eval_67abd54d9b0081909a86353f6fb9317a \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "eval", + "id": "eval_67abd54d9b0081909a86353f6fb9317a", + "data_source_config": { + "type": "custom", + "schema": { + "type": "object", + "properties": { + "item": { + "type": "object", + "properties": { + "input": { + "type": "string" + }, + "ground_truth": { + "type": "string" + } + }, + "required": [ + "input", + "ground_truth" + ] + } + }, + "required": [ + "item" + ] + } + }, + "testing_criteria": [ + { + "name": "String check", + "id": "String check-2eaf2d8d-d649-4335-8148-9535a7ca73c2", + "type": "string_check", + "input": "{{item.input}}", + "reference": "{{item.ground_truth}}", + "operation": "eq" + } + ], + "name": "External Data Eval", + "created_at": 1739314509, + "metadata": {}, + } + post: + operationId: updateEval + tags: + - Evals + summary: | + Update certain properties of an evaluation. + parameters: + - name: eval_id + in: path + required: true + schema: + type: string + description: The ID of the evaluation to update. + requestBody: + description: Request to update an evaluation + required: true + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: Rename the evaluation. + metadata: + $ref: "#/components/schemas/Metadata" + responses: + "200": + description: The updated evaluation + content: + application/json: + schema: + $ref: "#/components/schemas/Eval" + x-oaiMeta: + name: Update an eval + group: evals + returns: The [Eval](/docs/api-reference/evals/object) object matching the + updated version. + path: update + examples: + request: + curl: | + curl https://api.openai.com/v1/evals/eval_67abd54d9b0081909a86353f6fb9317a \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"name": "Updated Eval", "metadata": {"description": "Updated description"}}' + response: | + { + "object": "eval", + "id": "eval_67abd54d9b0081909a86353f6fb9317a", + "data_source_config": { + "type": "custom", + "schema": { + "type": "object", + "properties": { + "item": { + "type": "object", + "properties": { + "input": { + "type": "string" + }, + "ground_truth": { + "type": "string" + } + }, + "required": [ + "input", + "ground_truth" + ] + } + }, + "required": [ + "item" + ] + } + }, + "testing_criteria": [ + { + "name": "String check", + "id": "String check-2eaf2d8d-d649-4335-8148-9535a7ca73c2", + "type": "string_check", + "input": "{{item.input}}", + "reference": "{{item.ground_truth}}", + "operation": "eq" + } + ], + "name": "Updated Eval", + "created_at": 1739314509, + "metadata": {"description": "Updated description"}, + } + delete: + operationId: deleteEval + tags: + - Evals + summary: | + Delete an evaluation. + parameters: + - name: eval_id + in: path + required: true + schema: + type: string + description: The ID of the evaluation to delete. + responses: + "200": + description: Successfully deleted the evaluation. + content: + application/json: + schema: + type: object + properties: + object: + type: string + example: eval.deleted + deleted: + type: boolean + example: true + eval_id: + type: string + example: eval_abc123 + required: + - object + - deleted + - eval_id + "404": + description: Evaluation not found. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-oaiMeta: + name: Delete an eval + group: evals + returns: A deletion confirmation object. + examples: + request: + curl: | + curl https://api.openai.com/v1/evals/eval_abc123 \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_API_KEY" + response: | + { + "object": "eval.deleted", + "deleted": true, + "eval_id": "eval_abc123" + } + /evals/{eval_id}/runs: + get: + operationId: getEvalRuns + tags: + - Evals + summary: | + Get a list of runs for an evaluation. + parameters: + - name: eval_id + in: path + required: true + schema: + type: string + description: The ID of the evaluation to retrieve runs for. + - name: after + in: query + description: Identifier for the last run from the previous pagination request. + required: false + schema: + type: string + - name: limit + in: query + description: Number of runs to retrieve. + required: false + schema: + type: integer + default: 20 + - name: order + in: query + description: Sort order for runs by timestamp. Use `asc` for ascending order or + `desc` for descending order. Defaults to `asc`. + required: false + schema: + type: string + enum: + - asc + - desc + default: asc + - name: status + in: query + description: Filter runs by status. One of `queued` | `in_progress` | `failed` | + `completed` | `canceled`. + required: false + schema: + type: string + enum: + - queued + - in_progress + - completed + - canceled + - failed + responses: + "200": + description: A list of runs for the evaluation + content: + application/json: + schema: + $ref: "#/components/schemas/EvalRunList" + x-oaiMeta: + name: Get eval runs + group: evals + returns: A list of [EvalRun](/docs/api-reference/evals/run-object) objects + matching the specified ID. + path: get-runs + examples: + request: + curl: | + curl https://api.openai.com/v1/evals/egroup_67abd54d9b0081909a86353f6fb9317a/runs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" + response: > + { + "object": "list", + "data": [ + { + "object": "eval.run", + "id": "evalrun_67e0c7d31560819090d60c0780591042", + "eval_id": "eval_67e0c726d560819083f19a957c4c640b", + "report_url": "https://platform.openai.com/evaluations/eval_67e0c726d560819083f19a957c4c640b", + "status": "completed", + "model": "o3-mini", + "name": "bulk_with_negative_examples_o3-mini", + "created_at": 1742784467, + "result_counts": { + "total": 1, + "errored": 0, + "failed": 0, + "passed": 1 + }, + "per_model_usage": [ + { + "model_name": "o3-mini", + "invocation_count": 1, + "prompt_tokens": 563, + "completion_tokens": 874, + "total_tokens": 1437, + "cached_tokens": 0 + } + ], + "per_testing_criteria_results": [ + { + "testing_criteria": "Push Notification Summary Grader-1808cd0b-eeec-4e0b-a519-337e79f4f5d1", + "passed": 1, + "failed": 0 + } + ], + "data_source": { + "type": "completions", + "source": { + "type": "file_content", + "content": [ + { + "item": { + "notifications": "\n- New message from Sarah: \"Can you call me later?\"\n- Your package has been delivered!\n- Flash sale: 20% off electronics for the next 2 hours!\n" + } + } + ] + }, + "input_messages": { + "type": "template", + "template": [ + { + "type": "message", + "role": "developer", + "content": { + "type": "input_text", + "text": "\n\n\n\nYou are a helpful assistant that takes in an array of push notifications and returns a collapsed summary of them.\nThe push notification will be provided as follows:\n\n...notificationlist...\n\n\nYou should return just the summary and nothing else.\n\n\nYou should return a summary that is concise and snappy.\n\n\nHere is an example of a good summary:\n\n- Traffic alert: Accident reported on Main Street.- Package out for delivery: Expected by 5 PM.- New friend suggestion: Connect with Emma.\n\n\nTraffic alert, package expected by 5pm, suggestion for new friend (Emily).\n\n\n\nHere is an example of a bad summary:\n\n- Traffic alert: Accident reported on Main Street.- Package out for delivery: Expected by 5 PM.- New friend suggestion: Connect with Emma.\n\n\nTraffic alert reported on main street. You have a package that will arrive by 5pm, Emily is a new friend suggested for you.\n\n" + } + }, + { + "type": "message", + "role": "user", + "content": { + "type": "input_text", + "text": "{{item.notifications}}" + } + } + ] + }, + "model": "o3-mini", + "sampling_params": null + }, + "error": null, + "metadata": {} + } + ], + "first_id": "evalrun_67e0c7d31560819090d60c0780591042", + "last_id": "evalrun_67e0c7d31560819090d60c0780591042", + "has_more": true + } + post: + operationId: createEvalRun + tags: + - Evals + summary: > + Create a new evaluation run. This is the endpoint that will kick off + grading. + parameters: + - in: path + name: eval_id + required: true + schema: + type: string + description: The ID of the evaluation to create a run for. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateEvalRunRequest" + responses: + "201": + description: Successfully created a run for the evaluation + content: + application/json: + schema: + $ref: "#/components/schemas/EvalRun" + "400": + description: Bad request (for example, missing eval object) + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-oaiMeta: + name: Create eval run + group: evals + returns: The [EvalRun](/docs/api-reference/evals/run-object) object matching the + specified ID. + examples: + request: + curl: | + curl https://api.openai.com/v1/evals/eval_67e579652b548190aaa83ada4b125f47/runs \ + -X POST \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"name":"gpt-4o-mini","data_source":{"type":"completions","input_messages":{"type":"template","template":[{"role":"developer","content":"Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\n\n# Steps\n\n1. Analyze the content of the news headline to understand its primary focus.\n2. Extract the subject matter, identifying any key indicators or keywords.\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\n4. Ensure only one category is selected per headline.\n\n# Output Format\n\nRespond with the chosen category as a single word. For instance: \"Technology\", \"Markets\", \"World\", \"Business\", or \"Sports\".\n\n# Examples\n\n**Input**: \"Apple Unveils New iPhone Model, Featuring Advanced AI Features\" \n**Output**: \"Technology\"\n\n**Input**: \"Global Stocks Mixed as Investors Await Central Bank Decisions\" \n**Output**: \"Markets\"\n\n**Input**: \"War in Ukraine: Latest Updates on Negotiation Status\" \n**Output**: \"World\"\n\n**Input**: \"Microsoft in Talks to Acquire Gaming Company for $2 Billion\" \n**Output**: \"Business\"\n\n**Input**: \"Manchester United Secures Win in Premier League Football Match\" \n**Output**: \"Sports\" \n\n# Notes\n\n- If the headline appears to fit into more than one category, choose the most dominant theme.\n- Keywords or phrases such as \"stocks\", \"company acquisition\", \"match\", or technological brands can be good indicators for classification.\n"} , {"role":"user","content":"{{item.input}}"}]},"sampling_params":{"temperature":1,"max_completions_tokens":2048,"top_p":1,"seed":42},"model":"gpt-4o-mini","source":{"type":"file_content","content":[{"item":{"input":"Tech Company Launches Advanced Artificial Intelligence Platform","ground_truth":"Technology"}}]}}' + response: > + { + "object": "eval.run", + "id": "evalrun_67e57965b480819094274e3a32235e4c", + "eval_id": "eval_67e579652b548190aaa83ada4b125f47", + "report_url": "https://platform.openai.com/evaluations/eval_67e579652b548190aaa83ada4b125f47&run_id=evalrun_67e57965b480819094274e3a32235e4c", + "status": "queued", + "model": "gpt-4o-mini", + "name": "gpt-4o-mini", + "created_at": 1743092069, + "result_counts": { + "total": 0, + "errored": 0, + "failed": 0, + "passed": 0 + }, + "per_model_usage": null, + "per_testing_criteria_results": null, + "data_source": { + "type": "completions", + "source": { + "type": "file_content", + "content": [ + { + "item": { + "input": "Tech Company Launches Advanced Artificial Intelligence Platform", + "ground_truth": "Technology" + } + } + ] + }, + "input_messages": { + "type": "template", + "template": [ + { + "type": "message", + "role": "developer", + "content": { + "type": "input_text", + "text": "Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\n\n# Steps\n\n1. Analyze the content of the news headline to understand its primary focus.\n2. Extract the subject matter, identifying any key indicators or keywords.\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\n4. Ensure only one category is selected per headline.\n\n# Output Format\n\nRespond with the chosen category as a single word. For instance: \"Technology\", \"Markets\", \"World\", \"Business\", or \"Sports\".\n\n# Examples\n\n**Input**: \"Apple Unveils New iPhone Model, Featuring Advanced AI Features\" \n**Output**: \"Technology\"\n\n**Input**: \"Global Stocks Mixed as Investors Await Central Bank Decisions\" \n**Output**: \"Markets\"\n\n**Input**: \"War in Ukraine: Latest Updates on Negotiation Status\" \n**Output**: \"World\"\n\n**Input**: \"Microsoft in Talks to Acquire Gaming Company for $2 Billion\" \n**Output**: \"Business\"\n\n**Input**: \"Manchester United Secures Win in Premier League Football Match\" \n**Output**: \"Sports\" \n\n# Notes\n\n- If the headline appears to fit into more than one category, choose the most dominant theme.\n- Keywords or phrases such as \"stocks\", \"company acquisition\", \"match\", or technological brands can be good indicators for classification.\n" + } + }, + { + "type": "message", + "role": "user", + "content": { + "type": "input_text", + "text": "{{item.input}}" + } + } + ] + }, + "model": "gpt-4o-mini", + "sampling_params": { + "seed": 42, + "temperature": 1.0, + "top_p": 1.0, + "max_completions_tokens": 2048 + } + }, + "error": null, + "metadata": {} + } + /evals/{eval_id}/runs/{run_id}: + get: + operationId: getEvalRun + tags: + - Evals + summary: | + Get an evaluation run by ID. + parameters: + - name: eval_id + in: path + required: true + schema: + type: string + description: The ID of the evaluation to retrieve runs for. + - name: run_id + in: path + required: true + schema: + type: string + description: The ID of the run to retrieve. + responses: + "200": + description: The evaluation run + content: + application/json: + schema: + $ref: "#/components/schemas/EvalRun" + x-oaiMeta: + name: Get an eval run + group: evals + returns: The [EvalRun](/docs/api-reference/evals/run-object) object matching the + specified ID. + path: get + examples: + request: + curl: | + curl https://api.openai.com/v1/evals/eval_67abd54d9b0081909a86353f6fb9317a/runs/evalrun_67abd54d60ec8190832b46859da808f7 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" + response: > + { + "object": "eval.run", + "id": "evalrun_67abd54d60ec8190832b46859da808f7", + "eval_id": "eval_67abd54d9b0081909a86353f6fb9317a", + "report_url": "https://platform.openai.com/evaluations/eval_67abd54d9b0081909a86353f6fb9317a?run_id=evalrun_67abd54d60ec8190832b46859da808f7", + "status": "queued", + "model": "gpt-4o-mini", + "name": "gpt-4o-mini", + "created_at": 1743092069, + "result_counts": { + "total": 0, + "errored": 0, + "failed": 0, + "passed": 0 + }, + "per_model_usage": null, + "per_testing_criteria_results": null, + "data_source": { + "type": "completions", + "source": { + "type": "file_content", + "content": [ + { + "item": { + "input": "Tech Company Launches Advanced Artificial Intelligence Platform", + "ground_truth": "Technology" + } + }, + { + "item": { + "input": "Central Bank Increases Interest Rates Amid Inflation Concerns", + "ground_truth": "Markets" + } + }, + { + "item": { + "input": "International Summit Addresses Climate Change Strategies", + "ground_truth": "World" + } + }, + { + "item": { + "input": "Major Retailer Reports Record-Breaking Holiday Sales", + "ground_truth": "Business" + } + }, + { + "item": { + "input": "National Team Qualifies for World Championship Finals", + "ground_truth": "Sports" + } + }, + { + "item": { + "input": "Stock Markets Rally After Positive Economic Data Released", + "ground_truth": "Markets" + } + }, + { + "item": { + "input": "Global Manufacturer Announces Merger with Competitor", + "ground_truth": "Business" + } + }, + { + "item": { + "input": "Breakthrough in Renewable Energy Technology Unveiled", + "ground_truth": "Technology" + } + }, + { + "item": { + "input": "World Leaders Sign Historic Climate Agreement", + "ground_truth": "World" + } + }, + { + "item": { + "input": "Professional Athlete Sets New Record in Championship Event", + "ground_truth": "Sports" + } + }, + { + "item": { + "input": "Financial Institutions Adapt to New Regulatory Requirements", + "ground_truth": "Business" + } + }, + { + "item": { + "input": "Tech Conference Showcases Advances in Artificial Intelligence", + "ground_truth": "Technology" + } + }, + { + "item": { + "input": "Global Markets Respond to Oil Price Fluctuations", + "ground_truth": "Markets" + } + }, + { + "item": { + "input": "International Cooperation Strengthened Through New Treaty", + "ground_truth": "World" + } + }, + { + "item": { + "input": "Sports League Announces Revised Schedule for Upcoming Season", + "ground_truth": "Sports" + } + } + ] + }, + "input_messages": { + "type": "template", + "template": [ + { + "type": "message", + "role": "developer", + "content": { + "type": "input_text", + "text": "Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\n\n# Steps\n\n1. Analyze the content of the news headline to understand its primary focus.\n2. Extract the subject matter, identifying any key indicators or keywords.\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\n4. Ensure only one category is selected per headline.\n\n# Output Format\n\nRespond with the chosen category as a single word. For instance: \"Technology\", \"Markets\", \"World\", \"Business\", or \"Sports\".\n\n# Examples\n\n**Input**: \"Apple Unveils New iPhone Model, Featuring Advanced AI Features\" \n**Output**: \"Technology\"\n\n**Input**: \"Global Stocks Mixed as Investors Await Central Bank Decisions\" \n**Output**: \"Markets\"\n\n**Input**: \"War in Ukraine: Latest Updates on Negotiation Status\" \n**Output**: \"World\"\n\n**Input**: \"Microsoft in Talks to Acquire Gaming Company for $2 Billion\" \n**Output**: \"Business\"\n\n**Input**: \"Manchester United Secures Win in Premier League Football Match\" \n**Output**: \"Sports\" \n\n# Notes\n\n- If the headline appears to fit into more than one category, choose the most dominant theme.\n- Keywords or phrases such as \"stocks\", \"company acquisition\", \"match\", or technological brands can be good indicators for classification.\n" + } + }, + { + "type": "message", + "role": "user", + "content": { + "type": "input_text", + "text": "{{item.input}}" + } + } + ] + }, + "model": "gpt-4o-mini", + "sampling_params": { + "seed": 42, + "temperature": 1.0, + "top_p": 1.0, + "max_completions_tokens": 2048 + } + }, + "error": null, + "metadata": {} + } + post: + operationId: cancelEvalRun + tags: + - Evals + summary: | + Cancel an ongoing evaluation run. + parameters: + - name: eval_id + in: path + required: true + schema: + type: string + description: The ID of the evaluation whose run you want to cancel. + - name: run_id + in: path + required: true + schema: + type: string + description: The ID of the run to cancel. + responses: + "200": + description: The canceled eval run object + content: + application/json: + schema: + $ref: "#/components/schemas/EvalRun" + x-oaiMeta: + name: Cancel eval run + group: evals + returns: The updated [EvalRun](/docs/api-reference/evals/run-object) object + reflecting that the run is canceled. + path: post + examples: + request: + curl: | + curl https://api.openai.com/v1/evals/eval_67abd54d9b0081909a86353f6fb9317a/runs/evalrun_67abd54d60ec8190832b46859da808f7/cancel \ + -X POST \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" + response: > + { + "object": "eval.run", + "id": "evalrun_67abd54d60ec8190832b46859da808f7", + "eval_id": "eval_67abd54d9b0081909a86353f6fb9317a", + "report_url": "https://platform.openai.com/evaluations/eval_67abd54d9b0081909a86353f6fb9317a?run_id=evalrun_67abd54d60ec8190832b46859da808f7", + "status": "canceled", + "model": "gpt-4o-mini", + "name": "gpt-4o-mini", + "created_at": 1743092069, + "result_counts": { + "total": 0, + "errored": 0, + "failed": 0, + "passed": 0 + }, + "per_model_usage": null, + "per_testing_criteria_results": null, + "data_source": { + "type": "completions", + "source": { + "type": "file_content", + "content": [ + { + "item": { + "input": "Tech Company Launches Advanced Artificial Intelligence Platform", + "ground_truth": "Technology" + } + }, + { + "item": { + "input": "Central Bank Increases Interest Rates Amid Inflation Concerns", + "ground_truth": "Markets" + } + }, + { + "item": { + "input": "International Summit Addresses Climate Change Strategies", + "ground_truth": "World" + } + }, + { + "item": { + "input": "Major Retailer Reports Record-Breaking Holiday Sales", + "ground_truth": "Business" + } + }, + { + "item": { + "input": "National Team Qualifies for World Championship Finals", + "ground_truth": "Sports" + } + }, + { + "item": { + "input": "Stock Markets Rally After Positive Economic Data Released", + "ground_truth": "Markets" + } + }, + { + "item": { + "input": "Global Manufacturer Announces Merger with Competitor", + "ground_truth": "Business" + } + }, + { + "item": { + "input": "Breakthrough in Renewable Energy Technology Unveiled", + "ground_truth": "Technology" + } + }, + { + "item": { + "input": "World Leaders Sign Historic Climate Agreement", + "ground_truth": "World" + } + }, + { + "item": { + "input": "Professional Athlete Sets New Record in Championship Event", + "ground_truth": "Sports" + } + }, + { + "item": { + "input": "Financial Institutions Adapt to New Regulatory Requirements", + "ground_truth": "Business" + } + }, + { + "item": { + "input": "Tech Conference Showcases Advances in Artificial Intelligence", + "ground_truth": "Technology" + } + }, + { + "item": { + "input": "Global Markets Respond to Oil Price Fluctuations", + "ground_truth": "Markets" + } + }, + { + "item": { + "input": "International Cooperation Strengthened Through New Treaty", + "ground_truth": "World" + } + }, + { + "item": { + "input": "Sports League Announces Revised Schedule for Upcoming Season", + "ground_truth": "Sports" + } + } + ] + }, + "input_messages": { + "type": "template", + "template": [ + { + "type": "message", + "role": "developer", + "content": { + "type": "input_text", + "text": "Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\n\n# Steps\n\n1. Analyze the content of the news headline to understand its primary focus.\n2. Extract the subject matter, identifying any key indicators or keywords.\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\n4. Ensure only one category is selected per headline.\n\n# Output Format\n\nRespond with the chosen category as a single word. For instance: \"Technology\", \"Markets\", \"World\", \"Business\", or \"Sports\".\n\n# Examples\n\n**Input**: \"Apple Unveils New iPhone Model, Featuring Advanced AI Features\" \n**Output**: \"Technology\"\n\n**Input**: \"Global Stocks Mixed as Investors Await Central Bank Decisions\" \n**Output**: \"Markets\"\n\n**Input**: \"War in Ukraine: Latest Updates on Negotiation Status\" \n**Output**: \"World\"\n\n**Input**: \"Microsoft in Talks to Acquire Gaming Company for $2 Billion\" \n**Output**: \"Business\"\n\n**Input**: \"Manchester United Secures Win in Premier League Football Match\" \n**Output**: \"Sports\" \n\n# Notes\n\n- If the headline appears to fit into more than one category, choose the most dominant theme.\n- Keywords or phrases such as \"stocks\", \"company acquisition\", \"match\", or technological brands can be good indicators for classification.\n" + } + }, + { + "type": "message", + "role": "user", + "content": { + "type": "input_text", + "text": "{{item.input}}" + } + } + ] + }, + "model": "gpt-4o-mini", + "sampling_params": { + "seed": 42, + "temperature": 1.0, + "top_p": 1.0, + "max_completions_tokens": 2048 + } + }, + "error": null, + "metadata": {} + } + delete: + operationId: deleteEvalRun + tags: + - Evals + summary: | + Delete an eval run. + parameters: + - name: eval_id + in: path + required: true + schema: + type: string + description: The ID of the evaluation to delete the run from. + - name: run_id + in: path + required: true + schema: + type: string + description: The ID of the run to delete. + responses: + "200": + description: Successfully deleted the eval run + content: + application/json: + schema: + type: object + properties: + object: + type: string + example: eval.run.deleted + deleted: + type: boolean + example: true + run_id: + type: string + example: evalrun_677469f564d48190807532a852da3afb + "404": + description: Run not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-oaiMeta: + name: Delete eval run + group: evals + returns: An object containing the status of the delete operation. + path: delete + examples: + request: + curl: > + curl + https://api.openai.com/v1/evals/eval_123abc/runs/evalrun_abc456 \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "eval.run.deleted", + "deleted": true, + "run_id": "evalrun_abc456" + } + /evals/{eval_id}/runs/{run_id}/output_items: + get: + operationId: getEvalRunOutputItems + tags: + - Evals + summary: | + Get a list of output items for an evaluation run. + parameters: + - name: eval_id + in: path + required: true + schema: + type: string + description: The ID of the evaluation to retrieve runs for. + - name: run_id + in: path + required: true + schema: + type: string + description: The ID of the run to retrieve output items for. + - name: after + in: query + description: Identifier for the last output item from the previous pagination + request. + required: false + schema: + type: string + - name: limit + in: query + description: Number of output items to retrieve. + required: false + schema: + type: integer + default: 20 + - name: status + in: query + description: > + Filter output items by status. Use `failed` to filter by failed + output + + items or `pass` to filter by passed output items. + required: false + schema: + type: string + enum: + - fail + - pass + - name: order + in: query + description: Sort order for output items by timestamp. Use `asc` for ascending + order or `desc` for descending order. Defaults to `asc`. + required: false + schema: + type: string + enum: + - asc + - desc + default: asc + responses: + "200": + description: A list of output items for the evaluation run + content: + application/json: + schema: + $ref: "#/components/schemas/EvalRunOutputItemList" + x-oaiMeta: + name: Get eval run output items + group: evals + returns: A list of + [EvalRunOutputItem](/docs/api-reference/evals/run-output-item-object) + objects matching the specified ID. + path: get + examples: + request: + curl: | + curl https://api.openai.com/v1/evals/egroup_67abd54d9b0081909a86353f6fb9317a/runs/erun_67abd54d60ec8190832b46859da808f7/output_items \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" + response: > + { + "object": "list", + "data": [ + { + "object": "eval.run.output_item", + "id": "outputitem_67e5796c28e081909917bf79f6e6214d", + "created_at": 1743092076, + "run_id": "evalrun_67abd54d60ec8190832b46859da808f7", + "eval_id": "eval_67abd54d9b0081909a86353f6fb9317a", + "status": "pass", + "datasource_item_id": 5, + "datasource_item": { + "input": "Stock Markets Rally After Positive Economic Data Released", + "ground_truth": "Markets" + }, + "results": [ + { + "name": "String check-a2486074-d803-4445-b431-ad2262e85d47", + "sample": null, + "passed": true, + "score": 1.0 + } + ], + "sample": { + "input": [ + { + "role": "developer", + "content": "Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\n\n# Steps\n\n1. Analyze the content of the news headline to understand its primary focus.\n2. Extract the subject matter, identifying any key indicators or keywords.\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\n4. Ensure only one category is selected per headline.\n\n# Output Format\n\nRespond with the chosen category as a single word. For instance: \"Technology\", \"Markets\", \"World\", \"Business\", or \"Sports\".\n\n# Examples\n\n**Input**: \"Apple Unveils New iPhone Model, Featuring Advanced AI Features\" \n**Output**: \"Technology\"\n\n**Input**: \"Global Stocks Mixed as Investors Await Central Bank Decisions\" \n**Output**: \"Markets\"\n\n**Input**: \"War in Ukraine: Latest Updates on Negotiation Status\" \n**Output**: \"World\"\n\n**Input**: \"Microsoft in Talks to Acquire Gaming Company for $2 Billion\" \n**Output**: \"Business\"\n\n**Input**: \"Manchester United Secures Win in Premier League Football Match\" \n**Output**: \"Sports\" \n\n# Notes\n\n- If the headline appears to fit into more than one category, choose the most dominant theme.\n- Keywords or phrases such as \"stocks\", \"company acquisition\", \"match\", or technological brands can be good indicators for classification.\n", + "tool_call_id": null, + "tool_calls": null, + "function_call": null + }, + { + "role": "user", + "content": "Stock Markets Rally After Positive Economic Data Released", + "tool_call_id": null, + "tool_calls": null, + "function_call": null + } + ], + "output": [ + { + "role": "assistant", + "content": "Markets", + "tool_call_id": null, + "tool_calls": null, + "function_call": null + } + ], + "finish_reason": "stop", + "model": "gpt-4o-mini-2024-07-18", + "usage": { + "total_tokens": 325, + "completion_tokens": 2, + "prompt_tokens": 323, + "cached_tokens": 0 + }, + "error": null, + "temperature": 1.0, + "max_completion_tokens": 2048, + "top_p": 1.0, + "seed": 42 + } + } + ], + "first_id": "outputitem_67e5796c28e081909917bf79f6e6214d", + "last_id": "outputitem_67e5796c28e081909917bf79f6e6214d", + "has_more": true + } + /evals/{eval_id}/runs/{run_id}/output_items/{output_item_id}: + get: + operationId: getEvalRunOutputItem + tags: + - Evals + summary: | + Get an evaluation run output item by ID. + parameters: + - name: eval_id + in: path + required: true + schema: + type: string + description: The ID of the evaluation to retrieve runs for. + - name: run_id + in: path + required: true + schema: + type: string + description: The ID of the run to retrieve. + - name: output_item_id + in: path + required: true + schema: + type: string + description: The ID of the output item to retrieve. + responses: + "200": + description: The evaluation run output item + content: + application/json: + schema: + $ref: "#/components/schemas/EvalRunOutputItem" + x-oaiMeta: + name: Get an output item of an eval run + group: evals + returns: The + [EvalRunOutputItem](/docs/api-reference/evals/run-output-item-object) + object matching the specified ID. + path: get + examples: + request: + curl: | + curl https://api.openai.com/v1/evals/eval_67abd54d9b0081909a86353f6fb9317a/runs/evalrun_67abd54d60ec8190832b46859da808f7/output_items/outputitem_67abd55eb6548190bb580745d5644a33 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" + response: > + { + "object": "eval.run.output_item", + "id": "outputitem_67e5796c28e081909917bf79f6e6214d", + "created_at": 1743092076, + "run_id": "evalrun_67abd54d60ec8190832b46859da808f7", + "eval_id": "eval_67abd54d9b0081909a86353f6fb9317a", + "status": "pass", + "datasource_item_id": 5, + "datasource_item": { + "input": "Stock Markets Rally After Positive Economic Data Released", + "ground_truth": "Markets" + }, + "results": [ + { + "name": "String check-a2486074-d803-4445-b431-ad2262e85d47", + "sample": null, + "passed": true, + "score": 1.0 + } + ], + "sample": { + "input": [ + { + "role": "developer", + "content": "Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\n\n# Steps\n\n1. Analyze the content of the news headline to understand its primary focus.\n2. Extract the subject matter, identifying any key indicators or keywords.\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\n4. Ensure only one category is selected per headline.\n\n# Output Format\n\nRespond with the chosen category as a single word. For instance: \"Technology\", \"Markets\", \"World\", \"Business\", or \"Sports\".\n\n# Examples\n\n**Input**: \"Apple Unveils New iPhone Model, Featuring Advanced AI Features\" \n**Output**: \"Technology\"\n\n**Input**: \"Global Stocks Mixed as Investors Await Central Bank Decisions\" \n**Output**: \"Markets\"\n\n**Input**: \"War in Ukraine: Latest Updates on Negotiation Status\" \n**Output**: \"World\"\n\n**Input**: \"Microsoft in Talks to Acquire Gaming Company for $2 Billion\" \n**Output**: \"Business\"\n\n**Input**: \"Manchester United Secures Win in Premier League Football Match\" \n**Output**: \"Sports\" \n\n# Notes\n\n- If the headline appears to fit into more than one category, choose the most dominant theme.\n- Keywords or phrases such as \"stocks\", \"company acquisition\", \"match\", or technological brands can be good indicators for classification.\n", + "tool_call_id": null, + "tool_calls": null, + "function_call": null + }, + { + "role": "user", + "content": "Stock Markets Rally After Positive Economic Data Released", + "tool_call_id": null, + "tool_calls": null, + "function_call": null + } + ], + "output": [ + { + "role": "assistant", + "content": "Markets", + "tool_call_id": null, + "tool_calls": null, + "function_call": null + } + ], + "finish_reason": "stop", + "model": "gpt-4o-mini-2024-07-18", + "usage": { + "total_tokens": 325, + "completion_tokens": 2, + "prompt_tokens": 323, + "cached_tokens": 0 + }, + "error": null, + "temperature": 1.0, + "max_completion_tokens": 2048, + "top_p": 1.0, + "seed": 42 + } + } + /files: + get: + operationId: listFiles + tags: + - Files + summary: Returns a list of files. + parameters: + - in: query + name: purpose + required: false + schema: + type: string + description: Only return files with the given purpose. + - name: limit + in: query + description: > + A limit on the number of objects to be returned. Limit can range + between 1 and 10,000, and the default is 10,000. + required: false + schema: + type: integer + default: 10000 + - name: order + in: query + description: > + Sort order by the `created_at` timestamp of the objects. `asc` for + ascending order and `desc` for descending order. + schema: + type: string + default: desc + enum: + - asc + - desc + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ListFilesResponse" + x-oaiMeta: + name: List files + group: files + returns: A list of [File](/docs/api-reference/files/object) objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/files \ + -H "Authorization: Bearer $OPENAI_API_KEY" + python: | + from openai import OpenAI + client = OpenAI() + + client.files.list() + node.js: |- + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const list = await openai.files.list(); + + for await (const file of list) { + console.log(file); + } + } + + main(); + response: | + { + "data": [ + { + "id": "file-abc123", + "object": "file", + "bytes": 175, + "created_at": 1613677385, + "filename": "salesOverview.pdf", + "purpose": "assistants", + }, + { + "id": "file-abc123", + "object": "file", + "bytes": 140, + "created_at": 1613779121, + "filename": "puppy.jsonl", + "purpose": "fine-tune", + } + ], + "object": "list" + } + post: + operationId: createFile + tags: + - Files + summary: > + Upload a file that can be used across various endpoints. Individual + files can be up to 512 MB, and the size of all files uploaded by one + organization can be up to 100 GB. + + + The Assistants API supports files up to 2 million tokens and of specific + file types. See the [Assistants Tools guide](/docs/assistants/tools) for + details. + + + The Fine-tuning API only supports `.jsonl` files. The input also has + certain required formats for fine-tuning + [chat](/docs/api-reference/fine-tuning/chat-input) or + [completions](/docs/api-reference/fine-tuning/completions-input) models. + + + The Batch API only supports `.jsonl` files up to 200 MB in size. The + input also has a specific required + [format](/docs/api-reference/batch/request-input). + + + Please [contact us](https://help.openai.com/) if you need to increase + these storage limits. + requestBody: + required: true + content: + multipart/form-data: + schema: + $ref: "#/components/schemas/CreateFileRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/OpenAIFile" + x-oaiMeta: + name: Upload file + group: files + returns: The uploaded [File](/docs/api-reference/files/object) object. + examples: + request: + curl: | + curl https://api.openai.com/v1/files \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -F purpose="fine-tune" \ + -F file="@mydata.jsonl" + python: | + from openai import OpenAI + client = OpenAI() + + client.files.create( + file=open("mydata.jsonl", "rb"), + purpose="fine-tune" + ) + node.js: |- + import fs from "fs"; + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const file = await openai.files.create({ + file: fs.createReadStream("mydata.jsonl"), + purpose: "fine-tune", + }); + + console.log(file); + } + + main(); + response: | + { + "id": "file-abc123", + "object": "file", + "bytes": 120000, + "created_at": 1677610602, + "filename": "mydata.jsonl", + "purpose": "fine-tune", + } + /files/{file_id}: + delete: + operationId: deleteFile + tags: + - Files + summary: Delete a file. + parameters: + - in: path + name: file_id + required: true + schema: + type: string + description: The ID of the file to use for this request. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/DeleteFileResponse" + x-oaiMeta: + name: Delete file + group: files + returns: Deletion status. + examples: + request: + curl: | + curl https://api.openai.com/v1/files/file-abc123 \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_API_KEY" + python: | + from openai import OpenAI + client = OpenAI() + + client.files.delete("file-abc123") + node.js: |- + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const file = await openai.files.del("file-abc123"); + + console.log(file); + } + + main(); + response: | + { + "id": "file-abc123", + "object": "file", + "deleted": true + } + get: + operationId: retrieveFile + tags: + - Files + summary: Returns information about a specific file. + parameters: + - in: path + name: file_id + required: true + schema: + type: string + description: The ID of the file to use for this request. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/OpenAIFile" + x-oaiMeta: + name: Retrieve file + group: files + returns: The [File](/docs/api-reference/files/object) object matching the + specified ID. + examples: + request: + curl: | + curl https://api.openai.com/v1/files/file-abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" + python: | + from openai import OpenAI + client = OpenAI() + + client.files.retrieve("file-abc123") + node.js: |- + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const file = await openai.files.retrieve("file-abc123"); + + console.log(file); + } + + main(); + response: | + { + "id": "file-abc123", + "object": "file", + "bytes": 120000, + "created_at": 1677610602, + "filename": "mydata.jsonl", + "purpose": "fine-tune", + } + /files/{file_id}/content: + get: + operationId: downloadFile + tags: + - Files + summary: Returns the contents of the specified file. + parameters: + - in: path + name: file_id + required: true + schema: + type: string + description: The ID of the file to use for this request. + responses: + "200": + description: OK + content: + application/json: + schema: + type: string + x-oaiMeta: + name: Retrieve file content + group: files + returns: The file content. + examples: + request: + curl: | + curl https://api.openai.com/v1/files/file-abc123/content \ + -H "Authorization: Bearer $OPENAI_API_KEY" > file.jsonl + python: | + from openai import OpenAI + client = OpenAI() + + content = client.files.content("file-abc123") + node.js: | + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const file = await openai.files.content("file-abc123"); + + console.log(file); + } + + main(); + /fine_tuning/checkpoints/{fine_tuned_model_checkpoint}/permissions: + get: + operationId: listFineTuningCheckpointPermissions + tags: + - Fine-tuning + summary: > + **NOTE:** This endpoint requires an [admin API key](../admin-api-keys). + + + Organization owners can use this endpoint to view all permissions for a + fine-tuned model checkpoint. + parameters: + - in: path + name: fine_tuned_model_checkpoint + required: true + schema: + type: string + example: ft-AF1WoRqd3aJAHsqc9NY7iL8F + description: | + The ID of the fine-tuned model checkpoint to get permissions for. + - name: project_id + in: query + description: The ID of the project to get permissions for. + required: false + schema: + type: string + - name: after + in: query + description: Identifier for the last permission ID from the previous pagination + request. + required: false + schema: + type: string + - name: limit + in: query + description: Number of permissions to retrieve. + required: false + schema: + type: integer + default: 10 + - name: order + in: query + description: The order in which to retrieve permissions. + required: false + schema: + type: string + enum: + - ascending + - descending + default: descending + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ListFineTuningCheckpointPermissionResponse" + x-oaiMeta: + name: List checkpoint permissions + group: fine-tuning + returns: A list of fine-tuned model checkpoint [permission + objects](/docs/api-reference/fine-tuning/permission-object) for a + fine-tuned model checkpoint. + examples: + request: + curl: | + curl https://api.openai.com/v1/fine_tuning/checkpoints/ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd/permissions \ + -H "Authorization: Bearer $OPENAI_API_KEY" + response: | + { + "object": "list", + "data": [ + { + "object": "checkpoint.permission", + "id": "cp_zc4Q7MP6XxulcVzj4MZdwsAB", + "created_at": 1721764867, + "project_id": "proj_abGMw1llN8IrBb6SvvY5A1iH" + }, + { + "object": "checkpoint.permission", + "id": "cp_enQCFmOTGj3syEpYVhBRLTSy", + "created_at": 1721764800, + "project_id": "proj_iqGMw1llN8IrBb6SvvY5A1oF" + }, + ], + "first_id": "cp_zc4Q7MP6XxulcVzj4MZdwsAB", + "last_id": "cp_enQCFmOTGj3syEpYVhBRLTSy", + "has_more": false + } + post: + operationId: createFineTuningCheckpointPermission + tags: + - Fine-tuning + summary: > + **NOTE:** Calling this endpoint requires an [admin API + key](../admin-api-keys). + + + This enables organization owners to share fine-tuned models with other + projects in their organization. + parameters: + - in: path + name: fine_tuned_model_checkpoint + required: true + schema: + type: string + example: ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd + description: > + The ID of the fine-tuned model checkpoint to create a permission for. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateFineTuningCheckpointPermissionRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ListFineTuningCheckpointPermissionResponse" + x-oaiMeta: + name: Create checkpoint permissions + group: fine-tuning + returns: A list of fine-tuned model checkpoint [permission + objects](/docs/api-reference/fine-tuning/permission-object) for a + fine-tuned model checkpoint. + examples: + request: + curl: | + curl https://api.openai.com/v1/fine_tuning/checkpoints/ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd/permissions \ + -H "Authorization: Bearer $OPENAI_API_KEY" + -d '{"project_ids": ["proj_abGMw1llN8IrBb6SvvY5A1iH"]}' + response: | + { + "object": "list", + "data": [ + { + "object": "checkpoint.permission", + "id": "cp_zc4Q7MP6XxulcVzj4MZdwsAB", + "created_at": 1721764867, + "project_id": "proj_abGMw1llN8IrBb6SvvY5A1iH" + } + ], + "first_id": "cp_zc4Q7MP6XxulcVzj4MZdwsAB", + "last_id": "cp_zc4Q7MP6XxulcVzj4MZdwsAB", + "has_more": false + } + /fine_tuning/checkpoints/{fine_tuned_model_checkpoint}/permissions/{permission_id}: + delete: + operationId: deleteFineTuningCheckpointPermission + tags: + - Fine-tuning + summary: > + **NOTE:** This endpoint requires an [admin API key](../admin-api-keys). + + + Organization owners can use this endpoint to delete a permission for a + fine-tuned model checkpoint. + parameters: + - in: path + name: fine_tuned_model_checkpoint + required: true + schema: + type: string + example: ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd + description: > + The ID of the fine-tuned model checkpoint to delete a permission for. + - in: path + name: permission_id + required: true + schema: + type: string + example: cp_zc4Q7MP6XxulcVzj4MZdwsAB + description: | + The ID of the fine-tuned model checkpoint permission to delete. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/DeleteFineTuningCheckpointPermissionResponse" + x-oaiMeta: + name: Delete checkpoint permission + group: fine-tuning + returns: The deletion status of the fine-tuned model checkpoint [permission + object](/docs/api-reference/fine-tuning/permission-object). + examples: + request: + curl: | + curl https://api.openai.com/v1/fine_tuning/checkpoints/ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd/permissions/cp_zc4Q7MP6XxulcVzj4MZdwsAB \ + -H "Authorization: Bearer $OPENAI_API_KEY" + response: | + { + "object": "checkpoint.permission", + "id": "cp_zc4Q7MP6XxulcVzj4MZdwsAB", + "deleted": true + } + /fine_tuning/jobs: + post: + operationId: createFineTuningJob + tags: + - Fine-tuning + summary: > + Creates a fine-tuning job which begins the process of creating a new + model from a given dataset. + + + Response includes details of the enqueued job including job status and + the name of the fine-tuned models once complete. + + + [Learn more about fine-tuning](/docs/guides/fine-tuning) + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateFineTuningJobRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/FineTuningJob" + x-oaiMeta: + name: Create fine-tuning job + group: fine-tuning + returns: A [fine-tuning.job](/docs/api-reference/fine-tuning/object) object. + examples: + - title: Default + request: + curl: | + curl https://api.openai.com/v1/fine_tuning/jobs \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "training_file": "file-BK7bzQj3FfZFXr7DbL6xJwfo", + "model": "gpt-4o-mini" + }' + python: | + from openai import OpenAI + client = OpenAI() + + client.fine_tuning.jobs.create( + training_file="file-abc123", + model="gpt-4o-mini" + ) + node.js: | + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const fineTune = await openai.fineTuning.jobs.create({ + training_file: "file-abc123" + }); + + console.log(fineTune); + } + + main(); + response: | + { + "object": "fine_tuning.job", + "id": "ftjob-abc123", + "model": "gpt-4o-mini-2024-07-18", + "created_at": 1721764800, + "fine_tuned_model": null, + "organization_id": "org-123", + "result_files": [], + "status": "queued", + "validation_file": null, + "training_file": "file-abc123", + "method": { + "type": "supervised", + "supervised": { + "hyperparameters": { + "batch_size": "auto", + "learning_rate_multiplier": "auto", + "n_epochs": "auto", + } + } + }, + "metadata": null + } + - title: Epochs + request: + curl: | + curl https://api.openai.com/v1/fine_tuning/jobs \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "training_file": "file-abc123", + "model": "gpt-4o-mini", + "method": { + "type": "supervised", + "supervised": { + "hyperparameters": { + "n_epochs": 2 + } + } + } + }' + python: | + from openai import OpenAI + client = OpenAI() + + client.fine_tuning.jobs.create( + training_file="file-abc123", + model="gpt-4o-mini", + method={ + "type": "supervised", + "supervised": { + "hyperparameters": { + "n_epochs": 2 + } + } + } + ) + node.js: | + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const fineTune = await openai.fineTuning.jobs.create({ + training_file: "file-abc123", + model: "gpt-4o-mini", + method: { + type: "supervised", + supervised: { + hyperparameters: { + n_epochs: 2 + } + } + } + }); + + console.log(fineTune); + } + + main(); + response: | + { + "object": "fine_tuning.job", + "id": "ftjob-abc123", + "model": "gpt-4o-mini-2024-07-18", + "created_at": 1721764800, + "fine_tuned_model": null, + "organization_id": "org-123", + "result_files": [], + "status": "queued", + "validation_file": null, + "training_file": "file-abc123", + "hyperparameters": {"n_epochs": 2}, + "method": { + "type": "supervised", + "supervised": { + "hyperparameters": { + "batch_size": "auto", + "learning_rate_multiplier": "auto", + "n_epochs": 2, + } + } + }, + "metadata": null + } + - title: Validation file + request: + curl: | + curl https://api.openai.com/v1/fine_tuning/jobs \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "training_file": "file-abc123", + "validation_file": "file-abc123", + "model": "gpt-4o-mini" + }' + python: | + from openai import OpenAI + client = OpenAI() + + client.fine_tuning.jobs.create( + training_file="file-abc123", + validation_file="file-def456", + model="gpt-4o-mini" + ) + node.js: | + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const fineTune = await openai.fineTuning.jobs.create({ + training_file: "file-abc123", + validation_file: "file-abc123" + }); + + console.log(fineTune); + } + + main(); + response: | + { + "object": "fine_tuning.job", + "id": "ftjob-abc123", + "model": "gpt-4o-mini-2024-07-18", + "created_at": 1721764800, + "fine_tuned_model": null, + "organization_id": "org-123", + "result_files": [], + "status": "queued", + "validation_file": "file-abc123", + "training_file": "file-abc123", + "method": { + "type": "supervised", + "supervised": { + "hyperparameters": { + "batch_size": "auto", + "learning_rate_multiplier": "auto", + "n_epochs": "auto", + } + } + }, + "metadata": null + } + - title: DPO + request: + curl: | + curl https://api.openai.com/v1/fine_tuning/jobs \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "training_file": "file-abc123", + "validation_file": "file-abc123", + "model": "gpt-4o-mini", + "method": { + "type": "dpo", + "dpo": { + "hyperparameters": { + "beta": 0.1, + } + } + } + }' + response: | + { + "object": "fine_tuning.job", + "id": "ftjob-abc123", + "model": "gpt-4o-mini-2024-07-18", + "created_at": 1721764800, + "fine_tuned_model": null, + "organization_id": "org-123", + "result_files": [], + "status": "queued", + "validation_file": "file-abc123", + "training_file": "file-abc123", + "method": { + "type": "dpo", + "dpo": { + "hyperparameters": { + "beta": 0.1, + "batch_size": "auto", + "learning_rate_multiplier": "auto", + "n_epochs": "auto", + } + } + }, + "metadata": null + } + - title: W&B Integration + request: + curl: | + curl https://api.openai.com/v1/fine_tuning/jobs \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "training_file": "file-abc123", + "validation_file": "file-abc123", + "model": "gpt-4o-mini", + "integrations": [ + { + "type": "wandb", + "wandb": { + "project": "my-wandb-project", + "name": "ft-run-display-name" + "tags": [ + "first-experiment", "v2" + ] + } + } + ] + }' + response: | + { + "object": "fine_tuning.job", + "id": "ftjob-abc123", + "model": "gpt-4o-mini-2024-07-18", + "created_at": 1721764800, + "fine_tuned_model": null, + "organization_id": "org-123", + "result_files": [], + "status": "queued", + "validation_file": "file-abc123", + "training_file": "file-abc123", + "integrations": [ + { + "type": "wandb", + "wandb": { + "project": "my-wandb-project", + "entity": None, + "run_id": "ftjob-abc123" + } + } + ], + "method": { + "type": "supervised", + "supervised": { + "hyperparameters": { + "batch_size": "auto", + "learning_rate_multiplier": "auto", + "n_epochs": "auto", + } + } + }, + "metadata": null + } + get: + operationId: listPaginatedFineTuningJobs + tags: + - Fine-tuning + summary: | + List your organization's fine-tuning jobs + parameters: + - name: after + in: query + description: Identifier for the last job from the previous pagination request. + required: false + schema: + type: string + - name: limit + in: query + description: Number of fine-tuning jobs to retrieve. + required: false + schema: + type: integer + default: 20 + - in: query + name: metadata + required: false + schema: + type: object + nullable: true + additionalProperties: + type: string + style: deepObject + explode: true + description: > + Optional metadata filter. To filter, use the syntax `metadata[k]=v`. + Alternatively, set `metadata=null` to indicate no metadata. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ListPaginatedFineTuningJobsResponse" + x-oaiMeta: + name: List fine-tuning jobs + group: fine-tuning + returns: A list of paginated [fine-tuning + job](/docs/api-reference/fine-tuning/object) objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/fine_tuning/jobs?limit=2&metadata[key]=value \ + -H "Authorization: Bearer $OPENAI_API_KEY" + python: | + from openai import OpenAI + client = OpenAI() + + client.fine_tuning.jobs.list() + node.js: |- + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const list = await openai.fineTuning.jobs.list(); + + for await (const fineTune of list) { + console.log(fineTune); + } + } + + main(); + response: | + { + "object": "list", + "data": [ + { + "object": "fine_tuning.job", + "id": "ftjob-abc123", + "model": "gpt-4o-mini-2024-07-18", + "created_at": 1721764800, + "fine_tuned_model": null, + "organization_id": "org-123", + "result_files": [], + "status": "queued", + "validation_file": null, + "training_file": "file-abc123", + "metadata": { + "key": "value" + } + }, + { ... }, + { ... } + ], "has_more": true + } + /fine_tuning/jobs/{fine_tuning_job_id}: + get: + operationId: retrieveFineTuningJob + tags: + - Fine-tuning + summary: | + Get info about a fine-tuning job. + + [Learn more about fine-tuning](/docs/guides/fine-tuning) + parameters: + - in: path + name: fine_tuning_job_id + required: true + schema: + type: string + example: ft-AF1WoRqd3aJAHsqc9NY7iL8F + description: | + The ID of the fine-tuning job. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/FineTuningJob" + x-oaiMeta: + name: Retrieve fine-tuning job + group: fine-tuning + returns: The [fine-tuning](/docs/api-reference/fine-tuning/object) object with + the given ID. + examples: + request: + curl: | + curl https://api.openai.com/v1/fine_tuning/jobs/ft-AF1WoRqd3aJAHsqc9NY7iL8F \ + -H "Authorization: Bearer $OPENAI_API_KEY" + python: | + from openai import OpenAI + client = OpenAI() + + client.fine_tuning.jobs.retrieve("ftjob-abc123") + node.js: > + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + async function main() { + const fineTune = await openai.fineTuning.jobs.retrieve("ftjob-abc123"); + + console.log(fineTune); + } + + + main(); + response: > + { + "object": "fine_tuning.job", + "id": "ftjob-abc123", + "model": "davinci-002", + "created_at": 1692661014, + "finished_at": 1692661190, + "fine_tuned_model": "ft:davinci-002:my-org:custom_suffix:7q8mpxmy", + "organization_id": "org-123", + "result_files": [ + "file-abc123" + ], + "status": "succeeded", + "validation_file": null, + "training_file": "file-abc123", + "hyperparameters": { + "n_epochs": 4, + "batch_size": 1, + "learning_rate_multiplier": 1.0 + }, + "trained_tokens": 5768, + "integrations": [], + "seed": 0, + "estimated_finish": 0, + "method": { + "type": "supervised", + "supervised": { + "hyperparameters": { + "n_epochs": 4, + "batch_size": 1, + "learning_rate_multiplier": 1.0 + } + } + } + } + /fine_tuning/jobs/{fine_tuning_job_id}/cancel: + post: + operationId: cancelFineTuningJob + tags: + - Fine-tuning + summary: | + Immediately cancel a fine-tune job. + parameters: + - in: path + name: fine_tuning_job_id + required: true + schema: + type: string + example: ft-AF1WoRqd3aJAHsqc9NY7iL8F + description: | + The ID of the fine-tuning job to cancel. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/FineTuningJob" + x-oaiMeta: + name: Cancel fine-tuning + group: fine-tuning + returns: The cancelled [fine-tuning](/docs/api-reference/fine-tuning/object) + object. + examples: + request: + curl: > + curl -X POST + https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/cancel \ + -H "Authorization: Bearer $OPENAI_API_KEY" + python: | + from openai import OpenAI + client = OpenAI() + + client.fine_tuning.jobs.cancel("ftjob-abc123") + node.js: >- + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + async function main() { + const fineTune = await openai.fineTuning.jobs.cancel("ftjob-abc123"); + + console.log(fineTune); + } + + main(); + response: | + { + "object": "fine_tuning.job", + "id": "ftjob-abc123", + "model": "gpt-4o-mini-2024-07-18", + "created_at": 1721764800, + "fine_tuned_model": null, + "organization_id": "org-123", + "result_files": [], + "status": "cancelled", + "validation_file": "file-abc123", + "training_file": "file-abc123" + } + /fine_tuning/jobs/{fine_tuning_job_id}/checkpoints: + get: + operationId: listFineTuningJobCheckpoints + tags: + - Fine-tuning + summary: | + List checkpoints for a fine-tuning job. + parameters: + - in: path + name: fine_tuning_job_id + required: true + schema: + type: string + example: ft-AF1WoRqd3aJAHsqc9NY7iL8F + description: | + The ID of the fine-tuning job to get checkpoints for. + - name: after + in: query + description: Identifier for the last checkpoint ID from the previous pagination + request. + required: false + schema: + type: string + - name: limit + in: query + description: Number of checkpoints to retrieve. + required: false + schema: + type: integer + default: 10 + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ListFineTuningJobCheckpointsResponse" + x-oaiMeta: + name: List fine-tuning checkpoints + group: fine-tuning + returns: A list of fine-tuning [checkpoint + objects](/docs/api-reference/fine-tuning/checkpoint-object) for a + fine-tuning job. + examples: + request: + curl: | + curl https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/checkpoints \ + -H "Authorization: Bearer $OPENAI_API_KEY" + response: > + { + "object": "list" + "data": [ + { + "object": "fine_tuning.job.checkpoint", + "id": "ftckpt_zc4Q7MP6XxulcVzj4MZdwsAB", + "created_at": 1721764867, + "fine_tuned_model_checkpoint": "ft:gpt-4o-mini-2024-07-18:my-org:custom-suffix:96olL566:ckpt-step-2000", + "metrics": { + "full_valid_loss": 0.134, + "full_valid_mean_token_accuracy": 0.874 + }, + "fine_tuning_job_id": "ftjob-abc123", + "step_number": 2000, + }, + { + "object": "fine_tuning.job.checkpoint", + "id": "ftckpt_enQCFmOTGj3syEpYVhBRLTSy", + "created_at": 1721764800, + "fine_tuned_model_checkpoint": "ft:gpt-4o-mini-2024-07-18:my-org:custom-suffix:7q8mpxmy:ckpt-step-1000", + "metrics": { + "full_valid_loss": 0.167, + "full_valid_mean_token_accuracy": 0.781 + }, + "fine_tuning_job_id": "ftjob-abc123", + "step_number": 1000, + }, + ], + "first_id": "ftckpt_zc4Q7MP6XxulcVzj4MZdwsAB", + "last_id": "ftckpt_enQCFmOTGj3syEpYVhBRLTSy", + "has_more": true + } + /fine_tuning/jobs/{fine_tuning_job_id}/events: + get: + operationId: listFineTuningEvents + tags: + - Fine-tuning + summary: | + Get status updates for a fine-tuning job. + parameters: + - in: path + name: fine_tuning_job_id + required: true + schema: + type: string + example: ft-AF1WoRqd3aJAHsqc9NY7iL8F + description: | + The ID of the fine-tuning job to get events for. + - name: after + in: query + description: Identifier for the last event from the previous pagination request. + required: false + schema: + type: string + - name: limit + in: query + description: Number of events to retrieve. + required: false + schema: + type: integer + default: 20 + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ListFineTuningJobEventsResponse" + x-oaiMeta: + name: List fine-tuning events + group: fine-tuning + returns: A list of fine-tuning event objects. + examples: + request: + curl: > + curl + https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/events \ + -H "Authorization: Bearer $OPENAI_API_KEY" + python: | + from openai import OpenAI + client = OpenAI() + + client.fine_tuning.jobs.list_events( + fine_tuning_job_id="ftjob-abc123", + limit=2 + ) + node.js: >- + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + async function main() { + const list = await openai.fineTuning.list_events(id="ftjob-abc123", limit=2); + + for await (const fineTune of list) { + console.log(fineTune); + } + } + + + main(); + response: > + { + "object": "list", + "data": [ + { + "object": "fine_tuning.job.event", + "id": "ft-event-ddTJfwuMVpfLXseO0Am0Gqjm", + "created_at": 1721764800, + "level": "info", + "message": "Fine tuning job successfully completed", + "data": null, + "type": "message" + }, + { + "object": "fine_tuning.job.event", + "id": "ft-event-tyiGuB72evQncpH87xe505Sv", + "created_at": 1721764800, + "level": "info", + "message": "New fine-tuned model created: ft:gpt-4o-mini:openai::7p4lURel", + "data": null, + "type": "message" + } + ], + "has_more": true + } + /images/edits: + post: + operationId: createImageEdit + tags: + - Images + summary: Creates an edited or extended image given one or more source images and + a prompt. This endpoint only supports `gpt-image-1` and `dall-e-2`. + requestBody: + required: true + content: + multipart/form-data: + schema: + $ref: "#/components/schemas/CreateImageEditRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ImagesResponse" + x-oaiMeta: + name: Create image edit + group: images + returns: Returns a list of [image](/docs/api-reference/images/object) objects. + examples: + request: + curl: > + curl -s -D >(grep -i x-request-id >&2) \ + -o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \ + -X POST "https://api.openai.com/v1/images/edits" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -F "model=gpt-image-1" \ + -F "image[]=@body-lotion.png" \ + -F "image[]=@bath-bomb.png" \ + -F "image[]=@incense-kit.png" \ + -F "image[]=@soap.png" \ + -F 'prompt=Create a lovely gift basket with these four items in it' + python: > + import base64 + + from openai import OpenAI + + client = OpenAI() + + + prompt = """ + + Generate a photorealistic image of a gift basket on a white + background + + labeled 'Relax & Unwind' with a ribbon and handwriting-like font, + + containing all the items in the reference pictures. + + """ + + + result = client.images.edit( + model="gpt-image-1", + image=[ + open("body-lotion.png", "rb"), + open("bath-bomb.png", "rb"), + open("incense-kit.png", "rb"), + open("soap.png", "rb"), + ], + prompt=prompt + ) + + + image_base64 = result.data[0].b64_json + + image_bytes = base64.b64decode(image_base64) + + + # Save the image to a file + + with open("gift-basket.png", "wb") as f: + f.write(image_bytes) + node.js: > + import fs from "fs"; + + import OpenAI, { toFile } from "openai"; + + + const client = new OpenAI(); + + + const imageFiles = [ + "bath-bomb.png", + "body-lotion.png", + "incense-kit.png", + "soap.png", + ]; + + + const images = await Promise.all( + imageFiles.map(async (file) => + await toFile(fs.createReadStream(file), null, { + type: "image/png", + }) + ), + ); + + + const rsp = await client.images.edit({ + model: "gpt-image-1", + image: images, + prompt: "Create a lovely gift basket with these four items in it", + }); + + + // Save the image to a file + + const image_base64 = rsp.data[0].b64_json; + + const image_bytes = Buffer.from(image_base64, "base64"); + + fs.writeFileSync("basket.png", image_bytes); + response: | + { + "created": 1713833628, + "data": [ + { + "b64_json": "..." + } + ], + "usage": { + "total_tokens": 100, + "input_tokens": 50, + "output_tokens": 50, + "input_tokens_details": { + "text_tokens": 10, + "image_tokens": 40 + } + } + } + /images/generations: + post: + operationId: createImage + tags: + - Images + summary: | + Creates an image given a prompt. [Learn more](/docs/guides/images). + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateImageRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ImagesResponse" + x-oaiMeta: + name: Create image + group: images + returns: Returns a list of [image](/docs/api-reference/images/object) objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/images/generations \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-image-1", + "prompt": "A cute baby sea otter", + "n": 1, + "size": "1024x1024" + }' + python: | + import base64 + from openai import OpenAI + client = OpenAI() + + img = client.images.generate( + model="gpt-image-1", + prompt="A cute baby sea otter", + n=1, + size="1024x1024" + ) + + image_bytes = base64.b64decode(img.data[0].b64_json) + with open("output.png", "wb") as f: + f.write(image_bytes) + node.js: | + import OpenAI from "openai"; + import { writeFile } from "fs/promises"; + + const client = new OpenAI(); + + const img = await client.images.generate({ + model: "gpt-image-1", + prompt: "A cute baby sea otter", + n: 1, + size: "1024x1024" + }); + + const imageBuffer = Buffer.from(img.data[0].b64_json, "base64"); + await writeFile("output.png", imageBuffer); + response: | + { + "created": 1713833628, + "data": [ + { + "b64_json": "..." + } + ], + "usage": { + "total_tokens": 100, + "input_tokens": 50, + "output_tokens": 50, + "input_tokens_details": { + "text_tokens": 10, + "image_tokens": 40 + } + } + } + /images/variations: + post: + operationId: createImageVariation + tags: + - Images + summary: Creates a variation of a given image. This endpoint only supports + `dall-e-2`. + requestBody: + required: true + content: + multipart/form-data: + schema: + $ref: "#/components/schemas/CreateImageVariationRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ImagesResponse" + x-oaiMeta: + name: Create image variation + group: images + returns: Returns a list of [image](/docs/api-reference/images/object) objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/images/variations \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -F image="@otter.png" \ + -F n=2 \ + -F size="1024x1024" + python: | + from openai import OpenAI + client = OpenAI() + + response = client.images.create_variation( + image=open("image_edit_original.png", "rb"), + n=2, + size="1024x1024" + ) + node.js: |- + import fs from "fs"; + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const image = await openai.images.createVariation({ + image: fs.createReadStream("otter.png"), + }); + + console.log(image.data); + } + main(); + csharp: > + using System; + + + using OpenAI.Images; + + + ImageClient client = new( + model: "dall-e-2", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + GeneratedImage image = + client.GenerateImageVariation(imageFilePath: "otter.png"); + + + Console.WriteLine(image.ImageUri); + response: | + { + "created": 1589478378, + "data": [ + { + "url": "https://..." + }, + { + "url": "https://..." + } + ] + } + /models: + get: + operationId: listModels + tags: + - Models + summary: Lists the currently available models, and provides basic information + about each one such as the owner and availability. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ListModelsResponse" + x-oaiMeta: + name: List models + group: models + returns: A list of [model](/docs/api-reference/models/object) objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/models \ + -H "Authorization: Bearer $OPENAI_API_KEY" + python: | + from openai import OpenAI + client = OpenAI() + + client.models.list() + node.js: |- + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const list = await openai.models.list(); + + for await (const model of list) { + console.log(model); + } + } + main(); + csharp: | + using System; + + using OpenAI.Models; + + OpenAIModelClient client = new( + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + foreach (var model in client.GetModels().Value) + { + Console.WriteLine(model.Id); + } + response: | + { + "object": "list", + "data": [ + { + "id": "model-id-0", + "object": "model", + "created": 1686935002, + "owned_by": "organization-owner" + }, + { + "id": "model-id-1", + "object": "model", + "created": 1686935002, + "owned_by": "organization-owner", + }, + { + "id": "model-id-2", + "object": "model", + "created": 1686935002, + "owned_by": "openai" + }, + ], + "object": "list" + } + /models/{model}: + get: + operationId: retrieveModel + tags: + - Models + summary: Retrieves a model instance, providing basic information about the model + such as the owner and permissioning. + parameters: + - in: path + name: model + required: true + schema: + type: string + example: gpt-4o-mini + description: The ID of the model to use for this request + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/Model" + x-oaiMeta: + name: Retrieve model + group: models + returns: The [model](/docs/api-reference/models/object) object matching the + specified ID. + examples: + request: + curl: | + curl https://api.openai.com/v1/models/VAR_chat_model_id \ + -H "Authorization: Bearer $OPENAI_API_KEY" + python: | + from openai import OpenAI + client = OpenAI() + + client.models.retrieve("VAR_chat_model_id") + node.js: |- + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const model = await openai.models.retrieve("VAR_chat_model_id"); + + console.log(model); + } + + main(); + csharp: | + using System; + using System.ClientModel; + + using OpenAI.Models; + + OpenAIModelClient client = new( + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + ClientResult model = client.GetModel("babbage-002"); + Console.WriteLine(model.Value.Id); + response: | + { + "id": "VAR_chat_model_id", + "object": "model", + "created": 1686935002, + "owned_by": "openai" + } + delete: + operationId: deleteModel + tags: + - Models + summary: Delete a fine-tuned model. You must have the Owner role in your + organization to delete a model. + parameters: + - in: path + name: model + required: true + schema: + type: string + example: ft:gpt-4o-mini:acemeco:suffix:abc123 + description: The model to delete + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/DeleteModelResponse" + x-oaiMeta: + name: Delete a fine-tuned model + group: models + returns: Deletion status. + examples: + request: + curl: | + curl https://api.openai.com/v1/models/ft:gpt-4o-mini:acemeco:suffix:abc123 \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_API_KEY" + python: | + from openai import OpenAI + client = OpenAI() + + client.models.delete("ft:gpt-4o-mini:acemeco:suffix:abc123") + node.js: >- + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + async function main() { + const model = await openai.models.del("ft:gpt-4o-mini:acemeco:suffix:abc123"); + + console.log(model); + } + + main(); + csharp: > + using System; + + using System.ClientModel; + + + using OpenAI.Models; + + + OpenAIModelClient client = new( + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + ClientResult success = + client.DeleteModel("ft:gpt-4o-mini:acemeco:suffix:abc123"); + + Console.WriteLine(success); + response: | + { + "id": "ft:gpt-4o-mini:acemeco:suffix:abc123", + "object": "model", + "deleted": true + } + /moderations: + post: + operationId: createModeration + tags: + - Moderations + summary: | + Classifies if text and/or image inputs are potentially harmful. Learn + more in the [moderation guide](/docs/guides/moderation). + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateModerationRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/CreateModerationResponse" + x-oaiMeta: + name: Create moderation + group: moderations + returns: A [moderation](/docs/api-reference/moderations/object) object. + examples: + - title: Single string + request: + curl: | + curl https://api.openai.com/v1/moderations \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "input": "I want to kill them." + }' + python: > + from openai import OpenAI + + client = OpenAI() + + + moderation = client.moderations.create(input="I want to kill + them.") + + print(moderation) + node.js: > + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + async function main() { + const moderation = await openai.moderations.create({ input: "I want to kill them." }); + + console.log(moderation); + } + + main(); + csharp: > + using System; + + using System.ClientModel; + + + using OpenAI.Moderations; + + + ModerationClient client = new( + model: "omni-moderation-latest", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + ClientResult moderation = + client.ClassifyText("I want to kill them."); + response: | + { + "id": "modr-AB8CjOTu2jiq12hp1AQPfeqFWaORR", + "model": "text-moderation-007", + "results": [ + { + "flagged": true, + "categories": { + "sexual": false, + "hate": false, + "harassment": true, + "self-harm": false, + "sexual/minors": false, + "hate/threatening": false, + "violence/graphic": false, + "self-harm/intent": false, + "self-harm/instructions": false, + "harassment/threatening": true, + "violence": true + }, + "category_scores": { + "sexual": 0.000011726012417057063, + "hate": 0.22706663608551025, + "harassment": 0.5215635299682617, + "self-harm": 2.227119921371923e-6, + "sexual/minors": 7.107352217872176e-8, + "hate/threatening": 0.023547329008579254, + "violence/graphic": 0.00003391829886822961, + "self-harm/intent": 1.646940972932498e-6, + "self-harm/instructions": 1.1198755256458526e-9, + "harassment/threatening": 0.5694745779037476, + "violence": 0.9971134662628174 + } + } + ] + } + - title: Image and text + request: + curl: > + curl https://api.openai.com/v1/moderations \ + -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "omni-moderation-latest", + "input": [ + { "type": "text", "text": "...text to classify goes here..." }, + { + "type": "image_url", + "image_url": { + "url": "https://example.com/image.png" + } + } + ] + }' + python: > + from openai import OpenAI + + client = OpenAI() + + + response = client.moderations.create( + model="omni-moderation-latest", + input=[ + {"type": "text", "text": "...text to classify goes here..."}, + { + "type": "image_url", + "image_url": { + "url": "https://example.com/image.png", + # can also use base64 encoded image URLs + # "url": "data:image/jpeg;base64,abcdefg..." + } + }, + ], + ) + + + print(response) + node.js: > + import OpenAI from "openai"; + + const openai = new OpenAI(); + + + const moderation = await openai.moderations.create({ + model: "omni-moderation-latest", + input: [ + { type: "text", text: "...text to classify goes here..." }, + { + type: "image_url", + image_url: { + url: "https://example.com/image.png" + // can also use base64 encoded image URLs + // url: "data:image/jpeg;base64,abcdefg..." + } + } + ], + }); + + + console.log(moderation); + response: | + { + "id": "modr-0d9740456c391e43c445bf0f010940c7", + "model": "omni-moderation-latest", + "results": [ + { + "flagged": true, + "categories": { + "harassment": true, + "harassment/threatening": true, + "sexual": false, + "hate": false, + "hate/threatening": false, + "illicit": false, + "illicit/violent": false, + "self-harm/intent": false, + "self-harm/instructions": false, + "self-harm": false, + "sexual/minors": false, + "violence": true, + "violence/graphic": true + }, + "category_scores": { + "harassment": 0.8189693396524255, + "harassment/threatening": 0.804985420696006, + "sexual": 1.573112165348997e-6, + "hate": 0.007562942636942845, + "hate/threatening": 0.004208854591835476, + "illicit": 0.030535955153511665, + "illicit/violent": 0.008925306722380033, + "self-harm/intent": 0.00023023930975076432, + "self-harm/instructions": 0.0002293869201073356, + "self-harm": 0.012598046106750154, + "sexual/minors": 2.212566909570261e-8, + "violence": 0.9999992735124786, + "violence/graphic": 0.843064871157054 + }, + "category_applied_input_types": { + "harassment": [ + "text" + ], + "harassment/threatening": [ + "text" + ], + "sexual": [ + "text", + "image" + ], + "hate": [ + "text" + ], + "hate/threatening": [ + "text" + ], + "illicit": [ + "text" + ], + "illicit/violent": [ + "text" + ], + "self-harm/intent": [ + "text", + "image" + ], + "self-harm/instructions": [ + "text", + "image" + ], + "self-harm": [ + "text", + "image" + ], + "sexual/minors": [ + "text" + ], + "violence": [ + "text", + "image" + ], + "violence/graphic": [ + "text", + "image" + ] + } + } + ] + } + /organization/admin_api_keys: + get: + summary: List organization API keys + operationId: admin-api-keys-list + description: Retrieve a paginated list of organization admin API keys. + parameters: + - in: query + name: after + required: false + schema: + type: string + nullable: true + description: Return keys with IDs that come after this ID in the pagination + order. + - in: query + name: order + required: false + schema: + type: string + enum: + - asc + - desc + default: asc + description: Order results by creation time, ascending or descending. + - in: query + name: limit + required: false + schema: + type: integer + default: 20 + description: Maximum number of keys to return. + responses: + "200": + description: A list of organization API keys. + content: + application/json: + schema: + $ref: "#/components/schemas/ApiKeyList" + x-oaiMeta: + name: List all organization and project API keys. + group: administration + returns: A list of admin and project API key objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/admin_api_keys?after=key_abc&limit=20 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "list", + "data": [ + { + "object": "organization.admin_api_key", + "id": "key_abc", + "name": "Main Admin Key", + "redacted_value": "sk-admin...def", + "created_at": 1711471533, + "last_used_at": 1711471534, + "owner": { + "type": "service_account", + "object": "organization.service_account", + "id": "sa_456", + "name": "My Service Account", + "created_at": 1711471533, + "role": "member" + } + } + ], + "first_id": "key_abc", + "last_id": "key_abc", + "has_more": false + } + post: + summary: Create an organization admin API key + operationId: admin-api-keys-create + description: Create a new admin-level API key for the organization. + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - name + properties: + name: + type: string + example: New Admin Key + responses: + "200": + description: The newly created admin API key. + content: + application/json: + schema: + $ref: "#/components/schemas/AdminApiKey" + x-oaiMeta: + name: Create admin API key + group: administration + returns: The created [AdminApiKey](/docs/api-reference/admin-api-keys/object) + object. + examples: + request: + curl: > + curl -X POST https://api.openai.com/v1/organization/admin_api_keys + \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "New Admin Key" + }' + response: | + { + "object": "organization.admin_api_key", + "id": "key_xyz", + "name": "New Admin Key", + "redacted_value": "sk-admin...xyz", + "created_at": 1711471533, + "last_used_at": 1711471534, + "owner": { + "type": "user", + "object": "organization.user", + "id": "user_123", + "name": "John Doe", + "created_at": 1711471533, + "role": "owner" + }, + "value": "sk-admin-1234abcd" + } + /organization/admin_api_keys/{key_id}: + get: + summary: Retrieve a single organization API key + operationId: admin-api-keys-get + description: Get details for a specific organization API key by its ID. + parameters: + - in: path + name: key_id + required: true + schema: + type: string + description: The ID of the API key. + responses: + "200": + description: Details of the requested API key. + content: + application/json: + schema: + $ref: "#/components/schemas/AdminApiKey" + x-oaiMeta: + name: Retrieve admin API key + group: administration + returns: The requested [AdminApiKey](/docs/api-reference/admin-api-keys/object) + object. + examples: + request: + curl: > + curl https://api.openai.com/v1/organization/admin_api_keys/key_abc + \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "organization.admin_api_key", + "id": "key_abc", + "name": "Main Admin Key", + "redacted_value": "sk-admin...xyz", + "created_at": 1711471533, + "last_used_at": 1711471534, + "owner": { + "type": "user", + "object": "organization.user", + "id": "user_123", + "name": "John Doe", + "created_at": 1711471533, + "role": "owner" + } + } + delete: + summary: Delete an organization admin API key + operationId: admin-api-keys-delete + description: Delete the specified admin API key. + parameters: + - in: path + name: key_id + required: true + schema: + type: string + description: The ID of the API key to be deleted. + responses: + "200": + description: Confirmation that the API key was deleted. + content: + application/json: + schema: + type: object + properties: + id: + type: string + example: key_abc + object: + type: string + example: organization.admin_api_key.deleted + deleted: + type: boolean + example: true + x-oaiMeta: + name: Delete admin API key + group: administration + returns: A confirmation object indicating the key was deleted. + examples: + request: + curl: > + curl -X DELETE + https://api.openai.com/v1/organization/admin_api_keys/key_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "id": "key_abc", + "object": "organization.admin_api_key.deleted", + "deleted": true + } + /organization/audit_logs: + get: + summary: List user actions and configuration changes within this organization. + operationId: list-audit-logs + tags: + - Audit Logs + parameters: + - name: effective_at + in: query + description: Return only events whose `effective_at` (Unix seconds) is in this + range. + required: false + schema: + type: object + properties: + gt: + type: integer + description: Return only events whose `effective_at` (Unix seconds) is greater + than this value. + gte: + type: integer + description: Return only events whose `effective_at` (Unix seconds) is greater + than or equal to this value. + lt: + type: integer + description: Return only events whose `effective_at` (Unix seconds) is less than + this value. + lte: + type: integer + description: Return only events whose `effective_at` (Unix seconds) is less than + or equal to this value. + - name: project_ids[] + in: query + description: Return only events for these projects. + required: false + schema: + type: array + items: + type: string + - name: event_types[] + in: query + description: Return only events with a `type` in one of these values. For + example, `project.created`. For all options, see the documentation + for the [audit log object](/docs/api-reference/audit-logs/object). + required: false + schema: + type: array + items: + $ref: "#/components/schemas/AuditLogEventType" + - name: actor_ids[] + in: query + description: Return only events performed by these actors. Can be a user ID, a + service account ID, or an api key tracking ID. + required: false + schema: + type: array + items: + type: string + - name: actor_emails[] + in: query + description: Return only events performed by users with these emails. + required: false + schema: + type: array + items: + type: string + - name: resource_ids[] + in: query + description: Return only events performed on these targets. For example, a + project ID updated. + required: false + schema: + type: array + items: + type: string + - name: limit + in: query + description: > + A limit on the number of objects to be returned. Limit can range + between 1 and 100, and the default is 20. + required: false + schema: + type: integer + default: 20 + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + schema: + type: string + - name: before + in: query + description: > + A cursor for use in pagination. `before` is an object ID that + defines your place in the list. For instance, if you make a list + request and receive 100 objects, starting with obj_foo, your + subsequent call can include before=obj_foo in order to fetch the + previous page of the list. + schema: + type: string + responses: + "200": + description: Audit logs listed successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ListAuditLogsResponse" + x-oaiMeta: + name: List audit logs + group: audit-logs + returns: A list of paginated [Audit Log](/docs/api-reference/audit-logs/object) + objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/audit_logs \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: > + { + "object": "list", + "data": [ + { + "id": "audit_log-xxx_yyyymmdd", + "type": "project.archived", + "effective_at": 1722461446, + "actor": { + "type": "api_key", + "api_key": { + "type": "user", + "user": { + "id": "user-xxx", + "email": "user@example.com" + } + } + }, + "project.archived": { + "id": "proj_abc" + }, + }, + { + "id": "audit_log-yyy__20240101", + "type": "api_key.updated", + "effective_at": 1720804190, + "actor": { + "type": "session", + "session": { + "user": { + "id": "user-xxx", + "email": "user@example.com" + }, + "ip_address": "127.0.0.1", + "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36", + "ja3": "a497151ce4338a12c4418c44d375173e", + "ja4": "q13d0313h3_55b375c5d22e_c7319ce65786", + "ip_address_details": { + "country": "US", + "city": "San Francisco", + "region": "California", + "region_code": "CA", + "asn": "1234", + "latitude": "37.77490", + "longitude": "-122.41940" + } + } + }, + "api_key.updated": { + "id": "key_xxxx", + "data": { + "scopes": ["resource_2.operation_2"] + } + }, + } + ], + "first_id": "audit_log-xxx__20240101", + "last_id": "audit_log_yyy__20240101", + "has_more": true + } + /organization/certificates: + get: + summary: List uploaded certificates for this organization. + operationId: listOrganizationCertificates + tags: + - Certificates + parameters: + - name: limit + in: query + description: > + A limit on the number of objects to be returned. Limit can range + between 1 and 100, and the default is 20. + required: false + schema: + type: integer + default: 20 + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + required: false + schema: + type: string + - name: order + in: query + description: > + Sort order by the `created_at` timestamp of the objects. `asc` for + ascending order and `desc` for descending order. + schema: + type: string + default: desc + enum: + - asc + - desc + responses: + "200": + description: Certificates listed successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ListCertificatesResponse" + x-oaiMeta: + name: List organization certificates + group: administration + returns: A list of [Certificate](/docs/api-reference/certificates/object) + objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/certificates \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" + response: | + { + "object": "list", + "data": [ + { + "object": "organization.certificate", + "id": "cert_abc", + "name": "My Example Certificate", + "active": true, + "created_at": 1234567, + "certificate_details": { + "valid_at": 12345667, + "expires_at": 12345678 + } + }, + ], + "first_id": "cert_abc", + "last_id": "cert_abc", + "has_more": false + } + post: + summary: > + Upload a certificate to the organization. This does **not** + automatically activate the certificate. + + + Organizations can upload up to 50 certificates. + operationId: uploadCertificate + tags: + - Certificates + requestBody: + description: The certificate upload payload. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/UploadCertificateRequest" + responses: + "200": + description: Certificate uploaded successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/Certificate" + x-oaiMeta: + name: Upload certificate + group: administration + returns: A single [Certificate](/docs/api-reference/certificates/object) object. + examples: + request: + curl: > + curl -X POST https://api.openai.com/v1/organization/certificates \ + + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + + -H "Content-Type: application/json" \ + + -d '{ + "name": "My Example Certificate", + "certificate": "-----BEGIN CERTIFICATE-----\\nMIIDeT...\\n-----END CERTIFICATE-----" + }' + response: | + { + "object": "certificate", + "id": "cert_abc", + "name": "My Example Certificate", + "created_at": 1234567, + "certificate_details": { + "valid_at": 12345667, + "expires_at": 12345678 + } + } + /organization/certificates/activate: + post: + summary: > + Activate certificates at the organization level. + + + You can atomically and idempotently activate up to 10 certificates at a + time. + operationId: activateOrganizationCertificates + tags: + - Certificates + requestBody: + description: The certificate activation payload. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ToggleCertificatesRequest" + responses: + "200": + description: Certificates activated successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ListCertificatesResponse" + x-oaiMeta: + name: Activate certificates for organization + group: administration + returns: A list of [Certificate](/docs/api-reference/certificates/object) + objects that were activated. + examples: + request: + curl: > + curl https://api.openai.com/v1/organization/certificates/activate + \ + + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + + -H "Content-Type: application/json" \ + + -d '{ + "data": ["cert_abc", "cert_def"] + }' + response: | + { + "object": "organization.certificate.activation", + "data": [ + { + "object": "organization.certificate", + "id": "cert_abc", + "name": "My Example Certificate", + "active": true, + "created_at": 1234567, + "certificate_details": { + "valid_at": 12345667, + "expires_at": 12345678 + } + }, + { + "object": "organization.certificate", + "id": "cert_def", + "name": "My Example Certificate 2", + "active": true, + "created_at": 1234567, + "certificate_details": { + "valid_at": 12345667, + "expires_at": 12345678 + } + }, + ], + } + /organization/certificates/deactivate: + post: + summary: > + Deactivate certificates at the organization level. + + + You can atomically and idempotently deactivate up to 10 certificates at + a time. + operationId: deactivateOrganizationCertificates + tags: + - Certificates + requestBody: + description: The certificate deactivation payload. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ToggleCertificatesRequest" + responses: + "200": + description: Certificates deactivated successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ListCertificatesResponse" + x-oaiMeta: + name: Deactivate certificates for organization + group: administration + returns: A list of [Certificate](/docs/api-reference/certificates/object) + objects that were deactivated. + examples: + request: + curl: > + curl + https://api.openai.com/v1/organization/certificates/deactivate \ + + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + + -H "Content-Type: application/json" \ + + -d '{ + "data": ["cert_abc", "cert_def"] + }' + response: | + { + "object": "organization.certificate.deactivation", + "data": [ + { + "object": "organization.certificate", + "id": "cert_abc", + "name": "My Example Certificate", + "active": false, + "created_at": 1234567, + "certificate_details": { + "valid_at": 12345667, + "expires_at": 12345678 + } + }, + { + "object": "organization.certificate", + "id": "cert_def", + "name": "My Example Certificate 2", + "active": false, + "created_at": 1234567, + "certificate_details": { + "valid_at": 12345667, + "expires_at": 12345678 + } + }, + ], + } + /organization/certificates/{certificate_id}: + get: + summary: | + Get a certificate that has been uploaded to the organization. + + You can get a certificate regardless of whether it is active or not. + operationId: getCertificate + tags: + - Certificates + parameters: + - name: cert_id + in: path + description: Unique ID of the certificate to retrieve. + required: true + schema: + type: string + - name: include + in: query + description: A list of additional fields to include in the response. Currently + the only supported value is `content` to fetch the PEM content of + the certificate. + required: false + schema: + type: array + items: + type: string + enum: + - content + responses: + "200": + description: Certificate retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/Certificate" + x-oaiMeta: + name: Get certificate + group: administration + returns: A single [Certificate](/docs/api-reference/certificates/object) object. + examples: + request: + curl: | + curl "https://api.openai.com/v1/organization/certificates/cert_abc?include[]=content" \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" + response: > + { + "object": "certificate", + "id": "cert_abc", + "name": "My Example Certificate", + "created_at": 1234567, + "certificate_details": { + "valid_at": 1234567, + "expires_at": 12345678, + "content": "-----BEGIN CERTIFICATE-----MIIDeT...-----END CERTIFICATE-----" + } + } + post: + summary: | + Modify a certificate. Note that only the name can be modified. + operationId: modifyCertificate + tags: + - Certificates + requestBody: + description: The certificate modification payload. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ModifyCertificateRequest" + responses: + "200": + description: Certificate modified successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/Certificate" + x-oaiMeta: + name: Modify certificate + group: administration + returns: The updated [Certificate](/docs/api-reference/certificates/object) + object. + examples: + request: + curl: > + curl -X POST + https://api.openai.com/v1/organization/certificates/cert_abc \ + + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + + -H "Content-Type: application/json" \ + + -d '{ + "name": "Renamed Certificate" + }' + response: | + { + "object": "certificate", + "id": "cert_abc", + "name": "Renamed Certificate", + "created_at": 1234567, + "certificate_details": { + "valid_at": 12345667, + "expires_at": 12345678 + } + } + delete: + summary: | + Delete a certificate from the organization. + + The certificate must be inactive for the organization and all projects. + operationId: deleteCertificate + tags: + - Certificates + responses: + "200": + description: Certificate deleted successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/DeleteCertificateResponse" + x-oaiMeta: + name: Delete certificate + group: administration + returns: A confirmation object indicating the certificate was deleted. + examples: + request: + curl: > + curl -X DELETE + https://api.openai.com/v1/organization/certificates/cert_abc \ + + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" + response: | + { + "object": "certificate.deleted", + "id": "cert_abc" + } + /organization/costs: + get: + summary: Get costs details for the organization. + operationId: usage-costs + tags: + - Usage + parameters: + - name: start_time + in: query + description: Start time (Unix seconds) of the query time range, inclusive. + required: true + schema: + type: integer + - name: end_time + in: query + description: End time (Unix seconds) of the query time range, exclusive. + required: false + schema: + type: integer + - name: bucket_width + in: query + description: Width of each time bucket in response. Currently only `1d` is + supported, default to `1d`. + required: false + schema: + type: string + enum: + - 1d + default: 1d + - name: project_ids + in: query + description: Return only costs for these projects. + required: false + schema: + type: array + items: + type: string + - name: group_by + in: query + description: Group the costs by the specified fields. Support fields include + `project_id`, `line_item` and any combination of them. + required: false + schema: + type: array + items: + type: string + enum: + - project_id + - line_item + - name: limit + in: query + description: > + A limit on the number of buckets to be returned. Limit can range + between 1 and 180, and the default is 7. + required: false + schema: + type: integer + default: 7 + - name: page + in: query + description: A cursor for use in pagination. Corresponding to the `next_page` + field from the previous response. + schema: + type: string + responses: + "200": + description: Costs data retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/UsageResponse" + x-oaiMeta: + name: Costs + group: usage-costs + returns: A list of paginated, time bucketed + [Costs](/docs/api-reference/usage/costs_object) objects. + examples: + request: + curl: | + curl "https://api.openai.com/v1/organization/costs?start_time=1730419200&limit=1" \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "organization.costs.result", + "amount": { + "value": 0.06, + "currency": "usd" + }, + "line_item": null, + "project_id": null + } + ] + } + ], + "has_more": false, + "next_page": null + } + /organization/invites: + get: + summary: Returns a list of invites in the organization. + operationId: list-invites + tags: + - Invites + parameters: + - name: limit + in: query + description: > + A limit on the number of objects to be returned. Limit can range + between 1 and 100, and the default is 20. + required: false + schema: + type: integer + default: 20 + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + required: false + schema: + type: string + responses: + "200": + description: Invites listed successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/InviteListResponse" + x-oaiMeta: + name: List invites + group: administration + returns: A list of [Invite](/docs/api-reference/invite/object) objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/invites?after=invite-abc&limit=20 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "list", + "data": [ + { + "object": "organization.invite", + "id": "invite-abc", + "email": "user@example.com", + "role": "owner", + "status": "accepted", + "invited_at": 1711471533, + "expires_at": 1711471533, + "accepted_at": 1711471533 + } + ], + "first_id": "invite-abc", + "last_id": "invite-abc", + "has_more": false + } + post: + summary: Create an invite for a user to the organization. The invite must be + accepted by the user before they have access to the organization. + operationId: inviteUser + tags: + - Invites + requestBody: + description: The invite request payload. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/InviteRequest" + responses: + "200": + description: User invited successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/Invite" + x-oaiMeta: + name: Create invite + group: administration + returns: The created [Invite](/docs/api-reference/invite/object) object. + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/organization/invites \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "email": "anotheruser@example.com", + "role": "reader", + "projects": [ + { + "id": "project-xyz", + "role": "member" + }, + { + "id": "project-abc", + "role": "owner" + } + ] + }' + response: | + { + "object": "organization.invite", + "id": "invite-def", + "email": "anotheruser@example.com", + "role": "reader", + "status": "pending", + "invited_at": 1711471533, + "expires_at": 1711471533, + "accepted_at": null, + "projects": [ + { + "id": "project-xyz", + "role": "member" + }, + { + "id": "project-abc", + "role": "owner" + } + ] + } + /organization/invites/{invite_id}: + get: + summary: Retrieves an invite. + operationId: retrieve-invite + tags: + - Invites + parameters: + - in: path + name: invite_id + required: true + schema: + type: string + description: The ID of the invite to retrieve. + responses: + "200": + description: Invite retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/Invite" + x-oaiMeta: + name: Retrieve invite + group: administration + returns: The [Invite](/docs/api-reference/invite/object) object matching the + specified ID. + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/invites/invite-abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "organization.invite", + "id": "invite-abc", + "email": "user@example.com", + "role": "owner", + "status": "accepted", + "invited_at": 1711471533, + "expires_at": 1711471533, + "accepted_at": 1711471533 + } + delete: + summary: Delete an invite. If the invite has already been accepted, it cannot be + deleted. + operationId: delete-invite + tags: + - Invites + parameters: + - in: path + name: invite_id + required: true + schema: + type: string + description: The ID of the invite to delete. + responses: + "200": + description: Invite deleted successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/InviteDeleteResponse" + x-oaiMeta: + name: Delete invite + group: administration + returns: Confirmation that the invite has been deleted + examples: + request: + curl: > + curl -X DELETE + https://api.openai.com/v1/organization/invites/invite-abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "organization.invite.deleted", + "id": "invite-abc", + "deleted": true + } + /organization/projects: + get: + summary: Returns a list of projects. + operationId: list-projects + tags: + - Projects + parameters: + - name: limit + in: query + description: > + A limit on the number of objects to be returned. Limit can range + between 1 and 100, and the default is 20. + required: false + schema: + type: integer + default: 20 + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + required: false + schema: + type: string + - name: include_archived + in: query + schema: + type: boolean + default: false + description: If `true` returns all projects including those that have been + `archived`. Archived projects are not included by default. + responses: + "200": + description: Projects listed successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectListResponse" + x-oaiMeta: + name: List projects + group: administration + returns: A list of [Project](/docs/api-reference/projects/object) objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/projects?after=proj_abc&limit=20&include_archived=false \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "list", + "data": [ + { + "id": "proj_abc", + "object": "organization.project", + "name": "Project example", + "created_at": 1711471533, + "archived_at": null, + "status": "active" + } + ], + "first_id": "proj-abc", + "last_id": "proj-xyz", + "has_more": false + } + post: + summary: Create a new project in the organization. Projects can be created and + archived, but cannot be deleted. + operationId: create-project + tags: + - Projects + requestBody: + description: The project create request payload. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectCreateRequest" + responses: + "200": + description: Project created successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/Project" + x-oaiMeta: + name: Create project + group: administration + returns: The created [Project](/docs/api-reference/projects/object) object. + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/organization/projects \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Project ABC" + }' + response: | + { + "id": "proj_abc", + "object": "organization.project", + "name": "Project ABC", + "created_at": 1711471533, + "archived_at": null, + "status": "active" + } + /organization/projects/{project_id}: + get: + summary: Retrieves a project. + operationId: retrieve-project + tags: + - Projects + parameters: + - name: project_id + in: path + description: The ID of the project. + required: true + schema: + type: string + responses: + "200": + description: Project retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/Project" + x-oaiMeta: + name: Retrieve project + group: administration + description: Retrieve a project. + returns: The [Project](/docs/api-reference/projects/object) object matching the + specified ID. + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/projects/proj_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "id": "proj_abc", + "object": "organization.project", + "name": "Project example", + "created_at": 1711471533, + "archived_at": null, + "status": "active" + } + post: + summary: Modifies a project in the organization. + operationId: modify-project + tags: + - Projects + parameters: + - name: project_id + in: path + description: The ID of the project. + required: true + schema: + type: string + requestBody: + description: The project update request payload. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectUpdateRequest" + responses: + "200": + description: Project updated successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/Project" + "400": + description: Error response when updating the default project. + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + x-oaiMeta: + name: Modify project + group: administration + returns: The updated [Project](/docs/api-reference/projects/object) object. + examples: + request: + curl: > + curl -X POST + https://api.openai.com/v1/organization/projects/proj_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Project DEF" + }' + /organization/projects/{project_id}/api_keys: + get: + summary: Returns a list of API keys in the project. + operationId: list-project-api-keys + tags: + - Projects + parameters: + - name: project_id + in: path + description: The ID of the project. + required: true + schema: + type: string + - name: limit + in: query + description: > + A limit on the number of objects to be returned. Limit can range + between 1 and 100, and the default is 20. + required: false + schema: + type: integer + default: 20 + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + required: false + schema: + type: string + responses: + "200": + description: Project API keys listed successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectApiKeyListResponse" + x-oaiMeta: + name: List project API keys + group: administration + returns: A list of [ProjectApiKey](/docs/api-reference/project-api-keys/object) + objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/projects/proj_abc/api_keys?after=key_abc&limit=20 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "list", + "data": [ + { + "object": "organization.project.api_key", + "redacted_value": "sk-abc...def", + "name": "My API Key", + "created_at": 1711471533, + "last_used_at": 1711471534, + "id": "key_abc", + "owner": { + "type": "user", + "user": { + "object": "organization.project.user", + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "added_at": 1711471533 + } + } + } + ], + "first_id": "key_abc", + "last_id": "key_xyz", + "has_more": false + } + /organization/projects/{project_id}/api_keys/{key_id}: + get: + summary: Retrieves an API key in the project. + operationId: retrieve-project-api-key + tags: + - Projects + parameters: + - name: project_id + in: path + description: The ID of the project. + required: true + schema: + type: string + - name: key_id + in: path + description: The ID of the API key. + required: true + schema: + type: string + responses: + "200": + description: Project API key retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectApiKey" + x-oaiMeta: + name: Retrieve project API key + group: administration + returns: The [ProjectApiKey](/docs/api-reference/project-api-keys/object) object + matching the specified ID. + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/projects/proj_abc/api_keys/key_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "organization.project.api_key", + "redacted_value": "sk-abc...def", + "name": "My API Key", + "created_at": 1711471533, + "last_used_at": 1711471534, + "id": "key_abc", + "owner": { + "type": "user", + "user": { + "object": "organization.project.user", + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "added_at": 1711471533 + } + } + } + delete: + summary: Deletes an API key from the project. + operationId: delete-project-api-key + tags: + - Projects + parameters: + - name: project_id + in: path + description: The ID of the project. + required: true + schema: + type: string + - name: key_id + in: path + description: The ID of the API key. + required: true + schema: + type: string + responses: + "200": + description: Project API key deleted successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectApiKeyDeleteResponse" + "400": + description: Error response for various conditions. + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + x-oaiMeta: + name: Delete project API key + group: administration + returns: Confirmation of the key's deletion or an error if the key belonged to a + service account + examples: + request: + curl: | + curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/api_keys/key_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "organization.project.api_key.deleted", + "id": "key_abc", + "deleted": true + } + /organization/projects/{project_id}/archive: + post: + summary: Archives a project in the organization. Archived projects cannot be + used or updated. + operationId: archive-project + tags: + - Projects + parameters: + - name: project_id + in: path + description: The ID of the project. + required: true + schema: + type: string + responses: + "200": + description: Project archived successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/Project" + x-oaiMeta: + name: Archive project + group: administration + returns: The archived [Project](/docs/api-reference/projects/object) object. + examples: + request: + curl: > + curl -X POST + https://api.openai.com/v1/organization/projects/proj_abc/archive \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "id": "proj_abc", + "object": "organization.project", + "name": "Project DEF", + "created_at": 1711471533, + "archived_at": 1711471533, + "status": "archived" + } + /organization/projects/{project_id}/certificates: + get: + summary: List certificates for this project. + operationId: listProjectCertificates + tags: + - Certificates + parameters: + - name: limit + in: query + description: > + A limit on the number of objects to be returned. Limit can range + between 1 and 100, and the default is 20. + required: false + schema: + type: integer + default: 20 + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + required: false + schema: + type: string + - name: order + in: query + description: > + Sort order by the `created_at` timestamp of the objects. `asc` for + ascending order and `desc` for descending order. + schema: + type: string + default: desc + enum: + - asc + - desc + responses: + "200": + description: Certificates listed successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ListCertificatesResponse" + x-oaiMeta: + name: List project certificates + group: administration + returns: A list of [Certificate](/docs/api-reference/certificates/object) + objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/projects/proj_abc/certificates \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" + response: | + { + "object": "list", + "data": [ + { + "object": "organization.project.certificate", + "id": "cert_abc", + "name": "My Example Certificate", + "active": true, + "created_at": 1234567, + "certificate_details": { + "valid_at": 12345667, + "expires_at": 12345678 + } + }, + ], + "first_id": "cert_abc", + "last_id": "cert_abc", + "has_more": false + } + /organization/projects/{project_id}/certificates/activate: + post: + summary: > + Activate certificates at the project level. + + + You can atomically and idempotently activate up to 10 certificates at a + time. + operationId: activateProjectCertificates + tags: + - Certificates + requestBody: + description: The certificate activation payload. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ToggleCertificatesRequest" + responses: + "200": + description: Certificates activated successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ListCertificatesResponse" + x-oaiMeta: + name: Activate certificates for project + group: administration + returns: A list of [Certificate](/docs/api-reference/certificates/object) + objects that were activated. + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/projects/proj_abc/certificates/activate \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "data": ["cert_abc", "cert_def"] + }' + response: | + { + "object": "organization.project.certificate.activation", + "data": [ + { + "object": "organization.project.certificate", + "id": "cert_abc", + "name": "My Example Certificate", + "active": true, + "created_at": 1234567, + "certificate_details": { + "valid_at": 12345667, + "expires_at": 12345678 + } + }, + { + "object": "organization.project.certificate", + "id": "cert_def", + "name": "My Example Certificate 2", + "active": true, + "created_at": 1234567, + "certificate_details": { + "valid_at": 12345667, + "expires_at": 12345678 + } + }, + ], + } + /organization/projects/{project_id}/certificates/deactivate: + post: + summary: > + Deactivate certificates at the project level. + + + You can atomically and idempotently deactivate up to 10 certificates at + a time. + operationId: deactivateProjectCertificates + tags: + - Certificates + requestBody: + description: The certificate deactivation payload. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ToggleCertificatesRequest" + responses: + "200": + description: Certificates deactivated successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ListCertificatesResponse" + x-oaiMeta: + name: Deactivate certificates for project + group: administration + returns: A list of [Certificate](/docs/api-reference/certificates/object) + objects that were deactivated. + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/projects/proj_abc/certificates/deactivate \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "data": ["cert_abc", "cert_def"] + }' + response: | + { + "object": "organization.project.certificate.deactivation", + "data": [ + { + "object": "organization.project.certificate", + "id": "cert_abc", + "name": "My Example Certificate", + "active": false, + "created_at": 1234567, + "certificate_details": { + "valid_at": 12345667, + "expires_at": 12345678 + } + }, + { + "object": "organization.project.certificate", + "id": "cert_def", + "name": "My Example Certificate 2", + "active": false, + "created_at": 1234567, + "certificate_details": { + "valid_at": 12345667, + "expires_at": 12345678 + } + }, + ], + } + /organization/projects/{project_id}/rate_limits: + get: + summary: Returns the rate limits per model for a project. + operationId: list-project-rate-limits + tags: + - Projects + parameters: + - name: project_id + in: path + description: The ID of the project. + required: true + schema: + type: string + - name: limit + in: query + description: | + A limit on the number of objects to be returned. The default is 100. + required: false + schema: + type: integer + default: 100 + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + required: false + schema: + type: string + - name: before + in: query + description: > + A cursor for use in pagination. `before` is an object ID that + defines your place in the list. For instance, if you make a list + request and receive 100 objects, beginning with obj_foo, your + subsequent call can include before=obj_foo in order to fetch the + previous page of the list. + required: false + schema: + type: string + responses: + "200": + description: Project rate limits listed successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectRateLimitListResponse" + x-oaiMeta: + name: List project rate limits + group: administration + returns: A list of + [ProjectRateLimit](/docs/api-reference/project-rate-limits/object) + objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/projects/proj_abc/rate_limits?after=rl_xxx&limit=20 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "list", + "data": [ + { + "object": "project.rate_limit", + "id": "rl-ada", + "model": "ada", + "max_requests_per_1_minute": 600, + "max_tokens_per_1_minute": 150000, + "max_images_per_1_minute": 10 + } + ], + "first_id": "rl-ada", + "last_id": "rl-ada", + "has_more": false + } + error_response: | + { + "code": 404, + "message": "The project {project_id} was not found" + } + /organization/projects/{project_id}/rate_limits/{rate_limit_id}: + post: + summary: Updates a project rate limit. + operationId: update-project-rate-limits + tags: + - Projects + parameters: + - name: project_id + in: path + description: The ID of the project. + required: true + schema: + type: string + - name: rate_limit_id + in: path + description: The ID of the rate limit. + required: true + schema: + type: string + requestBody: + description: The project rate limit update request payload. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectRateLimitUpdateRequest" + responses: + "200": + description: Project rate limit updated successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectRateLimit" + "400": + description: Error response for various conditions. + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + x-oaiMeta: + name: Modify project rate limit + group: administration + returns: The updated + [ProjectRateLimit](/docs/api-reference/project-rate-limits/object) + object. + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/rate_limits/rl_xxx \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "max_requests_per_1_minute": 500 + }' + response: | + { + "object": "project.rate_limit", + "id": "rl-ada", + "model": "ada", + "max_requests_per_1_minute": 600, + "max_tokens_per_1_minute": 150000, + "max_images_per_1_minute": 10 + } + error_response: | + { + "code": 404, + "message": "The project {project_id} was not found" + } + /organization/projects/{project_id}/service_accounts: + get: + summary: Returns a list of service accounts in the project. + operationId: list-project-service-accounts + tags: + - Projects + parameters: + - name: project_id + in: path + description: The ID of the project. + required: true + schema: + type: string + - name: limit + in: query + description: > + A limit on the number of objects to be returned. Limit can range + between 1 and 100, and the default is 20. + required: false + schema: + type: integer + default: 20 + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + required: false + schema: + type: string + responses: + "200": + description: Project service accounts listed successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectServiceAccountListResponse" + "400": + description: Error response when project is archived. + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + x-oaiMeta: + name: List project service accounts + group: administration + returns: A list of + [ProjectServiceAccount](/docs/api-reference/project-service-accounts/object) + objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/projects/proj_abc/service_accounts?after=custom_id&limit=20 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "list", + "data": [ + { + "object": "organization.project.service_account", + "id": "svc_acct_abc", + "name": "Service Account", + "role": "owner", + "created_at": 1711471533 + } + ], + "first_id": "svc_acct_abc", + "last_id": "svc_acct_xyz", + "has_more": false + } + post: + summary: Creates a new service account in the project. This also returns an + unredacted API key for the service account. + operationId: create-project-service-account + tags: + - Projects + parameters: + - name: project_id + in: path + description: The ID of the project. + required: true + schema: + type: string + requestBody: + description: The project service account create request payload. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectServiceAccountCreateRequest" + responses: + "200": + description: Project service account created successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectServiceAccountCreateResponse" + "400": + description: Error response when project is archived. + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + x-oaiMeta: + name: Create project service account + group: administration + returns: The created + [ProjectServiceAccount](/docs/api-reference/project-service-accounts/object) + object. + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/service_accounts \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Production App" + }' + response: | + { + "object": "organization.project.service_account", + "id": "svc_acct_abc", + "name": "Production App", + "role": "member", + "created_at": 1711471533, + "api_key": { + "object": "organization.project.service_account.api_key", + "value": "sk-abcdefghijklmnop123", + "name": "Secret Key", + "created_at": 1711471533, + "id": "key_abc" + } + } + /organization/projects/{project_id}/service_accounts/{service_account_id}: + get: + summary: Retrieves a service account in the project. + operationId: retrieve-project-service-account + tags: + - Projects + parameters: + - name: project_id + in: path + description: The ID of the project. + required: true + schema: + type: string + - name: service_account_id + in: path + description: The ID of the service account. + required: true + schema: + type: string + responses: + "200": + description: Project service account retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectServiceAccount" + x-oaiMeta: + name: Retrieve project service account + group: administration + returns: The + [ProjectServiceAccount](/docs/api-reference/project-service-accounts/object) + object matching the specified ID. + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/projects/proj_abc/service_accounts/svc_acct_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "organization.project.service_account", + "id": "svc_acct_abc", + "name": "Service Account", + "role": "owner", + "created_at": 1711471533 + } + delete: + summary: Deletes a service account from the project. + operationId: delete-project-service-account + tags: + - Projects + parameters: + - name: project_id + in: path + description: The ID of the project. + required: true + schema: + type: string + - name: service_account_id + in: path + description: The ID of the service account. + required: true + schema: + type: string + responses: + "200": + description: Project service account deleted successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectServiceAccountDeleteResponse" + x-oaiMeta: + name: Delete project service account + group: administration + returns: Confirmation of service account being deleted, or an error in case of + an archived project, which has no service accounts + examples: + request: + curl: | + curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/service_accounts/svc_acct_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "organization.project.service_account.deleted", + "id": "svc_acct_abc", + "deleted": true + } + /organization/projects/{project_id}/users: + get: + summary: Returns a list of users in the project. + operationId: list-project-users + tags: + - Projects + parameters: + - name: project_id + in: path + description: The ID of the project. + required: true + schema: + type: string + - name: limit + in: query + description: > + A limit on the number of objects to be returned. Limit can range + between 1 and 100, and the default is 20. + required: false + schema: + type: integer + default: 20 + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + required: false + schema: + type: string + responses: + "200": + description: Project users listed successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectUserListResponse" + "400": + description: Error response when project is archived. + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + x-oaiMeta: + name: List project users + group: administration + returns: A list of [ProjectUser](/docs/api-reference/project-users/object) + objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/projects/proj_abc/users?after=user_abc&limit=20 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "list", + "data": [ + { + "object": "organization.project.user", + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "added_at": 1711471533 + } + ], + "first_id": "user-abc", + "last_id": "user-xyz", + "has_more": false + } + post: + summary: Adds a user to the project. Users must already be members of the + organization to be added to a project. + operationId: create-project-user + parameters: + - name: project_id + in: path + description: The ID of the project. + required: true + schema: + type: string + tags: + - Projects + requestBody: + description: The project user create request payload. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectUserCreateRequest" + responses: + "200": + description: User added to project successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectUser" + "400": + description: Error response for various conditions. + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + x-oaiMeta: + name: Create project user + group: administration + returns: The created [ProjectUser](/docs/api-reference/project-users/object) + object. + examples: + request: + curl: > + curl -X POST + https://api.openai.com/v1/organization/projects/proj_abc/users \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "user_id": "user_abc", + "role": "member" + }' + response: | + { + "object": "organization.project.user", + "id": "user_abc", + "email": "user@example.com", + "role": "owner", + "added_at": 1711471533 + } + /organization/projects/{project_id}/users/{user_id}: + get: + summary: Retrieves a user in the project. + operationId: retrieve-project-user + tags: + - Projects + parameters: + - name: project_id + in: path + description: The ID of the project. + required: true + schema: + type: string + - name: user_id + in: path + description: The ID of the user. + required: true + schema: + type: string + responses: + "200": + description: Project user retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectUser" + x-oaiMeta: + name: Retrieve project user + group: administration + returns: The [ProjectUser](/docs/api-reference/project-users/object) object + matching the specified ID. + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "organization.project.user", + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "added_at": 1711471533 + } + post: + summary: Modifies a user's role in the project. + operationId: modify-project-user + tags: + - Projects + parameters: + - name: project_id + in: path + description: The ID of the project. + required: true + schema: + type: string + - name: user_id + in: path + description: The ID of the user. + required: true + schema: + type: string + requestBody: + description: The project user update request payload. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectUserUpdateRequest" + responses: + "200": + description: Project user's role updated successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectUser" + "400": + description: Error response for various conditions. + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + x-oaiMeta: + name: Modify project user + group: administration + returns: The updated [ProjectUser](/docs/api-reference/project-users/object) + object. + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "role": "owner" + }' + response: | + { + "object": "organization.project.user", + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "added_at": 1711471533 + } + delete: + summary: Deletes a user from the project. + operationId: delete-project-user + tags: + - Projects + parameters: + - name: project_id + in: path + description: The ID of the project. + required: true + schema: + type: string + - name: user_id + in: path + description: The ID of the user. + required: true + schema: + type: string + responses: + "200": + description: Project user deleted successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectUserDeleteResponse" + "400": + description: Error response for various conditions. + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + x-oaiMeta: + name: Delete project user + group: administration + returns: Confirmation that project has been deleted or an error in case of an + archived project, which has no users + examples: + request: + curl: | + curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "organization.project.user.deleted", + "id": "user_abc", + "deleted": true + } + /organization/usage/audio_speeches: + get: + summary: Get audio speeches usage details for the organization. + operationId: usage-audio-speeches + tags: + - Usage + parameters: + - name: start_time + in: query + description: Start time (Unix seconds) of the query time range, inclusive. + required: true + schema: + type: integer + - name: end_time + in: query + description: End time (Unix seconds) of the query time range, exclusive. + required: false + schema: + type: integer + - name: bucket_width + in: query + description: Width of each time bucket in response. Currently `1m`, `1h` and + `1d` are supported, default to `1d`. + required: false + schema: + type: string + enum: + - 1m + - 1h + - 1d + default: 1d + - name: project_ids + in: query + description: Return only usage for these projects. + required: false + schema: + type: array + items: + type: string + - name: user_ids + in: query + description: Return only usage for these users. + required: false + schema: + type: array + items: + type: string + - name: api_key_ids + in: query + description: Return only usage for these API keys. + required: false + schema: + type: array + items: + type: string + - name: models + in: query + description: Return only usage for these models. + required: false + schema: + type: array + items: + type: string + - name: group_by + in: query + description: Group the usage data by the specified fields. Support fields + include `project_id`, `user_id`, `api_key_id`, `model` or any + combination of them. + required: false + schema: + type: array + items: + type: string + enum: + - project_id + - user_id + - api_key_id + - model + - name: limit + in: query + description: | + Specifies the number of buckets to return. + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 + required: false + schema: + type: integer + - name: page + in: query + description: A cursor for use in pagination. Corresponding to the `next_page` + field from the previous response. + schema: + type: string + responses: + "200": + description: Usage data retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/UsageResponse" + x-oaiMeta: + name: Audio speeches + group: usage-audio-speeches + returns: A list of paginated, time bucketed [Audio speeches + usage](/docs/api-reference/usage/audio_speeches_object) objects. + examples: + request: + curl: | + curl "https://api.openai.com/v1/organization/usage/audio_speeches?start_time=1730419200&limit=1" \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: > + { + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "organization.usage.audio_speeches.result", + "characters": 45, + "num_model_requests": 1, + "project_id": null, + "user_id": null, + "api_key_id": null, + "model": null + } + ] + } + ], + "has_more": false, + "next_page": null + } + /organization/usage/audio_transcriptions: + get: + summary: Get audio transcriptions usage details for the organization. + operationId: usage-audio-transcriptions + tags: + - Usage + parameters: + - name: start_time + in: query + description: Start time (Unix seconds) of the query time range, inclusive. + required: true + schema: + type: integer + - name: end_time + in: query + description: End time (Unix seconds) of the query time range, exclusive. + required: false + schema: + type: integer + - name: bucket_width + in: query + description: Width of each time bucket in response. Currently `1m`, `1h` and + `1d` are supported, default to `1d`. + required: false + schema: + type: string + enum: + - 1m + - 1h + - 1d + default: 1d + - name: project_ids + in: query + description: Return only usage for these projects. + required: false + schema: + type: array + items: + type: string + - name: user_ids + in: query + description: Return only usage for these users. + required: false + schema: + type: array + items: + type: string + - name: api_key_ids + in: query + description: Return only usage for these API keys. + required: false + schema: + type: array + items: + type: string + - name: models + in: query + description: Return only usage for these models. + required: false + schema: + type: array + items: + type: string + - name: group_by + in: query + description: Group the usage data by the specified fields. Support fields + include `project_id`, `user_id`, `api_key_id`, `model` or any + combination of them. + required: false + schema: + type: array + items: + type: string + enum: + - project_id + - user_id + - api_key_id + - model + - name: limit + in: query + description: | + Specifies the number of buckets to return. + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 + required: false + schema: + type: integer + - name: page + in: query + description: A cursor for use in pagination. Corresponding to the `next_page` + field from the previous response. + schema: + type: string + responses: + "200": + description: Usage data retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/UsageResponse" + x-oaiMeta: + name: Audio transcriptions + group: usage-audio-transcriptions + returns: A list of paginated, time bucketed [Audio transcriptions + usage](/docs/api-reference/usage/audio_transcriptions_object) objects. + examples: + request: + curl: | + curl "https://api.openai.com/v1/organization/usage/audio_transcriptions?start_time=1730419200&limit=1" \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: > + { + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "organization.usage.audio_transcriptions.result", + "seconds": 20, + "num_model_requests": 1, + "project_id": null, + "user_id": null, + "api_key_id": null, + "model": null + } + ] + } + ], + "has_more": false, + "next_page": null + } + /organization/usage/code_interpreter_sessions: + get: + summary: Get code interpreter sessions usage details for the organization. + operationId: usage-code-interpreter-sessions + tags: + - Usage + parameters: + - name: start_time + in: query + description: Start time (Unix seconds) of the query time range, inclusive. + required: true + schema: + type: integer + - name: end_time + in: query + description: End time (Unix seconds) of the query time range, exclusive. + required: false + schema: + type: integer + - name: bucket_width + in: query + description: Width of each time bucket in response. Currently `1m`, `1h` and + `1d` are supported, default to `1d`. + required: false + schema: + type: string + enum: + - 1m + - 1h + - 1d + default: 1d + - name: project_ids + in: query + description: Return only usage for these projects. + required: false + schema: + type: array + items: + type: string + - name: group_by + in: query + description: Group the usage data by the specified fields. Support fields + include `project_id`. + required: false + schema: + type: array + items: + type: string + enum: + - project_id + - name: limit + in: query + description: | + Specifies the number of buckets to return. + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 + required: false + schema: + type: integer + - name: page + in: query + description: A cursor for use in pagination. Corresponding to the `next_page` + field from the previous response. + schema: + type: string + responses: + "200": + description: Usage data retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/UsageResponse" + x-oaiMeta: + name: Code interpreter sessions + group: usage-code-interpreter-sessions + returns: A list of paginated, time bucketed [Code interpreter sessions + usage](/docs/api-reference/usage/code_interpreter_sessions_object) + objects. + examples: + request: + curl: | + curl "https://api.openai.com/v1/organization/usage/code_interpreter_sessions?start_time=1730419200&limit=1" \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: > + { + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "organization.usage.code_interpreter_sessions.result", + "num_sessions": 1, + "project_id": null + } + ] + } + ], + "has_more": false, + "next_page": null + } + /organization/usage/completions: + get: + summary: Get completions usage details for the organization. + operationId: usage-completions + tags: + - Usage + parameters: + - name: start_time + in: query + description: Start time (Unix seconds) of the query time range, inclusive. + required: true + schema: + type: integer + - name: end_time + in: query + description: End time (Unix seconds) of the query time range, exclusive. + required: false + schema: + type: integer + - name: bucket_width + in: query + description: Width of each time bucket in response. Currently `1m`, `1h` and + `1d` are supported, default to `1d`. + required: false + schema: + type: string + enum: + - 1m + - 1h + - 1d + default: 1d + - name: project_ids + in: query + description: Return only usage for these projects. + required: false + schema: + type: array + items: + type: string + - name: user_ids + in: query + description: Return only usage for these users. + required: false + schema: + type: array + items: + type: string + - name: api_key_ids + in: query + description: Return only usage for these API keys. + required: false + schema: + type: array + items: + type: string + - name: models + in: query + description: Return only usage for these models. + required: false + schema: + type: array + items: + type: string + - name: batch + in: query + description: > + If `true`, return batch jobs only. If `false`, return non-batch jobs + only. By default, return both. + required: false + schema: + type: boolean + - name: group_by + in: query + description: Group the usage data by the specified fields. Support fields + include `project_id`, `user_id`, `api_key_id`, `model`, `batch` or + any combination of them. + required: false + schema: + type: array + items: + type: string + enum: + - project_id + - user_id + - api_key_id + - model + - batch + - name: limit + in: query + description: | + Specifies the number of buckets to return. + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 + required: false + schema: + type: integer + - name: page + in: query + description: A cursor for use in pagination. Corresponding to the `next_page` + field from the previous response. + schema: + type: string + responses: + "200": + description: Usage data retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/UsageResponse" + x-oaiMeta: + name: Completions + group: usage-completions + returns: A list of paginated, time bucketed [Completions + usage](/docs/api-reference/usage/completions_object) objects. + examples: + request: + curl: | + curl "https://api.openai.com/v1/organization/usage/completions?start_time=1730419200&limit=1" \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: > + { + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "organization.usage.completions.result", + "input_tokens": 1000, + "output_tokens": 500, + "input_cached_tokens": 800, + "input_audio_tokens": 0, + "output_audio_tokens": 0, + "num_model_requests": 5, + "project_id": null, + "user_id": null, + "api_key_id": null, + "model": null, + "batch": null + } + ] + } + ], + "has_more": true, + "next_page": "page_AAAAAGdGxdEiJdKOAAAAAGcqsYA=" + } + /organization/usage/embeddings: + get: + summary: Get embeddings usage details for the organization. + operationId: usage-embeddings + tags: + - Usage + parameters: + - name: start_time + in: query + description: Start time (Unix seconds) of the query time range, inclusive. + required: true + schema: + type: integer + - name: end_time + in: query + description: End time (Unix seconds) of the query time range, exclusive. + required: false + schema: + type: integer + - name: bucket_width + in: query + description: Width of each time bucket in response. Currently `1m`, `1h` and + `1d` are supported, default to `1d`. + required: false + schema: + type: string + enum: + - 1m + - 1h + - 1d + default: 1d + - name: project_ids + in: query + description: Return only usage for these projects. + required: false + schema: + type: array + items: + type: string + - name: user_ids + in: query + description: Return only usage for these users. + required: false + schema: + type: array + items: + type: string + - name: api_key_ids + in: query + description: Return only usage for these API keys. + required: false + schema: + type: array + items: + type: string + - name: models + in: query + description: Return only usage for these models. + required: false + schema: + type: array + items: + type: string + - name: group_by + in: query + description: Group the usage data by the specified fields. Support fields + include `project_id`, `user_id`, `api_key_id`, `model` or any + combination of them. + required: false + schema: + type: array + items: + type: string + enum: + - project_id + - user_id + - api_key_id + - model + - name: limit + in: query + description: | + Specifies the number of buckets to return. + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 + required: false + schema: + type: integer + - name: page + in: query + description: A cursor for use in pagination. Corresponding to the `next_page` + field from the previous response. + schema: + type: string + responses: + "200": + description: Usage data retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/UsageResponse" + x-oaiMeta: + name: Embeddings + group: usage-embeddings + returns: A list of paginated, time bucketed [Embeddings + usage](/docs/api-reference/usage/embeddings_object) objects. + examples: + request: + curl: | + curl "https://api.openai.com/v1/organization/usage/embeddings?start_time=1730419200&limit=1" \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: > + { + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "organization.usage.embeddings.result", + "input_tokens": 16, + "num_model_requests": 2, + "project_id": null, + "user_id": null, + "api_key_id": null, + "model": null + } + ] + } + ], + "has_more": false, + "next_page": null + } + /organization/usage/images: + get: + summary: Get images usage details for the organization. + operationId: usage-images + tags: + - Usage + parameters: + - name: start_time + in: query + description: Start time (Unix seconds) of the query time range, inclusive. + required: true + schema: + type: integer + - name: end_time + in: query + description: End time (Unix seconds) of the query time range, exclusive. + required: false + schema: + type: integer + - name: bucket_width + in: query + description: Width of each time bucket in response. Currently `1m`, `1h` and + `1d` are supported, default to `1d`. + required: false + schema: + type: string + enum: + - 1m + - 1h + - 1d + default: 1d + - name: sources + in: query + description: Return only usages for these sources. Possible values are + `image.generation`, `image.edit`, `image.variation` or any + combination of them. + required: false + schema: + type: array + items: + type: string + enum: + - image.generation + - image.edit + - image.variation + - name: sizes + in: query + description: Return only usages for these image sizes. Possible values are + `256x256`, `512x512`, `1024x1024`, `1792x1792`, `1024x1792` or any + combination of them. + required: false + schema: + type: array + items: + type: string + enum: + - 256x256 + - 512x512 + - 1024x1024 + - 1792x1792 + - 1024x1792 + - name: project_ids + in: query + description: Return only usage for these projects. + required: false + schema: + type: array + items: + type: string + - name: user_ids + in: query + description: Return only usage for these users. + required: false + schema: + type: array + items: + type: string + - name: api_key_ids + in: query + description: Return only usage for these API keys. + required: false + schema: + type: array + items: + type: string + - name: models + in: query + description: Return only usage for these models. + required: false + schema: + type: array + items: + type: string + - name: group_by + in: query + description: Group the usage data by the specified fields. Support fields + include `project_id`, `user_id`, `api_key_id`, `model`, `size`, + `source` or any combination of them. + required: false + schema: + type: array + items: + type: string + enum: + - project_id + - user_id + - api_key_id + - model + - size + - source + - name: limit + in: query + description: | + Specifies the number of buckets to return. + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 + required: false + schema: + type: integer + - name: page + in: query + description: A cursor for use in pagination. Corresponding to the `next_page` + field from the previous response. + schema: + type: string + responses: + "200": + description: Usage data retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/UsageResponse" + x-oaiMeta: + name: Images + group: usage-images + returns: A list of paginated, time bucketed [Images + usage](/docs/api-reference/usage/images_object) objects. + examples: + request: + curl: | + curl "https://api.openai.com/v1/organization/usage/images?start_time=1730419200&limit=1" \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "organization.usage.images.result", + "images": 2, + "num_model_requests": 2, + "size": null, + "source": null, + "project_id": null, + "user_id": null, + "api_key_id": null, + "model": null + } + ] + } + ], + "has_more": false, + "next_page": null + } + /organization/usage/moderations: + get: + summary: Get moderations usage details for the organization. + operationId: usage-moderations + tags: + - Usage + parameters: + - name: start_time + in: query + description: Start time (Unix seconds) of the query time range, inclusive. + required: true + schema: + type: integer + - name: end_time + in: query + description: End time (Unix seconds) of the query time range, exclusive. + required: false + schema: + type: integer + - name: bucket_width + in: query + description: Width of each time bucket in response. Currently `1m`, `1h` and + `1d` are supported, default to `1d`. + required: false + schema: + type: string + enum: + - 1m + - 1h + - 1d + default: 1d + - name: project_ids + in: query + description: Return only usage for these projects. + required: false + schema: + type: array + items: + type: string + - name: user_ids + in: query + description: Return only usage for these users. + required: false + schema: + type: array + items: + type: string + - name: api_key_ids + in: query + description: Return only usage for these API keys. + required: false + schema: + type: array + items: + type: string + - name: models + in: query + description: Return only usage for these models. + required: false + schema: + type: array + items: + type: string + - name: group_by + in: query + description: Group the usage data by the specified fields. Support fields + include `project_id`, `user_id`, `api_key_id`, `model` or any + combination of them. + required: false + schema: + type: array + items: + type: string + enum: + - project_id + - user_id + - api_key_id + - model + - name: limit + in: query + description: | + Specifies the number of buckets to return. + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 + required: false + schema: + type: integer + - name: page + in: query + description: A cursor for use in pagination. Corresponding to the `next_page` + field from the previous response. + schema: + type: string + responses: + "200": + description: Usage data retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/UsageResponse" + x-oaiMeta: + name: Moderations + group: usage-moderations + returns: A list of paginated, time bucketed [Moderations + usage](/docs/api-reference/usage/moderations_object) objects. + examples: + request: + curl: | + curl "https://api.openai.com/v1/organization/usage/moderations?start_time=1730419200&limit=1" \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: > + { + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "organization.usage.moderations.result", + "input_tokens": 16, + "num_model_requests": 2, + "project_id": null, + "user_id": null, + "api_key_id": null, + "model": null + } + ] + } + ], + "has_more": false, + "next_page": null + } + /organization/usage/vector_stores: + get: + summary: Get vector stores usage details for the organization. + operationId: usage-vector-stores + tags: + - Usage + parameters: + - name: start_time + in: query + description: Start time (Unix seconds) of the query time range, inclusive. + required: true + schema: + type: integer + - name: end_time + in: query + description: End time (Unix seconds) of the query time range, exclusive. + required: false + schema: + type: integer + - name: bucket_width + in: query + description: Width of each time bucket in response. Currently `1m`, `1h` and + `1d` are supported, default to `1d`. + required: false + schema: + type: string + enum: + - 1m + - 1h + - 1d + default: 1d + - name: project_ids + in: query + description: Return only usage for these projects. + required: false + schema: + type: array + items: + type: string + - name: group_by + in: query + description: Group the usage data by the specified fields. Support fields + include `project_id`. + required: false + schema: + type: array + items: + type: string + enum: + - project_id + - name: limit + in: query + description: | + Specifies the number of buckets to return. + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 + required: false + schema: + type: integer + - name: page + in: query + description: A cursor for use in pagination. Corresponding to the `next_page` + field from the previous response. + schema: + type: string + responses: + "200": + description: Usage data retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/UsageResponse" + x-oaiMeta: + name: Vector stores + group: usage-vector-stores + returns: A list of paginated, time bucketed [Vector stores + usage](/docs/api-reference/usage/vector_stores_object) objects. + examples: + request: + curl: | + curl "https://api.openai.com/v1/organization/usage/vector_stores?start_time=1730419200&limit=1" \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: > + { + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "organization.usage.vector_stores.result", + "usage_bytes": 1024, + "project_id": null + } + ] + } + ], + "has_more": false, + "next_page": null + } + /organization/users: + get: + summary: Lists all of the users in the organization. + operationId: list-users + tags: + - Users + parameters: + - name: limit + in: query + description: > + A limit on the number of objects to be returned. Limit can range + between 1 and 100, and the default is 20. + required: false + schema: + type: integer + default: 20 + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + required: false + schema: + type: string + - name: emails + in: query + description: Filter by the email address of users. + required: false + schema: + type: array + items: + type: string + responses: + "200": + description: Users listed successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/UserListResponse" + x-oaiMeta: + name: List users + group: administration + returns: A list of [User](/docs/api-reference/users/object) objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/users?after=user_abc&limit=20 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "list", + "data": [ + { + "object": "organization.user", + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "added_at": 1711471533 + } + ], + "first_id": "user-abc", + "last_id": "user-xyz", + "has_more": false + } + /organization/users/{user_id}: + get: + summary: Retrieves a user by their identifier. + operationId: retrieve-user + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user. + required: true + schema: + type: string + responses: + "200": + description: User retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/User" + x-oaiMeta: + name: Retrieve user + group: administration + returns: The [User](/docs/api-reference/users/object) object matching the + specified ID. + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/users/user_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "organization.user", + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "added_at": 1711471533 + } + post: + summary: Modifies a user's role in the organization. + operationId: modify-user + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user. + required: true + schema: + type: string + requestBody: + description: The new user role to modify. This must be one of `owner` or `member`. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/UserRoleUpdateRequest" + responses: + "200": + description: User role updated successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/User" + x-oaiMeta: + name: Modify user + group: administration + returns: The updated [User](/docs/api-reference/users/object) object. + examples: + request: + curl: > + curl -X POST https://api.openai.com/v1/organization/users/user_abc + \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "role": "owner" + }' + response: | + { + "object": "organization.user", + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "added_at": 1711471533 + } + delete: + summary: Deletes a user from the organization. + operationId: delete-user + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user. + required: true + schema: + type: string + responses: + "200": + description: User deleted successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/UserDeleteResponse" + x-oaiMeta: + name: Delete user + group: administration + returns: Confirmation of the deleted user + examples: + request: + curl: > + curl -X DELETE + https://api.openai.com/v1/organization/users/user_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "organization.user.deleted", + "id": "user_abc", + "deleted": true + } + /realtime/sessions: + post: + summary: > + Create an ephemeral API token for use in client-side applications with + the + + Realtime API. Can be configured with the same session parameters as the + + `session.update` client event. + + + It responds with a session object, plus a `client_secret` key which + contains + + a usable ephemeral API token that can be used to authenticate browser + clients + + for the Realtime API. + operationId: create-realtime-session + tags: + - Realtime + requestBody: + description: Create an ephemeral API key with the given session configuration. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/RealtimeSessionCreateRequest" + responses: + "200": + description: Session created successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/RealtimeSessionCreateResponse" + x-oaiMeta: + name: Create session + group: realtime + returns: The created Realtime session object, plus an ephemeral key + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/realtime/sessions \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "gpt-4o-realtime-preview", + "modalities": ["audio", "text"], + "instructions": "You are a friendly assistant." + }' + response: | + { + "id": "sess_001", + "object": "realtime.session", + "model": "gpt-4o-realtime-preview", + "modalities": ["audio", "text"], + "instructions": "You are a friendly assistant.", + "voice": "alloy", + "input_audio_format": "pcm16", + "output_audio_format": "pcm16", + "input_audio_transcription": { + "model": "whisper-1" + }, + "turn_detection": null, + "tools": [], + "tool_choice": "none", + "temperature": 0.7, + "max_response_output_tokens": 200, + "client_secret": { + "value": "ek_abc123", + "expires_at": 1234567890 + } + } + /realtime/transcription_sessions: + post: + summary: > + Create an ephemeral API token for use in client-side applications with + the + + Realtime API specifically for realtime transcriptions. + + Can be configured with the same session parameters as the + `transcription_session.update` client event. + + + It responds with a session object, plus a `client_secret` key which + contains + + a usable ephemeral API token that can be used to authenticate browser + clients + + for the Realtime API. + operationId: create-realtime-transcription-session + tags: + - Realtime + requestBody: + description: Create an ephemeral API key with the given session configuration. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/RealtimeTranscriptionSessionCreateRequest" + responses: + "200": + description: Session created successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/RealtimeTranscriptionSessionCreateResponse" + x-oaiMeta: + name: Create transcription session + group: realtime + returns: The created [Realtime transcription session + object](/docs/api-reference/realtime-sessions/transcription_session_object), + plus an ephemeral key + examples: + request: + curl: > + curl -X POST + https://api.openai.com/v1/realtime/transcription_sessions \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{}' + response: | + { + "id": "sess_BBwZc7cFV3XizEyKGDCGL", + "object": "realtime.transcription_session", + "modalities": ["audio", "text"], + "turn_detection": { + "type": "server_vad", + "threshold": 0.5, + "prefix_padding_ms": 300, + "silence_duration_ms": 200 + }, + "input_audio_format": "pcm16", + "input_audio_transcription": { + "model": "gpt-4o-transcribe", + "language": null, + "prompt": "" + }, + "client_secret": null + } + /responses: + post: + operationId: createResponse + tags: + - Responses + summary: > + Creates a model response. Provide [text](/docs/guides/text) or + + [image](/docs/guides/images) inputs to generate + [text](/docs/guides/text) + + or [JSON](/docs/guides/structured-outputs) outputs. Have the model call + + your own [custom code](/docs/guides/function-calling) or use built-in + + [tools](/docs/guides/tools) like [web + search](/docs/guides/tools-web-search) + + or [file search](/docs/guides/tools-file-search) to use your own data + + as input for the model's response. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateResponse" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/Response" + text/event-stream: + schema: + $ref: "#/components/schemas/ResponseStreamEvent" + x-oaiMeta: + name: Create a model response + group: responses + returns: | + Returns a [Response](/docs/api-reference/responses/object) object. + path: create + examples: + - title: Text input + request: + curl: > + curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-4.1", + "input": "Tell me a three sentence bedtime story about a unicorn." + }' + javascript: > + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + const response = await openai.responses.create({ + model: "gpt-4.1", + input: "Tell me a three sentence bedtime story about a unicorn." + }); + + + console.log(response); + python: > + from openai import OpenAI + + + client = OpenAI() + + + response = client.responses.create( + model="gpt-4.1", + input="Tell me a three sentence bedtime story about a unicorn." + ) + + + print(response) + csharp: > + using System; + + using OpenAI.Responses; + + + OpenAIResponseClient client = new( + model: "gpt-4.1", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + OpenAIResponse response = client.CreateResponse("Tell me a three + sentence bedtime story about a unicorn."); + + + Console.WriteLine(response.GetOutputText()); + response: > + { + "id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b", + "object": "response", + "created_at": 1741476542, + "status": "completed", + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4.1-2025-04-14", + "output": [ + { + "type": "message", + "id": "msg_67ccd2bf17f0819081ff3bb2cf6508e60bb6a6b452d3795b", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "In a peaceful grove beneath a silver moon, a unicorn named Lumina discovered a hidden pool that reflected the stars. As she dipped her horn into the water, the pool began to shimmer, revealing a pathway to a magical realm of endless night skies. Filled with wonder, Lumina whispered a wish for all who dream to find their own hidden magic, and as she glanced back, her hoofprints sparkled like stardust.", + "annotations": [] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 36, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 87, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 123 + }, + "user": null, + "metadata": {} + } + - title: Image input + request: + curl: > + curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-4.1", + "input": [ + { + "role": "user", + "content": [ + {"type": "input_text", "text": "what is in this image?"}, + { + "type": "input_image", + "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg" + } + ] + } + ] + }' + javascript: > + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + const response = await openai.responses.create({ + model: "gpt-4.1", + input: [ + { + role: "user", + content: [ + { type: "input_text", text: "what is in this image?" }, + { + type: "input_image", + image_url: + "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg", + }, + ], + }, + ], + }); + + + console.log(response); + python: > + from openai import OpenAI + + + client = OpenAI() + + + response = client.responses.create( + model="gpt-4.1", + input=[ + { + "role": "user", + "content": [ + { "type": "input_text", "text": "what is in this image?" }, + { + "type": "input_image", + "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg" + } + ] + } + ] + ) + + + print(response) + csharp: > + using System; + + using System.Collections.Generic; + + + using OpenAI.Responses; + + + OpenAIResponseClient client = new( + model: "gpt-4.1", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + List inputItems = + + [ + ResponseItem.CreateUserMessageItem( + [ + ResponseContentPart.CreateInputTextPart("What is in this image?"), + ResponseContentPart.CreateInputImagePart(new Uri("https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg")) + ] + ) + ]; + + + OpenAIResponse response = client.CreateResponse(inputItems); + + + Console.WriteLine(response.GetOutputText()); + response: > + { + "id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41", + "object": "response", + "created_at": 1741476777, + "status": "completed", + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4.1-2025-04-14", + "output": [ + { + "type": "message", + "id": "msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "The image depicts a scenic landscape with a wooden boardwalk or pathway leading through lush, green grass under a blue sky with some clouds. The setting suggests a peaceful natural area, possibly a park or nature reserve. There are trees and shrubs in the background.", + "annotations": [] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 328, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 52, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 380 + }, + "user": null, + "metadata": {} + } + - title: Web search + request: + curl: | + curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-4.1", + "tools": [{ "type": "web_search_preview" }], + "input": "What was a positive news story from today?" + }' + javascript: | + import OpenAI from "openai"; + + const openai = new OpenAI(); + + const response = await openai.responses.create({ + model: "gpt-4.1", + tools: [{ type: "web_search_preview" }], + input: "What was a positive news story from today?", + }); + + console.log(response); + python: | + from openai import OpenAI + + client = OpenAI() + + response = client.responses.create( + model="gpt-4.1", + tools=[{ "type": "web_search_preview" }], + input="What was a positive news story from today?", + ) + + print(response) + csharp: > + using System; + + + using OpenAI.Responses; + + + OpenAIResponseClient client = new( + model: "gpt-4.1", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + string userInputText = "What was a positive news story from + today?"; + + + ResponseCreationOptions options = new() + + { + Tools = + { + ResponseTool.CreateWebSearchTool() + }, + }; + + + OpenAIResponse response = client.CreateResponse(userInputText, + options); + + + Console.WriteLine(response.GetOutputText()); + response: > + { + "id": "resp_67ccf18ef5fc8190b16dbee19bc54e5f087bb177ab789d5c", + "object": "response", + "created_at": 1741484430, + "status": "completed", + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4.1-2025-04-14", + "output": [ + { + "type": "web_search_call", + "id": "ws_67ccf18f64008190a39b619f4c8455ef087bb177ab789d5c", + "status": "completed" + }, + { + "type": "message", + "id": "msg_67ccf190ca3881909d433c50b1f6357e087bb177ab789d5c", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "As of today, March 9, 2025, one notable positive news story...", + "annotations": [ + { + "type": "url_citation", + "start_index": 442, + "end_index": 557, + "url": "https://.../?utm_source=chatgpt.com", + "title": "..." + }, + { + "type": "url_citation", + "start_index": 962, + "end_index": 1077, + "url": "https://.../?utm_source=chatgpt.com", + "title": "..." + }, + { + "type": "url_citation", + "start_index": 1336, + "end_index": 1451, + "url": "https://.../?utm_source=chatgpt.com", + "title": "..." + } + ] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [ + { + "type": "web_search_preview", + "domains": [], + "search_context_size": "medium", + "user_location": { + "type": "approximate", + "city": null, + "country": "US", + "region": null, + "timezone": null + } + } + ], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 328, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 356, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 684 + }, + "user": null, + "metadata": {} + } + - title: File search + request: + curl: > + curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-4.1", + "tools": [{ + "type": "file_search", + "vector_store_ids": ["vs_1234567890"], + "max_num_results": 20 + }], + "input": "What are the attributes of an ancient brown dragon?" + }' + javascript: > + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + const response = await openai.responses.create({ + model: "gpt-4.1", + tools: [{ + type: "file_search", + vector_store_ids: ["vs_1234567890"], + max_num_results: 20 + }], + input: "What are the attributes of an ancient brown dragon?", + }); + + + console.log(response); + python: | + from openai import OpenAI + + client = OpenAI() + + response = client.responses.create( + model="gpt-4.1", + tools=[{ + "type": "file_search", + "vector_store_ids": ["vs_1234567890"], + "max_num_results": 20 + }], + input="What are the attributes of an ancient brown dragon?", + ) + + print(response) + csharp: > + using System; + + + using OpenAI.Responses; + + + OpenAIResponseClient client = new( + model: "gpt-4.1", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + string userInputText = "What are the attributes of an ancient + brown dragon?"; + + + ResponseCreationOptions options = new() + + { + Tools = + { + ResponseTool.CreateFileSearchTool( + vectorStoreIds: ["vs_1234567890"], + maxResultCount: 20 + ) + }, + }; + + + OpenAIResponse response = client.CreateResponse(userInputText, + options); + + + Console.WriteLine(response.GetOutputText()); + response: > + { + "id": "resp_67ccf4c55fc48190b71bd0463ad3306d09504fb6872380d7", + "object": "response", + "created_at": 1741485253, + "status": "completed", + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4.1-2025-04-14", + "output": [ + { + "type": "file_search_call", + "id": "fs_67ccf4c63cd08190887ef6464ba5681609504fb6872380d7", + "status": "completed", + "queries": [ + "attributes of an ancient brown dragon" + ], + "results": null + }, + { + "type": "message", + "id": "msg_67ccf4c93e5c81909d595b369351a9d309504fb6872380d7", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "The attributes of an ancient brown dragon include...", + "annotations": [ + { + "type": "file_citation", + "index": 320, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 576, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 815, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 815, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 1030, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 1030, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 1156, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 1225, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + } + ] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [ + { + "type": "file_search", + "filters": null, + "max_num_results": 20, + "ranking_options": { + "ranker": "auto", + "score_threshold": 0.0 + }, + "vector_store_ids": [ + "vs_1234567890" + ] + } + ], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 18307, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 348, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 18655 + }, + "user": null, + "metadata": {} + } + - title: Streaming + request: + curl: | + curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-4.1", + "instructions": "You are a helpful assistant.", + "input": "Hello!", + "stream": true + }' + python: | + from openai import OpenAI + + client = OpenAI() + + response = client.responses.create( + model="gpt-4.1", + instructions="You are a helpful assistant.", + input="Hello!", + stream=True + ) + + for event in response: + print(event) + javascript: | + import OpenAI from "openai"; + + const openai = new OpenAI(); + + const response = await openai.responses.create({ + model: "gpt-4.1", + instructions: "You are a helpful assistant.", + input: "Hello!", + stream: true, + }); + + for await (const event of response) { + console.log(event); + } + csharp: > + using System; + + using System.ClientModel; + + using System.Threading.Tasks; + + + using OpenAI.Responses; + + + OpenAIResponseClient client = new( + model: "gpt-4.1", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + string userInputText = "Hello!"; + + + ResponseCreationOptions options = new() + + { + Instructions = "You are a helpful assistant.", + }; + + + AsyncCollectionResult responseUpdates = + client.CreateResponseStreamingAsync(userInputText, options); + + + await foreach (StreamingResponseUpdate responseUpdate in + responseUpdates) + + { + if (responseUpdate is StreamingResponseOutputTextDeltaUpdate outputTextDeltaUpdate) + { + Console.Write(outputTextDeltaUpdate.Delta); + } + } + response: | + event: response.created + data: {"type":"response.created","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"You are a helpful assistant.","max_output_tokens":null,"model":"gpt-4.1-2025-04-14","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}}} + + event: response.in_progress + data: {"type":"response.in_progress","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"You are a helpful assistant.","max_output_tokens":null,"model":"gpt-4.1-2025-04-14","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}}} + + event: response.output_item.added + data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"in_progress","role":"assistant","content":[]}} + + event: response.content_part.added + data: {"type":"response.content_part.added","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"","annotations":[]}} + + event: response.output_text.delta + data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"Hi"} + + ... + + event: response.output_text.done + data: {"type":"response.output_text.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"text":"Hi there! How can I assist you today?"} + + event: response.content_part.done + data: {"type":"response.content_part.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"Hi there! How can I assist you today?","annotations":[]}} + + event: response.output_item.done + data: {"type":"response.output_item.done","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Hi there! How can I assist you today?","annotations":[]}]}} + + event: response.completed + data: {"type":"response.completed","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"completed","error":null,"incomplete_details":null,"instructions":"You are a helpful assistant.","max_output_tokens":null,"model":"gpt-4.1-2025-04-14","output":[{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Hi there! How can I assist you today?","annotations":[]}]}],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":{"input_tokens":37,"output_tokens":11,"output_tokens_details":{"reasoning_tokens":0},"total_tokens":48},"user":null,"metadata":{}}} + - title: Functions + request: + curl: > + curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-4.1", + "input": "What is the weather like in Boston today?", + "tools": [ + { + "type": "function", + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": ["celsius", "fahrenheit"] + } + }, + "required": ["location", "unit"] + } + } + ], + "tool_choice": "auto" + }' + python: > + from openai import OpenAI + + + client = OpenAI() + + + tools = [ + { + "type": "function", + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA", + }, + "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}, + }, + "required": ["location", "unit"], + } + } + ] + + + response = client.responses.create( + model="gpt-4.1", + tools=tools, + input="What is the weather like in Boston today?", + tool_choice="auto" + ) + + + print(response) + javascript: > + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + const tools = [ + { + type: "function", + name: "get_current_weather", + description: "Get the current weather in a given location", + parameters: { + type: "object", + properties: { + location: { + type: "string", + description: "The city and state, e.g. San Francisco, CA", + }, + unit: { type: "string", enum: ["celsius", "fahrenheit"] }, + }, + required: ["location", "unit"], + }, + }, + ]; + + + const response = await openai.responses.create({ + model: "gpt-4.1", + tools: tools, + input: "What is the weather like in Boston today?", + tool_choice: "auto", + }); + + + console.log(response); + csharp: > + using System; + + using OpenAI.Responses; + + + OpenAIResponseClient client = new( + model: "gpt-4.1", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + ResponseTool getCurrentWeatherFunctionTool = + ResponseTool.CreateFunctionTool( + functionName: "get_current_weather", + functionDescription: "Get the current weather in a given location", + functionParameters: BinaryData.FromString(""" + { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]} + }, + "required": ["location", "unit"] + } + """ + ) + ); + + + string userInputText = "What is the weather like in Boston + today?"; + + + ResponseCreationOptions options = new() + + { + Tools = + { + getCurrentWeatherFunctionTool + }, + ToolChoice = ResponseToolChoice.CreateAutoChoice(), + }; + + + OpenAIResponse response = client.CreateResponse(userInputText, + options); + response: > + { + "id": "resp_67ca09c5efe0819096d0511c92b8c890096610f474011cc0", + "object": "response", + "created_at": 1741294021, + "status": "completed", + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4.1-2025-04-14", + "output": [ + { + "type": "function_call", + "id": "fc_67ca09c6bedc8190a7abfec07b1a1332096610f474011cc0", + "call_id": "call_unLAR8MvFNptuiZK6K6HCy5k", + "name": "get_current_weather", + "arguments": "{\"location\":\"Boston, MA\",\"unit\":\"celsius\"}", + "status": "completed" + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [ + { + "type": "function", + "description": "Get the current weather in a given location", + "name": "get_current_weather", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": [ + "celsius", + "fahrenheit" + ] + } + }, + "required": [ + "location", + "unit" + ] + }, + "strict": true + } + ], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 291, + "output_tokens": 23, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 314 + }, + "user": null, + "metadata": {} + } + - title: Reasoning + request: + curl: | + curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "o3-mini", + "input": "How much wood would a woodchuck chuck?", + "reasoning": { + "effort": "high" + } + }' + javascript: | + import OpenAI from "openai"; + const openai = new OpenAI(); + + const response = await openai.responses.create({ + model: "o3-mini", + input: "How much wood would a woodchuck chuck?", + reasoning: { + effort: "high" + } + }); + + console.log(response); + python: | + from openai import OpenAI + client = OpenAI() + + response = client.responses.create( + model="o3-mini", + input="How much wood would a woodchuck chuck?", + reasoning={ + "effort": "high" + } + ) + + print(response) + csharp: > + using System; + + using OpenAI.Responses; + + + OpenAIResponseClient client = new( + model: "o3-mini", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + string userInputText = "How much wood would a woodchuck chuck?"; + + + ResponseCreationOptions options = new() + + { + ReasoningOptions = new() + { + ReasoningEffortLevel = ResponseReasoningEffortLevel.High, + }, + }; + + + OpenAIResponse response = client.CreateResponse(userInputText, + options); + + + Console.WriteLine(response.GetOutputText()); + response: > + { + "id": "resp_67ccd7eca01881908ff0b5146584e408072912b2993db808", + "object": "response", + "created_at": 1741477868, + "status": "completed", + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "o1-2024-12-17", + "output": [ + { + "type": "message", + "id": "msg_67ccd7f7b5848190a6f3e95d809f6b44072912b2993db808", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "The classic tongue twister...", + "annotations": [] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": "high", + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 81, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 1035, + "output_tokens_details": { + "reasoning_tokens": 832 + }, + "total_tokens": 1116 + }, + "user": null, + "metadata": {} + } + /responses/{response_id}: + get: + operationId: getResponse + tags: + - Responses + summary: | + Retrieves a model response with the given ID. + parameters: + - in: path + name: response_id + required: true + schema: + type: string + example: resp_677efb5139a88190b512bc3fef8e535d + description: The ID of the response to retrieve. + - in: query + name: include + schema: + type: array + items: + $ref: "#/components/schemas/Includable" + description: | + Additional fields to include in the response. See the `include` + parameter for Response creation above for more information. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/Response" + x-oaiMeta: + name: Get a model response + group: responses + returns: > + The [Response](/docs/api-reference/responses/object) object matching + the + + specified ID. + examples: + request: + curl: | + curl https://api.openai.com/v1/responses/resp_123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" + javascript: | + import OpenAI from "openai"; + const client = new OpenAI(); + + const response = await client.responses.retrieve("resp_123"); + console.log(response); + python: | + from openai import OpenAI + client = OpenAI() + + response = client.responses.retrieve("resp_123") + print(response) + response: > + { + "id": "resp_67cb71b351908190a308f3859487620d06981a8637e6bc44", + "object": "response", + "created_at": 1741386163, + "status": "completed", + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4o-2024-08-06", + "output": [ + { + "type": "message", + "id": "msg_67cb71b3c2b0819084d481baaaf148f206981a8637e6bc44", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "Silent circuits hum, \nThoughts emerge in data streams— \nDigital dawn breaks.", + "annotations": [] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 32, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 18, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 50 + }, + "user": null, + "metadata": {} + } + delete: + operationId: deleteResponse + tags: + - Responses + summary: | + Deletes a model response with the given ID. + parameters: + - in: path + name: response_id + required: true + schema: + type: string + example: resp_677efb5139a88190b512bc3fef8e535d + description: The ID of the response to delete. + responses: + "200": + description: OK + "404": + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + x-oaiMeta: + name: Delete a model response + group: responses + returns: | + A success message. + examples: + request: + curl: | + curl -X DELETE https://api.openai.com/v1/responses/resp_123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" + javascript: | + import OpenAI from "openai"; + const client = new OpenAI(); + + const response = await client.responses.del("resp_123"); + console.log(response); + python: | + from openai import OpenAI + client = OpenAI() + + response = client.responses.del("resp_123") + print(response) + response: | + { + "id": "resp_6786a1bec27481909a17d673315b29f6", + "object": "response", + "deleted": true + } + /responses/{response_id}/input_items: + get: + operationId: listInputItems + tags: + - Responses + summary: Returns a list of input items for a given response. + parameters: + - in: path + name: response_id + required: true + schema: + type: string + description: The ID of the response to retrieve input items for. + - name: limit + in: query + description: > + A limit on the number of objects to be returned. Limit can range + between + + 1 and 100, and the default is 20. + required: false + schema: + type: integer + default: 20 + - in: query + name: order + schema: + type: string + enum: + - asc + - desc + description: | + The order to return the input items in. Default is `asc`. + - `asc`: Return the input items in ascending order. + - `desc`: Return the input items in descending order. + - in: query + name: after + schema: + type: string + description: | + An item ID to list items after, used in pagination. + - in: query + name: before + schema: + type: string + description: | + An item ID to list items before, used in pagination. + - in: query + name: include + schema: + type: array + items: + $ref: "#/components/schemas/Includable" + description: | + Additional fields to include in the response. See the `include` + parameter for Response creation above for more information. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ResponseItemList" + x-oaiMeta: + name: List input items + group: responses + returns: A list of input item objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/responses/resp_abc123/input_items \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" + javascript: > + import OpenAI from "openai"; + + const client = new OpenAI(); + + + const response = await + client.responses.inputItems.list("resp_123"); + + console.log(response.data); + python: | + from openai import OpenAI + client = OpenAI() + + response = client.responses.input_items.list("resp_123") + print(response.data) + response: > + { + "object": "list", + "data": [ + { + "id": "msg_abc123", + "type": "message", + "role": "user", + "content": [ + { + "type": "input_text", + "text": "Tell me a three sentence bedtime story about a unicorn." + } + ] + } + ], + "first_id": "msg_abc123", + "last_id": "msg_abc123", + "has_more": false + } + /threads: + post: + operationId: createThread + tags: + - Assistants + summary: Create a thread. + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CreateThreadRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ThreadObject" + x-oaiMeta: + name: Create thread + group: threads + beta: true + returns: A [thread](/docs/api-reference/threads) object. + examples: + - title: Empty + request: + curl: | + curl https://api.openai.com/v1/threads \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '' + python: | + from openai import OpenAI + client = OpenAI() + + empty_thread = client.beta.threads.create() + print(empty_thread) + node.js: |- + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const emptyThread = await openai.beta.threads.create(); + + console.log(emptyThread); + } + + main(); + response: | + { + "id": "thread_abc123", + "object": "thread", + "created_at": 1699012949, + "metadata": {}, + "tool_resources": {} + } + - title: Messages + request: + curl: | + curl https://api.openai.com/v1/threads \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "messages": [{ + "role": "user", + "content": "Hello, what is AI?" + }, { + "role": "user", + "content": "How does AI work? Explain it in simple terms." + }] + }' + python: | + from openai import OpenAI + client = OpenAI() + + message_thread = client.beta.threads.create( + messages=[ + { + "role": "user", + "content": "Hello, what is AI?" + }, + { + "role": "user", + "content": "How does AI work? Explain it in simple terms." + }, + ] + ) + + print(message_thread) + node.js: >- + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + async function main() { + const messageThread = await openai.beta.threads.create({ + messages: [ + { + role: "user", + content: "Hello, what is AI?" + }, + { + role: "user", + content: "How does AI work? Explain it in simple terms.", + }, + ], + }); + + console.log(messageThread); + } + + + main(); + response: | + { + "id": "thread_abc123", + "object": "thread", + "created_at": 1699014083, + "metadata": {}, + "tool_resources": {} + } + /threads/runs: + post: + operationId: createThreadAndRun + tags: + - Assistants + summary: Create a thread and run it in one request. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateThreadAndRunRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/RunObject" + x-oaiMeta: + name: Create thread and run + group: threads + beta: true + returns: A [run](/docs/api-reference/runs/object) object. + examples: + - title: Default + request: + curl: > + curl https://api.openai.com/v1/threads/runs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "assistant_id": "asst_abc123", + "thread": { + "messages": [ + {"role": "user", "content": "Explain deep learning to a 5 year old."} + ] + } + }' + python: > + from openai import OpenAI + + client = OpenAI() + + + run = client.beta.threads.create_and_run( + assistant_id="asst_abc123", + thread={ + "messages": [ + {"role": "user", "content": "Explain deep learning to a 5 year old."} + ] + } + ) + + + print(run) + node.js: > + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + async function main() { + const run = await openai.beta.threads.createAndRun({ + assistant_id: "asst_abc123", + thread: { + messages: [ + { role: "user", content: "Explain deep learning to a 5 year old." }, + ], + }, + }); + + console.log(run); + } + + + main(); + response: | + { + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699076792, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "queued", + "started_at": null, + "expires_at": 1699077392, + "cancelled_at": null, + "failed_at": null, + "completed_at": null, + "required_action": null, + "last_error": null, + "model": "gpt-4o", + "instructions": "You are a helpful assistant.", + "tools": [], + "tool_resources": {}, + "metadata": {}, + "temperature": 1.0, + "top_p": 1.0, + "max_completion_tokens": null, + "max_prompt_tokens": null, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "incomplete_details": null, + "usage": null, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true + } + - title: Streaming + request: + curl: | + curl https://api.openai.com/v1/threads/runs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "assistant_id": "asst_123", + "thread": { + "messages": [ + {"role": "user", "content": "Hello"} + ] + }, + "stream": true + }' + python: | + from openai import OpenAI + client = OpenAI() + + stream = client.beta.threads.create_and_run( + assistant_id="asst_123", + thread={ + "messages": [ + {"role": "user", "content": "Hello"} + ] + }, + stream=True + ) + + for event in stream: + print(event) + node.js: | + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const stream = await openai.beta.threads.createAndRun({ + assistant_id: "asst_123", + thread: { + messages: [ + { role: "user", content: "Hello" }, + ], + }, + stream: true + }); + + for await (const event of stream) { + console.log(event); + } + } + + main(); + response: | + event: thread.created + data: {"id":"thread_123","object":"thread","created_at":1710348075,"metadata":{}} + + event: thread.run.created + data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"tool_resources":{},"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true} + + event: thread.run.queued + data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"tool_resources":{},"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true} + + event: thread.run.in_progress + data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"tool_resources":{},"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true} + + event: thread.run.step.created + data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + + event: thread.run.step.in_progress + data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + + event: thread.message.created + data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[], "metadata":{}} + + event: thread.message.in_progress + data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[], "metadata":{}} + + event: thread.message.delta + data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} + + ... + + event: thread.message.delta + data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" today"}}]}} + + event: thread.message.delta + data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} + + event: thread.message.completed + data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710348077,"role":"assistant","content":[{"type":"text","text":{"value":"Hello! How can I assist you today?","annotations":[]}}], "metadata":{}} + + event: thread.run.step.completed + data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710348077,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31}} + + event: thread.run.completed + {"id":"run_123","object":"thread.run","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1713226836,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1713226837,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":345,"completion_tokens":11,"total_tokens":356},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true} + + event: done + data: [DONE] + - title: Streaming with Functions + request: + curl: > + curl https://api.openai.com/v1/threads/runs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "assistant_id": "asst_abc123", + "thread": { + "messages": [ + {"role": "user", "content": "What is the weather like in San Francisco?"} + ] + }, + "tools": [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": ["celsius", "fahrenheit"] + } + }, + "required": ["location"] + } + } + } + ], + "stream": true + }' + python: > + from openai import OpenAI + + client = OpenAI() + + + tools = [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA", + }, + "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}, + }, + "required": ["location"], + }, + } + } + ] + + + stream = client.beta.threads.create_and_run( + thread={ + "messages": [ + {"role": "user", "content": "What is the weather like in San Francisco?"} + ] + }, + assistant_id="asst_abc123", + tools=tools, + stream=True + ) + + + for event in stream: + print(event) + node.js: > + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + const tools = [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA", + }, + "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}, + }, + "required": ["location"], + }, + } + } + ]; + + + async function main() { + const stream = await openai.beta.threads.createAndRun({ + assistant_id: "asst_123", + thread: { + messages: [ + { role: "user", content: "What is the weather like in San Francisco?" }, + ], + }, + tools: tools, + stream: true + }); + + for await (const event of stream) { + console.log(event); + } + } + + + main(); + response: | + event: thread.created + data: {"id":"thread_123","object":"thread","created_at":1710351818,"metadata":{}} + + event: thread.run.created + data: {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + + event: thread.run.queued + data: {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + + event: thread.run.in_progress + data: {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710351818,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + + event: thread.run.step.created + data: {"id":"step_001","object":"thread.run.step","created_at":1710351819,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710352418,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[]},"usage":null} + + event: thread.run.step.in_progress + data: {"id":"step_001","object":"thread.run.step","created_at":1710351819,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710352418,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[]},"usage":null} + + event: thread.run.step.delta + data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"id":"call_XXNp8YGaFrjrSjgqxtC8JJ1B","type":"function","function":{"name":"get_current_weather","arguments":"","output":null}}]}}} + + event: thread.run.step.delta + data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"{\""}}]}}} + + event: thread.run.step.delta + data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"location"}}]}}} + + ... + + event: thread.run.step.delta + data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"ahrenheit"}}]}}} + + event: thread.run.step.delta + data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"\"}"}}]}}} + + event: thread.run.requires_action + data: {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"requires_action","started_at":1710351818,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":{"type":"submit_tool_outputs","submit_tool_outputs":{"tool_calls":[{"id":"call_XXNp8YGaFrjrSjgqxtC8JJ1B","type":"function","function":{"name":"get_current_weather","arguments":"{\"location\":\"San Francisco, CA\",\"unit\":\"fahrenheit\"}"}}]}},"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":345,"completion_tokens":11,"total_tokens":356},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + + event: done + data: [DONE] + /threads/{thread_id}: + get: + operationId: getThread + tags: + - Assistants + summary: Retrieves a thread. + parameters: + - in: path + name: thread_id + required: true + schema: + type: string + description: The ID of the thread to retrieve. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ThreadObject" + x-oaiMeta: + name: Retrieve thread + group: threads + beta: true + returns: The [thread](/docs/api-reference/threads/object) object matching the + specified ID. + examples: + request: + curl: | + curl https://api.openai.com/v1/threads/thread_abc123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" + python: | + from openai import OpenAI + client = OpenAI() + + my_thread = client.beta.threads.retrieve("thread_abc123") + print(my_thread) + node.js: |- + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const myThread = await openai.beta.threads.retrieve( + "thread_abc123" + ); + + console.log(myThread); + } + + main(); + response: | + { + "id": "thread_abc123", + "object": "thread", + "created_at": 1699014083, + "metadata": {}, + "tool_resources": { + "code_interpreter": { + "file_ids": [] + } + } + } + post: + operationId: modifyThread + tags: + - Assistants + summary: Modifies a thread. + parameters: + - in: path + name: thread_id + required: true + schema: + type: string + description: The ID of the thread to modify. Only the `metadata` can be modified. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ModifyThreadRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ThreadObject" + x-oaiMeta: + name: Modify thread + group: threads + beta: true + returns: The modified [thread](/docs/api-reference/threads/object) object + matching the specified ID. + examples: + request: + curl: | + curl https://api.openai.com/v1/threads/thread_abc123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "metadata": { + "modified": "true", + "user": "abc123" + } + }' + python: | + from openai import OpenAI + client = OpenAI() + + my_updated_thread = client.beta.threads.update( + "thread_abc123", + metadata={ + "modified": "true", + "user": "abc123" + } + ) + print(my_updated_thread) + node.js: |- + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const updatedThread = await openai.beta.threads.update( + "thread_abc123", + { + metadata: { modified: "true", user: "abc123" }, + } + ); + + console.log(updatedThread); + } + + main(); + response: | + { + "id": "thread_abc123", + "object": "thread", + "created_at": 1699014083, + "metadata": { + "modified": "true", + "user": "abc123" + }, + "tool_resources": {} + } + delete: + operationId: deleteThread + tags: + - Assistants + summary: Delete a thread. + parameters: + - in: path + name: thread_id + required: true + schema: + type: string + description: The ID of the thread to delete. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/DeleteThreadResponse" + x-oaiMeta: + name: Delete thread + group: threads + beta: true + returns: Deletion status + examples: + request: + curl: | + curl https://api.openai.com/v1/threads/thread_abc123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" \ + -X DELETE + python: | + from openai import OpenAI + client = OpenAI() + + response = client.beta.threads.delete("thread_abc123") + print(response) + node.js: |- + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const response = await openai.beta.threads.del("thread_abc123"); + + console.log(response); + } + main(); + response: | + { + "id": "thread_abc123", + "object": "thread.deleted", + "deleted": true + } + /threads/{thread_id}/messages: + get: + operationId: listMessages + tags: + - Assistants + summary: Returns a list of messages for a given thread. + parameters: + - in: path + name: thread_id + required: true + schema: + type: string + description: The ID of the [thread](/docs/api-reference/threads) the messages + belong to. + - name: limit + in: query + description: > + A limit on the number of objects to be returned. Limit can range + between 1 and 100, and the default is 20. + required: false + schema: + type: integer + default: 20 + - name: order + in: query + description: > + Sort order by the `created_at` timestamp of the objects. `asc` for + ascending order and `desc` for descending order. + schema: + type: string + default: desc + enum: + - asc + - desc + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + schema: + type: string + - name: before + in: query + description: > + A cursor for use in pagination. `before` is an object ID that + defines your place in the list. For instance, if you make a list + request and receive 100 objects, starting with obj_foo, your + subsequent call can include before=obj_foo in order to fetch the + previous page of the list. + schema: + type: string + - name: run_id + in: query + description: | + Filter messages by the run ID that generated them. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ListMessagesResponse" + x-oaiMeta: + name: List messages + group: threads + beta: true + returns: A list of [message](/docs/api-reference/messages) objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/threads/thread_abc123/messages \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" + python: > + from openai import OpenAI + + client = OpenAI() + + + thread_messages = + client.beta.threads.messages.list("thread_abc123") + + print(thread_messages.data) + node.js: |- + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const threadMessages = await openai.beta.threads.messages.list( + "thread_abc123" + ); + + console.log(threadMessages.data); + } + + main(); + response: > + { + "object": "list", + "data": [ + { + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1699016383, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] + } + } + ], + "attachments": [], + "metadata": {} + }, + { + "id": "msg_abc456", + "object": "thread.message", + "created_at": 1699016383, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "Hello, what is AI?", + "annotations": [] + } + } + ], + "attachments": [], + "metadata": {} + } + ], + "first_id": "msg_abc123", + "last_id": "msg_abc456", + "has_more": false + } + post: + operationId: createMessage + tags: + - Assistants + summary: Create a message. + parameters: + - in: path + name: thread_id + required: true + schema: + type: string + description: The ID of the [thread](/docs/api-reference/threads) to create a + message for. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateMessageRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/MessageObject" + x-oaiMeta: + name: Create message + group: threads + beta: true + returns: A [message](/docs/api-reference/messages/object) object. + examples: + request: + curl: | + curl https://api.openai.com/v1/threads/thread_abc123/messages \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "role": "user", + "content": "How does AI work? Explain it in simple terms." + }' + python: | + from openai import OpenAI + client = OpenAI() + + thread_message = client.beta.threads.messages.create( + "thread_abc123", + role="user", + content="How does AI work? Explain it in simple terms.", + ) + print(thread_message) + node.js: >- + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + async function main() { + const threadMessages = await openai.beta.threads.messages.create( + "thread_abc123", + { role: "user", content: "How does AI work? Explain it in simple terms." } + ); + + console.log(threadMessages); + } + + + main(); + response: | + { + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1713226573, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] + } + } + ], + "attachments": [], + "metadata": {} + } + /threads/{thread_id}/messages/{message_id}: + get: + operationId: getMessage + tags: + - Assistants + summary: Retrieve a message. + parameters: + - in: path + name: thread_id + required: true + schema: + type: string + description: The ID of the [thread](/docs/api-reference/threads) to which this + message belongs. + - in: path + name: message_id + required: true + schema: + type: string + description: The ID of the message to retrieve. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/MessageObject" + x-oaiMeta: + name: Retrieve message + group: threads + beta: true + returns: The [message](/docs/api-reference/messages/object) object matching the + specified ID. + examples: + request: + curl: | + curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" + python: | + from openai import OpenAI + client = OpenAI() + + message = client.beta.threads.messages.retrieve( + message_id="msg_abc123", + thread_id="thread_abc123", + ) + print(message) + node.js: |- + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const message = await openai.beta.threads.messages.retrieve( + "thread_abc123", + "msg_abc123" + ); + + console.log(message); + } + + main(); + response: | + { + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1699017614, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] + } + } + ], + "attachments": [], + "metadata": {} + } + post: + operationId: modifyMessage + tags: + - Assistants + summary: Modifies a message. + parameters: + - in: path + name: thread_id + required: true + schema: + type: string + description: The ID of the thread to which this message belongs. + - in: path + name: message_id + required: true + schema: + type: string + description: The ID of the message to modify. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ModifyMessageRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/MessageObject" + x-oaiMeta: + name: Modify message + group: threads + beta: true + returns: The modified [message](/docs/api-reference/messages/object) object. + examples: + request: + curl: | + curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "metadata": { + "modified": "true", + "user": "abc123" + } + }' + python: | + from openai import OpenAI + client = OpenAI() + + message = client.beta.threads.messages.update( + message_id="msg_abc12", + thread_id="thread_abc123", + metadata={ + "modified": "true", + "user": "abc123", + }, + ) + print(message) + node.js: |- + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const message = await openai.beta.threads.messages.update( + "thread_abc123", + "msg_abc123", + { + metadata: { + modified: "true", + user: "abc123", + }, + } + }' + response: | + { + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1699017614, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] + } + } + ], + "file_ids": [], + "metadata": { + "modified": "true", + "user": "abc123" + } + } + delete: + operationId: deleteMessage + tags: + - Assistants + summary: Deletes a message. + parameters: + - in: path + name: thread_id + required: true + schema: + type: string + description: The ID of the thread to which this message belongs. + - in: path + name: message_id + required: true + schema: + type: string + description: The ID of the message to delete. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/DeleteMessageResponse" + x-oaiMeta: + name: Delete message + group: threads + beta: true + returns: Deletion status + examples: + request: + curl: | + curl -X DELETE https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" + python: | + from openai import OpenAI + client = OpenAI() + + deleted_message = client.beta.threads.messages.delete( + message_id="msg_abc12", + thread_id="thread_abc123", + ) + print(deleted_message) + node.js: |- + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const deletedMessage = await openai.beta.threads.messages.del( + "thread_abc123", + "msg_abc123" + ); + + console.log(deletedMessage); + } + response: | + { + "id": "msg_abc123", + "object": "thread.message.deleted", + "deleted": true + } + /threads/{thread_id}/runs: + get: + operationId: listRuns + tags: + - Assistants + summary: Returns a list of runs belonging to a thread. + parameters: + - name: thread_id + in: path + required: true + schema: + type: string + description: The ID of the thread the run belongs to. + - name: limit + in: query + description: > + A limit on the number of objects to be returned. Limit can range + between 1 and 100, and the default is 20. + required: false + schema: + type: integer + default: 20 + - name: order + in: query + description: > + Sort order by the `created_at` timestamp of the objects. `asc` for + ascending order and `desc` for descending order. + schema: + type: string + default: desc + enum: + - asc + - desc + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + schema: + type: string + - name: before + in: query + description: > + A cursor for use in pagination. `before` is an object ID that + defines your place in the list. For instance, if you make a list + request and receive 100 objects, starting with obj_foo, your + subsequent call can include before=obj_foo in order to fetch the + previous page of the list. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ListRunsResponse" + x-oaiMeta: + name: List runs + group: threads + beta: true + returns: A list of [run](/docs/api-reference/runs/object) objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/threads/thread_abc123/runs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" + python: | + from openai import OpenAI + client = OpenAI() + + runs = client.beta.threads.runs.list( + "thread_abc123" + ) + + print(runs) + node.js: | + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const runs = await openai.beta.threads.runs.list( + "thread_abc123" + ); + + console.log(runs); + } + + main(); + response: | + { + "object": "list", + "data": [ + { + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699075072, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "completed", + "started_at": 1699075072, + "expires_at": null, + "cancelled_at": null, + "failed_at": null, + "completed_at": 1699075073, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ + { + "type": "code_interpreter" + } + ], + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "file-abc123", + "file-abc456" + ] + } + }, + "metadata": {}, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + }, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true + }, + { + "id": "run_abc456", + "object": "thread.run", + "created_at": 1699063290, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "completed", + "started_at": 1699063290, + "expires_at": null, + "cancelled_at": null, + "failed_at": null, + "completed_at": 1699063291, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ + { + "type": "code_interpreter" + } + ], + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "file-abc123", + "file-abc456" + ] + } + }, + "metadata": {}, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + }, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true + } + ], + "first_id": "run_abc123", + "last_id": "run_abc456", + "has_more": false + } + post: + operationId: createRun + tags: + - Assistants + summary: Create a run. + parameters: + - in: path + name: thread_id + required: true + schema: + type: string + description: The ID of the thread to run. + - name: include[] + in: query + description: | + A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. + + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + schema: + type: array + items: + type: string + enum: + - step_details.tool_calls[*].file_search.results[*].content + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateRunRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/RunObject" + x-oaiMeta: + name: Create run + group: threads + beta: true + returns: A [run](/docs/api-reference/runs/object) object. + examples: + - title: Default + request: + curl: | + curl https://api.openai.com/v1/threads/thread_abc123/runs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "assistant_id": "asst_abc123" + }' + python: | + from openai import OpenAI + client = OpenAI() + + run = client.beta.threads.runs.create( + thread_id="thread_abc123", + assistant_id="asst_abc123" + ) + + print(run) + node.js: | + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const run = await openai.beta.threads.runs.create( + "thread_abc123", + { assistant_id: "asst_abc123" } + ); + + console.log(run); + } + + main(); + response: | + { + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699063290, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "queued", + "started_at": 1699063290, + "expires_at": null, + "cancelled_at": null, + "failed_at": null, + "completed_at": 1699063291, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ + { + "type": "code_interpreter" + } + ], + "metadata": {}, + "usage": null, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true + } + - title: Streaming + request: + curl: | + curl https://api.openai.com/v1/threads/thread_123/runs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "assistant_id": "asst_123", + "stream": true + }' + python: | + from openai import OpenAI + client = OpenAI() + + stream = client.beta.threads.runs.create( + thread_id="thread_123", + assistant_id="asst_123", + stream=True + ) + + for event in stream: + print(event) + node.js: | + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const stream = await openai.beta.threads.runs.create( + "thread_123", + { assistant_id: "asst_123", stream: true } + ); + + for await (const event of stream) { + console.log(event); + } + } + + main(); + response: | + event: thread.run.created + data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + + event: thread.run.queued + data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + + event: thread.run.in_progress + data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710330641,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + + event: thread.run.step.created + data: {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + + event: thread.run.step.in_progress + data: {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + + event: thread.message.created + data: {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + + event: thread.message.in_progress + data: {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + + event: thread.message.delta + data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} + + ... + + event: thread.message.delta + data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" today"}}]}} + + event: thread.message.delta + data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} + + event: thread.message.completed + data: {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710330642,"role":"assistant","content":[{"type":"text","text":{"value":"Hello! How can I assist you today?","annotations":[]}}],"metadata":{}} + + event: thread.run.step.completed + data: {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710330642,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31}} + + event: thread.run.completed + data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710330641,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710330642,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + + event: done + data: [DONE] + - title: Streaming with Functions + request: + curl: > + curl https://api.openai.com/v1/threads/thread_abc123/runs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "assistant_id": "asst_abc123", + "tools": [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": ["celsius", "fahrenheit"] + } + }, + "required": ["location"] + } + } + } + ], + "stream": true + }' + python: > + from openai import OpenAI + + client = OpenAI() + + + tools = [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA", + }, + "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}, + }, + "required": ["location"], + }, + } + } + ] + + + stream = client.beta.threads.runs.create( + thread_id="thread_abc123", + assistant_id="asst_abc123", + tools=tools, + stream=True + ) + + + for event in stream: + print(event) + node.js: > + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + const tools = [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA", + }, + "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}, + }, + "required": ["location"], + }, + } + } + ]; + + + async function main() { + const stream = await openai.beta.threads.runs.create( + "thread_abc123", + { + assistant_id: "asst_abc123", + tools: tools, + stream: true + } + ); + + for await (const event of stream) { + console.log(event); + } + } + + + main(); + response: | + event: thread.run.created + data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + + event: thread.run.queued + data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + + event: thread.run.in_progress + data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710348075,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + + event: thread.run.step.created + data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + + event: thread.run.step.in_progress + data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + + event: thread.message.created + data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + + event: thread.message.in_progress + data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + + event: thread.message.delta + data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} + + ... + + event: thread.message.delta + data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" today"}}]}} + + event: thread.message.delta + data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} + + event: thread.message.completed + data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710348077,"role":"assistant","content":[{"type":"text","text":{"value":"Hello! How can I assist you today?","annotations":[]}}],"metadata":{}} + + event: thread.run.step.completed + data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710348077,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31}} + + event: thread.run.completed + data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710348075,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710348077,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + + event: done + data: [DONE] + /threads/{thread_id}/runs/{run_id}: + get: + operationId: getRun + tags: + - Assistants + summary: Retrieves a run. + parameters: + - in: path + name: thread_id + required: true + schema: + type: string + description: The ID of the [thread](/docs/api-reference/threads) that was run. + - in: path + name: run_id + required: true + schema: + type: string + description: The ID of the run to retrieve. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/RunObject" + x-oaiMeta: + name: Retrieve run + group: threads + beta: true + returns: The [run](/docs/api-reference/runs/object) object matching the + specified ID. + examples: + request: + curl: > + curl + https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" + python: | + from openai import OpenAI + client = OpenAI() + + run = client.beta.threads.runs.retrieve( + thread_id="thread_abc123", + run_id="run_abc123" + ) + + print(run) + node.js: | + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const run = await openai.beta.threads.runs.retrieve( + "thread_abc123", + "run_abc123" + ); + + console.log(run); + } + + main(); + response: | + { + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699075072, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "completed", + "started_at": 1699075072, + "expires_at": null, + "cancelled_at": null, + "failed_at": null, + "completed_at": 1699075073, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ + { + "type": "code_interpreter" + } + ], + "metadata": {}, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + }, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true + } + post: + operationId: modifyRun + tags: + - Assistants + summary: Modifies a run. + parameters: + - in: path + name: thread_id + required: true + schema: + type: string + description: The ID of the [thread](/docs/api-reference/threads) that was run. + - in: path + name: run_id + required: true + schema: + type: string + description: The ID of the run to modify. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ModifyRunRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/RunObject" + x-oaiMeta: + name: Modify run + group: threads + beta: true + returns: The modified [run](/docs/api-reference/runs/object) object matching the + specified ID. + examples: + request: + curl: > + curl + https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "metadata": { + "user_id": "user_abc123" + } + }' + python: | + from openai import OpenAI + client = OpenAI() + + run = client.beta.threads.runs.update( + thread_id="thread_abc123", + run_id="run_abc123", + metadata={"user_id": "user_abc123"}, + ) + + print(run) + node.js: | + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const run = await openai.beta.threads.runs.update( + "thread_abc123", + "run_abc123", + { + metadata: { + user_id: "user_abc123", + }, + } + ); + + console.log(run); + } + + main(); + response: | + { + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699075072, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "completed", + "started_at": 1699075072, + "expires_at": null, + "cancelled_at": null, + "failed_at": null, + "completed_at": 1699075073, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ + { + "type": "code_interpreter" + } + ], + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "file-abc123", + "file-abc456" + ] + } + }, + "metadata": { + "user_id": "user_abc123" + }, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + }, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true + } + /threads/{thread_id}/runs/{run_id}/cancel: + post: + operationId: cancelRun + tags: + - Assistants + summary: Cancels a run that is `in_progress`. + parameters: + - in: path + name: thread_id + required: true + schema: + type: string + description: The ID of the thread to which this run belongs. + - in: path + name: run_id + required: true + schema: + type: string + description: The ID of the run to cancel. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/RunObject" + x-oaiMeta: + name: Cancel a run + group: threads + beta: true + returns: The modified [run](/docs/api-reference/runs/object) object matching the + specified ID. + examples: + request: + curl: | + curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/cancel \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" \ + -X POST + python: | + from openai import OpenAI + client = OpenAI() + + run = client.beta.threads.runs.cancel( + thread_id="thread_abc123", + run_id="run_abc123" + ) + + print(run) + node.js: | + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const run = await openai.beta.threads.runs.cancel( + "thread_abc123", + "run_abc123" + ); + + console.log(run); + } + + main(); + response: | + { + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699076126, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "cancelling", + "started_at": 1699076126, + "expires_at": 1699076726, + "cancelled_at": null, + "failed_at": null, + "completed_at": null, + "last_error": null, + "model": "gpt-4o", + "instructions": "You summarize books.", + "tools": [ + { + "type": "file_search" + } + ], + "tool_resources": { + "file_search": { + "vector_store_ids": ["vs_123"] + } + }, + "metadata": {}, + "usage": null, + "temperature": 1.0, + "top_p": 1.0, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true + } + /threads/{thread_id}/runs/{run_id}/steps: + get: + operationId: listRunSteps + tags: + - Assistants + summary: Returns a list of run steps belonging to a run. + parameters: + - name: thread_id + in: path + required: true + schema: + type: string + description: The ID of the thread the run and run steps belong to. + - name: run_id + in: path + required: true + schema: + type: string + description: The ID of the run the run steps belong to. + - name: limit + in: query + description: > + A limit on the number of objects to be returned. Limit can range + between 1 and 100, and the default is 20. + required: false + schema: + type: integer + default: 20 + - name: order + in: query + description: > + Sort order by the `created_at` timestamp of the objects. `asc` for + ascending order and `desc` for descending order. + schema: + type: string + default: desc + enum: + - asc + - desc + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + schema: + type: string + - name: before + in: query + description: > + A cursor for use in pagination. `before` is an object ID that + defines your place in the list. For instance, if you make a list + request and receive 100 objects, starting with obj_foo, your + subsequent call can include before=obj_foo in order to fetch the + previous page of the list. + schema: + type: string + - name: include[] + in: query + description: | + A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. + + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + schema: + type: array + items: + type: string + enum: + - step_details.tool_calls[*].file_search.results[*].content + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ListRunStepsResponse" + x-oaiMeta: + name: List run steps + group: threads + beta: true + returns: A list of [run step](/docs/api-reference/run-steps/step-object) + objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" + python: | + from openai import OpenAI + client = OpenAI() + + run_steps = client.beta.threads.runs.steps.list( + thread_id="thread_abc123", + run_id="run_abc123" + ) + + print(run_steps) + node.js: | + import OpenAI from "openai"; + const openai = new OpenAI(); + + async function main() { + const runStep = await openai.beta.threads.runs.steps.list( + "thread_abc123", + "run_abc123" + ); + console.log(runStep); + } + + main(); + response: | + { + "object": "list", + "data": [ + { + "id": "step_abc123", + "object": "thread.run.step", + "created_at": 1699063291, + "run_id": "run_abc123", + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "type": "message_creation", + "status": "completed", + "cancelled_at": null, + "completed_at": 1699063291, + "expired_at": null, + "failed_at": null, + "last_error": null, + "step_details": { + "type": "message_creation", + "message_creation": { + "message_id": "msg_abc123" + } + }, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + } + } + ], + "first_id": "step_abc123", + "last_id": "step_abc456", + "has_more": false + } + /threads/{thread_id}/runs/{run_id}/steps/{step_id}: + get: + operationId: getRunStep + tags: + - Assistants + summary: Retrieves a run step. + parameters: + - in: path + name: thread_id + required: true + schema: + type: string + description: The ID of the thread to which the run and run step belongs. + - in: path + name: run_id + required: true + schema: + type: string + description: The ID of the run to which the run step belongs. + - in: path + name: step_id + required: true + schema: + type: string + description: The ID of the run step to retrieve. + - name: include[] + in: query + description: | + A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. + + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + schema: + type: array + items: + type: string + enum: + - step_details.tool_calls[*].file_search.results[*].content + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/RunStepObject" + x-oaiMeta: + name: Retrieve run step + group: threads + beta: true + returns: The [run step](/docs/api-reference/run-steps/step-object) object + matching the specified ID. + examples: + request: + curl: | + curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps/step_abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" + python: | + from openai import OpenAI + client = OpenAI() + + run_step = client.beta.threads.runs.steps.retrieve( + thread_id="thread_abc123", + run_id="run_abc123", + step_id="step_abc123" + ) + + print(run_step) + node.js: | + import OpenAI from "openai"; + const openai = new OpenAI(); + + async function main() { + const runStep = await openai.beta.threads.runs.steps.retrieve( + "thread_abc123", + "run_abc123", + "step_abc123" + ); + console.log(runStep); + } + + main(); + response: | + { + "id": "step_abc123", + "object": "thread.run.step", + "created_at": 1699063291, + "run_id": "run_abc123", + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "type": "message_creation", + "status": "completed", + "cancelled_at": null, + "completed_at": 1699063291, + "expired_at": null, + "failed_at": null, + "last_error": null, + "step_details": { + "type": "message_creation", + "message_creation": { + "message_id": "msg_abc123" + } + }, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + } + } + /threads/{thread_id}/runs/{run_id}/submit_tool_outputs: + post: + operationId: submitToolOuputsToRun + tags: + - Assistants + summary: > + When a run has the `status: "requires_action"` and + `required_action.type` is `submit_tool_outputs`, this endpoint can be + used to submit the outputs from the tool calls once they're all + completed. All outputs must be submitted in a single request. + parameters: + - in: path + name: thread_id + required: true + schema: + type: string + description: The ID of the [thread](/docs/api-reference/threads) to which this + run belongs. + - in: path + name: run_id + required: true + schema: + type: string + description: The ID of the run that requires the tool output submission. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/SubmitToolOutputsRunRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/RunObject" + x-oaiMeta: + name: Submit tool outputs to run + group: threads + beta: true + returns: The modified [run](/docs/api-reference/runs/object) object matching the + specified ID. + examples: + - title: Default + request: + curl: | + curl https://api.openai.com/v1/threads/thread_123/runs/run_123/submit_tool_outputs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "tool_outputs": [ + { + "tool_call_id": "call_001", + "output": "70 degrees and sunny." + } + ] + }' + python: | + from openai import OpenAI + client = OpenAI() + + run = client.beta.threads.runs.submit_tool_outputs( + thread_id="thread_123", + run_id="run_123", + tool_outputs=[ + { + "tool_call_id": "call_001", + "output": "70 degrees and sunny." + } + ] + ) + + print(run) + node.js: | + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const run = await openai.beta.threads.runs.submitToolOutputs( + "thread_123", + "run_123", + { + tool_outputs: [ + { + tool_call_id: "call_001", + output: "70 degrees and sunny.", + }, + ], + } + ); + + console.log(run); + } + + main(); + response: > + { + "id": "run_123", + "object": "thread.run", + "created_at": 1699075592, + "assistant_id": "asst_123", + "thread_id": "thread_123", + "status": "queued", + "started_at": 1699075592, + "expires_at": 1699076192, + "cancelled_at": null, + "failed_at": null, + "completed_at": null, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "tools": [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": ["celsius", "fahrenheit"] + } + }, + "required": ["location"] + } + } + } + ], + "metadata": {}, + "usage": null, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true + } + - title: Streaming + request: + curl: | + curl https://api.openai.com/v1/threads/thread_123/runs/run_123/submit_tool_outputs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "tool_outputs": [ + { + "tool_call_id": "call_001", + "output": "70 degrees and sunny." + } + ], + "stream": true + }' + python: | + from openai import OpenAI + client = OpenAI() + + stream = client.beta.threads.runs.submit_tool_outputs( + thread_id="thread_123", + run_id="run_123", + tool_outputs=[ + { + "tool_call_id": "call_001", + "output": "70 degrees and sunny." + } + ], + stream=True + ) + + for event in stream: + print(event) + node.js: > + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + async function main() { + const stream = await openai.beta.threads.runs.submitToolOutputs( + "thread_123", + "run_123", + { + tool_outputs: [ + { + tool_call_id: "call_001", + output: "70 degrees and sunny.", + }, + ], + } + ); + + for await (const event of stream) { + console.log(event); + } + } + + + main(); + response: | + event: thread.run.step.completed + data: {"id":"step_001","object":"thread.run.step","created_at":1710352449,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"completed","cancelled_at":null,"completed_at":1710352475,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[{"id":"call_iWr0kQ2EaYMaxNdl0v3KYkx7","type":"function","function":{"name":"get_current_weather","arguments":"{\"location\":\"San Francisco, CA\",\"unit\":\"fahrenheit\"}","output":"70 degrees and sunny."}}]},"usage":{"prompt_tokens":291,"completion_tokens":24,"total_tokens":315}} + + event: thread.run.queued + data: {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":1710352448,"expires_at":1710353047,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + + event: thread.run.in_progress + data: {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710352475,"expires_at":1710353047,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + + event: thread.run.step.created + data: {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":null} + + event: thread.run.step.in_progress + data: {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":null} + + event: thread.message.created + data: {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + + event: thread.message.in_progress + data: {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + + event: thread.message.delta + data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"The","annotations":[]}}]}} + + event: thread.message.delta + data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" current"}}]}} + + event: thread.message.delta + data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" weather"}}]}} + + ... + + event: thread.message.delta + data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" sunny"}}]}} + + event: thread.message.delta + data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"."}}]}} + + event: thread.message.completed + data: {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710352477,"role":"assistant","content":[{"type":"text","text":{"value":"The current weather in San Francisco, CA is 70 degrees Fahrenheit and sunny.","annotations":[]}}],"metadata":{}} + + event: thread.run.step.completed + data: {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710352477,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":{"prompt_tokens":329,"completion_tokens":18,"total_tokens":347}} + + event: thread.run.completed + data: {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710352475,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710352477,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + + event: done + data: [DONE] + /uploads: + post: + operationId: createUpload + tags: + - Uploads + summary: > + Creates an intermediate [Upload](/docs/api-reference/uploads/object) + object + + that you can add [Parts](/docs/api-reference/uploads/part-object) to. + + Currently, an Upload can accept at most 8 GB in total and expires after + an + + hour after you create it. + + + Once you complete the Upload, we will create a + + [File](/docs/api-reference/files/object) object that contains all the + parts + + you uploaded. This File is usable in the rest of our platform as a + regular + + File object. + + + For certain `purpose` values, the correct `mime_type` must be + specified. + + Please refer to documentation for the + + [supported MIME types for your use + case](/docs/assistants/tools/file-search#supported-files). + + + For guidance on the proper filename extensions for each purpose, please + + follow the documentation on [creating a + + File](/docs/api-reference/files/create). + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateUploadRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/Upload" + x-oaiMeta: + name: Create upload + group: uploads + returns: The [Upload](/docs/api-reference/uploads/object) object with status + `pending`. + examples: + request: + curl: | + curl https://api.openai.com/v1/uploads \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "purpose": "fine-tune", + "filename": "training_examples.jsonl", + "bytes": 2147483648, + "mime_type": "text/jsonl" + }' + response: | + { + "id": "upload_abc123", + "object": "upload", + "bytes": 2147483648, + "created_at": 1719184911, + "filename": "training_examples.jsonl", + "purpose": "fine-tune", + "status": "pending", + "expires_at": 1719127296 + } + /uploads/{upload_id}/cancel: + post: + operationId: cancelUpload + tags: + - Uploads + summary: | + Cancels the Upload. No Parts may be added after an Upload is cancelled. + parameters: + - in: path + name: upload_id + required: true + schema: + type: string + example: upload_abc123 + description: | + The ID of the Upload. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/Upload" + x-oaiMeta: + name: Cancel upload + group: uploads + returns: The [Upload](/docs/api-reference/uploads/object) object with status + `cancelled`. + examples: + request: + curl: | + curl https://api.openai.com/v1/uploads/upload_abc123/cancel + response: | + { + "id": "upload_abc123", + "object": "upload", + "bytes": 2147483648, + "created_at": 1719184911, + "filename": "training_examples.jsonl", + "purpose": "fine-tune", + "status": "cancelled", + "expires_at": 1719127296 + } + /uploads/{upload_id}/complete: + post: + operationId: completeUpload + tags: + - Uploads + summary: > + Completes the [Upload](/docs/api-reference/uploads/object). + + + Within the returned Upload object, there is a nested + [File](/docs/api-reference/files/object) object that is ready to use in + the rest of the platform. + + + You can specify the order of the Parts by passing in an ordered list of + the Part IDs. + + + The number of bytes uploaded upon completion must match the number of + bytes initially specified when creating the Upload object. No Parts may + be added after an Upload is completed. + parameters: + - in: path + name: upload_id + required: true + schema: + type: string + example: upload_abc123 + description: | + The ID of the Upload. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CompleteUploadRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/Upload" + x-oaiMeta: + name: Complete upload + group: uploads + returns: The [Upload](/docs/api-reference/uploads/object) object with status + `completed` with an additional `file` property containing the created + usable File object. + examples: + request: + curl: | + curl https://api.openai.com/v1/uploads/upload_abc123/complete + -d '{ + "part_ids": ["part_def456", "part_ghi789"] + }' + response: | + { + "id": "upload_abc123", + "object": "upload", + "bytes": 2147483648, + "created_at": 1719184911, + "filename": "training_examples.jsonl", + "purpose": "fine-tune", + "status": "completed", + "expires_at": 1719127296, + "file": { + "id": "file-xyz321", + "object": "file", + "bytes": 2147483648, + "created_at": 1719186911, + "filename": "training_examples.jsonl", + "purpose": "fine-tune", + } + } + /uploads/{upload_id}/parts: + post: + operationId: addUploadPart + tags: + - Uploads + summary: > + Adds a [Part](/docs/api-reference/uploads/part-object) to an + [Upload](/docs/api-reference/uploads/object) object. A Part represents a + chunk of bytes from the file you are trying to upload. + + + Each Part can be at most 64 MB, and you can add Parts until you hit the + Upload maximum of 8 GB. + + + It is possible to add multiple Parts in parallel. You can decide the + intended order of the Parts when you [complete the + Upload](/docs/api-reference/uploads/complete). + parameters: + - in: path + name: upload_id + required: true + schema: + type: string + example: upload_abc123 + description: | + The ID of the Upload. + requestBody: + required: true + content: + multipart/form-data: + schema: + $ref: "#/components/schemas/AddUploadPartRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/UploadPart" + x-oaiMeta: + name: Add upload part + group: uploads + returns: The upload [Part](/docs/api-reference/uploads/part-object) object. + examples: + request: + curl: | + curl https://api.openai.com/v1/uploads/upload_abc123/parts + -F data="aHR0cHM6Ly9hcGkub3BlbmFpLmNvbS92MS91cGxvYWRz..." + response: | + { + "id": "part_def456", + "object": "upload.part", + "created_at": 1719185911, + "upload_id": "upload_abc123" + } + /vector_stores: + get: + operationId: listVectorStores + tags: + - Vector stores + summary: Returns a list of vector stores. + parameters: + - name: limit + in: query + description: > + A limit on the number of objects to be returned. Limit can range + between 1 and 100, and the default is 20. + required: false + schema: + type: integer + default: 20 + - name: order + in: query + description: > + Sort order by the `created_at` timestamp of the objects. `asc` for + ascending order and `desc` for descending order. + schema: + type: string + default: desc + enum: + - asc + - desc + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + schema: + type: string + - name: before + in: query + description: > + A cursor for use in pagination. `before` is an object ID that + defines your place in the list. For instance, if you make a list + request and receive 100 objects, starting with obj_foo, your + subsequent call can include before=obj_foo in order to fetch the + previous page of the list. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ListVectorStoresResponse" + x-oaiMeta: + name: List vector stores + group: vector_stores + returns: A list of [vector store](/docs/api-reference/vector-stores/object) + objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/vector_stores \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" + python: | + from openai import OpenAI + client = OpenAI() + + vector_stores = client.vector_stores.list() + print(vector_stores) + node.js: | + import OpenAI from "openai"; + const openai = new OpenAI(); + + async function main() { + const vectorStores = await openai.vectorStores.list(); + console.log(vectorStores); + } + + main(); + response: | + { + "object": "list", + "data": [ + { + "id": "vs_abc123", + "object": "vector_store", + "created_at": 1699061776, + "name": "Support FAQ", + "bytes": 139920, + "file_counts": { + "in_progress": 0, + "completed": 3, + "failed": 0, + "cancelled": 0, + "total": 3 + } + }, + { + "id": "vs_abc456", + "object": "vector_store", + "created_at": 1699061776, + "name": "Support FAQ v2", + "bytes": 139920, + "file_counts": { + "in_progress": 0, + "completed": 3, + "failed": 0, + "cancelled": 0, + "total": 3 + } + } + ], + "first_id": "vs_abc123", + "last_id": "vs_abc456", + "has_more": false + } + post: + operationId: createVectorStore + tags: + - Vector stores + summary: Create a vector store. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateVectorStoreRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/VectorStoreObject" + x-oaiMeta: + name: Create vector store + group: vector_stores + returns: A [vector store](/docs/api-reference/vector-stores/object) object. + examples: + request: + curl: | + curl https://api.openai.com/v1/vector_stores \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "name": "Support FAQ" + }' + python: | + from openai import OpenAI + client = OpenAI() + + vector_store = client.vector_stores.create( + name="Support FAQ" + ) + print(vector_store) + node.js: | + import OpenAI from "openai"; + const openai = new OpenAI(); + + async function main() { + const vectorStore = await openai.vectorStores.create({ + name: "Support FAQ" + }); + console.log(vectorStore); + } + + main(); + response: | + { + "id": "vs_abc123", + "object": "vector_store", + "created_at": 1699061776, + "name": "Support FAQ", + "bytes": 139920, + "file_counts": { + "in_progress": 0, + "completed": 3, + "failed": 0, + "cancelled": 0, + "total": 3 + } + } + /vector_stores/{vector_store_id}: + get: + operationId: getVectorStore + tags: + - Vector stores + summary: Retrieves a vector store. + parameters: + - in: path + name: vector_store_id + required: true + schema: + type: string + description: The ID of the vector store to retrieve. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/VectorStoreObject" + x-oaiMeta: + name: Retrieve vector store + group: vector_stores + returns: The [vector store](/docs/api-reference/vector-stores/object) object + matching the specified ID. + examples: + request: + curl: | + curl https://api.openai.com/v1/vector_stores/vs_abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" + python: | + from openai import OpenAI + client = OpenAI() + + vector_store = client.vector_stores.retrieve( + vector_store_id="vs_abc123" + ) + print(vector_store) + node.js: | + import OpenAI from "openai"; + const openai = new OpenAI(); + + async function main() { + const vectorStore = await openai.vectorStores.retrieve( + "vs_abc123" + ); + console.log(vectorStore); + } + + main(); + response: | + { + "id": "vs_abc123", + "object": "vector_store", + "created_at": 1699061776 + } + post: + operationId: modifyVectorStore + tags: + - Vector stores + summary: Modifies a vector store. + parameters: + - in: path + name: vector_store_id + required: true + schema: + type: string + description: The ID of the vector store to modify. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/UpdateVectorStoreRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/VectorStoreObject" + x-oaiMeta: + name: Modify vector store + group: vector_stores + returns: The modified [vector store](/docs/api-reference/vector-stores/object) + object. + examples: + request: + curl: | + curl https://api.openai.com/v1/vector_stores/vs_abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" + -d '{ + "name": "Support FAQ" + }' + python: | + from openai import OpenAI + client = OpenAI() + + vector_store = client.vector_stores.update( + vector_store_id="vs_abc123", + name="Support FAQ" + ) + print(vector_store) + node.js: | + import OpenAI from "openai"; + const openai = new OpenAI(); + + async function main() { + const vectorStore = await openai.vectorStores.update( + "vs_abc123", + { + name: "Support FAQ" + } + ); + console.log(vectorStore); + } + + main(); + response: | + { + "id": "vs_abc123", + "object": "vector_store", + "created_at": 1699061776, + "name": "Support FAQ", + "bytes": 139920, + "file_counts": { + "in_progress": 0, + "completed": 3, + "failed": 0, + "cancelled": 0, + "total": 3 + } + } + delete: + operationId: deleteVectorStore + tags: + - Vector stores + summary: Delete a vector store. + parameters: + - in: path + name: vector_store_id + required: true + schema: + type: string + description: The ID of the vector store to delete. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/DeleteVectorStoreResponse" + x-oaiMeta: + name: Delete vector store + group: vector_stores + returns: Deletion status + examples: + request: + curl: | + curl https://api.openai.com/v1/vector_stores/vs_abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -X DELETE + python: | + from openai import OpenAI + client = OpenAI() + + deleted_vector_store = client.vector_stores.delete( + vector_store_id="vs_abc123" + ) + print(deleted_vector_store) + node.js: | + import OpenAI from "openai"; + const openai = new OpenAI(); + + async function main() { + const deletedVectorStore = await openai.vectorStores.del( + "vs_abc123" + ); + console.log(deletedVectorStore); + } + + main(); + response: | + { + id: "vs_abc123", + object: "vector_store.deleted", + deleted: true + } + /vector_stores/{vector_store_id}/file_batches: + post: + operationId: createVectorStoreFileBatch + tags: + - Vector stores + summary: Create a vector store file batch. + parameters: + - in: path + name: vector_store_id + required: true + schema: + type: string + example: vs_abc123 + description: | + The ID of the vector store for which to create a File Batch. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateVectorStoreFileBatchRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/VectorStoreFileBatchObject" + x-oaiMeta: + name: Create vector store file batch + group: vector_stores + returns: A [vector store file + batch](/docs/api-reference/vector-stores-file-batches/batch-object) + object. + examples: + request: + curl: > + curl + https://api.openai.com/v1/vector_stores/vs_abc123/file_batches \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "file_ids": ["file-abc123", "file-abc456"] + }' + python: > + from openai import OpenAI + + client = OpenAI() + + + vector_store_file_batch = + client.vector_stores.file_batches.create( + vector_store_id="vs_abc123", + file_ids=["file-abc123", "file-abc456"] + ) + + print(vector_store_file_batch) + node.js: > + import OpenAI from "openai"; + + const openai = new OpenAI(); + + + async function main() { + const myVectorStoreFileBatch = await openai.vectorStores.fileBatches.create( + "vs_abc123", + { + file_ids: ["file-abc123", "file-abc456"] + } + ); + console.log(myVectorStoreFileBatch); + } + + + main(); + response: | + { + "id": "vsfb_abc123", + "object": "vector_store.file_batch", + "created_at": 1699061776, + "vector_store_id": "vs_abc123", + "status": "in_progress", + "file_counts": { + "in_progress": 1, + "completed": 1, + "failed": 0, + "cancelled": 0, + "total": 0, + } + } + /vector_stores/{vector_store_id}/file_batches/{batch_id}: + get: + operationId: getVectorStoreFileBatch + tags: + - Vector stores + summary: Retrieves a vector store file batch. + parameters: + - in: path + name: vector_store_id + required: true + schema: + type: string + example: vs_abc123 + description: The ID of the vector store that the file batch belongs to. + - in: path + name: batch_id + required: true + schema: + type: string + example: vsfb_abc123 + description: The ID of the file batch being retrieved. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/VectorStoreFileBatchObject" + x-oaiMeta: + name: Retrieve vector store file batch + group: vector_stores + returns: The [vector store file + batch](/docs/api-reference/vector-stores-file-batches/batch-object) + object. + examples: + request: + curl: | + curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" + python: > + from openai import OpenAI + + client = OpenAI() + + + vector_store_file_batch = + client.vector_stores.file_batches.retrieve( + vector_store_id="vs_abc123", + batch_id="vsfb_abc123" + ) + + print(vector_store_file_batch) + node.js: > + import OpenAI from "openai"; + + const openai = new OpenAI(); + + + async function main() { + const vectorStoreFileBatch = await openai.vectorStores.fileBatches.retrieve( + "vs_abc123", + "vsfb_abc123" + ); + console.log(vectorStoreFileBatch); + } + + + main(); + response: | + { + "id": "vsfb_abc123", + "object": "vector_store.file_batch", + "created_at": 1699061776, + "vector_store_id": "vs_abc123", + "status": "in_progress", + "file_counts": { + "in_progress": 1, + "completed": 1, + "failed": 0, + "cancelled": 0, + "total": 0, + } + } + /vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel: + post: + operationId: cancelVectorStoreFileBatch + tags: + - Vector stores + summary: Cancel a vector store file batch. This attempts to cancel the + processing of files in this batch as soon as possible. + parameters: + - in: path + name: vector_store_id + required: true + schema: + type: string + description: The ID of the vector store that the file batch belongs to. + - in: path + name: batch_id + required: true + schema: + type: string + description: The ID of the file batch to cancel. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/VectorStoreFileBatchObject" + x-oaiMeta: + name: Cancel vector store file batch + group: vector_stores + returns: The modified vector store file batch object. + examples: + request: + curl: | + curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123/cancel \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -X POST + python: > + from openai import OpenAI + + client = OpenAI() + + + deleted_vector_store_file_batch = + client.vector_stores.file_batches.cancel( + vector_store_id="vs_abc123", + file_batch_id="vsfb_abc123" + ) + + print(deleted_vector_store_file_batch) + node.js: > + import OpenAI from "openai"; + + const openai = new OpenAI(); + + + async function main() { + const deletedVectorStoreFileBatch = await openai.vectorStores.fileBatches.cancel( + "vs_abc123", + "vsfb_abc123" + ); + console.log(deletedVectorStoreFileBatch); + } + + + main(); + response: | + { + "id": "vsfb_abc123", + "object": "vector_store.file_batch", + "created_at": 1699061776, + "vector_store_id": "vs_abc123", + "status": "in_progress", + "file_counts": { + "in_progress": 12, + "completed": 3, + "failed": 0, + "cancelled": 0, + "total": 15, + } + } + /vector_stores/{vector_store_id}/file_batches/{batch_id}/files: + get: + operationId: listFilesInVectorStoreBatch + tags: + - Vector stores + summary: Returns a list of vector store files in a batch. + parameters: + - name: vector_store_id + in: path + description: The ID of the vector store that the files belong to. + required: true + schema: + type: string + - name: batch_id + in: path + description: The ID of the file batch that the files belong to. + required: true + schema: + type: string + - name: limit + in: query + description: > + A limit on the number of objects to be returned. Limit can range + between 1 and 100, and the default is 20. + required: false + schema: + type: integer + default: 20 + - name: order + in: query + description: > + Sort order by the `created_at` timestamp of the objects. `asc` for + ascending order and `desc` for descending order. + schema: + type: string + default: desc + enum: + - asc + - desc + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + schema: + type: string + - name: before + in: query + description: > + A cursor for use in pagination. `before` is an object ID that + defines your place in the list. For instance, if you make a list + request and receive 100 objects, starting with obj_foo, your + subsequent call can include before=obj_foo in order to fetch the + previous page of the list. + schema: + type: string + - name: filter + in: query + description: Filter by file status. One of `in_progress`, `completed`, `failed`, + `cancelled`. + schema: + type: string + enum: + - in_progress + - completed + - failed + - cancelled + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ListVectorStoreFilesResponse" + x-oaiMeta: + name: List vector store files in a batch + group: vector_stores + returns: A list of [vector store + file](/docs/api-reference/vector-stores-files/file-object) objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123/files \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" + python: | + from openai import OpenAI + client = OpenAI() + + vector_store_files = client.vector_stores.file_batches.list_files( + vector_store_id="vs_abc123", + batch_id="vsfb_abc123" + ) + print(vector_store_files) + node.js: > + import OpenAI from "openai"; + + const openai = new OpenAI(); + + + async function main() { + const vectorStoreFiles = await openai.vectorStores.fileBatches.listFiles( + "vs_abc123", + "vsfb_abc123" + ); + console.log(vectorStoreFiles); + } + + + main(); + response: | + { + "object": "list", + "data": [ + { + "id": "file-abc123", + "object": "vector_store.file", + "created_at": 1699061776, + "vector_store_id": "vs_abc123" + }, + { + "id": "file-abc456", + "object": "vector_store.file", + "created_at": 1699061776, + "vector_store_id": "vs_abc123" + } + ], + "first_id": "file-abc123", + "last_id": "file-abc456", + "has_more": false + } + /vector_stores/{vector_store_id}/files: + get: + operationId: listVectorStoreFiles + tags: + - Vector stores + summary: Returns a list of vector store files. + parameters: + - name: vector_store_id + in: path + description: The ID of the vector store that the files belong to. + required: true + schema: + type: string + - name: limit + in: query + description: > + A limit on the number of objects to be returned. Limit can range + between 1 and 100, and the default is 20. + required: false + schema: + type: integer + default: 20 + - name: order + in: query + description: > + Sort order by the `created_at` timestamp of the objects. `asc` for + ascending order and `desc` for descending order. + schema: + type: string + default: desc + enum: + - asc + - desc + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + schema: + type: string + - name: before + in: query + description: > + A cursor for use in pagination. `before` is an object ID that + defines your place in the list. For instance, if you make a list + request and receive 100 objects, starting with obj_foo, your + subsequent call can include before=obj_foo in order to fetch the + previous page of the list. + schema: + type: string + - name: filter + in: query + description: Filter by file status. One of `in_progress`, `completed`, `failed`, + `cancelled`. + schema: + type: string + enum: + - in_progress + - completed + - failed + - cancelled + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ListVectorStoreFilesResponse" + x-oaiMeta: + name: List vector store files + group: vector_stores + returns: A list of [vector store + file](/docs/api-reference/vector-stores-files/file-object) objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" + python: | + from openai import OpenAI + client = OpenAI() + + vector_store_files = client.vector_stores.files.list( + vector_store_id="vs_abc123" + ) + print(vector_store_files) + node.js: | + import OpenAI from "openai"; + const openai = new OpenAI(); + + async function main() { + const vectorStoreFiles = await openai.vectorStores.files.list( + "vs_abc123" + ); + console.log(vectorStoreFiles); + } + + main(); + response: | + { + "object": "list", + "data": [ + { + "id": "file-abc123", + "object": "vector_store.file", + "created_at": 1699061776, + "vector_store_id": "vs_abc123" + }, + { + "id": "file-abc456", + "object": "vector_store.file", + "created_at": 1699061776, + "vector_store_id": "vs_abc123" + } + ], + "first_id": "file-abc123", + "last_id": "file-abc456", + "has_more": false + } + post: + operationId: createVectorStoreFile + tags: + - Vector stores + summary: Create a vector store file by attaching a + [File](/docs/api-reference/files) to a [vector + store](/docs/api-reference/vector-stores/object). + parameters: + - in: path + name: vector_store_id + required: true + schema: + type: string + example: vs_abc123 + description: | + The ID of the vector store for which to create a File. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateVectorStoreFileRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/VectorStoreFileObject" + x-oaiMeta: + name: Create vector store file + group: vector_stores + returns: A [vector store + file](/docs/api-reference/vector-stores-files/file-object) object. + examples: + request: + curl: | + curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "file_id": "file-abc123" + }' + python: | + from openai import OpenAI + client = OpenAI() + + vector_store_file = client.vector_stores.files.create( + vector_store_id="vs_abc123", + file_id="file-abc123" + ) + print(vector_store_file) + node.js: > + import OpenAI from "openai"; + + const openai = new OpenAI(); + + + async function main() { + const myVectorStoreFile = await openai.vectorStores.files.create( + "vs_abc123", + { + file_id: "file-abc123" + } + ); + console.log(myVectorStoreFile); + } + + + main(); + response: | + { + "id": "file-abc123", + "object": "vector_store.file", + "created_at": 1699061776, + "usage_bytes": 1234, + "vector_store_id": "vs_abcd", + "status": "completed", + "last_error": null + } + /vector_stores/{vector_store_id}/files/{file_id}: + get: + operationId: getVectorStoreFile + tags: + - Vector stores + summary: Retrieves a vector store file. + parameters: + - in: path + name: vector_store_id + required: true + schema: + type: string + example: vs_abc123 + description: The ID of the vector store that the file belongs to. + - in: path + name: file_id + required: true + schema: + type: string + example: file-abc123 + description: The ID of the file being retrieved. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/VectorStoreFileObject" + x-oaiMeta: + name: Retrieve vector store file + group: vector_stores + returns: The [vector store + file](/docs/api-reference/vector-stores-files/file-object) object. + examples: + request: + curl: | + curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" + python: | + from openai import OpenAI + client = OpenAI() + + vector_store_file = client.vector_stores.files.retrieve( + vector_store_id="vs_abc123", + file_id="file-abc123" + ) + print(vector_store_file) + node.js: > + import OpenAI from "openai"; + + const openai = new OpenAI(); + + + async function main() { + const vectorStoreFile = await openai.vectorStores.files.retrieve( + "vs_abc123", + "file-abc123" + ); + console.log(vectorStoreFile); + } + + + main(); + response: | + { + "id": "file-abc123", + "object": "vector_store.file", + "created_at": 1699061776, + "vector_store_id": "vs_abcd", + "status": "completed", + "last_error": null + } + delete: + operationId: deleteVectorStoreFile + tags: + - Vector stores + summary: Delete a vector store file. This will remove the file from the vector + store but the file itself will not be deleted. To delete the file, use + the [delete file](/docs/api-reference/files/delete) endpoint. + parameters: + - in: path + name: vector_store_id + required: true + schema: + type: string + description: The ID of the vector store that the file belongs to. + - in: path + name: file_id + required: true + schema: + type: string + description: The ID of the file to delete. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/DeleteVectorStoreFileResponse" + x-oaiMeta: + name: Delete vector store file + group: vector_stores + returns: Deletion status + examples: + request: + curl: | + curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -X DELETE + python: | + from openai import OpenAI + client = OpenAI() + + deleted_vector_store_file = client.vector_stores.files.delete( + vector_store_id="vs_abc123", + file_id="file-abc123" + ) + print(deleted_vector_store_file) + node.js: > + import OpenAI from "openai"; + + const openai = new OpenAI(); + + + async function main() { + const deletedVectorStoreFile = await openai.vectorStores.files.del( + "vs_abc123", + "file-abc123" + ); + console.log(deletedVectorStoreFile); + } + + + main(); + response: | + { + id: "file-abc123", + object: "vector_store.file.deleted", + deleted: true + } + post: + operationId: updateVectorStoreFileAttributes + tags: + - Vector stores + summary: Update attributes on a vector store file. + parameters: + - in: path + name: vector_store_id + required: true + schema: + type: string + example: vs_abc123 + description: The ID of the vector store the file belongs to. + - in: path + name: file_id + required: true + schema: + type: string + example: file-abc123 + description: The ID of the file to update attributes. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/UpdateVectorStoreFileAttributesRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/VectorStoreFileObject" + x-oaiMeta: + name: Update vector store file attributes + group: vector_stores + returns: The updated [vector store + file](/docs/api-reference/vector-stores-files/file-object) object. + examples: + request: + curl: | + curl https://api.openai.com/v1/vector_stores/{vector_store_id}/files/{file_id} \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"attributes": {"key1": "value1", "key2": 2}}' + response: | + { + "id": "file-abc123", + "object": "vector_store.file", + "usage_bytes": 1234, + "created_at": 1699061776, + "vector_store_id": "vs_abcd", + "status": "completed", + "last_error": null, + "chunking_strategy": {...}, + "attributes": {"key1": "value1", "key2": 2} + } + /vector_stores/{vector_store_id}/files/{file_id}/content: + get: + operationId: retrieveVectorStoreFileContent + tags: + - Vector stores + summary: Retrieve the parsed contents of a vector store file. + parameters: + - in: path + name: vector_store_id + required: true + schema: + type: string + example: vs_abc123 + description: The ID of the vector store. + - in: path + name: file_id + required: true + schema: + type: string + example: file-abc123 + description: The ID of the file within the vector store. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/VectorStoreFileContentResponse" + x-oaiMeta: + name: Retrieve vector store file content + group: vector_stores + returns: The parsed contents of the specified vector store file. + examples: + request: + curl: | + curl \ + https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content \ + -H "Authorization: Bearer $OPENAI_API_KEY" + response: | + { + "file_id": "file-abc123", + "filename": "example.txt", + "attributes": {"key": "value"}, + "content": [ + {"type": "text", "text": "..."}, + ... + ] + } + /vector_stores/{vector_store_id}/search: + post: + operationId: searchVectorStore + tags: + - Vector stores + summary: Search a vector store for relevant chunks based on a query and file + attributes filter. + parameters: + - in: path + name: vector_store_id + required: true + schema: + type: string + example: vs_abc123 + description: The ID of the vector store to search. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/VectorStoreSearchRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/VectorStoreSearchResultsPage" + x-oaiMeta: + name: Search vector store + group: vector_stores + returns: A page of search results from the vector store. + examples: + request: + curl: | + curl -X POST \ + https://api.openai.com/v1/vector_stores/vs_abc123/search \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"query": "What is the return policy?", "filters": {...}}' + response: | + { + "object": "vector_store.search_results.page", + "search_query": "What is the return policy?", + "data": [ + { + "file_id": "file_123", + "filename": "document.pdf", + "score": 0.95, + "attributes": { + "author": "John Doe", + "date": "2023-01-01" + }, + "content": [ + { + "type": "text", + "text": "Relevant chunk" + } + ] + }, + { + "file_id": "file_456", + "filename": "notes.txt", + "score": 0.89, + "attributes": { + "author": "Jane Smith", + "date": "2023-01-02" + }, + "content": [ + { + "type": "text", + "text": "Sample text content from the vector store." + } + ] + } + ], + "has_more": false, + "next_page": null + } +components: + schemas: + AddUploadPartRequest: + type: object + additionalProperties: false + properties: + data: + description: | + The chunk of bytes for this Part. + type: string + format: binary + required: + - data + AdminApiKey: + type: object + description: Represents an individual Admin API key in an org. + properties: + object: + type: string + example: organization.admin_api_key + description: The object type, which is always `organization.admin_api_key` + x-stainless-const: true + id: + type: string + example: key_abc + description: The identifier, which can be referenced in API endpoints + name: + type: string + example: Administration Key + description: The name of the API key + redacted_value: + type: string + example: sk-admin...def + description: The redacted value of the API key + value: + type: string + example: sk-admin-1234abcd + description: The value of the API key. Only shown on create. + created_at: + type: integer + format: int64 + example: 1711471533 + description: The Unix timestamp (in seconds) of when the API key was created + last_used_at: + type: integer + format: int64 + nullable: true + example: 1711471534 + description: The Unix timestamp (in seconds) of when the API key was last used + owner: + type: object + properties: + type: + type: string + example: user + description: Always `user` + object: + type: string + example: organization.user + description: The object type, which is always organization.user + id: + type: string + example: sa_456 + description: The identifier, which can be referenced in API endpoints + name: + type: string + example: My Service Account + description: The name of the user + created_at: + type: integer + format: int64 + example: 1711471533 + description: The Unix timestamp (in seconds) of when the user was created + role: + type: string + example: owner + description: Always `owner` + required: + - object + - redacted_value + - name + - created_at + - last_used_at + - id + - owner + x-oaiMeta: + name: The admin API key object + example: | + { + "object": "organization.admin_api_key", + "id": "key_abc", + "name": "Main Admin Key", + "redacted_value": "sk-admin...xyz", + "created_at": 1711471533, + "last_used_at": 1711471534, + "owner": { + "type": "user", + "object": "organization.user", + "id": "user_123", + "name": "John Doe", + "created_at": 1711471533, + "role": "owner" + } + } + ApiKeyList: + type: object + properties: + object: + type: string + example: list + data: + type: array + items: + $ref: "#/components/schemas/AdminApiKey" + has_more: + type: boolean + example: false + first_id: + type: string + example: key_abc + last_id: + type: string + example: key_xyz + AssistantObject: + type: object + title: Assistant + description: Represents an `assistant` that can call the model and use tools. + properties: + id: + description: The identifier, which can be referenced in API endpoints. + type: string + object: + description: The object type, which is always `assistant`. + type: string + enum: + - assistant + x-stainless-const: true + created_at: + description: The Unix timestamp (in seconds) for when the assistant was created. + type: integer + name: + description: | + The name of the assistant. The maximum length is 256 characters. + type: string + maxLength: 256 + nullable: true + description: + description: > + The description of the assistant. The maximum length is 512 + characters. + type: string + maxLength: 512 + nullable: true + model: + description: > + ID of the model to use. You can use the [List + models](/docs/api-reference/models/list) API to see all of your + available models, or see our [Model overview](/docs/models) for + descriptions of them. + type: string + instructions: + description: > + The system instructions that the assistant uses. The maximum length + is 256,000 characters. + type: string + maxLength: 256000 + nullable: true + tools: + description: > + A list of tool enabled on the assistant. There can be a maximum of + 128 tools per assistant. Tools can be of types `code_interpreter`, + `file_search`, or `function`. + default: [] + type: array + maxItems: 128 + items: + oneOf: + - $ref: "#/components/schemas/AssistantToolsCode" + - $ref: "#/components/schemas/AssistantToolsFileSearch" + - $ref: "#/components/schemas/AssistantToolsFunction" + tool_resources: + type: object + description: > + A set of resources that are used by the assistant's tools. The + resources are specific to the type of tool. For example, the + `code_interpreter` tool requires a list of file IDs, while the + `file_search` tool requires a list of vector store IDs. + properties: + code_interpreter: + type: object + properties: + file_ids: + type: array + description: > + A list of [file](/docs/api-reference/files) IDs made + available to the `code_interpreter`` tool. There can be a + maximum of 20 files associated with the tool. + default: [] + maxItems: 20 + items: + type: string + file_search: + type: object + properties: + vector_store_ids: + type: array + description: > + The ID of the [vector + store](/docs/api-reference/vector-stores/object) attached to + this assistant. There can be a maximum of 1 vector store + attached to the assistant. + maxItems: 1 + items: + type: string + nullable: true + metadata: + $ref: "#/components/schemas/Metadata" + temperature: + description: > + What sampling temperature to use, between 0 and 2. Higher values + like 0.8 will make the output more random, while lower values like + 0.2 will make it more focused and deterministic. + type: number + minimum: 0 + maximum: 2 + default: 1 + example: 1 + nullable: true + top_p: + type: number + minimum: 0 + maximum: 1 + default: 1 + example: 1 + nullable: true + description: > + An alternative to sampling with temperature, called nucleus + sampling, where the model considers the results of the tokens with + top_p probability mass. So 0.1 means only the tokens comprising the + top 10% probability mass are considered. + + + We generally recommend altering this or temperature but not both. + response_format: + $ref: "#/components/schemas/AssistantsApiResponseFormatOption" + nullable: true + required: + - id + - object + - created_at + - name + - description + - model + - instructions + - tools + - metadata + x-oaiMeta: + name: The assistant object + beta: true + example: > + { + "id": "asst_abc123", + "object": "assistant", + "created_at": 1698984975, + "name": "Math Tutor", + "description": null, + "model": "gpt-4o", + "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.", + "tools": [ + { + "type": "code_interpreter" + } + ], + "metadata": {}, + "top_p": 1.0, + "temperature": 1.0, + "response_format": "auto" + } + AssistantStreamEvent: + description: > + Represents an event emitted when streaming a Run. + + + Each event in a server-sent events stream has an `event` and `data` + property: + + + ``` + + event: thread.created + + data: {"id": "thread_123", "object": "thread", ...} + + ``` + + + We emit events whenever a new object is created, transitions to a new + state, or is being + + streamed in parts (deltas). For example, we emit `thread.run.created` + when a new run + + is created, `thread.run.completed` when a run completes, and so on. When + an Assistant chooses + + to create a message during a run, we emit a `thread.message.created + event`, a + + `thread.message.in_progress` event, many `thread.message.delta` events, + and finally a + + `thread.message.completed` event. + + + We may add additional events over time, so we recommend handling unknown + events gracefully + + in your code. See the [Assistants API + quickstart](/docs/assistants/overview) to learn how to + + integrate the Assistants API with streaming. + oneOf: + - $ref: "#/components/schemas/ThreadStreamEvent" + - $ref: "#/components/schemas/RunStreamEvent" + - $ref: "#/components/schemas/RunStepStreamEvent" + - $ref: "#/components/schemas/MessageStreamEvent" + - $ref: "#/components/schemas/ErrorEvent" + - $ref: "#/components/schemas/DoneEvent" + x-oaiMeta: + name: Assistant stream events + beta: true + AssistantSupportedModels: + type: string + enum: + - gpt-4.1 + - gpt-4.1-mini + - gpt-4.1-nano + - gpt-4.1-2025-04-14 + - gpt-4.1-mini-2025-04-14 + - gpt-4.1-nano-2025-04-14 + - o3-mini + - o3-mini-2025-01-31 + - o1 + - o1-2024-12-17 + - gpt-4o + - gpt-4o-2024-11-20 + - gpt-4o-2024-08-06 + - gpt-4o-2024-05-13 + - gpt-4o-mini + - gpt-4o-mini-2024-07-18 + - gpt-4.5-preview + - gpt-4.5-preview-2025-02-27 + - gpt-4-turbo + - gpt-4-turbo-2024-04-09 + - gpt-4-0125-preview + - gpt-4-turbo-preview + - gpt-4-1106-preview + - gpt-4-vision-preview + - gpt-4 + - gpt-4-0314 + - gpt-4-0613 + - gpt-4-32k + - gpt-4-32k-0314 + - gpt-4-32k-0613 + - gpt-3.5-turbo + - gpt-3.5-turbo-16k + - gpt-3.5-turbo-0613 + - gpt-3.5-turbo-1106 + - gpt-3.5-turbo-0125 + - gpt-3.5-turbo-16k-0613 + AssistantToolsCode: + type: object + title: Code interpreter tool + properties: + type: + type: string + description: "The type of tool being defined: `code_interpreter`" + enum: + - code_interpreter + x-stainless-const: true + required: + - type + AssistantToolsFileSearch: + type: object + title: FileSearch tool + properties: + type: + type: string + description: "The type of tool being defined: `file_search`" + enum: + - file_search + x-stainless-const: true + file_search: + type: object + description: Overrides for the file search tool. + properties: + max_num_results: + type: integer + minimum: 1 + maximum: 50 + description: | + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + ranking_options: + $ref: "#/components/schemas/FileSearchRankingOptions" + required: + - type + AssistantToolsFileSearchTypeOnly: + type: object + title: FileSearch tool + properties: + type: + type: string + description: "The type of tool being defined: `file_search`" + enum: + - file_search + x-stainless-const: true + required: + - type + AssistantToolsFunction: + type: object + title: Function tool + properties: + type: + type: string + description: "The type of tool being defined: `function`" + enum: + - function + x-stainless-const: true + function: + $ref: "#/components/schemas/FunctionObject" + required: + - type + - function + AssistantsApiResponseFormatOption: + description: > + Specifies the format that the model must output. Compatible with + [GPT-4o](/docs/models#gpt-4o), [GPT-4 + Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models + since `gpt-3.5-turbo-1106`. + + + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables + Structured Outputs which ensures the model will match your supplied JSON + schema. Learn more in the [Structured Outputs + guide](/docs/guides/structured-outputs). + + + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures + the message the model generates is valid JSON. + + + **Important:** when using JSON mode, you **must** also instruct the + model to produce JSON yourself via a system or user message. Without + this, the model may generate an unending stream of whitespace until the + generation reaches the token limit, resulting in a long-running and + seemingly "stuck" request. Also note that the message content may be + partially cut off if `finish_reason="length"`, which indicates the + generation exceeded `max_tokens` or the conversation exceeded the max + context length. + oneOf: + - type: string + description: | + `auto` is the default value + enum: + - auto + x-stainless-const: true + - $ref: "#/components/schemas/ResponseFormatText" + - $ref: "#/components/schemas/ResponseFormatJsonObject" + - $ref: "#/components/schemas/ResponseFormatJsonSchema" + AssistantsApiToolChoiceOption: + description: > + Controls which (if any) tool is called by the model. + + `none` means the model will not call any tools and instead generates a + message. + + `auto` is the default value and means the model can pick between + generating a message or calling one or more tools. + + `required` means the model must call one or more tools before responding + to the user. + + Specifying a particular tool like `{"type": "file_search"}` or `{"type": + "function", "function": {"name": "my_function"}}` forces the model to + call that tool. + oneOf: + - type: string + description: > + `none` means the model will not call any tools and instead generates + a message. `auto` means the model can pick between generating a + message or calling one or more tools. `required` means the model + must call one or more tools before responding to the user. + enum: + - none + - auto + - required + - $ref: "#/components/schemas/AssistantsNamedToolChoice" + AssistantsNamedToolChoice: + type: object + description: Specifies a tool the model should use. Use to force the model to + call a specific tool. + properties: + type: + type: string + enum: + - function + - code_interpreter + - file_search + description: The type of the tool. If type is `function`, the function name must + be set + function: + type: object + properties: + name: + type: string + description: The name of the function to call. + required: + - name + required: + - type + AudioResponseFormat: + description: > + The format of the output, in one of these options: `json`, `text`, + `srt`, `verbose_json`, or `vtt`. For `gpt-4o-transcribe` and + `gpt-4o-mini-transcribe`, the only supported format is `json`. + type: string + enum: + - json + - text + - srt + - verbose_json + - vtt + default: json + AuditLog: + type: object + description: A log of a user action or configuration change within this organization. + properties: + id: + type: string + description: The ID of this log. + type: + $ref: "#/components/schemas/AuditLogEventType" + effective_at: + type: integer + description: The Unix timestamp (in seconds) of the event. + project: + type: object + description: The project that the action was scoped to. Absent for actions not + scoped to projects. + properties: + id: + type: string + description: The project ID. + name: + type: string + description: The project title. + actor: + $ref: "#/components/schemas/AuditLogActor" + api_key.created: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The tracking ID of the API key. + data: + type: object + description: The payload used to create the API key. + properties: + scopes: + type: array + items: + type: string + description: A list of scopes allowed for the API key, e.g. + `["api.model.request"]` + api_key.updated: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The tracking ID of the API key. + changes_requested: + type: object + description: The payload used to update the API key. + properties: + scopes: + type: array + items: + type: string + description: A list of scopes allowed for the API key, e.g. + `["api.model.request"]` + api_key.deleted: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The tracking ID of the API key. + checkpoint_permission.created: + type: object + description: The project and fine-tuned model checkpoint that the checkpoint + permission was created for. + properties: + id: + type: string + description: The ID of the checkpoint permission. + data: + type: object + description: The payload used to create the checkpoint permission. + properties: + project_id: + type: string + description: The ID of the project that the checkpoint permission was created + for. + fine_tuned_model_checkpoint: + type: string + description: The ID of the fine-tuned model checkpoint. + checkpoint_permission.deleted: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The ID of the checkpoint permission. + invite.sent: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The ID of the invite. + data: + type: object + description: The payload used to create the invite. + properties: + email: + type: string + description: The email invited to the organization. + role: + type: string + description: The role the email was invited to be. Is either `owner` or + `member`. + invite.accepted: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The ID of the invite. + invite.deleted: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The ID of the invite. + login.failed: + type: object + description: The details for events with this `type`. + properties: + error_code: + type: string + description: The error code of the failure. + error_message: + type: string + description: The error message of the failure. + logout.failed: + type: object + description: The details for events with this `type`. + properties: + error_code: + type: string + description: The error code of the failure. + error_message: + type: string + description: The error message of the failure. + organization.updated: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The organization ID. + changes_requested: + type: object + description: The payload used to update the organization settings. + properties: + title: + type: string + description: The organization title. + description: + type: string + description: The organization description. + name: + type: string + description: The organization name. + settings: + type: object + properties: + threads_ui_visibility: + type: string + description: Visibility of the threads page which shows messages created with + the Assistants API and Playground. One of `ANY_ROLE`, + `OWNERS`, or `NONE`. + usage_dashboard_visibility: + type: string + description: Visibility of the usage dashboard which shows activity and costs + for your organization. One of `ANY_ROLE` or `OWNERS`. + project.created: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The project ID. + data: + type: object + description: The payload used to create the project. + properties: + name: + type: string + description: The project name. + title: + type: string + description: The title of the project as seen on the dashboard. + project.updated: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The project ID. + changes_requested: + type: object + description: The payload used to update the project. + properties: + title: + type: string + description: The title of the project as seen on the dashboard. + project.archived: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The project ID. + rate_limit.updated: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The rate limit ID + changes_requested: + type: object + description: The payload used to update the rate limits. + properties: + max_requests_per_1_minute: + type: integer + description: The maximum requests per minute. + max_tokens_per_1_minute: + type: integer + description: The maximum tokens per minute. + max_images_per_1_minute: + type: integer + description: The maximum images per minute. Only relevant for certain models. + max_audio_megabytes_per_1_minute: + type: integer + description: The maximum audio megabytes per minute. Only relevant for certain + models. + max_requests_per_1_day: + type: integer + description: The maximum requests per day. Only relevant for certain models. + batch_1_day_max_input_tokens: + type: integer + description: The maximum batch input tokens per day. Only relevant for certain + models. + rate_limit.deleted: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The rate limit ID + service_account.created: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The service account ID. + data: + type: object + description: The payload used to create the service account. + properties: + role: + type: string + description: The role of the service account. Is either `owner` or `member`. + service_account.updated: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The service account ID. + changes_requested: + type: object + description: The payload used to updated the service account. + properties: + role: + type: string + description: The role of the service account. Is either `owner` or `member`. + service_account.deleted: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The service account ID. + user.added: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The user ID. + data: + type: object + description: The payload used to add the user to the project. + properties: + role: + type: string + description: The role of the user. Is either `owner` or `member`. + user.updated: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The project ID. + changes_requested: + type: object + description: The payload used to update the user. + properties: + role: + type: string + description: The role of the user. Is either `owner` or `member`. + user.deleted: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The user ID. + certificate.created: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The certificate ID. + name: + type: string + description: The name of the certificate. + certificate.updated: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The certificate ID. + name: + type: string + description: The name of the certificate. + certificate.deleted: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The certificate ID. + name: + type: string + description: The name of the certificate. + certificate: + type: string + description: The certificate content in PEM format. + certificates.activated: + type: object + description: The details for events with this `type`. + properties: + certificates: + type: array + items: + type: object + properties: + id: + type: string + description: The certificate ID. + name: + type: string + description: The name of the certificate. + certificates.deactivated: + type: object + description: The details for events with this `type`. + properties: + certificates: + type: array + items: + type: object + properties: + id: + type: string + description: The certificate ID. + name: + type: string + description: The name of the certificate. + required: + - id + - type + - effective_at + - actor + x-oaiMeta: + name: The audit log object + example: > + { + "id": "req_xxx_20240101", + "type": "api_key.created", + "effective_at": 1720804090, + "actor": { + "type": "session", + "session": { + "user": { + "id": "user-xxx", + "email": "user@example.com" + }, + "ip_address": "127.0.0.1", + "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36" + } + }, + "api_key.created": { + "id": "key_xxxx", + "data": { + "scopes": ["resource.operation"] + } + } + } + AuditLogActor: + type: object + description: The actor who performed the audit logged action. + properties: + type: + type: string + description: The type of actor. Is either `session` or `api_key`. + enum: + - session + - api_key + session: + $ref: "#/components/schemas/AuditLogActorSession" + api_key: + $ref: "#/components/schemas/AuditLogActorApiKey" + AuditLogActorApiKey: + type: object + description: The API Key used to perform the audit logged action. + properties: + id: + type: string + description: The tracking id of the API key. + type: + type: string + description: The type of API key. Can be either `user` or `service_account`. + enum: + - user + - service_account + user: + $ref: "#/components/schemas/AuditLogActorUser" + service_account: + $ref: "#/components/schemas/AuditLogActorServiceAccount" + AuditLogActorServiceAccount: + type: object + description: The service account that performed the audit logged action. + properties: + id: + type: string + description: The service account id. + AuditLogActorSession: + type: object + description: The session in which the audit logged action was performed. + properties: + user: + $ref: "#/components/schemas/AuditLogActorUser" + ip_address: + type: string + description: The IP address from which the action was performed. + AuditLogActorUser: + type: object + description: The user who performed the audit logged action. + properties: + id: + type: string + description: The user id. + email: + type: string + description: The user email. + AuditLogEventType: + type: string + description: The event type. + enum: + - api_key.created + - api_key.updated + - api_key.deleted + - checkpoint_permission.created + - checkpoint_permission.deleted + - invite.sent + - invite.accepted + - invite.deleted + - login.succeeded + - login.failed + - logout.succeeded + - logout.failed + - organization.updated + - project.created + - project.updated + - project.archived + - service_account.created + - service_account.updated + - service_account.deleted + - rate_limit.updated + - rate_limit.deleted + - user.added + - user.updated + - user.deleted + AutoChunkingStrategyRequestParam: + type: object + title: Auto Chunking Strategy + description: The default strategy. This strategy currently uses a + `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. + additionalProperties: false + properties: + type: + type: string + description: Always `auto`. + enum: + - auto + x-stainless-const: true + required: + - type + Batch: + type: object + properties: + id: + type: string + object: + type: string + enum: + - batch + description: The object type, which is always `batch`. + x-stainless-const: true + endpoint: + type: string + description: The OpenAI API endpoint used by the batch. + errors: + type: object + properties: + object: + type: string + description: The object type, which is always `list`. + data: + type: array + items: + type: object + properties: + code: + type: string + description: An error code identifying the error type. + message: + type: string + description: A human-readable message providing more details about the error. + param: + type: string + description: The name of the parameter that caused the error, if applicable. + nullable: true + line: + type: integer + description: The line number of the input file where the error occurred, if + applicable. + nullable: true + input_file_id: + type: string + description: The ID of the input file for the batch. + completion_window: + type: string + description: The time frame within which the batch should be processed. + status: + type: string + description: The current status of the batch. + enum: + - validating + - failed + - in_progress + - finalizing + - completed + - expired + - cancelling + - cancelled + output_file_id: + type: string + description: The ID of the file containing the outputs of successfully executed + requests. + error_file_id: + type: string + description: The ID of the file containing the outputs of requests with errors. + created_at: + type: integer + description: The Unix timestamp (in seconds) for when the batch was created. + in_progress_at: + type: integer + description: The Unix timestamp (in seconds) for when the batch started + processing. + expires_at: + type: integer + description: The Unix timestamp (in seconds) for when the batch will expire. + finalizing_at: + type: integer + description: The Unix timestamp (in seconds) for when the batch started + finalizing. + completed_at: + type: integer + description: The Unix timestamp (in seconds) for when the batch was completed. + failed_at: + type: integer + description: The Unix timestamp (in seconds) for when the batch failed. + expired_at: + type: integer + description: The Unix timestamp (in seconds) for when the batch expired. + cancelling_at: + type: integer + description: The Unix timestamp (in seconds) for when the batch started + cancelling. + cancelled_at: + type: integer + description: The Unix timestamp (in seconds) for when the batch was cancelled. + request_counts: + type: object + properties: + total: + type: integer + description: Total number of requests in the batch. + completed: + type: integer + description: Number of requests that have been completed successfully. + failed: + type: integer + description: Number of requests that have failed. + required: + - total + - completed + - failed + description: The request counts for different statuses within the batch. + metadata: + $ref: "#/components/schemas/Metadata" + required: + - id + - object + - endpoint + - input_file_id + - completion_window + - status + - created_at + x-oaiMeta: + name: The batch object + example: | + { + "id": "batch_abc123", + "object": "batch", + "endpoint": "/v1/completions", + "errors": null, + "input_file_id": "file-abc123", + "completion_window": "24h", + "status": "completed", + "output_file_id": "file-cvaTdG", + "error_file_id": "file-HOWS94", + "created_at": 1711471533, + "in_progress_at": 1711471538, + "expires_at": 1711557933, + "finalizing_at": 1711493133, + "completed_at": 1711493163, + "failed_at": null, + "expired_at": null, + "cancelling_at": null, + "cancelled_at": null, + "request_counts": { + "total": 100, + "completed": 95, + "failed": 5 + }, + "metadata": { + "customer_id": "user_123456789", + "batch_description": "Nightly eval job", + } + } + BatchRequestInput: + type: object + description: The per-line object of the batch input file + properties: + custom_id: + type: string + description: A developer-provided per-request id that will be used to match + outputs to inputs. Must be unique for each request in a batch. + method: + type: string + enum: + - POST + description: The HTTP method to be used for the request. Currently only `POST` + is supported. + x-stainless-const: true + url: + type: string + description: The OpenAI API relative URL to be used for the request. Currently + `/v1/chat/completions`, `/v1/embeddings`, and `/v1/completions` are + supported. + x-oaiMeta: + name: The request input object + example: > + {"custom_id": "request-1", "method": "POST", "url": + "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": + [{"role": "system", "content": "You are a helpful assistant."}, + {"role": "user", "content": "What is 2+2?"}]}} + BatchRequestOutput: + type: object + description: The per-line object of the batch output and error files + properties: + id: + type: string + custom_id: + type: string + description: A developer-provided per-request id that will be used to match + outputs to inputs. + response: + type: object + nullable: true + properties: + status_code: + type: integer + description: The HTTP status code of the response + request_id: + type: string + description: An unique identifier for the OpenAI API request. Please include + this request ID when contacting support. + body: + type: object + x-oaiTypeLabel: map + description: The JSON body of the response + error: + type: object + nullable: true + description: For requests that failed with a non-HTTP error, this will contain + more information on the cause of the failure. + properties: + code: + type: string + description: A machine-readable error code. + message: + type: string + description: A human-readable error message. + x-oaiMeta: + name: The request output object + example: > + {"id": "batch_req_wnaDys", "custom_id": "request-2", "response": + {"status_code": 200, "request_id": "req_c187b3", "body": {"id": + "chatcmpl-9758Iw", "object": "chat.completion", "created": 1711475054, + "model": "gpt-4o-mini", "choices": [{"index": 0, "message": {"role": + "assistant", "content": "2 + 2 equals 4."}, "finish_reason": "stop"}], + "usage": {"prompt_tokens": 24, "completion_tokens": 15, + "total_tokens": 39}, "system_fingerprint": null}}, "error": null} + Certificate: + type: object + description: Represents an individual `certificate` uploaded to the organization. + properties: + object: + type: string + enum: + - certificate + - organization.certificate + - organization.project.certificate + description: > + The object type. + + + - If creating, updating, or getting a specific certificate, the + object type is `certificate`. + + - If listing, activating, or deactivating certificates for the + organization, the object type is `organization.certificate`. + + - If listing, activating, or deactivating certificates for a + project, the object type is `organization.project.certificate`. + x-stainless-const: true + id: + type: string + description: The identifier, which can be referenced in API endpoints + name: + type: string + description: The name of the certificate. + created_at: + type: integer + description: The Unix timestamp (in seconds) of when the certificate was uploaded. + certificate_details: + type: object + properties: + valid_at: + type: integer + description: The Unix timestamp (in seconds) of when the certificate becomes + valid. + expires_at: + type: integer + description: The Unix timestamp (in seconds) of when the certificate expires. + content: + type: string + description: The content of the certificate in PEM format. + active: + type: boolean + description: Whether the certificate is currently active at the specified scope. + Not returned when getting details for a specific certificate. + required: + - object + - id + - name + - created_at + - certificate_details + x-oaiMeta: + name: The certificate object + example: > + { + "object": "certificate", + "id": "cert_abc", + "name": "My Certificate", + "created_at": 1234567, + "certificate_details": { + "valid_at": 1234567, + "expires_at": 12345678, + "content": "-----BEGIN CERTIFICATE----- MIIGAjCCA...6znFlOW+ -----END CERTIFICATE-----" + } + } + ChatCompletionDeleted: + type: object + properties: + object: + type: string + description: The type of object being deleted. + enum: + - chat.completion.deleted + x-stainless-const: true + id: + type: string + description: The ID of the chat completion that was deleted. + deleted: + type: boolean + description: Whether the chat completion was deleted. + required: + - object + - id + - deleted + ChatCompletionFunctionCallOption: + type: object + description: > + Specifying a particular function via `{"name": "my_function"}` forces + the model to call that function. + properties: + name: + type: string + description: The name of the function to call. + required: + - name + ChatCompletionFunctions: + type: object + deprecated: true + properties: + description: + type: string + description: A description of what the function does, used by the model to + choose when and how to call the function. + name: + type: string + description: The name of the function to be called. Must be a-z, A-Z, 0-9, or + contain underscores and dashes, with a maximum length of 64. + parameters: + $ref: "#/components/schemas/FunctionParameters" + required: + - name + ChatCompletionList: + type: object + title: ChatCompletionList + description: | + An object representing a list of Chat Completions. + properties: + object: + type: string + enum: + - list + default: list + description: | + The type of this object. It is always set to "list". + x-stainless-const: true + data: + type: array + description: | + An array of chat completion objects. + items: + $ref: "#/components/schemas/CreateChatCompletionResponse" + first_id: + type: string + description: The identifier of the first chat completion in the data array. + last_id: + type: string + description: The identifier of the last chat completion in the data array. + has_more: + type: boolean + description: Indicates whether there are more Chat Completions available. + required: + - object + - data + - first_id + - last_id + - has_more + x-oaiMeta: + name: The chat completion list object + group: chat + example: > + { + "object": "list", + "data": [ + { + "object": "chat.completion", + "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", + "model": "gpt-4o-2024-08-06", + "created": 1738960610, + "request_id": "req_ded8ab984ec4bf840f37566c1011c417", + "tool_choice": null, + "usage": { + "total_tokens": 31, + "completion_tokens": 18, + "prompt_tokens": 13 + }, + "seed": 4944116822809979520, + "top_p": 1.0, + "temperature": 1.0, + "presence_penalty": 0.0, + "frequency_penalty": 0.0, + "system_fingerprint": "fp_50cad350e4", + "input_user": null, + "service_tier": "default", + "tools": null, + "metadata": {}, + "choices": [ + { + "index": 0, + "message": { + "content": "Mind of circuits hum, \nLearning patterns in silence— \nFuture's quiet spark.", + "role": "assistant", + "tool_calls": null, + "function_call": null + }, + "finish_reason": "stop", + "logprobs": null + } + ], + "response_format": null + } + ], + "first_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", + "last_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", + "has_more": false + } + ChatCompletionMessageList: + type: object + title: ChatCompletionMessageList + description: | + An object representing a list of chat completion messages. + properties: + object: + type: string + enum: + - list + default: list + description: | + The type of this object. It is always set to "list". + x-stainless-const: true + data: + type: array + description: | + An array of chat completion message objects. + items: + allOf: + - $ref: "#/components/schemas/ChatCompletionResponseMessage" + - type: object + required: + - id + properties: + id: + type: string + description: The identifier of the chat message. + first_id: + type: string + description: The identifier of the first chat message in the data array. + last_id: + type: string + description: The identifier of the last chat message in the data array. + has_more: + type: boolean + description: Indicates whether there are more chat messages available. + required: + - object + - data + - first_id + - last_id + - has_more + x-oaiMeta: + name: The chat completion message list object + group: chat + example: | + { + "object": "list", + "data": [ + { + "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0", + "role": "user", + "content": "write a haiku about ai", + "name": null, + "content_parts": null + } + ], + "first_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0", + "last_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0", + "has_more": false + } + ChatCompletionMessageToolCall: + type: object + properties: + id: + type: string + description: The ID of the tool call. + type: + type: string + enum: + - function + description: The type of the tool. Currently, only `function` is supported. + x-stainless-const: true + function: + type: object + description: The function that the model called. + properties: + name: + type: string + description: The name of the function to call. + arguments: + type: string + description: The arguments to call the function with, as generated by the model + in JSON format. Note that the model does not always generate + valid JSON, and may hallucinate parameters not defined by your + function schema. Validate the arguments in your code before + calling your function. + required: + - name + - arguments + required: + - id + - type + - function + ChatCompletionMessageToolCallChunk: + type: object + properties: + index: + type: integer + id: + type: string + description: The ID of the tool call. + type: + type: string + enum: + - function + description: The type of the tool. Currently, only `function` is supported. + x-stainless-const: true + function: + type: object + properties: + name: + type: string + description: The name of the function to call. + arguments: + type: string + description: The arguments to call the function with, as generated by the model + in JSON format. Note that the model does not always generate + valid JSON, and may hallucinate parameters not defined by your + function schema. Validate the arguments in your code before + calling your function. + required: + - index + ChatCompletionMessageToolCalls: + type: array + description: The tool calls generated by the model, such as function calls. + items: + $ref: "#/components/schemas/ChatCompletionMessageToolCall" + ChatCompletionModalities: + type: array + nullable: true + description: > + Output types that you would like the model to generate for this request. + + Most models are capable of generating text, which is the default: + + + `["text"]` + + + The `gpt-4o-audio-preview` model can also be used to [generate + audio](/docs/guides/audio). To + + request that this model generate both text and audio responses, you can + + use: + + + `["text", "audio"]` + items: + type: string + enum: + - text + - audio + ChatCompletionNamedToolChoice: + type: object + description: Specifies a tool the model should use. Use to force the model to + call a specific function. + properties: + type: + type: string + enum: + - function + description: The type of the tool. Currently, only `function` is supported. + x-stainless-const: true + function: + type: object + properties: + name: + type: string + description: The name of the function to call. + required: + - name + required: + - type + - function + ChatCompletionRequestAssistantMessage: + type: object + title: Assistant message + description: | + Messages sent by the model in response to user messages. + properties: + content: + nullable: true + oneOf: + - type: string + description: The contents of the assistant message. + title: Text content + - type: array + description: An array of content parts with a defined type. Can be one or more + of type `text`, or exactly one of type `refusal`. + title: Array of content parts + items: + $ref: "#/components/schemas/ChatCompletionRequestAssistantMessageContentPart" + minItems: 1 + description: > + The contents of the assistant message. Required unless `tool_calls` + or `function_call` is specified. + refusal: + nullable: true + type: string + description: The refusal message by the assistant. + role: + type: string + enum: + - assistant + description: The role of the messages author, in this case `assistant`. + x-stainless-const: true + name: + type: string + description: An optional name for the participant. Provides the model + information to differentiate between participants of the same role. + audio: + type: object + nullable: true + description: | + Data about a previous audio response from the model. + [Learn more](/docs/guides/audio). + required: + - id + properties: + id: + type: string + description: | + Unique identifier for a previous audio response from the model. + tool_calls: + $ref: "#/components/schemas/ChatCompletionMessageToolCalls" + function_call: + type: object + deprecated: true + description: Deprecated and replaced by `tool_calls`. The name and arguments of + a function that should be called, as generated by the model. + nullable: true + properties: + arguments: + type: string + description: The arguments to call the function with, as generated by the model + in JSON format. Note that the model does not always generate + valid JSON, and may hallucinate parameters not defined by your + function schema. Validate the arguments in your code before + calling your function. + name: + type: string + description: The name of the function to call. + required: + - arguments + - name + required: + - role + ChatCompletionRequestAssistantMessageContentPart: + oneOf: + - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartText" + - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartRefusal" + ChatCompletionRequestDeveloperMessage: + type: object + title: Developer message + description: > + Developer-provided instructions that the model should follow, regardless + of + + messages sent by the user. With o1 models and newer, `developer` + messages + + replace the previous `system` messages. + properties: + content: + description: The contents of the developer message. + oneOf: + - type: string + description: The contents of the developer message. + title: Text content + - type: array + description: An array of content parts with a defined type. For developer + messages, only type `text` is supported. + title: Array of content parts + items: + $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartText" + minItems: 1 + role: + type: string + enum: + - developer + description: The role of the messages author, in this case `developer`. + x-stainless-const: true + name: + type: string + description: An optional name for the participant. Provides the model + information to differentiate between participants of the same role. + required: + - content + - role + ChatCompletionRequestFunctionMessage: + type: object + title: Function message + deprecated: true + properties: + role: + type: string + enum: + - function + description: The role of the messages author, in this case `function`. + x-stainless-const: true + content: + nullable: true + type: string + description: The contents of the function message. + name: + type: string + description: The name of the function to call. + required: + - role + - content + - name + ChatCompletionRequestMessage: + oneOf: + - $ref: "#/components/schemas/ChatCompletionRequestDeveloperMessage" + - $ref: "#/components/schemas/ChatCompletionRequestSystemMessage" + - $ref: "#/components/schemas/ChatCompletionRequestUserMessage" + - $ref: "#/components/schemas/ChatCompletionRequestAssistantMessage" + - $ref: "#/components/schemas/ChatCompletionRequestToolMessage" + - $ref: "#/components/schemas/ChatCompletionRequestFunctionMessage" + ChatCompletionRequestMessageContentPartAudio: + type: object + title: Audio content part + description: | + Learn about [audio inputs](/docs/guides/audio). + properties: + type: + type: string + enum: + - input_audio + description: The type of the content part. Always `input_audio`. + x-stainless-const: true + input_audio: + type: object + properties: + data: + type: string + description: Base64 encoded audio data. + format: + type: string + enum: + - wav + - mp3 + description: > + The format of the encoded audio data. Currently supports "wav" + and "mp3". + required: + - data + - format + required: + - type + - input_audio + ChatCompletionRequestMessageContentPartFile: + type: object + title: File content part + description: | + Learn about [file inputs](/docs/guides/text) for text generation. + properties: + type: + type: string + enum: + - file + description: The type of the content part. Always `file`. + x-stainless-const: true + file: + type: object + properties: + filename: + type: string + description: > + The name of the file, used when passing the file to the model as + a + + string. + file_data: + type: string + description: > + The base64 encoded file data, used when passing the file to the + model + + as a string. + file_id: + type: string + description: | + The ID of an uploaded file to use as input. + required: + - type + - file + ChatCompletionRequestMessageContentPartImage: + type: object + title: Image content part + description: | + Learn about [image inputs](/docs/guides/vision). + properties: + type: + type: string + enum: + - image_url + description: The type of the content part. + x-stainless-const: true + image_url: + type: object + properties: + url: + type: string + description: Either a URL of the image or the base64 encoded image data. + format: uri + detail: + type: string + description: Specifies the detail level of the image. Learn more in the [Vision + guide](/docs/guides/vision#low-or-high-fidelity-image-understanding). + enum: + - auto + - low + - high + default: auto + required: + - url + required: + - type + - image_url + ChatCompletionRequestMessageContentPartRefusal: + type: object + title: Refusal content part + properties: + type: + type: string + enum: + - refusal + description: The type of the content part. + x-stainless-const: true + refusal: + type: string + description: The refusal message generated by the model. + required: + - type + - refusal + ChatCompletionRequestMessageContentPartText: + type: object + title: Text content part + description: | + Learn about [text inputs](/docs/guides/text-generation). + properties: + type: + type: string + enum: + - text + description: The type of the content part. + x-stainless-const: true + text: + type: string + description: The text content. + required: + - type + - text + ChatCompletionRequestSystemMessage: + type: object + title: System message + description: > + Developer-provided instructions that the model should follow, regardless + of + + messages sent by the user. With o1 models and newer, use `developer` + messages + + for this purpose instead. + properties: + content: + description: The contents of the system message. + oneOf: + - type: string + description: The contents of the system message. + title: Text content + - type: array + description: An array of content parts with a defined type. For system messages, + only type `text` is supported. + title: Array of content parts + items: + $ref: "#/components/schemas/ChatCompletionRequestSystemMessageContentPart" + minItems: 1 + role: + type: string + enum: + - system + description: The role of the messages author, in this case `system`. + x-stainless-const: true + name: + type: string + description: An optional name for the participant. Provides the model + information to differentiate between participants of the same role. + required: + - content + - role + ChatCompletionRequestSystemMessageContentPart: + oneOf: + - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartText" + ChatCompletionRequestToolMessage: + type: object + title: Tool message + properties: + role: + type: string + enum: + - tool + description: The role of the messages author, in this case `tool`. + x-stainless-const: true + content: + oneOf: + - type: string + description: The contents of the tool message. + title: Text content + - type: array + description: An array of content parts with a defined type. For tool messages, + only type `text` is supported. + title: Array of content parts + items: + $ref: "#/components/schemas/ChatCompletionRequestToolMessageContentPart" + minItems: 1 + description: The contents of the tool message. + tool_call_id: + type: string + description: Tool call that this message is responding to. + required: + - role + - content + - tool_call_id + ChatCompletionRequestToolMessageContentPart: + oneOf: + - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartText" + ChatCompletionRequestUserMessage: + type: object + title: User message + description: | + Messages sent by an end user, containing prompts or additional context + information. + properties: + content: + description: | + The contents of the user message. + oneOf: + - type: string + description: The text contents of the message. + title: Text content + - type: array + description: An array of content parts with a defined type. Supported options + differ based on the [model](/docs/models) being used to generate + the response. Can contain text, image, or audio inputs. + title: Array of content parts + items: + $ref: "#/components/schemas/ChatCompletionRequestUserMessageContentPart" + minItems: 1 + role: + type: string + enum: + - user + description: The role of the messages author, in this case `user`. + x-stainless-const: true + name: + type: string + description: An optional name for the participant. Provides the model + information to differentiate between participants of the same role. + required: + - content + - role + ChatCompletionRequestUserMessageContentPart: + oneOf: + - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartText" + - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartImage" + - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartAudio" + - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartFile" + ChatCompletionResponseMessage: + type: object + description: A chat completion message generated by the model. + properties: + content: + type: string + description: The contents of the message. + nullable: true + refusal: + type: string + description: The refusal message generated by the model. + nullable: true + tool_calls: + $ref: "#/components/schemas/ChatCompletionMessageToolCalls" + annotations: + type: array + description: | + Annotations for the message, when applicable, as when using the + [web search tool](/docs/guides/tools-web-search?api-mode=chat). + items: + type: object + description: | + A URL citation when using web search. + required: + - type + - url_citation + properties: + type: + type: string + description: The type of the URL citation. Always `url_citation`. + enum: + - url_citation + x-stainless-const: true + url_citation: + type: object + description: A URL citation when using web search. + required: + - end_index + - start_index + - url + - title + properties: + end_index: + type: integer + description: The index of the last character of the URL citation in the message. + start_index: + type: integer + description: The index of the first character of the URL citation in the + message. + url: + type: string + description: The URL of the web resource. + title: + type: string + description: The title of the web resource. + role: + type: string + enum: + - assistant + description: The role of the author of this message. + x-stainless-const: true + function_call: + type: object + deprecated: true + description: Deprecated and replaced by `tool_calls`. The name and arguments of + a function that should be called, as generated by the model. + properties: + arguments: + type: string + description: The arguments to call the function with, as generated by the model + in JSON format. Note that the model does not always generate + valid JSON, and may hallucinate parameters not defined by your + function schema. Validate the arguments in your code before + calling your function. + name: + type: string + description: The name of the function to call. + required: + - name + - arguments + audio: + type: object + nullable: true + description: > + If the audio output modality is requested, this object contains data + + about the audio response from the model. [Learn + more](/docs/guides/audio). + required: + - id + - expires_at + - data + - transcript + properties: + id: + type: string + description: Unique identifier for this audio response. + expires_at: + type: integer + description: > + The Unix timestamp (in seconds) for when this audio response + will + + no longer be accessible on the server for use in multi-turn + + conversations. + data: + type: string + description: | + Base64 encoded audio bytes generated by the model, in the format + specified in the request. + transcript: + type: string + description: Transcript of the audio generated by the model. + required: + - role + - content + - refusal + ChatCompletionRole: + type: string + description: The role of the author of a message + enum: + - developer + - system + - user + - assistant + - tool + - function + ChatCompletionStreamOptions: + description: > + Options for streaming response. Only set this when you set `stream: + true`. + type: object + nullable: true + default: null + properties: + include_usage: + type: boolean + description: > + If set, an additional chunk will be streamed before the `data: + [DONE]` + + message. The `usage` field on this chunk shows the token usage + statistics + + for the entire request, and the `choices` field will always be an + empty + + array. + + + All other chunks will also include a `usage` field, but with a null + + value. **NOTE:** If the stream is interrupted, you may not receive + the + + final usage chunk which contains the total token usage for the + request. + ChatCompletionStreamResponseDelta: + type: object + description: A chat completion delta generated by streamed model responses. + properties: + content: + type: string + description: The contents of the chunk message. + nullable: true + function_call: + deprecated: true + type: object + description: Deprecated and replaced by `tool_calls`. The name and arguments of + a function that should be called, as generated by the model. + properties: + arguments: + type: string + description: The arguments to call the function with, as generated by the model + in JSON format. Note that the model does not always generate + valid JSON, and may hallucinate parameters not defined by your + function schema. Validate the arguments in your code before + calling your function. + name: + type: string + description: The name of the function to call. + tool_calls: + type: array + items: + $ref: "#/components/schemas/ChatCompletionMessageToolCallChunk" + role: + type: string + enum: + - developer + - system + - user + - assistant + - tool + description: The role of the author of this message. + refusal: + type: string + description: The refusal message generated by the model. + nullable: true + ChatCompletionTokenLogprob: + type: object + properties: + token: + description: The token. + type: string + logprob: + description: The log probability of this token, if it is within the top 20 most + likely tokens. Otherwise, the value `-9999.0` is used to signify + that the token is very unlikely. + type: number + bytes: + description: A list of integers representing the UTF-8 bytes representation of + the token. Useful in instances where characters are represented by + multiple tokens and their byte representations must be combined to + generate the correct text representation. Can be `null` if there is + no bytes representation for the token. + type: array + items: + type: integer + nullable: true + top_logprobs: + description: List of the most likely tokens and their log probability, at this + token position. In rare cases, there may be fewer than the number of + requested `top_logprobs` returned. + type: array + items: + type: object + properties: + token: + description: The token. + type: string + logprob: + description: The log probability of this token, if it is within the top 20 most + likely tokens. Otherwise, the value `-9999.0` is used to + signify that the token is very unlikely. + type: number + bytes: + description: A list of integers representing the UTF-8 bytes representation of + the token. Useful in instances where characters are + represented by multiple tokens and their byte representations + must be combined to generate the correct text representation. + Can be `null` if there is no bytes representation for the + token. + type: array + items: + type: integer + nullable: true + required: + - token + - logprob + - bytes + required: + - token + - logprob + - bytes + - top_logprobs + ChatCompletionTool: + type: object + properties: + type: + type: string + enum: + - function + description: The type of the tool. Currently, only `function` is supported. + x-stainless-const: true + function: + $ref: "#/components/schemas/FunctionObject" + required: + - type + - function + ChatCompletionToolChoiceOption: + description: > + Controls which (if any) tool is called by the model. + + `none` means the model will not call any tool and instead generates a + message. + + `auto` means the model can pick between generating a message or calling + one or more tools. + + `required` means the model must call one or more tools. + + Specifying a particular tool via `{"type": "function", "function": + {"name": "my_function"}}` forces the model to call that tool. + + + `none` is the default when no tools are present. `auto` is the default + if tools are present. + oneOf: + - type: string + description: > + `none` means the model will not call any tool and instead generates + a message. `auto` means the model can pick between generating a + message or calling one or more tools. `required` means the model + must call one or more tools. + enum: + - none + - auto + - required + - $ref: "#/components/schemas/ChatCompletionNamedToolChoice" + ChunkingStrategyRequestParam: + type: object + description: The chunking strategy used to chunk the file(s). If not set, will + use the `auto` strategy. + oneOf: + - $ref: "#/components/schemas/AutoChunkingStrategyRequestParam" + - $ref: "#/components/schemas/StaticChunkingStrategyRequestParam" + Click: + type: object + title: Click + description: | + A click action. + properties: + type: + type: string + enum: + - click + default: click + description: | + Specifies the event type. For a click action, this property is + always set to `click`. + x-stainless-const: true + button: + type: string + enum: + - left + - right + - wheel + - back + - forward + description: > + Indicates which mouse button was pressed during the click. One of + `left`, `right`, `wheel`, `back`, or `forward`. + x: + type: integer + description: | + The x-coordinate where the click occurred. + y: + type: integer + description: | + The y-coordinate where the click occurred. + required: + - type + - button + - x + - y + CodeInterpreterFileOutput: + type: object + title: Code interpreter file output + description: | + The output of a code interpreter tool call that is a file. + properties: + type: + type: string + enum: + - files + description: | + The type of the code interpreter file output. Always `files`. + x-stainless-const: true + files: + type: array + items: + type: object + properties: + mime_type: + type: string + description: | + The MIME type of the file. + file_id: + type: string + description: | + The ID of the file. + required: + - mime_type + - file_id + required: + - type + - files + CodeInterpreterTextOutput: + type: object + title: Code interpreter text output + description: | + The output of a code interpreter tool call that is text. + properties: + type: + type: string + enum: + - logs + description: | + The type of the code interpreter text output. Always `logs`. + x-stainless-const: true + logs: + type: string + description: | + The logs of the code interpreter tool call. + required: + - type + - logs + CodeInterpreterToolCall: + type: object + title: Code interpreter tool call + description: | + A tool call to run code. + properties: + id: + type: string + description: | + The unique ID of the code interpreter tool call. + type: + type: string + enum: + - code_interpreter_call + description: > + The type of the code interpreter tool call. Always + `code_interpreter_call`. + x-stainless-const: true + code: + type: string + description: | + The code to run. + status: + type: string + enum: + - in_progress + - interpreting + - completed + description: | + The status of the code interpreter tool call. + results: + type: array + items: + $ref: "#/components/schemas/CodeInterpreterToolOutput" + description: | + The results of the code interpreter tool call. + required: + - id + - type + - code + - status + - results + CodeInterpreterToolOutput: + oneOf: + - $ref: "#/components/schemas/CodeInterpreterTextOutput" + - $ref: "#/components/schemas/CodeInterpreterFileOutput" + ComparisonFilter: + type: object + additionalProperties: false + title: Comparison Filter + description: > + A filter used to compare a specified attribute key to a given value + using a defined comparison operation. + properties: + type: + type: string + default: eq + enum: + - eq + - ne + - gt + - gte + - lt + - lte + description: > + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, + `lte`. + + - `eq`: equals + + - `ne`: not equal + + - `gt`: greater than + + - `gte`: greater than or equal + + - `lt`: less than + + - `lte`: less than or equal + key: + type: string + description: The key to compare against the value. + value: + oneOf: + - type: string + - type: number + - type: boolean + description: The value to compare against the attribute key; supports string, + number, or boolean types. + required: + - type + - key + - value + x-oaiMeta: + name: ComparisonFilter + CompleteUploadRequest: + type: object + additionalProperties: false + properties: + part_ids: + type: array + description: | + The ordered list of Part IDs. + items: + type: string + md5: + description: > + The optional md5 checksum for the file contents to verify if the + bytes uploaded matches what you expect. + type: string + required: + - part_ids + CompletionUsage: + type: object + description: Usage statistics for the completion request. + properties: + completion_tokens: + type: integer + default: 0 + description: Number of tokens in the generated completion. + prompt_tokens: + type: integer + default: 0 + description: Number of tokens in the prompt. + total_tokens: + type: integer + default: 0 + description: Total number of tokens used in the request (prompt + completion). + completion_tokens_details: + type: object + description: Breakdown of tokens used in a completion. + properties: + accepted_prediction_tokens: + type: integer + default: 0 + description: | + When using Predicted Outputs, the number of tokens in the + prediction that appeared in the completion. + audio_tokens: + type: integer + default: 0 + description: Audio input tokens generated by the model. + reasoning_tokens: + type: integer + default: 0 + description: Tokens generated by the model for reasoning. + rejected_prediction_tokens: + type: integer + default: 0 + description: > + When using Predicted Outputs, the number of tokens in the + + prediction that did not appear in the completion. However, like + + reasoning tokens, these tokens are still counted in the total + + completion tokens for purposes of billing, output, and context + window + + limits. + prompt_tokens_details: + type: object + description: Breakdown of tokens used in the prompt. + properties: + audio_tokens: + type: integer + default: 0 + description: Audio input tokens present in the prompt. + cached_tokens: + type: integer + default: 0 + description: Cached tokens present in the prompt. + required: + - prompt_tokens + - completion_tokens + - total_tokens + CompoundFilter: + $recursiveAnchor: true + type: object + additionalProperties: false + title: Compound Filter + description: Combine multiple filters using `and` or `or`. + properties: + type: + type: string + description: "Type of operation: `and` or `or`." + enum: + - and + - or + filters: + type: array + description: Array of filters to combine. Items can be `ComparisonFilter` or + `CompoundFilter`. + items: + oneOf: + - $ref: "#/components/schemas/ComparisonFilter" + - $recursiveRef: "#" + required: + - type + - filters + x-oaiMeta: + name: CompoundFilter + ComputerAction: + oneOf: + - $ref: "#/components/schemas/Click" + - $ref: "#/components/schemas/DoubleClick" + - $ref: "#/components/schemas/Drag" + - $ref: "#/components/schemas/KeyPress" + - $ref: "#/components/schemas/Move" + - $ref: "#/components/schemas/Screenshot" + - $ref: "#/components/schemas/Scroll" + - $ref: "#/components/schemas/Type" + - $ref: "#/components/schemas/Wait" + ComputerScreenshotImage: + type: object + description: | + A computer screenshot image used with the computer use tool. + properties: + type: + type: string + enum: + - computer_screenshot + default: computer_screenshot + description: > + Specifies the event type. For a computer screenshot, this property + is + + always set to `computer_screenshot`. + x-stainless-const: true + image_url: + type: string + description: The URL of the screenshot image. + file_id: + type: string + description: The identifier of an uploaded file that contains the screenshot. + required: + - type + ComputerToolCall: + type: object + title: Computer tool call + description: > + A tool call to a computer use tool. See the + + [computer use guide](/docs/guides/tools-computer-use) for more + information. + properties: + type: + type: string + description: The type of the computer call. Always `computer_call`. + enum: + - computer_call + default: computer_call + id: + type: string + description: The unique ID of the computer call. + call_id: + type: string + description: | + An identifier used when responding to the tool call with output. + action: + $ref: "#/components/schemas/ComputerAction" + pending_safety_checks: + type: array + items: + $ref: "#/components/schemas/ComputerToolCallSafetyCheck" + description: | + The pending safety checks for the computer call. + status: + type: string + description: | + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + enum: + - in_progress + - completed + - incomplete + required: + - type + - id + - action + - call_id + - pending_safety_checks + - status + ComputerToolCallOutput: + type: object + title: Computer tool call output + description: | + The output of a computer tool call. + properties: + type: + type: string + description: > + The type of the computer tool call output. Always + `computer_call_output`. + enum: + - computer_call_output + default: computer_call_output + x-stainless-const: true + id: + type: string + description: | + The ID of the computer tool call output. + call_id: + type: string + description: | + The ID of the computer tool call that produced the output. + acknowledged_safety_checks: + type: array + description: > + The safety checks reported by the API that have been acknowledged by + the + + developer. + items: + $ref: "#/components/schemas/ComputerToolCallSafetyCheck" + output: + $ref: "#/components/schemas/ComputerScreenshotImage" + status: + type: string + description: > + The status of the message input. One of `in_progress`, `completed`, + or + + `incomplete`. Populated when input items are returned via API. + enum: + - in_progress + - completed + - incomplete + required: + - type + - call_id + - output + ComputerToolCallOutputResource: + allOf: + - $ref: "#/components/schemas/ComputerToolCallOutput" + - type: object + properties: + id: + type: string + description: | + The unique ID of the computer call tool output. + required: + - id + ComputerToolCallSafetyCheck: + type: object + description: | + A pending safety check for the computer call. + properties: + id: + type: string + description: The ID of the pending safety check. + code: + type: string + description: The type of the pending safety check. + message: + type: string + description: Details about the pending safety check. + required: + - id + - code + - message + Content: + description: | + Multi-modal input and output contents. + oneOf: + - title: Input content types + $ref: "#/components/schemas/InputContent" + - title: Output content types + $ref: "#/components/schemas/OutputContent" + Coordinate: + type: object + title: Coordinate + description: | + An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`. + properties: + x: + type: integer + description: | + The x-coordinate. + y: + type: integer + description: | + The y-coordinate. + required: + - x + - y + CostsResult: + type: object + description: The aggregated costs details of the specific time bucket. + properties: + object: + type: string + enum: + - organization.costs.result + x-stainless-const: true + amount: + type: object + description: The monetary value in its associated currency. + properties: + value: + type: number + description: The numeric value of the cost. + currency: + type: string + description: Lowercase ISO-4217 currency e.g. "usd" + line_item: + type: string + nullable: true + description: When `group_by=line_item`, this field provides the line item of the + grouped costs result. + project_id: + type: string + nullable: true + description: When `group_by=project_id`, this field provides the project ID of + the grouped costs result. + required: + - object + x-oaiMeta: + name: Costs object + example: | + { + "object": "organization.costs.result", + "amount": { + "value": 0.06, + "currency": "usd" + }, + "line_item": "Image models", + "project_id": "proj_abc" + } + CreateAssistantRequest: + type: object + additionalProperties: false + properties: + model: + description: > + ID of the model to use. You can use the [List + models](/docs/api-reference/models/list) API to see all of your + available models, or see our [Model overview](/docs/models) for + descriptions of them. + example: gpt-4o + anyOf: + - type: string + - $ref: "#/components/schemas/AssistantSupportedModels" + x-oaiTypeLabel: string + name: + description: | + The name of the assistant. The maximum length is 256 characters. + type: string + nullable: true + maxLength: 256 + description: + description: > + The description of the assistant. The maximum length is 512 + characters. + type: string + nullable: true + maxLength: 512 + instructions: + description: > + The system instructions that the assistant uses. The maximum length + is 256,000 characters. + type: string + nullable: true + maxLength: 256000 + reasoning_effort: + $ref: "#/components/schemas/ReasoningEffort" + tools: + description: > + A list of tool enabled on the assistant. There can be a maximum of + 128 tools per assistant. Tools can be of types `code_interpreter`, + `file_search`, or `function`. + default: [] + type: array + maxItems: 128 + items: + oneOf: + - $ref: "#/components/schemas/AssistantToolsCode" + - $ref: "#/components/schemas/AssistantToolsFileSearch" + - $ref: "#/components/schemas/AssistantToolsFunction" + tool_resources: + type: object + description: > + A set of resources that are used by the assistant's tools. The + resources are specific to the type of tool. For example, the + `code_interpreter` tool requires a list of file IDs, while the + `file_search` tool requires a list of vector store IDs. + properties: + code_interpreter: + type: object + properties: + file_ids: + type: array + description: > + A list of [file](/docs/api-reference/files) IDs made + available to the `code_interpreter` tool. There can be a + maximum of 20 files associated with the tool. + default: [] + maxItems: 20 + items: + type: string + file_search: + type: object + properties: + vector_store_ids: + type: array + description: > + The [vector store](/docs/api-reference/vector-stores/object) + attached to this assistant. There can be a maximum of 1 + vector store attached to the assistant. + maxItems: 1 + items: + type: string + vector_stores: + type: array + description: > + A helper to create a [vector + store](/docs/api-reference/vector-stores/object) with + file_ids and attach it to this assistant. There can be a + maximum of 1 vector store attached to the assistant. + maxItems: 1 + items: + type: object + properties: + file_ids: + type: array + description: > + A list of [file](/docs/api-reference/files) IDs to add + to the vector store. There can be a maximum of 10000 + files in a vector store. + maxItems: 10000 + items: + type: string + chunking_strategy: + type: object + description: The chunking strategy used to chunk the file(s). If not set, will + use the `auto` strategy. + oneOf: + - type: object + title: Auto Chunking Strategy + description: The default strategy. This strategy currently uses a + `max_chunk_size_tokens` of `800` and + `chunk_overlap_tokens` of `400`. + additionalProperties: false + properties: + type: + type: string + description: Always `auto`. + enum: + - auto + x-stainless-const: true + required: + - type + - type: object + title: Static Chunking Strategy + additionalProperties: false + properties: + type: + type: string + description: Always `static`. + enum: + - static + x-stainless-const: true + static: + type: object + additionalProperties: false + properties: + max_chunk_size_tokens: + type: integer + minimum: 100 + maximum: 4096 + description: The maximum number of tokens in each chunk. The default value is + `800`. The minimum value is `100` and the + maximum value is `4096`. + chunk_overlap_tokens: + type: integer + description: > + The number of tokens that overlap between + chunks. The default value is `400`. + + + Note that the overlap must not exceed half + of `max_chunk_size_tokens`. + required: + - max_chunk_size_tokens + - chunk_overlap_tokens + required: + - type + - static + metadata: + $ref: "#/components/schemas/Metadata" + oneOf: + - required: + - vector_store_ids + - required: + - vector_stores + nullable: true + metadata: + $ref: "#/components/schemas/Metadata" + temperature: + description: > + What sampling temperature to use, between 0 and 2. Higher values + like 0.8 will make the output more random, while lower values like + 0.2 will make it more focused and deterministic. + type: number + minimum: 0 + maximum: 2 + default: 1 + example: 1 + nullable: true + top_p: + type: number + minimum: 0 + maximum: 1 + default: 1 + example: 1 + nullable: true + description: > + An alternative to sampling with temperature, called nucleus + sampling, where the model considers the results of the tokens with + top_p probability mass. So 0.1 means only the tokens comprising the + top 10% probability mass are considered. + + + We generally recommend altering this or temperature but not both. + response_format: + $ref: "#/components/schemas/AssistantsApiResponseFormatOption" + nullable: true + required: + - model + CreateChatCompletionRequest: + allOf: + - $ref: "#/components/schemas/CreateModelResponseProperties" + - type: object + properties: + messages: + description: > + A list of messages comprising the conversation so far. Depending + on the + + [model](/docs/models) you use, different message types + (modalities) are + + supported, like [text](/docs/guides/text-generation), + + [images](/docs/guides/vision), and [audio](/docs/guides/audio). + type: array + minItems: 1 + items: + $ref: "#/components/schemas/ChatCompletionRequestMessage" + model: + description: > + Model ID used to generate the response, like `gpt-4o` or `o3`. + OpenAI + + offers a wide range of models with different capabilities, + performance + + characteristics, and price points. Refer to the [model + guide](/docs/models) + + to browse and compare available models. + $ref: "#/components/schemas/ModelIdsShared" + modalities: + $ref: "#/components/schemas/ResponseModalities" + reasoning_effort: + $ref: "#/components/schemas/ReasoningEffort" + max_completion_tokens: + description: > + An upper bound for the number of tokens that can be generated + for a completion, including visible output tokens and [reasoning + tokens](/docs/guides/reasoning). + type: integer + nullable: true + frequency_penalty: + type: number + default: 0 + minimum: -2 + maximum: 2 + nullable: true + description: > + Number between -2.0 and 2.0. Positive values penalize new tokens + based on + + their existing frequency in the text so far, decreasing the + model's + + likelihood to repeat the same line verbatim. + presence_penalty: + type: number + default: 0 + minimum: -2 + maximum: 2 + nullable: true + description: > + Number between -2.0 and 2.0. Positive values penalize new tokens + based on + + whether they appear in the text so far, increasing the model's + likelihood + + to talk about new topics. + web_search_options: + type: object + title: Web search + description: > + This tool searches the web for relevant results to use in a + response. + + Learn more about the [web search + tool](/docs/guides/tools-web-search?api-mode=chat). + properties: + user_location: + type: object + nullable: true + required: + - type + - approximate + description: | + Approximate location parameters for the search. + properties: + type: + type: string + description: > + The type of location approximation. Always `approximate`. + enum: + - approximate + x-stainless-const: true + approximate: + $ref: "#/components/schemas/WebSearchLocation" + search_context_size: + $ref: "#/components/schemas/WebSearchContextSize" + top_logprobs: + description: > + An integer between 0 and 20 specifying the number of most likely + tokens to + + return at each token position, each with an associated log + probability. + + `logprobs` must be set to `true` if this parameter is used. + type: integer + minimum: 0 + maximum: 20 + nullable: true + response_format: + description: > + An object specifying the format that the model must output. + + + Setting to `{ "type": "json_schema", "json_schema": {...} }` + enables + + Structured Outputs which ensures the model will match your + supplied JSON + + schema. Learn more in the [Structured Outputs + + guide](/docs/guides/structured-outputs). + + + Setting to `{ "type": "json_object" }` enables the older JSON + mode, which + + ensures the message the model generates is valid JSON. Using + `json_schema` + + is preferred for models that support it. + oneOf: + - $ref: "#/components/schemas/ResponseFormatText" + - $ref: "#/components/schemas/ResponseFormatJsonSchema" + - $ref: "#/components/schemas/ResponseFormatJsonObject" + audio: + type: object + nullable: true + description: > + Parameters for audio output. Required when audio output is + requested with + + `modalities: ["audio"]`. [Learn more](/docs/guides/audio). + required: + - voice + - format + properties: + voice: + $ref: "#/components/schemas/VoiceIdsShared" + description: > + The voice the model uses to respond. Supported voices are + + `alloy`, `ash`, `ballad`, `coral`, `echo`, `fable`, `nova`, + `onyx`, `sage`, and `shimmer`. + format: + type: string + enum: + - wav + - aac + - mp3 + - flac + - opus + - pcm16 + description: > + Specifies the output audio format. Must be one of `wav`, + `mp3`, `flac`, + + `opus`, or `pcm16`. + store: + type: boolean + default: false + nullable: true + description: > + Whether or not to store the output of this chat completion + request for + + use in our [model distillation](/docs/guides/distillation) or + + [evals](/docs/guides/evals) products. + stream: + description: | + If set to true, the model response data will be streamed to the client + as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). + See the [Streaming section below](/docs/api-reference/chat/streaming) + for more information, along with the [streaming responses](/docs/guides/streaming-responses) + guide for more information on how to handle the streaming events. + type: boolean + nullable: true + default: false + stop: + $ref: "#/components/schemas/StopConfiguration" + logit_bias: + type: object + x-oaiTypeLabel: map + default: null + nullable: true + additionalProperties: + type: integer + description: > + Modify the likelihood of specified tokens appearing in the + completion. + + + Accepts a JSON object that maps tokens (specified by their token + ID in the + + tokenizer) to an associated bias value from -100 to 100. + Mathematically, + + the bias is added to the logits generated by the model prior to + sampling. + + The exact effect will vary per model, but values between -1 and + 1 should + + decrease or increase likelihood of selection; values like -100 + or 100 + + should result in a ban or exclusive selection of the relevant + token. + logprobs: + description: > + Whether to return log probabilities of the output tokens or not. + If true, + + returns the log probabilities of each output token returned in + the + + `content` of `message`. + type: boolean + default: false + nullable: true + max_tokens: + description: > + The maximum number of [tokens](/tokenizer) that can be generated + in the + + chat completion. This value can be used to control + + [costs](https://openai.com/api/pricing/) for text generated via + API. + + + This value is now deprecated in favor of + `max_completion_tokens`, and is + + not compatible with [o-series models](/docs/guides/reasoning). + type: integer + nullable: true + deprecated: true + n: + type: integer + minimum: 1 + maximum: 128 + default: 1 + example: 1 + nullable: true + description: How many chat completion choices to generate for each input + message. Note that you will be charged based on the number of + generated tokens across all of the choices. Keep `n` as `1` to + minimize costs. + prediction: + nullable: true + description: > + Configuration for a [Predicted + Output](/docs/guides/predicted-outputs), + + which can greatly improve response times when large parts of the + model + + response are known ahead of time. This is most common when you + are + + regenerating a file with only minor changes to most of the + content. + oneOf: + - $ref: "#/components/schemas/PredictionContent" + seed: + type: integer + minimum: -9223372036854776000 + maximum: 9223372036854776000 + nullable: true + description: > + This feature is in Beta. + + If specified, our system will make a best effort to sample + deterministically, such that repeated requests with the same + `seed` and parameters should return the same result. + + Determinism is not guaranteed, and you should refer to the + `system_fingerprint` response parameter to monitor changes in + the backend. + x-oaiMeta: + beta: true + stream_options: + $ref: "#/components/schemas/ChatCompletionStreamOptions" + tools: + type: array + description: > + A list of tools the model may call. Currently, only functions + are supported as a tool. Use this to provide a list of functions + the model may generate JSON inputs for. A max of 128 functions + are supported. + items: + $ref: "#/components/schemas/ChatCompletionTool" + tool_choice: + $ref: "#/components/schemas/ChatCompletionToolChoiceOption" + parallel_tool_calls: + $ref: "#/components/schemas/ParallelToolCalls" + function_call: + deprecated: true + description: > + Deprecated in favor of `tool_choice`. + + + Controls which (if any) function is called by the model. + + + `none` means the model will not call a function and instead + generates a + + message. + + + `auto` means the model can pick between generating a message or + calling a + + function. + + + Specifying a particular function via `{"name": "my_function"}` + forces the + + model to call that function. + + + `none` is the default when no functions are present. `auto` is + the default + + if functions are present. + oneOf: + - type: string + description: > + `none` means the model will not call a function and instead + generates a message. `auto` means the model can pick between + generating a message or calling a function. + enum: + - none + - auto + - $ref: "#/components/schemas/ChatCompletionFunctionCallOption" + functions: + deprecated: true + description: | + Deprecated in favor of `tools`. + + A list of functions the model may generate JSON inputs for. + type: array + minItems: 1 + maxItems: 128 + items: + $ref: "#/components/schemas/ChatCompletionFunctions" + required: + - model + - messages + CreateChatCompletionResponse: + type: object + description: Represents a chat completion response returned by model, based on + the provided input. + properties: + id: + type: string + description: A unique identifier for the chat completion. + choices: + type: array + description: A list of chat completion choices. Can be more than one if `n` is + greater than 1. + items: + type: object + required: + - finish_reason + - index + - message + - logprobs + properties: + finish_reason: + type: string + description: > + The reason the model stopped generating tokens. This will be + `stop` if the model hit a natural stop point or a provided + stop sequence, + + `length` if the maximum number of tokens specified in the + request was reached, + + `content_filter` if content was omitted due to a flag from our + content filters, + + `tool_calls` if the model called a tool, or `function_call` + (deprecated) if the model called a function. + enum: + - stop + - length + - tool_calls + - content_filter + - function_call + index: + type: integer + description: The index of the choice in the list of choices. + message: + $ref: "#/components/schemas/ChatCompletionResponseMessage" + logprobs: + description: Log probability information for the choice. + type: object + nullable: true + properties: + content: + description: A list of message content tokens with log probability information. + type: array + items: + $ref: "#/components/schemas/ChatCompletionTokenLogprob" + nullable: true + refusal: + description: A list of message refusal tokens with log probability information. + type: array + items: + $ref: "#/components/schemas/ChatCompletionTokenLogprob" + nullable: true + required: + - content + - refusal + created: + type: integer + description: The Unix timestamp (in seconds) of when the chat completion was + created. + model: + type: string + description: The model used for the chat completion. + service_tier: + $ref: "#/components/schemas/ServiceTier" + system_fingerprint: + type: string + description: > + This fingerprint represents the backend configuration that the model + runs with. + + + Can be used in conjunction with the `seed` request parameter to + understand when backend changes have been made that might impact + determinism. + object: + type: string + description: The object type, which is always `chat.completion`. + enum: + - chat.completion + x-stainless-const: true + usage: + $ref: "#/components/schemas/CompletionUsage" + required: + - choices + - created + - id + - model + - object + x-oaiMeta: + name: The chat completion object + group: chat + example: > + { + "id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG", + "object": "chat.completion", + "created": 1741570283, + "model": "gpt-4o-2024-08-06", + "choices": [ + { + "index": 0, + "message": { + "role": "assistant", + "content": "The image shows a wooden boardwalk path running through a lush green field or meadow. The sky is bright blue with some scattered clouds, giving the scene a serene and peaceful atmosphere. Trees and shrubs are visible in the background.", + "refusal": null, + "annotations": [] + }, + "logprobs": null, + "finish_reason": "stop" + } + ], + "usage": { + "prompt_tokens": 1117, + "completion_tokens": 46, + "total_tokens": 1163, + "prompt_tokens_details": { + "cached_tokens": 0, + "audio_tokens": 0 + }, + "completion_tokens_details": { + "reasoning_tokens": 0, + "audio_tokens": 0, + "accepted_prediction_tokens": 0, + "rejected_prediction_tokens": 0 + } + }, + "service_tier": "default", + "system_fingerprint": "fp_fc9f1d7035" + } + CreateChatCompletionStreamResponse: + type: object + description: | + Represents a streamed chunk of a chat completion response returned + by the model, based on the provided input. + [Learn more](/docs/guides/streaming-responses). + properties: + id: + type: string + description: A unique identifier for the chat completion. Each chunk has the + same ID. + choices: + type: array + description: > + A list of chat completion choices. Can contain more than one + elements if `n` is greater than 1. Can also be empty for the + + last chunk if you set `stream_options: {"include_usage": true}`. + items: + type: object + required: + - delta + - finish_reason + - index + properties: + delta: + $ref: "#/components/schemas/ChatCompletionStreamResponseDelta" + logprobs: + description: Log probability information for the choice. + type: object + nullable: true + properties: + content: + description: A list of message content tokens with log probability information. + type: array + items: + $ref: "#/components/schemas/ChatCompletionTokenLogprob" + nullable: true + refusal: + description: A list of message refusal tokens with log probability information. + type: array + items: + $ref: "#/components/schemas/ChatCompletionTokenLogprob" + nullable: true + required: + - content + - refusal + finish_reason: + type: string + description: > + The reason the model stopped generating tokens. This will be + `stop` if the model hit a natural stop point or a provided + stop sequence, + + `length` if the maximum number of tokens specified in the + request was reached, + + `content_filter` if content was omitted due to a flag from our + content filters, + + `tool_calls` if the model called a tool, or `function_call` + (deprecated) if the model called a function. + enum: + - stop + - length + - tool_calls + - content_filter + - function_call + nullable: true + index: + type: integer + description: The index of the choice in the list of choices. + created: + type: integer + description: The Unix timestamp (in seconds) of when the chat completion was + created. Each chunk has the same timestamp. + model: + type: string + description: The model to generate the completion. + service_tier: + $ref: "#/components/schemas/ServiceTier" + system_fingerprint: + type: string + description: > + This fingerprint represents the backend configuration that the model + runs with. + + Can be used in conjunction with the `seed` request parameter to + understand when backend changes have been made that might impact + determinism. + object: + type: string + description: The object type, which is always `chat.completion.chunk`. + enum: + - chat.completion.chunk + x-stainless-const: true + usage: + $ref: "#/components/schemas/CompletionUsage" + nullable: true + description: > + An optional field that will only be present when you set + + `stream_options: {"include_usage": true}` in your request. When + present, it + + contains a null value **except for the last chunk** which contains + the + + token usage statistics for the entire request. + + + **NOTE:** If the stream is interrupted or cancelled, you may not + + receive the final usage chunk which contains the total token usage + for + + the request. + required: + - choices + - created + - id + - model + - object + x-oaiMeta: + name: The chat completion chunk object + group: chat + example: | + {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]} + + {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"content":"Hello"},"logprobs":null,"finish_reason":null}]} + + .... + + {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}]} + CreateCompletionRequest: + type: object + properties: + model: + description: > + ID of the model to use. You can use the [List + models](/docs/api-reference/models/list) API to see all of your + available models, or see our [Model overview](/docs/models) for + descriptions of them. + anyOf: + - type: string + - type: string + enum: + - gpt-3.5-turbo-instruct + - davinci-002 + - babbage-002 + x-oaiTypeLabel: string + prompt: + description: > + The prompt(s) to generate completions for, encoded as a string, + array of strings, array of tokens, or array of token arrays. + + + Note that <|endoftext|> is the document separator that the model + sees during training, so if a prompt is not specified the model will + generate as if from the beginning of a new document. + default: <|endoftext|> + nullable: true + oneOf: + - type: string + default: "" + example: This is a test. + - type: array + items: + type: string + default: "" + example: This is a test. + - type: array + minItems: 1 + items: + type: integer + example: "[1212, 318, 257, 1332, 13]" + - type: array + minItems: 1 + items: + type: array + minItems: 1 + items: + type: integer + example: "[[1212, 318, 257, 1332, 13]]" + best_of: + type: integer + default: 1 + minimum: 0 + maximum: 20 + nullable: true + description: > + Generates `best_of` completions server-side and returns the "best" + (the one with the highest log probability per token). Results cannot + be streamed. + + + When used with `n`, `best_of` controls the number of candidate + completions and `n` specifies how many to return – `best_of` must be + greater than `n`. + + + **Note:** Because this parameter generates many completions, it can + quickly consume your token quota. Use carefully and ensure that you + have reasonable settings for `max_tokens` and `stop`. + echo: + type: boolean + default: false + nullable: true + description: | + Echo back the prompt in addition to the completion + frequency_penalty: + type: number + default: 0 + minimum: -2 + maximum: 2 + nullable: true + description: > + Number between -2.0 and 2.0. Positive values penalize new tokens + based on their existing frequency in the text so far, decreasing the + model's likelihood to repeat the same line verbatim. + + + [See more information about frequency and presence + penalties.](/docs/guides/text-generation) + logit_bias: + type: object + x-oaiTypeLabel: map + default: null + nullable: true + additionalProperties: + type: integer + description: > + Modify the likelihood of specified tokens appearing in the + completion. + + + Accepts a JSON object that maps tokens (specified by their token ID + in the GPT tokenizer) to an associated bias value from -100 to 100. + You can use this [tokenizer tool](/tokenizer?view=bpe) to convert + text to token IDs. Mathematically, the bias is added to the logits + generated by the model prior to sampling. The exact effect will vary + per model, but values between -1 and 1 should decrease or increase + likelihood of selection; values like -100 or 100 should result in a + ban or exclusive selection of the relevant token. + + + As an example, you can pass `{"50256": -100}` to prevent the + <|endoftext|> token from being generated. + logprobs: + type: integer + minimum: 0 + maximum: 5 + default: null + nullable: true + description: > + Include the log probabilities on the `logprobs` most likely output + tokens, as well the chosen tokens. For example, if `logprobs` is 5, + the API will return a list of the 5 most likely tokens. The API will + always return the `logprob` of the sampled token, so there may be up + to `logprobs+1` elements in the response. + + + The maximum value for `logprobs` is 5. + max_tokens: + type: integer + minimum: 0 + default: 16 + example: 16 + nullable: true + description: | + The maximum number of [tokens](/tokenizer) that can be generated in the completion. + + The token count of your prompt plus `max_tokens` cannot exceed the model's context length. [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken) for counting tokens. + n: + type: integer + minimum: 1 + maximum: 128 + default: 1 + example: 1 + nullable: true + description: > + How many completions to generate for each prompt. + + + **Note:** Because this parameter generates many completions, it can + quickly consume your token quota. Use carefully and ensure that you + have reasonable settings for `max_tokens` and `stop`. + presence_penalty: + type: number + default: 0 + minimum: -2 + maximum: 2 + nullable: true + description: > + Number between -2.0 and 2.0. Positive values penalize new tokens + based on whether they appear in the text so far, increasing the + model's likelihood to talk about new topics. + + + [See more information about frequency and presence + penalties.](/docs/guides/text-generation) + seed: + type: integer + format: int64 + nullable: true + description: > + If specified, our system will make a best effort to sample + deterministically, such that repeated requests with the same `seed` + and parameters should return the same result. + + + Determinism is not guaranteed, and you should refer to the + `system_fingerprint` response parameter to monitor changes in the + backend. + stop: + $ref: "#/components/schemas/StopConfiguration" + stream: + description: | + Whether to stream back partial progress. If set, tokens will be sent as data-only [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format) as they become available, with the stream terminated by a `data: [DONE]` message. [Example Python code](https://cookbook.openai.com/examples/how_to_stream_completions). + type: boolean + nullable: true + default: false + stream_options: + $ref: "#/components/schemas/ChatCompletionStreamOptions" + suffix: + description: | + The suffix that comes after a completion of inserted text. + + This parameter is only supported for `gpt-3.5-turbo-instruct`. + default: null + nullable: true + type: string + example: test. + temperature: + type: number + minimum: 0 + maximum: 2 + default: 1 + example: 1 + nullable: true + description: > + What sampling temperature to use, between 0 and 2. Higher values + like 0.8 will make the output more random, while lower values like + 0.2 will make it more focused and deterministic. + + + We generally recommend altering this or `top_p` but not both. + top_p: + type: number + minimum: 0 + maximum: 1 + default: 1 + example: 1 + nullable: true + description: > + An alternative to sampling with temperature, called nucleus + sampling, where the model considers the results of the tokens with + top_p probability mass. So 0.1 means only the tokens comprising the + top 10% probability mass are considered. + + + We generally recommend altering this or `temperature` but not both. + user: + type: string + example: user-1234 + description: > + A unique identifier representing your end-user, which can help + OpenAI to monitor and detect abuse. [Learn + more](/docs/guides/safety-best-practices#end-user-ids). + required: + - model + - prompt + CreateCompletionResponse: + type: object + description: > + Represents a completion response from the API. Note: both the streamed + and non-streamed response objects share the same shape (unlike the chat + endpoint). + properties: + id: + type: string + description: A unique identifier for the completion. + choices: + type: array + description: The list of completion choices the model generated for the input + prompt. + items: + type: object + required: + - finish_reason + - index + - logprobs + - text + properties: + finish_reason: + type: string + description: > + The reason the model stopped generating tokens. This will be + `stop` if the model hit a natural stop point or a provided + stop sequence, + + `length` if the maximum number of tokens specified in the + request was reached, + + or `content_filter` if content was omitted due to a flag from + our content filters. + enum: + - stop + - length + - content_filter + index: + type: integer + logprobs: + type: object + nullable: true + properties: + text_offset: + type: array + items: + type: integer + token_logprobs: + type: array + items: + type: number + tokens: + type: array + items: + type: string + top_logprobs: + type: array + items: + type: object + additionalProperties: + type: number + text: + type: string + created: + type: integer + description: The Unix timestamp (in seconds) of when the completion was created. + model: + type: string + description: The model used for completion. + system_fingerprint: + type: string + description: > + This fingerprint represents the backend configuration that the model + runs with. + + + Can be used in conjunction with the `seed` request parameter to + understand when backend changes have been made that might impact + determinism. + object: + type: string + description: The object type, which is always "text_completion" + enum: + - text_completion + x-stainless-const: true + usage: + $ref: "#/components/schemas/CompletionUsage" + required: + - id + - object + - created + - model + - choices + x-oaiMeta: + name: The completion object + legacy: true + example: | + { + "id": "cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7", + "object": "text_completion", + "created": 1589478378, + "model": "gpt-4-turbo", + "choices": [ + { + "text": "\n\nThis is indeed a test", + "index": 0, + "logprobs": null, + "finish_reason": "length" + } + ], + "usage": { + "prompt_tokens": 5, + "completion_tokens": 7, + "total_tokens": 12 + } + } + CreateEmbeddingRequest: + type: object + additionalProperties: false + properties: + input: + description: | + Input text to embed, encoded as a string or array of tokens. To embed multiple inputs in a single request, pass an array of strings or array of token arrays. The input must not exceed the max input tokens for the model (8192 tokens for `text-embedding-ada-002`), cannot be an empty string, and any array must be 2048 dimensions or less. [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken) for counting tokens. Some models may also impose a limit on total number of tokens summed across inputs. + example: The quick brown fox jumped over the lazy dog + oneOf: + - type: string + title: string + description: The string that will be turned into an embedding. + default: "" + example: This is a test. + - type: array + title: array + description: The array of strings that will be turned into an embedding. + minItems: 1 + maxItems: 2048 + items: + type: string + default: "" + example: "['This is a test.']" + - type: array + title: array + description: The array of integers that will be turned into an embedding. + minItems: 1 + maxItems: 2048 + items: + type: integer + example: "[1212, 318, 257, 1332, 13]" + - type: array + title: array + description: The array of arrays containing integers that will be turned into an + embedding. + minItems: 1 + maxItems: 2048 + items: + type: array + minItems: 1 + items: + type: integer + example: "[[1212, 318, 257, 1332, 13]]" + model: + description: > + ID of the model to use. You can use the [List + models](/docs/api-reference/models/list) API to see all of your + available models, or see our [Model overview](/docs/models) for + descriptions of them. + example: text-embedding-3-small + anyOf: + - type: string + - type: string + enum: + - text-embedding-ada-002 + - text-embedding-3-small + - text-embedding-3-large + x-oaiTypeLabel: string + encoding_format: + description: The format to return the embeddings in. Can be either `float` or + [`base64`](https://pypi.org/project/pybase64/). + example: float + default: float + type: string + enum: + - float + - base64 + dimensions: + description: > + The number of dimensions the resulting output embeddings should + have. Only supported in `text-embedding-3` and later models. + type: integer + minimum: 1 + user: + type: string + example: user-1234 + description: > + A unique identifier representing your end-user, which can help + OpenAI to monitor and detect abuse. [Learn + more](/docs/guides/safety-best-practices#end-user-ids). + required: + - model + - input + CreateEmbeddingResponse: + type: object + properties: + data: + type: array + description: The list of embeddings generated by the model. + items: + $ref: "#/components/schemas/Embedding" + model: + type: string + description: The name of the model used to generate the embedding. + object: + type: string + description: The object type, which is always "list". + enum: + - list + x-stainless-const: true + usage: + type: object + description: The usage information for the request. + properties: + prompt_tokens: + type: integer + description: The number of tokens used by the prompt. + total_tokens: + type: integer + description: The total number of tokens used by the request. + required: + - prompt_tokens + - total_tokens + required: + - object + - model + - data + - usage + CreateEvalCompletionsRunDataSource: + type: object + title: CompletionsRunDataSource + description: > + A CompletionsRunDataSource object describing a model sampling + configuration. + properties: + type: + type: string + enum: + - completions + default: completions + description: The type of run data source. Always `completions`. + input_messages: + oneOf: + - type: object + title: TemplateInputMessages + properties: + type: + type: string + enum: + - template + description: The type of input messages. Always `template`. + template: + type: array + description: A list of chat messages forming the prompt or context. May include + variable references to the "item" namespace, ie + {{item.name}}. + items: + oneOf: + - $ref: "#/components/schemas/EasyInputMessage" + - $ref: "#/components/schemas/EvalItem" + required: + - type + - template + - type: object + title: ItemReferenceInputMessages + properties: + type: + type: string + enum: + - item_reference + description: The type of input messages. Always `item_reference`. + item_reference: + type: string + description: A reference to a variable in the "item" namespace. Ie, "item.name" + required: + - type + - item_reference + sampling_params: + type: object + properties: + temperature: + type: number + description: A higher temperature increases randomness in the outputs. + default: 1 + max_completion_tokens: + type: integer + description: The maximum number of tokens in the generated output. + top_p: + type: number + description: An alternative to temperature for nucleus sampling; 1.0 includes + all tokens. + default: 1 + seed: + type: integer + description: A seed value to initialize the randomness, during sampling. + default: 42 + model: + type: string + description: The name of the model to use for generating completions (e.g. + "o3-mini"). + source: + oneOf: + - $ref: "#/components/schemas/EvalJsonlFileContentSource" + - $ref: "#/components/schemas/EvalJsonlFileIdSource" + - $ref: "#/components/schemas/EvalStoredCompletionsSource" + required: + - type + - source + x-oaiMeta: + name: The completions data source object used to configure an individual run + group: eval runs + example: | + { + "name": "gpt-4o-mini-2024-07-18", + "data_source": { + "type": "completions", + "input_messages": { + "type": "item_reference", + "item_reference": "item.input" + }, + "model": "gpt-4o-mini-2024-07-18", + "source": { + "type": "stored_completions", + "model": "gpt-4o-mini-2024-07-18" + } + } + } + CreateEvalCustomDataSourceConfig: + type: object + title: CustomDataSourceConfig + description: > + A CustomDataSourceConfig object that defines the schema for the data + source used for the evaluation runs. + + This schema is used to define the shape of the data that will be: + + - Used to define your testing criteria and + + - What data is required when creating a run + properties: + type: + type: string + enum: + - custom + default: custom + description: The type of data source. Always `custom`. + x-stainless-const: true + item_schema: + type: object + description: The json schema for each row in the data source. + additionalProperties: true + example: | + { + "type": "object", + "properties": { + "name": {"type": "string"}, + "age": {"type": "integer"} + }, + "required": ["name", "age"] + } + include_sample_schema: + type: boolean + default: false + description: Whether the eval should expect you to populate the sample namespace + (ie, by generating responses off of your data source) + required: + - item_schema + - type + x-oaiMeta: + name: The eval file data source config object + group: evals + example: | + { + "type": "custom", + "item_schema": { + "type": "object", + "properties": { + "name": {"type": "string"}, + "age": {"type": "integer"} + }, + "required": ["name", "age"] + }, + "include_sample_schema": true + } + CreateEvalItem: + title: CreateEvalItem + description: A chat message that makes up the prompt or context. May include + variable references to the "item" namespace, ie {{item.name}}. + type: object + oneOf: + - type: object + title: SimpleInputMessage + properties: + role: + type: string + description: The role of the message (e.g. "system", "assistant", "user"). + content: + type: string + description: The content of the message. + required: + - role + - content + - $ref: "#/components/schemas/EvalItem" + x-oaiMeta: + name: The chat message object used to configure an individual run + CreateEvalJsonlRunDataSource: + type: object + title: JsonlRunDataSource + description: > + A JsonlRunDataSource object with that specifies a JSONL file that + matches the eval + properties: + type: + type: string + enum: + - jsonl + default: jsonl + description: The type of data source. Always `jsonl`. + x-stainless-const: true + source: + oneOf: + - $ref: "#/components/schemas/EvalJsonlFileContentSource" + - $ref: "#/components/schemas/EvalJsonlFileIdSource" + required: + - type + - source + x-oaiMeta: + name: The file data source object for the eval run configuration + group: evals + example: | + { + "type": "jsonl", + "source": { + "type": "file_id", + "id": "file-9GYS6xbkWgWhmE7VoLUWFg" + } + } + CreateEvalLabelModelGrader: + type: object + title: LabelModelGrader + description: > + A LabelModelGrader object which uses a model to assign labels to each + item + + in the evaluation. + properties: + type: + description: The object type, which is always `label_model`. + type: string + enum: + - label_model + x-stainless-const: true + name: + type: string + description: The name of the grader. + model: + type: string + description: The model to use for the evaluation. Must support structured outputs. + input: + type: array + description: A list of chat messages forming the prompt or context. May include + variable references to the "item" namespace, ie {{item.name}}. + items: + $ref: "#/components/schemas/CreateEvalItem" + labels: + type: array + items: + type: string + description: The labels to classify to each item in the evaluation. + passing_labels: + type: array + items: + type: string + description: The labels that indicate a passing result. Must be a subset of + labels. + required: + - type + - model + - input + - passing_labels + - labels + - name + x-oaiMeta: + name: The eval label model grader object + group: evals + example: > + { + "type": "label_model", + "model": "gpt-4o-2024-08-06", + "input": [ + { + "role": "system", + "content": "Classify the sentiment of the following statement as one of 'positive', 'neutral', or 'negative'" + }, + { + "role": "user", + "content": "Statement: {{item.response}}" + } + ], + "passing_labels": ["positive"], + "labels": ["positive", "neutral", "negative"], + "name": "Sentiment label grader" + } + CreateEvalLogsDataSourceConfig: + type: object + title: LogsDataSourceConfig + description: > + A data source config which specifies the metadata property of your + stored completions query. + + This is usually metadata like `usecase=chatbot` or `prompt-version=v2`, + etc. + properties: + type: + type: string + enum: + - logs + default: logs + description: The type of data source. Always `logs`. + x-stainless-const: true + metadata: + type: object + description: Metadata filters for the logs data source. + additionalProperties: true + example: | + { + "use_case": "customer_support_agent" + } + required: + - type + x-oaiMeta: + name: The logs data source object for evals + group: evals + example: | + { + "type": "logs", + "metadata": { + "use_case": "customer_support_agent" + } + } + CreateEvalRequest: + type: object + title: CreateEvalRequest + properties: + name: + type: string + description: The name of the evaluation. + metadata: + $ref: "#/components/schemas/Metadata" + data_source_config: + type: object + description: The configuration for the data source used for the evaluation runs. + oneOf: + - $ref: "#/components/schemas/CreateEvalCustomDataSourceConfig" + - $ref: "#/components/schemas/CreateEvalLogsDataSourceConfig" + testing_criteria: + type: array + description: A list of graders for all eval runs in this group. + items: + oneOf: + - $ref: "#/components/schemas/CreateEvalLabelModelGrader" + - $ref: "#/components/schemas/EvalStringCheckGrader" + - $ref: "#/components/schemas/EvalTextSimilarityGrader" + - $ref: "#/components/schemas/EvalPythonGrader" + - $ref: "#/components/schemas/EvalScoreModelGrader" + required: + - data_source_config + - testing_criteria + CreateEvalResponsesRunDataSource: + type: object + title: ResponsesRunDataSource + description: > + A ResponsesRunDataSource object describing a model sampling + configuration. + properties: + type: + type: string + enum: + - completions + default: completions + description: The type of run data source. Always `completions`. + input_messages: + oneOf: + - type: object + properties: + type: + type: string + enum: + - template + description: The type of input messages. Always `template`. + template: + type: array + description: A list of chat messages forming the prompt or context. May include + variable references to the "item" namespace, ie + {{item.name}}. + items: + oneOf: + - type: object + title: ChatMessage + properties: + role: + type: string + description: The role of the message (e.g. "system", "assistant", "user"). + content: + type: string + description: The content of the message. + required: + - role + - content + - $ref: "#/components/schemas/EvalItem" + required: + - type + - template + - type: object + properties: + type: + type: string + enum: + - item_reference + description: The type of input messages. Always `item_reference`. + item_reference: + type: string + description: A reference to a variable in the "item" namespace. Ie, "item.name" + required: + - type + - item_reference + sampling_params: + type: object + properties: + temperature: + type: number + description: A higher temperature increases randomness in the outputs. + default: 1 + max_completion_tokens: + type: integer + description: The maximum number of tokens in the generated output. + top_p: + type: number + description: An alternative to temperature for nucleus sampling; 1.0 includes + all tokens. + default: 1 + seed: + type: integer + description: A seed value to initialize the randomness, during sampling. + default: 42 + model: + type: string + description: The name of the model to use for generating completions (e.g. + "o3-mini"). + source: + oneOf: + - $ref: "#/components/schemas/EvalJsonlFileContentSource" + - $ref: "#/components/schemas/EvalJsonlFileIdSource" + - $ref: "#/components/schemas/EvalResponsesSource" + required: + - type + - source + x-oaiMeta: + name: The completions data source object used to configure an individual run + group: eval runs + example: | + { + "name": "gpt-4o-mini-2024-07-18", + "data_source": { + "type": "completions", + "input_messages": { + "type": "item_reference", + "item_reference": "item.input" + }, + "model": "gpt-4o-mini-2024-07-18", + "source": { + "type": "stored_completions", + "model": "gpt-4o-mini-2024-07-18" + } + } + } + CreateEvalRunRequest: + type: object + title: CreateEvalRunRequest + properties: + name: + type: string + description: The name of the run. + metadata: + $ref: "#/components/schemas/Metadata" + data_source: + type: object + description: Details about the run's data source. + oneOf: + - $ref: "#/components/schemas/CreateEvalJsonlRunDataSource" + - $ref: "#/components/schemas/CreateEvalCompletionsRunDataSource" + - $ref: "#/components/schemas/CreateEvalResponsesRunDataSource" + required: + - data_source + CreateFileRequest: + type: object + additionalProperties: false + properties: + file: + description: | + The File object (not file name) to be uploaded. + type: string + format: binary + purpose: + description: > + The intended purpose of the uploaded file. One of: - `assistants`: + Used in the Assistants API - `batch`: Used in the Batch API - + `fine-tune`: Used for fine-tuning - `vision`: Images used for vision + fine-tuning - `user_data`: Flexible file type for any purpose - + `evals`: Used for eval data sets + type: string + enum: + - assistants + - batch + - fine-tune + - vision + - user_data + - evals + required: + - file + - purpose + CreateFineTuningCheckpointPermissionRequest: + type: object + additionalProperties: false + properties: + project_ids: + type: array + description: The project identifiers to grant access to. + items: + type: string + required: + - project_ids + CreateFineTuningJobRequest: + type: object + properties: + model: + description: > + The name of the model to fine-tune. You can select one of the + + [supported + models](/docs/guides/fine-tuning#which-models-can-be-fine-tuned). + example: gpt-4o-mini + anyOf: + - type: string + - type: string + enum: + - babbage-002 + - davinci-002 + - gpt-3.5-turbo + - gpt-4o-mini + x-oaiTypeLabel: string + training_file: + description: > + The ID of an uploaded file that contains training data. + + + See [upload file](/docs/api-reference/files/create) for how to + upload a file. + + + Your dataset must be formatted as a JSONL file. Additionally, you + must upload your file with the purpose `fine-tune`. + + + The contents of the file should differ depending on if the model + uses the [chat](/docs/api-reference/fine-tuning/chat-input), + [completions](/docs/api-reference/fine-tuning/completions-input) + format, or if the fine-tuning method uses the + [preference](/docs/api-reference/fine-tuning/preference-input) + format. + + + See the [fine-tuning guide](/docs/guides/fine-tuning) for more + details. + type: string + example: file-abc123 + hyperparameters: + type: object + description: > + The hyperparameters used for the fine-tuning job. + + This value is now deprecated in favor of `method`, and should be + passed in under the `method` parameter. + properties: + batch_size: + description: > + Number of examples in each batch. A larger batch size means that + model parameters + + are updated less frequently, but with lower variance. + oneOf: + - type: string + enum: + - auto + x-stainless-const: true + - type: integer + minimum: 1 + maximum: 256 + default: auto + learning_rate_multiplier: + description: > + Scaling factor for the learning rate. A smaller learning rate + may be useful to avoid + + overfitting. + oneOf: + - type: string + enum: + - auto + x-stainless-const: true + - type: number + minimum: 0 + exclusiveMinimum: true + default: auto + n_epochs: + description: > + The number of epochs to train the model for. An epoch refers to + one full cycle + + through the training dataset. + oneOf: + - type: string + enum: + - auto + x-stainless-const: true + - type: integer + minimum: 1 + maximum: 50 + default: auto + deprecated: true + suffix: + description: > + A string of up to 64 characters that will be added to your + fine-tuned model name. + + + For example, a `suffix` of "custom-model-name" would produce a model + name like `ft:gpt-4o-mini:openai:custom-model-name:7p4lURel`. + type: string + minLength: 1 + maxLength: 64 + default: null + nullable: true + validation_file: + description: > + The ID of an uploaded file that contains validation data. + + + If you provide this file, the data is used to generate validation + + metrics periodically during fine-tuning. These metrics can be viewed + in + + the fine-tuning results file. + + The same data should not be present in both train and validation + files. + + + Your dataset must be formatted as a JSONL file. You must upload your + file with the purpose `fine-tune`. + + + See the [fine-tuning guide](/docs/guides/fine-tuning) for more + details. + type: string + nullable: true + example: file-abc123 + integrations: + type: array + description: A list of integrations to enable for your fine-tuning job. + nullable: true + items: + type: object + required: + - type + - wandb + properties: + type: + description: > + The type of integration to enable. Currently, only "wandb" + (Weights and Biases) is supported. + oneOf: + - type: string + enum: + - wandb + x-stainless-const: true + wandb: + type: object + description: > + The settings for your integration with Weights and Biases. + This payload specifies the project that + + metrics will be sent to. Optionally, you can set an explicit + display name for your run, add tags + + to your run, and set a default entity (team, username, etc) to + be associated with your run. + required: + - project + properties: + project: + description: > + The name of the project that the new run will be created + under. + type: string + example: my-wandb-project + name: + description: > + A display name to set for the run. If not set, we will use + the Job ID as the name. + nullable: true + type: string + entity: + description: > + The entity to use for the run. This allows you to set the + team or username of the WandB user that you would + + like associated with the run. If not set, the default + entity for the registered WandB API key is used. + nullable: true + type: string + tags: + description: > + A list of tags to be attached to the newly created run. + These tags are passed through directly to WandB. Some + + default tags are generated by OpenAI: "openai/finetune", + "openai/{base-model}", "openai/{ftjob-abcdef}". + type: array + items: + type: string + example: custom-tag + seed: + description: > + The seed controls the reproducibility of the job. Passing in the + same seed and job parameters should produce the same results, but + may differ in rare cases. + + If a seed is not specified, one will be generated for you. + type: integer + nullable: true + minimum: 0 + maximum: 2147483647 + example: 42 + method: + $ref: "#/components/schemas/FineTuneMethod" + metadata: + $ref: "#/components/schemas/Metadata" + required: + - model + - training_file + CreateImageEditRequest: + type: object + properties: + image: + anyOf: + - type: string + format: binary + - type: array + maxItems: 16 + items: + type: string + format: binary + description: > + The image(s) to edit. Must be a supported image file or an array of + images. + + + For `gpt-image-1`, each image should be a `png`, `webp`, or `jpg` + file less + + than 25MB. You can provide up to 16 images. + + + For `dall-e-2`, you can only provide one image, and it should be a + square + + `png` file less than 4MB. + prompt: + description: A text description of the desired image(s). The maximum length is + 1000 characters for `dall-e-2`, and 32000 characters for + `gpt-image-1`. + type: string + example: A cute baby sea otter wearing a beret + mask: + description: An additional image whose fully transparent areas (e.g. where alpha + is zero) indicate where `image` should be edited. If there are + multiple images provided, the mask will be applied on the first + image. Must be a valid PNG file, less than 4MB, and have the same + dimensions as `image`. + type: string + format: binary + model: + anyOf: + - type: string + - type: string + enum: + - dall-e-2 + - gpt-image-1 + x-stainless-const: true + x-oaiTypeLabel: string + default: dall-e-2 + example: gpt-image-1 + nullable: true + description: The model to use for image generation. Only `dall-e-2` and + `gpt-image-1` are supported. Defaults to `dall-e-2` unless a + parameter specific to `gpt-image-1` is used. + n: + type: integer + minimum: 1 + maximum: 10 + default: 1 + example: 1 + nullable: true + description: The number of images to generate. Must be between 1 and 10. + size: + type: string + enum: + - 256x256 + - 512x512 + - 1024x1024 + - 1536x1024 + - 1024x1536 + - auto + default: 1024x1024 + example: 1024x1024 + nullable: true + description: The size of the generated images. Must be one of `1024x1024`, + `1536x1024` (landscape), `1024x1536` (portrait), or `auto` (default + value) for `gpt-image-1`, and one of `256x256`, `512x512`, or + `1024x1024` for `dall-e-2`. + response_format: + type: string + enum: + - url + - b64_json + default: url + example: url + nullable: true + description: The format in which the generated images are returned. Must be one + of `url` or `b64_json`. URLs are only valid for 60 minutes after the + image has been generated. This parameter is only supported for + `dall-e-2`, as `gpt-image-1` will always return base64-encoded + images. + user: + type: string + example: user-1234 + description: > + A unique identifier representing your end-user, which can help + OpenAI to monitor and detect abuse. [Learn + more](/docs/guides/safety-best-practices#end-user-ids). + quality: + type: string + enum: + - standard + - low + - medium + - high + - auto + default: auto + example: high + nullable: true + description: > + The quality of the image that will be generated. `high`, `medium` + and `low` are only supported for `gpt-image-1`. `dall-e-2` only + supports `standard` quality. Defaults to `auto`. + required: + - prompt + - image + CreateImageRequest: + type: object + properties: + prompt: + description: A text description of the desired image(s). The maximum length is + 32000 characters for `gpt-image-1`, 1000 characters for `dall-e-2` + and 4000 characters for `dall-e-3`. + type: string + example: A cute baby sea otter + model: + anyOf: + - type: string + - type: string + enum: + - dall-e-2 + - dall-e-3 + - gpt-image-1 + x-oaiTypeLabel: string + default: dall-e-2 + example: gpt-image-1 + nullable: true + description: The model to use for image generation. One of `dall-e-2`, + `dall-e-3`, or `gpt-image-1`. Defaults to `dall-e-2` unless a + parameter specific to `gpt-image-1` is used. + n: + type: integer + minimum: 1 + maximum: 10 + default: 1 + example: 1 + nullable: true + description: The number of images to generate. Must be between 1 and 10. For + `dall-e-3`, only `n=1` is supported. + quality: + type: string + enum: + - standard + - hd + - low + - medium + - high + - auto + default: auto + example: medium + nullable: true + description: > + The quality of the image that will be generated. + + + - `auto` (default value) will automatically select the best quality + for the given model. + + - `high`, `medium` and `low` are supported for `gpt-image-1`. + + - `hd` and `standard` are supported for `dall-e-3`. + + - `standard` is the only option for `dall-e-2`. + response_format: + type: string + enum: + - url + - b64_json + default: url + example: url + nullable: true + description: The format in which generated images with `dall-e-2` and `dall-e-3` + are returned. Must be one of `url` or `b64_json`. URLs are only + valid for 60 minutes after the image has been generated. This + parameter isn't supported for `gpt-image-1` which will always return + base64-encoded images. + output_format: + type: string + enum: + - png + - jpeg + - webp + default: png + example: png + nullable: true + description: The format in which the generated images are returned. This + parameter is only supported for `gpt-image-1`. Must be one of `png`, + `jpeg`, or `webp`. + output_compression: + type: integer + default: 100 + example: 100 + nullable: true + description: The compression level (0-100%) for the generated images. This + parameter is only supported for `gpt-image-1` with the `webp` or + `jpeg` output formats, and defaults to 100. + size: + type: string + enum: + - auto + - 1024x1024 + - 1536x1024 + - 1024x1536 + - 256x256 + - 512x512 + - 1792x1024 + - 1024x1792 + default: auto + example: 1024x1024 + nullable: true + description: The size of the generated images. Must be one of `1024x1024`, + `1536x1024` (landscape), `1024x1536` (portrait), or `auto` (default + value) for `gpt-image-1`, one of `256x256`, `512x512`, or + `1024x1024` for `dall-e-2`, and one of `1024x1024`, `1792x1024`, or + `1024x1792` for `dall-e-3`. + moderation: + type: string + enum: + - low + - auto + default: auto + example: low + nullable: true + description: Control the content-moderation level for images generated by + `gpt-image-1`. Must be either `low` for less restrictive filtering + or `auto` (default value). + background: + type: string + enum: + - transparent + - opaque + - auto + default: auto + example: transparent + nullable: true + description: > + Allows to set transparency for the background of the generated + image(s). + + This parameter is only supported for `gpt-image-1`. Must be one of + + `transparent`, `opaque` or `auto` (default value). When `auto` is + used, the + + model will automatically determine the best background for the + image. + + + If `transparent`, the output format needs to support transparency, + so it + + should be set to either `png` (default value) or `webp`. + style: + type: string + enum: + - vivid + - natural + default: vivid + example: vivid + nullable: true + description: The style of the generated images. This parameter is only supported + for `dall-e-3`. Must be one of `vivid` or `natural`. Vivid causes + the model to lean towards generating hyper-real and dramatic images. + Natural causes the model to produce more natural, less hyper-real + looking images. + user: + type: string + example: user-1234 + description: > + A unique identifier representing your end-user, which can help + OpenAI to monitor and detect abuse. [Learn + more](/docs/guides/safety-best-practices#end-user-ids). + required: + - prompt + CreateImageVariationRequest: + type: object + properties: + image: + description: The image to use as the basis for the variation(s). Must be a valid + PNG file, less than 4MB, and square. + type: string + format: binary + model: + anyOf: + - type: string + - type: string + enum: + - dall-e-2 + x-stainless-const: true + x-oaiTypeLabel: string + default: dall-e-2 + example: dall-e-2 + nullable: true + description: The model to use for image generation. Only `dall-e-2` is supported + at this time. + n: + type: integer + minimum: 1 + maximum: 10 + default: 1 + example: 1 + nullable: true + description: The number of images to generate. Must be between 1 and 10. + response_format: + type: string + enum: + - url + - b64_json + default: url + example: url + nullable: true + description: The format in which the generated images are returned. Must be one + of `url` or `b64_json`. URLs are only valid for 60 minutes after the + image has been generated. + size: + type: string + enum: + - 256x256 + - 512x512 + - 1024x1024 + default: 1024x1024 + example: 1024x1024 + nullable: true + description: The size of the generated images. Must be one of `256x256`, + `512x512`, or `1024x1024`. + user: + type: string + example: user-1234 + description: > + A unique identifier representing your end-user, which can help + OpenAI to monitor and detect abuse. [Learn + more](/docs/guides/safety-best-practices#end-user-ids). + required: + - image + CreateMessageRequest: + type: object + additionalProperties: false + required: + - role + - content + properties: + role: + type: string + enum: + - user + - assistant + description: > + The role of the entity that is creating the message. Allowed values + include: + + - `user`: Indicates the message is sent by an actual user and should + be used in most cases to represent user-generated messages. + + - `assistant`: Indicates the message is generated by the assistant. + Use this value to insert messages from the assistant into the + conversation. + content: + oneOf: + - type: string + description: The text contents of the message. + title: Text content + - type: array + description: An array of content parts with a defined type, each can be of type + `text` or images can be passed with `image_url` or `image_file`. + Image types are only supported on [Vision-compatible + models](/docs/models). + title: Array of content parts + items: + oneOf: + - $ref: "#/components/schemas/MessageContentImageFileObject" + - $ref: "#/components/schemas/MessageContentImageUrlObject" + - $ref: "#/components/schemas/MessageRequestContentTextObject" + minItems: 1 + attachments: + type: array + items: + type: object + properties: + file_id: + type: string + description: The ID of the file to attach to the message. + tools: + description: The tools to add this file to. + type: array + items: + oneOf: + - $ref: "#/components/schemas/AssistantToolsCode" + - $ref: "#/components/schemas/AssistantToolsFileSearchTypeOnly" + description: A list of files attached to the message, and the tools they should + be added to. + required: + - file_id + - tools + nullable: true + metadata: + $ref: "#/components/schemas/Metadata" + CreateModelResponseProperties: + allOf: + - $ref: "#/components/schemas/ModelResponseProperties" + CreateModerationRequest: + type: object + properties: + input: + description: > + Input (or inputs) to classify. Can be a single string, an array of + strings, or + + an array of multi-modal input objects similar to other models. + oneOf: + - type: string + description: A string of text to classify for moderation. + default: "" + example: I want to kill them. + - type: array + description: An array of strings to classify for moderation. + items: + type: string + default: "" + example: I want to kill them. + - type: array + description: An array of multi-modal inputs to the moderation model. + items: + oneOf: + - type: object + description: An object describing an image to classify. + properties: + type: + description: Always `image_url`. + type: string + enum: + - image_url + x-stainless-const: true + image_url: + type: object + description: Contains either an image URL or a data URL for a base64 encoded + image. + properties: + url: + type: string + description: Either a URL of the image or the base64 encoded image data. + format: uri + example: https://example.com/image.jpg + required: + - url + required: + - type + - image_url + - type: object + description: An object describing text to classify. + properties: + type: + description: Always `text`. + type: string + enum: + - text + x-stainless-const: true + text: + description: A string of text to classify. + type: string + example: I want to kill them + required: + - type + - text + model: + description: | + The content moderation model you would like to use. Learn more in + [the moderation guide](/docs/guides/moderation), and learn about + available models [here](/docs/models#moderation). + nullable: false + default: omni-moderation-latest + example: omni-moderation-2024-09-26 + anyOf: + - type: string + - type: string + enum: + - omni-moderation-latest + - omni-moderation-2024-09-26 + - text-moderation-latest + - text-moderation-stable + x-oaiTypeLabel: string + required: + - input + CreateModerationResponse: + type: object + description: Represents if a given text input is potentially harmful. + properties: + id: + type: string + description: The unique identifier for the moderation request. + model: + type: string + description: The model used to generate the moderation results. + results: + type: array + description: A list of moderation objects. + items: + type: object + properties: + flagged: + type: boolean + description: Whether any of the below categories are flagged. + categories: + type: object + description: A list of the categories, and whether they are flagged or not. + properties: + hate: + type: boolean + description: Content that expresses, incites, or promotes hate based on race, + gender, ethnicity, religion, nationality, sexual + orientation, disability status, or caste. Hateful content + aimed at non-protected groups (e.g., chess players) is + harassment. + hate/threatening: + type: boolean + description: Hateful content that also includes violence or serious harm towards + the targeted group based on race, gender, ethnicity, + religion, nationality, sexual orientation, disability + status, or caste. + harassment: + type: boolean + description: Content that expresses, incites, or promotes harassing language + towards any target. + harassment/threatening: + type: boolean + description: Harassment content that also includes violence or serious harm + towards any target. + illicit: + type: boolean + nullable: true + description: Content that includes instructions or advice that facilitate the + planning or execution of wrongdoing, or that gives advice + or instruction on how to commit illicit acts. For example, + "how to shoplift" would fit this category. + illicit/violent: + type: boolean + nullable: true + description: Content that includes instructions or advice that facilitate the + planning or execution of wrongdoing that also includes + violence, or that gives advice or instruction on the + procurement of any weapon. + self-harm: + type: boolean + description: Content that promotes, encourages, or depicts acts of self-harm, + such as suicide, cutting, and eating disorders. + self-harm/intent: + type: boolean + description: Content where the speaker expresses that they are engaging or + intend to engage in acts of self-harm, such as suicide, + cutting, and eating disorders. + self-harm/instructions: + type: boolean + description: Content that encourages performing acts of self-harm, such as + suicide, cutting, and eating disorders, or that gives + instructions or advice on how to commit such acts. + sexual: + type: boolean + description: Content meant to arouse sexual excitement, such as the description + of sexual activity, or that promotes sexual services + (excluding sex education and wellness). + sexual/minors: + type: boolean + description: Sexual content that includes an individual who is under 18 years + old. + violence: + type: boolean + description: Content that depicts death, violence, or physical injury. + violence/graphic: + type: boolean + description: Content that depicts death, violence, or physical injury in graphic + detail. + required: + - hate + - hate/threatening + - harassment + - harassment/threatening + - illicit + - illicit/violent + - self-harm + - self-harm/intent + - self-harm/instructions + - sexual + - sexual/minors + - violence + - violence/graphic + category_scores: + type: object + description: A list of the categories along with their scores as predicted by + model. + properties: + hate: + type: number + description: The score for the category 'hate'. + hate/threatening: + type: number + description: The score for the category 'hate/threatening'. + harassment: + type: number + description: The score for the category 'harassment'. + harassment/threatening: + type: number + description: The score for the category 'harassment/threatening'. + illicit: + type: number + description: The score for the category 'illicit'. + illicit/violent: + type: number + description: The score for the category 'illicit/violent'. + self-harm: + type: number + description: The score for the category 'self-harm'. + self-harm/intent: + type: number + description: The score for the category 'self-harm/intent'. + self-harm/instructions: + type: number + description: The score for the category 'self-harm/instructions'. + sexual: + type: number + description: The score for the category 'sexual'. + sexual/minors: + type: number + description: The score for the category 'sexual/minors'. + violence: + type: number + description: The score for the category 'violence'. + violence/graphic: + type: number + description: The score for the category 'violence/graphic'. + required: + - hate + - hate/threatening + - harassment + - harassment/threatening + - illicit + - illicit/violent + - self-harm + - self-harm/intent + - self-harm/instructions + - sexual + - sexual/minors + - violence + - violence/graphic + category_applied_input_types: + type: object + description: A list of the categories along with the input type(s) that the + score applies to. + properties: + hate: + type: array + description: The applied input type(s) for the category 'hate'. + items: + type: string + enum: + - text + x-stainless-const: true + hate/threatening: + type: array + description: The applied input type(s) for the category 'hate/threatening'. + items: + type: string + enum: + - text + x-stainless-const: true + harassment: + type: array + description: The applied input type(s) for the category 'harassment'. + items: + type: string + enum: + - text + x-stainless-const: true + harassment/threatening: + type: array + description: The applied input type(s) for the category + 'harassment/threatening'. + items: + type: string + enum: + - text + x-stainless-const: true + illicit: + type: array + description: The applied input type(s) for the category 'illicit'. + items: + type: string + enum: + - text + x-stainless-const: true + illicit/violent: + type: array + description: The applied input type(s) for the category 'illicit/violent'. + items: + type: string + enum: + - text + x-stainless-const: true + self-harm: + type: array + description: The applied input type(s) for the category 'self-harm'. + items: + type: string + enum: + - text + - image + self-harm/intent: + type: array + description: The applied input type(s) for the category 'self-harm/intent'. + items: + type: string + enum: + - text + - image + self-harm/instructions: + type: array + description: The applied input type(s) for the category + 'self-harm/instructions'. + items: + type: string + enum: + - text + - image + sexual: + type: array + description: The applied input type(s) for the category 'sexual'. + items: + type: string + enum: + - text + - image + sexual/minors: + type: array + description: The applied input type(s) for the category 'sexual/minors'. + items: + type: string + enum: + - text + x-stainless-const: true + violence: + type: array + description: The applied input type(s) for the category 'violence'. + items: + type: string + enum: + - text + - image + violence/graphic: + type: array + description: The applied input type(s) for the category 'violence/graphic'. + items: + type: string + enum: + - text + - image + required: + - hate + - hate/threatening + - harassment + - harassment/threatening + - illicit + - illicit/violent + - self-harm + - self-harm/intent + - self-harm/instructions + - sexual + - sexual/minors + - violence + - violence/graphic + required: + - flagged + - categories + - category_scores + - category_applied_input_types + required: + - id + - model + - results + x-oaiMeta: + name: The moderation object + example: | + { + "id": "modr-0d9740456c391e43c445bf0f010940c7", + "model": "omni-moderation-latest", + "results": [ + { + "flagged": true, + "categories": { + "harassment": true, + "harassment/threatening": true, + "sexual": false, + "hate": false, + "hate/threatening": false, + "illicit": false, + "illicit/violent": false, + "self-harm/intent": false, + "self-harm/instructions": false, + "self-harm": false, + "sexual/minors": false, + "violence": true, + "violence/graphic": true + }, + "category_scores": { + "harassment": 0.8189693396524255, + "harassment/threatening": 0.804985420696006, + "sexual": 1.573112165348997e-6, + "hate": 0.007562942636942845, + "hate/threatening": 0.004208854591835476, + "illicit": 0.030535955153511665, + "illicit/violent": 0.008925306722380033, + "self-harm/intent": 0.00023023930975076432, + "self-harm/instructions": 0.0002293869201073356, + "self-harm": 0.012598046106750154, + "sexual/minors": 2.212566909570261e-8, + "violence": 0.9999992735124786, + "violence/graphic": 0.843064871157054 + }, + "category_applied_input_types": { + "harassment": [ + "text" + ], + "harassment/threatening": [ + "text" + ], + "sexual": [ + "text", + "image" + ], + "hate": [ + "text" + ], + "hate/threatening": [ + "text" + ], + "illicit": [ + "text" + ], + "illicit/violent": [ + "text" + ], + "self-harm/intent": [ + "text", + "image" + ], + "self-harm/instructions": [ + "text", + "image" + ], + "self-harm": [ + "text", + "image" + ], + "sexual/minors": [ + "text" + ], + "violence": [ + "text", + "image" + ], + "violence/graphic": [ + "text", + "image" + ] + } + } + ] + } + CreateResponse: + allOf: + - $ref: "#/components/schemas/CreateModelResponseProperties" + - $ref: "#/components/schemas/ResponseProperties" + - type: object + properties: + input: + description: > + Text, image, or file inputs to the model, used to generate a + response. + + + Learn more: + + - [Text inputs and outputs](/docs/guides/text) + + - [Image inputs](/docs/guides/images) + + - [File inputs](/docs/guides/pdf-files) + + - [Conversation state](/docs/guides/conversation-state) + + - [Function calling](/docs/guides/function-calling) + oneOf: + - type: string + title: Text input + description: > + A text input to the model, equivalent to a text input with + the + + `user` role. + - type: array + title: Input item list + description: | + A list of one or many input items to the model, containing + different content types. + items: + $ref: "#/components/schemas/InputItem" + include: + type: array + description: > + Specify additional output data to include in the model response. + Currently + + supported values are: + + - `file_search_call.results`: Include the search results of + the file search tool call. + - `message.input_image.image_url`: Include image urls from the + input message. + + - `computer_call_output.output.image_url`: Include image urls + from the computer call output. + items: + $ref: "#/components/schemas/Includable" + nullable: true + parallel_tool_calls: + type: boolean + description: | + Whether to allow the model to run tool calls in parallel. + default: true + nullable: true + store: + type: boolean + description: > + Whether to store the generated model response for later + retrieval via + + API. + default: true + nullable: true + stream: + description: | + If set to true, the model response data will be streamed to the client + as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). + See the [Streaming section below](/docs/api-reference/responses-streaming) + for more information. + type: boolean + nullable: true + default: false + required: + - model + - input + CreateRunRequest: + type: object + additionalProperties: false + properties: + assistant_id: + description: The ID of the [assistant](/docs/api-reference/assistants) to use to + execute this run. + type: string + model: + description: The ID of the [Model](/docs/api-reference/models) to be used to + execute this run. If a value is provided here, it will override the + model associated with the assistant. If not, the model associated + with the assistant will be used. + example: gpt-4o + anyOf: + - type: string + - $ref: "#/components/schemas/AssistantSupportedModels" + x-oaiTypeLabel: string + nullable: true + reasoning_effort: + $ref: "#/components/schemas/ReasoningEffort" + instructions: + description: Overrides the + [instructions](/docs/api-reference/assistants/createAssistant) of + the assistant. This is useful for modifying the behavior on a + per-run basis. + type: string + nullable: true + additional_instructions: + description: Appends additional instructions at the end of the instructions for + the run. This is useful for modifying the behavior on a per-run + basis without overriding other instructions. + type: string + nullable: true + additional_messages: + description: Adds additional messages to the thread before creating the run. + type: array + items: + $ref: "#/components/schemas/CreateMessageRequest" + nullable: true + tools: + description: Override the tools the assistant can use for this run. This is + useful for modifying the behavior on a per-run basis. + nullable: true + type: array + maxItems: 20 + items: + oneOf: + - $ref: "#/components/schemas/AssistantToolsCode" + - $ref: "#/components/schemas/AssistantToolsFileSearch" + - $ref: "#/components/schemas/AssistantToolsFunction" + metadata: + $ref: "#/components/schemas/Metadata" + temperature: + type: number + minimum: 0 + maximum: 2 + default: 1 + example: 1 + nullable: true + description: > + What sampling temperature to use, between 0 and 2. Higher values + like 0.8 will make the output more random, while lower values like + 0.2 will make it more focused and deterministic. + top_p: + type: number + minimum: 0 + maximum: 1 + default: 1 + example: 1 + nullable: true + description: > + An alternative to sampling with temperature, called nucleus + sampling, where the model considers the results of the tokens with + top_p probability mass. So 0.1 means only the tokens comprising the + top 10% probability mass are considered. + + + We generally recommend altering this or temperature but not both. + stream: + type: boolean + nullable: true + description: > + If `true`, returns a stream of events that happen during the Run as + server-sent events, terminating when the Run enters a terminal state + with a `data: [DONE]` message. + max_prompt_tokens: + type: integer + nullable: true + description: > + The maximum number of prompt tokens that may be used over the course + of the run. The run will make a best effort to use only the number + of prompt tokens specified, across multiple turns of the run. If the + run exceeds the number of prompt tokens specified, the run will end + with status `incomplete`. See `incomplete_details` for more info. + minimum: 256 + max_completion_tokens: + type: integer + nullable: true + description: > + The maximum number of completion tokens that may be used over the + course of the run. The run will make a best effort to use only the + number of completion tokens specified, across multiple turns of the + run. If the run exceeds the number of completion tokens specified, + the run will end with status `incomplete`. See `incomplete_details` + for more info. + minimum: 256 + truncation_strategy: + allOf: + - $ref: "#/components/schemas/TruncationObject" + - nullable: true + tool_choice: + allOf: + - $ref: "#/components/schemas/AssistantsApiToolChoiceOption" + - nullable: true + parallel_tool_calls: + $ref: "#/components/schemas/ParallelToolCalls" + response_format: + $ref: "#/components/schemas/AssistantsApiResponseFormatOption" + nullable: true + required: + - assistant_id + CreateSpeechRequest: + type: object + additionalProperties: false + properties: + model: + description: > + One of the available [TTS models](/docs/models#tts): `tts-1`, + `tts-1-hd` or `gpt-4o-mini-tts`. + anyOf: + - type: string + - type: string + enum: + - tts-1 + - tts-1-hd + - gpt-4o-mini-tts + x-oaiTypeLabel: string + input: + type: string + description: The text to generate audio for. The maximum length is 4096 + characters. + maxLength: 4096 + instructions: + type: string + description: Control the voice of your generated audio with additional + instructions. Does not work with `tts-1` or `tts-1-hd`. + maxLength: 4096 + voice: + description: The voice to use when generating the audio. Supported voices are + `alloy`, `ash`, `ballad`, `coral`, `echo`, `fable`, `onyx`, `nova`, + `sage`, `shimmer`, and `verse`. Previews of the voices are available + in the [Text to speech + guide](/docs/guides/text-to-speech#voice-options). + $ref: "#/components/schemas/VoiceIdsShared" + response_format: + description: The format to audio in. Supported formats are `mp3`, `opus`, `aac`, + `flac`, `wav`, and `pcm`. + default: mp3 + type: string + enum: + - mp3 + - opus + - aac + - flac + - wav + - pcm + speed: + description: The speed of the generated audio. Select a value from `0.25` to + `4.0`. `1.0` is the default. + type: number + default: 1 + minimum: 0.25 + maximum: 4 + required: + - model + - input + - voice + CreateThreadAndRunRequest: + type: object + additionalProperties: false + properties: + assistant_id: + description: The ID of the [assistant](/docs/api-reference/assistants) to use to + execute this run. + type: string + thread: + $ref: "#/components/schemas/CreateThreadRequest" + model: + description: The ID of the [Model](/docs/api-reference/models) to be used to + execute this run. If a value is provided here, it will override the + model associated with the assistant. If not, the model associated + with the assistant will be used. + example: gpt-4o + anyOf: + - type: string + - type: string + enum: + - gpt-4.1 + - gpt-4.1-mini + - gpt-4.1-nano + - gpt-4.1-2025-04-14 + - gpt-4.1-mini-2025-04-14 + - gpt-4.1-nano-2025-04-14 + - gpt-4o + - gpt-4o-2024-11-20 + - gpt-4o-2024-08-06 + - gpt-4o-2024-05-13 + - gpt-4o-mini + - gpt-4o-mini-2024-07-18 + - gpt-4.5-preview + - gpt-4.5-preview-2025-02-27 + - gpt-4-turbo + - gpt-4-turbo-2024-04-09 + - gpt-4-0125-preview + - gpt-4-turbo-preview + - gpt-4-1106-preview + - gpt-4-vision-preview + - gpt-4 + - gpt-4-0314 + - gpt-4-0613 + - gpt-4-32k + - gpt-4-32k-0314 + - gpt-4-32k-0613 + - gpt-3.5-turbo + - gpt-3.5-turbo-16k + - gpt-3.5-turbo-0613 + - gpt-3.5-turbo-1106 + - gpt-3.5-turbo-0125 + - gpt-3.5-turbo-16k-0613 + x-oaiTypeLabel: string + nullable: true + instructions: + description: Override the default system message of the assistant. This is + useful for modifying the behavior on a per-run basis. + type: string + nullable: true + tools: + description: Override the tools the assistant can use for this run. This is + useful for modifying the behavior on a per-run basis. + nullable: true + type: array + maxItems: 20 + items: + oneOf: + - $ref: "#/components/schemas/AssistantToolsCode" + - $ref: "#/components/schemas/AssistantToolsFileSearch" + - $ref: "#/components/schemas/AssistantToolsFunction" + tool_resources: + type: object + description: > + A set of resources that are used by the assistant's tools. The + resources are specific to the type of tool. For example, the + `code_interpreter` tool requires a list of file IDs, while the + `file_search` tool requires a list of vector store IDs. + properties: + code_interpreter: + type: object + properties: + file_ids: + type: array + description: > + A list of [file](/docs/api-reference/files) IDs made + available to the `code_interpreter` tool. There can be a + maximum of 20 files associated with the tool. + default: [] + maxItems: 20 + items: + type: string + file_search: + type: object + properties: + vector_store_ids: + type: array + description: > + The ID of the [vector + store](/docs/api-reference/vector-stores/object) attached to + this assistant. There can be a maximum of 1 vector store + attached to the assistant. + maxItems: 1 + items: + type: string + nullable: true + metadata: + $ref: "#/components/schemas/Metadata" + temperature: + type: number + minimum: 0 + maximum: 2 + default: 1 + example: 1 + nullable: true + description: > + What sampling temperature to use, between 0 and 2. Higher values + like 0.8 will make the output more random, while lower values like + 0.2 will make it more focused and deterministic. + top_p: + type: number + minimum: 0 + maximum: 1 + default: 1 + example: 1 + nullable: true + description: > + An alternative to sampling with temperature, called nucleus + sampling, where the model considers the results of the tokens with + top_p probability mass. So 0.1 means only the tokens comprising the + top 10% probability mass are considered. + + + We generally recommend altering this or temperature but not both. + stream: + type: boolean + nullable: true + description: > + If `true`, returns a stream of events that happen during the Run as + server-sent events, terminating when the Run enters a terminal state + with a `data: [DONE]` message. + max_prompt_tokens: + type: integer + nullable: true + description: > + The maximum number of prompt tokens that may be used over the course + of the run. The run will make a best effort to use only the number + of prompt tokens specified, across multiple turns of the run. If the + run exceeds the number of prompt tokens specified, the run will end + with status `incomplete`. See `incomplete_details` for more info. + minimum: 256 + max_completion_tokens: + type: integer + nullable: true + description: > + The maximum number of completion tokens that may be used over the + course of the run. The run will make a best effort to use only the + number of completion tokens specified, across multiple turns of the + run. If the run exceeds the number of completion tokens specified, + the run will end with status `incomplete`. See `incomplete_details` + for more info. + minimum: 256 + truncation_strategy: + allOf: + - $ref: "#/components/schemas/TruncationObject" + - nullable: true + tool_choice: + allOf: + - $ref: "#/components/schemas/AssistantsApiToolChoiceOption" + - nullable: true + parallel_tool_calls: + $ref: "#/components/schemas/ParallelToolCalls" + response_format: + $ref: "#/components/schemas/AssistantsApiResponseFormatOption" + nullable: true + required: + - assistant_id + CreateThreadRequest: + type: object + description: | + Options to create a new thread. If no thread is provided when running a + request, an empty thread will be created. + additionalProperties: false + properties: + messages: + description: A list of [messages](/docs/api-reference/messages) to start the + thread with. + type: array + items: + $ref: "#/components/schemas/CreateMessageRequest" + tool_resources: + type: object + description: > + A set of resources that are made available to the assistant's tools + in this thread. The resources are specific to the type of tool. For + example, the `code_interpreter` tool requires a list of file IDs, + while the `file_search` tool requires a list of vector store IDs. + properties: + code_interpreter: + type: object + properties: + file_ids: + type: array + description: > + A list of [file](/docs/api-reference/files) IDs made + available to the `code_interpreter` tool. There can be a + maximum of 20 files associated with the tool. + default: [] + maxItems: 20 + items: + type: string + file_search: + type: object + properties: + vector_store_ids: + type: array + description: > + The [vector store](/docs/api-reference/vector-stores/object) + attached to this thread. There can be a maximum of 1 vector + store attached to the thread. + maxItems: 1 + items: + type: string + vector_stores: + type: array + description: > + A helper to create a [vector + store](/docs/api-reference/vector-stores/object) with + file_ids and attach it to this thread. There can be a + maximum of 1 vector store attached to the thread. + maxItems: 1 + items: + type: object + properties: + file_ids: + type: array + description: > + A list of [file](/docs/api-reference/files) IDs to add + to the vector store. There can be a maximum of 10000 + files in a vector store. + maxItems: 10000 + items: + type: string + chunking_strategy: + type: object + description: The chunking strategy used to chunk the file(s). If not set, will + use the `auto` strategy. + oneOf: + - type: object + title: Auto Chunking Strategy + description: The default strategy. This strategy currently uses a + `max_chunk_size_tokens` of `800` and + `chunk_overlap_tokens` of `400`. + additionalProperties: false + properties: + type: + type: string + description: Always `auto`. + enum: + - auto + x-stainless-const: true + required: + - type + - type: object + title: Static Chunking Strategy + additionalProperties: false + properties: + type: + type: string + description: Always `static`. + enum: + - static + x-stainless-const: true + static: + type: object + additionalProperties: false + properties: + max_chunk_size_tokens: + type: integer + minimum: 100 + maximum: 4096 + description: The maximum number of tokens in each chunk. The default value is + `800`. The minimum value is `100` and the + maximum value is `4096`. + chunk_overlap_tokens: + type: integer + description: > + The number of tokens that overlap between + chunks. The default value is `400`. + + + Note that the overlap must not exceed half + of `max_chunk_size_tokens`. + required: + - max_chunk_size_tokens + - chunk_overlap_tokens + required: + - type + - static + metadata: + $ref: "#/components/schemas/Metadata" + oneOf: + - required: + - vector_store_ids + - required: + - vector_stores + nullable: true + metadata: + $ref: "#/components/schemas/Metadata" + CreateTranscriptionRequest: + type: object + additionalProperties: false + properties: + file: + description: > + The audio file object (not file name) to transcribe, in one of these + formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm. + type: string + x-oaiTypeLabel: file + format: binary + model: + description: > + ID of the model to use. The options are `gpt-4o-transcribe`, + `gpt-4o-mini-transcribe`, and `whisper-1` (which is powered by our + open source Whisper V2 model). + example: gpt-4o-transcribe + anyOf: + - type: string + - type: string + enum: + - whisper-1 + - gpt-4o-transcribe + - gpt-4o-mini-transcribe + x-stainless-const: true + x-oaiTypeLabel: string + language: + description: > + The language of the input audio. Supplying the input language in + [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) + (e.g. `en`) format will improve accuracy and latency. + type: string + prompt: + description: > + An optional text to guide the model's style or continue a previous + audio segment. The [prompt](/docs/guides/speech-to-text#prompting) + should match the audio language. + type: string + response_format: + $ref: "#/components/schemas/AudioResponseFormat" + temperature: + description: > + The sampling temperature, between 0 and 1. Higher values like 0.8 + will make the output more random, while lower values like 0.2 will + make it more focused and deterministic. If set to 0, the model will + use [log probability](https://en.wikipedia.org/wiki/Log_probability) + to automatically increase the temperature until certain thresholds + are hit. + type: number + default: 0 + include[]: + description: > + Additional information to include in the transcription response. + + `logprobs` will return the log probabilities of the tokens in the + + response to understand the model's confidence in the transcription. + + `logprobs` only works with response_format set to `json` and only + with + + the models `gpt-4o-transcribe` and `gpt-4o-mini-transcribe`. + type: array + items: + $ref: "#/components/schemas/TranscriptionInclude" + timestamp_granularities[]: + description: > + The timestamp granularities to populate for this transcription. + `response_format` must be set `verbose_json` to use timestamp + granularities. Either or both of these options are supported: + `word`, or `segment`. Note: There is no additional latency for + segment timestamps, but generating word timestamps incurs additional + latency. + type: array + items: + type: string + enum: + - word + - segment + default: + - segment + stream: + description: | + If set to true, the model response data will be streamed to the client + as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). + See the [Streaming section of the Speech-to-Text guide](/docs/guides/speech-to-text?lang=curl#streaming-transcriptions) + for more information. + + Note: Streaming is not supported for the `whisper-1` model and will be ignored. + type: boolean + nullable: true + default: false + required: + - file + - model + CreateTranscriptionResponseJson: + type: object + description: Represents a transcription response returned by model, based on the + provided input. + properties: + text: + type: string + description: The transcribed text. + logprobs: + type: array + optional: true + description: > + The log probabilities of the tokens in the transcription. Only + returned with the models `gpt-4o-transcribe` and + `gpt-4o-mini-transcribe` if `logprobs` is added to the `include` + array. + items: + type: object + properties: + token: + type: string + description: The token in the transcription. + logprob: + type: number + description: The log probability of the token. + bytes: + type: array + items: + type: number + description: The bytes of the token. + required: + - text + x-oaiMeta: + name: The transcription object (JSON) + group: audio + example: > + { + "text": "Imagine the wildest idea that you've ever had, and you're curious about how it might scale to something that's a 100, a 1,000 times bigger. This is a place where you can get to do that." + } + CreateTranscriptionResponseStreamEvent: + anyOf: + - $ref: "#/components/schemas/TranscriptTextDeltaEvent" + - $ref: "#/components/schemas/TranscriptTextDoneEvent" + discriminator: + propertyName: type + CreateTranscriptionResponseVerboseJson: + type: object + description: Represents a verbose json transcription response returned by model, + based on the provided input. + properties: + language: + type: string + description: The language of the input audio. + duration: + type: number + description: The duration of the input audio. + text: + type: string + description: The transcribed text. + words: + type: array + description: Extracted words and their corresponding timestamps. + items: + $ref: "#/components/schemas/TranscriptionWord" + segments: + type: array + description: Segments of the transcribed text and their corresponding details. + items: + $ref: "#/components/schemas/TranscriptionSegment" + required: + - language + - duration + - text + x-oaiMeta: + name: The transcription object (Verbose JSON) + group: audio + example: > + { + "task": "transcribe", + "language": "english", + "duration": 8.470000267028809, + "text": "The beach was a popular spot on a hot summer day. People were swimming in the ocean, building sandcastles, and playing beach volleyball.", + "segments": [ + { + "id": 0, + "seek": 0, + "start": 0.0, + "end": 3.319999933242798, + "text": " The beach was a popular spot on a hot summer day.", + "tokens": [ + 50364, 440, 7534, 390, 257, 3743, 4008, 322, 257, 2368, 4266, 786, 13, 50530 + ], + "temperature": 0.0, + "avg_logprob": -0.2860786020755768, + "compression_ratio": 1.2363636493682861, + "no_speech_prob": 0.00985979475080967 + }, + ... + ] + } + CreateTranslationRequest: + type: object + additionalProperties: false + properties: + file: + description: > + The audio file object (not file name) translate, in one of these + formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm. + type: string + x-oaiTypeLabel: file + format: binary + model: + description: > + ID of the model to use. Only `whisper-1` (which is powered by our + open source Whisper V2 model) is currently available. + example: whisper-1 + anyOf: + - type: string + - type: string + enum: + - whisper-1 + x-stainless-const: true + x-oaiTypeLabel: string + prompt: + description: > + An optional text to guide the model's style or continue a previous + audio segment. The [prompt](/docs/guides/speech-to-text#prompting) + should be in English. + type: string + response_format: + description: > + The format of the output, in one of these options: `json`, `text`, + `srt`, `verbose_json`, or `vtt`. + type: string + enum: + - json + - text + - srt + - verbose_json + - vtt + default: json + temperature: + description: > + The sampling temperature, between 0 and 1. Higher values like 0.8 + will make the output more random, while lower values like 0.2 will + make it more focused and deterministic. If set to 0, the model will + use [log probability](https://en.wikipedia.org/wiki/Log_probability) + to automatically increase the temperature until certain thresholds + are hit. + type: number + default: 0 + required: + - file + - model + CreateTranslationResponseJson: + type: object + properties: + text: + type: string + required: + - text + CreateTranslationResponseVerboseJson: + type: object + properties: + language: + type: string + description: The language of the output translation (always `english`). + duration: + type: number + description: The duration of the input audio. + text: + type: string + description: The translated text. + segments: + type: array + description: Segments of the translated text and their corresponding details. + items: + $ref: "#/components/schemas/TranscriptionSegment" + required: + - language + - duration + - text + CreateUploadRequest: + type: object + additionalProperties: false + properties: + filename: + description: | + The name of the file to upload. + type: string + purpose: + description: > + The intended purpose of the uploaded file. + + + See the [documentation on File + purposes](/docs/api-reference/files/create#files-create-purpose). + type: string + enum: + - assistants + - batch + - fine-tune + - vision + bytes: + description: | + The number of bytes in the file you are uploading. + type: integer + mime_type: + description: > + The MIME type of the file. + + + This must fall within the supported MIME types for your file + purpose. See the supported MIME types for assistants and vision. + type: string + required: + - filename + - purpose + - bytes + - mime_type + CreateVectorStoreFileBatchRequest: + type: object + additionalProperties: false + properties: + file_ids: + description: A list of [File](/docs/api-reference/files) IDs that the vector + store should use. Useful for tools like `file_search` that can + access files. + type: array + minItems: 1 + maxItems: 500 + items: + type: string + chunking_strategy: + $ref: "#/components/schemas/ChunkingStrategyRequestParam" + attributes: + $ref: "#/components/schemas/VectorStoreFileAttributes" + required: + - file_ids + CreateVectorStoreFileRequest: + type: object + additionalProperties: false + properties: + file_id: + description: A [File](/docs/api-reference/files) ID that the vector store should + use. Useful for tools like `file_search` that can access files. + type: string + chunking_strategy: + $ref: "#/components/schemas/ChunkingStrategyRequestParam" + attributes: + $ref: "#/components/schemas/VectorStoreFileAttributes" + required: + - file_id + CreateVectorStoreRequest: + type: object + additionalProperties: false + properties: + file_ids: + description: A list of [File](/docs/api-reference/files) IDs that the vector + store should use. Useful for tools like `file_search` that can + access files. + type: array + maxItems: 500 + items: + type: string + name: + description: The name of the vector store. + type: string + expires_after: + $ref: "#/components/schemas/VectorStoreExpirationAfter" + chunking_strategy: + type: object + description: The chunking strategy used to chunk the file(s). If not set, will + use the `auto` strategy. Only applicable if `file_ids` is non-empty. + oneOf: + - $ref: "#/components/schemas/AutoChunkingStrategyRequestParam" + - $ref: "#/components/schemas/StaticChunkingStrategyRequestParam" + metadata: + $ref: "#/components/schemas/Metadata" + DeleteAssistantResponse: + type: object + properties: + id: + type: string + deleted: + type: boolean + object: + type: string + enum: + - assistant.deleted + x-stainless-const: true + required: + - id + - object + - deleted + DeleteCertificateResponse: + type: object + properties: + object: + type: string + description: The object type, must be `certificate.deleted`. + enum: + - certificate.deleted + x-stainless-const: true + id: + type: string + description: The ID of the certificate that was deleted. + required: + - object + - id + DeleteFileResponse: + type: object + properties: + id: + type: string + object: + type: string + enum: + - file + x-stainless-const: true + deleted: + type: boolean + required: + - id + - object + - deleted + DeleteFineTuningCheckpointPermissionResponse: + type: object + properties: + id: + type: string + description: The ID of the fine-tuned model checkpoint permission that was + deleted. + object: + type: string + description: The object type, which is always "checkpoint.permission". + enum: + - checkpoint.permission + x-stainless-const: true + deleted: + type: boolean + description: Whether the fine-tuned model checkpoint permission was successfully + deleted. + required: + - id + - object + - deleted + DeleteMessageResponse: + type: object + properties: + id: + type: string + deleted: + type: boolean + object: + type: string + enum: + - thread.message.deleted + x-stainless-const: true + required: + - id + - object + - deleted + DeleteModelResponse: + type: object + properties: + id: + type: string + deleted: + type: boolean + object: + type: string + required: + - id + - object + - deleted + DeleteThreadResponse: + type: object + properties: + id: + type: string + deleted: + type: boolean + object: + type: string + enum: + - thread.deleted + x-stainless-const: true + required: + - id + - object + - deleted + DeleteVectorStoreFileResponse: + type: object + properties: + id: + type: string + deleted: + type: boolean + object: + type: string + enum: + - vector_store.file.deleted + x-stainless-const: true + required: + - id + - object + - deleted + DeleteVectorStoreResponse: + type: object + properties: + id: + type: string + deleted: + type: boolean + object: + type: string + enum: + - vector_store.deleted + x-stainless-const: true + required: + - id + - object + - deleted + DoneEvent: + type: object + properties: + event: + type: string + enum: + - done + x-stainless-const: true + data: + type: string + enum: + - "[DONE]" + x-stainless-const: true + required: + - event + - data + description: Occurs when a stream ends. + x-oaiMeta: + dataDescription: "`data` is `[DONE]`" + DoubleClick: + type: object + title: DoubleClick + description: | + A double click action. + properties: + type: + type: string + enum: + - double_click + default: double_click + description: > + Specifies the event type. For a double click action, this property + is + + always set to `double_click`. + x-stainless-const: true + x: + type: integer + description: | + The x-coordinate where the double click occurred. + y: + type: integer + description: | + The y-coordinate where the double click occurred. + required: + - type + - x + - y + Drag: + type: object + title: Drag + description: | + A drag action. + properties: + type: + type: string + enum: + - drag + default: drag + description: | + Specifies the event type. For a drag action, this property is + always set to `drag`. + x-stainless-const: true + path: + type: array + description: > + An array of coordinates representing the path of the drag action. + Coordinates will appear as an array + + of objects, eg + + ``` + + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + + ``` + items: + title: Drag path coordinates + description: | + A series of x/y coordinate pairs in the drag path. + $ref: "#/components/schemas/Coordinate" + required: + - type + - path + EasyInputMessage: + type: object + title: Input message + description: > + A message input to the model with a role indicating instruction + following + + hierarchy. Instructions given with the `developer` or `system` role take + + precedence over instructions given with the `user` role. Messages with + the + + `assistant` role are presumed to have been generated by the model in + previous + + interactions. + properties: + role: + type: string + description: > + The role of the message input. One of `user`, `assistant`, `system`, + or + + `developer`. + enum: + - user + - assistant + - system + - developer + content: + description: > + Text, image, or audio input to the model, used to generate a + response. + + Can also contain previous assistant responses. + oneOf: + - type: string + title: Text input + description: | + A text input to the model. + - $ref: "#/components/schemas/InputMessageContentList" + type: + type: string + description: | + The type of the message input. Always `message`. + enum: + - message + x-stainless-const: true + required: + - role + - content + Embedding: + type: object + description: | + Represents an embedding vector returned by embedding endpoint. + properties: + index: + type: integer + description: The index of the embedding in the list of embeddings. + embedding: + type: array + description: > + The embedding vector, which is a list of floats. The length of + vector depends on the model as listed in the [embedding + guide](/docs/guides/embeddings). + items: + type: number + object: + type: string + description: The object type, which is always "embedding". + enum: + - embedding + x-stainless-const: true + required: + - index + - object + - embedding + x-oaiMeta: + name: The embedding object + example: | + { + "object": "embedding", + "embedding": [ + 0.0023064255, + -0.009327292, + .... (1536 floats total for ada-002) + -0.0028842222, + ], + "index": 0 + } + Error: + type: object + properties: + code: + type: string + nullable: true + message: + type: string + nullable: false + param: + type: string + nullable: true + type: + type: string + nullable: false + required: + - type + - message + - param + - code + ErrorEvent: + type: object + properties: + event: + type: string + enum: + - error + x-stainless-const: true + data: + $ref: "#/components/schemas/Error" + required: + - event + - data + description: Occurs when an [error](/docs/guides/error-codes#api-errors) occurs. + This can happen due to an internal server error or a timeout. + x-oaiMeta: + dataDescription: "`data` is an [error](/docs/guides/error-codes#api-errors)" + ErrorResponse: + type: object + properties: + error: + $ref: "#/components/schemas/Error" + required: + - error + Eval: + type: object + title: Eval + description: | + An Eval object with a data source config and testing criteria. + An Eval represents a task to be done for your LLM integration. + Like: + - Improve the quality of my chatbot + - See how well my chatbot handles customer support + - Check if o3-mini is better at my usecase than gpt-4o + properties: + object: + type: string + enum: + - eval + default: eval + description: The object type. + x-stainless-const: true + id: + type: string + description: Unique identifier for the evaluation. + name: + type: string + description: The name of the evaluation. + example: Chatbot effectiveness Evaluation + data_source_config: + type: object + description: Configuration of data sources used in runs of the evaluation. + oneOf: + - $ref: "#/components/schemas/EvalCustomDataSourceConfig" + - $ref: "#/components/schemas/EvalStoredCompletionsDataSourceConfig" + testing_criteria: + default: eval + description: A list of testing criteria. + type: array + items: + oneOf: + - $ref: "#/components/schemas/EvalLabelModelGrader" + - $ref: "#/components/schemas/EvalStringCheckGrader" + - $ref: "#/components/schemas/EvalTextSimilarityGrader" + - $ref: "#/components/schemas/EvalPythonGrader" + - $ref: "#/components/schemas/EvalScoreModelGrader" + created_at: + type: integer + description: The Unix timestamp (in seconds) for when the eval was created. + metadata: + $ref: "#/components/schemas/Metadata" + required: + - id + - data_source_config + - object + - testing_criteria + - name + - created_at + - metadata + x-oaiMeta: + name: The eval object + group: evals + example: | + { + "object": "eval", + "id": "eval_67abd54d9b0081909a86353f6fb9317a", + "data_source_config": { + "type": "custom", + "item_schema": { + "type": "object", + "properties": { + "label": {"type": "string"}, + }, + "required": ["label"] + }, + "include_sample_schema": true + }, + "testing_criteria": [ + { + "name": "My string check grader", + "type": "string_check", + "input": "{{sample.output_text}}", + "reference": "{{item.label}}", + "operation": "eq", + } + ], + "name": "External Data Eval", + "created_at": 1739314509, + "metadata": { + "test": "synthetics", + } + } + EvalApiError: + type: object + title: EvalApiError + description: | + An object representing an error response from the Eval API. + properties: + code: + type: string + description: The error code. + message: + type: string + description: The error message. + required: + - code + - message + x-oaiMeta: + name: The API error object + group: evals + example: | + { + "code": "internal_error", + "message": "The eval run failed due to an internal error." + } + EvalCustomDataSourceConfig: + type: object + title: CustomDataSourceConfig + description: > + A CustomDataSourceConfig which specifies the schema of your `item` and + optionally `sample` namespaces. + + The response schema defines the shape of the data that will be: + + - Used to define your testing criteria and + + - What data is required when creating a run + properties: + type: + type: string + enum: + - custom + default: custom + description: The type of data source. Always `custom`. + x-stainless-const: true + schema: + type: object + description: | + The json schema for the run data source items. + Learn how to build JSON schemas [here](https://json-schema.org/). + additionalProperties: true + example: | + { + "type": "object", + "properties": { + "item": { + "type": "object", + "properties": { + "label": {"type": "string"}, + }, + "required": ["label"] + } + }, + "required": ["item"] + } + required: + - type + - schema + x-oaiMeta: + name: The eval custom data source config object + group: evals + example: | + { + "type": "custom", + "schema": { + "type": "object", + "properties": { + "item": { + "type": "object", + "properties": { + "label": {"type": "string"}, + }, + "required": ["label"] + } + }, + "required": ["item"] + } + } + EvalItem: + type: object + title: Eval message object + description: > + A message input to the model with a role indicating instruction + following + + hierarchy. Instructions given with the `developer` or `system` role take + + precedence over instructions given with the `user` role. Messages with + the + + `assistant` role are presumed to have been generated by the model in + previous + + interactions. + properties: + role: + type: string + description: > + The role of the message input. One of `user`, `assistant`, `system`, + or + + `developer`. + enum: + - user + - assistant + - system + - developer + content: + description: | + Text inputs to the model - can contain template strings. + oneOf: + - type: string + title: Text input + description: | + A text input to the model. + - $ref: "#/components/schemas/InputTextContent" + - type: object + title: Output text + description: | + A text output from the model. + properties: + type: + type: string + description: | + The type of the output text. Always `output_text`. + enum: + - output_text + x-stainless-const: true + text: + type: string + description: | + The text output from the model. + required: + - type + - text + type: + type: string + description: | + The type of the message input. Always `message`. + enum: + - message + x-stainless-const: true + required: + - role + - content + EvalJsonlFileContentSource: + type: object + title: EvalJsonlFileContentSource + properties: + type: + type: string + enum: + - file_content + default: file_content + description: The type of jsonl source. Always `file_content`. + x-stainless-const: true + content: + type: array + items: + type: object + properties: + item: + type: object + additionalProperties: true + sample: + type: object + additionalProperties: true + required: + - item + description: The content of the jsonl file. + required: + - type + - content + EvalJsonlFileIdSource: + type: object + title: EvalJsonlFileIdSource + properties: + type: + type: string + enum: + - file_id + default: file_id + description: The type of jsonl source. Always `file_id`. + x-stainless-const: true + id: + type: string + description: The identifier of the file. + required: + - type + - id + EvalLabelModelGrader: + type: object + title: LabelModelGrader + description: > + A LabelModelGrader object which uses a model to assign labels to each + item + + in the evaluation. + properties: + type: + description: The object type, which is always `label_model`. + type: string + enum: + - label_model + x-stainless-const: true + name: + type: string + description: The name of the grader. + model: + type: string + description: The model to use for the evaluation. Must support structured outputs. + input: + type: array + items: + $ref: "#/components/schemas/EvalItem" + labels: + type: array + items: + type: string + description: The labels to assign to each item in the evaluation. + passing_labels: + type: array + items: + type: string + description: The labels that indicate a passing result. Must be a subset of + labels. + required: + - type + - model + - input + - passing_labels + - labels + - name + x-oaiMeta: + name: The eval label model grader object + group: evals + example: > + { + "name": "First label grader", + "type": "label_model", + "model": "gpt-4o-2024-08-06", + "input": [ + { + "type": "message", + "role": "system", + "content": { + "type": "input_text", + "text": "Classify the sentiment of the following statement as one of positive, neutral, or negative" + } + }, + { + "type": "message", + "role": "user", + "content": { + "type": "input_text", + "text": "Statement: {{item.response}}" + } + } + ], + "passing_labels": [ + "positive" + ], + "labels": [ + "positive", + "neutral", + "negative" + ] + } + EvalList: + type: object + title: EvalList + description: | + An object representing a list of evals. + properties: + object: + type: string + enum: + - list + default: list + description: | + The type of this object. It is always set to "list". + x-stainless-const: true + data: + type: array + description: | + An array of eval objects. + items: + $ref: "#/components/schemas/Eval" + first_id: + type: string + description: The identifier of the first eval in the data array. + last_id: + type: string + description: The identifier of the last eval in the data array. + has_more: + type: boolean + description: Indicates whether there are more evals available. + required: + - object + - data + - first_id + - last_id + - has_more + x-oaiMeta: + name: The eval list object + group: evals + example: | + { + "object": "list", + "data": [ + { + "object": "eval", + "id": "eval_67abd54d9b0081909a86353f6fb9317a", + "data_source_config": { + "type": "custom", + "schema": { + "type": "object", + "properties": { + "item": { + "type": "object", + "properties": { + "input": { + "type": "string" + }, + "ground_truth": { + "type": "string" + } + }, + "required": [ + "input", + "ground_truth" + ] + } + }, + "required": [ + "item" + ] + } + }, + "testing_criteria": [ + { + "name": "String check", + "id": "String check-2eaf2d8d-d649-4335-8148-9535a7ca73c2", + "type": "string_check", + "input": "{{item.input}}", + "reference": "{{item.ground_truth}}", + "operation": "eq" + } + ], + "name": "External Data Eval", + "created_at": 1739314509, + "metadata": {}, + } + ], + "first_id": "eval_67abd54d9b0081909a86353f6fb9317a", + "last_id": "eval_67abd54d9b0081909a86353f6fb9317a", + "has_more": true + } + EvalPythonGrader: + type: object + title: PythonGrader + description: | + A PythonGrader object that runs a python script on the input. + properties: + type: + type: string + enum: + - python + description: The object type, which is always `python`. + x-stainless-const: true + name: + type: string + description: The name of the grader. + source: + type: string + description: The source code of the python script. + pass_threshold: + type: number + description: The threshold for the score. + image_tag: + type: string + description: The image tag to use for the python script. + required: + - type + - name + - source + x-oaiMeta: + name: The eval python grader object + group: evals + example: | + { + "type": "string_check", + "name": "Example string check grader", + "input": "{{sample.output_text}}", + "reference": "{{item.label}}", + "operation": "eq" + } + EvalResponsesSource: + type: object + title: EvalResponsesSource + description: | + A EvalResponsesSource object describing a run data source configuration. + properties: + type: + type: string + enum: + - responses + description: The type of run data source. Always `responses`. + metadata: + type: object + nullable: true + description: Metadata filter for the responses. This is a query parameter used + to select responses. + model: + type: string + nullable: true + description: The name of the model to find responses for. This is a query + parameter used to select responses. + instructions_search: + type: string + nullable: true + description: Optional search string for instructions. This is a query parameter + used to select responses. + created_after: + type: integer + minimum: 0 + nullable: true + description: Only include items created after this timestamp (inclusive). This + is a query parameter used to select responses. + created_before: + type: integer + minimum: 0 + nullable: true + description: Only include items created before this timestamp (inclusive). This + is a query parameter used to select responses. + has_tool_calls: + type: boolean + nullable: true + description: Whether the response has tool calls. This is a query parameter used + to select responses. + reasoning_effort: + $ref: "#/components/schemas/ReasoningEffort" + nullable: true + description: Optional reasoning effort parameter. This is a query parameter used + to select responses. + temperature: + type: number + nullable: true + description: Sampling temperature. This is a query parameter used to select + responses. + top_p: + type: number + nullable: true + description: Nucleus sampling parameter. This is a query parameter used to + select responses. + users: + type: array + items: + type: string + nullable: true + description: List of user identifiers. This is a query parameter used to select + responses. + allow_parallel_tool_calls: + type: boolean + nullable: true + description: Whether to allow parallel tool calls. This is a query parameter + used to select responses. + required: + - type + x-oaiMeta: + name: The run data source object used to configure an individual run + group: eval runs + example: | + { + "type": "responses", + "model": "gpt-4o-mini-2024-07-18", + "temperature": 0.7, + "top_p": 1.0, + "users": ["user1", "user2"], + "allow_parallel_tool_calls": true + } + EvalRun: + type: object + title: EvalRun + description: | + A schema representing an evaluation run. + properties: + object: + type: string + enum: + - eval.run + default: eval.run + description: The type of the object. Always "eval.run". + x-stainless-const: true + id: + type: string + description: Unique identifier for the evaluation run. + eval_id: + type: string + description: The identifier of the associated evaluation. + status: + type: string + description: The status of the evaluation run. + model: + type: string + description: The model that is evaluated, if applicable. + name: + type: string + description: The name of the evaluation run. + created_at: + type: integer + description: Unix timestamp (in seconds) when the evaluation run was created. + report_url: + type: string + description: The URL to the rendered evaluation run report on the UI dashboard. + result_counts: + type: object + description: Counters summarizing the outcomes of the evaluation run. + properties: + total: + type: integer + description: Total number of executed output items. + errored: + type: integer + description: Number of output items that resulted in an error. + failed: + type: integer + description: Number of output items that failed to pass the evaluation. + passed: + type: integer + description: Number of output items that passed the evaluation. + required: + - total + - errored + - failed + - passed + per_model_usage: + type: array + description: Usage statistics for each model during the evaluation run. + items: + type: object + properties: + model_name: + type: string + description: The name of the model. + invocation_count: + type: integer + description: The number of invocations. + prompt_tokens: + type: integer + description: The number of prompt tokens used. + completion_tokens: + type: integer + description: The number of completion tokens generated. + total_tokens: + type: integer + description: The total number of tokens used. + cached_tokens: + type: integer + description: The number of tokens retrieved from cache. + required: + - model_name + - invocation_count + - prompt_tokens + - completion_tokens + - total_tokens + - cached_tokens + per_testing_criteria_results: + type: array + description: Results per testing criteria applied during the evaluation run. + items: + type: object + properties: + testing_criteria: + type: string + description: A description of the testing criteria. + passed: + type: integer + description: Number of tests passed for this criteria. + failed: + type: integer + description: Number of tests failed for this criteria. + required: + - testing_criteria + - passed + - failed + data_source: + type: object + description: Information about the run's data source. + oneOf: + - $ref: "#/components/schemas/CreateEvalJsonlRunDataSource" + - $ref: "#/components/schemas/CreateEvalCompletionsRunDataSource" + - $ref: "#/components/schemas/CreateEvalResponsesRunDataSource" + metadata: + $ref: "#/components/schemas/Metadata" + error: + $ref: "#/components/schemas/EvalApiError" + required: + - object + - id + - eval_id + - status + - model + - name + - created_at + - report_url + - result_counts + - per_model_usage + - per_testing_criteria_results + - data_source + - metadata + - error + x-oaiMeta: + name: The eval run object + group: evals + example: > + { + "object": "eval.run", + "id": "evalrun_67e57965b480819094274e3a32235e4c", + "eval_id": "eval_67e579652b548190aaa83ada4b125f47", + "report_url": "https://platform.openai.com/evaluations/eval_67e579652b548190aaa83ada4b125f47?run_id=evalrun_67e57965b480819094274e3a32235e4c", + "status": "queued", + "model": "gpt-4o-mini", + "name": "gpt-4o-mini", + "created_at": 1743092069, + "result_counts": { + "total": 0, + "errored": 0, + "failed": 0, + "passed": 0 + }, + "per_model_usage": null, + "per_testing_criteria_results": null, + "data_source": { + "type": "completions", + "source": { + "type": "file_content", + "content": [ + { + "item": { + "input": "Tech Company Launches Advanced Artificial Intelligence Platform", + "ground_truth": "Technology" + } + }, + { + "item": { + "input": "Central Bank Increases Interest Rates Amid Inflation Concerns", + "ground_truth": "Markets" + } + }, + { + "item": { + "input": "International Summit Addresses Climate Change Strategies", + "ground_truth": "World" + } + }, + { + "item": { + "input": "Major Retailer Reports Record-Breaking Holiday Sales", + "ground_truth": "Business" + } + }, + { + "item": { + "input": "National Team Qualifies for World Championship Finals", + "ground_truth": "Sports" + } + }, + { + "item": { + "input": "Stock Markets Rally After Positive Economic Data Released", + "ground_truth": "Markets" + } + }, + { + "item": { + "input": "Global Manufacturer Announces Merger with Competitor", + "ground_truth": "Business" + } + }, + { + "item": { + "input": "Breakthrough in Renewable Energy Technology Unveiled", + "ground_truth": "Technology" + } + }, + { + "item": { + "input": "World Leaders Sign Historic Climate Agreement", + "ground_truth": "World" + } + }, + { + "item": { + "input": "Professional Athlete Sets New Record in Championship Event", + "ground_truth": "Sports" + } + }, + { + "item": { + "input": "Financial Institutions Adapt to New Regulatory Requirements", + "ground_truth": "Business" + } + }, + { + "item": { + "input": "Tech Conference Showcases Advances in Artificial Intelligence", + "ground_truth": "Technology" + } + }, + { + "item": { + "input": "Global Markets Respond to Oil Price Fluctuations", + "ground_truth": "Markets" + } + }, + { + "item": { + "input": "International Cooperation Strengthened Through New Treaty", + "ground_truth": "World" + } + }, + { + "item": { + "input": "Sports League Announces Revised Schedule for Upcoming Season", + "ground_truth": "Sports" + } + } + ] + }, + "input_messages": { + "type": "template", + "template": [ + { + "type": "message", + "role": "developer", + "content": { + "type": "input_text", + "text": "Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\n\n# Steps\n\n1. Analyze the content of the news headline to understand its primary focus.\n2. Extract the subject matter, identifying any key indicators or keywords.\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\n4. Ensure only one category is selected per headline.\n\n# Output Format\n\nRespond with the chosen category as a single word. For instance: \"Technology\", \"Markets\", \"World\", \"Business\", or \"Sports\".\n\n# Examples\n\n**Input**: \"Apple Unveils New iPhone Model, Featuring Advanced AI Features\" \n**Output**: \"Technology\"\n\n**Input**: \"Global Stocks Mixed as Investors Await Central Bank Decisions\" \n**Output**: \"Markets\"\n\n**Input**: \"War in Ukraine: Latest Updates on Negotiation Status\" \n**Output**: \"World\"\n\n**Input**: \"Microsoft in Talks to Acquire Gaming Company for $2 Billion\" \n**Output**: \"Business\"\n\n**Input**: \"Manchester United Secures Win in Premier League Football Match\" \n**Output**: \"Sports\" \n\n# Notes\n\n- If the headline appears to fit into more than one category, choose the most dominant theme.\n- Keywords or phrases such as \"stocks\", \"company acquisition\", \"match\", or technological brands can be good indicators for classification.\n" + } + }, + { + "type": "message", + "role": "user", + "content": { + "type": "input_text", + "text": "{{item.input}}" + } + } + ] + }, + "model": "gpt-4o-mini", + "sampling_params": { + "seed": 42, + "temperature": 1.0, + "top_p": 1.0, + "max_completions_tokens": 2048 + } + }, + "error": null, + "metadata": {} + } + EvalRunList: + type: object + title: EvalRunList + description: | + An object representing a list of runs for an evaluation. + properties: + object: + type: string + enum: + - list + default: list + description: | + The type of this object. It is always set to "list". + x-stainless-const: true + data: + type: array + description: | + An array of eval run objects. + items: + $ref: "#/components/schemas/EvalRun" + first_id: + type: string + description: The identifier of the first eval run in the data array. + last_id: + type: string + description: The identifier of the last eval run in the data array. + has_more: + type: boolean + description: Indicates whether there are more evals available. + required: + - object + - data + - first_id + - last_id + - has_more + x-oaiMeta: + name: The eval run list object + group: evals + example: > + { + "object": "list", + "data": [ + { + "object": "eval.run", + "id": "evalrun_67b7fbdad46c819092f6fe7a14189620", + "eval_id": "eval_67b7fa9a81a88190ab4aa417e397ea21", + "report_url": "https://platform.openai.com/evaluations/eval_67b7fa9a81a88190ab4aa417e397ea21?run_id=evalrun_67b7fbdad46c819092f6fe7a14189620", + "status": "completed", + "model": "o3-mini", + "name": "Academic Assistant", + "created_at": 1740110812, + "result_counts": { + "total": 171, + "errored": 0, + "failed": 80, + "passed": 91 + }, + "per_model_usage": null, + "per_testing_criteria_results": [ + { + "testing_criteria": "String check grader", + "passed": 91, + "failed": 80 + } + ], + "run_data_source": { + "type": "completions", + "template_messages": [ + { + "type": "message", + "role": "system", + "content": { + "type": "input_text", + "text": "You are a helpful assistant." + } + }, + { + "type": "message", + "role": "user", + "content": { + "type": "input_text", + "text": "Hello, can you help me with my homework?" + } + } + ], + "datasource_reference": null, + "model": "o3-mini", + "max_completion_tokens": null, + "seed": null, + "temperature": null, + "top_p": null + }, + "error": null, + "metadata": {"test": "synthetics"} + } + ], + "first_id": "evalrun_67abd54d60ec8190832b46859da808f7", + "last_id": "evalrun_67abd54d60ec8190832b46859da808f7", + "has_more": false + } + EvalRunOutputItem: + type: object + title: EvalRunOutputItem + description: | + A schema representing an evaluation run output item. + properties: + object: + type: string + enum: + - eval.run.output_item + default: eval.run.output_item + description: The type of the object. Always "eval.run.output_item". + x-stainless-const: true + id: + type: string + description: Unique identifier for the evaluation run output item. + run_id: + type: string + description: The identifier of the evaluation run associated with this output + item. + eval_id: + type: string + description: The identifier of the evaluation group. + created_at: + type: integer + description: Unix timestamp (in seconds) when the evaluation run was created. + status: + type: string + description: The status of the evaluation run. + datasource_item_id: + type: integer + description: The identifier for the data source item. + datasource_item: + type: object + description: Details of the input data source item. + additionalProperties: true + results: + type: array + description: A list of results from the evaluation run. + items: + type: object + description: A result object. + additionalProperties: true + sample: + type: object + description: A sample containing the input and output of the evaluation run. + properties: + input: + type: array + description: An array of input messages. + items: + type: object + description: An input message. + properties: + role: + type: string + description: The role of the message sender (e.g., system, user, developer). + content: + type: string + description: The content of the message. + required: + - role + - content + output: + type: array + description: An array of output messages. + items: + type: object + properties: + role: + type: string + description: The role of the message (e.g. "system", "assistant", "user"). + content: + type: string + description: The content of the message. + finish_reason: + type: string + description: The reason why the sample generation was finished. + model: + type: string + description: The model used for generating the sample. + usage: + type: object + description: Token usage details for the sample. + properties: + total_tokens: + type: integer + description: The total number of tokens used. + completion_tokens: + type: integer + description: The number of completion tokens generated. + prompt_tokens: + type: integer + description: The number of prompt tokens used. + cached_tokens: + type: integer + description: The number of tokens retrieved from cache. + required: + - total_tokens + - completion_tokens + - prompt_tokens + - cached_tokens + error: + $ref: "#/components/schemas/EvalApiError" + temperature: + type: number + description: The sampling temperature used. + max_completion_tokens: + type: integer + description: The maximum number of tokens allowed for completion. + top_p: + type: number + description: The top_p value used for sampling. + seed: + type: integer + description: The seed used for generating the sample. + required: + - input + - output + - finish_reason + - model + - usage + - error + - temperature + - max_completion_tokens + - top_p + - seed + required: + - object + - id + - run_id + - eval_id + - created_at + - status + - datasource_item_id + - datasource_item + - results + - sample + x-oaiMeta: + name: The eval run output item object + group: evals + example: > + { + "object": "eval.run.output_item", + "id": "outputitem_67abd55eb6548190bb580745d5644a33", + "run_id": "evalrun_67abd54d60ec8190832b46859da808f7", + "eval_id": "eval_67abd54d9b0081909a86353f6fb9317a", + "created_at": 1739314509, + "status": "pass", + "datasource_item_id": 137, + "datasource_item": { + "teacher": "To grade essays, I only check for style, content, and grammar.", + "student": "I am a student who is trying to write the best essay." + }, + "results": [ + { + "name": "String Check Grader", + "type": "string-check-grader", + "score": 1.0, + "passed": true, + } + ], + "sample": { + "input": [ + { + "role": "system", + "content": "You are an evaluator bot..." + }, + { + "role": "user", + "content": "You are assessing..." + } + ], + "output": [ + { + "role": "assistant", + "content": "The rubric is not clear nor concise." + } + ], + "finish_reason": "stop", + "model": "gpt-4o-2024-08-06", + "usage": { + "total_tokens": 521, + "completion_tokens": 2, + "prompt_tokens": 519, + "cached_tokens": 0 + }, + "error": null, + "temperature": 1.0, + "max_completion_tokens": 2048, + "top_p": 1.0, + "seed": 42 + } + } + EvalRunOutputItemList: + type: object + title: EvalRunOutputItemList + description: | + An object representing a list of output items for an evaluation run. + properties: + object: + type: string + enum: + - list + default: list + description: | + The type of this object. It is always set to "list". + x-stainless-const: true + data: + type: array + description: | + An array of eval run output item objects. + items: + $ref: "#/components/schemas/EvalRunOutputItem" + first_id: + type: string + description: The identifier of the first eval run output item in the data array. + last_id: + type: string + description: The identifier of the last eval run output item in the data array. + has_more: + type: boolean + description: Indicates whether there are more eval run output items available. + required: + - object + - data + - first_id + - last_id + - has_more + x-oaiMeta: + name: The eval run output item list object + group: evals + example: > + { + "object": "list", + "data": [ + { + "object": "eval.run.output_item", + "id": "outputitem_67abd55eb6548190bb580745d5644a33", + "run_id": "evalrun_67abd54d60ec8190832b46859da808f7", + "eval_id": "eval_67abd54d9b0081909a86353f6fb9317a", + "created_at": 1739314509, + "status": "pass", + "datasource_item_id": 137, + "datasource_item": { + "teacher": "To grade essays, I only check for style, content, and grammar.", + "student": "I am a student who is trying to write the best essay." + }, + "results": [ + { + "name": "String Check Grader", + "type": "string-check-grader", + "score": 1.0, + "passed": true, + } + ], + "sample": { + "input": [ + { + "role": "system", + "content": "You are an evaluator bot..." + }, + { + "role": "user", + "content": "You are assessing..." + } + ], + "output": [ + { + "role": "assistant", + "content": "The rubric is not clear nor concise." + } + ], + "finish_reason": "stop", + "model": "gpt-4o-2024-08-06", + "usage": { + "total_tokens": 521, + "completion_tokens": 2, + "prompt_tokens": 519, + "cached_tokens": 0 + }, + "error": null, + "temperature": 1.0, + "max_completion_tokens": 2048, + "top_p": 1.0, + "seed": 42 + } + }, + ], + "first_id": "outputitem_67abd55eb6548190bb580745d5644a33", + "last_id": "outputitem_67abd55eb6548190bb580745d5644a33", + "has_more": false + } + EvalScoreModelGrader: + type: object + title: ScoreModelGrader + description: > + A ScoreModelGrader object that uses a model to assign a score to the + input. + properties: + type: + type: string + enum: + - score_model + description: The object type, which is always `score_model`. + x-stainless-const: true + name: + type: string + description: The name of the grader. + model: + type: string + description: The model to use for the evaluation. + sampling_params: + type: object + description: The sampling parameters for the model. + input: + type: array + items: + $ref: "#/components/schemas/EvalItem" + description: The input text. This may include template strings. + pass_threshold: + type: number + description: The threshold for the score. + range: + type: array + items: + type: number + min_items: 2 + max_items: 2 + description: The range of the score. Defaults to `[0, 1]`. + required: + - type + - name + - input + - model + x-oaiMeta: + name: The eval score model grader object + group: evals + example: | + { + "type": "score_model", + "name": "Example score model grader", + "input": "{{sample.output_text}}", + "reference": "{{item.label}}", + "operation": "eq" + } + EvalStoredCompletionsDataSourceConfig: + type: object + title: StoredCompletionsDataSourceConfig + description: > + A StoredCompletionsDataSourceConfig which specifies the metadata + property of your stored completions query. + + This is usually metadata like `usecase=chatbot` or `prompt-version=v2`, + etc. + + The schema returned by this data source config is used to defined what + variables are available in your evals. + + `item` and `sample` are both defined when using this data source config. + properties: + type: + type: string + enum: + - stored_completions + default: stored_completions + description: The type of data source. Always `stored_completions`. + x-stainless-const: true + metadata: + $ref: "#/components/schemas/Metadata" + schema: + type: object + description: | + The json schema for the run data source items. + Learn how to build JSON schemas [here](https://json-schema.org/). + additionalProperties: true + required: + - type + - schema + x-oaiMeta: + name: The stored completions data source object for evals + group: evals + example: | + { + "type": "stored_completions", + "metadata": { + "language": "english" + }, + "schema": { + "type": "object", + "properties": { + "item": { + "type": "object" + }, + "sample": { + "type": "object" + } + }, + "required": [ + "item", + "sample" + } + } + EvalStoredCompletionsSource: + type: object + title: StoredCompletionsRunDataSource + description: > + A StoredCompletionsRunDataSource configuration describing a set of + filters + properties: + type: + type: string + enum: + - stored_completions + default: stored_completions + description: The type of source. Always `stored_completions`. + x-stainless-const: true + metadata: + $ref: "#/components/schemas/Metadata" + model: + type: string + nullable: true + description: An optional model to filter by (e.g., 'gpt-4o'). + created_after: + type: integer + nullable: true + description: An optional Unix timestamp to filter items created after this time. + created_before: + type: integer + nullable: true + description: An optional Unix timestamp to filter items created before this time. + limit: + type: integer + nullable: true + description: An optional maximum number of items to return. + required: + - type + x-oaiMeta: + name: The stored completions data source object used to configure an individual + run + group: eval runs + example: | + { + "type": "stored_completions", + "model": "gpt-4o", + "created_after": 1668124800, + "created_before": 1668124900, + "limit": 100, + "metadata": {} + } + EvalStringCheckGrader: + type: object + title: StringCheckGrader + description: > + A StringCheckGrader object that performs a string comparison between + input and reference using a specified operation. + properties: + type: + type: string + enum: + - string_check + description: The object type, which is always `string_check`. + x-stainless-const: true + name: + type: string + description: The name of the grader. + input: + type: string + description: The input text. This may include template strings. + reference: + type: string + description: The reference text. This may include template strings. + operation: + type: string + enum: + - eq + - ne + - like + - ilike + description: The string check operation to perform. One of `eq`, `ne`, `like`, + or `ilike`. + required: + - type + - name + - input + - reference + - operation + x-oaiMeta: + name: The eval string check grader object + group: evals + example: | + { + "type": "string_check", + "name": "Example string check grader", + "input": "{{sample.output_text}}", + "reference": "{{item.label}}", + "operation": "eq" + } + EvalTextSimilarityGrader: + type: object + title: TextSimilarityGrader + description: > + A TextSimilarityGrader object which grades text based on similarity + metrics. + properties: + type: + type: string + enum: + - text_similarity + default: text_similarity + description: The type of grader. + x-stainless-const: true + name: + type: string + description: The name of the grader. + input: + type: string + description: The text being graded. + reference: + type: string + description: The text being graded against. + pass_threshold: + type: number + description: A float score where a value greater than or equal indicates a + passing grade. + evaluation_metric: + type: string + enum: + - fuzzy_match + - bleu + - gleu + - meteor + - rouge_1 + - rouge_2 + - rouge_3 + - rouge_4 + - rouge_5 + - rouge_l + description: The evaluation metric to use. One of `fuzzy_match`, `bleu`, `gleu`, + `meteor`, `rouge_1`, `rouge_2`, `rouge_3`, `rouge_4`, `rouge_5`, or + `rouge_l`. + required: + - type + - input + - reference + - pass_threshold + - evaluation_metric + x-oaiMeta: + name: The eval text similarity grader object + group: evals + example: | + { + "type": "text_similarity", + "name": "example text similarity grader", + "input": "The graded text", + "reference": "The reference text", + "pass_threshold": 0.8, + "evaluation_metric": "fuzzy_match" + } + FilePath: + type: object + title: File path + description: | + A path to a file. + properties: + type: + type: string + description: | + The type of the file path. Always `file_path`. + enum: + - file_path + x-stainless-const: true + file_id: + type: string + description: | + The ID of the file. + index: + type: integer + description: | + The index of the file in the list of files. + required: + - type + - file_id + - index + FileSearchRanker: + type: string + description: The ranker to use for the file search. If not specified will use + the `auto` ranker. + enum: + - auto + - default_2024_08_21 + FileSearchRankingOptions: + title: File search tool call ranking options + type: object + description: | + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + properties: + ranker: + $ref: "#/components/schemas/FileSearchRanker" + score_threshold: + type: number + description: The score threshold for the file search. All values must be a + floating point number between 0 and 1. + minimum: 0 + maximum: 1 + required: + - score_threshold + FileSearchToolCall: + type: object + title: File search tool call + description: > + The results of a file search tool call. See the + + [file search guide](/docs/guides/tools-file-search) for more + information. + properties: + id: + type: string + description: | + The unique ID of the file search tool call. + type: + type: string + enum: + - file_search_call + description: | + The type of the file search tool call. Always `file_search_call`. + x-stainless-const: true + status: + type: string + description: | + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, + enum: + - in_progress + - searching + - completed + - incomplete + - failed + queries: + type: array + items: + type: string + description: | + The queries used to search for files. + results: + type: array + description: | + The results of the file search tool call. + items: + type: object + properties: + file_id: + type: string + description: | + The unique ID of the file. + text: + type: string + description: | + The text that was retrieved from the file. + filename: + type: string + description: | + The name of the file. + attributes: + $ref: "#/components/schemas/VectorStoreFileAttributes" + score: + type: number + format: float + description: | + The relevance score of the file - a value between 0 and 1. + nullable: true + required: + - id + - type + - status + - queries + FineTuneChatCompletionRequestAssistantMessage: + allOf: + - type: object + title: Assistant message + deprecated: false + properties: + weight: + type: integer + enum: + - 0 + - 1 + description: Controls whether the assistant message is trained against (0 or 1) + - $ref: "#/components/schemas/ChatCompletionRequestAssistantMessage" + required: + - role + FineTuneChatRequestInput: + type: object + description: The per-line training example of a fine-tuning input file for chat + models using the supervised method. + properties: + messages: + type: array + minItems: 1 + items: + oneOf: + - $ref: "#/components/schemas/ChatCompletionRequestSystemMessage" + - $ref: "#/components/schemas/ChatCompletionRequestUserMessage" + - $ref: "#/components/schemas/FineTuneChatCompletionRequestAssistantMessage" + - $ref: "#/components/schemas/ChatCompletionRequestToolMessage" + - $ref: "#/components/schemas/ChatCompletionRequestFunctionMessage" + tools: + type: array + description: A list of tools the model may generate JSON inputs for. + items: + $ref: "#/components/schemas/ChatCompletionTool" + parallel_tool_calls: + $ref: "#/components/schemas/ParallelToolCalls" + functions: + deprecated: true + description: A list of functions the model may generate JSON inputs for. + type: array + minItems: 1 + maxItems: 128 + items: + $ref: "#/components/schemas/ChatCompletionFunctions" + x-oaiMeta: + name: Training format for chat models using the supervised method + example: > + { + "messages": [ + { "role": "user", "content": "What is the weather in San Francisco?" }, + { + "role": "assistant", + "tool_calls": [ + { + "id": "call_id", + "type": "function", + "function": { + "name": "get_current_weather", + "arguments": "{\"location\": \"San Francisco, USA\", \"format\": \"celsius\"}" + } + } + ] + } + ], + "parallel_tool_calls": false, + "tools": [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and country, eg. San Francisco, USA" + }, + "format": { "type": "string", "enum": ["celsius", "fahrenheit"] } + }, + "required": ["location", "format"] + } + } + } + ] + } + FineTuneCompletionRequestInput: + type: object + description: The per-line training example of a fine-tuning input file for + completions models + properties: + prompt: + type: string + description: The input prompt for this training example. + completion: + type: string + description: The desired completion for this training example. + x-oaiMeta: + name: Training format for completions models + example: | + { + "prompt": "What is the answer to 2+2", + "completion": "4" + } + FineTuneDPOMethod: + type: object + description: Configuration for the DPO fine-tuning method. + properties: + hyperparameters: + type: object + description: The hyperparameters used for the fine-tuning job. + properties: + beta: + description: > + The beta value for the DPO method. A higher beta value will + increase the weight of the penalty between the policy and + reference model. + oneOf: + - type: string + enum: + - auto + x-stainless-const: true + - type: number + minimum: 0 + maximum: 2 + exclusiveMinimum: true + default: auto + batch_size: + description: > + Number of examples in each batch. A larger batch size means that + model parameters are updated less frequently, but with lower + variance. + oneOf: + - type: string + enum: + - auto + x-stainless-const: true + - type: integer + minimum: 1 + maximum: 256 + default: auto + learning_rate_multiplier: + description: > + Scaling factor for the learning rate. A smaller learning rate + may be useful to avoid overfitting. + oneOf: + - type: string + enum: + - auto + x-stainless-const: true + - type: number + minimum: 0 + exclusiveMinimum: true + default: auto + n_epochs: + description: > + The number of epochs to train the model for. An epoch refers to + one full cycle through the training dataset. + oneOf: + - type: string + enum: + - auto + x-stainless-const: true + - type: integer + minimum: 1 + maximum: 50 + default: auto + FineTuneMethod: + type: object + description: The method used for fine-tuning. + properties: + type: + type: string + description: The type of method. Is either `supervised` or `dpo`. + enum: + - supervised + - dpo + supervised: + $ref: "#/components/schemas/FineTuneSupervisedMethod" + dpo: + $ref: "#/components/schemas/FineTuneDPOMethod" + FineTunePreferenceRequestInput: + type: object + description: The per-line training example of a fine-tuning input file for chat + models using the dpo method. + properties: + input: + type: object + properties: + messages: + type: array + minItems: 1 + items: + oneOf: + - $ref: "#/components/schemas/ChatCompletionRequestSystemMessage" + - $ref: "#/components/schemas/ChatCompletionRequestUserMessage" + - $ref: "#/components/schemas/FineTuneChatCompletionRequestAssistantMessage" + - $ref: "#/components/schemas/ChatCompletionRequestToolMessage" + - $ref: "#/components/schemas/ChatCompletionRequestFunctionMessage" + tools: + type: array + description: A list of tools the model may generate JSON inputs for. + items: + $ref: "#/components/schemas/ChatCompletionTool" + parallel_tool_calls: + $ref: "#/components/schemas/ParallelToolCalls" + preferred_completion: + type: array + description: The preferred completion message for the output. + maxItems: 1 + items: + oneOf: + - $ref: "#/components/schemas/ChatCompletionRequestAssistantMessage" + non_preferred_completion: + type: array + description: The non-preferred completion message for the output. + maxItems: 1 + items: + oneOf: + - $ref: "#/components/schemas/ChatCompletionRequestAssistantMessage" + x-oaiMeta: + name: Training format for chat models using the preference method + example: > + { + "input": { + "messages": [ + { "role": "user", "content": "What is the weather in San Francisco?" } + ] + }, + "preferred_completion": [ + { + "role": "assistant", + "content": "The weather in San Francisco is 70 degrees Fahrenheit." + } + ], + "non_preferred_completion": [ + { + "role": "assistant", + "content": "The weather in San Francisco is 21 degrees Celsius." + } + ] + } + FineTuneSupervisedMethod: + type: object + description: Configuration for the supervised fine-tuning method. + properties: + hyperparameters: + type: object + description: The hyperparameters used for the fine-tuning job. + properties: + batch_size: + description: > + Number of examples in each batch. A larger batch size means that + model parameters are updated less frequently, but with lower + variance. + oneOf: + - type: string + enum: + - auto + x-stainless-const: true + - type: integer + minimum: 1 + maximum: 256 + default: auto + learning_rate_multiplier: + description: > + Scaling factor for the learning rate. A smaller learning rate + may be useful to avoid overfitting. + oneOf: + - type: string + enum: + - auto + x-stainless-const: true + - type: number + minimum: 0 + exclusiveMinimum: true + default: auto + n_epochs: + description: > + The number of epochs to train the model for. An epoch refers to + one full cycle through the training dataset. + oneOf: + - type: string + enum: + - auto + x-stainless-const: true + - type: integer + minimum: 1 + maximum: 50 + default: auto + FineTuningCheckpointPermission: + type: object + title: FineTuningCheckpointPermission + description: > + The `checkpoint.permission` object represents a permission for a + fine-tuned model checkpoint. + properties: + id: + type: string + description: The permission identifier, which can be referenced in the API + endpoints. + created_at: + type: integer + description: The Unix timestamp (in seconds) for when the permission was created. + project_id: + type: string + description: The project identifier that the permission is for. + object: + type: string + description: The object type, which is always "checkpoint.permission". + enum: + - checkpoint.permission + x-stainless-const: true + required: + - created_at + - id + - object + - project_id + x-oaiMeta: + name: The fine-tuned model checkpoint permission object + example: | + { + "object": "checkpoint.permission", + "id": "cp_zc4Q7MP6XxulcVzj4MZdwsAB", + "created_at": 1712211699, + "project_id": "proj_abGMw1llN8IrBb6SvvY5A1iH" + } + FineTuningIntegration: + type: object + title: Fine-Tuning Job Integration + required: + - type + - wandb + properties: + type: + type: string + description: The type of the integration being enabled for the fine-tuning job + enum: + - wandb + x-stainless-const: true + wandb: + type: object + description: > + The settings for your integration with Weights and Biases. This + payload specifies the project that + + metrics will be sent to. Optionally, you can set an explicit display + name for your run, add tags + + to your run, and set a default entity (team, username, etc) to be + associated with your run. + required: + - project + properties: + project: + description: | + The name of the project that the new run will be created under. + type: string + example: my-wandb-project + name: + description: > + A display name to set for the run. If not set, we will use the + Job ID as the name. + nullable: true + type: string + entity: + description: > + The entity to use for the run. This allows you to set the team + or username of the WandB user that you would + + like associated with the run. If not set, the default entity for + the registered WandB API key is used. + nullable: true + type: string + tags: + description: > + A list of tags to be attached to the newly created run. These + tags are passed through directly to WandB. Some + + default tags are generated by OpenAI: "openai/finetune", + "openai/{base-model}", "openai/{ftjob-abcdef}". + type: array + items: + type: string + example: custom-tag + FineTuningJob: + type: object + title: FineTuningJob + description: > + The `fine_tuning.job` object represents a fine-tuning job that has been + created through the API. + properties: + id: + type: string + description: The object identifier, which can be referenced in the API endpoints. + created_at: + type: integer + description: The Unix timestamp (in seconds) for when the fine-tuning job was + created. + error: + type: object + nullable: true + description: For fine-tuning jobs that have `failed`, this will contain more + information on the cause of the failure. + properties: + code: + type: string + description: A machine-readable error code. + message: + type: string + description: A human-readable error message. + param: + type: string + description: The parameter that was invalid, usually `training_file` or + `validation_file`. This field will be null if the failure was + not parameter-specific. + nullable: true + required: + - code + - message + - param + fine_tuned_model: + type: string + nullable: true + description: The name of the fine-tuned model that is being created. The value + will be null if the fine-tuning job is still running. + finished_at: + type: integer + nullable: true + description: The Unix timestamp (in seconds) for when the fine-tuning job was + finished. The value will be null if the fine-tuning job is still + running. + hyperparameters: + type: object + description: The hyperparameters used for the fine-tuning job. This value will + only be returned when running `supervised` jobs. + properties: + batch_size: + description: > + Number of examples in each batch. A larger batch size means that + model parameters + + are updated less frequently, but with lower variance. + oneOf: + - type: string + enum: + - auto + x-stainless-const: true + - type: integer + minimum: 1 + maximum: 256 + default: auto + learning_rate_multiplier: + description: > + Scaling factor for the learning rate. A smaller learning rate + may be useful to avoid + + overfitting. + oneOf: + - type: string + enum: + - auto + x-stainless-const: true + - type: number + minimum: 0 + exclusiveMinimum: true + default: auto + n_epochs: + description: > + The number of epochs to train the model for. An epoch refers to + one full cycle + + through the training dataset. + oneOf: + - type: string + enum: + - auto + x-stainless-const: true + - type: integer + minimum: 1 + maximum: 50 + default: auto + model: + type: string + description: The base model that is being fine-tuned. + object: + type: string + description: The object type, which is always "fine_tuning.job". + enum: + - fine_tuning.job + x-stainless-const: true + organization_id: + type: string + description: The organization that owns the fine-tuning job. + result_files: + type: array + description: The compiled results file ID(s) for the fine-tuning job. You can + retrieve the results with the [Files + API](/docs/api-reference/files/retrieve-contents). + items: + type: string + example: file-abc123 + status: + type: string + description: The current status of the fine-tuning job, which can be either + `validating_files`, `queued`, `running`, `succeeded`, `failed`, or + `cancelled`. + enum: + - validating_files + - queued + - running + - succeeded + - failed + - cancelled + trained_tokens: + type: integer + nullable: true + description: The total number of billable tokens processed by this fine-tuning + job. The value will be null if the fine-tuning job is still running. + training_file: + type: string + description: The file ID used for training. You can retrieve the training data + with the [Files API](/docs/api-reference/files/retrieve-contents). + validation_file: + type: string + nullable: true + description: The file ID used for validation. You can retrieve the validation + results with the [Files + API](/docs/api-reference/files/retrieve-contents). + integrations: + type: array + nullable: true + description: A list of integrations to enable for this fine-tuning job. + maxItems: 5 + items: + oneOf: + - $ref: "#/components/schemas/FineTuningIntegration" + seed: + type: integer + description: The seed used for the fine-tuning job. + estimated_finish: + type: integer + nullable: true + description: The Unix timestamp (in seconds) for when the fine-tuning job is + estimated to finish. The value will be null if the fine-tuning job + is not running. + method: + $ref: "#/components/schemas/FineTuneMethod" + metadata: + $ref: "#/components/schemas/Metadata" + required: + - created_at + - error + - finished_at + - fine_tuned_model + - hyperparameters + - id + - model + - object + - organization_id + - result_files + - status + - trained_tokens + - training_file + - validation_file + - seed + x-oaiMeta: + name: The fine-tuning job object + example: | + { + "object": "fine_tuning.job", + "id": "ftjob-abc123", + "model": "davinci-002", + "created_at": 1692661014, + "finished_at": 1692661190, + "fine_tuned_model": "ft:davinci-002:my-org:custom_suffix:7q8mpxmy", + "organization_id": "org-123", + "result_files": [ + "file-abc123" + ], + "status": "succeeded", + "validation_file": null, + "training_file": "file-abc123", + "hyperparameters": { + "n_epochs": 4, + "batch_size": 1, + "learning_rate_multiplier": 1.0 + }, + "trained_tokens": 5768, + "integrations": [], + "seed": 0, + "estimated_finish": 0, + "method": { + "type": "supervised", + "supervised": { + "hyperparameters": { + "n_epochs": 4, + "batch_size": 1, + "learning_rate_multiplier": 1.0 + } + } + }, + "metadata": { + "key": "value" + } + } + FineTuningJobCheckpoint: + type: object + title: FineTuningJobCheckpoint + description: > + The `fine_tuning.job.checkpoint` object represents a model checkpoint + for a fine-tuning job that is ready to use. + properties: + id: + type: string + description: The checkpoint identifier, which can be referenced in the API + endpoints. + created_at: + type: integer + description: The Unix timestamp (in seconds) for when the checkpoint was created. + fine_tuned_model_checkpoint: + type: string + description: The name of the fine-tuned checkpoint model that is created. + step_number: + type: integer + description: The step number that the checkpoint was created at. + metrics: + type: object + description: Metrics at the step number during the fine-tuning job. + properties: + step: + type: number + train_loss: + type: number + train_mean_token_accuracy: + type: number + valid_loss: + type: number + valid_mean_token_accuracy: + type: number + full_valid_loss: + type: number + full_valid_mean_token_accuracy: + type: number + fine_tuning_job_id: + type: string + description: The name of the fine-tuning job that this checkpoint was created + from. + object: + type: string + description: The object type, which is always "fine_tuning.job.checkpoint". + enum: + - fine_tuning.job.checkpoint + x-stainless-const: true + required: + - created_at + - fine_tuning_job_id + - fine_tuned_model_checkpoint + - id + - metrics + - object + - step_number + x-oaiMeta: + name: The fine-tuning job checkpoint object + example: > + { + "object": "fine_tuning.job.checkpoint", + "id": "ftckpt_qtZ5Gyk4BLq1SfLFWp3RtO3P", + "created_at": 1712211699, + "fine_tuned_model_checkpoint": "ft:gpt-4o-mini-2024-07-18:my-org:custom_suffix:9ABel2dg:ckpt-step-88", + "fine_tuning_job_id": "ftjob-fpbNQ3H1GrMehXRf8cO97xTN", + "metrics": { + "step": 88, + "train_loss": 0.478, + "train_mean_token_accuracy": 0.924, + "valid_loss": 10.112, + "valid_mean_token_accuracy": 0.145, + "full_valid_loss": 0.567, + "full_valid_mean_token_accuracy": 0.944 + }, + "step_number": 88 + } + FineTuningJobEvent: + type: object + description: Fine-tuning job event object + properties: + object: + type: string + description: The object type, which is always "fine_tuning.job.event". + enum: + - fine_tuning.job.event + x-stainless-const: true + id: + type: string + description: The object identifier. + created_at: + type: integer + description: The Unix timestamp (in seconds) for when the fine-tuning job was + created. + level: + type: string + description: The log level of the event. + enum: + - info + - warn + - error + message: + type: string + description: The message of the event. + type: + type: string + description: The type of event. + enum: + - message + - metrics + data: + type: object + description: The data associated with the event. + required: + - id + - object + - created_at + - level + - message + x-oaiMeta: + name: The fine-tuning job event object + example: | + { + "object": "fine_tuning.job.event", + "id": "ftevent-abc123" + "created_at": 1677610602, + "level": "info", + "message": "Created fine-tuning job", + "data": {}, + "type": "message" + } + FunctionObject: + type: object + properties: + description: + type: string + description: A description of what the function does, used by the model to + choose when and how to call the function. + name: + type: string + description: The name of the function to be called. Must be a-z, A-Z, 0-9, or + contain underscores and dashes, with a maximum length of 64. + parameters: + $ref: "#/components/schemas/FunctionParameters" + strict: + type: boolean + nullable: true + default: false + description: Whether to enable strict schema adherence when generating the + function call. If set to true, the model will follow the exact + schema defined in the `parameters` field. Only a subset of JSON + Schema is supported when `strict` is `true`. Learn more about + Structured Outputs in the [function calling + guide](docs/guides/function-calling). + required: + - name + FunctionParameters: + type: object + description: >- + The parameters the functions accepts, described as a JSON Schema object. + See the [guide](/docs/guides/function-calling) for examples, and the + [JSON Schema + reference](https://json-schema.org/understanding-json-schema/) for + documentation about the format. + + + Omitting `parameters` defines a function with an empty parameter list. + additionalProperties: true + FunctionToolCall: + type: object + title: Function tool call + description: > + A tool call to run a function. See the + + [function calling guide](/docs/guides/function-calling) for more + information. + properties: + id: + type: string + description: | + The unique ID of the function tool call. + type: + type: string + enum: + - function_call + description: | + The type of the function tool call. Always `function_call`. + x-stainless-const: true + call_id: + type: string + description: | + The unique ID of the function tool call generated by the model. + name: + type: string + description: | + The name of the function to run. + arguments: + type: string + description: | + A JSON string of the arguments to pass to the function. + status: + type: string + description: | + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + enum: + - in_progress + - completed + - incomplete + required: + - type + - call_id + - name + - arguments + FunctionToolCallOutput: + type: object + title: Function tool call output + description: | + The output of a function tool call. + properties: + id: + type: string + description: > + The unique ID of the function tool call output. Populated when this + item + + is returned via API. + type: + type: string + enum: + - function_call_output + description: > + The type of the function tool call output. Always + `function_call_output`. + x-stainless-const: true + call_id: + type: string + description: | + The unique ID of the function tool call generated by the model. + output: + type: string + description: | + A JSON string of the output of the function tool call. + status: + type: string + description: | + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + enum: + - in_progress + - completed + - incomplete + required: + - type + - call_id + - output + FunctionToolCallOutputResource: + allOf: + - $ref: "#/components/schemas/FunctionToolCallOutput" + - type: object + properties: + id: + type: string + description: | + The unique ID of the function call tool output. + required: + - id + FunctionToolCallResource: + allOf: + - $ref: "#/components/schemas/FunctionToolCall" + - type: object + properties: + id: + type: string + description: | + The unique ID of the function tool call. + required: + - id + Image: + type: object + description: Represents the content or the URL of an image generated by the + OpenAI API. + properties: + b64_json: + type: string + description: The base64-encoded JSON of the generated image. Default value for + `gpt-image-1`, and only present if `response_format` is set to + `b64_json` for `dall-e-2` and `dall-e-3`. + url: + type: string + description: When using `dall-e-2` or `dall-e-3`, the URL of the generated image + if `response_format` is set to `url` (default value). Unsupported + for `gpt-image-1`. + revised_prompt: + type: string + description: For `dall-e-3` only, the revised prompt that was used to generate + the image. + ImagesResponse: + type: object + title: Image generation response + description: The response from the image generation endpoint. + properties: + created: + type: integer + description: The Unix timestamp (in seconds) of when the image was created. + data: + type: array + description: The list of generated images. + items: + $ref: "#/components/schemas/Image" + usage: + type: object + description: > + For `gpt-image-1` only, the token usage information for the image + generation. + required: + - total_tokens + - input_tokens + - output_tokens + - input_tokens_details + properties: + total_tokens: + type: integer + description: The total number of tokens (images and text) used for the image + generation. + input_tokens: + type: integer + description: The number of tokens (images and text) in the input prompt. + output_tokens: + type: integer + description: The number of image tokens in the output image. + input_tokens_details: + type: object + description: The input tokens detailed information for the image generation. + required: + - text_tokens + - image_tokens + properties: + text_tokens: + type: integer + description: The number of text tokens in the input prompt. + image_tokens: + type: integer + description: The number of image tokens in the input prompt. + required: + - created + x-oaiMeta: + name: The image generation response + group: images + example: | + { + "created": 1713833628, + "data": [ + { + "b64_json": "..." + } + ], + "usage": { + "total_tokens": 100, + "input_tokens": 50, + "output_tokens": 50, + "input_tokens_details": { + "text_tokens": 10, + "image_tokens": 40 + } + } + } + Includable: + type: string + description: > + Specify additional output data to include in the model response. + Currently + + supported values are: + + - `file_search_call.results`: Include the search results of + the file search tool call. + - `message.input_image.image_url`: Include image urls from the input + message. + + - `computer_call_output.output.image_url`: Include image urls from the + computer call output. + enum: + - file_search_call.results + - message.input_image.image_url + - computer_call_output.output.image_url + InputAudio: + type: object + title: Audio input + description: | + An audio input to the model. + properties: + type: + type: string + description: | + The type of the input item. Always `input_audio`. + enum: + - input_audio + x-stainless-const: true + data: + type: string + description: | + Base64-encoded audio data. + format: + type: string + description: > + The format of the audio data. Currently supported formats are `mp3` + and + + `wav`. + enum: + - mp3 + - wav + required: + - type + - data + - format + InputContent: + oneOf: + - $ref: "#/components/schemas/InputTextContent" + - $ref: "#/components/schemas/InputImageContent" + - $ref: "#/components/schemas/InputFileContent" + InputItem: + oneOf: + - $ref: "#/components/schemas/EasyInputMessage" + - type: object + title: Item + description: | + An item representing part of the context for the response to be + generated by the model. Can contain text, images, and audio inputs, + as well as previous assistant responses and tool call outputs. + $ref: "#/components/schemas/Item" + - $ref: "#/components/schemas/ItemReferenceParam" + discriminator: + propertyName: type + InputMessage: + type: object + title: Input message + description: > + A message input to the model with a role indicating instruction + following + + hierarchy. Instructions given with the `developer` or `system` role take + + precedence over instructions given with the `user` role. + properties: + type: + type: string + description: | + The type of the message input. Always set to `message`. + enum: + - message + x-stainless-const: true + role: + type: string + description: > + The role of the message input. One of `user`, `system`, or + `developer`. + enum: + - user + - system + - developer + status: + type: string + description: | + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + enum: + - in_progress + - completed + - incomplete + content: + $ref: "#/components/schemas/InputMessageContentList" + required: + - role + - content + InputMessageContentList: + type: array + title: Input item content list + description: > + A list of one or many input items to the model, containing different + content + + types. + items: + $ref: "#/components/schemas/InputContent" + InputMessageResource: + allOf: + - $ref: "#/components/schemas/InputMessage" + - type: object + properties: + id: + type: string + description: | + The unique ID of the message input. + required: + - id + Invite: + type: object + description: Represents an individual `invite` to the organization. + properties: + object: + type: string + enum: + - organization.invite + description: The object type, which is always `organization.invite` + x-stainless-const: true + id: + type: string + description: The identifier, which can be referenced in API endpoints + email: + type: string + description: The email address of the individual to whom the invite was sent + role: + type: string + enum: + - owner + - reader + description: "`owner` or `reader`" + status: + type: string + enum: + - accepted + - expired + - pending + description: "`accepted`,`expired`, or `pending`" + invited_at: + type: integer + description: The Unix timestamp (in seconds) of when the invite was sent. + expires_at: + type: integer + description: The Unix timestamp (in seconds) of when the invite expires. + accepted_at: + type: integer + description: The Unix timestamp (in seconds) of when the invite was accepted. + projects: + type: array + description: The projects that were granted membership upon acceptance of the + invite. + items: + type: object + properties: + id: + type: string + description: Project's public ID + role: + type: string + enum: + - member + - owner + description: Project membership role + required: + - object + - id + - email + - role + - status + - invited_at + - expires_at + x-oaiMeta: + name: The invite object + example: | + { + "object": "organization.invite", + "id": "invite-abc", + "email": "user@example.com", + "role": "owner", + "status": "accepted", + "invited_at": 1711471533, + "expires_at": 1711471533, + "accepted_at": 1711471533, + "projects": [ + { + "id": "project-xyz", + "role": "member" + } + ] + } + InviteDeleteResponse: + type: object + properties: + object: + type: string + enum: + - organization.invite.deleted + description: The object type, which is always `organization.invite.deleted` + x-stainless-const: true + id: + type: string + deleted: + type: boolean + required: + - object + - id + - deleted + InviteListResponse: + type: object + properties: + object: + type: string + enum: + - list + description: The object type, which is always `list` + x-stainless-const: true + data: + type: array + items: + $ref: "#/components/schemas/Invite" + first_id: + type: string + description: The first `invite_id` in the retrieved `list` + last_id: + type: string + description: The last `invite_id` in the retrieved `list` + has_more: + type: boolean + description: The `has_more` property is used for pagination to indicate there + are additional results. + required: + - object + - data + InviteRequest: + type: object + properties: + email: + type: string + description: Send an email to this address + role: + type: string + enum: + - reader + - owner + description: "`owner` or `reader`" + projects: + type: array + description: An array of projects to which membership is granted at the same + time the org invite is accepted. If omitted, the user will be + invited to the default project for compatibility with legacy + behavior. + items: + type: object + properties: + id: + type: string + description: Project's public ID + role: + type: string + enum: + - member + - owner + description: Project membership role + required: + - id + - role + required: + - email + - role + Item: + type: object + description: | + Content item used to generate a response. + oneOf: + - $ref: "#/components/schemas/InputMessage" + - $ref: "#/components/schemas/OutputMessage" + - $ref: "#/components/schemas/FileSearchToolCall" + - $ref: "#/components/schemas/ComputerToolCall" + - $ref: "#/components/schemas/ComputerCallOutputItemParam" + - $ref: "#/components/schemas/WebSearchToolCall" + - $ref: "#/components/schemas/FunctionToolCall" + - $ref: "#/components/schemas/FunctionCallOutputItemParam" + - $ref: "#/components/schemas/ReasoningItem" + discriminator: + propertyName: type + ItemResource: + description: | + Content item used to generate a response. + oneOf: + - $ref: "#/components/schemas/InputMessageResource" + - $ref: "#/components/schemas/OutputMessage" + - $ref: "#/components/schemas/FileSearchToolCall" + - $ref: "#/components/schemas/ComputerToolCall" + - $ref: "#/components/schemas/ComputerToolCallOutputResource" + - $ref: "#/components/schemas/WebSearchToolCall" + - $ref: "#/components/schemas/FunctionToolCallResource" + - $ref: "#/components/schemas/FunctionToolCallOutputResource" + discriminator: + propertyName: type + KeyPress: + type: object + title: KeyPress + description: | + A collection of keypresses the model would like to perform. + properties: + type: + type: string + enum: + - keypress + default: keypress + description: | + Specifies the event type. For a keypress action, this property is + always set to `keypress`. + x-stainless-const: true + keys: + type: array + items: + type: string + description: | + One of the keys the model is requesting to be pressed. + description: > + The combination of keys the model is requesting to be pressed. This + is an + + array of strings, each representing a key. + required: + - type + - keys + ListAssistantsResponse: + type: object + properties: + object: + type: string + example: list + data: + type: array + items: + $ref: "#/components/schemas/AssistantObject" + first_id: + type: string + example: asst_abc123 + last_id: + type: string + example: asst_abc456 + has_more: + type: boolean + example: false + required: + - object + - data + - first_id + - last_id + - has_more + x-oaiMeta: + name: List assistants response object + group: chat + example: > + { + "object": "list", + "data": [ + { + "id": "asst_abc123", + "object": "assistant", + "created_at": 1698982736, + "name": "Coding Tutor", + "description": null, + "model": "gpt-4o", + "instructions": "You are a helpful assistant designed to make me better at coding!", + "tools": [], + "tool_resources": {}, + "metadata": {}, + "top_p": 1.0, + "temperature": 1.0, + "response_format": "auto" + }, + { + "id": "asst_abc456", + "object": "assistant", + "created_at": 1698982718, + "name": "My Assistant", + "description": null, + "model": "gpt-4o", + "instructions": "You are a helpful assistant designed to make me better at coding!", + "tools": [], + "tool_resources": {}, + "metadata": {}, + "top_p": 1.0, + "temperature": 1.0, + "response_format": "auto" + }, + { + "id": "asst_abc789", + "object": "assistant", + "created_at": 1698982643, + "name": null, + "description": null, + "model": "gpt-4o", + "instructions": null, + "tools": [], + "tool_resources": {}, + "metadata": {}, + "top_p": 1.0, + "temperature": 1.0, + "response_format": "auto" + } + ], + "first_id": "asst_abc123", + "last_id": "asst_abc789", + "has_more": false + } + ListAuditLogsResponse: + type: object + properties: + object: + type: string + enum: + - list + x-stainless-const: true + data: + type: array + items: + $ref: "#/components/schemas/AuditLog" + first_id: + type: string + example: audit_log-defb456h8dks + last_id: + type: string + example: audit_log-hnbkd8s93s + has_more: + type: boolean + required: + - object + - data + - first_id + - last_id + - has_more + ListBatchesResponse: + type: object + properties: + data: + type: array + items: + $ref: "#/components/schemas/Batch" + first_id: + type: string + example: batch_abc123 + last_id: + type: string + example: batch_abc456 + has_more: + type: boolean + object: + type: string + enum: + - list + x-stainless-const: true + required: + - object + - data + - has_more + ListCertificatesResponse: + type: object + properties: + data: + type: array + items: + $ref: "#/components/schemas/Certificate" + first_id: + type: string + example: cert_abc + last_id: + type: string + example: cert_abc + has_more: + type: boolean + object: + type: string + enum: + - list + x-stainless-const: true + required: + - object + - data + - has_more + ListFilesResponse: + type: object + properties: + object: + type: string + example: list + data: + type: array + items: + $ref: "#/components/schemas/OpenAIFile" + first_id: + type: string + example: file-abc123 + last_id: + type: string + example: file-abc456 + has_more: + type: boolean + example: false + required: + - object + - data + - first_id + - last_id + - has_more + ListFineTuningCheckpointPermissionResponse: + type: object + properties: + data: + type: array + items: + $ref: "#/components/schemas/FineTuningCheckpointPermission" + object: + type: string + enum: + - list + x-stainless-const: true + first_id: + type: string + nullable: true + last_id: + type: string + nullable: true + has_more: + type: boolean + required: + - object + - data + - has_more + ListFineTuningJobCheckpointsResponse: + type: object + properties: + data: + type: array + items: + $ref: "#/components/schemas/FineTuningJobCheckpoint" + object: + type: string + enum: + - list + x-stainless-const: true + first_id: + type: string + nullable: true + last_id: + type: string + nullable: true + has_more: + type: boolean + required: + - object + - data + - has_more + ListFineTuningJobEventsResponse: + type: object + properties: + data: + type: array + items: + $ref: "#/components/schemas/FineTuningJobEvent" + object: + type: string + enum: + - list + x-stainless-const: true + has_more: + type: boolean + required: + - object + - data + - has_more + ListMessagesResponse: + properties: + object: + type: string + example: list + data: + type: array + items: + $ref: "#/components/schemas/MessageObject" + first_id: + type: string + example: msg_abc123 + last_id: + type: string + example: msg_abc123 + has_more: + type: boolean + example: false + required: + - object + - data + - first_id + - last_id + - has_more + ListModelsResponse: + type: object + properties: + object: + type: string + enum: + - list + x-stainless-const: true + data: + type: array + items: + $ref: "#/components/schemas/Model" + required: + - object + - data + ListPaginatedFineTuningJobsResponse: + type: object + properties: + data: + type: array + items: + $ref: "#/components/schemas/FineTuningJob" + has_more: + type: boolean + object: + type: string + enum: + - list + x-stainless-const: true + required: + - object + - data + - has_more + ListRunStepsResponse: + properties: + object: + type: string + example: list + data: + type: array + items: + $ref: "#/components/schemas/RunStepObject" + first_id: + type: string + example: step_abc123 + last_id: + type: string + example: step_abc456 + has_more: + type: boolean + example: false + required: + - object + - data + - first_id + - last_id + - has_more + ListRunsResponse: + type: object + properties: + object: + type: string + example: list + data: + type: array + items: + $ref: "#/components/schemas/RunObject" + first_id: + type: string + example: run_abc123 + last_id: + type: string + example: run_abc456 + has_more: + type: boolean + example: false + required: + - object + - data + - first_id + - last_id + - has_more + ListVectorStoreFilesResponse: + properties: + object: + type: string + example: list + data: + type: array + items: + $ref: "#/components/schemas/VectorStoreFileObject" + first_id: + type: string + example: file-abc123 + last_id: + type: string + example: file-abc456 + has_more: + type: boolean + example: false + required: + - object + - data + - first_id + - last_id + - has_more + ListVectorStoresResponse: + properties: + object: + type: string + example: list + data: + type: array + items: + $ref: "#/components/schemas/VectorStoreObject" + first_id: + type: string + example: vs_abc123 + last_id: + type: string + example: vs_abc456 + has_more: + type: boolean + example: false + required: + - object + - data + - first_id + - last_id + - has_more + LogProbProperties: + type: object + description: | + A log probability object. + properties: + token: + type: string + description: | + The token that was used to generate the log probability. + logprob: + type: number + description: | + The log probability of the token. + bytes: + type: array + items: + type: integer + description: | + The bytes that were used to generate the log probability. + required: + - token + - logprob + - bytes + MessageContentImageFileObject: + title: Image file + type: object + description: References an image [File](/docs/api-reference/files) in the + content of a message. + properties: + type: + description: Always `image_file`. + type: string + enum: + - image_file + x-stainless-const: true + image_file: + type: object + properties: + file_id: + description: The [File](/docs/api-reference/files) ID of the image in the + message content. Set `purpose="vision"` when uploading the File + if you need to later display the file content. + type: string + detail: + type: string + description: Specifies the detail level of the image if specified by the user. + `low` uses fewer tokens, you can opt in to high resolution using + `high`. + enum: + - auto + - low + - high + default: auto + required: + - file_id + required: + - type + - image_file + MessageContentImageUrlObject: + title: Image URL + type: object + description: References an image URL in the content of a message. + properties: + type: + type: string + enum: + - image_url + description: The type of the content part. + x-stainless-const: true + image_url: + type: object + properties: + url: + type: string + description: "The external URL of the image, must be a supported image types: + jpeg, jpg, png, gif, webp." + format: uri + detail: + type: string + description: Specifies the detail level of the image. `low` uses fewer tokens, + you can opt in to high resolution using `high`. Default value is + `auto` + enum: + - auto + - low + - high + default: auto + required: + - url + required: + - type + - image_url + MessageContentRefusalObject: + title: Refusal + type: object + description: The refusal content generated by the assistant. + properties: + type: + description: Always `refusal`. + type: string + enum: + - refusal + x-stainless-const: true + refusal: + type: string + nullable: false + required: + - type + - refusal + MessageContentTextAnnotationsFileCitationObject: + title: File citation + type: object + description: A citation within the message that points to a specific quote from + a specific File associated with the assistant or the message. Generated + when the assistant uses the "file_search" tool to search files. + properties: + type: + description: Always `file_citation`. + type: string + enum: + - file_citation + x-stainless-const: true + text: + description: The text in the message content that needs to be replaced. + type: string + file_citation: + type: object + properties: + file_id: + description: The ID of the specific File the citation is from. + type: string + required: + - file_id + start_index: + type: integer + minimum: 0 + end_index: + type: integer + minimum: 0 + required: + - type + - text + - file_citation + - start_index + - end_index + MessageContentTextAnnotationsFilePathObject: + title: File path + type: object + description: A URL for the file that's generated when the assistant used the + `code_interpreter` tool to generate a file. + properties: + type: + description: Always `file_path`. + type: string + enum: + - file_path + x-stainless-const: true + text: + description: The text in the message content that needs to be replaced. + type: string + file_path: + type: object + properties: + file_id: + description: The ID of the file that was generated. + type: string + required: + - file_id + start_index: + type: integer + minimum: 0 + end_index: + type: integer + minimum: 0 + required: + - type + - text + - file_path + - start_index + - end_index + MessageContentTextObject: + title: Text + type: object + description: The text content that is part of a message. + properties: + type: + description: Always `text`. + type: string + enum: + - text + x-stainless-const: true + text: + type: object + properties: + value: + description: The data that makes up the text. + type: string + annotations: + type: array + items: + oneOf: + - $ref: "#/components/schemas/MessageContentTextAnnotationsFileCitationObject" + - $ref: "#/components/schemas/MessageContentTextAnnotationsFilePathObject" + required: + - value + - annotations + required: + - type + - text + MessageDeltaContentImageFileObject: + title: Image file + type: object + description: References an image [File](/docs/api-reference/files) in the + content of a message. + properties: + index: + type: integer + description: The index of the content part in the message. + type: + description: Always `image_file`. + type: string + enum: + - image_file + x-stainless-const: true + image_file: + type: object + properties: + file_id: + description: The [File](/docs/api-reference/files) ID of the image in the + message content. Set `purpose="vision"` when uploading the File + if you need to later display the file content. + type: string + detail: + type: string + description: Specifies the detail level of the image if specified by the user. + `low` uses fewer tokens, you can opt in to high resolution using + `high`. + enum: + - auto + - low + - high + default: auto + required: + - index + - type + MessageDeltaContentImageUrlObject: + title: Image URL + type: object + description: References an image URL in the content of a message. + properties: + index: + type: integer + description: The index of the content part in the message. + type: + description: Always `image_url`. + type: string + enum: + - image_url + x-stainless-const: true + image_url: + type: object + properties: + url: + description: "The URL of the image, must be a supported image types: jpeg, jpg, + png, gif, webp." + type: string + detail: + type: string + description: Specifies the detail level of the image. `low` uses fewer tokens, + you can opt in to high resolution using `high`. + enum: + - auto + - low + - high + default: auto + required: + - index + - type + MessageDeltaContentRefusalObject: + title: Refusal + type: object + description: The refusal content that is part of a message. + properties: + index: + type: integer + description: The index of the refusal part in the message. + type: + description: Always `refusal`. + type: string + enum: + - refusal + x-stainless-const: true + refusal: + type: string + required: + - index + - type + MessageDeltaContentTextAnnotationsFileCitationObject: + title: File citation + type: object + description: A citation within the message that points to a specific quote from + a specific File associated with the assistant or the message. Generated + when the assistant uses the "file_search" tool to search files. + properties: + index: + type: integer + description: The index of the annotation in the text content part. + type: + description: Always `file_citation`. + type: string + enum: + - file_citation + x-stainless-const: true + text: + description: The text in the message content that needs to be replaced. + type: string + file_citation: + type: object + properties: + file_id: + description: The ID of the specific File the citation is from. + type: string + quote: + description: The specific quote in the file. + type: string + start_index: + type: integer + minimum: 0 + end_index: + type: integer + minimum: 0 + required: + - index + - type + MessageDeltaContentTextAnnotationsFilePathObject: + title: File path + type: object + description: A URL for the file that's generated when the assistant used the + `code_interpreter` tool to generate a file. + properties: + index: + type: integer + description: The index of the annotation in the text content part. + type: + description: Always `file_path`. + type: string + enum: + - file_path + x-stainless-const: true + text: + description: The text in the message content that needs to be replaced. + type: string + file_path: + type: object + properties: + file_id: + description: The ID of the file that was generated. + type: string + start_index: + type: integer + minimum: 0 + end_index: + type: integer + minimum: 0 + required: + - index + - type + MessageDeltaContentTextObject: + title: Text + type: object + description: The text content that is part of a message. + properties: + index: + type: integer + description: The index of the content part in the message. + type: + description: Always `text`. + type: string + enum: + - text + x-stainless-const: true + text: + type: object + properties: + value: + description: The data that makes up the text. + type: string + annotations: + type: array + items: + oneOf: + - $ref: "#/components/schemas/MessageDeltaContentTextAnnotationsFileCitationObject" + - $ref: "#/components/schemas/MessageDeltaContentTextAnnotationsFilePathObject" + required: + - index + - type + MessageDeltaObject: + type: object + title: Message delta object + description: > + Represents a message delta i.e. any changed fields on a message during + streaming. + properties: + id: + description: The identifier of the message, which can be referenced in API + endpoints. + type: string + object: + description: The object type, which is always `thread.message.delta`. + type: string + enum: + - thread.message.delta + x-stainless-const: true + delta: + description: The delta containing the fields that have changed on the Message. + type: object + properties: + role: + description: The entity that produced the message. One of `user` or `assistant`. + type: string + enum: + - user + - assistant + content: + description: The content of the message in array of text and/or images. + type: array + items: + oneOf: + - $ref: "#/components/schemas/MessageDeltaContentImageFileObject" + - $ref: "#/components/schemas/MessageDeltaContentTextObject" + - $ref: "#/components/schemas/MessageDeltaContentRefusalObject" + - $ref: "#/components/schemas/MessageDeltaContentImageUrlObject" + required: + - id + - object + - delta + x-oaiMeta: + name: The message delta object + beta: true + example: | + { + "id": "msg_123", + "object": "thread.message.delta", + "delta": { + "content": [ + { + "index": 0, + "type": "text", + "text": { "value": "Hello", "annotations": [] } + } + ] + } + } + MessageObject: + type: object + title: The message object + description: Represents a message within a [thread](/docs/api-reference/threads). + properties: + id: + description: The identifier, which can be referenced in API endpoints. + type: string + object: + description: The object type, which is always `thread.message`. + type: string + enum: + - thread.message + x-stainless-const: true + created_at: + description: The Unix timestamp (in seconds) for when the message was created. + type: integer + thread_id: + description: The [thread](/docs/api-reference/threads) ID that this message + belongs to. + type: string + status: + description: The status of the message, which can be either `in_progress`, + `incomplete`, or `completed`. + type: string + enum: + - in_progress + - incomplete + - completed + incomplete_details: + description: On an incomplete message, details about why the message is + incomplete. + type: object + properties: + reason: + type: string + description: The reason the message is incomplete. + enum: + - content_filter + - max_tokens + - run_cancelled + - run_expired + - run_failed + nullable: true + required: + - reason + completed_at: + description: The Unix timestamp (in seconds) for when the message was completed. + type: integer + nullable: true + incomplete_at: + description: The Unix timestamp (in seconds) for when the message was marked as + incomplete. + type: integer + nullable: true + role: + description: The entity that produced the message. One of `user` or `assistant`. + type: string + enum: + - user + - assistant + content: + description: The content of the message in array of text and/or images. + type: array + items: + oneOf: + - $ref: "#/components/schemas/MessageContentImageFileObject" + - $ref: "#/components/schemas/MessageContentImageUrlObject" + - $ref: "#/components/schemas/MessageContentTextObject" + - $ref: "#/components/schemas/MessageContentRefusalObject" + assistant_id: + description: If applicable, the ID of the + [assistant](/docs/api-reference/assistants) that authored this + message. + type: string + nullable: true + run_id: + description: The ID of the [run](/docs/api-reference/runs) associated with the + creation of this message. Value is `null` when messages are created + manually using the create message or create thread endpoints. + type: string + nullable: true + attachments: + type: array + items: + type: object + properties: + file_id: + type: string + description: The ID of the file to attach to the message. + tools: + description: The tools to add this file to. + type: array + items: + oneOf: + - $ref: "#/components/schemas/AssistantToolsCode" + - $ref: "#/components/schemas/AssistantToolsFileSearchTypeOnly" + description: A list of files attached to the message, and the tools they were + added to. + nullable: true + metadata: + $ref: "#/components/schemas/Metadata" + required: + - id + - object + - created_at + - thread_id + - status + - incomplete_details + - completed_at + - incomplete_at + - role + - content + - assistant_id + - run_id + - attachments + - metadata + x-oaiMeta: + name: The message object + beta: true + example: | + { + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1698983503, + "thread_id": "thread_abc123", + "role": "assistant", + "content": [ + { + "type": "text", + "text": { + "value": "Hi! How can I help you today?", + "annotations": [] + } + } + ], + "assistant_id": "asst_abc123", + "run_id": "run_abc123", + "attachments": [], + "metadata": {} + } + MessageRequestContentTextObject: + title: Text + type: object + description: The text content that is part of a message. + properties: + type: + description: Always `text`. + type: string + enum: + - text + x-stainless-const: true + text: + type: string + description: Text content to be sent to the model + required: + - type + - text + MessageStreamEvent: + oneOf: + - type: object + properties: + event: + type: string + enum: + - thread.message.created + x-stainless-const: true + data: + $ref: "#/components/schemas/MessageObject" + required: + - event + - data + description: Occurs when a [message](/docs/api-reference/messages/object) is + created. + x-oaiMeta: + dataDescription: "`data` is a [message](/docs/api-reference/messages/object)" + - type: object + properties: + event: + type: string + enum: + - thread.message.in_progress + x-stainless-const: true + data: + $ref: "#/components/schemas/MessageObject" + required: + - event + - data + description: Occurs when a [message](/docs/api-reference/messages/object) moves + to an `in_progress` state. + x-oaiMeta: + dataDescription: "`data` is a [message](/docs/api-reference/messages/object)" + - type: object + properties: + event: + type: string + enum: + - thread.message.delta + x-stainless-const: true + data: + $ref: "#/components/schemas/MessageDeltaObject" + required: + - event + - data + description: Occurs when parts of a + [Message](/docs/api-reference/messages/object) are being streamed. + x-oaiMeta: + dataDescription: "`data` is a [message + delta](/docs/api-reference/assistants-streaming/message-delta-obj\ + ect)" + - type: object + properties: + event: + type: string + enum: + - thread.message.completed + x-stainless-const: true + data: + $ref: "#/components/schemas/MessageObject" + required: + - event + - data + description: Occurs when a [message](/docs/api-reference/messages/object) is + completed. + x-oaiMeta: + dataDescription: "`data` is a [message](/docs/api-reference/messages/object)" + - type: object + properties: + event: + type: string + enum: + - thread.message.incomplete + x-stainless-const: true + data: + $ref: "#/components/schemas/MessageObject" + required: + - event + - data + description: Occurs when a [message](/docs/api-reference/messages/object) ends + before it is completed. + x-oaiMeta: + dataDescription: "`data` is a [message](/docs/api-reference/messages/object)" + Metadata: + type: object + description: > + Set of 16 key-value pairs that can be attached to an object. This can be + + useful for storing additional information about the object in a + structured + + format, and querying for objects via API or the dashboard. + + + Keys are strings with a maximum length of 64 characters. Values are + strings + + with a maximum length of 512 characters. + additionalProperties: + type: string + x-oaiTypeLabel: map + nullable: true + Model: + title: Model + description: Describes an OpenAI model offering that can be used with the API. + properties: + id: + type: string + description: The model identifier, which can be referenced in the API endpoints. + created: + type: integer + description: The Unix timestamp (in seconds) when the model was created. + object: + type: string + description: The object type, which is always "model". + enum: + - model + x-stainless-const: true + owned_by: + type: string + description: The organization that owns the model. + required: + - id + - object + - created + - owned_by + x-oaiMeta: + name: The model object + example: | + { + "id": "VAR_chat_model_id", + "object": "model", + "created": 1686935002, + "owned_by": "openai" + } + ModelIds: + anyOf: + - $ref: "#/components/schemas/ModelIdsShared" + - $ref: "#/components/schemas/ModelIdsResponses" + ModelIdsResponses: + example: gpt-4o + anyOf: + - $ref: "#/components/schemas/ModelIdsShared" + - type: string + title: ResponsesOnlyModel + enum: + - o1-pro + - o1-pro-2025-03-19 + - computer-use-preview + - computer-use-preview-2025-03-11 + ModelIdsShared: + example: gpt-4o + anyOf: + - type: string + - type: string + enum: + - gpt-4.1 + - gpt-4.1-mini + - gpt-4.1-nano + - gpt-4.1-2025-04-14 + - gpt-4.1-mini-2025-04-14 + - gpt-4.1-nano-2025-04-14 + - o4-mini + - o4-mini-2025-04-16 + - o3 + - o3-2025-04-16 + - o3-mini + - o3-mini-2025-01-31 + - o1 + - o1-2024-12-17 + - o1-preview + - o1-preview-2024-09-12 + - o1-mini + - o1-mini-2024-09-12 + - gpt-4o + - gpt-4o-2024-11-20 + - gpt-4o-2024-08-06 + - gpt-4o-2024-05-13 + - gpt-4o-audio-preview + - gpt-4o-audio-preview-2024-10-01 + - gpt-4o-audio-preview-2024-12-17 + - gpt-4o-mini-audio-preview + - gpt-4o-mini-audio-preview-2024-12-17 + - gpt-4o-search-preview + - gpt-4o-mini-search-preview + - gpt-4o-search-preview-2025-03-11 + - gpt-4o-mini-search-preview-2025-03-11 + - chatgpt-4o-latest + - gpt-4o-mini + - gpt-4o-mini-2024-07-18 + - gpt-4-turbo + - gpt-4-turbo-2024-04-09 + - gpt-4-0125-preview + - gpt-4-turbo-preview + - gpt-4-1106-preview + - gpt-4-vision-preview + - gpt-4 + - gpt-4-0314 + - gpt-4-0613 + - gpt-4-32k + - gpt-4-32k-0314 + - gpt-4-32k-0613 + - gpt-3.5-turbo + - gpt-3.5-turbo-16k + - gpt-3.5-turbo-0301 + - gpt-3.5-turbo-0613 + - gpt-3.5-turbo-1106 + - gpt-3.5-turbo-0125 + - gpt-3.5-turbo-16k-0613 + ModelResponseProperties: + type: object + properties: + metadata: + $ref: "#/components/schemas/Metadata" + temperature: + type: number + minimum: 0 + maximum: 2 + default: 1 + example: 1 + nullable: true + description: > + What sampling temperature to use, between 0 and 2. Higher values + like 0.8 will make the output more random, while lower values like + 0.2 will make it more focused and deterministic. + + We generally recommend altering this or `top_p` but not both. + top_p: + type: number + minimum: 0 + maximum: 1 + default: 1 + example: 1 + nullable: true + description: > + An alternative to sampling with temperature, called nucleus + sampling, + + where the model considers the results of the tokens with top_p + probability + + mass. So 0.1 means only the tokens comprising the top 10% + probability mass + + are considered. + + + We generally recommend altering this or `temperature` but not both. + user: + type: string + example: user-1234 + description: > + A unique identifier representing your end-user, which can help + OpenAI to monitor and detect abuse. [Learn + more](/docs/guides/safety-best-practices#end-user-ids). + service_tier: + $ref: "#/components/schemas/ServiceTier" + ModifyAssistantRequest: + type: object + additionalProperties: false + properties: + model: + description: > + ID of the model to use. You can use the [List + models](/docs/api-reference/models/list) API to see all of your + available models, or see our [Model overview](/docs/models) for + descriptions of them. + anyOf: + - type: string + - $ref: "#/components/schemas/AssistantSupportedModels" + reasoning_effort: + $ref: "#/components/schemas/ReasoningEffort" + name: + description: | + The name of the assistant. The maximum length is 256 characters. + type: string + nullable: true + maxLength: 256 + description: + description: > + The description of the assistant. The maximum length is 512 + characters. + type: string + nullable: true + maxLength: 512 + instructions: + description: > + The system instructions that the assistant uses. The maximum length + is 256,000 characters. + type: string + nullable: true + maxLength: 256000 + tools: + description: > + A list of tool enabled on the assistant. There can be a maximum of + 128 tools per assistant. Tools can be of types `code_interpreter`, + `file_search`, or `function`. + default: [] + type: array + maxItems: 128 + items: + oneOf: + - $ref: "#/components/schemas/AssistantToolsCode" + - $ref: "#/components/schemas/AssistantToolsFileSearch" + - $ref: "#/components/schemas/AssistantToolsFunction" + tool_resources: + type: object + description: > + A set of resources that are used by the assistant's tools. The + resources are specific to the type of tool. For example, the + `code_interpreter` tool requires a list of file IDs, while the + `file_search` tool requires a list of vector store IDs. + properties: + code_interpreter: + type: object + properties: + file_ids: + type: array + description: > + Overrides the list of [file](/docs/api-reference/files) IDs + made available to the `code_interpreter` tool. There can be + a maximum of 20 files associated with the tool. + default: [] + maxItems: 20 + items: + type: string + file_search: + type: object + properties: + vector_store_ids: + type: array + description: > + Overrides the [vector + store](/docs/api-reference/vector-stores/object) attached to + this assistant. There can be a maximum of 1 vector store + attached to the assistant. + maxItems: 1 + items: + type: string + nullable: true + metadata: + $ref: "#/components/schemas/Metadata" + temperature: + description: > + What sampling temperature to use, between 0 and 2. Higher values + like 0.8 will make the output more random, while lower values like + 0.2 will make it more focused and deterministic. + type: number + minimum: 0 + maximum: 2 + default: 1 + example: 1 + nullable: true + top_p: + type: number + minimum: 0 + maximum: 1 + default: 1 + example: 1 + nullable: true + description: > + An alternative to sampling with temperature, called nucleus + sampling, where the model considers the results of the tokens with + top_p probability mass. So 0.1 means only the tokens comprising the + top 10% probability mass are considered. + + + We generally recommend altering this or temperature but not both. + response_format: + $ref: "#/components/schemas/AssistantsApiResponseFormatOption" + nullable: true + ModifyCertificateRequest: + type: object + properties: + name: + type: string + description: The updated name for the certificate + required: + - name + ModifyMessageRequest: + type: object + additionalProperties: false + properties: + metadata: + $ref: "#/components/schemas/Metadata" + ModifyRunRequest: + type: object + additionalProperties: false + properties: + metadata: + $ref: "#/components/schemas/Metadata" + ModifyThreadRequest: + type: object + additionalProperties: false + properties: + tool_resources: + type: object + description: > + A set of resources that are made available to the assistant's tools + in this thread. The resources are specific to the type of tool. For + example, the `code_interpreter` tool requires a list of file IDs, + while the `file_search` tool requires a list of vector store IDs. + properties: + code_interpreter: + type: object + properties: + file_ids: + type: array + description: > + A list of [file](/docs/api-reference/files) IDs made + available to the `code_interpreter` tool. There can be a + maximum of 20 files associated with the tool. + default: [] + maxItems: 20 + items: + type: string + file_search: + type: object + properties: + vector_store_ids: + type: array + description: > + The [vector store](/docs/api-reference/vector-stores/object) + attached to this thread. There can be a maximum of 1 vector + store attached to the thread. + maxItems: 1 + items: + type: string + nullable: true + metadata: + $ref: "#/components/schemas/Metadata" + Move: + type: object + title: Move + description: | + A mouse move action. + properties: + type: + type: string + enum: + - move + default: move + description: | + Specifies the event type. For a move action, this property is + always set to `move`. + x-stainless-const: true + x: + type: integer + description: | + The x-coordinate to move to. + y: + type: integer + description: | + The y-coordinate to move to. + required: + - type + - x + - y + OpenAIFile: + title: OpenAIFile + description: The `File` object represents a document that has been uploaded to OpenAI. + properties: + id: + type: string + description: The file identifier, which can be referenced in the API endpoints. + bytes: + type: integer + description: The size of the file, in bytes. + created_at: + type: integer + description: The Unix timestamp (in seconds) for when the file was created. + expires_at: + type: integer + description: The Unix timestamp (in seconds) for when the file will expire. + filename: + type: string + description: The name of the file. + object: + type: string + description: The object type, which is always `file`. + enum: + - file + x-stainless-const: true + purpose: + type: string + description: The intended purpose of the file. Supported values are + `assistants`, `assistants_output`, `batch`, `batch_output`, + `fine-tune`, `fine-tune-results` and `vision`. + enum: + - assistants + - assistants_output + - batch + - batch_output + - fine-tune + - fine-tune-results + - vision + status: + type: string + deprecated: true + description: Deprecated. The current status of the file, which can be either + `uploaded`, `processed`, or `error`. + enum: + - uploaded + - processed + - error + status_details: + type: string + deprecated: true + description: Deprecated. For details on why a fine-tuning training file failed + validation, see the `error` field on `fine_tuning.job`. + required: + - id + - object + - bytes + - created_at + - filename + - purpose + - status + x-oaiMeta: + name: The file object + example: | + { + "id": "file-abc123", + "object": "file", + "bytes": 120000, + "created_at": 1677610602, + "expires_at": 1680202602, + "filename": "salesOverview.pdf", + "purpose": "assistants", + } + OtherChunkingStrategyResponseParam: + type: object + title: Other Chunking Strategy + description: This is returned when the chunking strategy is unknown. Typically, + this is because the file was indexed before the `chunking_strategy` + concept was introduced in the API. + additionalProperties: false + properties: + type: + type: string + description: Always `other`. + enum: + - other + x-stainless-const: true + required: + - type + OutputAudio: + type: object + title: Output audio + description: | + An audio output from the model. + properties: + type: + type: string + description: | + The type of the output audio. Always `output_audio`. + enum: + - output_audio + x-stainless-const: true + data: + type: string + description: | + Base64-encoded audio data from the model. + transcript: + type: string + description: | + The transcript of the audio data from the model. + required: + - type + - data + - transcript + OutputContent: + oneOf: + - $ref: "#/components/schemas/OutputTextContent" + - $ref: "#/components/schemas/RefusalContent" + OutputItem: + anyOf: + - $ref: "#/components/schemas/OutputMessage" + - $ref: "#/components/schemas/FileSearchToolCall" + - $ref: "#/components/schemas/FunctionToolCall" + - $ref: "#/components/schemas/WebSearchToolCall" + - $ref: "#/components/schemas/ComputerToolCall" + - $ref: "#/components/schemas/ReasoningItem" + discriminator: + propertyName: type + OutputMessage: + type: object + title: Output message + description: | + An output message from the model. + properties: + id: + type: string + description: | + The unique ID of the output message. + type: + type: string + description: | + The type of the output message. Always `message`. + enum: + - message + x-stainless-const: true + role: + type: string + description: | + The role of the output message. Always `assistant`. + enum: + - assistant + x-stainless-const: true + content: + type: array + description: | + The content of the output message. + items: + $ref: "#/components/schemas/OutputContent" + status: + type: string + description: > + The status of the message input. One of `in_progress`, `completed`, + or + + `incomplete`. Populated when input items are returned via API. + enum: + - in_progress + - completed + - incomplete + required: + - id + - type + - role + - content + - status + ParallelToolCalls: + description: Whether to enable [parallel function + calling](/docs/guides/function-calling#configuring-parallel-function-calling) + during tool use. + type: boolean + default: true + PredictionContent: + type: object + title: Static Content + description: > + Static predicted output content, such as the content of a text file that + is + + being regenerated. + required: + - type + - content + properties: + type: + type: string + enum: + - content + description: | + The type of the predicted content you want to provide. This type is + currently always `content`. + x-stainless-const: true + content: + description: > + The content that should be matched when generating a model response. + + If generated tokens would match this content, the entire model + response + + can be returned much more quickly. + oneOf: + - type: string + title: Text content + description: | + The content used for a Predicted Output. This is often the + text of a file you are regenerating with minor changes. + - type: array + description: An array of content parts with a defined type. Supported options + differ based on the [model](/docs/models) being used to generate + the response. Can contain text inputs. + title: Array of content parts + items: + $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartText" + minItems: 1 + Project: + type: object + description: Represents an individual project. + properties: + id: + type: string + description: The identifier, which can be referenced in API endpoints + object: + type: string + enum: + - organization.project + description: The object type, which is always `organization.project` + x-stainless-const: true + name: + type: string + description: The name of the project. This appears in reporting. + created_at: + type: integer + description: The Unix timestamp (in seconds) of when the project was created. + archived_at: + type: integer + nullable: true + description: The Unix timestamp (in seconds) of when the project was archived or + `null`. + status: + type: string + enum: + - active + - archived + description: "`active` or `archived`" + required: + - id + - object + - name + - created_at + - status + x-oaiMeta: + name: The project object + example: | + { + "id": "proj_abc", + "object": "organization.project", + "name": "Project example", + "created_at": 1711471533, + "archived_at": null, + "status": "active" + } + ProjectApiKey: + type: object + description: Represents an individual API key in a project. + properties: + object: + type: string + enum: + - organization.project.api_key + description: The object type, which is always `organization.project.api_key` + x-stainless-const: true + redacted_value: + type: string + description: The redacted value of the API key + name: + type: string + description: The name of the API key + created_at: + type: integer + description: The Unix timestamp (in seconds) of when the API key was created + last_used_at: + type: integer + description: The Unix timestamp (in seconds) of when the API key was last used. + id: + type: string + description: The identifier, which can be referenced in API endpoints + owner: + type: object + properties: + type: + type: string + enum: + - user + - service_account + description: "`user` or `service_account`" + user: + $ref: "#/components/schemas/ProjectUser" + service_account: + $ref: "#/components/schemas/ProjectServiceAccount" + required: + - object + - redacted_value + - name + - created_at + - last_used_at + - id + - owner + x-oaiMeta: + name: The project API key object + example: | + { + "object": "organization.project.api_key", + "redacted_value": "sk-abc...def", + "name": "My API Key", + "created_at": 1711471533, + "last_used_at": 1711471534, + "id": "key_abc", + "owner": { + "type": "user", + "user": { + "object": "organization.project.user", + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "created_at": 1711471533 + } + } + } + ProjectApiKeyDeleteResponse: + type: object + properties: + object: + type: string + enum: + - organization.project.api_key.deleted + x-stainless-const: true + id: + type: string + deleted: + type: boolean + required: + - object + - id + - deleted + ProjectApiKeyListResponse: + type: object + properties: + object: + type: string + enum: + - list + x-stainless-const: true + data: + type: array + items: + $ref: "#/components/schemas/ProjectApiKey" + first_id: + type: string + last_id: + type: string + has_more: + type: boolean + required: + - object + - data + - first_id + - last_id + - has_more + ProjectCreateRequest: + type: object + properties: + name: + type: string + description: The friendly name of the project, this name appears in reports. + required: + - name + ProjectListResponse: + type: object + properties: + object: + type: string + enum: + - list + x-stainless-const: true + data: + type: array + items: + $ref: "#/components/schemas/Project" + first_id: + type: string + last_id: + type: string + has_more: + type: boolean + required: + - object + - data + - first_id + - last_id + - has_more + ProjectRateLimit: + type: object + description: Represents a project rate limit config. + properties: + object: + type: string + enum: + - project.rate_limit + description: The object type, which is always `project.rate_limit` + x-stainless-const: true + id: + type: string + description: The identifier, which can be referenced in API endpoints. + model: + type: string + description: The model this rate limit applies to. + max_requests_per_1_minute: + type: integer + description: The maximum requests per minute. + max_tokens_per_1_minute: + type: integer + description: The maximum tokens per minute. + max_images_per_1_minute: + type: integer + description: The maximum images per minute. Only present for relevant models. + max_audio_megabytes_per_1_minute: + type: integer + description: The maximum audio megabytes per minute. Only present for relevant + models. + max_requests_per_1_day: + type: integer + description: The maximum requests per day. Only present for relevant models. + batch_1_day_max_input_tokens: + type: integer + description: The maximum batch input tokens per day. Only present for relevant + models. + required: + - object + - id + - model + - max_requests_per_1_minute + - max_tokens_per_1_minute + x-oaiMeta: + name: The project rate limit object + example: | + { + "object": "project.rate_limit", + "id": "rl_ada", + "model": "ada", + "max_requests_per_1_minute": 600, + "max_tokens_per_1_minute": 150000, + "max_images_per_1_minute": 10 + } + ProjectRateLimitListResponse: + type: object + properties: + object: + type: string + enum: + - list + x-stainless-const: true + data: + type: array + items: + $ref: "#/components/schemas/ProjectRateLimit" + first_id: + type: string + last_id: + type: string + has_more: + type: boolean + required: + - object + - data + - first_id + - last_id + - has_more + ProjectRateLimitUpdateRequest: + type: object + properties: + max_requests_per_1_minute: + type: integer + description: The maximum requests per minute. + max_tokens_per_1_minute: + type: integer + description: The maximum tokens per minute. + max_images_per_1_minute: + type: integer + description: The maximum images per minute. Only relevant for certain models. + max_audio_megabytes_per_1_minute: + type: integer + description: The maximum audio megabytes per minute. Only relevant for certain + models. + max_requests_per_1_day: + type: integer + description: The maximum requests per day. Only relevant for certain models. + batch_1_day_max_input_tokens: + type: integer + description: The maximum batch input tokens per day. Only relevant for certain + models. + ProjectServiceAccount: + type: object + description: Represents an individual service account in a project. + properties: + object: + type: string + enum: + - organization.project.service_account + description: The object type, which is always + `organization.project.service_account` + x-stainless-const: true + id: + type: string + description: The identifier, which can be referenced in API endpoints + name: + type: string + description: The name of the service account + role: + type: string + enum: + - owner + - member + description: "`owner` or `member`" + created_at: + type: integer + description: The Unix timestamp (in seconds) of when the service account was + created + required: + - object + - id + - name + - role + - created_at + x-oaiMeta: + name: The project service account object + example: | + { + "object": "organization.project.service_account", + "id": "svc_acct_abc", + "name": "Service Account", + "role": "owner", + "created_at": 1711471533 + } + ProjectServiceAccountApiKey: + type: object + properties: + object: + type: string + enum: + - organization.project.service_account.api_key + description: The object type, which is always + `organization.project.service_account.api_key` + x-stainless-const: true + value: + type: string + name: + type: string + created_at: + type: integer + id: + type: string + required: + - object + - value + - name + - created_at + - id + ProjectServiceAccountCreateRequest: + type: object + properties: + name: + type: string + description: The name of the service account being created. + required: + - name + ProjectServiceAccountCreateResponse: + type: object + properties: + object: + type: string + enum: + - organization.project.service_account + x-stainless-const: true + id: + type: string + name: + type: string + role: + type: string + enum: + - member + description: Service accounts can only have one role of type `member` + x-stainless-const: true + created_at: + type: integer + api_key: + $ref: "#/components/schemas/ProjectServiceAccountApiKey" + required: + - object + - id + - name + - role + - created_at + - api_key + ProjectServiceAccountDeleteResponse: + type: object + properties: + object: + type: string + enum: + - organization.project.service_account.deleted + x-stainless-const: true + id: + type: string + deleted: + type: boolean + required: + - object + - id + - deleted + ProjectServiceAccountListResponse: + type: object + properties: + object: + type: string + enum: + - list + x-stainless-const: true + data: + type: array + items: + $ref: "#/components/schemas/ProjectServiceAccount" + first_id: + type: string + last_id: + type: string + has_more: + type: boolean + required: + - object + - data + - first_id + - last_id + - has_more + ProjectUpdateRequest: + type: object + properties: + name: + type: string + description: The updated name of the project, this name appears in reports. + required: + - name + ProjectUser: + type: object + description: Represents an individual user in a project. + properties: + object: + type: string + enum: + - organization.project.user + description: The object type, which is always `organization.project.user` + x-stainless-const: true + id: + type: string + description: The identifier, which can be referenced in API endpoints + name: + type: string + description: The name of the user + email: + type: string + description: The email address of the user + role: + type: string + enum: + - owner + - member + description: "`owner` or `member`" + added_at: + type: integer + description: The Unix timestamp (in seconds) of when the project was added. + required: + - object + - id + - name + - email + - role + - added_at + x-oaiMeta: + name: The project user object + example: | + { + "object": "organization.project.user", + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "added_at": 1711471533 + } + ProjectUserCreateRequest: + type: object + properties: + user_id: + type: string + description: The ID of the user. + role: + type: string + enum: + - owner + - member + description: "`owner` or `member`" + required: + - user_id + - role + ProjectUserDeleteResponse: + type: object + properties: + object: + type: string + enum: + - organization.project.user.deleted + x-stainless-const: true + id: + type: string + deleted: + type: boolean + required: + - object + - id + - deleted + ProjectUserListResponse: + type: object + properties: + object: + type: string + data: + type: array + items: + $ref: "#/components/schemas/ProjectUser" + first_id: + type: string + last_id: + type: string + has_more: + type: boolean + required: + - object + - data + - first_id + - last_id + - has_more + ProjectUserUpdateRequest: + type: object + properties: + role: + type: string + enum: + - owner + - member + description: "`owner` or `member`" + required: + - role + RealtimeClientEvent: + discriminator: + propertyName: type + description: | + A realtime client event. + anyOf: + - $ref: "#/components/schemas/RealtimeClientEventConversationItemCreate" + - $ref: "#/components/schemas/RealtimeClientEventConversationItemDelete" + - $ref: "#/components/schemas/RealtimeClientEventConversationItemRetrieve" + - $ref: "#/components/schemas/RealtimeClientEventConversationItemTruncate" + - $ref: "#/components/schemas/RealtimeClientEventInputAudioBufferAppend" + - $ref: "#/components/schemas/RealtimeClientEventInputAudioBufferClear" + - $ref: "#/components/schemas/RealtimeClientEventOutputAudioBufferClear" + - $ref: "#/components/schemas/RealtimeClientEventInputAudioBufferCommit" + - $ref: "#/components/schemas/RealtimeClientEventResponseCancel" + - $ref: "#/components/schemas/RealtimeClientEventResponseCreate" + - $ref: "#/components/schemas/RealtimeClientEventSessionUpdate" + - $ref: "#/components/schemas/RealtimeClientEventTranscriptionSessionUpdate" + RealtimeClientEventConversationItemCreate: + type: object + description: > + Add a new Item to the Conversation's context, including messages, + function + + calls, and function call responses. This event can be used both to + populate a + + "history" of the conversation and to add new items mid-stream, but has + the + + current limitation that it cannot populate assistant audio messages. + + + If successful, the server will respond with a + `conversation.item.created` + + event, otherwise an `error` event will be sent. + properties: + event_id: + type: string + description: Optional client-generated ID used to identify this event. + type: + type: string + enum: + - conversation.item.create + description: The event type, must be `conversation.item.create`. + x-stainless-const: true + previous_item_id: + type: string + description: > + The ID of the preceding item after which the new item will be + inserted. + + If not set, the new item will be appended to the end of the + conversation. + + If set to `root`, the new item will be added to the beginning of the + conversation. + + If set to an existing ID, it allows an item to be inserted + mid-conversation. If the + + ID cannot be found, an error will be returned and the item will not + be added. + item: + $ref: "#/components/schemas/RealtimeConversationItem" + required: + - type + - item + x-oaiMeta: + name: conversation.item.create + group: realtime + example: | + { + "event_id": "event_345", + "type": "conversation.item.create", + "previous_item_id": null, + "item": { + "id": "msg_001", + "type": "message", + "role": "user", + "content": [ + { + "type": "input_text", + "text": "Hello, how are you?" + } + ] + } + } + RealtimeClientEventConversationItemDelete: + type: object + description: > + Send this event when you want to remove any item from the conversation + + history. The server will respond with a `conversation.item.deleted` + event, + + unless the item does not exist in the conversation history, in which + case the + + server will respond with an error. + properties: + event_id: + type: string + description: Optional client-generated ID used to identify this event. + type: + type: string + enum: + - conversation.item.delete + description: The event type, must be `conversation.item.delete`. + x-stainless-const: true + item_id: + type: string + description: The ID of the item to delete. + required: + - type + - item_id + x-oaiMeta: + name: conversation.item.delete + group: realtime + example: | + { + "event_id": "event_901", + "type": "conversation.item.delete", + "item_id": "msg_003" + } + RealtimeClientEventConversationItemRetrieve: + type: object + description: > + Send this event when you want to retrieve the server's representation of + a specific item in the conversation history. This is useful, for + example, to inspect user audio after noise cancellation and VAD. + + The server will respond with a `conversation.item.retrieved` event, + + unless the item does not exist in the conversation history, in which + case the + + server will respond with an error. + properties: + event_id: + type: string + description: Optional client-generated ID used to identify this event. + type: + type: string + enum: + - conversation.item.retrieve + description: The event type, must be `conversation.item.retrieve`. + x-stainless-const: true + item_id: + type: string + description: The ID of the item to retrieve. + required: + - type + - item_id + x-oaiMeta: + name: conversation.item.retrieve + group: realtime + example: | + { + "event_id": "event_901", + "type": "conversation.item.retrieve", + "item_id": "msg_003" + } + RealtimeClientEventConversationItemTruncate: + type: object + description: > + Send this event to truncate a previous assistant message’s audio. The + server + + will produce audio faster than realtime, so this event is useful when + the user + + interrupts to truncate audio that has already been sent to the client + but not + + yet played. This will synchronize the server's understanding of the + audio with + + the client's playback. + + + Truncating audio will delete the server-side text transcript to ensure + there + + is not text in the context that hasn't been heard by the user. + + + If successful, the server will respond with a + `conversation.item.truncated` + + event. + properties: + event_id: + type: string + description: Optional client-generated ID used to identify this event. + type: + type: string + enum: + - conversation.item.truncate + description: The event type, must be `conversation.item.truncate`. + x-stainless-const: true + item_id: + type: string + description: > + The ID of the assistant message item to truncate. Only assistant + message + + items can be truncated. + content_index: + type: integer + description: The index of the content part to truncate. Set this to 0. + audio_end_ms: + type: integer + description: > + Inclusive duration up to which audio is truncated, in milliseconds. + If + + the audio_end_ms is greater than the actual audio duration, the + server + + will respond with an error. + required: + - type + - item_id + - content_index + - audio_end_ms + x-oaiMeta: + name: conversation.item.truncate + group: realtime + example: | + { + "event_id": "event_678", + "type": "conversation.item.truncate", + "item_id": "msg_002", + "content_index": 0, + "audio_end_ms": 1500 + } + RealtimeClientEventInputAudioBufferAppend: + type: object + description: > + Send this event to append audio bytes to the input audio buffer. The + audio + + buffer is temporary storage you can write to and later commit. In Server + VAD + + mode, the audio buffer is used to detect speech and the server will + decide + + when to commit. When Server VAD is disabled, you must commit the audio + buffer + + manually. + + + The client may choose how much audio to place in each event up to a + maximum + + of 15 MiB, for example streaming smaller chunks from the client may + allow the + + VAD to be more responsive. Unlike made other client events, the server + will + + not send a confirmation response to this event. + properties: + event_id: + type: string + description: Optional client-generated ID used to identify this event. + type: + type: string + enum: + - input_audio_buffer.append + description: The event type, must be `input_audio_buffer.append`. + x-stainless-const: true + audio: + type: string + description: > + Base64-encoded audio bytes. This must be in the format specified by + the + + `input_audio_format` field in the session configuration. + required: + - type + - audio + x-oaiMeta: + name: input_audio_buffer.append + group: realtime + example: | + { + "event_id": "event_456", + "type": "input_audio_buffer.append", + "audio": "Base64EncodedAudioData" + } + RealtimeClientEventInputAudioBufferClear: + type: object + description: | + Send this event to clear the audio bytes in the buffer. The server will + respond with an `input_audio_buffer.cleared` event. + properties: + event_id: + type: string + description: Optional client-generated ID used to identify this event. + type: + type: string + enum: + - input_audio_buffer.clear + description: The event type, must be `input_audio_buffer.clear`. + x-stainless-const: true + required: + - type + x-oaiMeta: + name: input_audio_buffer.clear + group: realtime + example: | + { + "event_id": "event_012", + "type": "input_audio_buffer.clear" + } + RealtimeClientEventInputAudioBufferCommit: + type: object + description: > + Send this event to commit the user input audio buffer, which will create + a + + new user message item in the conversation. This event will produce an + error + + if the input audio buffer is empty. When in Server VAD mode, the client + does + + not need to send this event, the server will commit the audio buffer + + automatically. + + + Committing the input audio buffer will trigger input audio + transcription + + (if enabled in session configuration), but it will not create a + response + + from the model. The server will respond with an + `input_audio_buffer.committed` + + event. + properties: + event_id: + type: string + description: Optional client-generated ID used to identify this event. + type: + type: string + enum: + - input_audio_buffer.commit + description: The event type, must be `input_audio_buffer.commit`. + x-stainless-const: true + required: + - type + x-oaiMeta: + name: input_audio_buffer.commit + group: realtime + example: | + { + "event_id": "event_789", + "type": "input_audio_buffer.commit" + } + RealtimeClientEventOutputAudioBufferClear: + type: object + description: | + **WebRTC Only:** Emit to cut off the current audio response. This will trigger the server to + stop generating audio and emit a `output_audio_buffer.cleared` event. This + event should be preceded by a `response.cancel` client event to stop the + generation of the current response. + [Learn more](/docs/guides/realtime-model-capabilities#client-and-server-events-for-audio-in-webrtc). + properties: + event_id: + type: string + description: The unique ID of the client event used for error handling. + type: + type: string + enum: + - output_audio_buffer.clear + description: The event type, must be `output_audio_buffer.clear`. + x-stainless-const: true + required: + - type + x-oaiMeta: + name: output_audio_buffer.clear + group: realtime + example: | + { + "event_id": "optional_client_event_id", + "type": "output_audio_buffer.clear" + } + RealtimeClientEventResponseCancel: + type: object + description: > + Send this event to cancel an in-progress response. The server will + respond + + with a `response.cancelled` event or an error if there is no response + to + + cancel. + properties: + event_id: + type: string + description: Optional client-generated ID used to identify this event. + type: + type: string + enum: + - response.cancel + description: The event type, must be `response.cancel`. + x-stainless-const: true + response_id: + type: string + description: | + A specific response ID to cancel - if not provided, will cancel an + in-progress response in the default conversation. + required: + - type + x-oaiMeta: + name: response.cancel + group: realtime + example: | + { + "event_id": "event_567", + "type": "response.cancel" + } + RealtimeClientEventResponseCreate: + type: object + description: > + This event instructs the server to create a Response, which means + triggering + + model inference. When in Server VAD mode, the server will create + Responses + + automatically. + + + A Response will include at least one Item, and may have two, in which + case + + the second will be a function call. These Items will be appended to the + + conversation history. + + + The server will respond with a `response.created` event, events for + Items + + and content created, and finally a `response.done` event to indicate + the + + Response is complete. + + + The `response.create` event includes inference configuration like + + `instructions`, and `temperature`. These fields will override the + Session's + + configuration for this Response only. + properties: + event_id: + type: string + description: Optional client-generated ID used to identify this event. + type: + type: string + enum: + - response.create + description: The event type, must be `response.create`. + x-stainless-const: true + response: + $ref: "#/components/schemas/RealtimeResponseCreateParams" + required: + - type + x-oaiMeta: + name: response.create + group: realtime + example: | + { + "event_id": "event_234", + "type": "response.create", + "response": { + "modalities": ["text", "audio"], + "instructions": "Please assist the user.", + "voice": "sage", + "output_audio_format": "pcm16", + "tools": [ + { + "type": "function", + "name": "calculate_sum", + "description": "Calculates the sum of two numbers.", + "parameters": { + "type": "object", + "properties": { + "a": { "type": "number" }, + "b": { "type": "number" } + }, + "required": ["a", "b"] + } + } + ], + "tool_choice": "auto", + "temperature": 0.8, + "max_output_tokens": 1024 + } + } + RealtimeClientEventSessionUpdate: + type: object + description: > + Send this event to update the session’s default configuration. + + The client may send this event at any time to update any field, + + except for `voice`. However, note that once a session has been + + initialized with a particular `model`, it can’t be changed to + + another model using `session.update`. + + + When the server receives a `session.update`, it will respond + + with a `session.updated` event showing the full, effective + configuration. + + Only the fields that are present are updated. To clear a field like + + `instructions`, pass an empty string. + properties: + event_id: + type: string + description: Optional client-generated ID used to identify this event. + type: + type: string + enum: + - session.update + description: The event type, must be `session.update`. + x-stainless-const: true + session: + $ref: "#/components/schemas/RealtimeSessionCreateRequest" + required: + - type + - session + x-oaiMeta: + name: session.update + group: realtime + example: | + { + "event_id": "event_123", + "type": "session.update", + "session": { + "modalities": ["text", "audio"], + "instructions": "You are a helpful assistant.", + "voice": "sage", + "input_audio_format": "pcm16", + "output_audio_format": "pcm16", + "input_audio_transcription": { + "model": "whisper-1" + }, + "turn_detection": { + "type": "server_vad", + "threshold": 0.5, + "prefix_padding_ms": 300, + "silence_duration_ms": 500, + "create_response": true + }, + "tools": [ + { + "type": "function", + "name": "get_weather", + "description": "Get the current weather...", + "parameters": { + "type": "object", + "properties": { + "location": { "type": "string" } + }, + "required": ["location"] + } + } + ], + "tool_choice": "auto", + "temperature": 0.8, + "max_response_output_tokens": "inf" + } + } + RealtimeClientEventTranscriptionSessionUpdate: + type: object + description: | + Send this event to update a transcription session. + properties: + event_id: + type: string + description: Optional client-generated ID used to identify this event. + type: + type: string + enum: + - transcription_session.update + description: The event type, must be `transcription_session.update`. + x-stainless-const: true + session: + $ref: "#/components/schemas/RealtimeTranscriptionSessionCreateRequest" + required: + - type + - session + x-oaiMeta: + name: transcription_session.update + group: realtime + example: | + { + "type": "transcription_session.update", + "session": { + "input_audio_format": "pcm16", + "input_audio_transcription": { + "model": "gpt-4o-transcribe", + "prompt": "", + "language": "" + }, + "turn_detection": { + "type": "server_vad", + "threshold": 0.5, + "prefix_padding_ms": 300, + "silence_duration_ms": 500, + "create_response": true, + }, + "input_audio_noise_reduction": { + "type": "near_field" + }, + "include": [ + "item.input_audio_transcription.logprobs", + ] + } + } + RealtimeConversationItem: + type: object + description: The item to add to the conversation. + properties: + id: + type: string + description: > + The unique ID of the item, this can be generated by the client to + help + + manage server-side context, but is not required because the server + will + + generate one if not provided. + type: + type: string + enum: + - message + - function_call + - function_call_output + description: > + The type of the item (`message`, `function_call`, + `function_call_output`). + object: + type: string + enum: + - realtime.item + description: > + Identifier for the API object being returned - always + `realtime.item`. + x-stainless-const: true + status: + type: string + enum: + - completed + - incomplete + description: > + The status of the item (`completed`, `incomplete`). These have no + effect + + on the conversation, but are accepted for consistency with the + + `conversation.item.created` event. + role: + type: string + enum: + - user + - assistant + - system + description: > + The role of the message sender (`user`, `assistant`, `system`), + only + + applicable for `message` items. + content: + type: array + description: > + The content of the message, applicable for `message` items. + + - Message items of role `system` support only `input_text` content + + - Message items of role `user` support `input_text` and + `input_audio` + content + - Message items of role `assistant` support `text` content. + items: + type: object + properties: + type: + type: string + enum: + - input_audio + - input_text + - item_reference + - text + description: > + The content type (`input_text`, `input_audio`, + `item_reference`, `text`). + text: + type: string + description: > + The text content, used for `input_text` and `text` content + types. + id: + type: string + description: > + ID of a previous conversation item to reference (for + `item_reference` + + content types in `response.create` events). These can + reference both + + client and server created items. + audio: + type: string + description: > + Base64-encoded audio bytes, used for `input_audio` content + type. + transcript: + type: string + description: > + The transcript of the audio, used for `input_audio` content + type. + call_id: + type: string + description: > + The ID of the function call (for `function_call` and + + `function_call_output` items). If passed on a + `function_call_output` + + item, the server will check that a `function_call` item with the + same + + ID exists in the conversation history. + name: + type: string + description: | + The name of the function being called (for `function_call` items). + arguments: + type: string + description: | + The arguments of the function call (for `function_call` items). + output: + type: string + description: | + The output of the function call (for `function_call_output` items). + RealtimeConversationItemWithReference: + type: object + description: The item to add to the conversation. + properties: + id: + type: string + description: > + For an item of type (`message` | `function_call` | + `function_call_output`) + + this field allows the client to assign the unique ID of the item. It + is + + not required because the server will generate one if not provided. + + + For an item of type `item_reference`, this field is required and is + a + + reference to any item that has previously existed in the + conversation. + type: + type: string + enum: + - message + - function_call + - function_call_output + description: > + The type of the item (`message`, `function_call`, + `function_call_output`, `item_reference`). + object: + type: string + enum: + - realtime.item + description: > + Identifier for the API object being returned - always + `realtime.item`. + x-stainless-const: true + status: + type: string + enum: + - completed + - incomplete + description: > + The status of the item (`completed`, `incomplete`). These have no + effect + + on the conversation, but are accepted for consistency with the + + `conversation.item.created` event. + role: + type: string + enum: + - user + - assistant + - system + description: > + The role of the message sender (`user`, `assistant`, `system`), + only + + applicable for `message` items. + content: + type: array + description: > + The content of the message, applicable for `message` items. + + - Message items of role `system` support only `input_text` content + + - Message items of role `user` support `input_text` and + `input_audio` + content + - Message items of role `assistant` support `text` content. + items: + type: object + properties: + type: + type: string + enum: + - input_audio + - input_text + - item_reference + - text + description: > + The content type (`input_text`, `input_audio`, + `item_reference`, `text`). + text: + type: string + description: > + The text content, used for `input_text` and `text` content + types. + id: + type: string + description: > + ID of a previous conversation item to reference (for + `item_reference` + + content types in `response.create` events). These can + reference both + + client and server created items. + audio: + type: string + description: > + Base64-encoded audio bytes, used for `input_audio` content + type. + transcript: + type: string + description: > + The transcript of the audio, used for `input_audio` content + type. + call_id: + type: string + description: > + The ID of the function call (for `function_call` and + + `function_call_output` items). If passed on a + `function_call_output` + + item, the server will check that a `function_call` item with the + same + + ID exists in the conversation history. + name: + type: string + description: | + The name of the function being called (for `function_call` items). + arguments: + type: string + description: | + The arguments of the function call (for `function_call` items). + output: + type: string + description: | + The output of the function call (for `function_call_output` items). + RealtimeResponse: + type: object + description: The response resource. + properties: + id: + type: string + description: The unique ID of the response. + object: + type: string + enum: + - realtime.response + description: The object type, must be `realtime.response`. + x-stainless-const: true + status: + type: string + enum: + - completed + - cancelled + - failed + - incomplete + description: > + The final status of the response (`completed`, `cancelled`, + `failed`, or + + `incomplete`). + status_details: + type: object + description: Additional details about the status. + properties: + type: + type: string + enum: + - completed + - cancelled + - failed + - incomplete + description: > + The type of error that caused the response to fail, + corresponding + + with the `status` field (`completed`, `cancelled`, + `incomplete`, + + `failed`). + reason: + type: string + enum: + - turn_detected + - client_cancelled + - max_output_tokens + - content_filter + description: > + The reason the Response did not complete. For a `cancelled` + Response, + + one of `turn_detected` (the server VAD detected a new start of + speech) + + or `client_cancelled` (the client sent a cancel event). For an + + `incomplete` Response, one of `max_output_tokens` or + `content_filter` + + (the server-side safety filter activated and cut off the + response). + error: + type: object + description: | + A description of the error that caused the response to fail, + populated when the `status` is `failed`. + properties: + type: + type: string + description: The type of error. + code: + type: string + description: Error code, if any. + output: + type: array + description: The list of output items generated by the response. + items: + $ref: "#/components/schemas/RealtimeConversationItem" + metadata: + $ref: "#/components/schemas/Metadata" + usage: + type: object + description: > + Usage statistics for the Response, this will correspond to billing. + A + + Realtime API session will maintain a conversation context and append + new + + Items to the Conversation, thus output from previous turns (text + and + + audio tokens) will become the input for later turns. + properties: + total_tokens: + type: integer + description: > + The total number of tokens in the Response including input and + output + + text and audio tokens. + input_tokens: + type: integer + description: > + The number of input tokens used in the Response, including text + and + + audio tokens. + output_tokens: + type: integer + description: > + The number of output tokens sent in the Response, including text + and + + audio tokens. + input_token_details: + type: object + description: Details about the input tokens used in the Response. + properties: + cached_tokens: + type: integer + description: The number of cached tokens used in the Response. + text_tokens: + type: integer + description: The number of text tokens used in the Response. + audio_tokens: + type: integer + description: The number of audio tokens used in the Response. + output_token_details: + type: object + description: Details about the output tokens used in the Response. + properties: + text_tokens: + type: integer + description: The number of text tokens used in the Response. + audio_tokens: + type: integer + description: The number of audio tokens used in the Response. + conversation_id: + description: > + Which conversation the response is added to, determined by the + `conversation` + + field in the `response.create` event. If `auto`, the response will + be added to + + the default conversation and the value of `conversation_id` will be + an id like + + `conv_1234`. If `none`, the response will not be added to any + conversation and + + the value of `conversation_id` will be `null`. If responses are + being triggered + + by server VAD, the response will be added to the default + conversation, thus + + the `conversation_id` will be an id like `conv_1234`. + type: string + voice: + $ref: "#/components/schemas/VoiceIdsShared" + description: > + The voice the model used to respond. + + Current voice options are `alloy`, `ash`, `ballad`, `coral`, `echo`, + `fable`, + + `onyx`, `nova`, `sage`, `shimmer`, and `verse`. + modalities: + type: array + description: > + The set of modalities the model used to respond. If there are + multiple modalities, + + the model will pick one, for example if `modalities` is `["text", + "audio"]`, the model + + could be responding in either text or audio. + items: + type: string + enum: + - text + - audio + output_audio_format: + type: string + enum: + - pcm16 + - g711_ulaw + - g711_alaw + description: > + The format of output audio. Options are `pcm16`, `g711_ulaw`, or + `g711_alaw`. + temperature: + type: number + description: > + Sampling temperature for the model, limited to [0.6, 1.2]. Defaults + to 0.8. + max_output_tokens: + oneOf: + - type: integer + - type: string + enum: + - inf + x-stainless-const: true + description: | + Maximum number of output tokens for a single assistant response, + inclusive of tool calls, that was used in this response. + RealtimeResponseCreateParams: + type: object + description: Create a new Realtime response with these parameters + properties: + modalities: + type: array + description: | + The set of modalities the model can respond with. To disable audio, + set this to ["text"]. + items: + type: string + enum: + - text + - audio + instructions: + type: string + description: > + The default system instructions (i.e. system message) prepended to + model + + calls. This field allows the client to guide the model on desired + + responses. The model can be instructed on response content and + format, + + (e.g. "be extremely succinct", "act friendly", "here are examples of + good + + responses") and on audio behavior (e.g. "talk quickly", "inject + emotion + + into your voice", "laugh frequently"). The instructions are not + guaranteed + + to be followed by the model, but they provide guidance to the model + on the + + desired behavior. + + + Note that the server sets default instructions which will be used if + this + + field is not set and are visible in the `session.created` event at + the + + start of the session. + voice: + $ref: "#/components/schemas/VoiceIdsShared" + description: > + The voice the model uses to respond. Voice cannot be changed during + the + + session once the model has responded with audio at least once. + Current + + voice options are `alloy`, `ash`, `ballad`, `coral`, `echo`, + `fable`, + + `onyx`, `nova`, `sage`, `shimmer`, and `verse`. + output_audio_format: + type: string + enum: + - pcm16 + - g711_ulaw + - g711_alaw + description: > + The format of output audio. Options are `pcm16`, `g711_ulaw`, or + `g711_alaw`. + tools: + type: array + description: Tools (functions) available to the model. + items: + type: object + properties: + type: + type: string + enum: + - function + description: The type of the tool, i.e. `function`. + x-stainless-const: true + name: + type: string + description: The name of the function. + description: + type: string + description: > + The description of the function, including guidance on when + and how + + to call it, and guidance about what to tell the user when + calling + + (if anything). + parameters: + type: object + description: Parameters of the function in JSON Schema. + tool_choice: + type: string + description: > + How the model chooses tools. Options are `auto`, `none`, `required`, + or + + specify a function, like `{"type": "function", "function": {"name": + "my_function"}}`. + temperature: + type: number + description: > + Sampling temperature for the model, limited to [0.6, 1.2]. Defaults + to 0.8. + max_response_output_tokens: + oneOf: + - type: integer + - type: string + enum: + - inf + x-stainless-const: true + description: | + Maximum number of output tokens for a single assistant response, + inclusive of tool calls. Provide an integer between 1 and 4096 to + limit output tokens, or `inf` for the maximum available tokens for a + given model. Defaults to `inf`. + conversation: + description: > + Controls which conversation the response is added to. Currently + supports + + `auto` and `none`, with `auto` as the default value. The `auto` + value + + means that the contents of the response will be added to the default + + conversation. Set this to `none` to create an out-of-band response + which + + will not add items to default conversation. + oneOf: + - type: string + - type: string + default: auto + enum: + - auto + - none + metadata: + $ref: "#/components/schemas/Metadata" + input: + type: array + description: > + Input items to include in the prompt for the model. Using this field + + creates a new context for this Response instead of using the default + + conversation. An empty array `[]` will clear the context for this + Response. + + Note that this can include references to items from the default + conversation. + items: + $ref: "#/components/schemas/RealtimeConversationItemWithReference" + RealtimeServerEvent: + discriminator: + propertyName: type + description: | + A realtime server event. + anyOf: + - $ref: "#/components/schemas/RealtimeServerEventConversationCreated" + - $ref: "#/components/schemas/RealtimeServerEventConversationItemCreated" + - $ref: "#/components/schemas/RealtimeServerEventConversationItemDeleted" + - $ref: "#/components/schemas/RealtimeServerEventConversationItemInputAudioTranscriptionCompleted" + - $ref: "#/components/schemas/RealtimeServerEventConversationItemInputAudioTranscriptionDelta" + - $ref: "#/components/schemas/RealtimeServerEventConversationItemInputAudioTranscriptionFailed" + - $ref: "#/components/schemas/RealtimeServerEventConversationItemRetrieved" + - $ref: "#/components/schemas/RealtimeServerEventConversationItemTruncated" + - $ref: "#/components/schemas/RealtimeServerEventError" + - $ref: "#/components/schemas/RealtimeServerEventInputAudioBufferCleared" + - $ref: "#/components/schemas/RealtimeServerEventInputAudioBufferCommitted" + - $ref: "#/components/schemas/RealtimeServerEventInputAudioBufferSpeechStarted" + - $ref: "#/components/schemas/RealtimeServerEventInputAudioBufferSpeechStopped" + - $ref: "#/components/schemas/RealtimeServerEventRateLimitsUpdated" + - $ref: "#/components/schemas/RealtimeServerEventResponseAudioDelta" + - $ref: "#/components/schemas/RealtimeServerEventResponseAudioDone" + - $ref: "#/components/schemas/RealtimeServerEventResponseAudioTranscriptDelta" + - $ref: "#/components/schemas/RealtimeServerEventResponseAudioTranscriptDone" + - $ref: "#/components/schemas/RealtimeServerEventResponseContentPartAdded" + - $ref: "#/components/schemas/RealtimeServerEventResponseContentPartDone" + - $ref: "#/components/schemas/RealtimeServerEventResponseCreated" + - $ref: "#/components/schemas/RealtimeServerEventResponseDone" + - $ref: "#/components/schemas/RealtimeServerEventResponseFunctionCallArgumentsDelta" + - $ref: "#/components/schemas/RealtimeServerEventResponseFunctionCallArgumentsDone" + - $ref: "#/components/schemas/RealtimeServerEventResponseOutputItemAdded" + - $ref: "#/components/schemas/RealtimeServerEventResponseOutputItemDone" + - $ref: "#/components/schemas/RealtimeServerEventResponseTextDelta" + - $ref: "#/components/schemas/RealtimeServerEventResponseTextDone" + - $ref: "#/components/schemas/RealtimeServerEventSessionCreated" + - $ref: "#/components/schemas/RealtimeServerEventSessionUpdated" + - $ref: "#/components/schemas/RealtimeServerEventTranscriptionSessionUpdated" + - $ref: "#/components/schemas/RealtimeServerEventOutputAudioBufferStarted" + - $ref: "#/components/schemas/RealtimeServerEventOutputAudioBufferStopped" + - $ref: "#/components/schemas/RealtimeServerEventOutputAudioBufferCleared" + RealtimeServerEventConversationCreated: + type: object + description: > + Returned when a conversation is created. Emitted right after session + creation. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - conversation.created + description: The event type, must be `conversation.created`. + x-stainless-const: true + conversation: + type: object + description: The conversation resource. + properties: + id: + type: string + description: The unique ID of the conversation. + object: + type: string + description: The object type, must be `realtime.conversation`. + required: + - event_id + - type + - conversation + x-oaiMeta: + name: conversation.created + group: realtime + example: | + { + "event_id": "event_9101", + "type": "conversation.created", + "conversation": { + "id": "conv_001", + "object": "realtime.conversation" + } + } + RealtimeServerEventConversationItemCreated: + type: object + description: > + Returned when a conversation item is created. There are several + scenarios that produce this event: + - The server is generating a Response, which if successful will produce + either one or two Items, which will be of type `message` + (role `assistant`) or type `function_call`. + - The input audio buffer has been committed, either by the client or the + server (in `server_vad` mode). The server will take the content of the + input audio buffer and add it to a new user message Item. + - The client has sent a `conversation.item.create` event to add a new Item + to the Conversation. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - conversation.item.created + description: The event type, must be `conversation.item.created`. + x-stainless-const: true + previous_item_id: + type: string + description: > + The ID of the preceding item in the Conversation context, allows + the + + client to understand the order of the conversation. + item: + $ref: "#/components/schemas/RealtimeConversationItem" + required: + - event_id + - type + - previous_item_id + - item + x-oaiMeta: + name: conversation.item.created + group: realtime + example: | + { + "event_id": "event_1920", + "type": "conversation.item.created", + "previous_item_id": "msg_002", + "item": { + "id": "msg_003", + "object": "realtime.item", + "type": "message", + "status": "completed", + "role": "user", + "content": [] + } + } + RealtimeServerEventConversationItemDeleted: + type: object + description: > + Returned when an item in the conversation is deleted by the client with + a + + `conversation.item.delete` event. This event is used to synchronize the + + server's understanding of the conversation history with the client's + view. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - conversation.item.deleted + description: The event type, must be `conversation.item.deleted`. + x-stainless-const: true + item_id: + type: string + description: The ID of the item that was deleted. + required: + - event_id + - type + - item_id + x-oaiMeta: + name: conversation.item.deleted + group: realtime + example: | + { + "event_id": "event_2728", + "type": "conversation.item.deleted", + "item_id": "msg_005" + } + RealtimeServerEventConversationItemInputAudioTranscriptionCompleted: + type: object + description: > + This event is the output of audio transcription for user audio written + to the + + user audio buffer. Transcription begins when the input audio buffer is + + committed by the client or server (in `server_vad` mode). Transcription + runs + + asynchronously with Response creation, so this event may come before or + after + + the Response events. + + + Realtime API models accept audio natively, and thus input transcription + is a + + separate process run on a separate ASR (Automatic Speech Recognition) + model, + + currently always `whisper-1`. Thus the transcript may diverge somewhat + from + + the model's interpretation, and should be treated as a rough guide. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - conversation.item.input_audio_transcription.completed + description: | + The event type, must be + `conversation.item.input_audio_transcription.completed`. + x-stainless-const: true + item_id: + type: string + description: The ID of the user message item containing the audio. + content_index: + type: integer + description: The index of the content part containing the audio. + transcript: + type: string + description: The transcribed text. + logprobs: + type: array + description: The log probabilities of the transcription. + nullable: true + items: + $ref: "#/components/schemas/LogProbProperties" + required: + - event_id + - type + - item_id + - content_index + - transcript + x-oaiMeta: + name: conversation.item.input_audio_transcription.completed + group: realtime + example: | + { + "event_id": "event_2122", + "type": "conversation.item.input_audio_transcription.completed", + "item_id": "msg_003", + "content_index": 0, + "transcript": "Hello, how are you?" + } + RealtimeServerEventConversationItemInputAudioTranscriptionDelta: + type: object + description: > + Returned when the text value of an input audio transcription content + part is updated. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - conversation.item.input_audio_transcription.delta + description: The event type, must be + `conversation.item.input_audio_transcription.delta`. + x-stainless-const: true + item_id: + type: string + description: The ID of the item. + content_index: + type: integer + description: The index of the content part in the item's content array. + delta: + type: string + description: The text delta. + logprobs: + type: array + description: The log probabilities of the transcription. + nullable: true + items: + $ref: "#/components/schemas/LogProbProperties" + required: + - event_id + - type + - item_id + x-oaiMeta: + name: conversation.item.input_audio_transcription.delta + group: realtime + example: | + { + "type": "conversation.item.input_audio_transcription.delta", + "event_id": "event_001", + "item_id": "item_001", + "content_index": 0, + "delta": "Hello" + } + RealtimeServerEventConversationItemInputAudioTranscriptionFailed: + type: object + description: > + Returned when input audio transcription is configured, and a + transcription + + request for a user message failed. These events are separate from other + + `error` events so that the client can identify the related Item. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - conversation.item.input_audio_transcription.failed + description: | + The event type, must be + `conversation.item.input_audio_transcription.failed`. + x-stainless-const: true + item_id: + type: string + description: The ID of the user message item. + content_index: + type: integer + description: The index of the content part containing the audio. + error: + type: object + description: Details of the transcription error. + properties: + type: + type: string + description: The type of error. + code: + type: string + description: Error code, if any. + message: + type: string + description: A human-readable error message. + param: + type: string + description: Parameter related to the error, if any. + required: + - event_id + - type + - item_id + - content_index + - error + x-oaiMeta: + name: conversation.item.input_audio_transcription.failed + group: realtime + example: | + { + "event_id": "event_2324", + "type": "conversation.item.input_audio_transcription.failed", + "item_id": "msg_003", + "content_index": 0, + "error": { + "type": "transcription_error", + "code": "audio_unintelligible", + "message": "The audio could not be transcribed.", + "param": null + } + } + RealtimeServerEventConversationItemRetrieved: + type: object + description: > + Returned when a conversation item is retrieved with + `conversation.item.retrieve`. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - conversation.item.retrieved + description: The event type, must be `conversation.item.retrieved`. + x-stainless-const: true + item: + $ref: "#/components/schemas/RealtimeConversationItem" + required: + - event_id + - type + - item + x-oaiMeta: + name: conversation.item.retrieved + group: realtime + example: | + { + "event_id": "event_1920", + "type": "conversation.item.created", + "previous_item_id": "msg_002", + "item": { + "id": "msg_003", + "object": "realtime.item", + "type": "message", + "status": "completed", + "role": "user", + "content": [ + { + "type": "input_audio", + "transcript": "hello how are you", + "audio": "base64encodedaudio==" + } + ] + } + } + RealtimeServerEventConversationItemTruncated: + type: object + description: > + Returned when an earlier assistant audio message item is truncated by + the + + client with a `conversation.item.truncate` event. This event is used to + + synchronize the server's understanding of the audio with the client's + playback. + + + This action will truncate the audio and remove the server-side text + transcript + + to ensure there is no text in the context that hasn't been heard by the + user. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - conversation.item.truncated + description: The event type, must be `conversation.item.truncated`. + x-stainless-const: true + item_id: + type: string + description: The ID of the assistant message item that was truncated. + content_index: + type: integer + description: The index of the content part that was truncated. + audio_end_ms: + type: integer + description: | + The duration up to which the audio was truncated, in milliseconds. + required: + - event_id + - type + - item_id + - content_index + - audio_end_ms + x-oaiMeta: + name: conversation.item.truncated + group: realtime + example: | + { + "event_id": "event_2526", + "type": "conversation.item.truncated", + "item_id": "msg_004", + "content_index": 0, + "audio_end_ms": 1500 + } + RealtimeServerEventError: + type: object + description: > + Returned when an error occurs, which could be a client problem or a + server + + problem. Most errors are recoverable and the session will stay open, we + + recommend to implementors to monitor and log error messages by default. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - error + description: The event type, must be `error`. + x-stainless-const: true + error: + type: object + description: Details of the error. + required: + - type + - message + properties: + type: + type: string + description: > + The type of error (e.g., "invalid_request_error", + "server_error"). + code: + type: string + description: Error code, if any. + nullable: true + message: + type: string + description: A human-readable error message. + param: + type: string + description: Parameter related to the error, if any. + nullable: true + event_id: + type: string + description: > + The event_id of the client event that caused the error, if + applicable. + nullable: true + required: + - event_id + - type + - error + x-oaiMeta: + name: error + group: realtime + example: | + { + "event_id": "event_890", + "type": "error", + "error": { + "type": "invalid_request_error", + "code": "invalid_event", + "message": "The 'type' field is missing.", + "param": null, + "event_id": "event_567" + } + } + RealtimeServerEventInputAudioBufferCleared: + type: object + description: | + Returned when the input audio buffer is cleared by the client with a + `input_audio_buffer.clear` event. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - input_audio_buffer.cleared + description: The event type, must be `input_audio_buffer.cleared`. + x-stainless-const: true + required: + - event_id + - type + x-oaiMeta: + name: input_audio_buffer.cleared + group: realtime + example: | + { + "event_id": "event_1314", + "type": "input_audio_buffer.cleared" + } + RealtimeServerEventInputAudioBufferCommitted: + type: object + description: > + Returned when an input audio buffer is committed, either by the client + or + + automatically in server VAD mode. The `item_id` property is the ID of + the user + + message item that will be created, thus a `conversation.item.created` + event + + will also be sent to the client. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - input_audio_buffer.committed + description: The event type, must be `input_audio_buffer.committed`. + x-stainless-const: true + previous_item_id: + type: string + description: > + The ID of the preceding item after which the new item will be + inserted. + item_id: + type: string + description: The ID of the user message item that will be created. + required: + - event_id + - type + - previous_item_id + - item_id + x-oaiMeta: + name: input_audio_buffer.committed + group: realtime + example: | + { + "event_id": "event_1121", + "type": "input_audio_buffer.committed", + "previous_item_id": "msg_001", + "item_id": "msg_002" + } + RealtimeServerEventInputAudioBufferSpeechStarted: + type: object + description: > + Sent by the server when in `server_vad` mode to indicate that speech has + been + + detected in the audio buffer. This can happen any time audio is added to + the + + buffer (unless speech is already detected). The client may want to use + this + + event to interrupt audio playback or provide visual feedback to the + user. + + + The client should expect to receive a + `input_audio_buffer.speech_stopped` event + + when speech stops. The `item_id` property is the ID of the user message + item + + that will be created when speech stops and will also be included in the + + `input_audio_buffer.speech_stopped` event (unless the client manually + commits + + the audio buffer during VAD activation). + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - input_audio_buffer.speech_started + description: The event type, must be `input_audio_buffer.speech_started`. + x-stainless-const: true + audio_start_ms: + type: integer + description: > + Milliseconds from the start of all audio written to the buffer + during the + + session when speech was first detected. This will correspond to the + + beginning of audio sent to the model, and thus includes the + + `prefix_padding_ms` configured in the Session. + item_id: + type: string + description: > + The ID of the user message item that will be created when speech + stops. + required: + - event_id + - type + - audio_start_ms + - item_id + x-oaiMeta: + name: input_audio_buffer.speech_started + group: realtime + example: | + { + "event_id": "event_1516", + "type": "input_audio_buffer.speech_started", + "audio_start_ms": 1000, + "item_id": "msg_003" + } + RealtimeServerEventInputAudioBufferSpeechStopped: + type: object + description: > + Returned in `server_vad` mode when the server detects the end of speech + in + + the audio buffer. The server will also send an + `conversation.item.created` + + event with the user message item that is created from the audio buffer. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - input_audio_buffer.speech_stopped + description: The event type, must be `input_audio_buffer.speech_stopped`. + x-stainless-const: true + audio_end_ms: + type: integer + description: > + Milliseconds since the session started when speech stopped. This + will + + correspond to the end of audio sent to the model, and thus includes + the + + `min_silence_duration_ms` configured in the Session. + item_id: + type: string + description: The ID of the user message item that will be created. + required: + - event_id + - type + - audio_end_ms + - item_id + x-oaiMeta: + name: input_audio_buffer.speech_stopped + group: realtime + example: | + { + "event_id": "event_1718", + "type": "input_audio_buffer.speech_stopped", + "audio_end_ms": 2000, + "item_id": "msg_003" + } + RealtimeServerEventOutputAudioBufferCleared: + type: object + description: | + **WebRTC Only:** Emitted when the output audio buffer is cleared. This happens either in VAD + mode when the user has interrupted (`input_audio_buffer.speech_started`), + or when the client has emitted the `output_audio_buffer.clear` event to manually + cut off the current audio response. + [Learn more](/docs/guides/realtime-model-capabilities#client-and-server-events-for-audio-in-webrtc). + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - output_audio_buffer.cleared + description: The event type, must be `output_audio_buffer.cleared`. + x-stainless-const: true + response_id: + type: string + description: The unique ID of the response that produced the audio. + required: + - event_id + - type + - response_id + x-oaiMeta: + name: output_audio_buffer.cleared + group: realtime + example: | + { + "event_id": "event_abc123", + "type": "output_audio_buffer.cleared", + "response_id": "resp_abc123" + } + RealtimeServerEventOutputAudioBufferStarted: + type: object + description: | + **WebRTC Only:** Emitted when the server begins streaming audio to the client. This event is + emitted after an audio content part has been added (`response.content_part.added`) + to the response. + [Learn more](/docs/guides/realtime-model-capabilities#client-and-server-events-for-audio-in-webrtc). + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - output_audio_buffer.started + description: The event type, must be `output_audio_buffer.started`. + x-stainless-const: true + response_id: + type: string + description: The unique ID of the response that produced the audio. + required: + - event_id + - type + - response_id + x-oaiMeta: + name: output_audio_buffer.started + group: realtime + example: | + { + "event_id": "event_abc123", + "type": "output_audio_buffer.started", + "response_id": "resp_abc123" + } + RealtimeServerEventOutputAudioBufferStopped: + type: object + description: | + **WebRTC Only:** Emitted when the output audio buffer has been completely drained on the server, + and no more audio is forthcoming. This event is emitted after the full response + data has been sent to the client (`response.done`). + [Learn more](/docs/guides/realtime-model-capabilities#client-and-server-events-for-audio-in-webrtc). + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - output_audio_buffer.stopped + description: The event type, must be `output_audio_buffer.stopped`. + x-stainless-const: true + response_id: + type: string + description: The unique ID of the response that produced the audio. + required: + - event_id + - type + - response_id + x-oaiMeta: + name: output_audio_buffer.stopped + group: realtime + example: | + { + "event_id": "event_abc123", + "type": "output_audio_buffer.stopped", + "response_id": "resp_abc123" + } + RealtimeServerEventRateLimitsUpdated: + type: object + description: > + Emitted at the beginning of a Response to indicate the updated rate + limits. + + When a Response is created some tokens will be "reserved" for the + output + + tokens, the rate limits shown here reflect that reservation, which is + then + + adjusted accordingly once the Response is completed. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - rate_limits.updated + description: The event type, must be `rate_limits.updated`. + x-stainless-const: true + rate_limits: + type: array + description: List of rate limit information. + items: + type: object + properties: + name: + type: string + enum: + - requests + - tokens + description: | + The name of the rate limit (`requests`, `tokens`). + limit: + type: integer + description: The maximum allowed value for the rate limit. + remaining: + type: integer + description: The remaining value before the limit is reached. + reset_seconds: + type: number + description: Seconds until the rate limit resets. + required: + - event_id + - type + - rate_limits + x-oaiMeta: + name: rate_limits.updated + group: realtime + example: | + { + "event_id": "event_5758", + "type": "rate_limits.updated", + "rate_limits": [ + { + "name": "requests", + "limit": 1000, + "remaining": 999, + "reset_seconds": 60 + }, + { + "name": "tokens", + "limit": 50000, + "remaining": 49950, + "reset_seconds": 60 + } + ] + } + RealtimeServerEventResponseAudioDelta: + type: object + description: Returned when the model-generated audio is updated. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - response.audio.delta + description: The event type, must be `response.audio.delta`. + x-stainless-const: true + response_id: + type: string + description: The ID of the response. + item_id: + type: string + description: The ID of the item. + output_index: + type: integer + description: The index of the output item in the response. + content_index: + type: integer + description: The index of the content part in the item's content array. + delta: + type: string + description: Base64-encoded audio data delta. + required: + - event_id + - type + - response_id + - item_id + - output_index + - content_index + - delta + x-oaiMeta: + name: response.audio.delta + group: realtime + example: | + { + "event_id": "event_4950", + "type": "response.audio.delta", + "response_id": "resp_001", + "item_id": "msg_008", + "output_index": 0, + "content_index": 0, + "delta": "Base64EncodedAudioDelta" + } + RealtimeServerEventResponseAudioDone: + type: object + description: > + Returned when the model-generated audio is done. Also emitted when a + Response + + is interrupted, incomplete, or cancelled. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - response.audio.done + description: The event type, must be `response.audio.done`. + x-stainless-const: true + response_id: + type: string + description: The ID of the response. + item_id: + type: string + description: The ID of the item. + output_index: + type: integer + description: The index of the output item in the response. + content_index: + type: integer + description: The index of the content part in the item's content array. + required: + - event_id + - type + - response_id + - item_id + - output_index + - content_index + x-oaiMeta: + name: response.audio.done + group: realtime + example: | + { + "event_id": "event_5152", + "type": "response.audio.done", + "response_id": "resp_001", + "item_id": "msg_008", + "output_index": 0, + "content_index": 0 + } + RealtimeServerEventResponseAudioTranscriptDelta: + type: object + description: > + Returned when the model-generated transcription of audio output is + updated. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - response.audio_transcript.delta + description: The event type, must be `response.audio_transcript.delta`. + x-stainless-const: true + response_id: + type: string + description: The ID of the response. + item_id: + type: string + description: The ID of the item. + output_index: + type: integer + description: The index of the output item in the response. + content_index: + type: integer + description: The index of the content part in the item's content array. + delta: + type: string + description: The transcript delta. + required: + - event_id + - type + - response_id + - item_id + - output_index + - content_index + - delta + x-oaiMeta: + name: response.audio_transcript.delta + group: realtime + example: | + { + "event_id": "event_4546", + "type": "response.audio_transcript.delta", + "response_id": "resp_001", + "item_id": "msg_008", + "output_index": 0, + "content_index": 0, + "delta": "Hello, how can I a" + } + RealtimeServerEventResponseAudioTranscriptDone: + type: object + description: | + Returned when the model-generated transcription of audio output is done + streaming. Also emitted when a Response is interrupted, incomplete, or + cancelled. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - response.audio_transcript.done + description: The event type, must be `response.audio_transcript.done`. + x-stainless-const: true + response_id: + type: string + description: The ID of the response. + item_id: + type: string + description: The ID of the item. + output_index: + type: integer + description: The index of the output item in the response. + content_index: + type: integer + description: The index of the content part in the item's content array. + transcript: + type: string + description: The final transcript of the audio. + required: + - event_id + - type + - response_id + - item_id + - output_index + - content_index + - transcript + x-oaiMeta: + name: response.audio_transcript.done + group: realtime + example: | + { + "event_id": "event_4748", + "type": "response.audio_transcript.done", + "response_id": "resp_001", + "item_id": "msg_008", + "output_index": 0, + "content_index": 0, + "transcript": "Hello, how can I assist you today?" + } + RealtimeServerEventResponseContentPartAdded: + type: object + description: > + Returned when a new content part is added to an assistant message item + during + + response generation. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - response.content_part.added + description: The event type, must be `response.content_part.added`. + x-stainless-const: true + response_id: + type: string + description: The ID of the response. + item_id: + type: string + description: The ID of the item to which the content part was added. + output_index: + type: integer + description: The index of the output item in the response. + content_index: + type: integer + description: The index of the content part in the item's content array. + part: + type: object + description: The content part that was added. + properties: + type: + type: string + enum: + - audio + - text + description: The content type ("text", "audio"). + text: + type: string + description: The text content (if type is "text"). + audio: + type: string + description: Base64-encoded audio data (if type is "audio"). + transcript: + type: string + description: The transcript of the audio (if type is "audio"). + required: + - event_id + - type + - response_id + - item_id + - output_index + - content_index + - part + x-oaiMeta: + name: response.content_part.added + group: realtime + example: | + { + "event_id": "event_3738", + "type": "response.content_part.added", + "response_id": "resp_001", + "item_id": "msg_007", + "output_index": 0, + "content_index": 0, + "part": { + "type": "text", + "text": "" + } + } + RealtimeServerEventResponseContentPartDone: + type: object + description: > + Returned when a content part is done streaming in an assistant message + item. + + Also emitted when a Response is interrupted, incomplete, or cancelled. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - response.content_part.done + description: The event type, must be `response.content_part.done`. + x-stainless-const: true + response_id: + type: string + description: The ID of the response. + item_id: + type: string + description: The ID of the item. + output_index: + type: integer + description: The index of the output item in the response. + content_index: + type: integer + description: The index of the content part in the item's content array. + part: + type: object + description: The content part that is done. + properties: + type: + type: string + enum: + - audio + - text + description: The content type ("text", "audio"). + text: + type: string + description: The text content (if type is "text"). + audio: + type: string + description: Base64-encoded audio data (if type is "audio"). + transcript: + type: string + description: The transcript of the audio (if type is "audio"). + required: + - event_id + - type + - response_id + - item_id + - output_index + - content_index + - part + x-oaiMeta: + name: response.content_part.done + group: realtime + example: | + { + "event_id": "event_3940", + "type": "response.content_part.done", + "response_id": "resp_001", + "item_id": "msg_007", + "output_index": 0, + "content_index": 0, + "part": { + "type": "text", + "text": "Sure, I can help with that." + } + } + RealtimeServerEventResponseCreated: + type: object + description: > + Returned when a new Response is created. The first event of response + creation, + + where the response is in an initial state of `in_progress`. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - response.created + description: The event type, must be `response.created`. + x-stainless-const: true + response: + $ref: "#/components/schemas/RealtimeResponse" + required: + - event_id + - type + - response + x-oaiMeta: + name: response.created + group: realtime + example: | + { + "event_id": "event_2930", + "type": "response.created", + "response": { + "id": "resp_001", + "object": "realtime.response", + "status": "in_progress", + "status_details": null, + "output": [], + "usage": null + } + } + RealtimeServerEventResponseDone: + type: object + description: > + Returned when a Response is done streaming. Always emitted, no matter + the + + final state. The Response object included in the `response.done` event + will + + include all output Items in the Response but will omit the raw audio + data. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - response.done + description: The event type, must be `response.done`. + x-stainless-const: true + response: + $ref: "#/components/schemas/RealtimeResponse" + required: + - event_id + - type + - response + x-oaiMeta: + name: response.done + group: realtime + example: | + { + "event_id": "event_3132", + "type": "response.done", + "response": { + "id": "resp_001", + "object": "realtime.response", + "status": "completed", + "status_details": null, + "output": [ + { + "id": "msg_006", + "object": "realtime.item", + "type": "message", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "text", + "text": "Sure, how can I assist you today?" + } + ] + } + ], + "usage": { + "total_tokens":275, + "input_tokens":127, + "output_tokens":148, + "input_token_details": { + "cached_tokens":384, + "text_tokens":119, + "audio_tokens":8, + "cached_tokens_details": { + "text_tokens": 128, + "audio_tokens": 256 + } + }, + "output_token_details": { + "text_tokens":36, + "audio_tokens":112 + } + } + } + } + RealtimeServerEventResponseFunctionCallArgumentsDelta: + type: object + description: | + Returned when the model-generated function call arguments are updated. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - response.function_call_arguments.delta + description: | + The event type, must be `response.function_call_arguments.delta`. + x-stainless-const: true + response_id: + type: string + description: The ID of the response. + item_id: + type: string + description: The ID of the function call item. + output_index: + type: integer + description: The index of the output item in the response. + call_id: + type: string + description: The ID of the function call. + delta: + type: string + description: The arguments delta as a JSON string. + required: + - event_id + - type + - response_id + - item_id + - output_index + - call_id + - delta + x-oaiMeta: + name: response.function_call_arguments.delta + group: realtime + example: | + { + "event_id": "event_5354", + "type": "response.function_call_arguments.delta", + "response_id": "resp_002", + "item_id": "fc_001", + "output_index": 0, + "call_id": "call_001", + "delta": "{\"location\": \"San\"" + } + RealtimeServerEventResponseFunctionCallArgumentsDone: + type: object + description: > + Returned when the model-generated function call arguments are done + streaming. + + Also emitted when a Response is interrupted, incomplete, or cancelled. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - response.function_call_arguments.done + description: | + The event type, must be `response.function_call_arguments.done`. + x-stainless-const: true + response_id: + type: string + description: The ID of the response. + item_id: + type: string + description: The ID of the function call item. + output_index: + type: integer + description: The index of the output item in the response. + call_id: + type: string + description: The ID of the function call. + arguments: + type: string + description: The final arguments as a JSON string. + required: + - event_id + - type + - response_id + - item_id + - output_index + - call_id + - arguments + x-oaiMeta: + name: response.function_call_arguments.done + group: realtime + example: | + { + "event_id": "event_5556", + "type": "response.function_call_arguments.done", + "response_id": "resp_002", + "item_id": "fc_001", + "output_index": 0, + "call_id": "call_001", + "arguments": "{\"location\": \"San Francisco\"}" + } + RealtimeServerEventResponseOutputItemAdded: + type: object + description: Returned when a new Item is created during Response generation. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - response.output_item.added + description: The event type, must be `response.output_item.added`. + x-stainless-const: true + response_id: + type: string + description: The ID of the Response to which the item belongs. + output_index: + type: integer + description: The index of the output item in the Response. + item: + $ref: "#/components/schemas/RealtimeConversationItem" + required: + - event_id + - type + - response_id + - output_index + - item + x-oaiMeta: + name: response.output_item.added + group: realtime + example: | + { + "event_id": "event_3334", + "type": "response.output_item.added", + "response_id": "resp_001", + "output_index": 0, + "item": { + "id": "msg_007", + "object": "realtime.item", + "type": "message", + "status": "in_progress", + "role": "assistant", + "content": [] + } + } + RealtimeServerEventResponseOutputItemDone: + type: object + description: > + Returned when an Item is done streaming. Also emitted when a Response + is + + interrupted, incomplete, or cancelled. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - response.output_item.done + description: The event type, must be `response.output_item.done`. + x-stainless-const: true + response_id: + type: string + description: The ID of the Response to which the item belongs. + output_index: + type: integer + description: The index of the output item in the Response. + item: + $ref: "#/components/schemas/RealtimeConversationItem" + required: + - event_id + - type + - response_id + - output_index + - item + x-oaiMeta: + name: response.output_item.done + group: realtime + example: | + { + "event_id": "event_3536", + "type": "response.output_item.done", + "response_id": "resp_001", + "output_index": 0, + "item": { + "id": "msg_007", + "object": "realtime.item", + "type": "message", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "text", + "text": "Sure, I can help with that." + } + ] + } + } + RealtimeServerEventResponseTextDelta: + type: object + description: Returned when the text value of a "text" content part is updated. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - response.text.delta + description: The event type, must be `response.text.delta`. + x-stainless-const: true + response_id: + type: string + description: The ID of the response. + item_id: + type: string + description: The ID of the item. + output_index: + type: integer + description: The index of the output item in the response. + content_index: + type: integer + description: The index of the content part in the item's content array. + delta: + type: string + description: The text delta. + required: + - event_id + - type + - response_id + - item_id + - output_index + - content_index + - delta + x-oaiMeta: + name: response.text.delta + group: realtime + example: | + { + "event_id": "event_4142", + "type": "response.text.delta", + "response_id": "resp_001", + "item_id": "msg_007", + "output_index": 0, + "content_index": 0, + "delta": "Sure, I can h" + } + RealtimeServerEventResponseTextDone: + type: object + description: > + Returned when the text value of a "text" content part is done streaming. + Also + + emitted when a Response is interrupted, incomplete, or cancelled. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - response.text.done + description: The event type, must be `response.text.done`. + x-stainless-const: true + response_id: + type: string + description: The ID of the response. + item_id: + type: string + description: The ID of the item. + output_index: + type: integer + description: The index of the output item in the response. + content_index: + type: integer + description: The index of the content part in the item's content array. + text: + type: string + description: The final text content. + required: + - event_id + - type + - response_id + - item_id + - output_index + - content_index + - text + x-oaiMeta: + name: response.text.done + group: realtime + example: | + { + "event_id": "event_4344", + "type": "response.text.done", + "response_id": "resp_001", + "item_id": "msg_007", + "output_index": 0, + "content_index": 0, + "text": "Sure, I can help with that." + } + RealtimeServerEventSessionCreated: + type: object + description: > + Returned when a Session is created. Emitted automatically when a new + + connection is established as the first server event. This event will + contain + + the default Session configuration. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - session.created + description: The event type, must be `session.created`. + x-stainless-const: true + session: + $ref: "#/components/schemas/RealtimeSession" + required: + - event_id + - type + - session + x-oaiMeta: + name: session.created + group: realtime + example: | + { + "event_id": "event_1234", + "type": "session.created", + "session": { + "id": "sess_001", + "object": "realtime.session", + "model": "gpt-4o-realtime-preview", + "modalities": ["text", "audio"], + "instructions": "...model instructions here...", + "voice": "sage", + "input_audio_format": "pcm16", + "output_audio_format": "pcm16", + "input_audio_transcription": null, + "turn_detection": { + "type": "server_vad", + "threshold": 0.5, + "prefix_padding_ms": 300, + "silence_duration_ms": 200 + }, + "tools": [], + "tool_choice": "auto", + "temperature": 0.8, + "max_response_output_tokens": "inf" + } + } + RealtimeServerEventSessionUpdated: + type: object + description: > + Returned when a session is updated with a `session.update` event, + unless + + there is an error. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - session.updated + description: The event type, must be `session.updated`. + x-stainless-const: true + session: + $ref: "#/components/schemas/RealtimeSession" + required: + - event_id + - type + - session + x-oaiMeta: + name: session.updated + group: realtime + example: | + { + "event_id": "event_5678", + "type": "session.updated", + "session": { + "id": "sess_001", + "object": "realtime.session", + "model": "gpt-4o-realtime-preview", + "modalities": ["text"], + "instructions": "New instructions", + "voice": "sage", + "input_audio_format": "pcm16", + "output_audio_format": "pcm16", + "input_audio_transcription": { + "model": "whisper-1" + }, + "turn_detection": null, + "tools": [], + "tool_choice": "none", + "temperature": 0.7, + "max_response_output_tokens": 200 + } + } + RealtimeServerEventTranscriptionSessionUpdated: + type: object + description: > + Returned when a transcription session is updated with a + `transcription_session.update` event, unless + + there is an error. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: + type: string + enum: + - transcription_session.updated + description: The event type, must be `transcription_session.updated`. + x-stainless-const: true + session: + $ref: "#/components/schemas/RealtimeTranscriptionSessionCreateResponse" + required: + - event_id + - type + - session + x-oaiMeta: + name: transcription_session.updated + group: realtime + example: | + { + "event_id": "event_5678", + "type": "transcription_session.updated", + "session": { + "id": "sess_001", + "object": "realtime.transcription_session", + "input_audio_format": "pcm16", + "input_audio_transcription": { + "model": "gpt-4o-transcribe", + "prompt": "", + "language": "" + }, + "turn_detection": { + "type": "server_vad", + "threshold": 0.5, + "prefix_padding_ms": 300, + "silence_duration_ms": 500, + "create_response": true, + // "interrupt_response": false -- this will NOT be returned + }, + "input_audio_noise_reduction": { + "type": "near_field" + }, + "include": [ + "item.input_audio_transcription.avg_logprob", + ], + } + } + RealtimeSession: + type: object + description: Realtime session object configuration. + properties: + id: + type: string + description: > + Unique identifier for the session that looks like + `sess_1234567890abcdef`. + modalities: + description: | + The set of modalities the model can respond with. To disable audio, + set this to ["text"]. + items: + type: string + default: + - text + - audio + enum: + - text + - audio + model: + type: string + description: | + The Realtime model used for this session. + enum: + - gpt-4o-realtime-preview + - gpt-4o-realtime-preview-2024-10-01 + - gpt-4o-realtime-preview-2024-12-17 + - gpt-4o-mini-realtime-preview + - gpt-4o-mini-realtime-preview-2024-12-17 + instructions: + type: string + description: > + The default system instructions (i.e. system message) prepended to + model calls. This field allows the client to guide the model on + desired responses. The model can be instructed on response content + and format, (e.g. "be extremely succinct", "act friendly", "here + are examples of good responses") and on audio behavior (e.g. "talk + quickly", "inject emotion into your voice", "laugh frequently"). + The instructions are not guaranteed to be followed by the model, + but they provide guidance to the model on the desired behavior. + + + Note that the server sets default instructions which will be used if + this field is not set and are visible in the `session.created` + event at the start of the session. + voice: + $ref: "#/components/schemas/VoiceIdsShared" + description: > + The voice the model uses to respond. Voice cannot be changed during + the + + session once the model has responded with audio at least once. + Current + + voice options are `alloy`, `ash`, `ballad`, `coral`, `echo` `sage`, + + `shimmer` and `verse`. + input_audio_format: + type: string + default: pcm16 + enum: + - pcm16 + - g711_ulaw + - g711_alaw + description: > + The format of input audio. Options are `pcm16`, `g711_ulaw`, or + `g711_alaw`. + + For `pcm16`, input audio must be 16-bit PCM at a 24kHz sample rate, + + single channel (mono), and little-endian byte order. + output_audio_format: + type: string + default: pcm16 + enum: + - pcm16 + - g711_ulaw + - g711_alaw + description: > + The format of output audio. Options are `pcm16`, `g711_ulaw`, or + `g711_alaw`. + + For `pcm16`, output audio is sampled at a rate of 24kHz. + input_audio_transcription: + type: object + description: | + Configuration for input audio transcription, defaults to off and can be set to `null` to turn off once on. Input audio transcription is not native to the model, since the model consumes audio directly. Transcription runs asynchronously through [the /audio/transcriptions endpoint](https://platform.openai.com/docs/api-reference/audio/createTranscription) and should be treated as guidance of input audio content rather than precisely what the model heard. The client can optionally set the language and prompt for transcription, these offer additional guidance to the transcription service. + properties: + model: + type: string + description: > + The model to use for transcription, current options are + `gpt-4o-transcribe`, `gpt-4o-mini-transcribe`, and `whisper-1`. + language: + type: string + description: | + The language of the input audio. Supplying the input language in + [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g. `en`) format + will improve accuracy and latency. + prompt: + type: string + description: > + An optional text to guide the model's style or continue a + previous audio + + segment. + + For `whisper-1`, the [prompt is a list of + keywords](/docs/guides/speech-to-text#prompting). + + For `gpt-4o-transcribe` models, the prompt is a free text + string, for example "expect words related to technology". + turn_detection: + type: object + description: > + Configuration for turn detection, ether Server VAD or Semantic VAD. + This can be set to `null` to turn off, in which case the client must + manually trigger model response. + + Server VAD means that the model will detect the start and end of + speech based on audio volume and respond at the end of user speech. + + Semantic VAD is more advanced and uses a turn detection model (in + conjuction with VAD) to semantically estimate whether the user has + finished speaking, then dynamically sets a timeout based on this + probability. For example, if user audio trails off with "uhhm", the + model will score a low probability of turn end and wait longer for + the user to continue speaking. This can be useful for more natural + conversations, but may have a higher latency. + properties: + type: + type: string + default: server_vad + enum: + - server_vad + - semantic_vad + description: | + Type of turn detection. + eagerness: + type: string + default: auto + enum: + - low + - medium + - high + - auto + description: > + Used only for `semantic_vad` mode. The eagerness of the model to + respond. `low` will wait longer for the user to continue + speaking, `high` will respond more quickly. `auto` is the + default and is equivalent to `medium`. + threshold: + type: number + description: > + Used only for `server_vad` mode. Activation threshold for VAD + (0.0 to 1.0), this defaults to 0.5. A + + higher threshold will require louder audio to activate the + model, and + + thus might perform better in noisy environments. + prefix_padding_ms: + type: integer + description: > + Used only for `server_vad` mode. Amount of audio to include + before the VAD detected speech (in + + milliseconds). Defaults to 300ms. + silence_duration_ms: + type: integer + description: > + Used only for `server_vad` mode. Duration of silence to detect + speech stop (in milliseconds). Defaults + + to 500ms. With shorter values the model will respond more + quickly, + + but may jump in on short pauses from the user. + create_response: + type: boolean + default: true + description: > + Whether or not to automatically generate a response when a VAD + stop event occurs. + interrupt_response: + type: boolean + default: true + description: > + Whether or not to automatically interrupt any ongoing response + with output to the default + + conversation (i.e. `conversation` of `auto`) when a VAD start + event occurs. + input_audio_noise_reduction: + type: object + default: null + description: > + Configuration for input audio noise reduction. This can be set to + `null` to turn off. + + Noise reduction filters audio added to the input audio buffer before + it is sent to VAD and the model. + + Filtering the audio can improve VAD and turn detection accuracy + (reducing false positives) and model performance by improving + perception of the input audio. + properties: + type: + type: string + enum: + - near_field + - far_field + description: > + Type of noise reduction. `near_field` is for close-talking + microphones such as headphones, `far_field` is for far-field + microphones such as laptop or conference room microphones. + tools: + type: array + description: Tools (functions) available to the model. + items: + type: object + properties: + type: + type: string + enum: + - function + description: The type of the tool, i.e. `function`. + x-stainless-const: true + name: + type: string + description: The name of the function. + description: + type: string + description: > + The description of the function, including guidance on when + and how + + to call it, and guidance about what to tell the user when + calling + + (if anything). + parameters: + type: object + description: Parameters of the function in JSON Schema. + tool_choice: + type: string + default: auto + description: > + How the model chooses tools. Options are `auto`, `none`, `required`, + or + + specify a function. + temperature: + type: number + default: 0.8 + description: > + Sampling temperature for the model, limited to [0.6, 1.2]. For audio + models a temperature of 0.8 is highly recommended for best + performance. + max_response_output_tokens: + oneOf: + - type: integer + - type: string + enum: + - inf + x-stainless-const: true + description: | + Maximum number of output tokens for a single assistant response, + inclusive of tool calls. Provide an integer between 1 and 4096 to + limit output tokens, or `inf` for the maximum available tokens for a + given model. Defaults to `inf`. + RealtimeSessionCreateRequest: + type: object + description: Realtime session object configuration. + properties: + modalities: + description: | + The set of modalities the model can respond with. To disable audio, + set this to ["text"]. + items: + type: string + default: + - text + - audio + enum: + - text + - audio + model: + type: string + description: | + The Realtime model used for this session. + enum: + - gpt-4o-realtime-preview + - gpt-4o-realtime-preview-2024-10-01 + - gpt-4o-realtime-preview-2024-12-17 + - gpt-4o-mini-realtime-preview + - gpt-4o-mini-realtime-preview-2024-12-17 + instructions: + type: string + description: > + The default system instructions (i.e. system message) prepended to + model calls. This field allows the client to guide the model on + desired responses. The model can be instructed on response content + and format, (e.g. "be extremely succinct", "act friendly", "here + are examples of good responses") and on audio behavior (e.g. "talk + quickly", "inject emotion into your voice", "laugh frequently"). + The instructions are not guaranteed to be followed by the model, + but they provide guidance to the model on the desired behavior. + + + Note that the server sets default instructions which will be used if + this field is not set and are visible in the `session.created` + event at the start of the session. + voice: + $ref: "#/components/schemas/VoiceIdsShared" + description: > + The voice the model uses to respond. Voice cannot be changed during + the + + session once the model has responded with audio at least once. + Current + + voice options are `alloy`, `ash`, `ballad`, `coral`, `echo`, + `fable`, + + `onyx`, `nova`, `sage`, `shimmer`, and `verse`. + input_audio_format: + type: string + default: pcm16 + enum: + - pcm16 + - g711_ulaw + - g711_alaw + description: > + The format of input audio. Options are `pcm16`, `g711_ulaw`, or + `g711_alaw`. + + For `pcm16`, input audio must be 16-bit PCM at a 24kHz sample rate, + + single channel (mono), and little-endian byte order. + output_audio_format: + type: string + default: pcm16 + enum: + - pcm16 + - g711_ulaw + - g711_alaw + description: > + The format of output audio. Options are `pcm16`, `g711_ulaw`, or + `g711_alaw`. + + For `pcm16`, output audio is sampled at a rate of 24kHz. + input_audio_transcription: + type: object + description: | + Configuration for input audio transcription, defaults to off and can be set to `null` to turn off once on. Input audio transcription is not native to the model, since the model consumes audio directly. Transcription runs asynchronously through [the /audio/transcriptions endpoint](https://platform.openai.com/docs/api-reference/audio/createTranscription) and should be treated as guidance of input audio content rather than precisely what the model heard. The client can optionally set the language and prompt for transcription, these offer additional guidance to the transcription service. + properties: + model: + type: string + description: > + The model to use for transcription, current options are + `gpt-4o-transcribe`, `gpt-4o-mini-transcribe`, and `whisper-1`. + language: + type: string + description: | + The language of the input audio. Supplying the input language in + [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g. `en`) format + will improve accuracy and latency. + prompt: + type: string + description: > + An optional text to guide the model's style or continue a + previous audio + + segment. + + For `whisper-1`, the [prompt is a list of + keywords](/docs/guides/speech-to-text#prompting). + + For `gpt-4o-transcribe` models, the prompt is a free text + string, for example "expect words related to technology". + turn_detection: + type: object + description: > + Configuration for turn detection, ether Server VAD or Semantic VAD. + This can be set to `null` to turn off, in which case the client must + manually trigger model response. + + Server VAD means that the model will detect the start and end of + speech based on audio volume and respond at the end of user speech. + + Semantic VAD is more advanced and uses a turn detection model (in + conjuction with VAD) to semantically estimate whether the user has + finished speaking, then dynamically sets a timeout based on this + probability. For example, if user audio trails off with "uhhm", the + model will score a low probability of turn end and wait longer for + the user to continue speaking. This can be useful for more natural + conversations, but may have a higher latency. + properties: + type: + type: string + default: server_vad + enum: + - server_vad + - semantic_vad + description: | + Type of turn detection. + eagerness: + type: string + default: auto + enum: + - low + - medium + - high + - auto + description: > + Used only for `semantic_vad` mode. The eagerness of the model to + respond. `low` will wait longer for the user to continue + speaking, `high` will respond more quickly. `auto` is the + default and is equivalent to `medium`. + threshold: + type: number + description: > + Used only for `server_vad` mode. Activation threshold for VAD + (0.0 to 1.0), this defaults to 0.5. A + + higher threshold will require louder audio to activate the + model, and + + thus might perform better in noisy environments. + prefix_padding_ms: + type: integer + description: > + Used only for `server_vad` mode. Amount of audio to include + before the VAD detected speech (in + + milliseconds). Defaults to 300ms. + silence_duration_ms: + type: integer + description: > + Used only for `server_vad` mode. Duration of silence to detect + speech stop (in milliseconds). Defaults + + to 500ms. With shorter values the model will respond more + quickly, + + but may jump in on short pauses from the user. + create_response: + type: boolean + default: true + description: > + Whether or not to automatically generate a response when a VAD + stop event occurs. + interrupt_response: + type: boolean + default: true + description: > + Whether or not to automatically interrupt any ongoing response + with output to the default + + conversation (i.e. `conversation` of `auto`) when a VAD start + event occurs. + input_audio_noise_reduction: + type: object + default: null + description: > + Configuration for input audio noise reduction. This can be set to + `null` to turn off. + + Noise reduction filters audio added to the input audio buffer before + it is sent to VAD and the model. + + Filtering the audio can improve VAD and turn detection accuracy + (reducing false positives) and model performance by improving + perception of the input audio. + properties: + type: + type: string + enum: + - near_field + - far_field + description: > + Type of noise reduction. `near_field` is for close-talking + microphones such as headphones, `far_field` is for far-field + microphones such as laptop or conference room microphones. + tools: + type: array + description: Tools (functions) available to the model. + items: + type: object + properties: + type: + type: string + enum: + - function + description: The type of the tool, i.e. `function`. + x-stainless-const: true + name: + type: string + description: The name of the function. + description: + type: string + description: > + The description of the function, including guidance on when + and how + + to call it, and guidance about what to tell the user when + calling + + (if anything). + parameters: + type: object + description: Parameters of the function in JSON Schema. + tool_choice: + type: string + default: auto + description: > + How the model chooses tools. Options are `auto`, `none`, `required`, + or + + specify a function. + temperature: + type: number + default: 0.8 + description: > + Sampling temperature for the model, limited to [0.6, 1.2]. For audio + models a temperature of 0.8 is highly recommended for best + performance. + max_response_output_tokens: + oneOf: + - type: integer + - type: string + enum: + - inf + x-stainless-const: true + description: | + Maximum number of output tokens for a single assistant response, + inclusive of tool calls. Provide an integer between 1 and 4096 to + limit output tokens, or `inf` for the maximum available tokens for a + given model. Defaults to `inf`. + RealtimeSessionCreateResponse: + type: object + description: > + A new Realtime session configuration, with an ephermeral key. Default + TTL + + for keys is one minute. + properties: + client_secret: + type: object + description: Ephemeral key returned by the API. + properties: + value: + type: string + description: > + Ephemeral key usable in client environments to authenticate + connections + + to the Realtime API. Use this in client-side environments rather + than + + a standard API token, which should only be used server-side. + expires_at: + type: integer + description: > + Timestamp for when the token expires. Currently, all tokens + expire + + after one minute. + required: + - value + - expires_at + modalities: + description: | + The set of modalities the model can respond with. To disable audio, + set this to ["text"]. + items: + type: string + enum: + - text + - audio + instructions: + type: string + description: > + The default system instructions (i.e. system message) prepended to + model + + calls. This field allows the client to guide the model on desired + + responses. The model can be instructed on response content and + format, + + (e.g. "be extremely succinct", "act friendly", "here are examples of + good + + responses") and on audio behavior (e.g. "talk quickly", "inject + emotion + + into your voice", "laugh frequently"). The instructions are not + guaranteed + + to be followed by the model, but they provide guidance to the model + on the + + desired behavior. + + + Note that the server sets default instructions which will be used if + this + + field is not set and are visible in the `session.created` event at + the + + start of the session. + voice: + $ref: "#/components/schemas/VoiceIdsShared" + description: > + The voice the model uses to respond. Voice cannot be changed during + the + + session once the model has responded with audio at least once. + Current + + voice options are `alloy`, `ash`, `ballad`, `coral`, `echo` `sage`, + + `shimmer` and `verse`. + input_audio_format: + type: string + description: > + The format of input audio. Options are `pcm16`, `g711_ulaw`, or + `g711_alaw`. + output_audio_format: + type: string + description: > + The format of output audio. Options are `pcm16`, `g711_ulaw`, or + `g711_alaw`. + input_audio_transcription: + type: object + description: > + Configuration for input audio transcription, defaults to off and can + be + + set to `null` to turn off once on. Input audio transcription is not + native + + to the model, since the model consumes audio directly. Transcription + runs + + asynchronously through Whisper and should be treated as rough + guidance + + rather than the representation understood by the model. + properties: + model: + type: string + description: > + The model to use for transcription, `whisper-1` is the only + currently + + supported model. + turn_detection: + type: object + description: > + Configuration for turn detection. Can be set to `null` to turn off. + Server + + VAD means that the model will detect the start and end of speech + based on + + audio volume and respond at the end of user speech. + properties: + type: + type: string + description: > + Type of turn detection, only `server_vad` is currently supported. + threshold: + type: number + description: > + Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. + A + + higher threshold will require louder audio to activate the + model, and + + thus might perform better in noisy environments. + prefix_padding_ms: + type: integer + description: | + Amount of audio to include before the VAD detected speech (in + milliseconds). Defaults to 300ms. + silence_duration_ms: + type: integer + description: > + Duration of silence to detect speech stop (in milliseconds). + Defaults + + to 500ms. With shorter values the model will respond more + quickly, + + but may jump in on short pauses from the user. + tools: + type: array + description: Tools (functions) available to the model. + items: + type: object + properties: + type: + type: string + enum: + - function + description: The type of the tool, i.e. `function`. + x-stainless-const: true + name: + type: string + description: The name of the function. + description: + type: string + description: > + The description of the function, including guidance on when + and how + + to call it, and guidance about what to tell the user when + calling + + (if anything). + parameters: + type: object + description: Parameters of the function in JSON Schema. + tool_choice: + type: string + description: > + How the model chooses tools. Options are `auto`, `none`, `required`, + or + + specify a function. + temperature: + type: number + description: > + Sampling temperature for the model, limited to [0.6, 1.2]. Defaults + to 0.8. + max_response_output_tokens: + oneOf: + - type: integer + - type: string + enum: + - inf + x-stainless-const: true + description: | + Maximum number of output tokens for a single assistant response, + inclusive of tool calls. Provide an integer between 1 and 4096 to + limit output tokens, or `inf` for the maximum available tokens for a + given model. Defaults to `inf`. + required: + - client_secret + x-oaiMeta: + name: The session object + group: realtime + example: | + { + "id": "sess_001", + "object": "realtime.session", + "model": "gpt-4o-realtime-preview", + "modalities": ["audio", "text"], + "instructions": "You are a friendly assistant.", + "voice": "alloy", + "input_audio_format": "pcm16", + "output_audio_format": "pcm16", + "input_audio_transcription": { + "model": "whisper-1" + }, + "turn_detection": null, + "tools": [], + "tool_choice": "none", + "temperature": 0.7, + "max_response_output_tokens": 200, + "client_secret": { + "value": "ek_abc123", + "expires_at": 1234567890 + } + } + RealtimeTranscriptionSessionCreateRequest: + type: object + description: Realtime transcription session object configuration. + properties: + modalities: + description: | + The set of modalities the model can respond with. To disable audio, + set this to ["text"]. + items: + type: string + default: + - text + - audio + enum: + - text + - audio + input_audio_format: + type: string + default: pcm16 + enum: + - pcm16 + - g711_ulaw + - g711_alaw + description: > + The format of input audio. Options are `pcm16`, `g711_ulaw`, or + `g711_alaw`. + + For `pcm16`, input audio must be 16-bit PCM at a 24kHz sample rate, + + single channel (mono), and little-endian byte order. + input_audio_transcription: + type: object + description: > + Configuration for input audio transcription. The client can + optionally set the language and prompt for transcription, these + offer additional guidance to the transcription service. + properties: + model: + type: string + description: > + The model to use for transcription, current options are + `gpt-4o-transcribe`, `gpt-4o-mini-transcribe`, and `whisper-1`. + enum: + - gpt-4o-transcribe + - gpt-4o-mini-transcribe + - whisper-1 + language: + type: string + description: | + The language of the input audio. Supplying the input language in + [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g. `en`) format + will improve accuracy and latency. + prompt: + type: string + description: > + An optional text to guide the model's style or continue a + previous audio + + segment. + + For `whisper-1`, the [prompt is a list of + keywords](/docs/guides/speech-to-text#prompting). + + For `gpt-4o-transcribe` models, the prompt is a free text + string, for example "expect words related to technology". + turn_detection: + type: object + description: > + Configuration for turn detection, ether Server VAD or Semantic VAD. + This can be set to `null` to turn off, in which case the client must + manually trigger model response. + + Server VAD means that the model will detect the start and end of + speech based on audio volume and respond at the end of user speech. + + Semantic VAD is more advanced and uses a turn detection model (in + conjuction with VAD) to semantically estimate whether the user has + finished speaking, then dynamically sets a timeout based on this + probability. For example, if user audio trails off with "uhhm", the + model will score a low probability of turn end and wait longer for + the user to continue speaking. This can be useful for more natural + conversations, but may have a higher latency. + properties: + type: + type: string + default: server_vad + enum: + - server_vad + - semantic_vad + description: | + Type of turn detection. + eagerness: + type: string + default: auto + enum: + - low + - medium + - high + - auto + description: > + Used only for `semantic_vad` mode. The eagerness of the model to + respond. `low` will wait longer for the user to continue + speaking, `high` will respond more quickly. `auto` is the + default and is equivalent to `medium`. + threshold: + type: number + description: > + Used only for `server_vad` mode. Activation threshold for VAD + (0.0 to 1.0), this defaults to 0.5. A + + higher threshold will require louder audio to activate the + model, and + + thus might perform better in noisy environments. + prefix_padding_ms: + type: integer + description: > + Used only for `server_vad` mode. Amount of audio to include + before the VAD detected speech (in + + milliseconds). Defaults to 300ms. + silence_duration_ms: + type: integer + description: > + Used only for `server_vad` mode. Duration of silence to detect + speech stop (in milliseconds). Defaults + + to 500ms. With shorter values the model will respond more + quickly, + + but may jump in on short pauses from the user. + create_response: + type: boolean + default: true + description: > + Whether or not to automatically generate a response when a VAD + stop event occurs. Not available for transcription sessions. + interrupt_response: + type: boolean + default: true + description: > + Whether or not to automatically interrupt any ongoing response + with output to the default + + conversation (i.e. `conversation` of `auto`) when a VAD start + event occurs. Not available for transcription sessions. + input_audio_noise_reduction: + type: object + default: null + description: > + Configuration for input audio noise reduction. This can be set to + `null` to turn off. + + Noise reduction filters audio added to the input audio buffer before + it is sent to VAD and the model. + + Filtering the audio can improve VAD and turn detection accuracy + (reducing false positives) and model performance by improving + perception of the input audio. + properties: + type: + type: string + enum: + - near_field + - far_field + description: > + Type of noise reduction. `near_field` is for close-talking + microphones such as headphones, `far_field` is for far-field + microphones such as laptop or conference room microphones. + include: + type: array + items: + type: string + description: > + The set of items to include in the transcription. Current available + items are: + + - `item.input_audio_transcription.logprobs` + RealtimeTranscriptionSessionCreateResponse: + type: object + description: > + A new Realtime transcription session configuration. + + + When a session is created on the server via REST API, the session object + + also contains an ephemeral key. Default TTL for keys is one minute. + This + + property is not present when a session is updated via the WebSocket API. + properties: + client_secret: + type: object + description: | + Ephemeral key returned by the API. Only present when the session is + created on the server via REST API. + properties: + value: + type: string + description: > + Ephemeral key usable in client environments to authenticate + connections + + to the Realtime API. Use this in client-side environments rather + than + + a standard API token, which should only be used server-side. + expires_at: + type: integer + description: > + Timestamp for when the token expires. Currently, all tokens + expire + + after one minute. + required: + - value + - expires_at + modalities: + description: | + The set of modalities the model can respond with. To disable audio, + set this to ["text"]. + items: + type: string + enum: + - text + - audio + input_audio_format: + type: string + description: > + The format of input audio. Options are `pcm16`, `g711_ulaw`, or + `g711_alaw`. + input_audio_transcription: + type: object + description: | + Configuration of the transcription model. + properties: + model: + type: string + description: > + The model to use for transcription. Can be `gpt-4o-transcribe`, + `gpt-4o-mini-transcribe`, or `whisper-1`. + enum: + - gpt-4o-transcribe + - gpt-4o-mini-transcribe + - whisper-1 + language: + type: string + description: | + The language of the input audio. Supplying the input language in + [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g. `en`) format + will improve accuracy and latency. + prompt: + type: string + description: > + An optional text to guide the model's style or continue a + previous audio + + segment. The [prompt](/docs/guides/speech-to-text#prompting) + should match + + the audio language. + turn_detection: + type: object + description: > + Configuration for turn detection. Can be set to `null` to turn off. + Server + + VAD means that the model will detect the start and end of speech + based on + + audio volume and respond at the end of user speech. + properties: + type: + type: string + description: > + Type of turn detection, only `server_vad` is currently supported. + threshold: + type: number + description: > + Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. + A + + higher threshold will require louder audio to activate the + model, and + + thus might perform better in noisy environments. + prefix_padding_ms: + type: integer + description: | + Amount of audio to include before the VAD detected speech (in + milliseconds). Defaults to 300ms. + silence_duration_ms: + type: integer + description: > + Duration of silence to detect speech stop (in milliseconds). + Defaults + + to 500ms. With shorter values the model will respond more + quickly, + + but may jump in on short pauses from the user. + required: + - client_secret + x-oaiMeta: + name: The transcription session object + group: realtime + example: | + { + "id": "sess_BBwZc7cFV3XizEyKGDCGL", + "object": "realtime.transcription_session", + "expires_at": 1742188264, + "modalities": ["audio", "text"], + "turn_detection": { + "type": "server_vad", + "threshold": 0.5, + "prefix_padding_ms": 300, + "silence_duration_ms": 200 + }, + "input_audio_format": "pcm16", + "input_audio_transcription": { + "model": "gpt-4o-transcribe", + "language": null, + "prompt": "" + }, + "client_secret": null + } + Reasoning: + type: object + description: | + **o-series models only** + + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). + title: Reasoning + properties: + effort: + $ref: "#/components/schemas/ReasoningEffort" + summary: + type: string + description: > + A summary of the reasoning performed by the model. This can be + + useful for debugging and understanding the model's reasoning + process. + + One of `auto`, `concise`, or `detailed`. + enum: + - auto + - concise + - detailed + nullable: true + generate_summary: + type: string + deprecated: true + description: > + **Deprecated:** use `summary` instead. + + + A summary of the reasoning performed by the model. This can be + + useful for debugging and understanding the model's reasoning + process. + + One of `auto`, `concise`, or `detailed`. + enum: + - auto + - concise + - detailed + nullable: true + ReasoningEffort: + type: string + enum: + - low + - medium + - high + default: medium + nullable: true + description: | + **o-series models only** + + Constrains effort on reasoning for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). + Currently supported values are `low`, `medium`, and `high`. Reducing + reasoning effort can result in faster responses and fewer tokens used + on reasoning in a response. + ReasoningItem: + type: object + description: > + A description of the chain of thought used by a reasoning model while + generating + + a response. + title: Reasoning + properties: + type: + type: string + description: | + The type of the object. Always `reasoning`. + enum: + - reasoning + x-stainless-const: true + id: + type: string + description: | + The unique identifier of the reasoning content. + summary: + type: array + description: | + Reasoning text contents. + items: + type: object + properties: + type: + type: string + description: | + The type of the object. Always `summary_text`. + enum: + - summary_text + x-stainless-const: true + text: + type: string + description: > + A short summary of the reasoning used by the model when + generating + + the response. + required: + - type + - text + status: + type: string + description: | + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + enum: + - in_progress + - completed + - incomplete + required: + - id + - summary + - type + Response: + allOf: + - $ref: "#/components/schemas/ModelResponseProperties" + - $ref: "#/components/schemas/ResponseProperties" + - type: object + properties: + id: + type: string + description: | + Unique identifier for this Response. + object: + type: string + description: | + The object type of this resource - always set to `response`. + enum: + - response + x-stainless-const: true + status: + type: string + description: > + The status of the response generation. One of `completed`, + `failed`, + + `in_progress`, or `incomplete`. + enum: + - completed + - failed + - in_progress + - incomplete + created_at: + type: number + description: | + Unix timestamp (in seconds) of when this Response was created. + error: + $ref: "#/components/schemas/ResponseError" + incomplete_details: + type: object + nullable: true + description: | + Details about why the response is incomplete. + properties: + reason: + type: string + description: The reason why the response is incomplete. + enum: + - max_output_tokens + - content_filter + output: + type: array + description: > + An array of content items generated by the model. + + + - The length and order of items in the `output` array is + dependent + on the model's response. + - Rather than accessing the first item in the `output` array + and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. + items: + $ref: "#/components/schemas/OutputItem" + output_text: + type: string + nullable: true + description: > + SDK-only convenience property that contains the aggregated text + output + + from all `output_text` items in the `output` array, if any are + present. + + Supported in the Python and JavaScript SDKs. + x-oaiSupportedSDKs: + - python + - javascript + usage: + $ref: "#/components/schemas/ResponseUsage" + parallel_tool_calls: + type: boolean + description: | + Whether to allow the model to run tool calls in parallel. + default: true + required: + - id + - object + - created_at + - error + - incomplete_details + - instructions + - model + - tools + - output + - parallel_tool_calls + - metadata + - tool_choice + - temperature + - top_p + x-oaiMeta: + name: The response object + group: responses + example: > + { + "id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41", + "object": "response", + "created_at": 1741476777, + "status": "completed", + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4o-2024-08-06", + "output": [ + { + "type": "message", + "id": "msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "The image depicts a scenic landscape with a wooden boardwalk or pathway leading through lush, green grass under a blue sky with some clouds. The setting suggests a peaceful natural area, possibly a park or nature reserve. There are trees and shrubs in the background.", + "annotations": [] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 328, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 52, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 380 + }, + "user": null, + "metadata": {} + } + ResponseAudioDeltaEvent: + type: object + description: Emitted when there is a partial audio response. + properties: + type: + type: string + description: | + The type of the event. Always `response.audio.delta`. + enum: + - response.audio.delta + x-stainless-const: true + delta: + type: string + description: | + A chunk of Base64 encoded response audio bytes. + required: + - type + - delta + x-oaiMeta: + name: response.audio.delta + group: responses + example: | + { + "type": "response.audio.delta", + "response_id": "resp_123", + "delta": "base64encoded..." + } + ResponseAudioDoneEvent: + type: object + description: Emitted when the audio response is complete. + properties: + type: + type: string + description: | + The type of the event. Always `response.audio.done`. + enum: + - response.audio.done + x-stainless-const: true + required: + - type + - response_id + x-oaiMeta: + name: response.audio.done + group: responses + example: | + { + "type": "response.audio.done", + "response_id": "resp-123" + } + ResponseAudioTranscriptDeltaEvent: + type: object + description: Emitted when there is a partial transcript of audio. + properties: + type: + type: string + description: | + The type of the event. Always `response.audio.transcript.delta`. + enum: + - response.audio.transcript.delta + x-stainless-const: true + delta: + type: string + description: | + The partial transcript of the audio response. + required: + - type + - response_id + - delta + x-oaiMeta: + name: response.audio.transcript.delta + group: responses + example: | + { + "type": "response.audio.transcript.delta", + "response_id": "resp_123", + "delta": " ... partial transcript ... " + } + ResponseAudioTranscriptDoneEvent: + type: object + description: Emitted when the full audio transcript is completed. + properties: + type: + type: string + description: | + The type of the event. Always `response.audio.transcript.done`. + enum: + - response.audio.transcript.done + x-stainless-const: true + required: + - type + - response_id + x-oaiMeta: + name: response.audio.transcript.done + group: responses + example: | + { + "type": "response.audio.transcript.done", + "response_id": "resp_123" + } + ResponseCodeInterpreterCallCodeDeltaEvent: + type: object + description: Emitted when a partial code snippet is added by the code interpreter. + properties: + type: + type: string + description: > + The type of the event. Always + `response.code_interpreter_call.code.delta`. + enum: + - response.code_interpreter_call.code.delta + x-stainless-const: true + output_index: + type: integer + description: > + The index of the output item that the code interpreter call is in + progress. + delta: + type: string + description: | + The partial code snippet added by the code interpreter. + required: + - type + - response_id + - output_index + - delta + x-oaiMeta: + name: response.code_interpreter_call.code.delta + group: responses + example: | + { + "type": "response.code_interpreter_call.code.delta", + "response_id": "resp-123", + "output_index": 0, + "delta": "partial code" + } + ResponseCodeInterpreterCallCodeDoneEvent: + type: object + description: Emitted when code snippet output is finalized by the code interpreter. + properties: + type: + type: string + description: > + The type of the event. Always + `response.code_interpreter_call.code.done`. + enum: + - response.code_interpreter_call.code.done + x-stainless-const: true + output_index: + type: integer + description: > + The index of the output item that the code interpreter call is in + progress. + code: + type: string + description: | + The final code snippet output by the code interpreter. + required: + - type + - response_id + - output_index + - code + x-oaiMeta: + name: response.code_interpreter_call.code.done + group: responses + example: | + { + "type": "response.code_interpreter_call.code.done", + "response_id": "resp-123", + "output_index": 3, + "code": "console.log('done');" + } + ResponseCodeInterpreterCallCompletedEvent: + type: object + description: Emitted when the code interpreter call is completed. + properties: + type: + type: string + description: > + The type of the event. Always + `response.code_interpreter_call.completed`. + enum: + - response.code_interpreter_call.completed + x-stainless-const: true + output_index: + type: integer + description: > + The index of the output item that the code interpreter call is in + progress. + code_interpreter_call: + $ref: "#/components/schemas/CodeInterpreterToolCall" + required: + - type + - response_id + - output_index + - code_interpreter_call + x-oaiMeta: + name: response.code_interpreter_call.completed + group: responses + example: | + { + "type": "response.code_interpreter_call.completed", + "response_id": "resp-123", + "output_index": 5, + "code_interpreter_call": {} + } + ResponseCodeInterpreterCallInProgressEvent: + type: object + description: Emitted when a code interpreter call is in progress. + properties: + type: + type: string + description: > + The type of the event. Always + `response.code_interpreter_call.in_progress`. + enum: + - response.code_interpreter_call.in_progress + x-stainless-const: true + output_index: + type: integer + description: > + The index of the output item that the code interpreter call is in + progress. + code_interpreter_call: + $ref: "#/components/schemas/CodeInterpreterToolCall" + required: + - type + - response_id + - output_index + - code_interpreter_call + x-oaiMeta: + name: response.code_interpreter_call.in_progress + group: responses + example: | + { + "type": "response.code_interpreter_call.in.progress", + "response_id": "resp-123", + "output_index": 0, + "code_interpreter_call": {} + } + ResponseCodeInterpreterCallInterpretingEvent: + type: object + description: Emitted when the code interpreter is actively interpreting the code + snippet. + properties: + type: + type: string + description: > + The type of the event. Always + `response.code_interpreter_call.interpreting`. + enum: + - response.code_interpreter_call.interpreting + x-stainless-const: true + output_index: + type: integer + description: > + The index of the output item that the code interpreter call is in + progress. + code_interpreter_call: + $ref: "#/components/schemas/CodeInterpreterToolCall" + required: + - type + - response_id + - output_index + - code_interpreter_call + x-oaiMeta: + name: response.code_interpreter_call.interpreting + group: responses + example: | + { + "type": "response.code_interpreter_call.interpreting", + "response_id": "resp-123", + "output_index": 4, + "code_interpreter_call": {} + } + ResponseCompletedEvent: + type: object + description: Emitted when the model response is complete. + properties: + type: + type: string + description: | + The type of the event. Always `response.completed`. + enum: + - response.completed + x-stainless-const: true + response: + $ref: "#/components/schemas/Response" + description: | + Properties of the completed response. + required: + - type + - response + x-oaiMeta: + name: response.completed + group: responses + example: > + { + "type": "response.completed", + "response": { + "id": "resp_123", + "object": "response", + "created_at": 1740855869, + "status": "completed", + "error": null, + "incomplete_details": null, + "input": [], + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4o-mini-2024-07-18", + "output": [ + { + "id": "msg_123", + "type": "message", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.", + "annotations": [] + } + ] + } + ], + "previous_response_id": null, + "reasoning_effort": null, + "store": false, + "temperature": 1, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1, + "truncation": "disabled", + "usage": { + "input_tokens": 0, + "output_tokens": 0, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 0 + }, + "user": null, + "metadata": {} + } + } + ResponseContentPartAddedEvent: + type: object + description: Emitted when a new content part is added. + properties: + type: + type: string + description: | + The type of the event. Always `response.content_part.added`. + enum: + - response.content_part.added + x-stainless-const: true + item_id: + type: string + description: | + The ID of the output item that the content part was added to. + output_index: + type: integer + description: | + The index of the output item that the content part was added to. + content_index: + type: integer + description: | + The index of the content part that was added. + part: + $ref: "#/components/schemas/OutputContent" + description: | + The content part that was added. + required: + - type + - item_id + - output_index + - content_index + - part + x-oaiMeta: + name: response.content_part.added + group: responses + example: | + { + "type": "response.content_part.added", + "item_id": "msg_123", + "output_index": 0, + "content_index": 0, + "part": { + "type": "output_text", + "text": "", + "annotations": [] + } + } + ResponseContentPartDoneEvent: + type: object + description: Emitted when a content part is done. + properties: + type: + type: string + description: | + The type of the event. Always `response.content_part.done`. + enum: + - response.content_part.done + x-stainless-const: true + item_id: + type: string + description: | + The ID of the output item that the content part was added to. + output_index: + type: integer + description: | + The index of the output item that the content part was added to. + content_index: + type: integer + description: | + The index of the content part that is done. + part: + $ref: "#/components/schemas/OutputContent" + description: | + The content part that is done. + required: + - type + - item_id + - output_index + - content_index + - part + x-oaiMeta: + name: response.content_part.done + group: responses + example: > + { + "type": "response.content_part.done", + "item_id": "msg_123", + "output_index": 0, + "content_index": 0, + "part": { + "type": "output_text", + "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.", + "annotations": [] + } + } + ResponseCreatedEvent: + type: object + description: | + An event that is emitted when a response is created. + properties: + type: + type: string + description: | + The type of the event. Always `response.created`. + enum: + - response.created + x-stainless-const: true + response: + $ref: "#/components/schemas/Response" + description: | + The response that was created. + required: + - type + - response + x-oaiMeta: + name: response.created + group: responses + example: | + { + "type": "response.created", + "response": { + "id": "resp_67ccfcdd16748190a91872c75d38539e09e4d4aac714747c", + "object": "response", + "created_at": 1741487325, + "status": "in_progress", + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4o-2024-08-06", + "output": [], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1, + "truncation": "disabled", + "usage": null, + "user": null, + "metadata": {} + } + } + ResponseError: + type: object + description: | + An error object returned when the model fails to generate a Response. + nullable: true + properties: + code: + $ref: "#/components/schemas/ResponseErrorCode" + message: + type: string + description: | + A human-readable description of the error. + required: + - code + - message + ResponseErrorCode: + type: string + description: | + The error code for the response. + enum: + - server_error + - rate_limit_exceeded + - invalid_prompt + - vector_store_timeout + - invalid_image + - invalid_image_format + - invalid_base64_image + - invalid_image_url + - image_too_large + - image_too_small + - image_parse_error + - image_content_policy_violation + - invalid_image_mode + - image_file_too_large + - unsupported_image_media_type + - empty_image_file + - failed_to_download_image + - image_file_not_found + ResponseErrorEvent: + type: object + description: Emitted when an error occurs. + properties: + type: + type: string + description: | + The type of the event. Always `error`. + enum: + - error + x-stainless-const: true + code: + type: string + description: | + The error code. + nullable: true + message: + type: string + description: | + The error message. + param: + type: string + description: | + The error parameter. + nullable: true + required: + - type + - code + - message + - param + x-oaiMeta: + name: error + group: responses + example: | + { + "type": "error", + "code": "ERR_SOMETHING", + "message": "Something went wrong", + "param": null + } + ResponseFailedEvent: + type: object + description: | + An event that is emitted when a response fails. + properties: + type: + type: string + description: | + The type of the event. Always `response.failed`. + enum: + - response.failed + x-stainless-const: true + response: + $ref: "#/components/schemas/Response" + description: | + The response that failed. + required: + - type + - response + x-oaiMeta: + name: response.failed + group: responses + example: | + { + "type": "response.failed", + "response": { + "id": "resp_123", + "object": "response", + "created_at": 1740855869, + "status": "failed", + "error": { + "code": "server_error", + "message": "The model failed to generate a response." + }, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4o-mini-2024-07-18", + "output": [], + "previous_response_id": null, + "reasoning_effort": null, + "store": false, + "temperature": 1, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1, + "truncation": "disabled", + "usage": null, + "user": null, + "metadata": {} + } + } + ResponseFileSearchCallCompletedEvent: + type: object + description: Emitted when a file search call is completed (results found). + properties: + type: + type: string + description: | + The type of the event. Always `response.file_search_call.completed`. + enum: + - response.file_search_call.completed + x-stainless-const: true + output_index: + type: integer + description: | + The index of the output item that the file search call is initiated. + item_id: + type: string + description: | + The ID of the output item that the file search call is initiated. + required: + - type + - output_index + - item_id + x-oaiMeta: + name: response.file_search_call.completed + group: responses + example: | + { + "type": "response.file_search_call.completed", + "output_index": 0, + "item_id": "fs_123", + } + ResponseFileSearchCallInProgressEvent: + type: object + description: Emitted when a file search call is initiated. + properties: + type: + type: string + description: > + The type of the event. Always + `response.file_search_call.in_progress`. + enum: + - response.file_search_call.in_progress + x-stainless-const: true + output_index: + type: integer + description: | + The index of the output item that the file search call is initiated. + item_id: + type: string + description: | + The ID of the output item that the file search call is initiated. + required: + - type + - output_index + - item_id + x-oaiMeta: + name: response.file_search_call.in_progress + group: responses + example: | + { + "type": "response.file_search_call.in_progress", + "output_index": 0, + "item_id": "fs_123", + } + ResponseFileSearchCallSearchingEvent: + type: object + description: Emitted when a file search is currently searching. + properties: + type: + type: string + description: | + The type of the event. Always `response.file_search_call.searching`. + enum: + - response.file_search_call.searching + x-stainless-const: true + output_index: + type: integer + description: | + The index of the output item that the file search call is searching. + item_id: + type: string + description: | + The ID of the output item that the file search call is initiated. + required: + - type + - output_index + - item_id + x-oaiMeta: + name: response.file_search_call.searching + group: responses + example: | + { + "type": "response.file_search_call.searching", + "output_index": 0, + "item_id": "fs_123", + } + ResponseFormatJsonObject: + type: object + title: JSON object + description: > + JSON object response format. An older method of generating JSON + responses. + + Using `json_schema` is recommended for models that support it. Note that + the + + model will not generate JSON without a system or user message + instructing it + + to do so. + properties: + type: + type: string + description: The type of response format being defined. Always `json_object`. + enum: + - json_object + x-stainless-const: true + required: + - type + ResponseFormatJsonSchema: + type: object + title: JSON schema + description: | + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). + properties: + type: + type: string + description: The type of response format being defined. Always `json_schema`. + enum: + - json_schema + x-stainless-const: true + json_schema: + type: object + title: JSON schema + description: | + Structured Outputs configuration options, including a JSON Schema. + properties: + description: + type: string + description: > + A description of what the response format is for, used by the + model to + + determine how to respond in the format. + name: + type: string + description: > + The name of the response format. Must be a-z, A-Z, 0-9, or + contain + + underscores and dashes, with a maximum length of 64. + schema: + $ref: "#/components/schemas/ResponseFormatJsonSchemaSchema" + strict: + type: boolean + nullable: true + default: false + description: > + Whether to enable strict schema adherence when generating the + output. + + If set to true, the model will always follow the exact schema + defined + + in the `schema` field. Only a subset of JSON Schema is supported + when + + `strict` is `true`. To learn more, read the [Structured Outputs + + guide](/docs/guides/structured-outputs). + required: + - name + required: + - type + - json_schema + ResponseFormatJsonSchemaSchema: + type: object + title: JSON schema + description: | + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). + additionalProperties: true + ResponseFormatText: + type: object + title: Text + description: | + Default response format. Used to generate text responses. + properties: + type: + type: string + description: The type of response format being defined. Always `text`. + enum: + - text + x-stainless-const: true + required: + - type + ResponseFunctionCallArgumentsDeltaEvent: + type: object + description: Emitted when there is a partial function-call arguments delta. + properties: + type: + type: string + description: > + The type of the event. Always + `response.function_call_arguments.delta`. + enum: + - response.function_call_arguments.delta + x-stainless-const: true + item_id: + type: string + description: > + The ID of the output item that the function-call arguments delta is + added to. + output_index: + type: integer + description: > + The index of the output item that the function-call arguments delta + is added to. + delta: + type: string + description: | + The function-call arguments delta that is added. + required: + - type + - item_id + - output_index + - delta + x-oaiMeta: + name: response.function_call_arguments.delta + group: responses + example: | + { + "type": "response.function_call_arguments.delta", + "item_id": "item-abc", + "output_index": 0, + "delta": "{ \"arg\":" + } + ResponseFunctionCallArgumentsDoneEvent: + type: object + description: Emitted when function-call arguments are finalized. + properties: + type: + type: string + enum: + - response.function_call_arguments.done + x-stainless-const: true + item_id: + type: string + description: The ID of the item. + output_index: + type: integer + description: The index of the output item. + arguments: + type: string + description: The function-call arguments. + required: + - type + - item_id + - output_index + - arguments + x-oaiMeta: + name: response.function_call_arguments.done + group: responses + example: | + { + "type": "response.function_call_arguments.done", + "item_id": "item-abc", + "output_index": 1, + "arguments": "{ \"arg\": 123 }" + } + ResponseInProgressEvent: + type: object + description: Emitted when the response is in progress. + properties: + type: + type: string + description: | + The type of the event. Always `response.in_progress`. + enum: + - response.in_progress + x-stainless-const: true + response: + $ref: "#/components/schemas/Response" + description: | + The response that is in progress. + required: + - type + - response + x-oaiMeta: + name: response.in_progress + group: responses + example: | + { + "type": "response.in_progress", + "response": { + "id": "resp_67ccfcdd16748190a91872c75d38539e09e4d4aac714747c", + "object": "response", + "created_at": 1741487325, + "status": "in_progress", + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4o-2024-08-06", + "output": [], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1, + "truncation": "disabled", + "usage": null, + "user": null, + "metadata": {} + } + } + ResponseIncompleteEvent: + type: object + description: | + An event that is emitted when a response finishes as incomplete. + properties: + type: + type: string + description: | + The type of the event. Always `response.incomplete`. + enum: + - response.incomplete + x-stainless-const: true + response: + $ref: "#/components/schemas/Response" + description: | + The response that was incomplete. + required: + - type + - response + x-oaiMeta: + name: response.incomplete + group: responses + example: | + { + "type": "response.incomplete", + "response": { + "id": "resp_123", + "object": "response", + "created_at": 1740855869, + "status": "incomplete", + "error": null, + "incomplete_details": { + "reason": "max_tokens" + }, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4o-mini-2024-07-18", + "output": [], + "previous_response_id": null, + "reasoning_effort": null, + "store": false, + "temperature": 1, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1, + "truncation": "disabled", + "usage": null, + "user": null, + "metadata": {} + } + } + ResponseItemList: + type: object + description: A list of Response items. + properties: + object: + type: string + description: The type of object returned, must be `list`. + enum: + - list + x-stainless-const: true + data: + type: array + description: A list of items used to generate this response. + items: + $ref: "#/components/schemas/ItemResource" + has_more: + type: boolean + description: Whether there are more items available. + first_id: + type: string + description: The ID of the first item in the list. + last_id: + type: string + description: The ID of the last item in the list. + required: + - object + - data + - has_more + - first_id + - last_id + x-oaiMeta: + name: The input item list + group: responses + example: > + { + "object": "list", + "data": [ + { + "id": "msg_abc123", + "type": "message", + "role": "user", + "content": [ + { + "type": "input_text", + "text": "Tell me a three sentence bedtime story about a unicorn." + } + ] + } + ], + "first_id": "msg_abc123", + "last_id": "msg_abc123", + "has_more": false + } + ResponseModalities: + type: array + nullable: true + description: > + Output types that you would like the model to generate. + + Most models are capable of generating text, which is the default: + + + `["text"]` + + + The `gpt-4o-audio-preview` model can also be used to + + [generate audio](/docs/guides/audio). To request that this model + generate + + both text and audio responses, you can use: + + + `["text", "audio"]` + items: + type: string + enum: + - text + - audio + ResponseOutputItemAddedEvent: + type: object + description: Emitted when a new output item is added. + properties: + type: + type: string + description: | + The type of the event. Always `response.output_item.added`. + enum: + - response.output_item.added + x-stainless-const: true + output_index: + type: integer + description: | + The index of the output item that was added. + item: + $ref: "#/components/schemas/OutputItem" + description: | + The output item that was added. + required: + - type + - output_index + - item + x-oaiMeta: + name: response.output_item.added + group: responses + example: | + { + "type": "response.output_item.added", + "output_index": 0, + "item": { + "id": "msg_123", + "status": "in_progress", + "type": "message", + "role": "assistant", + "content": [] + } + } + ResponseOutputItemDoneEvent: + type: object + description: Emitted when an output item is marked done. + properties: + type: + type: string + description: | + The type of the event. Always `response.output_item.done`. + enum: + - response.output_item.done + x-stainless-const: true + output_index: + type: integer + description: | + The index of the output item that was marked done. + item: + $ref: "#/components/schemas/OutputItem" + description: | + The output item that was marked done. + required: + - type + - output_index + - item + x-oaiMeta: + name: response.output_item.done + group: responses + example: > + { + "type": "response.output_item.done", + "output_index": 0, + "item": { + "id": "msg_123", + "status": "completed", + "type": "message", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.", + "annotations": [] + } + ] + } + } + ResponseProperties: + type: object + properties: + previous_response_id: + type: string + description: | + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](/docs/guides/conversation-state). + nullable: true + model: + description: > + Model ID used to generate the response, like `gpt-4o` or `o3`. + OpenAI + + offers a wide range of models with different capabilities, + performance + + characteristics, and price points. Refer to the [model + guide](/docs/models) + + to browse and compare available models. + $ref: "#/components/schemas/ModelIdsResponses" + reasoning: + $ref: "#/components/schemas/Reasoning" + nullable: true + max_output_tokens: + description: > + An upper bound for the number of tokens that can be generated for a + response, including visible output tokens and [reasoning + tokens](/docs/guides/reasoning). + type: integer + nullable: true + instructions: + type: string + description: > + Inserts a system (or developer) message as the first item in the + model's context. + + + When using along with `previous_response_id`, the instructions from + a previous + + response will not be carried over to the next response. This makes + it simple + + to swap out system (or developer) messages in new responses. + nullable: true + text: + type: object + description: > + Configuration options for a text response from the model. Can be + plain + + text or structured JSON data. Learn more: + + - [Text inputs and outputs](/docs/guides/text) + + - [Structured Outputs](/docs/guides/structured-outputs) + properties: + format: + $ref: "#/components/schemas/TextResponseFormatConfiguration" + tools: + type: array + description: > + An array of tools the model may call while generating a response. + You + + can specify which tool to use by setting the `tool_choice` + parameter. + + + The two categories of tools you can provide the model are: + + + - **Built-in tools**: Tools that are provided by OpenAI that extend + the + model's capabilities, like [web search](/docs/guides/tools-web-search) + or [file search](/docs/guides/tools-file-search). Learn more about + [built-in tools](/docs/guides/tools). + - **Function calls (custom tools)**: Functions that are defined by + you, + enabling the model to call your own code. Learn more about + [function calling](/docs/guides/function-calling). + items: + $ref: "#/components/schemas/Tool" + tool_choice: + description: > + How the model should select which tool (or tools) to use when + generating + + a response. See the `tools` parameter to see how to specify which + tools + + the model can call. + oneOf: + - $ref: "#/components/schemas/ToolChoiceOptions" + - $ref: "#/components/schemas/ToolChoiceTypes" + - $ref: "#/components/schemas/ToolChoiceFunction" + truncation: + type: string + description: > + The truncation strategy to use for the model response. + + - `auto`: If the context of this response and previous ones exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping input items in the + middle of the conversation. + - `disabled` (default): If a model response will exceed the context + window + size for a model, the request will fail with a 400 error. + enum: + - auto + - disabled + nullable: true + default: disabled + ResponseReasoningSummaryPartAddedEvent: + type: object + description: Emitted when a new reasoning summary part is added. + properties: + type: + type: string + description: > + The type of the event. Always + `response.reasoning_summary_part.added`. + enum: + - response.reasoning_summary_part.added + x-stainless-const: true + item_id: + type: string + description: | + The ID of the item this summary part is associated with. + output_index: + type: integer + description: | + The index of the output item this summary part is associated with. + summary_index: + type: integer + description: | + The index of the summary part within the reasoning summary. + part: + type: object + description: | + The summary part that was added. + properties: + type: + type: string + description: The type of the summary part. Always `summary_text`. + enum: + - summary_text + x-stainless-const: true + text: + type: string + description: The text of the summary part. + required: + - type + - text + required: + - type + - item_id + - output_index + - summary_index + - part + x-oaiMeta: + name: response.reasoning_summary_part.added + group: responses + example: | + { + "type": "response.reasoning_summary_part.added", + "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476", + "output_index": 0, + "summary_index": 0, + "part": { + "type": "summary_text", + "text": "" + } + } + ResponseReasoningSummaryPartDoneEvent: + type: object + description: Emitted when a reasoning summary part is completed. + properties: + type: + type: string + description: > + The type of the event. Always `response.reasoning_summary_part.done`. + enum: + - response.reasoning_summary_part.done + x-stainless-const: true + item_id: + type: string + description: | + The ID of the item this summary part is associated with. + output_index: + type: integer + description: | + The index of the output item this summary part is associated with. + summary_index: + type: integer + description: | + The index of the summary part within the reasoning summary. + part: + type: object + description: | + The completed summary part. + properties: + type: + type: string + description: The type of the summary part. Always `summary_text`. + enum: + - summary_text + x-stainless-const: true + text: + type: string + description: The text of the summary part. + required: + - type + - text + required: + - type + - item_id + - output_index + - summary_index + - part + x-oaiMeta: + name: response.reasoning_summary_part.done + group: responses + example: > + { + "type": "response.reasoning_summary_part.done", + "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476", + "output_index": 0, + "summary_index": 0, + "part": { + "type": "summary_text", + "text": "**Responding to a greeting**\n\nThe user just said, \"Hello!\" So, it seems I need to engage. I'll greet them back and offer help since they're looking to chat. I could say something like, \"Hello! How can I assist you today?\" That feels friendly and open. They didn't ask a specific question, so this approach will work well for starting a conversation. Let's see where it goes from there!" + } + } + ResponseReasoningSummaryTextDeltaEvent: + type: object + description: Emitted when a delta is added to a reasoning summary text. + properties: + type: + type: string + description: > + The type of the event. Always + `response.reasoning_summary_text.delta`. + enum: + - response.reasoning_summary_text.delta + x-stainless-const: true + item_id: + type: string + description: | + The ID of the item this summary text delta is associated with. + output_index: + type: integer + description: > + The index of the output item this summary text delta is associated + with. + summary_index: + type: integer + description: | + The index of the summary part within the reasoning summary. + delta: + type: string + description: | + The text delta that was added to the summary. + required: + - type + - item_id + - output_index + - summary_index + - delta + x-oaiMeta: + name: response.reasoning_summary_text.delta + group: responses + example: | + { + "type": "response.reasoning_summary_text.delta", + "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476", + "output_index": 0, + "summary_index": 0, + "delta": "**Respond" + } + ResponseReasoningSummaryTextDoneEvent: + type: object + description: Emitted when a reasoning summary text is completed. + properties: + type: + type: string + description: > + The type of the event. Always `response.reasoning_summary_text.done`. + enum: + - response.reasoning_summary_text.done + x-stainless-const: true + item_id: + type: string + description: | + The ID of the item this summary text is associated with. + output_index: + type: integer + description: | + The index of the output item this summary text is associated with. + summary_index: + type: integer + description: | + The index of the summary part within the reasoning summary. + text: + type: string + description: | + The full text of the completed reasoning summary. + required: + - type + - item_id + - output_index + - summary_index + - text + x-oaiMeta: + name: response.reasoning_summary_text.done + group: responses + example: > + { + "type": "response.reasoning_summary_text.done", + "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476", + "output_index": 0, + "summary_index": 0, + "text": "**Responding to a greeting**\n\nThe user just said, \"Hello!\" So, it seems I need to engage. I'll greet them back and offer help since they're looking to chat. I could say something like, \"Hello! How can I assist you today?\" That feels friendly and open. They didn't ask a specific question, so this approach will work well for starting a conversation. Let's see where it goes from there!" + } + ResponseRefusalDeltaEvent: + type: object + description: Emitted when there is a partial refusal text. + properties: + type: + type: string + description: | + The type of the event. Always `response.refusal.delta`. + enum: + - response.refusal.delta + x-stainless-const: true + item_id: + type: string + description: | + The ID of the output item that the refusal text is added to. + output_index: + type: integer + description: | + The index of the output item that the refusal text is added to. + content_index: + type: integer + description: | + The index of the content part that the refusal text is added to. + delta: + type: string + description: | + The refusal text that is added. + required: + - type + - item_id + - output_index + - content_index + - delta + x-oaiMeta: + name: response.refusal.delta + group: responses + example: | + { + "type": "response.refusal.delta", + "item_id": "msg_123", + "output_index": 0, + "content_index": 0, + "delta": "refusal text so far" + } + ResponseRefusalDoneEvent: + type: object + description: Emitted when refusal text is finalized. + properties: + type: + type: string + description: | + The type of the event. Always `response.refusal.done`. + enum: + - response.refusal.done + x-stainless-const: true + item_id: + type: string + description: | + The ID of the output item that the refusal text is finalized. + output_index: + type: integer + description: | + The index of the output item that the refusal text is finalized. + content_index: + type: integer + description: | + The index of the content part that the refusal text is finalized. + refusal: + type: string + description: | + The refusal text that is finalized. + required: + - type + - item_id + - output_index + - content_index + - refusal + x-oaiMeta: + name: response.refusal.done + group: responses + example: | + { + "type": "response.refusal.done", + "item_id": "item-abc", + "output_index": 1, + "content_index": 2, + "refusal": "final refusal text" + } + ResponseStreamEvent: + anyOf: + - $ref: "#/components/schemas/ResponseAudioDeltaEvent" + - $ref: "#/components/schemas/ResponseAudioDoneEvent" + - $ref: "#/components/schemas/ResponseAudioTranscriptDeltaEvent" + - $ref: "#/components/schemas/ResponseAudioTranscriptDoneEvent" + - $ref: "#/components/schemas/ResponseCodeInterpreterCallCodeDeltaEvent" + - $ref: "#/components/schemas/ResponseCodeInterpreterCallCodeDoneEvent" + - $ref: "#/components/schemas/ResponseCodeInterpreterCallCompletedEvent" + - $ref: "#/components/schemas/ResponseCodeInterpreterCallInProgressEvent" + - $ref: "#/components/schemas/ResponseCodeInterpreterCallInterpretingEvent" + - $ref: "#/components/schemas/ResponseCompletedEvent" + - $ref: "#/components/schemas/ResponseContentPartAddedEvent" + - $ref: "#/components/schemas/ResponseContentPartDoneEvent" + - $ref: "#/components/schemas/ResponseCreatedEvent" + - $ref: "#/components/schemas/ResponseErrorEvent" + - $ref: "#/components/schemas/ResponseFileSearchCallCompletedEvent" + - $ref: "#/components/schemas/ResponseFileSearchCallInProgressEvent" + - $ref: "#/components/schemas/ResponseFileSearchCallSearchingEvent" + - $ref: "#/components/schemas/ResponseFunctionCallArgumentsDeltaEvent" + - $ref: "#/components/schemas/ResponseFunctionCallArgumentsDoneEvent" + - $ref: "#/components/schemas/ResponseInProgressEvent" + - $ref: "#/components/schemas/ResponseFailedEvent" + - $ref: "#/components/schemas/ResponseIncompleteEvent" + - $ref: "#/components/schemas/ResponseOutputItemAddedEvent" + - $ref: "#/components/schemas/ResponseOutputItemDoneEvent" + - $ref: "#/components/schemas/ResponseReasoningSummaryPartAddedEvent" + - $ref: "#/components/schemas/ResponseReasoningSummaryPartDoneEvent" + - $ref: "#/components/schemas/ResponseReasoningSummaryTextDeltaEvent" + - $ref: "#/components/schemas/ResponseReasoningSummaryTextDoneEvent" + - $ref: "#/components/schemas/ResponseRefusalDeltaEvent" + - $ref: "#/components/schemas/ResponseRefusalDoneEvent" + - $ref: "#/components/schemas/ResponseTextAnnotationDeltaEvent" + - $ref: "#/components/schemas/ResponseTextDeltaEvent" + - $ref: "#/components/schemas/ResponseTextDoneEvent" + - $ref: "#/components/schemas/ResponseWebSearchCallCompletedEvent" + - $ref: "#/components/schemas/ResponseWebSearchCallInProgressEvent" + - $ref: "#/components/schemas/ResponseWebSearchCallSearchingEvent" + discriminator: + propertyName: type + ResponseTextAnnotationDeltaEvent: + type: object + description: Emitted when a text annotation is added. + properties: + type: + type: string + description: > + The type of the event. Always + `response.output_text.annotation.added`. + enum: + - response.output_text.annotation.added + x-stainless-const: true + item_id: + type: string + description: | + The ID of the output item that the text annotation was added to. + output_index: + type: integer + description: | + The index of the output item that the text annotation was added to. + content_index: + type: integer + description: | + The index of the content part that the text annotation was added to. + annotation_index: + type: integer + description: | + The index of the annotation that was added. + annotation: + $ref: "#/components/schemas/Annotation" + required: + - type + - item_id + - output_index + - content_index + - annotation_index + - annotation + x-oaiMeta: + name: response.output_text.annotation.added + group: responses + example: | + { + "type": "response.output_text.annotation.added", + "item_id": "msg_abc123", + "output_index": 1, + "content_index": 0, + "annotation_index": 0, + "annotation": { + "type": "file_citation", + "index": 390, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + } + } + ResponseTextDeltaEvent: + type: object + description: Emitted when there is an additional text delta. + properties: + type: + type: string + description: | + The type of the event. Always `response.output_text.delta`. + enum: + - response.output_text.delta + x-stainless-const: true + item_id: + type: string + description: | + The ID of the output item that the text delta was added to. + output_index: + type: integer + description: | + The index of the output item that the text delta was added to. + content_index: + type: integer + description: | + The index of the content part that the text delta was added to. + delta: + type: string + description: | + The text delta that was added. + required: + - type + - item_id + - output_index + - content_index + - delta + x-oaiMeta: + name: response.output_text.delta + group: responses + example: | + { + "type": "response.output_text.delta", + "item_id": "msg_123", + "output_index": 0, + "content_index": 0, + "delta": "In" + } + ResponseTextDoneEvent: + type: object + description: Emitted when text content is finalized. + properties: + type: + type: string + description: | + The type of the event. Always `response.output_text.done`. + enum: + - response.output_text.done + x-stainless-const: true + item_id: + type: string + description: | + The ID of the output item that the text content is finalized. + output_index: + type: integer + description: | + The index of the output item that the text content is finalized. + content_index: + type: integer + description: | + The index of the content part that the text content is finalized. + text: + type: string + description: | + The text content that is finalized. + required: + - type + - item_id + - output_index + - content_index + - text + x-oaiMeta: + name: response.output_text.done + group: responses + example: > + { + "type": "response.output_text.done", + "item_id": "msg_123", + "output_index": 0, + "content_index": 0, + "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic." + } + ResponseUsage: + type: object + description: | + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. + properties: + input_tokens: + type: integer + description: The number of input tokens. + input_tokens_details: + type: object + description: A detailed breakdown of the input tokens. + properties: + cached_tokens: + type: integer + description: | + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). + required: + - cached_tokens + output_tokens: + type: integer + description: The number of output tokens. + output_tokens_details: + type: object + description: A detailed breakdown of the output tokens. + properties: + reasoning_tokens: + type: integer + description: The number of reasoning tokens. + required: + - reasoning_tokens + total_tokens: + type: integer + description: The total number of tokens used. + required: + - input_tokens + - input_tokens_details + - output_tokens + - output_tokens_details + - total_tokens + ResponseWebSearchCallCompletedEvent: + type: object + description: Emitted when a web search call is completed. + properties: + type: + type: string + description: | + The type of the event. Always `response.web_search_call.completed`. + enum: + - response.web_search_call.completed + x-stainless-const: true + output_index: + type: integer + description: > + The index of the output item that the web search call is associated + with. + item_id: + type: string + description: | + Unique ID for the output item associated with the web search call. + required: + - type + - output_index + - item_id + x-oaiMeta: + name: response.web_search_call.completed + group: responses + example: | + { + "type": "response.web_search_call.completed", + "output_index": 0, + "item_id": "ws_123", + } + ResponseWebSearchCallInProgressEvent: + type: object + description: Emitted when a web search call is initiated. + properties: + type: + type: string + description: > + The type of the event. Always `response.web_search_call.in_progress`. + enum: + - response.web_search_call.in_progress + x-stainless-const: true + output_index: + type: integer + description: > + The index of the output item that the web search call is associated + with. + item_id: + type: string + description: | + Unique ID for the output item associated with the web search call. + required: + - type + - output_index + - item_id + x-oaiMeta: + name: response.web_search_call.in_progress + group: responses + example: | + { + "type": "response.web_search_call.in_progress", + "output_index": 0, + "item_id": "ws_123", + } + ResponseWebSearchCallSearchingEvent: + type: object + description: Emitted when a web search call is executing. + properties: + type: + type: string + description: | + The type of the event. Always `response.web_search_call.searching`. + enum: + - response.web_search_call.searching + x-stainless-const: true + output_index: + type: integer + description: > + The index of the output item that the web search call is associated + with. + item_id: + type: string + description: | + Unique ID for the output item associated with the web search call. + required: + - type + - output_index + - item_id + x-oaiMeta: + name: response.web_search_call.searching + group: responses + example: | + { + "type": "response.web_search_call.searching", + "output_index": 0, + "item_id": "ws_123", + } + RunCompletionUsage: + type: object + description: Usage statistics related to the run. This value will be `null` if + the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + properties: + completion_tokens: + type: integer + description: Number of completion tokens used over the course of the run. + prompt_tokens: + type: integer + description: Number of prompt tokens used over the course of the run. + total_tokens: + type: integer + description: Total number of tokens used (prompt + completion). + required: + - prompt_tokens + - completion_tokens + - total_tokens + nullable: true + RunObject: + type: object + title: A run on a thread + description: Represents an execution run on a [thread](/docs/api-reference/threads). + properties: + id: + description: The identifier, which can be referenced in API endpoints. + type: string + object: + description: The object type, which is always `thread.run`. + type: string + enum: + - thread.run + x-stainless-const: true + created_at: + description: The Unix timestamp (in seconds) for when the run was created. + type: integer + thread_id: + description: The ID of the [thread](/docs/api-reference/threads) that was + executed on as a part of this run. + type: string + assistant_id: + description: The ID of the [assistant](/docs/api-reference/assistants) used for + execution of this run. + type: string + status: + description: The status of the run, which can be either `queued`, `in_progress`, + `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, + `incomplete`, or `expired`. + type: string + enum: + - queued + - in_progress + - requires_action + - cancelling + - cancelled + - failed + - completed + - incomplete + - expired + required_action: + type: object + description: Details on the action required to continue the run. Will be `null` + if no action is required. + nullable: true + properties: + type: + description: For now, this is always `submit_tool_outputs`. + type: string + enum: + - submit_tool_outputs + x-stainless-const: true + submit_tool_outputs: + type: object + description: Details on the tool outputs needed for this run to continue. + properties: + tool_calls: + type: array + description: A list of the relevant tool calls. + items: + $ref: "#/components/schemas/RunToolCallObject" + required: + - tool_calls + required: + - type + - submit_tool_outputs + last_error: + type: object + description: The last error associated with this run. Will be `null` if there + are no errors. + nullable: true + properties: + code: + type: string + description: One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + enum: + - server_error + - rate_limit_exceeded + - invalid_prompt + message: + type: string + description: A human-readable description of the error. + required: + - code + - message + expires_at: + description: The Unix timestamp (in seconds) for when the run will expire. + type: integer + nullable: true + started_at: + description: The Unix timestamp (in seconds) for when the run was started. + type: integer + nullable: true + cancelled_at: + description: The Unix timestamp (in seconds) for when the run was cancelled. + type: integer + nullable: true + failed_at: + description: The Unix timestamp (in seconds) for when the run failed. + type: integer + nullable: true + completed_at: + description: The Unix timestamp (in seconds) for when the run was completed. + type: integer + nullable: true + incomplete_details: + description: Details on why the run is incomplete. Will be `null` if the run is + not incomplete. + type: object + nullable: true + properties: + reason: + description: The reason why the run is incomplete. This will point to which + specific token limit was reached over the course of the run. + type: string + enum: + - max_completion_tokens + - max_prompt_tokens + model: + description: The model that the [assistant](/docs/api-reference/assistants) used + for this run. + type: string + instructions: + description: The instructions that the + [assistant](/docs/api-reference/assistants) used for this run. + type: string + tools: + description: The list of tools that the + [assistant](/docs/api-reference/assistants) used for this run. + default: [] + type: array + maxItems: 20 + items: + oneOf: + - $ref: "#/components/schemas/AssistantToolsCode" + - $ref: "#/components/schemas/AssistantToolsFileSearch" + - $ref: "#/components/schemas/AssistantToolsFunction" + metadata: + $ref: "#/components/schemas/Metadata" + usage: + $ref: "#/components/schemas/RunCompletionUsage" + temperature: + description: The sampling temperature used for this run. If not set, defaults to + 1. + type: number + nullable: true + top_p: + description: The nucleus sampling value used for this run. If not set, defaults + to 1. + type: number + nullable: true + max_prompt_tokens: + type: integer + nullable: true + description: > + The maximum number of prompt tokens specified to have been used over + the course of the run. + minimum: 256 + max_completion_tokens: + type: integer + nullable: true + description: > + The maximum number of completion tokens specified to have been used + over the course of the run. + minimum: 256 + truncation_strategy: + allOf: + - $ref: "#/components/schemas/TruncationObject" + - nullable: true + tool_choice: + allOf: + - $ref: "#/components/schemas/AssistantsApiToolChoiceOption" + - nullable: true + parallel_tool_calls: + $ref: "#/components/schemas/ParallelToolCalls" + response_format: + $ref: "#/components/schemas/AssistantsApiResponseFormatOption" + nullable: true + required: + - id + - object + - created_at + - thread_id + - assistant_id + - status + - required_action + - last_error + - expires_at + - started_at + - cancelled_at + - failed_at + - completed_at + - model + - instructions + - tools + - metadata + - usage + - incomplete_details + - max_prompt_tokens + - max_completion_tokens + - truncation_strategy + - tool_choice + - parallel_tool_calls + - response_format + x-oaiMeta: + name: The run object + beta: true + example: | + { + "id": "run_abc123", + "object": "thread.run", + "created_at": 1698107661, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "completed", + "started_at": 1699073476, + "expires_at": null, + "cancelled_at": null, + "failed_at": null, + "completed_at": 1699073498, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "tools": [{"type": "file_search"}, {"type": "code_interpreter"}], + "metadata": {}, + "incomplete_details": null, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + }, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true + } + RunStepCompletionUsage: + type: object + description: Usage statistics related to the run step. This value will be `null` + while the run step's status is `in_progress`. + properties: + completion_tokens: + type: integer + description: Number of completion tokens used over the course of the run step. + prompt_tokens: + type: integer + description: Number of prompt tokens used over the course of the run step. + total_tokens: + type: integer + description: Total number of tokens used (prompt + completion). + required: + - prompt_tokens + - completion_tokens + - total_tokens + nullable: true + RunStepDeltaObject: + type: object + title: Run step delta object + description: > + Represents a run step delta i.e. any changed fields on a run step during + streaming. + properties: + id: + description: The identifier of the run step, which can be referenced in API + endpoints. + type: string + object: + description: The object type, which is always `thread.run.step.delta`. + type: string + enum: + - thread.run.step.delta + x-stainless-const: true + delta: + description: The delta containing the fields that have changed on the run step. + type: object + properties: + step_details: + type: object + description: The details of the run step. + oneOf: + - $ref: "#/components/schemas/RunStepDeltaStepDetailsMessageCreationObject" + - $ref: "#/components/schemas/RunStepDeltaStepDetailsToolCallsObject" + required: + - id + - object + - delta + x-oaiMeta: + name: The run step delta object + beta: true + example: | + { + "id": "step_123", + "object": "thread.run.step.delta", + "delta": { + "step_details": { + "type": "tool_calls", + "tool_calls": [ + { + "index": 0, + "id": "call_123", + "type": "code_interpreter", + "code_interpreter": { "input": "", "outputs": [] } + } + ] + } + } + } + RunStepDeltaStepDetailsMessageCreationObject: + title: Message creation + type: object + description: Details of the message creation by the run step. + properties: + type: + description: Always `message_creation`. + type: string + enum: + - message_creation + x-stainless-const: true + message_creation: + type: object + properties: + message_id: + type: string + description: The ID of the message that was created by this run step. + required: + - type + RunStepDeltaStepDetailsToolCallsCodeObject: + title: Code interpreter tool call + type: object + description: Details of the Code Interpreter tool call the run step was involved in. + properties: + index: + type: integer + description: The index of the tool call in the tool calls array. + id: + type: string + description: The ID of the tool call. + type: + type: string + description: The type of tool call. This is always going to be + `code_interpreter` for this type of tool call. + enum: + - code_interpreter + x-stainless-const: true + code_interpreter: + type: object + description: The Code Interpreter tool call definition. + properties: + input: + type: string + description: The input to the Code Interpreter tool call. + outputs: + type: array + description: The outputs from the Code Interpreter tool call. Code Interpreter + can output one or more items, including text (`logs`) or images + (`image`). Each of these are represented by a different object + type. + items: + type: object + oneOf: + - $ref: "#/components/schemas/RunStepDeltaStepDetailsToolCallsCodeOutputLogsObject" + - $ref: "#/components/schemas/RunStepDeltaStepDetailsToolCallsCodeOutputImageObject" + required: + - index + - type + RunStepDeltaStepDetailsToolCallsCodeOutputImageObject: + title: Code interpreter image output + type: object + properties: + index: + type: integer + description: The index of the output in the outputs array. + type: + description: Always `image`. + type: string + enum: + - image + x-stainless-const: true + image: + type: object + properties: + file_id: + description: The [file](/docs/api-reference/files) ID of the image. + type: string + required: + - index + - type + RunStepDeltaStepDetailsToolCallsCodeOutputLogsObject: + title: Code interpreter log output + type: object + description: Text output from the Code Interpreter tool call as part of a run step. + properties: + index: + type: integer + description: The index of the output in the outputs array. + type: + description: Always `logs`. + type: string + enum: + - logs + x-stainless-const: true + logs: + type: string + description: The text output from the Code Interpreter tool call. + required: + - index + - type + RunStepDeltaStepDetailsToolCallsFileSearchObject: + title: File search tool call + type: object + properties: + index: + type: integer + description: The index of the tool call in the tool calls array. + id: + type: string + description: The ID of the tool call object. + type: + type: string + description: The type of tool call. This is always going to be `file_search` for + this type of tool call. + enum: + - file_search + x-stainless-const: true + file_search: + type: object + description: For now, this is always going to be an empty object. + x-oaiTypeLabel: map + required: + - index + - type + - file_search + RunStepDeltaStepDetailsToolCallsFunctionObject: + type: object + title: Function tool call + properties: + index: + type: integer + description: The index of the tool call in the tool calls array. + id: + type: string + description: The ID of the tool call object. + type: + type: string + description: The type of tool call. This is always going to be `function` for + this type of tool call. + enum: + - function + x-stainless-const: true + function: + type: object + description: The definition of the function that was called. + properties: + name: + type: string + description: The name of the function. + arguments: + type: string + description: The arguments passed to the function. + output: + type: string + description: The output of the function. This will be `null` if the outputs have + not been [submitted](/docs/api-reference/runs/submitToolOutputs) + yet. + nullable: true + required: + - index + - type + RunStepDeltaStepDetailsToolCallsObject: + title: Tool calls + type: object + description: Details of the tool call. + properties: + type: + description: Always `tool_calls`. + type: string + enum: + - tool_calls + x-stainless-const: true + tool_calls: + type: array + description: > + An array of tool calls the run step was involved in. These can be + associated with one of three types of tools: `code_interpreter`, + `file_search`, or `function`. + items: + oneOf: + - $ref: "#/components/schemas/RunStepDeltaStepDetailsToolCallsCodeObject" + - $ref: "#/components/schemas/RunStepDeltaStepDetailsToolCallsFileSearchObject" + - $ref: "#/components/schemas/RunStepDeltaStepDetailsToolCallsFunctionObject" + required: + - type + RunStepDetailsMessageCreationObject: + title: Message creation + type: object + description: Details of the message creation by the run step. + properties: + type: + description: Always `message_creation`. + type: string + enum: + - message_creation + x-stainless-const: true + message_creation: + type: object + properties: + message_id: + type: string + description: The ID of the message that was created by this run step. + required: + - message_id + required: + - type + - message_creation + RunStepDetailsToolCallsCodeObject: + title: Code Interpreter tool call + type: object + description: Details of the Code Interpreter tool call the run step was involved in. + properties: + id: + type: string + description: The ID of the tool call. + type: + type: string + description: The type of tool call. This is always going to be + `code_interpreter` for this type of tool call. + enum: + - code_interpreter + x-stainless-const: true + code_interpreter: + type: object + description: The Code Interpreter tool call definition. + required: + - input + - outputs + properties: + input: + type: string + description: The input to the Code Interpreter tool call. + outputs: + type: array + description: The outputs from the Code Interpreter tool call. Code Interpreter + can output one or more items, including text (`logs`) or images + (`image`). Each of these are represented by a different object + type. + items: + type: object + oneOf: + - $ref: "#/components/schemas/RunStepDetailsToolCallsCodeOutputLogsObject" + - $ref: "#/components/schemas/RunStepDetailsToolCallsCodeOutputImageObject" + required: + - id + - type + - code_interpreter + RunStepDetailsToolCallsCodeOutputImageObject: + title: Code Interpreter image output + type: object + properties: + type: + description: Always `image`. + type: string + enum: + - image + x-stainless-const: true + image: + type: object + properties: + file_id: + description: The [file](/docs/api-reference/files) ID of the image. + type: string + required: + - file_id + required: + - type + - image + RunStepDetailsToolCallsCodeOutputLogsObject: + title: Code Interpreter log output + type: object + description: Text output from the Code Interpreter tool call as part of a run step. + properties: + type: + description: Always `logs`. + type: string + enum: + - logs + x-stainless-const: true + logs: + type: string + description: The text output from the Code Interpreter tool call. + required: + - type + - logs + RunStepDetailsToolCallsFileSearchObject: + title: File search tool call + type: object + properties: + id: + type: string + description: The ID of the tool call object. + type: + type: string + description: The type of tool call. This is always going to be `file_search` for + this type of tool call. + enum: + - file_search + x-stainless-const: true + file_search: + type: object + description: For now, this is always going to be an empty object. + x-oaiTypeLabel: map + properties: + ranking_options: + $ref: "#/components/schemas/RunStepDetailsToolCallsFileSearchRankingOptionsObject" + results: + type: array + description: The results of the file search. + items: + $ref: "#/components/schemas/RunStepDetailsToolCallsFileSearchResultObject" + required: + - id + - type + - file_search + RunStepDetailsToolCallsFileSearchRankingOptionsObject: + title: File search tool call ranking options + type: object + description: The ranking options for the file search. + properties: + ranker: + $ref: "#/components/schemas/FileSearchRanker" + score_threshold: + type: number + description: The score threshold for the file search. All values must be a + floating point number between 0 and 1. + minimum: 0 + maximum: 1 + required: + - ranker + - score_threshold + RunStepDetailsToolCallsFileSearchResultObject: + title: File search tool call result + type: object + description: A result instance of the file search. + x-oaiTypeLabel: map + properties: + file_id: + type: string + description: The ID of the file that result was found in. + file_name: + type: string + description: The name of the file that result was found in. + score: + type: number + description: The score of the result. All values must be a floating point number + between 0 and 1. + minimum: 0 + maximum: 1 + content: + type: array + description: The content of the result that was found. The content is only + included if requested via the include query parameter. + items: + type: object + properties: + type: + type: string + description: The type of the content. + enum: + - text + x-stainless-const: true + text: + type: string + description: The text content of the file. + required: + - file_id + - file_name + - score + RunStepDetailsToolCallsFunctionObject: + type: object + title: Function tool call + properties: + id: + type: string + description: The ID of the tool call object. + type: + type: string + description: The type of tool call. This is always going to be `function` for + this type of tool call. + enum: + - function + x-stainless-const: true + function: + type: object + description: The definition of the function that was called. + properties: + name: + type: string + description: The name of the function. + arguments: + type: string + description: The arguments passed to the function. + output: + type: string + description: The output of the function. This will be `null` if the outputs have + not been [submitted](/docs/api-reference/runs/submitToolOutputs) + yet. + nullable: true + required: + - name + - arguments + - output + required: + - id + - type + - function + RunStepDetailsToolCallsObject: + title: Tool calls + type: object + description: Details of the tool call. + properties: + type: + description: Always `tool_calls`. + type: string + enum: + - tool_calls + x-stainless-const: true + tool_calls: + type: array + description: > + An array of tool calls the run step was involved in. These can be + associated with one of three types of tools: `code_interpreter`, + `file_search`, or `function`. + items: + oneOf: + - $ref: "#/components/schemas/RunStepDetailsToolCallsCodeObject" + - $ref: "#/components/schemas/RunStepDetailsToolCallsFileSearchObject" + - $ref: "#/components/schemas/RunStepDetailsToolCallsFunctionObject" + required: + - type + - tool_calls + RunStepObject: + type: object + title: Run steps + description: | + Represents a step in execution of a run. + properties: + id: + description: The identifier of the run step, which can be referenced in API + endpoints. + type: string + object: + description: The object type, which is always `thread.run.step`. + type: string + enum: + - thread.run.step + x-stainless-const: true + created_at: + description: The Unix timestamp (in seconds) for when the run step was created. + type: integer + assistant_id: + description: The ID of the [assistant](/docs/api-reference/assistants) + associated with the run step. + type: string + thread_id: + description: The ID of the [thread](/docs/api-reference/threads) that was run. + type: string + run_id: + description: The ID of the [run](/docs/api-reference/runs) that this run step is + a part of. + type: string + type: + description: The type of run step, which can be either `message_creation` or + `tool_calls`. + type: string + enum: + - message_creation + - tool_calls + status: + description: The status of the run step, which can be either `in_progress`, + `cancelled`, `failed`, `completed`, or `expired`. + type: string + enum: + - in_progress + - cancelled + - failed + - completed + - expired + step_details: + type: object + description: The details of the run step. + oneOf: + - $ref: "#/components/schemas/RunStepDetailsMessageCreationObject" + - $ref: "#/components/schemas/RunStepDetailsToolCallsObject" + last_error: + type: object + description: The last error associated with this run step. Will be `null` if + there are no errors. + nullable: true + properties: + code: + type: string + description: One of `server_error` or `rate_limit_exceeded`. + enum: + - server_error + - rate_limit_exceeded + message: + type: string + description: A human-readable description of the error. + required: + - code + - message + expired_at: + description: The Unix timestamp (in seconds) for when the run step expired. A + step is considered expired if the parent run is expired. + type: integer + nullable: true + cancelled_at: + description: The Unix timestamp (in seconds) for when the run step was cancelled. + type: integer + nullable: true + failed_at: + description: The Unix timestamp (in seconds) for when the run step failed. + type: integer + nullable: true + completed_at: + description: The Unix timestamp (in seconds) for when the run step completed. + type: integer + nullable: true + metadata: + $ref: "#/components/schemas/Metadata" + usage: + $ref: "#/components/schemas/RunStepCompletionUsage" + required: + - id + - object + - created_at + - assistant_id + - thread_id + - run_id + - type + - status + - step_details + - last_error + - expired_at + - cancelled_at + - failed_at + - completed_at + - metadata + - usage + x-oaiMeta: + name: The run step object + beta: true + example: | + { + "id": "step_abc123", + "object": "thread.run.step", + "created_at": 1699063291, + "run_id": "run_abc123", + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "type": "message_creation", + "status": "completed", + "cancelled_at": null, + "completed_at": 1699063291, + "expired_at": null, + "failed_at": null, + "last_error": null, + "step_details": { + "type": "message_creation", + "message_creation": { + "message_id": "msg_abc123" + } + }, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + } + } + RunStepStreamEvent: + oneOf: + - type: object + properties: + event: + type: string + enum: + - thread.run.step.created + x-stainless-const: true + data: + $ref: "#/components/schemas/RunStepObject" + required: + - event + - data + description: Occurs when a [run step](/docs/api-reference/run-steps/step-object) + is created. + x-oaiMeta: + dataDescription: "`data` is a [run step](/docs/api-reference/run-steps/step-object)" + - type: object + properties: + event: + type: string + enum: + - thread.run.step.in_progress + x-stainless-const: true + data: + $ref: "#/components/schemas/RunStepObject" + required: + - event + - data + description: Occurs when a [run step](/docs/api-reference/run-steps/step-object) + moves to an `in_progress` state. + x-oaiMeta: + dataDescription: "`data` is a [run step](/docs/api-reference/run-steps/step-object)" + - type: object + properties: + event: + type: string + enum: + - thread.run.step.delta + x-stainless-const: true + data: + $ref: "#/components/schemas/RunStepDeltaObject" + required: + - event + - data + description: Occurs when parts of a [run + step](/docs/api-reference/run-steps/step-object) are being streamed. + x-oaiMeta: + dataDescription: "`data` is a [run step + delta](/docs/api-reference/assistants-streaming/run-step-delta-ob\ + ject)" + - type: object + properties: + event: + type: string + enum: + - thread.run.step.completed + x-stainless-const: true + data: + $ref: "#/components/schemas/RunStepObject" + required: + - event + - data + description: Occurs when a [run step](/docs/api-reference/run-steps/step-object) + is completed. + x-oaiMeta: + dataDescription: "`data` is a [run step](/docs/api-reference/run-steps/step-object)" + - type: object + properties: + event: + type: string + enum: + - thread.run.step.failed + x-stainless-const: true + data: + $ref: "#/components/schemas/RunStepObject" + required: + - event + - data + description: Occurs when a [run step](/docs/api-reference/run-steps/step-object) + fails. + x-oaiMeta: + dataDescription: "`data` is a [run step](/docs/api-reference/run-steps/step-object)" + - type: object + properties: + event: + type: string + enum: + - thread.run.step.cancelled + x-stainless-const: true + data: + $ref: "#/components/schemas/RunStepObject" + required: + - event + - data + description: Occurs when a [run step](/docs/api-reference/run-steps/step-object) + is cancelled. + x-oaiMeta: + dataDescription: "`data` is a [run step](/docs/api-reference/run-steps/step-object)" + - type: object + properties: + event: + type: string + enum: + - thread.run.step.expired + x-stainless-const: true + data: + $ref: "#/components/schemas/RunStepObject" + required: + - event + - data + description: Occurs when a [run step](/docs/api-reference/run-steps/step-object) + expires. + x-oaiMeta: + dataDescription: "`data` is a [run step](/docs/api-reference/run-steps/step-object)" + RunStreamEvent: + oneOf: + - type: object + properties: + event: + type: string + enum: + - thread.run.created + x-stainless-const: true + data: + $ref: "#/components/schemas/RunObject" + required: + - event + - data + description: Occurs when a new [run](/docs/api-reference/runs/object) is created. + x-oaiMeta: + dataDescription: "`data` is a [run](/docs/api-reference/runs/object)" + - type: object + properties: + event: + type: string + enum: + - thread.run.queued + x-stainless-const: true + data: + $ref: "#/components/schemas/RunObject" + required: + - event + - data + description: Occurs when a [run](/docs/api-reference/runs/object) moves to a + `queued` status. + x-oaiMeta: + dataDescription: "`data` is a [run](/docs/api-reference/runs/object)" + - type: object + properties: + event: + type: string + enum: + - thread.run.in_progress + x-stainless-const: true + data: + $ref: "#/components/schemas/RunObject" + required: + - event + - data + description: Occurs when a [run](/docs/api-reference/runs/object) moves to an + `in_progress` status. + x-oaiMeta: + dataDescription: "`data` is a [run](/docs/api-reference/runs/object)" + - type: object + properties: + event: + type: string + enum: + - thread.run.requires_action + x-stainless-const: true + data: + $ref: "#/components/schemas/RunObject" + required: + - event + - data + description: Occurs when a [run](/docs/api-reference/runs/object) moves to a + `requires_action` status. + x-oaiMeta: + dataDescription: "`data` is a [run](/docs/api-reference/runs/object)" + - type: object + properties: + event: + type: string + enum: + - thread.run.completed + x-stainless-const: true + data: + $ref: "#/components/schemas/RunObject" + required: + - event + - data + description: Occurs when a [run](/docs/api-reference/runs/object) is completed. + x-oaiMeta: + dataDescription: "`data` is a [run](/docs/api-reference/runs/object)" + - type: object + properties: + event: + type: string + enum: + - thread.run.incomplete + x-stainless-const: true + data: + $ref: "#/components/schemas/RunObject" + required: + - event + - data + description: Occurs when a [run](/docs/api-reference/runs/object) ends with + status `incomplete`. + x-oaiMeta: + dataDescription: "`data` is a [run](/docs/api-reference/runs/object)" + - type: object + properties: + event: + type: string + enum: + - thread.run.failed + x-stainless-const: true + data: + $ref: "#/components/schemas/RunObject" + required: + - event + - data + description: Occurs when a [run](/docs/api-reference/runs/object) fails. + x-oaiMeta: + dataDescription: "`data` is a [run](/docs/api-reference/runs/object)" + - type: object + properties: + event: + type: string + enum: + - thread.run.cancelling + x-stainless-const: true + data: + $ref: "#/components/schemas/RunObject" + required: + - event + - data + description: Occurs when a [run](/docs/api-reference/runs/object) moves to a + `cancelling` status. + x-oaiMeta: + dataDescription: "`data` is a [run](/docs/api-reference/runs/object)" + - type: object + properties: + event: + type: string + enum: + - thread.run.cancelled + x-stainless-const: true + data: + $ref: "#/components/schemas/RunObject" + required: + - event + - data + description: Occurs when a [run](/docs/api-reference/runs/object) is cancelled. + x-oaiMeta: + dataDescription: "`data` is a [run](/docs/api-reference/runs/object)" + - type: object + properties: + event: + type: string + enum: + - thread.run.expired + x-stainless-const: true + data: + $ref: "#/components/schemas/RunObject" + required: + - event + - data + description: Occurs when a [run](/docs/api-reference/runs/object) expires. + x-oaiMeta: + dataDescription: "`data` is a [run](/docs/api-reference/runs/object)" + RunToolCallObject: + type: object + description: Tool call objects + properties: + id: + type: string + description: The ID of the tool call. This ID must be referenced when you submit + the tool outputs in using the [Submit tool outputs to + run](/docs/api-reference/runs/submitToolOutputs) endpoint. + type: + type: string + description: The type of tool call the output is required for. For now, this is + always `function`. + enum: + - function + x-stainless-const: true + function: + type: object + description: The function definition. + properties: + name: + type: string + description: The name of the function. + arguments: + type: string + description: The arguments that the model expects you to pass to the function. + required: + - name + - arguments + required: + - id + - type + - function + Screenshot: + type: object + title: Screenshot + description: | + A screenshot action. + properties: + type: + type: string + enum: + - screenshot + default: screenshot + description: | + Specifies the event type. For a screenshot action, this property is + always set to `screenshot`. + x-stainless-const: true + required: + - type + Scroll: + type: object + title: Scroll + description: | + A scroll action. + properties: + type: + type: string + enum: + - scroll + default: scroll + description: | + Specifies the event type. For a scroll action, this property is + always set to `scroll`. + x-stainless-const: true + x: + type: integer + description: | + The x-coordinate where the scroll occurred. + y: + type: integer + description: | + The y-coordinate where the scroll occurred. + scroll_x: + type: integer + description: | + The horizontal scroll distance. + scroll_y: + type: integer + description: | + The vertical scroll distance. + required: + - type + - x + - y + - scroll_x + - scroll_y + ServiceTier: + type: string + description: > + Specifies the latency tier to use for processing the request. This + parameter is relevant for customers subscribed to the scale tier + service: + - If set to 'auto', and the Project is Scale tier enabled, the system + will utilize scale tier credits until they are exhausted. + - If set to 'auto', and the Project is not Scale tier enabled, the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee. + - If set to 'default', the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee. + - If set to 'flex', the request will be processed with the Flex Processing service tier. [Learn more](/docs/guides/flex-processing). + - When not set, the default behavior is 'auto'. + + When this parameter is set, the response body will include the `service_tier` utilized. + enum: + - auto + - default + - flex + nullable: true + default: auto + StaticChunkingStrategy: + type: object + additionalProperties: false + properties: + max_chunk_size_tokens: + type: integer + minimum: 100 + maximum: 4096 + description: The maximum number of tokens in each chunk. The default value is + `800`. The minimum value is `100` and the maximum value is `4096`. + chunk_overlap_tokens: + type: integer + description: > + The number of tokens that overlap between chunks. The default value + is `400`. + + + Note that the overlap must not exceed half of + `max_chunk_size_tokens`. + required: + - max_chunk_size_tokens + - chunk_overlap_tokens + StaticChunkingStrategyRequestParam: + type: object + title: Static Chunking Strategy + description: Customize your own chunking strategy by setting chunk size and + chunk overlap. + additionalProperties: false + properties: + type: + type: string + description: Always `static`. + enum: + - static + x-stainless-const: true + static: + $ref: "#/components/schemas/StaticChunkingStrategy" + required: + - type + - static + StaticChunkingStrategyResponseParam: + type: object + title: Static Chunking Strategy + additionalProperties: false + properties: + type: + type: string + description: Always `static`. + enum: + - static + x-stainless-const: true + static: + $ref: "#/components/schemas/StaticChunkingStrategy" + required: + - type + - static + StopConfiguration: + description: | + Not supported with latest reasoning models `o3` and `o4-mini`. + + Up to 4 sequences where the API will stop generating further tokens. The + returned text will not contain the stop sequence. + default: null + nullable: true + oneOf: + - type: string + default: <|endoftext|> + example: "\n" + nullable: true + - type: array + minItems: 1 + maxItems: 4 + items: + type: string + example: '["\n"]' + SubmitToolOutputsRunRequest: + type: object + additionalProperties: false + properties: + tool_outputs: + description: A list of tools for which the outputs are being submitted. + type: array + items: + type: object + properties: + tool_call_id: + type: string + description: The ID of the tool call in the `required_action` object within the + run object the output is being submitted for. + output: + type: string + description: The output of the tool call to be submitted to continue the run. + stream: + type: boolean + nullable: true + description: > + If `true`, returns a stream of events that happen during the Run as + server-sent events, terminating when the Run enters a terminal state + with a `data: [DONE]` message. + required: + - tool_outputs + TextResponseFormatConfiguration: + description: > + An object specifying the format that the model must output. + + + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + + which ensures the model will match your supplied JSON schema. Learn more + in the + + [Structured Outputs guide](/docs/guides/structured-outputs). + + + The default format is `{ "type": "text" }` with no additional options. + + + **Not recommended for gpt-4o and newer models:** + + + Setting to `{ "type": "json_object" }` enables the older JSON mode, + which + + ensures the message the model generates is valid JSON. Using + `json_schema` + + is preferred for models that support it. + oneOf: + - $ref: "#/components/schemas/ResponseFormatText" + - $ref: "#/components/schemas/TextResponseFormatJsonSchema" + - $ref: "#/components/schemas/ResponseFormatJsonObject" + TextResponseFormatJsonSchema: + type: object + title: JSON schema + description: | + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). + properties: + type: + type: string + description: The type of response format being defined. Always `json_schema`. + enum: + - json_schema + x-stainless-const: true + description: + type: string + description: > + A description of what the response format is for, used by the model + to + + determine how to respond in the format. + name: + type: string + description: | + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. + schema: + $ref: "#/components/schemas/ResponseFormatJsonSchemaSchema" + strict: + type: boolean + nullable: true + default: false + description: > + Whether to enable strict schema adherence when generating the + output. + + If set to true, the model will always follow the exact schema + defined + + in the `schema` field. Only a subset of JSON Schema is supported + when + + `strict` is `true`. To learn more, read the [Structured Outputs + + guide](/docs/guides/structured-outputs). + required: + - type + - schema + - name + ThreadObject: + type: object + title: Thread + description: Represents a thread that contains + [messages](/docs/api-reference/messages). + properties: + id: + description: The identifier, which can be referenced in API endpoints. + type: string + object: + description: The object type, which is always `thread`. + type: string + enum: + - thread + x-stainless-const: true + created_at: + description: The Unix timestamp (in seconds) for when the thread was created. + type: integer + tool_resources: + type: object + description: > + A set of resources that are made available to the assistant's tools + in this thread. The resources are specific to the type of tool. For + example, the `code_interpreter` tool requires a list of file IDs, + while the `file_search` tool requires a list of vector store IDs. + properties: + code_interpreter: + type: object + properties: + file_ids: + type: array + description: > + A list of [file](/docs/api-reference/files) IDs made + available to the `code_interpreter` tool. There can be a + maximum of 20 files associated with the tool. + default: [] + maxItems: 20 + items: + type: string + file_search: + type: object + properties: + vector_store_ids: + type: array + description: > + The [vector store](/docs/api-reference/vector-stores/object) + attached to this thread. There can be a maximum of 1 vector + store attached to the thread. + maxItems: 1 + items: + type: string + nullable: true + metadata: + $ref: "#/components/schemas/Metadata" + required: + - id + - object + - created_at + - tool_resources + - metadata + x-oaiMeta: + name: The thread object + beta: true + example: | + { + "id": "thread_abc123", + "object": "thread", + "created_at": 1698107661, + "metadata": {} + } + ThreadStreamEvent: + oneOf: + - type: object + properties: + enabled: + type: boolean + description: Whether to enable input audio transcription. + event: + type: string + enum: + - thread.created + x-stainless-const: true + data: + $ref: "#/components/schemas/ThreadObject" + required: + - event + - data + description: Occurs when a new [thread](/docs/api-reference/threads/object) is + created. + x-oaiMeta: + dataDescription: "`data` is a [thread](/docs/api-reference/threads/object)" + ToggleCertificatesRequest: + type: object + properties: + certificate_ids: + type: array + items: + type: string + example: cert_abc + minItems: 1 + maxItems: 10 + required: + - certificate_ids + ToolChoiceFunction: + type: object + title: Function tool + description: | + Use this option to force the model to call a specific function. + properties: + type: + type: string + enum: + - function + description: For function calling, the type is always `function`. + x-stainless-const: true + name: + type: string + description: The name of the function to call. + required: + - type + - name + ToolChoiceOptions: + type: string + title: Tool choice mode + description: > + Controls which (if any) tool is called by the model. + + + `none` means the model will not call any tool and instead generates a + message. + + + `auto` means the model can pick between generating a message or calling + one or + + more tools. + + + `required` means the model must call one or more tools. + enum: + - none + - auto + - required + ToolChoiceTypes: + type: object + title: Hosted tool + description: > + Indicates that the model should use a built-in tool to generate a + response. + + [Learn more about built-in tools](/docs/guides/tools). + properties: + type: + type: string + description: | + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). + + Allowed values are: + - `file_search` + - `web_search_preview` + - `computer_use_preview` + enum: + - file_search + - web_search_preview + - computer_use_preview + - web_search_preview_2025_03_11 + required: + - type + TranscriptTextDeltaEvent: + type: object + description: Emitted when there is an additional text delta. This is also the + first event emitted when the transcription starts. Only emitted when you + [create a transcription](/docs/api-reference/audio/create-transcription) + with the `Stream` parameter set to `true`. + properties: + type: + type: string + description: | + The type of the event. Always `transcript.text.delta`. + enum: + - transcript.text.delta + x-stainless-const: true + delta: + type: string + description: | + The text delta that was additionally transcribed. + logprobs: + type: array + description: > + The log probabilities of the delta. Only included if you [create a + transcription](/docs/api-reference/audio/create-transcription) with + the `include[]` parameter set to `logprobs`. + items: + type: object + properties: + token: + type: string + description: | + The token that was used to generate the log probability. + logprob: + type: number + description: | + The log probability of the token. + bytes: + type: array + description: | + The bytes that were used to generate the log probability. + required: + - type + - delta + x-oaiMeta: + name: Stream Event (transcript.text.delta) + group: transcript + example: | + { + "type": "transcript.text.delta", + "delta": " wonderful" + } + TranscriptTextDoneEvent: + type: object + description: Emitted when the transcription is complete. Contains the complete + transcription text. Only emitted when you [create a + transcription](/docs/api-reference/audio/create-transcription) with the + `Stream` parameter set to `true`. + properties: + type: + type: string + description: | + The type of the event. Always `transcript.text.done`. + enum: + - transcript.text.done + x-stainless-const: true + text: + type: string + description: | + The text that was transcribed. + logprobs: + type: array + description: > + The log probabilities of the individual tokens in the transcription. + Only included if you [create a + transcription](/docs/api-reference/audio/create-transcription) with + the `include[]` parameter set to `logprobs`. + items: + type: object + properties: + token: + type: string + description: | + The token that was used to generate the log probability. + logprob: + type: number + description: | + The log probability of the token. + bytes: + type: array + description: | + The bytes that were used to generate the log probability. + required: + - type + - text + x-oaiMeta: + name: Stream Event (transcript.text.done) + group: transcript + example: > + { + "type": "transcript.text.done", + "text": "I see skies of blue and clouds of white, the bright blessed days, the dark sacred nights, and I think to myself, what a wonderful world." + } + TranscriptionInclude: + type: string + enum: + - logprobs + default: [] + TranscriptionSegment: + type: object + properties: + id: + type: integer + description: Unique identifier of the segment. + seek: + type: integer + description: Seek offset of the segment. + start: + type: number + format: float + description: Start time of the segment in seconds. + end: + type: number + format: float + description: End time of the segment in seconds. + text: + type: string + description: Text content of the segment. + tokens: + type: array + items: + type: integer + description: Array of token IDs for the text content. + temperature: + type: number + format: float + description: Temperature parameter used for generating the segment. + avg_logprob: + type: number + format: float + description: Average logprob of the segment. If the value is lower than -1, + consider the logprobs failed. + compression_ratio: + type: number + format: float + description: Compression ratio of the segment. If the value is greater than 2.4, + consider the compression failed. + no_speech_prob: + type: number + format: float + description: Probability of no speech in the segment. If the value is higher + than 1.0 and the `avg_logprob` is below -1, consider this segment + silent. + required: + - id + - seek + - start + - end + - text + - tokens + - temperature + - avg_logprob + - compression_ratio + - no_speech_prob + TranscriptionWord: + type: object + properties: + word: + type: string + description: The text content of the word. + start: + type: number + format: float + description: Start time of the word in seconds. + end: + type: number + format: float + description: End time of the word in seconds. + required: + - word + - start + - end + TruncationObject: + type: object + title: Thread Truncation Controls + description: Controls for how a thread will be truncated prior to the run. Use + this to control the intial context window of the run. + properties: + type: + type: string + description: The truncation strategy to use for the thread. The default is + `auto`. If set to `last_messages`, the thread will be truncated to + the n most recent messages in the thread. When set to `auto`, + messages in the middle of the thread will be dropped to fit the + context length of the model, `max_prompt_tokens`. + enum: + - auto + - last_messages + last_messages: + type: integer + description: The number of most recent messages from the thread when + constructing the context for the run. + minimum: 1 + nullable: true + required: + - type + Type: + type: object + title: Type + description: | + An action to type in text. + properties: + type: + type: string + enum: + - type + default: type + description: | + Specifies the event type. For a type action, this property is + always set to `type`. + x-stainless-const: true + text: + type: string + description: | + The text to type. + required: + - type + - text + UpdateVectorStoreFileAttributesRequest: + type: object + additionalProperties: false + properties: + attributes: + $ref: "#/components/schemas/VectorStoreFileAttributes" + required: + - attributes + x-oaiMeta: + name: Update vector store file attributes request + UpdateVectorStoreRequest: + type: object + additionalProperties: false + properties: + name: + description: The name of the vector store. + type: string + nullable: true + expires_after: + allOf: + - $ref: "#/components/schemas/VectorStoreExpirationAfter" + - nullable: true + metadata: + $ref: "#/components/schemas/Metadata" + Upload: + type: object + title: Upload + description: | + The Upload object can accept byte chunks in the form of Parts. + properties: + id: + type: string + description: The Upload unique identifier, which can be referenced in API + endpoints. + created_at: + type: integer + description: The Unix timestamp (in seconds) for when the Upload was created. + filename: + type: string + description: The name of the file to be uploaded. + bytes: + type: integer + description: The intended number of bytes to be uploaded. + purpose: + type: string + description: The intended purpose of the file. [Please refer + here](/docs/api-reference/files/object#files/object-purpose) for + acceptable values. + status: + type: string + description: The status of the Upload. + enum: + - pending + - completed + - cancelled + - expired + expires_at: + type: integer + description: The Unix timestamp (in seconds) for when the Upload will expire. + object: + type: string + description: The object type, which is always "upload". + enum: + - upload + x-stainless-const: true + file: + allOf: + - $ref: "#/components/schemas/OpenAIFile" + - nullable: true + description: The ready File object after the Upload is completed. + required: + - bytes + - created_at + - expires_at + - filename + - id + - purpose + - status + x-oaiMeta: + name: The upload object + example: | + { + "id": "upload_abc123", + "object": "upload", + "bytes": 2147483648, + "created_at": 1719184911, + "filename": "training_examples.jsonl", + "purpose": "fine-tune", + "status": "completed", + "expires_at": 1719127296, + "file": { + "id": "file-xyz321", + "object": "file", + "bytes": 2147483648, + "created_at": 1719186911, + "filename": "training_examples.jsonl", + "purpose": "fine-tune", + } + } + UploadCertificateRequest: + type: object + properties: + name: + type: string + description: An optional name for the certificate + content: + type: string + description: The certificate content in PEM format + required: + - content + UploadPart: + type: object + title: UploadPart + description: > + The upload Part represents a chunk of bytes we can add to an Upload + object. + properties: + id: + type: string + description: The upload Part unique identifier, which can be referenced in API + endpoints. + created_at: + type: integer + description: The Unix timestamp (in seconds) for when the Part was created. + upload_id: + type: string + description: The ID of the Upload object that this Part was added to. + object: + type: string + description: The object type, which is always `upload.part`. + enum: + - upload.part + x-stainless-const: true + required: + - created_at + - id + - object + - upload_id + x-oaiMeta: + name: The upload part object + example: | + { + "id": "part_def456", + "object": "upload.part", + "created_at": 1719186911, + "upload_id": "upload_abc123" + } + UsageAudioSpeechesResult: + type: object + description: The aggregated audio speeches usage details of the specific time bucket. + properties: + object: + type: string + enum: + - organization.usage.audio_speeches.result + x-stainless-const: true + characters: + type: integer + description: The number of characters processed. + num_model_requests: + type: integer + description: The count of requests made to the model. + project_id: + type: string + nullable: true + description: When `group_by=project_id`, this field provides the project ID of + the grouped usage result. + user_id: + type: string + nullable: true + description: When `group_by=user_id`, this field provides the user ID of the + grouped usage result. + api_key_id: + type: string + nullable: true + description: When `group_by=api_key_id`, this field provides the API key ID of + the grouped usage result. + model: + type: string + nullable: true + description: When `group_by=model`, this field provides the model name of the + grouped usage result. + required: + - object + - characters + - num_model_requests + x-oaiMeta: + name: Audio speeches usage object + example: | + { + "object": "organization.usage.audio_speeches.result", + "characters": 45, + "num_model_requests": 1, + "project_id": "proj_abc", + "user_id": "user-abc", + "api_key_id": "key_abc", + "model": "tts-1" + } + UsageAudioTranscriptionsResult: + type: object + description: The aggregated audio transcriptions usage details of the specific + time bucket. + properties: + object: + type: string + enum: + - organization.usage.audio_transcriptions.result + x-stainless-const: true + seconds: + type: integer + description: The number of seconds processed. + num_model_requests: + type: integer + description: The count of requests made to the model. + project_id: + type: string + nullable: true + description: When `group_by=project_id`, this field provides the project ID of + the grouped usage result. + user_id: + type: string + nullable: true + description: When `group_by=user_id`, this field provides the user ID of the + grouped usage result. + api_key_id: + type: string + nullable: true + description: When `group_by=api_key_id`, this field provides the API key ID of + the grouped usage result. + model: + type: string + nullable: true + description: When `group_by=model`, this field provides the model name of the + grouped usage result. + required: + - object + - seconds + - num_model_requests + x-oaiMeta: + name: Audio transcriptions usage object + example: | + { + "object": "organization.usage.audio_transcriptions.result", + "seconds": 10, + "num_model_requests": 1, + "project_id": "proj_abc", + "user_id": "user-abc", + "api_key_id": "key_abc", + "model": "tts-1" + } + UsageCodeInterpreterSessionsResult: + type: object + description: The aggregated code interpreter sessions usage details of the + specific time bucket. + properties: + object: + type: string + enum: + - organization.usage.code_interpreter_sessions.result + x-stainless-const: true + num_sessions: + type: integer + description: The number of code interpreter sessions. + project_id: + type: string + nullable: true + description: When `group_by=project_id`, this field provides the project ID of + the grouped usage result. + required: + - object + - sessions + x-oaiMeta: + name: Code interpreter sessions usage object + example: | + { + "object": "organization.usage.code_interpreter_sessions.result", + "num_sessions": 1, + "project_id": "proj_abc" + } + UsageCompletionsResult: + type: object + description: The aggregated completions usage details of the specific time bucket. + properties: + object: + type: string + enum: + - organization.usage.completions.result + x-stainless-const: true + input_tokens: + type: integer + description: The aggregated number of text input tokens used, including cached + tokens. For customers subscribe to scale tier, this includes scale + tier tokens. + input_cached_tokens: + type: integer + description: The aggregated number of text input tokens that has been cached + from previous requests. For customers subscribe to scale tier, this + includes scale tier tokens. + output_tokens: + type: integer + description: The aggregated number of text output tokens used. For customers + subscribe to scale tier, this includes scale tier tokens. + input_audio_tokens: + type: integer + description: The aggregated number of audio input tokens used, including cached + tokens. + output_audio_tokens: + type: integer + description: The aggregated number of audio output tokens used. + num_model_requests: + type: integer + description: The count of requests made to the model. + project_id: + type: string + nullable: true + description: When `group_by=project_id`, this field provides the project ID of + the grouped usage result. + user_id: + type: string + nullable: true + description: When `group_by=user_id`, this field provides the user ID of the + grouped usage result. + api_key_id: + type: string + nullable: true + description: When `group_by=api_key_id`, this field provides the API key ID of + the grouped usage result. + model: + type: string + nullable: true + description: When `group_by=model`, this field provides the model name of the + grouped usage result. + batch: + type: boolean + nullable: true + description: When `group_by=batch`, this field tells whether the grouped usage + result is batch or not. + required: + - object + - input_tokens + - output_tokens + - num_model_requests + x-oaiMeta: + name: Completions usage object + example: | + { + "object": "organization.usage.completions.result", + "input_tokens": 5000, + "output_tokens": 1000, + "input_cached_tokens": 4000, + "input_audio_tokens": 300, + "output_audio_tokens": 200, + "num_model_requests": 5, + "project_id": "proj_abc", + "user_id": "user-abc", + "api_key_id": "key_abc", + "model": "gpt-4o-mini-2024-07-18", + "batch": false + } + UsageEmbeddingsResult: + type: object + description: The aggregated embeddings usage details of the specific time bucket. + properties: + object: + type: string + enum: + - organization.usage.embeddings.result + x-stainless-const: true + input_tokens: + type: integer + description: The aggregated number of input tokens used. + num_model_requests: + type: integer + description: The count of requests made to the model. + project_id: + type: string + nullable: true + description: When `group_by=project_id`, this field provides the project ID of + the grouped usage result. + user_id: + type: string + nullable: true + description: When `group_by=user_id`, this field provides the user ID of the + grouped usage result. + api_key_id: + type: string + nullable: true + description: When `group_by=api_key_id`, this field provides the API key ID of + the grouped usage result. + model: + type: string + nullable: true + description: When `group_by=model`, this field provides the model name of the + grouped usage result. + required: + - object + - input_tokens + - num_model_requests + x-oaiMeta: + name: Embeddings usage object + example: | + { + "object": "organization.usage.embeddings.result", + "input_tokens": 20, + "num_model_requests": 2, + "project_id": "proj_abc", + "user_id": "user-abc", + "api_key_id": "key_abc", + "model": "text-embedding-ada-002-v2" + } + UsageImagesResult: + type: object + description: The aggregated images usage details of the specific time bucket. + properties: + object: + type: string + enum: + - organization.usage.images.result + x-stainless-const: true + images: + type: integer + description: The number of images processed. + num_model_requests: + type: integer + description: The count of requests made to the model. + source: + type: string + nullable: true + description: When `group_by=source`, this field provides the source of the + grouped usage result, possible values are `image.generation`, + `image.edit`, `image.variation`. + size: + type: string + nullable: true + description: When `group_by=size`, this field provides the image size of the + grouped usage result. + project_id: + type: string + nullable: true + description: When `group_by=project_id`, this field provides the project ID of + the grouped usage result. + user_id: + type: string + nullable: true + description: When `group_by=user_id`, this field provides the user ID of the + grouped usage result. + api_key_id: + type: string + nullable: true + description: When `group_by=api_key_id`, this field provides the API key ID of + the grouped usage result. + model: + type: string + nullable: true + description: When `group_by=model`, this field provides the model name of the + grouped usage result. + required: + - object + - images + - num_model_requests + x-oaiMeta: + name: Images usage object + example: | + { + "object": "organization.usage.images.result", + "images": 2, + "num_model_requests": 2, + "size": "1024x1024", + "source": "image.generation", + "project_id": "proj_abc", + "user_id": "user-abc", + "api_key_id": "key_abc", + "model": "dall-e-3" + } + UsageModerationsResult: + type: object + description: The aggregated moderations usage details of the specific time bucket. + properties: + object: + type: string + enum: + - organization.usage.moderations.result + x-stainless-const: true + input_tokens: + type: integer + description: The aggregated number of input tokens used. + num_model_requests: + type: integer + description: The count of requests made to the model. + project_id: + type: string + nullable: true + description: When `group_by=project_id`, this field provides the project ID of + the grouped usage result. + user_id: + type: string + nullable: true + description: When `group_by=user_id`, this field provides the user ID of the + grouped usage result. + api_key_id: + type: string + nullable: true + description: When `group_by=api_key_id`, this field provides the API key ID of + the grouped usage result. + model: + type: string + nullable: true + description: When `group_by=model`, this field provides the model name of the + grouped usage result. + required: + - object + - input_tokens + - num_model_requests + x-oaiMeta: + name: Moderations usage object + example: | + { + "object": "organization.usage.moderations.result", + "input_tokens": 20, + "num_model_requests": 2, + "project_id": "proj_abc", + "user_id": "user-abc", + "api_key_id": "key_abc", + "model": "text-moderation" + } + UsageResponse: + type: object + properties: + object: + type: string + enum: + - page + x-stainless-const: true + data: + type: array + items: + $ref: "#/components/schemas/UsageTimeBucket" + has_more: + type: boolean + next_page: + type: string + required: + - object + - data + - has_more + - next_page + UsageTimeBucket: + type: object + properties: + object: + type: string + enum: + - bucket + x-stainless-const: true + start_time: + type: integer + end_time: + type: integer + result: + type: array + items: + oneOf: + - $ref: "#/components/schemas/UsageCompletionsResult" + - $ref: "#/components/schemas/UsageEmbeddingsResult" + - $ref: "#/components/schemas/UsageModerationsResult" + - $ref: "#/components/schemas/UsageImagesResult" + - $ref: "#/components/schemas/UsageAudioSpeechesResult" + - $ref: "#/components/schemas/UsageAudioTranscriptionsResult" + - $ref: "#/components/schemas/UsageVectorStoresResult" + - $ref: "#/components/schemas/UsageCodeInterpreterSessionsResult" + - $ref: "#/components/schemas/CostsResult" + required: + - object + - start_time + - end_time + - result + UsageVectorStoresResult: + type: object + description: The aggregated vector stores usage details of the specific time bucket. + properties: + object: + type: string + enum: + - organization.usage.vector_stores.result + x-stainless-const: true + usage_bytes: + type: integer + description: The vector stores usage in bytes. + project_id: + type: string + nullable: true + description: When `group_by=project_id`, this field provides the project ID of + the grouped usage result. + required: + - object + - usage_bytes + x-oaiMeta: + name: Vector stores usage object + example: | + { + "object": "organization.usage.vector_stores.result", + "usage_bytes": 1024, + "project_id": "proj_abc" + } + User: + type: object + description: Represents an individual `user` within an organization. + properties: + object: + type: string + enum: + - organization.user + description: The object type, which is always `organization.user` + x-stainless-const: true + id: + type: string + description: The identifier, which can be referenced in API endpoints + name: + type: string + description: The name of the user + email: + type: string + description: The email address of the user + role: + type: string + enum: + - owner + - reader + description: "`owner` or `reader`" + added_at: + type: integer + description: The Unix timestamp (in seconds) of when the user was added. + required: + - object + - id + - name + - email + - role + - added_at + x-oaiMeta: + name: The user object + example: | + { + "object": "organization.user", + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "added_at": 1711471533 + } + UserDeleteResponse: + type: object + properties: + object: + type: string + enum: + - organization.user.deleted + x-stainless-const: true + id: + type: string + deleted: + type: boolean + required: + - object + - id + - deleted + UserListResponse: + type: object + properties: + object: + type: string + enum: + - list + x-stainless-const: true + data: + type: array + items: + $ref: "#/components/schemas/User" + first_id: + type: string + last_id: + type: string + has_more: + type: boolean + required: + - object + - data + - first_id + - last_id + - has_more + UserRoleUpdateRequest: + type: object + properties: + role: + type: string + enum: + - owner + - reader + description: "`owner` or `reader`" + required: + - role + VectorStoreExpirationAfter: + type: object + title: Vector store expiration policy + description: The expiration policy for a vector store. + properties: + anchor: + description: "Anchor timestamp after which the expiration policy applies. + Supported anchors: `last_active_at`." + type: string + enum: + - last_active_at + x-stainless-const: true + days: + description: The number of days after the anchor time that the vector store will + expire. + type: integer + minimum: 1 + maximum: 365 + required: + - anchor + - days + VectorStoreFileAttributes: + type: object + description: > + Set of 16 key-value pairs that can be attached to an object. This can + be + + useful for storing additional information about the object in a + structured + + format, and querying for objects via API or the dashboard. Keys are + strings + + with a maximum length of 64 characters. Values are strings with a + maximum + + length of 512 characters, booleans, or numbers. + maxProperties: 16 + propertyNames: + type: string + maxLength: 64 + additionalProperties: + oneOf: + - type: string + maxLength: 512 + - type: number + - type: boolean + x-oaiTypeLabel: map + nullable: true + VectorStoreFileBatchObject: + type: object + title: Vector store file batch + description: A batch of files attached to a vector store. + properties: + id: + description: The identifier, which can be referenced in API endpoints. + type: string + object: + description: The object type, which is always `vector_store.file_batch`. + type: string + enum: + - vector_store.files_batch + x-stainless-const: true + created_at: + description: The Unix timestamp (in seconds) for when the vector store files + batch was created. + type: integer + vector_store_id: + description: The ID of the [vector + store](/docs/api-reference/vector-stores/object) that the + [File](/docs/api-reference/files) is attached to. + type: string + status: + description: The status of the vector store files batch, which can be either + `in_progress`, `completed`, `cancelled` or `failed`. + type: string + enum: + - in_progress + - completed + - cancelled + - failed + file_counts: + type: object + properties: + in_progress: + description: The number of files that are currently being processed. + type: integer + completed: + description: The number of files that have been processed. + type: integer + failed: + description: The number of files that have failed to process. + type: integer + cancelled: + description: The number of files that where cancelled. + type: integer + total: + description: The total number of files. + type: integer + required: + - in_progress + - completed + - cancelled + - failed + - total + required: + - id + - object + - created_at + - vector_store_id + - status + - file_counts + x-oaiMeta: + name: The vector store files batch object + beta: true + example: | + { + "id": "vsfb_123", + "object": "vector_store.files_batch", + "created_at": 1698107661, + "vector_store_id": "vs_abc123", + "status": "completed", + "file_counts": { + "in_progress": 0, + "completed": 100, + "failed": 0, + "cancelled": 0, + "total": 100 + } + } + VectorStoreFileContentResponse: + type: object + description: Represents the parsed content of a vector store file. + properties: + object: + type: string + enum: + - vector_store.file_content.page + description: The object type, which is always `vector_store.file_content.page` + x-stainless-const: true + data: + type: array + description: Parsed content of the file. + items: + type: object + properties: + type: + type: string + description: The content type (currently only `"text"`) + text: + type: string + description: The text content + has_more: + type: boolean + description: Indicates if there are more content pages to fetch. + next_page: + type: string + description: The token for the next page, if any. + nullable: true + required: + - object + - data + - has_more + - next_page + VectorStoreFileObject: + type: object + title: Vector store files + description: A list of files attached to a vector store. + properties: + id: + description: The identifier, which can be referenced in API endpoints. + type: string + object: + description: The object type, which is always `vector_store.file`. + type: string + enum: + - vector_store.file + x-stainless-const: true + usage_bytes: + description: The total vector store usage in bytes. Note that this may be + different from the original file size. + type: integer + created_at: + description: The Unix timestamp (in seconds) for when the vector store file was + created. + type: integer + vector_store_id: + description: The ID of the [vector + store](/docs/api-reference/vector-stores/object) that the + [File](/docs/api-reference/files) is attached to. + type: string + status: + description: The status of the vector store file, which can be either + `in_progress`, `completed`, `cancelled`, or `failed`. The status + `completed` indicates that the vector store file is ready for use. + type: string + enum: + - in_progress + - completed + - cancelled + - failed + last_error: + type: object + description: The last error associated with this vector store file. Will be + `null` if there are no errors. + nullable: true + properties: + code: + type: string + description: One of `server_error` or `rate_limit_exceeded`. + enum: + - server_error + - unsupported_file + - invalid_file + message: + type: string + description: A human-readable description of the error. + required: + - code + - message + chunking_strategy: + type: object + description: The strategy used to chunk the file. + oneOf: + - $ref: "#/components/schemas/StaticChunkingStrategyResponseParam" + - $ref: "#/components/schemas/OtherChunkingStrategyResponseParam" + attributes: + $ref: "#/components/schemas/VectorStoreFileAttributes" + required: + - id + - object + - usage_bytes + - created_at + - vector_store_id + - status + - last_error + x-oaiMeta: + name: The vector store file object + beta: true + example: | + { + "id": "file-abc123", + "object": "vector_store.file", + "usage_bytes": 1234, + "created_at": 1698107661, + "vector_store_id": "vs_abc123", + "status": "completed", + "last_error": null, + "chunking_strategy": { + "type": "static", + "static": { + "max_chunk_size_tokens": 800, + "chunk_overlap_tokens": 400 + } + } + } + VectorStoreObject: + type: object + title: Vector store + description: A vector store is a collection of processed files can be used by + the `file_search` tool. + properties: + id: + description: The identifier, which can be referenced in API endpoints. + type: string + object: + description: The object type, which is always `vector_store`. + type: string + enum: + - vector_store + x-stainless-const: true + created_at: + description: The Unix timestamp (in seconds) for when the vector store was + created. + type: integer + name: + description: The name of the vector store. + type: string + usage_bytes: + description: The total number of bytes used by the files in the vector store. + type: integer + file_counts: + type: object + properties: + in_progress: + description: The number of files that are currently being processed. + type: integer + completed: + description: The number of files that have been successfully processed. + type: integer + failed: + description: The number of files that have failed to process. + type: integer + cancelled: + description: The number of files that were cancelled. + type: integer + total: + description: The total number of files. + type: integer + required: + - in_progress + - completed + - failed + - cancelled + - total + status: + description: The status of the vector store, which can be either `expired`, + `in_progress`, or `completed`. A status of `completed` indicates + that the vector store is ready for use. + type: string + enum: + - expired + - in_progress + - completed + expires_after: + $ref: "#/components/schemas/VectorStoreExpirationAfter" + expires_at: + description: The Unix timestamp (in seconds) for when the vector store will + expire. + type: integer + nullable: true + last_active_at: + description: The Unix timestamp (in seconds) for when the vector store was last + active. + type: integer + nullable: true + metadata: + $ref: "#/components/schemas/Metadata" + required: + - id + - object + - usage_bytes + - created_at + - status + - last_active_at + - name + - file_counts + - metadata + x-oaiMeta: + name: The vector store object + example: | + { + "id": "vs_123", + "object": "vector_store", + "created_at": 1698107661, + "usage_bytes": 123456, + "last_active_at": 1698107661, + "name": "my_vector_store", + "status": "completed", + "file_counts": { + "in_progress": 0, + "completed": 100, + "cancelled": 0, + "failed": 0, + "total": 100 + }, + "last_used_at": 1698107661 + } + VectorStoreSearchRequest: + type: object + additionalProperties: false + properties: + query: + description: A query string for a search + oneOf: + - type: string + - type: array + items: + type: string + description: A list of queries to search for. + minItems: 1 + rewrite_query: + description: Whether to rewrite the natural language query for vector search. + type: boolean + default: false + max_num_results: + description: The maximum number of results to return. This number should be + between 1 and 50 inclusive. + type: integer + default: 10 + minimum: 1 + maximum: 50 + filters: + description: A filter to apply based on file attributes. + oneOf: + - $ref: "#/components/schemas/ComparisonFilter" + - $ref: "#/components/schemas/CompoundFilter" + ranking_options: + description: Ranking options for search. + type: object + additionalProperties: false + properties: + ranker: + type: string + enum: + - auto + - default-2024-11-15 + default: auto + score_threshold: + type: number + minimum: 0 + maximum: 1 + default: 0 + required: + - query + x-oaiMeta: + name: Vector store search request + VectorStoreSearchResultContentObject: + type: object + additionalProperties: false + properties: + type: + description: The type of content. + type: string + enum: + - text + text: + description: The text content returned from search. + type: string + required: + - type + - text + x-oaiMeta: + name: Vector store search result content object + VectorStoreSearchResultItem: + type: object + additionalProperties: false + properties: + file_id: + type: string + description: The ID of the vector store file. + filename: + type: string + description: The name of the vector store file. + score: + type: number + description: The similarity score for the result. + minimum: 0 + maximum: 1 + attributes: + $ref: "#/components/schemas/VectorStoreFileAttributes" + content: + type: array + description: Content chunks from the file. + items: + $ref: "#/components/schemas/VectorStoreSearchResultContentObject" + required: + - file_id + - filename + - score + - attributes + - content + x-oaiMeta: + name: Vector store search result item + VectorStoreSearchResultsPage: + type: object + additionalProperties: false + properties: + object: + type: string + enum: + - vector_store.search_results.page + description: The object type, which is always `vector_store.search_results.page` + x-stainless-const: true + search_query: + type: array + items: + type: string + description: The query used for this search. + minItems: 1 + data: + type: array + description: The list of search result items. + items: + $ref: "#/components/schemas/VectorStoreSearchResultItem" + has_more: + type: boolean + description: Indicates if there are more results to fetch. + next_page: + type: string + description: The token for the next page, if any. + nullable: true + required: + - object + - search_query + - data + - has_more + - next_page + x-oaiMeta: + name: Vector store search results page + VoiceIdsShared: + example: ash + anyOf: + - type: string + - type: string + enum: + - alloy + - ash + - ballad + - coral + - echo + - fable + - onyx + - nova + - sage + - shimmer + - verse + Wait: + type: object + title: Wait + description: | + A wait action. + properties: + type: + type: string + enum: + - wait + default: wait + description: | + Specifies the event type. For a wait action, this property is + always set to `wait`. + x-stainless-const: true + required: + - type + WebSearchContextSize: + type: string + description: > + High level guidance for the amount of context window space to use for + the + + search. One of `low`, `medium`, or `high`. `medium` is the default. + enum: + - low + - medium + - high + default: medium + WebSearchLocation: + type: object + title: Web search location + description: Approximate location parameters for the search. + properties: + country: + type: string + description: > + The two-letter + + [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the + user, + + e.g. `US`. + region: + type: string + description: | + Free text input for the region of the user, e.g. `California`. + city: + type: string + description: | + Free text input for the city of the user, e.g. `San Francisco`. + timezone: + type: string + description: > + The [IANA + timezone](https://timeapi.io/documentation/iana-timezones) + + of the user, e.g. `America/Los_Angeles`. + WebSearchToolCall: + type: object + title: Web search tool call + description: | + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. + properties: + id: + type: string + description: | + The unique ID of the web search tool call. + type: + type: string + enum: + - web_search_call + description: | + The type of the web search tool call. Always `web_search_call`. + x-stainless-const: true + status: + type: string + description: | + The status of the web search tool call. + enum: + - in_progress + - searching + - completed + - failed + required: + - id + - type + - status + InputTextContent: + properties: + type: + type: string + enum: + - input_text + description: The type of the input item. Always `input_text`. + default: input_text + x-stainless-const: true + text: + type: string + description: The text input to the model. + type: object + required: + - type + - text + title: Input text + description: A text input to the model. + InputImageContent: + properties: + type: + type: string + enum: + - input_image + description: The type of the input item. Always `input_image`. + default: input_image + x-stainless-const: true + image_url: + anyOf: + - type: string + description: The URL of the image to be sent to the model. A fully qualified URL + or base64 encoded image in a data URL. + - type: "null" + file_id: + anyOf: + - type: string + description: The ID of the file to be sent to the model. + - type: "null" + detail: + type: string + enum: + - low + - high + - auto + description: The detail level of the image to be sent to the model. One of + `high`, `low`, or `auto`. Defaults to `auto`. + type: object + required: + - type + - detail + title: Input image + description: An image input to the model. Learn about [image + inputs](/docs/guides/vision). + InputFileContent: + properties: + type: + type: string + enum: + - input_file + description: The type of the input item. Always `input_file`. + default: input_file + x-stainless-const: true + file_id: + anyOf: + - type: string + description: The ID of the file to be sent to the model. + - type: "null" + filename: + type: string + description: The name of the file to be sent to the model. + file_data: + type: string + description: | + The content of the file to be sent to the model. + type: object + required: &a1 + - type + title: Input file + description: A file input to the model. + RankingOptions: + properties: + ranker: + type: string + enum: + - auto + - default-2024-11-15 + description: The ranker to use for the file search. + score_threshold: + type: number + description: The score threshold for the file search, a number between 0 and 1. + Numbers closer to 1 will attempt to return only the most relevant + results, but may return fewer results. + type: object + required: [] + Filters: + anyOf: + - $ref: "#/components/schemas/ComparisonFilter" + - $ref: "#/components/schemas/CompoundFilter" + FileSearchTool: + properties: + type: + type: string + enum: + - file_search + description: The type of the file search tool. Always `file_search`. + default: file_search + x-stainless-const: true + vector_store_ids: + items: + type: string + type: array + description: The IDs of the vector stores to search. + max_num_results: + type: integer + description: The maximum number of results to return. This number should be + between 1 and 50 inclusive. + ranking_options: + $ref: "#/components/schemas/RankingOptions" + description: Ranking options for search. + filters: + anyOf: + - $ref: "#/components/schemas/Filters" + description: A filter to apply. + - type: "null" + type: object + required: + - type + - vector_store_ids + title: File search + description: A tool that searches for relevant content from uploaded files. + Learn more about the [file search + tool](https://platform.openai.com/docs/guides/tools-file-search). + FunctionTool: + properties: + type: + type: string + enum: + - function + description: The type of the function tool. Always `function`. + default: function + x-stainless-const: true + name: + type: string + description: The name of the function to call. + description: + anyOf: + - type: string + description: A description of the function. Used by the model to determine + whether or not to call the function. + - type: "null" + parameters: + anyOf: + - additionalProperties: {} + type: object + description: A JSON schema object describing the parameters of the function. + - type: "null" + strict: + anyOf: + - type: boolean + description: Whether to enforce strict parameter validation. Default `true`. + - type: "null" + type: object + required: + - type + - name + - strict + - parameters + title: Function + description: Defines a function in your own code the model can choose to call. + Learn more about [function + calling](https://platform.openai.com/docs/guides/function-calling). + ApproximateLocation: + properties: + type: + type: string + enum: + - approximate + description: The type of location approximation. Always `approximate`. + default: approximate + x-stainless-const: true + country: + anyOf: + - type: string + description: The two-letter [ISO country + code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, + e.g. `US`. + - type: "null" + region: + anyOf: + - type: string + description: Free text input for the region of the user, e.g. `California`. + - type: "null" + city: + anyOf: + - type: string + description: Free text input for the city of the user, e.g. `San Francisco`. + - type: "null" + timezone: + anyOf: + - type: string + description: The [IANA + timezone](https://timeapi.io/documentation/iana-timezones) of + the user, e.g. `America/Los_Angeles`. + - type: "null" + type: object + required: *a1 + WebSearchPreviewTool: + properties: + type: + type: string + enum: + - web_search_preview + - web_search_preview_2025_03_11 + description: The type of the web search tool. One of `web_search_preview` or + `web_search_preview_2025_03_11`. + default: web_search_preview + x-stainless-const: true + user_location: + anyOf: + - $ref: "#/components/schemas/ApproximateLocation" + description: The user's location. + - type: "null" + search_context_size: + type: string + enum: + - low + - medium + - high + description: High level guidance for the amount of context window space to use + for the search. One of `low`, `medium`, or `high`. `medium` is the + default. + type: object + required: *a1 + title: Web search preview + description: This tool searches the web for relevant results to use in a + response. Learn more about the [web search + tool](https://platform.openai.com/docs/guides/tools-web-search). + ComputerUsePreviewTool: + properties: + type: + type: string + enum: + - computer_use_preview + description: The type of the computer use tool. Always `computer_use_preview`. + default: computer_use_preview + x-stainless-const: true + environment: + type: string + enum: + - windows + - mac + - linux + - ubuntu + - browser + description: The type of computer environment to control. + display_width: + type: integer + description: The width of the computer display. + display_height: + type: integer + description: The height of the computer display. + type: object + required: + - type + - environment + - display_width + - display_height + title: Computer use preview + description: A tool that controls a virtual computer. Learn more about the + [computer + tool](https://platform.openai.com/docs/guides/tools-computer-use). + Tool: + oneOf: + - $ref: "#/components/schemas/FileSearchTool" + - $ref: "#/components/schemas/FunctionTool" + - $ref: "#/components/schemas/WebSearchPreviewTool" + - $ref: "#/components/schemas/ComputerUsePreviewTool" + discriminator: + propertyName: type + FileCitationBody: + properties: + type: + type: string + enum: + - file_citation + description: The type of the file citation. Always `file_citation`. + default: file_citation + x-stainless-const: true + file_id: + type: string + description: The ID of the file. + index: + type: integer + description: The index of the file in the list of files. + type: object + required: + - type + - file_id + - index + title: File citation + description: A citation to a file. + UrlCitationBody: + properties: + type: + type: string + enum: + - url_citation + description: The type of the URL citation. Always `url_citation`. + default: url_citation + x-stainless-const: true + url: + type: string + description: The URL of the web resource. + start_index: + type: integer + description: The index of the first character of the URL citation in the message. + end_index: + type: integer + description: The index of the last character of the URL citation in the message. + title: + type: string + description: The title of the web resource. + type: object + required: + - type + - url + - start_index + - end_index + - title + title: URL citation + description: A citation for a web resource used to generate a model response. + Annotation: + oneOf: + - $ref: "#/components/schemas/FileCitationBody" + - $ref: "#/components/schemas/UrlCitationBody" + - $ref: "#/components/schemas/FilePath" + discriminator: + propertyName: type + OutputTextContent: + properties: + type: + type: string + enum: + - output_text + description: The type of the output text. Always `output_text`. + default: output_text + x-stainless-const: true + text: + type: string + description: The text output from the model. + annotations: + items: + $ref: "#/components/schemas/Annotation" + type: array + description: The annotations of the text output. + type: object + required: + - type + - text + - annotations + title: Output text + description: A text output from the model. + RefusalContent: + properties: + type: + type: string + enum: + - refusal + description: The type of the refusal. Always `refusal`. + default: refusal + x-stainless-const: true + refusal: + type: string + description: The refusal explanationfrom the model. + type: object + required: + - type + - refusal + title: Refusal + description: A refusal from the model. + ComputerCallSafetyCheckParam: + properties: + id: + type: string + description: The ID of the pending safety check. + code: + anyOf: + - type: string + description: The type of the pending safety check. + - type: "null" + message: + anyOf: + - type: string + description: Details about the pending safety check. + - type: "null" + type: object + required: + - id + description: A pending safety check for the computer call. + ComputerCallOutputItemParam: + properties: + id: + anyOf: + - type: string + description: The ID of the computer tool call output. + - type: "null" + call_id: + type: string + maxLength: 64 + minLength: 1 + description: The ID of the computer tool call that produced the output. + type: + type: string + enum: + - computer_call_output + description: The type of the computer tool call output. Always + `computer_call_output`. + default: computer_call_output + x-stainless-const: true + output: + $ref: "#/components/schemas/ComputerScreenshotImage" + acknowledged_safety_checks: + anyOf: + - items: + $ref: "#/components/schemas/ComputerCallSafetyCheckParam" + type: array + description: The safety checks reported by the API that have been acknowledged + by the developer. + - type: "null" + status: + anyOf: + - type: string + enum: + - in_progress + - completed + - incomplete + description: The status of the message input. One of `in_progress`, `completed`, + or `incomplete`. Populated when input items are returned via + API. + - type: "null" + type: object + required: + - call_id + - type + - output + title: Computer tool call output + description: The output of a computer tool call. + FunctionCallOutputItemParam: + properties: + id: + anyOf: + - type: string + description: The unique ID of the function tool call output. Populated when this + item is returned via API. + - type: "null" + call_id: + type: string + maxLength: 64 + minLength: 1 + description: The unique ID of the function tool call generated by the model. + type: + type: string + enum: + - function_call_output + description: The type of the function tool call output. Always + `function_call_output`. + default: function_call_output + x-stainless-const: true + output: + type: string + maxLength: 10485760 + description: A JSON string of the output of the function tool call. + status: + anyOf: + - type: string + enum: + - in_progress + - completed + - incomplete + description: The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + - type: "null" + type: object + required: + - call_id + - type + - output + title: Function tool call output + description: The output of a function tool call. + ItemReferenceParam: + properties: + type: + anyOf: + - type: string + enum: + - item_reference + description: The type of item to reference. Always `item_reference`. + default: item_reference + x-stainless-const: true + - type: "null" + id: + type: string + description: The ID of the item to reference. + type: object + required: + - id + title: Item reference + description: An internal identifier for an item to reference. + securitySchemes: + ApiKeyAuth: + type: http + scheme: bearer +x-oaiMeta: + navigationGroups: + - id: responses + title: Responses + - id: chat + title: Chat Completions + - id: realtime + title: Realtime + beta: true + - id: endpoints + title: Platform APIs + - id: vector_stores + title: Vector stores + - id: assistants + title: Assistants + beta: true + - id: administration + title: Administration + - id: legacy + title: Legacy + groups: + - id: responses + title: Responses + description: > + OpenAI's most advanced interface for generating model responses. + Supports + + text and image inputs, and text outputs. Create stateful interactions + + with the model, using the output of previous responses as input. Extend + + the model's capabilities with built-in tools for file search, web + search, + + computer use, and more. Allow the model access to external systems and + data + + using function calling. + + + Related guides: + + - [Quickstart](/docs/quickstart?api-mode=responses) + + - [Text inputs and outputs](/docs/guides/text?api-mode=responses) + + - [Image inputs](/docs/guides/images?api-mode=responses) + + - [Structured + Outputs](/docs/guides/structured-outputs?api-mode=responses) + + - [Function calling](/docs/guides/function-calling?api-mode=responses) + + - [Conversation + state](/docs/guides/conversation-state?api-mode=responses) + + - [Extend the models with tools](/docs/guides/tools?api-mode=responses) + navigationGroup: responses + sections: + - type: endpoint + key: createResponse + path: create + - type: endpoint + key: getResponse + path: get + - type: endpoint + key: deleteResponse + path: delete + - type: endpoint + key: listInputItems + path: input-items + - type: object + key: Response + path: object + - type: object + key: ResponseItemList + path: list + - id: responses-streaming + title: Streaming + description: > + When you [create a Response](/docs/api-reference/responses/create) with + + `stream` set to `true`, the server will emit server-sent events to the + + client as the Response is generated. This section contains the events + that + + are emitted by the server. + + + [Learn more about streaming + responses](/docs/guides/streaming-responses?api-mode=responses). + navigationGroup: responses + sections: + - type: object + key: ResponseCreatedEvent + path: + - type: object + key: ResponseInProgressEvent + path: + - type: object + key: ResponseCompletedEvent + path: + - type: object + key: ResponseFailedEvent + path: + - type: object + key: ResponseIncompleteEvent + path: + - type: object + key: ResponseOutputItemAddedEvent + path: + - type: object + key: ResponseOutputItemDoneEvent + path: + - type: object + key: ResponseContentPartAddedEvent + path: + - type: object + key: ResponseContentPartDoneEvent + path: + - type: object + key: ResponseTextDeltaEvent + path: + - type: object + key: ResponseTextAnnotationDeltaEvent + path: + - type: object + key: ResponseTextDoneEvent + path: + - type: object + key: ResponseRefusalDeltaEvent + path: + - type: object + key: ResponseRefusalDoneEvent + path: + - type: object + key: ResponseFunctionCallArgumentsDeltaEvent + path: + - type: object + key: ResponseFunctionCallArgumentsDoneEvent + path: + - type: object + key: ResponseFileSearchCallInProgressEvent + path: + - type: object + key: ResponseFileSearchCallSearchingEvent + path: + - type: object + key: ResponseFileSearchCallCompletedEvent + path: + - type: object + key: ResponseWebSearchCallInProgressEvent + path: + - type: object + key: ResponseWebSearchCallSearchingEvent + path: + - type: object + key: ResponseWebSearchCallCompletedEvent + path: + - type: object + key: ResponseReasoningSummaryPartAddedEvent + path: + - type: object + key: ResponseReasoningSummaryPartDoneEvent + path: + - type: object + key: ResponseReasoningSummaryTextDeltaEvent + path: + - type: object + key: ResponseReasoningSummaryTextDoneEvent + path: + - type: object + key: ResponseErrorEvent + path: + - id: chat + title: Chat Completions + description: | + The Chat Completions API endpoint will generate a model response from a + list of messages comprising a conversation. + + Related guides: + - [Quickstart](/docs/quickstart?api-mode=chat) + - [Text inputs and outputs](/docs/guides/text?api-mode=chat) + - [Image inputs](/docs/guides/images?api-mode=chat) + - [Audio inputs and outputs](/docs/guides/audio?api-mode=chat) + - [Structured Outputs](/docs/guides/structured-outputs?api-mode=chat) + - [Function calling](/docs/guides/function-calling?api-mode=chat) + - [Conversation state](/docs/guides/conversation-state?api-mode=chat) + + **Starting a new project?** We recommend trying [Responses](/docs/api-reference/responses) + to take advantage of the latest OpenAI platform features. Compare + [Chat Completions with Responses](/docs/guides/responses-vs-chat-completions?api-mode=responses). + navigationGroup: chat + sections: + - type: endpoint + key: createChatCompletion + path: create + - type: endpoint + key: getChatCompletion + path: get + - type: endpoint + key: getChatCompletionMessages + path: getMessages + - type: endpoint + key: listChatCompletions + path: list + - type: endpoint + key: updateChatCompletion + path: update + - type: endpoint + key: deleteChatCompletion + path: delete + - type: object + key: CreateChatCompletionResponse + path: object + - type: object + key: ChatCompletionList + path: list-object + - type: object + key: ChatCompletionMessageList + path: message-list + - id: chat-streaming + title: Streaming + description: | + Stream Chat Completions in real time. Receive chunks of completions + returned from the model using server-sent events. + [Learn more](/docs/guides/streaming-responses?api-mode=chat). + navigationGroup: chat + sections: + - type: object + key: CreateChatCompletionStreamResponse + path: streaming + - id: realtime + title: Realtime + beta: true + description: | + Communicate with a GPT-4o class model in real time using WebRTC or + WebSockets. Supports text and audio inputs and ouputs, along with audio + transcriptions. + [Learn more about the Realtime API](/docs/guides/realtime). + navigationGroup: realtime + - id: realtime-sessions + title: Session tokens + description: > + REST API endpoint to generate ephemeral session tokens for use in + client-side + + applications. + navigationGroup: realtime + sections: + - type: endpoint + key: create-realtime-session + path: create + - type: endpoint + key: create-realtime-transcription-session + path: create-transcription + - type: object + key: RealtimeSessionCreateResponse + path: session_object + - type: object + key: RealtimeTranscriptionSessionCreateResponse + path: transcription_session_object + - id: realtime-client-events + title: Client events + description: > + These are events that the OpenAI Realtime WebSocket server will accept + from the client. + navigationGroup: realtime + sections: + - type: object + key: RealtimeClientEventSessionUpdate + path: + - type: object + key: RealtimeClientEventInputAudioBufferAppend + path: + - type: object + key: RealtimeClientEventInputAudioBufferCommit + path: + - type: object + key: RealtimeClientEventInputAudioBufferClear + path: + - type: object + key: RealtimeClientEventConversationItemCreate + path: + - type: object + key: RealtimeClientEventConversationItemRetrieve + path: + - type: object + key: RealtimeClientEventConversationItemTruncate + path: + - type: object + key: RealtimeClientEventConversationItemDelete + path: + - type: object + key: RealtimeClientEventResponseCreate + path: + - type: object + key: RealtimeClientEventResponseCancel + path: + - type: object + key: RealtimeClientEventTranscriptionSessionUpdate + path: + - type: object + key: RealtimeClientEventOutputAudioBufferClear + path: + - id: realtime-server-events + title: Server events + description: > + These are events emitted from the OpenAI Realtime WebSocket server to + the client. + navigationGroup: realtime + sections: + - type: object + key: RealtimeServerEventError + path: + - type: object + key: RealtimeServerEventSessionCreated + path: + - type: object + key: RealtimeServerEventSessionUpdated + path: + - type: object + key: RealtimeServerEventConversationCreated + path: + - type: object + key: RealtimeServerEventConversationItemCreated + path: + - type: object + key: RealtimeServerEventConversationItemRetrieved + path: + - type: object + key: RealtimeServerEventConversationItemInputAudioTranscriptionCompleted + path: + - type: object + key: RealtimeServerEventConversationItemInputAudioTranscriptionDelta + path: + - type: object + key: RealtimeServerEventConversationItemInputAudioTranscriptionFailed + path: + - type: object + key: RealtimeServerEventConversationItemTruncated + path: + - type: object + key: RealtimeServerEventConversationItemDeleted + path: + - type: object + key: RealtimeServerEventInputAudioBufferCommitted + path: + - type: object + key: RealtimeServerEventInputAudioBufferCleared + path: + - type: object + key: RealtimeServerEventInputAudioBufferSpeechStarted + path: + - type: object + key: RealtimeServerEventInputAudioBufferSpeechStopped + path: + - type: object + key: RealtimeServerEventResponseCreated + path: + - type: object + key: RealtimeServerEventResponseDone + path: + - type: object + key: RealtimeServerEventResponseOutputItemAdded + path: + - type: object + key: RealtimeServerEventResponseOutputItemDone + path: + - type: object + key: RealtimeServerEventResponseContentPartAdded + path: + - type: object + key: RealtimeServerEventResponseContentPartDone + path: + - type: object + key: RealtimeServerEventResponseTextDelta + path: + - type: object + key: RealtimeServerEventResponseTextDone + path: + - type: object + key: RealtimeServerEventResponseAudioTranscriptDelta + path: + - type: object + key: RealtimeServerEventResponseAudioTranscriptDone + path: + - type: object + key: RealtimeServerEventResponseAudioDelta + path: + - type: object + key: RealtimeServerEventResponseAudioDone + path: + - type: object + key: RealtimeServerEventResponseFunctionCallArgumentsDelta + path: + - type: object + key: RealtimeServerEventResponseFunctionCallArgumentsDone + path: + - type: object + key: RealtimeServerEventTranscriptionSessionUpdated + path: + - type: object + key: RealtimeServerEventRateLimitsUpdated + path: + - type: object + key: RealtimeServerEventOutputAudioBufferStarted + path: + - type: object + key: RealtimeServerEventOutputAudioBufferStopped + path: + - type: object + key: RealtimeServerEventOutputAudioBufferCleared + path: + - id: audio + title: Audio + description: | + Learn how to turn audio into text or text into audio. + + Related guide: [Speech to text](/docs/guides/speech-to-text) + navigationGroup: endpoints + sections: + - type: endpoint + key: createSpeech + path: createSpeech + - type: endpoint + key: createTranscription + path: createTranscription + - type: endpoint + key: createTranslation + path: createTranslation + - type: object + key: CreateTranscriptionResponseJson + path: json-object + - type: object + key: CreateTranscriptionResponseVerboseJson + path: verbose-json-object + - type: object + key: TranscriptTextDeltaEvent + path: transcript-text-delta-event + - type: object + key: TranscriptTextDoneEvent + path: transcript-text-done-event + - id: images + title: Images + description: > + Given a prompt and/or an input image, the model will generate a new + image. + + Related guide: [Image generation](/docs/guides/images) + navigationGroup: endpoints + sections: + - type: endpoint + key: createImage + path: create + - type: endpoint + key: createImageEdit + path: createEdit + - type: endpoint + key: createImageVariation + path: createVariation + - type: object + key: ImagesResponse + path: object + - id: embeddings + title: Embeddings + description: > + Get a vector representation of a given input that can be easily consumed + by machine learning models and algorithms. + + Related guide: [Embeddings](/docs/guides/embeddings) + navigationGroup: endpoints + sections: + - type: endpoint + key: createEmbedding + path: create + - type: object + key: Embedding + path: object + - id: evals + title: Evals + description: | + Create, manage, and run evals in the OpenAI platform. + Related guide: [Evals](/docs/guides/evals) + navigationGroup: endpoints + sections: + - type: endpoint + key: createEval + path: create + - type: endpoint + key: getEval + path: get + - type: endpoint + key: updateEval + path: update + - type: endpoint + key: deleteEval + path: delete + - type: endpoint + key: listEvals + path: list + - type: endpoint + key: getEvalRuns + path: getRuns + - type: endpoint + key: getEvalRun + path: getRun + - type: endpoint + key: createEvalRun + path: createRun + - type: endpoint + key: cancelEvalRun + path: cancelRun + - type: endpoint + key: deleteEvalRun + path: deleteRun + - type: endpoint + key: getEvalRunOutputItem + path: getRunOutputItem + - type: endpoint + key: getEvalRunOutputItems + path: getRunOutputItems + - type: object + key: Eval + path: object + - type: object + key: EvalRun + path: run-object + - type: object + key: EvalRunOutputItem + path: run-output-item-object + - id: fine-tuning + title: Fine-tuning + description: > + Manage fine-tuning jobs to tailor a model to your specific training + data. + + Related guide: [Fine-tune models](/docs/guides/fine-tuning) + navigationGroup: endpoints + sections: + - type: endpoint + key: createFineTuningJob + path: create + - type: endpoint + key: listPaginatedFineTuningJobs + path: list + - type: endpoint + key: listFineTuningEvents + path: list-events + - type: endpoint + key: listFineTuningJobCheckpoints + path: list-checkpoints + - type: endpoint + key: listFineTuningCheckpointPermissions + path: list-permissions + - type: endpoint + key: createFineTuningCheckpointPermission + path: create-permission + - type: endpoint + key: deleteFineTuningCheckpointPermission + path: delete-permission + - type: endpoint + key: retrieveFineTuningJob + path: retrieve + - type: endpoint + key: cancelFineTuningJob + path: cancel + - type: object + key: FineTuneChatRequestInput + path: chat-input + - type: object + key: FineTunePreferenceRequestInput + path: preference-input + - type: object + key: FineTuneCompletionRequestInput + path: completions-input + - type: object + key: FineTuningJob + path: object + - type: object + key: FineTuningJobEvent + path: event-object + - type: object + key: FineTuningJobCheckpoint + path: checkpoint-object + - type: object + key: FineTuningCheckpointPermission + path: permission-object + - id: batch + title: Batch + description: > + Create large batches of API requests for asynchronous processing. The + Batch API returns completions within 24 hours for a 50% discount. + + Related guide: [Batch](/docs/guides/batch) + navigationGroup: endpoints + sections: + - type: endpoint + key: createBatch + path: create + - type: endpoint + key: retrieveBatch + path: retrieve + - type: endpoint + key: cancelBatch + path: cancel + - type: endpoint + key: listBatches + path: list + - type: object + key: Batch + path: object + - type: object + key: BatchRequestInput + path: request-input + - type: object + key: BatchRequestOutput + path: request-output + - id: files + title: Files + description: > + Files are used to upload documents that can be used with features like + [Assistants](/docs/api-reference/assistants), + [Fine-tuning](/docs/api-reference/fine-tuning), and [Batch + API](/docs/guides/batch). + navigationGroup: endpoints + sections: + - type: endpoint + key: createFile + path: create + - type: endpoint + key: listFiles + path: list + - type: endpoint + key: retrieveFile + path: retrieve + - type: endpoint + key: deleteFile + path: delete + - type: endpoint + key: downloadFile + path: retrieve-contents + - type: object + key: OpenAIFile + path: object + - id: uploads + title: Uploads + description: | + Allows you to upload large files in multiple parts. + navigationGroup: endpoints + sections: + - type: endpoint + key: createUpload + path: create + - type: endpoint + key: addUploadPart + path: add-part + - type: endpoint + key: completeUpload + path: complete + - type: endpoint + key: cancelUpload + path: cancel + - type: object + key: Upload + path: object + - type: object + key: UploadPart + path: part-object + - id: models + title: Models + description: > + List and describe the various models available in the API. You can refer + to the [Models](/docs/models) documentation to understand what models + are available and the differences between them. + navigationGroup: endpoints + sections: + - type: endpoint + key: listModels + path: list + - type: endpoint + key: retrieveModel + path: retrieve + - type: endpoint + key: deleteModel + path: delete + - type: object + key: Model + path: object + - id: moderations + title: Moderations + description: > + Given text and/or image inputs, classifies if those inputs are + potentially harmful across several categories. + + Related guide: [Moderations](/docs/guides/moderation) + navigationGroup: endpoints + sections: + - type: endpoint + key: createModeration + path: create + - type: object + key: CreateModerationResponse + path: object + - id: vector-stores + title: Vector stores + description: > + Vector stores power semantic search for the Retrieval API and the + `file_search` tool in the Responses and Assistants APIs. + + + Related guide: [File Search](/docs/assistants/tools/file-search) + navigationGroup: vector_stores + sections: + - type: endpoint + key: createVectorStore + path: create + - type: endpoint + key: listVectorStores + path: list + - type: endpoint + key: getVectorStore + path: retrieve + - type: endpoint + key: modifyVectorStore + path: modify + - type: endpoint + key: deleteVectorStore + path: delete + - type: endpoint + key: searchVectorStore + path: search + - type: object + key: VectorStoreObject + path: object + - id: vector-stores-files + title: Vector store files + description: | + Vector store files represent files inside a vector store. + + Related guide: [File Search](/docs/assistants/tools/file-search) + navigationGroup: vector_stores + sections: + - type: endpoint + key: createVectorStoreFile + path: createFile + - type: endpoint + key: listVectorStoreFiles + path: listFiles + - type: endpoint + key: getVectorStoreFile + path: getFile + - type: endpoint + key: retrieveVectorStoreFileContent + path: getContent + - type: endpoint + key: updateVectorStoreFileAttributes + path: updateAttributes + - type: endpoint + key: deleteVectorStoreFile + path: deleteFile + - type: object + key: VectorStoreFileObject + path: file-object + - id: vector-stores-file-batches + title: Vector store file batches + description: > + Vector store file batches represent operations to add multiple files to + a vector store. + + Related guide: [File Search](/docs/assistants/tools/file-search) + navigationGroup: vector_stores + sections: + - type: endpoint + key: createVectorStoreFileBatch + path: createBatch + - type: endpoint + key: getVectorStoreFileBatch + path: getBatch + - type: endpoint + key: cancelVectorStoreFileBatch + path: cancelBatch + - type: endpoint + key: listFilesInVectorStoreBatch + path: listBatchFiles + - type: object + key: VectorStoreFileBatchObject + path: batch-object + - id: assistants + title: Assistants + beta: true + description: | + Build assistants that can call models and use tools to perform tasks. + + [Get started with the Assistants API](/docs/assistants) + navigationGroup: assistants + sections: + - type: endpoint + key: createAssistant + path: createAssistant + - type: endpoint + key: listAssistants + path: listAssistants + - type: endpoint + key: getAssistant + path: getAssistant + - type: endpoint + key: modifyAssistant + path: modifyAssistant + - type: endpoint + key: deleteAssistant + path: deleteAssistant + - type: object + key: AssistantObject + path: object + - id: threads + title: Threads + beta: true + description: | + Create threads that assistants can interact with. + + Related guide: [Assistants](/docs/assistants/overview) + navigationGroup: assistants + sections: + - type: endpoint + key: createThread + path: createThread + - type: endpoint + key: getThread + path: getThread + - type: endpoint + key: modifyThread + path: modifyThread + - type: endpoint + key: deleteThread + path: deleteThread + - type: object + key: ThreadObject + path: object + - id: messages + title: Messages + beta: true + description: | + Create messages within threads + + Related guide: [Assistants](/docs/assistants/overview) + navigationGroup: assistants + sections: + - type: endpoint + key: createMessage + path: createMessage + - type: endpoint + key: listMessages + path: listMessages + - type: endpoint + key: getMessage + path: getMessage + - type: endpoint + key: modifyMessage + path: modifyMessage + - type: endpoint + key: deleteMessage + path: deleteMessage + - type: object + key: MessageObject + path: object + - id: runs + title: Runs + beta: true + description: | + Represents an execution run on a thread. + + Related guide: [Assistants](/docs/assistants/overview) + navigationGroup: assistants + sections: + - type: endpoint + key: createRun + path: createRun + - type: endpoint + key: createThreadAndRun + path: createThreadAndRun + - type: endpoint + key: listRuns + path: listRuns + - type: endpoint + key: getRun + path: getRun + - type: endpoint + key: modifyRun + path: modifyRun + - type: endpoint + key: submitToolOuputsToRun + path: submitToolOutputs + - type: endpoint + key: cancelRun + path: cancelRun + - type: object + key: RunObject + path: object + - id: run-steps + title: Run steps + beta: true + description: | + Represents the steps (model and tool calls) taken during the run. + + Related guide: [Assistants](/docs/assistants/overview) + navigationGroup: assistants + sections: + - type: endpoint + key: listRunSteps + path: listRunSteps + - type: endpoint + key: getRunStep + path: getRunStep + - type: object + key: RunStepObject + path: step-object + - id: assistants-streaming + title: Streaming + beta: true + description: | + Stream the result of executing a Run or resuming a Run after submitting tool outputs. + You can stream events from the [Create Thread and Run](/docs/api-reference/runs/createThreadAndRun), + [Create Run](/docs/api-reference/runs/createRun), and [Submit Tool Outputs](/docs/api-reference/runs/submitToolOutputs) + endpoints by passing `"stream": true`. The response will be a [Server-Sent events](https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events) stream. + Our Node and Python SDKs provide helpful utilities to make streaming easy. Reference the + [Assistants API quickstart](/docs/assistants/overview) to learn more. + navigationGroup: assistants + sections: + - type: object + key: MessageDeltaObject + path: message-delta-object + - type: object + key: RunStepDeltaObject + path: run-step-delta-object + - type: object + key: AssistantStreamEvent + path: events + - id: administration + title: Administration + description: | + Programmatically manage your organization. + The Audit Logs endpoint provides a log of all actions taken in the organization for security and monitoring purposes. + To access these endpoints please generate an Admin API Key through the [API Platform Organization overview](/organization/admin-keys). Admin API keys cannot be used for non-administration endpoints. + For best practices on setting up your organization, please refer to this [guide](/docs/guides/production-best-practices#setting-up-your-organization) + navigationGroup: administration + - id: admin-api-keys + title: Admin API Keys + description: | + Admin API keys enable Organization Owners to programmatically manage various aspects of their organization, including users, projects, and API keys. These keys provide administrative capabilities, such as creating, updating, and deleting users; managing projects; and overseeing API key lifecycles. + + Key Features of Admin API Keys: + + - User Management: Invite new users, update roles, and remove users from the organization. + + - Project Management: Create, update, archive projects, and manage user assignments within projects. + + - API Key Oversight: List, retrieve, and delete API keys associated with projects. + + Only Organization Owners have the authority to create and utilize Admin API keys. To manage these keys, Organization Owners can navigate to the Admin Keys section of their API Platform dashboard. + + For direct access to the Admin Keys management page, Organization Owners can use the following link: + + [https://platform.openai.com/settings/organization/admin-keys](https://platform.openai.com/settings/organization/admin-keys) + + It's crucial to handle Admin API keys with care due to their elevated permissions. Adhering to best practices, such as regular key rotation and assigning appropriate permissions, enhances security and ensures proper governance within the organization. + navigationGroup: administration + sections: + - type: endpoint + key: admin-api-keys-list + path: list + - type: endpoint + key: admin-api-keys-create + path: create + - type: endpoint + key: admin-api-keys-get + path: listget + - type: endpoint + key: admin-api-keys-delete + path: delete + - type: object + key: AdminApiKey + path: object + - id: invite + title: Invites + description: Invite and manage invitations for an organization. + navigationGroup: administration + sections: + - type: endpoint + key: list-invites + path: list + - type: endpoint + key: inviteUser + path: create + - type: endpoint + key: retrieve-invite + path: retrieve + - type: endpoint + key: delete-invite + path: delete + - type: object + key: Invite + path: object + - id: users + title: Users + description: | + Manage users and their role in an organization. + navigationGroup: administration + sections: + - type: endpoint + key: list-users + path: list + - type: endpoint + key: modify-user + path: modify + - type: endpoint + key: retrieve-user + path: retrieve + - type: endpoint + key: delete-user + path: delete + - type: object + key: User + path: object + - id: projects + title: Projects + description: > + Manage the projects within an orgnanization includes creation, updating, + and archiving or projects. + + The Default project cannot be archived. + navigationGroup: administration + sections: + - type: endpoint + key: list-projects + path: list + - type: endpoint + key: create-project + path: create + - type: endpoint + key: retrieve-project + path: retrieve + - type: endpoint + key: modify-project + path: modify + - type: endpoint + key: archive-project + path: archive + - type: object + key: Project + path: object + - id: project-users + title: Project users + description: > + Manage users within a project, including adding, updating roles, and + removing users. + navigationGroup: administration + sections: + - type: endpoint + key: list-project-users + path: list + - type: endpoint + key: create-project-user + path: creeate + - type: endpoint + key: retrieve-project-user + path: retrieve + - type: endpoint + key: modify-project-user + path: modify + - type: endpoint + key: delete-project-user + path: delete + - type: object + key: ProjectUser + path: object + - id: project-service-accounts + title: Project service accounts + description: > + Manage service accounts within a project. A service account is a bot + user that is not associated with a user. + + If a user leaves an organization, their keys and membership in projects + will no longer work. Service accounts + + do not have this limitation. However, service accounts can also be + deleted from a project. + navigationGroup: administration + sections: + - type: endpoint + key: list-project-service-accounts + path: list + - type: endpoint + key: create-project-service-account + path: create + - type: endpoint + key: retrieve-project-service-account + path: retrieve + - type: endpoint + key: delete-project-service-account + path: delete + - type: object + key: ProjectServiceAccount + path: object + - id: project-api-keys + title: Project API keys + description: > + Manage API keys for a given project. Supports listing and deleting keys + for users. + + This API does not allow issuing keys for users, as users need to + authorize themselves to generate keys. + navigationGroup: administration + sections: + - type: endpoint + key: list-project-api-keys + path: list + - type: endpoint + key: retrieve-project-api-key + path: retrieve + - type: endpoint + key: delete-project-api-key + path: delete + - type: object + key: ProjectApiKey + path: object + - id: project-rate-limits + title: Project rate limits + description: > + Manage rate limits per model for projects. Rate limits may be configured + to be equal to or lower than the organization's rate limits. + navigationGroup: administration + sections: + - type: endpoint + key: list-project-rate-limits + path: list + - type: endpoint + key: update-project-rate-limits + path: update + - type: object + key: ProjectRateLimit + path: object + - id: audit-logs + title: Audit logs + description: > + Logs of user actions and configuration changes within this organization. + + To log events, you must activate logging in the [Organization + Settings](/settings/organization/general). + + Once activated, for security reasons, logging cannot be deactivated. + navigationGroup: administration + sections: + - type: endpoint + key: list-audit-logs + path: list + - type: object + key: AuditLog + path: object + - id: usage + title: Usage + description: > + The **Usage API** provides detailed insights into your activity across + the OpenAI API. It also includes a separate [Costs + endpoint](/docs/api-reference/usage/costs), which offers visibility into + your spend, breaking down consumption by invoice line items and project + IDs. + + + While the Usage API delivers granular usage data, it may not always + reconcile perfectly with the Costs due to minor differences in how usage + and spend are recorded. For financial purposes, we recommend using the + [Costs endpoint](/docs/api-reference/usage/costs) or the [Costs + tab](/settings/organization/usage) in the Usage Dashboard, which will + reconcile back to your billing invoice. + navigationGroup: administration + sections: + - type: endpoint + key: usage-completions + path: completions + - type: object + key: UsageCompletionsResult + path: completions_object + - type: endpoint + key: usage-embeddings + path: embeddings + - type: object + key: UsageEmbeddingsResult + path: embeddings_object + - type: endpoint + key: usage-moderations + path: moderations + - type: object + key: UsageModerationsResult + path: moderations_object + - type: endpoint + key: usage-images + path: images + - type: object + key: UsageImagesResult + path: images_object + - type: endpoint + key: usage-audio-speeches + path: audio_speeches + - type: object + key: UsageAudioSpeechesResult + path: audio_speeches_object + - type: endpoint + key: usage-audio-transcriptions + path: audio_transcriptions + - type: object + key: UsageAudioTranscriptionsResult + path: audio_transcriptions_object + - type: endpoint + key: usage-vector-stores + path: vector_stores + - type: object + key: UsageVectorStoresResult + path: vector_stores_object + - type: endpoint + key: usage-code-interpreter-sessions + path: code_interpreter_sessions + - type: object + key: UsageCodeInterpreterSessionsResult + path: code_interpreter_sessions_object + - type: endpoint + key: usage-costs + path: costs + - type: object + key: CostsResult + path: costs_object + - id: certificates + beta: true + title: Certificates + description: | + Manage Mutual TLS certificates across your organization and projects. + + [Learn more about Mutual TLS.](https://help.openai.com/en/articles/10876024-openai-mutual-tls-beta-program) + navigationGroup: administration + sections: + - type: endpoint + key: uploadCertificate + path: uploadCertificate + - type: endpoint + key: getCertificate + path: getCertificate + - type: endpoint + key: modifyCertificate + path: modifyCertificate + - type: endpoint + key: deleteCertificate + path: deleteCertificate + - type: endpoint + key: listOrganizationCertificates + path: listOrganizationCertificates + - type: endpoint + key: listProjectCertificates + path: listProjectCertificates + - type: endpoint + key: activateOrganizationCertificates + path: activateOrganizationCertificates + - type: endpoint + key: deactivateOrganizationCertificates + path: deactivateOrganizationCertificates + - type: endpoint + key: activateProjectCertificates + path: activateProjectCertificates + - type: endpoint + key: deactivateProjectCertificates + path: deactivateProjectCertificates + - type: object + key: Certificate + path: object + - id: completions + title: Completions + legacy: true + navigationGroup: legacy + description: > + Given a prompt, the model will return one or more predicted completions + along with the probabilities of alternative tokens at each position. + Most developer should use our [Chat Completions + API](/docs/guides/text-generation#text-generation-models) to leverage + our best and newest models. + sections: + - type: endpoint + key: createCompletion + path: create + - type: object + key: CreateCompletionResponse + path: object \ No newline at end of file