--- title: "Execute Tool" method: POST path: "/tools/{id}" tags: ["Chats", "dev-api"] --- # Execute Tool `POST /tools/{id}` ## Request - Base URL: `https://gateway.prem.io` - URL: `https://gateway.prem.io/tools/{id}` - Auth: HTTP bearer and API key in header `Authorization` Execute a specific tool by passing encrypted parameters. ## Path parameters - `id` string, required ## Request body - union: Request body for executing a tool with encrypted parameters. The structure varies based on the tool type: simple tools, file output tools, or file input tools. - object: Request for simple tools that don't involve file I/O: webSearchTool, getTime, webPageScraperTool - `cipherText` string, required: Cipher text from ML-KEM encapsulation for shared secret generation - `encryptedParams` string, required: Encrypted JSON string containing the tool parameters - `nonce` string, required: Nonce used for encrypting the parameters payload - object: Request for tools that generate files: generateImage, audioGenerateFromText, createFileForUser. Requires additional DEK encryption materials for secure file output. - `cipherText` string, required: Cipher text from ML-KEM encapsulation for shared secret generation - `encryptedParams` string, required: Encrypted JSON string containing the tool parameters - `nonce` string, required: Nonce used for encrypting the parameters payload - `encryptedDEK` string, required: Encrypted Data Encryption Key (DEK) for file output encryption - `dekNonce` string, required: Nonce used for encrypting the DEK - `wrappedDEK` string, required: Wrapped Data Encryption Key for file storage to enable later file decryption - `kid` string, required: Key identifier (SHA3-256 hash of the public key used for encryption) for file metadata storage - object: Request for tools that process existing files: imageDescribeAndCaption, imageDescribeAndCaptionFallback, videoDescribeAndCaption, getPDFContent, getTextDocumentContent, transcribeAudioToText, transcribeAudioWithDiarization, audioDiarization, getSpreadsheetContent, getPowerPointContent, getDataFileContent, getFileContentOCR. Requires fileId and DEK for file decryption. - `cipherText` string, required: Cipher text from ML-KEM encapsulation for shared secret generation - `nonce` string, required: Nonce used for encrypting the parameters payload - `fileId` string, required: File ID of the encrypted file to process - `encryptedDEK` string, required: Encrypted Data Encryption Key (DEK) - `dekNonce` string, required: Nonce used for encrypting the DEK - `encryptedFileDEK` string, required: Encrypted Data Encryption Key (DEK) for file decryption - `fileDEKNonce` string, required: Nonce used for encrypting the DEK - object: Request for tools that perform RAG operations: searchRag. Requires additional RAG DEK encryption materials for secure search. - `cipherText` string, required: Cipher text from ML-KEM encapsulation for shared secret generation - `encryptedParams` string, required: Encrypted JSON string containing the tool parameters - `nonce` string, required: Nonce used for encrypting the parameters payload - `encryptedDEK` string, required: Encrypted Data Encryption Key (DEK) for file output encryption - `dekNonce` string, required: Nonce used for encrypting the DEK - `encryptedFileDEKs` object[], required: Encrypted Data Encryption Keys (DEKs) for file decryption - `encryptedDEK` string, required: Encrypted Data Encryption Key (DEK) - `nonce` string, required: Nonce used for encrypting the DEK - `fileId` string, required: File ID of the encrypted file to process - `encryptedRagDEK` string, required: Encrypted RAG Data Encryption Key (DEK) for file output encryption - `ragDEKNonce` string, required: Nonce used for encrypting the RAG DEK - `encryptedRagVersion` string, required: Encrypted RAG Version - `ragVersionNonce` string, required: Nonce used for encrypting the RAG Version ## Response `200` Tool executed successfully with encrypted response - object - `status` 200 | 201 | 202, required: Status code of the response - `data` union, required: Response from tool execution. Structure varies by tool type. - object: Response for file-producing tools (generateImage, audioGenerateFromText, createFileForUser) - `fileId` string, required: Unique identifier for the created file - `fileName` string, required: Encrypted file name (decrypt using DEK) - `fileSize` integer, required: File size in bytes - `handle` string: Encrypted file handle for local access - `mimeType` string, required: Encrypted MIME type (decrypt using DEK) - `s3Path` string, required: Storage path for the encrypted file - `success` boolean, required - `message` string: Human-readable message about the operation - object: Encrypted response for all non-file tools. Decrypt encryptedResponse using DEK and nonce. The _decryptedResponse property shows reference structures for each tool type. - `encryptedResponse` string, required: Encrypted response data. Decrypt using DEK and nonce to get the actual tool response. - `nonce` string, required: Nonce used for encryption - `_decryptedResponse` union: **Reference only** - This shows the possible structures that encryptedResponse should contain when decrypted, depending on the tool type. - object - `now` string, date-time, required: Current timestamp in ISO 8601 format - `timezone` string, required: Requested timezone - string: Markdown formatted search results with titles, URLs, and descriptions - string: Web page content converted to markdown - string: Text description of the image or video content - object - `chunks` object[], required: Array of text chunks extracted from the PDF - `pageContent` string - `metadata` object - object - `content` string, required: Full text content of the document - `chunks` object[]: Chunked content for easier processing - `pageContent` string - `metadata` object - `format` string, required: File format (txt, md, docx, etc.) - `wordCount` integer: Approximate word count - `error` string - object - `text` string, required: Full transcribed text - `segments` object[]: Timed segments of the transcription - `id` integer - `start` number - `end` number - `text` string - `language` string: Detected or specified language - object - `segments` object[], required: Segments with speaker labels and timestamps - `speaker` string - `start` number - `end` number - `text` string - `speakers` string[], required: List of identified speakers - `totalDuration` number: Total audio duration in seconds - `totalWords` integer: Total word count - `detectedLanguage` string: Detected language - string: Extracted text from OCR processing - object - `format` 'csv' | 'xlsx', required: Spreadsheet format - `data` array[]: 2D array of cell values (for CSV) - unknown[] - … - `sheets` object[]: Array of sheets (for XLSX) - `name` string - `data` unknown[] - … - `preview` string - `preview` string: Human-readable table preview - `rowCount` integer, required - `columnCount` integer, required - `error` string - object - `format` 'json' | 'xml', required: Data file format - `content` string, required: Pretty-printed file content - `summary` object: Summary of the data structure - `type` string - `length` integer - `keys` string[] - `keyCount` integer - `rootTag` string - `elementCount` integer - `error` string - object - `slides` object[], required: Array of slide content - `slideNumber` integer - `text` string - `notes` string - `hasImages` boolean - `imageCount` integer - `recommendedOcr` boolean - `textLength` integer - `totalSlides` integer, required: Total number of slides - `format` string, required: PowerPoint format (pptx, ppt, etc.) - `formattedContent` string, required: Human-readable formatted content of all slides - `ocrSummary` object - `slidesNeedingOcr` integer - `slidesWithImages` integer - `slidesWithMinimalText` integer - `error` string - object - `speakers` object[], required: Audio separated by speakers - `speaker` string - `segments` unknown[] - … - string: Search results from user's document store - `error` string, nullable: Error message of the response, human readable - `message` string, nullable, required: Message of the response, human readable - `env` 'development' | 'production', required: API environment - `log` union: Useful informaiton, not always present, to debug the response - string - object - `validator` union: Validator response object, each key is the field name and value is the error message - object - unknown[] - unknown - `support_id` string, uuid, nullable: Support ID linked to the response, used to identify it when talking with our team. ## Other responses - `400`: Bad request - `401`: Access token is missing or invalid - `403`: You do not have the required permissions to access this resource - `404`: Resource not found ## Changes - **2026-11-13** `d46bc3931b34`: 12 warning - added the new `405.00` enum value to the `allOf[subschema #1]/status` response property for the response status `401` - added the new `405.00` enum value to the `allOf[subschema #1]/status` response property for the response status `403` - added the new `405.00` enum value to the `allOf[subschema #1]/status` response property for the response status `404` - added the new `405.00` enum value to the `status` response property for the response status `400` - …8 more - **2026-10-16** `d5b1beb33be5`: 1 info - endpoint added [Operation history](https://skmtc.dev/premai-io/apis/prem-studio-api/changes/tools/:id/post.md) --- [API](https://skmtc.dev/premai-io/apis/prem-studio-api.md) - [All operations](https://skmtc.dev/premai-io/apis/prem-studio-api/llms.txt) - [OpenAPI document](https://skmtc.dev/premai-io/apis/prem-studio-api/revisions/d46bc3931b34?raw)