# OpenAI OpenAI models. Generate text and images, compute embeddings, moderate content, and manage files, fine-tuning, and vector stores. | Property | Value | | --- | --- | | Slug | `openai` | | Definition version | `0.1.0` | | Base URL | `https://api.openai.com/v1` | | Auth schemes | `api_key` | | Action tools | 32 | | By class | 13 read, 13 write, 6 destructive | | Triggers | 0 | | Provider rate limit | not declared, so outbound calls are unpaced | ## Measured routing accuracy 54 golden cases replayed through the router over the whole index: measured over corpus `ea4f12ad2948` (65 toolkits, 2283 tools indexed and 13 declared uncallable), 27 cases written by hand and 27 cases from the paraphrase pass. A case counts as top-1 when its gold tool ranked first and top-8 when it reached the slate at all. | Measure | Cases | Share | | --- | --- | --- | | top-1 | 35/54 | 64.8% | | top-8 | 45/54 | 83.3% | 5 of the 32 action tools listed above are declared uncallable, so they are indexed nowhere and answer none of these cases. The counts here are scored over the other 27. The sweep is offline: the reranker is a deterministic identity fake that returns candidates in the order retrieval produced them, so top-1 measures retrieval order rather than a reranked slate. `just eval-live` measures the same cases through the live reranker. ## Authentication Connect an entity with `ConnectionsService.InitiateConnection`, naming this toolkit's slug. Credentials stay in the connections vault; callers hold connected-account ids only. ### `api_key` | Property | Value | | --- | --- | | Placement | `header` | | Name | `Authorization` | | Rendered as | `Bearer {key}` | Submit the key with `ConnectionsService` rather than putting it in a request; it is sealed at rest and never returned. ## Tools 32 action tools. The catalog-wide slug is `openai.`, which is what `search_tools` returns and `call_tool` takes. ### `openai.create_chat_completion` Generate a chat completion from an OpenAI GPT model (gpt-4o, gpt-4, gpt-3.5-turbo, or another chat model by name). Use when the user wants an AI-written reply, summary, draft, or answer produced from a prompt or conversation, rather than a saved template. Takes a system prompt plus message history; no function/tool calling in this schema. Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /chat/completions`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `max_tokens` | integer | no | Upper bound on tokens generated in the reply. | | `messages` | array of object | **yes** | Conversation so far, oldest first. | | `messages[].content` | string | **yes** | Message text. | | `messages[].role` | string, one of system, user, assistant | **yes** | Who this message is from. | | `model` | string | **yes** | Model name, e.g. "gpt-4o" or "gpt-4o-mini". | | `response_format` | string, one of text, json_object | no | Set json_object to force the reply to be a single valid JSON object. | | `stop` | array of string | no | Up to 4 strings; generation stops if one is produced. | | `temperature` | number | no | Sampling randomness, 0 to 2. Lower is more deterministic. Omit for the model default. | | `top_p` | number | no | Nucleus sampling threshold, 0 to 1. Use instead of temperature, not alongside it. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `choices` | array of object | | | `choices[].finish_reason` | string | | | `choices[].index` | integer | | | `choices[].message` | object | | | `choices[].message.content` | string | | | `choices[].message.role` | string | | | `id` | string | | | `model` | string | | | `usage` | object | | | `usage.completion_tokens` | integer | | | `usage.prompt_tokens` | integer | | | `usage.total_tokens` | integer | | Also retrieved by: "ask gpt to write a reply for this", "have the model draft an answer to this question", "get an ai-written summary of this text", "run this prompt through gpt-4o and see what comes back", "generate a response from the language model for this conversation". ### `openai.create_image` Generate a brand-new image from a text prompt with an OpenAI image model (gpt-image-1 or dall-e-3). Use when the user wants original artwork or a picture created purely from a description. To modify an existing image instead of creating a new one, this toolkit cannot help (edit_image and create_image_variation are not callable here). Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /images/generations`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `model` | string | no | Image model name, e.g. "gpt-image-1" or "dall-e-3". Omit for the account default. | | `n` | integer | no | Number of images to generate. dall-e-3 supports only 1. | | `prompt` | string | **yes** | Text description of the desired image. | | `quality` | string | no | Rendering quality, e.g. "standard" or "hd" for dall-e-3. | | `size` | string | no | Output dimensions, e.g. "1024x1024", "1792x1024", "1024x1792". Valid values depend on the model. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `created` | integer | | | `data` | array of object | | | `data[].b64_json` | string | | | `data[].revised_prompt` | string | | | `data[].url` | string | | Also retrieved by: "make a picture of a robot riding a bicycle", "draw something from this description", "generate artwork of a sunset over mountains", "turn this idea into a piece of ai artwork", "render an original picture of a cat wearing a hat". ### `openai.create_embedding` Compute an OpenAI text embedding vector for one or more strings, turning text into numbers for search or similarity comparison. Use when the user wants to embed, vectorize, or compare text semantically, not when they want the model to write a reply. Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /embeddings`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `dimensions` | integer | no | Shorten the output vector to this many dimensions, if the model supports it. | | `input` | array of string | **yes** | Strings to embed, one vector per string. | | `model` | string | **yes** | Embedding model name, e.g. "text-embedding-3-small" or "text-embedding-3-large". | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `data` | array of object | | | `data[].embedding` | array of number | | | `data[].index` | integer | | | `model` | string | | | `usage` | object | | | `usage.prompt_tokens` | integer | | | `usage.total_tokens` | integer | | Also retrieved by: "turn this sentence into a vector for search", "compute a numeric representation of this text", "get the vector for this string so i can compare it to others", "vectorize this paragraph for semantic search". ### `openai.create_moderation` Check whether text is flagged as unsafe by OpenAI's moderation model, across categories like hate, harassment, self-harm, sexual content, and violence. Use before showing user-submitted or model-generated text to others, or before sending it on to another tool. Read-only: it classifies text and creates nothing on the account. Class `read` (reads only). No scopes beyond the connection's defaults. Calls `POST /moderations`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `input` | array of string | **yes** | Strings to check. | | `model` | string | no | Moderation model name, e.g. "omni-moderation-latest". Omit for the account default. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `id` | string | | | `model` | string | | | `results` | array of object | | | `results[].categories` | object | | | `results[].categories.harassment` | boolean | | | `results[].categories.hate` | boolean | | | `results[].categories.self_harm` | boolean | | | `results[].categories.sexual` | boolean | | | `results[].categories.violence` | boolean | | | `results[].flagged` | boolean | | Also retrieved by: "check whether this text is safe to show people", "is this message flagged for anything", "scan this for hate speech or harassment before I post it", "run a safety check on this user submission", "flag anything unsafe in what the model just wrote". ### `openai.create_transcription` Transcribe an audio file to text with an OpenAI speech-to-text model (Whisper). Use when the user wants a written transcript of an audio recording in its original language. Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /audio/transcriptions`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `file` | string | **yes** | Audio file bytes to transcribe. | | `language` | string | no | ISO-639-1 language code of the audio, e.g. "en". | | `model` | string | **yes** | Transcription model name, e.g. "whisper-1". | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `text` | string | | Also retrieved by: "turn this recording into written words", "what did they say in this voice memo", "give me a text version of this podcast clip". ### `openai.create_translation` Translate an audio file directly into English text with an OpenAI speech-to-text model (Whisper). Use when the user has audio in another language and wants an English transcript, not a transcript in the original language. Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /audio/translations`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `file` | string | **yes** | Audio file bytes to translate. | | `model` | string | **yes** | Translation model name, e.g. "whisper-1". | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `text` | string | | Also retrieved by: "turn this foreign-language recording into an english transcript", "what is being said in this clip, in english", "give me an english write-up of this spanish voicemail". ### `openai.edit_image` Edit or inpaint part of an existing image from a text prompt and an optional mask, with an OpenAI image model. Use when the user wants to change one area of a picture they already have rather than generate a new one from scratch. Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /images/edits`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `image` | string | **yes** | Source image file bytes. | | `mask` | string | no | Optional mask file bytes marking the area to edit. | | `prompt` | string | **yes** | Text description of the desired edit. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `data` | array of object | | | `data[].url` | string | | Also retrieved by: "paint over just this part of the picture", "swap out the background in this photo using a mask", "change one area of this picture, keep the rest the same". ### `openai.create_image_variation` Generate variations on an existing image without a text prompt, with an OpenAI image model. Use when the user wants a few alternate takes on a picture they already have, rather than a specific edit or a brand-new image. Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /images/variations`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `image` | string | **yes** | Source image file bytes. | | `n` | integer | no | Number of variations to generate. | | `size` | string | no | Output dimensions, e.g. "1024x1024". | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `data` | array of object | | | `data[].url` | string | | Also retrieved by: "give me a few different takes on this picture", "remix this image into some alternates", "show me some fresh spins on this existing artwork". ### `openai.list_models` List every OpenAI model available to the account, base models and the account's own fine-tuned models alike. Use when the user asks what models they can use or wants a fine-tuned model's exact id. Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /models`. Takes no arguments. Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `data` | array of object | | | `data[].created` | integer | | | `data[].id` | string | | | `data[].owned_by` | string | | Also retrieved by: "what language models can I use here", "show me every model available on this account", "what's the exact id of my custom trained model". ### `openai.retrieve_model` Get one OpenAI model's details by id, base or fine-tuned. Use when the user already has a model id and wants to confirm it exists or see who owns it, rather than browsing the full list. Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /models/{{params.model}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `model` | string | **yes** | Model id to look up. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `created` | integer | | | `id` | string | | | `owned_by` | string | | Also retrieved by: "look up the details for this specific model id", "confirm this model still exists and who owns it", "check the info on one particular model". ### `openai.delete_fine_tuned_model` Permanently delete one of the account's own OpenAI fine-tuned models by id. Use when the user wants to remove a fine-tuned model they trained. Only fine-tuned models can be deleted this way; base models cannot. Irreversible. Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). No scopes beyond the connection's defaults. Calls `DELETE /models/{{params.model}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `model` | string | **yes** | Fine-tuned model id to delete. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `deleted` | boolean | | | `id` | string | | Also retrieved by: "get rid of this custom trained model for good", "remove the fine-tuned model I no longer need", "wipe out that custom model from the account". ### `openai.upload_file` Upload a file to OpenAI's storage for use as fine-tuning training data, a batch job's input, or a vector store document. Use when the user wants to add a new file to the account rather than reference one that's already there. Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /files`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `file` | string | **yes** | File bytes to upload. | | `purpose` | string, one of fine-tune, batch, assistants, vision | **yes** | What the file will be used for. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `bytes` | integer | | | `filename` | string | | | `id` | string | | | `purpose` | string | | Also retrieved by: "add this document to the account's storage", "get this dataset uploaded so I can use it later", "push this file up for training or search". ### `openai.list_files` List files uploaded to the OpenAI account, optionally filtered by purpose (fine-tune, batch, vision). Use when the user asks what files they've uploaded or wants a file's id before referencing it in another call. Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /files`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `purpose` | string | no | Filter to files uploaded for this purpose, e.g. "fine-tune". | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `data` | array of object | | | `data[].bytes` | integer | | | `data[].created_at` | integer | | | `data[].filename` | string | | | `data[].id` | string | | | `data[].purpose` | string | | Also retrieved by: "what files have I uploaded so far", "show me everything sitting in storage right now", "find the id for that dataset I uploaded earlier". ### `openai.retrieve_file` Get one uploaded OpenAI file's metadata by id: name, size, purpose, and upload time. Use when the user already has a file id and wants its details, not the file's actual content or bytes. Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /files/{{params.file_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `file_id` | string | **yes** | File to look up. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `bytes` | integer | | | `created_at` | integer | | | `filename` | string | | | `id` | string | | | `purpose` | string | | Also retrieved by: "pull up the details on this uploaded document", "check the size and purpose of this stored file", "look up metadata for one item in storage". ### `openai.delete_file` Permanently delete an uploaded OpenAI file by id. Use when the user wants to remove a file from the account's storage. A file already in use by a fine-tuning job, batch, or vector store may still be referenced there after deletion fails or succeeds depending on OpenAI's own state; check first if that matters. Irreversible. Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). No scopes beyond the connection's defaults. Calls `DELETE /files/{{params.file_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `file_id` | string | **yes** | File to delete. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `deleted` | boolean | | | `id` | string | | Also retrieved by: "remove this document from storage for good", "clear out that old dataset I don't need anymore", "get rid of this uploaded file". ### `openai.create_fine_tuning_job` Start an OpenAI fine-tuning job that trains a custom model from an already-uploaded training file. Use when the user wants to fine-tune or customize a base model on their own data. The training file must already exist in OpenAI's storage (see list_files); this toolkit cannot upload one directly. Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /fine_tuning/jobs`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `model` | string | **yes** | Base model to fine-tune, e.g. "gpt-4o-mini-2024-07-18". | | `suffix` | string | no | Optional label appended to the resulting model's name. | | `training_file` | string | **yes** | File id of the uploaded training data. | | `validation_file` | string | no | Optional file id of held-out validation data. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `created_at` | integer | | | `fine_tuned_model` | string | | | `id` | string | | | `model` | string | | | `status` | string | | Also retrieved by: "kick off a custom training run on my dataset", "start fine-tuning a model with the data I uploaded", "train a custom version of a base model". ### `openai.list_fine_tuning_jobs` List the OpenAI fine-tuning jobs run on the account, newest first. Use when the user asks what fine-tunes they've kicked off or wants a job's id before checking on it or cancelling it. Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /fine_tuning/jobs`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `limit` | integer | no | Maximum jobs to return. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `data` | array of object | | | `data[].created_at` | integer | | | `data[].fine_tuned_model` | string | | | `data[].id` | string | | | `data[].model` | string | | | `data[].status` | string | | Also retrieved by: "what training runs have I started", "show me every custom-training job on this account", "find the id for that fine-tune I kicked off earlier". ### `openai.retrieve_fine_tuning_job` Get one OpenAI fine-tuning job's current status by id: whether it's queued, running, succeeded, or failed, and the resulting model name once it finishes. Use when the user already has a job id and wants to check on a specific fine-tune. Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /fine_tuning/jobs/{{params.fine_tuning_job_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `fine_tuning_job_id` | string | **yes** | Fine-tuning job to look up. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `fine_tuned_model` | string | | | `id` | string | | | `model` | string | | | `status` | string | | | `trained_tokens` | integer | | Also retrieved by: "how's my custom training run coming along", "check on the progress of one specific fine-tune", "has my model finished training yet". ### `openai.cancel_fine_tuning_job` Stop an OpenAI fine-tuning job that hasn't finished yet. Use when the user wants to cancel, kill, or abort a fine-tune that's still queued or running. Irreversible; a job that has already completed or failed cannot be cancelled. Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). No scopes beyond the connection's defaults. Calls `POST /fine_tuning/jobs/{{params.fine_tuning_job_id}}/cancel`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `fine_tuning_job_id` | string | **yes** | Fine-tuning job to cancel. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `id` | string | | | `status` | string | | Also retrieved by: "stop this training run before it finishes", "kill that custom-training job, it's not needed anymore", "abort the fine-tune that's still going". ### `openai.list_fine_tuning_events` List the progress events (metrics, status changes) an OpenAI fine-tuning job has logged, oldest or newest first. Use when the user wants to see how a fine-tune is progressing in detail, beyond just its current status. Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /fine_tuning/jobs/{{params.fine_tuning_job_id}}/events`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `fine_tuning_job_id` | string | **yes** | Fine-tuning job whose events to list. | | `limit` | integer | no | Maximum events to return. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `data` | array of object | | | `data[].created_at` | integer | | | `data[].id` | string | | | `data[].level` | string | | | `data[].message` | string | | Also retrieved by: "show me the play-by-play of this training run", "what's been logged during this custom-training job", "give me the detailed progress log, not just the status". ### `openai.create_batch` Submit an OpenAI batch job: run many chat completion or embedding requests from one already-uploaded JSONL input file, at lower cost and with results delivered within a completion window rather than immediately. Use when the user wants to process a large set of prompts asynchronously instead of one at a time. Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /batches`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `completion_window` | string | **yes** | How long OpenAI has to finish the batch, currently only "24h". | | `endpoint` | string, one of /v1/chat/completions, /v1/embeddings | **yes** | Which API endpoint every request in the batch calls. | | `input_file_id` | string | **yes** | File id of the uploaded JSONL batch input. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `endpoint` | string | | | `id` | string | | | `output_file_id` | string | | | `request_counts` | object | | | `request_counts.completed` | integer | | | `request_counts.failed` | integer | | | `request_counts.total` | integer | | | `status` | string | | Also retrieved by: "run all these prompts overnight instead of one by one", "submit a big pile of requests as a bulk job", "process this large set of inputs asynchronously". ### `openai.retrieve_batch` Get one OpenAI batch job's current status by id: how many of its requests have completed or failed, and the output file id once it's done. Use when the user already has a batch id and wants to check on a specific bulk job. Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /batches/{{params.batch_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `batch_id` | string | **yes** | Batch job to look up. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `error_file_id` | string | | | `id` | string | | | `output_file_id` | string | | | `request_counts` | object | | | `request_counts.completed` | integer | | | `request_counts.failed` | integer | | | `request_counts.total` | integer | | | `status` | string | | Also retrieved by: "how far along is that bulk job I submitted", "check the progress on this large async run", "has the batch I kicked off finished yet". ### `openai.cancel_batch` Stop an OpenAI batch job that hasn't finished yet; in-flight requests are allowed to finish but no new ones start. Use when the user wants to cancel or abort a bulk job that's still in progress. Irreversible; a batch that has already completed cannot be cancelled. Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). No scopes beyond the connection's defaults. Calls `POST /batches/{{params.batch_id}}/cancel`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `batch_id` | string | **yes** | Batch job to cancel. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `id` | string | | | `status` | string | | Also retrieved by: "stop that bulk job before it finishes", "abort the large async run that's still in progress", "kill the batch, we don't need those results anymore". ### `openai.list_batches` List the OpenAI batch jobs run on the account, newest first. Use when the user asks what bulk jobs they've submitted or wants a batch's id before checking on it or cancelling it. Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /batches`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `limit` | integer | no | Maximum batches to return. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `data` | array of object | | | `data[].created_at` | integer | | | `data[].endpoint` | string | | | `data[].id` | string | | | `data[].status` | string | | Also retrieved by: "what bulk jobs have I submitted", "show me every large async run on this account", "find the id for that batch I kicked off earlier". ### `openai.create_vector_store` Create a new OpenAI vector store: a searchable collection of files for retrieval. Use when the user wants to set up a new knowledge base or document collection for semantic search, not add a file to one that already exists. Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /vector_stores`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `file_ids` | array of string | no | File ids to add immediately, already uploaded to OpenAI. | | `name` | string | no | Name for the vector store. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `created_at` | integer | | | `file_counts` | object | | | `file_counts.completed` | integer | | | `file_counts.failed` | integer | | | `file_counts.total` | integer | | | `id` | string | | | `name` | string | | | `status` | string | | Also retrieved by: "set up a new knowledge base for search", "build a searchable collection out of some documents", "start a fresh document index for retrieval". ### `openai.list_vector_stores` List the OpenAI vector stores set up on the account. Use when the user asks what knowledge bases or document collections exist, or wants a vector store's id before adding files to it. Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /vector_stores`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `limit` | integer | no | Maximum vector stores to return. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `data` | array of object | | | `data[].created_at` | integer | | | `data[].id` | string | | | `data[].name` | string | | | `data[].status` | string | | Also retrieved by: "what knowledge bases do I have set up", "show me every document collection on this account", "find the id for the search index I built earlier". ### `openai.retrieve_vector_store` Get one OpenAI vector store's details by id: its name, status, and how many files it holds. Use when the user already has a vector store id and wants its current state, not the full account list. Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /vector_stores/{{params.vector_store_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `vector_store_id` | string | **yes** | Vector store to look up. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `file_counts` | object | | | `file_counts.completed` | integer | | | `file_counts.failed` | integer | | | `file_counts.total` | integer | | | `id` | string | | | `name` | string | | | `status` | string | | | `usage_bytes` | integer | | Also retrieved by: "check how many files are in this knowledge base", "look up the state of one specific document collection", "is this search index still processing". ### `openai.update_vector_store` Rename an OpenAI vector store, or change when it expires. Use when the user wants to relabel a knowledge base or adjust its expiry, not change which files it contains. Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /vector_stores/{{params.vector_store_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `name` | string | no | New name for the vector store. | | `vector_store_id` | string | **yes** | Vector store to update. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `id` | string | | | `name` | string | | Also retrieved by: "rename this knowledge base to something clearer", "change the expiry on this document collection", "relabel this search index". ### `openai.delete_vector_store` Permanently delete an OpenAI vector store by id. Use when the user wants to remove a knowledge base or document collection entirely. Removes the store's index, not the underlying uploaded files themselves. Irreversible. Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). No scopes beyond the connection's defaults. Calls `DELETE /vector_stores/{{params.vector_store_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `vector_store_id` | string | **yes** | Vector store to delete. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `deleted` | boolean | | | `id` | string | | Also retrieved by: "tear down this knowledge base entirely", "remove this document collection for good", "get rid of the whole search index". ### `openai.add_file_to_vector_store` Add an already-uploaded file to an OpenAI vector store, indexing it for retrieval. Use when the user wants to add a document to an existing knowledge base. The file must already exist in OpenAI's storage (see list_files); this toolkit cannot upload one directly. Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /vector_stores/{{params.vector_store_id}}/files`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `file_id` | string | **yes** | File id of the already-uploaded document. | | `vector_store_id` | string | **yes** | Vector store to add the file to. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `id` | string | | | `status` | string | | Also retrieved by: "drop this document into the knowledge base", "index this file so it shows up in search", "add one more document to the collection". ### `openai.list_vector_store_files` List the files indexed in an OpenAI vector store, with each one's processing status. Use when the user asks what documents are in a knowledge base, or wants a file's status before searching against it. Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /vector_stores/{{params.vector_store_id}}/files`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `limit` | integer | no | Maximum files to return. | | `vector_store_id` | string | **yes** | Vector store whose files to list. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `data` | array of object | | | `data[].created_at` | integer | | | `data[].id` | string | | | `data[].status` | string | | Also retrieved by: "what documents are indexed in this knowledge base", "show me every file in this search collection", "check whether this document has finished processing". ### `openai.remove_file_from_vector_store` Remove a file from an OpenAI vector store's index by file id. Use when the user wants a document taken out of a knowledge base's search results. Deletes the file's presence in this store's index only; the file itself stays in OpenAI's storage. Irreversible for this store's index. Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). No scopes beyond the connection's defaults. Calls `DELETE /vector_stores/{{params.vector_store_id}}/files/{{params.file_id}}`. Arguments: | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `file_id` | string | **yes** | File id to remove. | | `vector_store_id` | string | **yes** | Vector store to remove the file from. | Result fields (the payload is trimmed to these before it reaches the model): | Field | Type | Notes | | --- | --- | --- | | `deleted` | boolean | | | `id` | string | | Also retrieved by: "take this document out of the knowledge base", "stop this file from showing up in search results", "drop one document from the collection's index".