# OpenAI on boxd

> Toolkit for OpenAI APIs: manage Assistants, Threads/Messages; upload/list/delete Files; list/retrieve Models (including vision/multimodal); and view fine-tune listings and events.

- Page: https://boxd.sh/integrations/openai/
- CLI: `run openai` (126 commands, 67 marked common)
- SDK: `import { openai } from "@boxd/run"`; every parameter and response type is at `@boxd/run/openai`
- Triggers: none
- Connect: `run auth openai` (API key), or https://app.boxd.sh/integrations/detail/openai
- All integrations: https://boxd.sh/integrations/ (Markdown: https://boxd.sh/integrations/index.md)

## From the shell

```sh
run auth openai      # once: prints a link to connect your account
run openai           # list its commands
run openai list-evals
```

Parameters are flags (`--flag value`); object and array parameters take a JSON string. Output is YAML, or JSON with `--json`. Calls use your own connection; `--scope <name>` uses a connection shared with your team.

## From a script

```ts
import { every, openai } from "@boxd/run";

every("1 hour", async () => {
  const result = await openai.listEvals({});
  console.log(result);
});
```

Run it with `run openai.run.ts`. OpenAI has no triggers; `every()` polls on a schedule, keeps the script running as a job, and wakes the machine when it is due.

## Commands

Required flags are listed; `run openai <command> --help` lists the optional ones. "common" marks what `run openai` shows without `--all`.

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `add-upload-part` | `openai.addUploadPart()` | `--upload-id` | 4 | Add a part (chunk of bytes) to an Upload object |
| `cancel-batch` ·common | `openai.cancelBatch()` | `--batch-id` | 0 | Cancel an in-progress batch |
| `cancel-eval-run` ·common | `openai.cancelEvalRun()` | `--eval-id` `--run-id` | 0 | Cancel an ongoing evaluation run |
| `cancel-response` | `openai.cancelResponse()` | `--response-id` | 0 | Cancel a background model response by its ID |
| `cancel-run` ·common | `openai.cancelRun()` | `--run-id` `--thread-id` | 0 | Cancel a run that is currently in progress |
| `cancel-upload` | `openai.cancelUpload()` | `--upload-id` | 0 | Cancel an upload |
| `compact-response` | `openai.compactResponse()` | `--model` | 3 | Compact a conversation or response to reduce token usage |
| `create-audio-transcription` ·common | `openai.createAudioTranscription()` | `--model` | 9 | Transcribe audio files to text via OpenAI Audio Transcriptions API |
| `create-audio-translation` | `openai.createAudioTranslation()` | `--model` | 7 | Translate audio files to English text via OpenAI Audio Translations API |
| `create-batch` ·common | `openai.createBatch()` | `--completion-window` `--endpoint` `--input-file-id` | 2 | Create and execute a batch from an uploaded file of requests |
| `create-chat-completion` ·common | `openai.createChatCompletion()` | `--messages` `--model` | 28 | Create a chat completion response from OpenAI models |
| `create-completion` | `openai.createCompletion()` | `--model` `--prompt` | 16 | Generate text completions using OpenAI's legacy Completions API |
| `create-container` ·common | `openai.createContainer()` | `--name` | 5 | Create a new container with configurable memory, expiration, file access, and network policies |
| `create-container-file` | `openai.createContainerFile()` | `--container-id` | 2 | Create a file in a container |
| `create-conversation` ·common | `openai.createConversation()` | — | 2 | Create a new conversation for multi-turn interactions |
| `create-conversation-items` ·common | `openai.createConversationItems()` | `--conversation-id` `--items` | 1 | Create items in a conversation with the given ID |
| `create-embeddings` ·common | `openai.createEmbeddings()` | `--input` `--model` | 3 | Generate text embeddings via the OpenAI embeddings endpoint |
| `create-eval` ·common | `openai.createEval()` | `--data-source-config` `--name` `--testing-criteria` | 1 | Create an evaluation structure for testing a model's performance |
| `create-eval-run` ·common | `openai.createEvalRun()` | `--data-source` `--eval-id` | 2 | Create a new evaluation run for testing model configurations |
| `create-fine-tuning-job` ·common | `openai.createFineTuningJob()` | `--model` `--training-file` | 7 | Create a fine-tuning job which begins the process of creating a new model from a given dataset |
| `create-image` ·common | `openai.createImage()` | `--model` `--prompt` | 9 | Generate an image via the OpenAI Images API and return hosted image asset URL and metadata |
| `create-image-edit` ·common | `openai.createImageEdit()` | `--images` `--prompt` | 11 | Create edited or extended images via OpenAI Images Edit API |
| `create-image-variation` ·common | `openai.createImageVariation()` | `--image` | 5 | Create a variation of a given image using the OpenAI Images API |
| `create-message` ·common | `openai.createMessage()` | `--content` `--role` `--thread-id` | 2 | Create a new message in a specific thread |
| `create-moderation` ·common | `openai.createModeration()` | `--input` | 1 | Classify text and/or image inputs for potentially harmful content via the OpenAI Moderation API |
| `create-realtime-call` | `openai.createRealtimeCall()` | `--model` `--sdp` | 0 | Create a Realtime API call over WebRTC and receive the SDP answer needed to complete the peer connection |
| `create-realtime-client-secret` ·common | `openai.createRealtimeClientSecret()` | — | 2 | Create an ephemeral client secret for authenticating Realtime API connections |
| `create-realtime-session` ·common | `openai.createRealtimeSession()` | `--model` | 15 | Create an ephemeral API token for client-side Realtime API applications |
| `create-realtime-transcription-session` ·common | `openai.createRealtimeTranscriptionSession()` | — | 5 | Create an ephemeral API token for realtime transcriptions via the Realtime API |
| `create-response` ·common | `openai.createResponse()` | `--input` `--model` | 13 | Generate a one-shot model response via the Responses API |
| `create-run` ·common | `openai.createRun()` | `--assistant-id` `--thread-id` | 16 | Create a run on a thread with an assistant |
| `create-skill` ·common | `openai.createSkill()` | `--files` | 0 | Create a skill from uploaded files |
| `create-speech` ·common | `openai.createSpeech()` | `--input` `--model` `--voice` | 2 | Generate text-to-speech audio using OpenAI's Audio API |
| `create-thread` ·common | `openai.createThread()` | — | 2 | Create a new thread |
| `create-thread-and-run` ·common | `openai.createThreadAndRun()` | `--assistant-id` | 15 | Create a thread and run it in one request |
| `create-upload` ·common | `openai.createUpload()` | `--bytes` `--filename` `--mime-type` `--purpose` | 1 | Create an intermediate Upload object for large file uploads |
| `create-vector-store` ·common | `openai.createVectorStore()` | — | 5 | Create a new vector store |
| `create-vector-store-file` ·common | `openai.createVectorStoreFile()` | `--file-id` `--vector-store-id` | 1 | Create a vector store file by attaching a File to a vector store |
| `create-vector-store-file-batch` | `openai.createVectorStoreFileBatch()` | `--vector-store-id` | 4 | Create a vector store file batch |
| `create-video` ·common | `openai.createVideo()` | `--prompt` | 3 | Create a video using Sora models via the OpenAI Videos API |
| `create-video-remix` ·common | `openai.createVideoRemix()` | `--prompt` `--video-id` | 0 | Create a video remix from an existing generated video using OpenAI's Video API |
| `delete-assistant` ·common | `openai.deleteAssistant()` | `--assistant-id` | 0 | Delete a specific assistant by its ID |
| `delete-chat-completion` | `openai.deleteChatCompletion()` | `--completion-id` | 0 | Delete a stored chat completion by its ID |
| `delete-container` | `openai.deleteContainer()` | `--container-id` | 0 | Delete a specific container by its ID |
| `delete-container-file` | `openai.deleteContainerFile()` | `--container-id` `--file-id` | 0 | Delete a file from a container |
| `delete-conversation` ·common | `openai.deleteConversation()` | `--conversation-id` | 0 | Delete a conversation by its ID |
| `delete-conversation-item` | `openai.deleteConversationItem()` | `--conversation-id` `--item-id` | 0 | Delete an item from a conversation with the given IDs |
| `delete-eval` | `openai.deleteEval()` | `--eval-id` | 0 | Delete a specific evaluation by its ID |
| `delete-eval-run` | `openai.deleteEvalRun()` | `--eval-id` `--run-id` | 0 | Delete an evaluation run |
| `delete-file` ·common | `openai.deleteFile()` | `--file-id` | 0 | Delete a file by its ID after confirming the target |
| `delete-message` | `openai.deleteMessage()` | `--message-id` `--thread-id` | 0 | Delete a message from a thread |
| `delete-response` | `openai.deleteResponse()` | `--response-id` | 0 | Delete a model response with the given ID |
| `delete-skill` | `openai.deleteSkill()` | `--skill-id` | 0 | Delete a specific skill by its ID |
| `delete-thread` ·common | `openai.deleteThread()` | `--thread-id` | 0 | Delete a thread by its ID |
| `delete-vector-store` ·common | `openai.deleteVectorStore()` | `--vector-store-id` | 0 | Delete a vector store |
| `delete-vector-store-file` | `openai.deleteVectorStoreFile()` | `--file-id` `--vector-store-id` | 0 | Delete a vector store file |
| `delete-video` ·common | `openai.deleteVideo()` | `--video-id` | 0 | Delete a video by its ID |
| `download-file` | `openai.downloadFile()` | `--file-id` | 0 | Download the contents of a specified file by its ID |
| `download-video` | `openai.downloadVideo()` | `--video-id` | 1 | Download video content (MP4) or preview assets from OpenAI Videos API |
| `get-chat-completion` ·common | `openai.getChatCompletion()` | `--completion-id` | 0 | Retrieve a stored chat completion |
| `get-chat-completion-messages` | `openai.getChatCompletionMessages()` | `--completion-id` | 3 | Retrieve messages from a stored chat completion |
| `get-chatkit-thread` | `openai.getChatkitThread()` | `--thread-id` | 0 | Retrieve a ChatKit thread by its ID |
| `get-conversation-item` | `openai.getConversationItem()` | `--conversation-id` `--item-id` | 1 | Retrieve a single item from a conversation |
| `get-eval` | `openai.getEval()` | `--eval-id` | 0 | Retrieve an evaluation by ID |
| `get-eval-run` | `openai.getEvalRun()` | `--eval-id` `--run-id` | 0 | Retrieve an evaluation run by ID to check status and results |
| `get-eval-run-output-item` | `openai.getEvalRunOutputItem()` | `--eval-id` `--output-item-id` `--run-id` | 0 | Retrieve a specific output item from an evaluation run by its ID |
| `get-eval-run-output-items` ·common | `openai.getEvalRunOutputItems()` | `--eval-id` `--run-id` | 4 | Get a list of output items for an evaluation run |
| `get-eval-runs` | `openai.getEvalRuns()` | `--eval-id` | 4 | Get a paginated list of runs for an evaluation |
| `get-input-token-counts` ·common | `openai.getInputTokenCounts()` | — | 11 | Calculate input token counts for OpenAI API requests |
| `get-message` ·common | `openai.getMessage()` | `--message-id` `--thread-id` | 0 | Retrieve a specific message from a thread by its ID |
| `get-response` | `openai.getResponse()` | `--response-id` | 4 | Retrieve a model response by ID |
| `get-run-step` | `openai.getRunStep()` | `--run-id` `--step-id` `--thread-id` | 1 | Retrieve a specific run step from an Assistants API run to inspect detailed execution progress, view tool calls, or check message creation |
| `get-vector-store` ·common | `openai.getVectorStore()` | `--vector-store-id` | 0 | Retrieve a vector store by its ID |
| `get-vector-store-file` ·common | `openai.getVectorStoreFile()` | `--file-id` `--vector-store-id` | 0 | Retrieve a file from a vector store |
| `get-vector-store-file-batch` | `openai.getVectorStoreFileBatch()` | `--batch-id` `--vector-store-id` | 0 | Retrieve a vector store file batch |
| `get-video` | `openai.getVideo()` | `--video-id` | 0 | Retrieve a video generation job by its unique identifier |
| `list-assistants` ·common | `openai.listAssistants()` | — | 4 | List assistants to discover the correct assistant_id by name or metadata |
| `list-batches` ·common | `openai.listBatches()` | — | 2 | List your organization's batches |
| `list-chat-completions` | `openai.listChatCompletions()` | — | 5 | List stored chat completions that were created with the `store` parameter set to true |
| `list-chatkit-thread-items` | `openai.listChatkitThreadItems()` | `--thread-id` | 4 | List ChatKit thread items |
| `list-container-files` | `openai.listContainerFiles()` | `--container-id` | 3 | List files in a container |
| `list-containers` | `openai.listContainers()` | — | 4 | List containers |
| `list-conversation-items` | `openai.listConversationItems()` | `--conversation-id` | 4 | List all items for a conversation with the given ID |
| `list-engines` | `openai.listEngines()` | — | 0 | List available engines and their basic information |
| `list-evals` ·common | `openai.listEvals()` | — | 4 | List evaluations for a project |
| `list-files` ·common | `openai.listFiles()` | — | 3 | Retrieve a list of files uploaded to your organization/project context |
| `list-files-in-vector-store-batch` | `openai.listFilesInVectorStoreBatch()` | `--batch-id` `--vector-store-id` | 5 | List vector store files in a batch |
| `list-fine-tunes` ·common | `openai.listFineTunes()` | — | 2 | List your organization's fine-tuning jobs |
| `list-fine-tuning-events` | `openai.listFineTuningEvents()` | `--fine-tuning-job-id` | 2 | Get status updates for a fine-tuning job |
| `list-fine-tuning-job-checkpoints` | `openai.listFineTuningJobCheckpoints()` | `--fine-tuning-job-id` | 2 | List checkpoints for a fine-tuning job |
| `list-input-items` | `openai.listInputItems()` | `--response-id` | 4 | Retrieve input items for a given response from the OpenAI Responses API |
| `list-messages` ·common | `openai.listMessages()` | `--thread-id` | 5 | List messages in an Assistants thread to fetch the assistant's generated outputs after a run completes |
| `list-models` ·common | `openai.listModels()` | — | 0 | List available models scoped to the current account/organization, some public models may be absent due to permissions |
| `list-run-steps` ·common | `openai.listRunSteps()` | `--run-id` `--thread-id` | 5 | List run steps for an Assistants API run to track detailed execution progress, inspect tool calls, and view message creation events |
| `list-runs` | `openai.listRuns()` | `--thread-id` | 4 | List runs belonging to a thread |
| `list-skills` | `openai.listSkills()` | — | 3 | List skills |
| `list-threads` | `openai.listThreads()` | — | 5 | List ChatKit threads with pagination and filtering |
| `list-vector-store-files` ·common | `openai.listVectorStoreFiles()` | `--vector-store-id` | 5 | List files in a vector store |
| `list-vector-stores` | `openai.listVectorStores()` | — | 4 | List vector stores to discover available vector stores by name or metadata |
| `list-videos` | `openai.listVideos()` | — | 3 | List all video generation jobs |
| `modify-assistant` ·common | `openai.modifyAssistant()` | `--assistant-id` | 10 | Modify an existing assistant |
| `modify-message` | `openai.modifyMessage()` | `--message-id` `--thread-id` | 1 | Modify an existing message's metadata in a thread |
| `modify-run` ·common | `openai.modifyRun()` | `--run-id` `--thread-id` | 1 | Modify a run's metadata |
| `modify-thread` ·common | `openai.modifyThread()` | `--thread-id` | 1 | Modify an existing thread's metadata |
| `modify-vector-store` | `openai.modifyVectorStore()` | `--vector-store-id` | 3 | Modify an existing vector store |
| `retrieve-assistant` ·common | `openai.retrieveAssistant()` | `--assistant-id` | 0 | Retrieve details of a specific assistant |
| `retrieve-batch` ·common | `openai.retrieveBatch()` | `--batch-id` | 0 | Retrieve a batch by ID to check its status, progress, and results |
| `retrieve-container` ·common | `openai.retrieveContainer()` | `--container-id` | 0 | Retrieve details of a specific container by its ID |
| `retrieve-container-file` | `openai.retrieveContainerFile()` | `--container-id` `--file-id` | 0 | Retrieve metadata for a specific file in a container |
| `retrieve-container-file-content` | `openai.retrieveContainerFileContent()` | `--container-id` `--file-id` | 0 | Retrieve the content of a file within a container |
| `retrieve-engine` | `openai.retrieveEngine()` | `--engine-id` | 0 | Retrieve details of a specific engine |
| `retrieve-file` ·common | `openai.retrieveFile()` | `--file-id` | 0 | Retrieve information about a specific file |
| `retrieve-fine-tuning-job` ·common | `openai.retrieveFineTuningJob()` | `--fine-tuning-job-id` | 0 | Retrieve information about a fine-tuning job |
| `retrieve-model` ·common | `openai.retrieveModel()` | `--model` | 0 | Retrieve details of a specific model, confirming its metadata (ownership, created date) and verifying access under your org, a model appearing in list-models does not guarantee access |
| `retrieve-run` ·common | `openai.retrieveRun()` | `--run-id` `--thread-id` | 0 | Retrieve an Assistants run by ID to check status, errors, and usage |
| `retrieve-thread` ·common | `openai.retrieveThread()` | `--thread-id` | 0 | Retrieve metadata of a specific thread by its ID, does not include message bodies or assistant replies (those require a completed run and separate message listing) |
| `retrieve-vector-store-file-content` | `openai.retrieveVectorStoreFileContent()` | `--file-id` `--vector-store-id` | 0 | Retrieve the parsed contents of a vector store file |
| `run-grader` | `openai.runGrader()` | `--grader` `--model-sample` | 1 | Run a grader to evaluate model performance on a given sample |
| `search-vector-store` ·common | `openai.searchVectorStore()` | `--query` `--vector-store-id` | 4 | Search a vector store for relevant chunks based on a query and file attributes filter |
| `submit-tool-outputs-to-run` ·common | `openai.submitToolOutputsToRun()` | `--run-id` `--thread-id` `--tool-outputs` | 1 | Submit tool call outputs to continue a run that requires action |
| `update-chat-completion` | `openai.updateChatCompletion()` | `--completion-id` | 1 | Update metadata for a stored chat completion |
| `update-conversation` | `openai.updateConversation()` | `--conversation-id` | 1 | Update a conversation's metadata |
| `update-eval` | `openai.updateEval()` | `--eval-id` | 2 | Update certain properties of an evaluation (name and metadata) |
| `update-vector-store-file-attributes` | `openai.updateVectorStoreFileAttributes()` | `--file-id` `--vector-store-id` | 1 | Update custom attributes on a vector store file |
| `upload-file` ·common | `openai.uploadFile()` | `--file` `--purpose` | 0 | Upload a file for use across OpenAI endpoints |
| `validate-grader` | `openai.validateGrader()` | `--grader` | 0 | Validate a grader configuration for fine-tuning jobs |

## Docs

- [run CLI](https://docs.boxd.sh/cli/run): Call connected integrations from the shell, connect new ones, and run automations.
- [Quickstart](https://docs.boxd.sh/guides/integrations/quickstart): Connect an integration, call it from the shell, and turn a script into an automation.
- [Connections](https://docs.boxd.sh/guides/integrations/connections): Connect an account once, for yourself or for your whole organization.
- [Scripts](https://docs.boxd.sh/guides/automations/scripts): Typed integrations, triggers, schedules and state in a .run.ts file.
- [Jobs](https://docs.boxd.sh/guides/automations/jobs): How a script becomes a background job: states, retries, sleep and wake.
- [Beyond the catalog](https://docs.boxd.sh/guides/automations/beyond-the-catalog): Reach your own APIs, databases and cloud accounts from a script.