{ "openapi": "3.0.2", "info": { "version": "ml_v1", "title": "watsonx.ai", "license": { "name": "IBM", "url": "https://www.ibm.com" }, "x-alternate-name": "watsonx_ai_ml", "termsOfService": "https://www.ibm.com/software/sla/sladb.nsf/sla/bm-6883-09", "x-codegen-config": { "groupMethodsByTag": true, "cli": { "apiPackage": "github.ibm.com/AILifecycle/cpdctl", "cliPluginName": "cpdctl", "cliExecutableName": "", "serviceCommandName": "wx.ai", "disableConfigCommand": true }, "python": { "apiPackage": "ibm_wxai" }, "java": { "apiPackage": "com.ibm.cloud.watsonx.ai" } }, "x-github": "https://github.ibm.com/cloud-api-docs/machine-learning", "x-github-issues": "https://github.ibm.com/cloud-api-docs/machine-learning/issues/new", "description": "## Introduction to IBM watsonx.ai as a Service\n\nUsing `IBM watsonx.ai as a Service` APIs, you can run text inference, prompt tuning and more on Large Language Models (LLM).\n\nIf you are looking for the `IBM watsonx.ai software` APIs, see [here](https://cloud.ibm.com/apidocs/watsonx-ai-cp).\n\nStep-by-step instructions on how to use `IBM watsonx.ai as a Service` can be found\n[here](https://dataplatform.cloud.ibm.com/docs/content/wsj/getting-started/get-started-wdp.html?context=wx&audience=wdp).\n\nThere is a specialized python library that is available to access\n[this REST API](https://ibm.github.io/watsonx-ai-python-sdk/).\n\n## Endpoint URLs\n\n\n\nThe following URL represents the base URLs for the `watsonx.ai` API endpoints.\nWhen you call the API, use the URL and add the path for each method to form the complete API endpoint for your requests.\n\n* Dallas: `https://us-south.ml.cloud.ibm.com`\n* Frankfurt - `https://eu-de.ml.cloud.ibm.com`\n* London - `https://eu-gb.ml.cloud.ibm.com`\n* Tokyo - `https://jp-tok.ml.cloud.ibm.com`\n* Sydney - `https://au-syd.ml.cloud.ibm.com`\n* Toronto - `https://ca-tor.ml.cloud.ibm.com`\n* Mumbai - `https://ap-south-1.aws.wxai.ibm.com`\n\nNote that for `prompts`, `vector indexes` and `agent tools` the base URLs are the following:\n\n* Dallas: `https://api.dataplatform.cloud.ibm.com/wx`\n* Frankfurt - `https://api.eu-de.dataplatform.cloud.ibm.com/wx`\n* London - `https://api.eu-gb.dataplatform.cloud.ibm.com/wx`\n* Tokyo - `https://api.jp-tok.dataplatform.cloud.ibm.com/wx`\n* Sydney - `https://api.au-syd.dai.cloud.ibm.com/wx`\n* Toronto - `https://api.ca-tor.dai.cloud.ibm.com/wx`\n* Mumbai - `https://api.ap-south-1.aws.data.ibm.com/wx`\n\nNote that for `notebooks` the base URLs are the following:\n\n* Dallas: `https://api.dataplatform.cloud.ibm.com`\n* Frankfurt - `https://api.eu-de.dataplatform.cloud.ibm.com`\n* London - `https://api.eu-gb.dataplatform.cloud.ibm.com`\n* Tokyo - `https://api.jp-tok.dataplatform.cloud.ibm.com`\n* Sydney - `https://api.au-syd.dai.cloud.ibm.com`\n* Toronto - `https://api.ca-tor.dai.cloud.ibm.com`\n* Mumbai - `https://api.ap-south-1.aws.data.ibm.com`\n\nExample request to a Dallas endpoint:\n\n```sh\ncurl -H \"Authorization: Bearer {token}\" -X {request_method} \"https://us-south.ml.cloud.ibm.com/{method_endpoint}\"\n```\n\nReplace `{request_method}`, and `{method_endpoint}` in this example with the values\nfor your particular API call. See the `Authentication` section below for more details about the bearer `{token}`.\n\n## Authentication\n\nThis API uses IBM Cloud Identity and Access Management (IAM) to authenticate requests.\n\nTo work with the API, authenticate your application or service by including your IBM Cloud\n[IAM access token](https://cloud.ibm.com/docs/account?topic=account-iamtoken_from_apikey#iamtoken_from_apikey)\nin API requests.\n\nIAM authentication. Replace `{token}` and `{url}/{method}` with your service credentials.\n\n```bash\ncurl -H \"Authorization:Bearer {token}\" -X \"{url}/{method}\"\n```\n\nAuthorization: Bearer {token}\n\nFor example, if the token is `tzLbqWhyALQawBg5TjRIf5sAznhrKQyvBFFaZbtF60m5` in the service credentials, include the credentials in your call like this:\n\n```bash\ncurl -H \"Authorization:Bearer tzLbqWhyALQawBg5TjRIf5sAznhrKQyvBFFaZbtF60m5\" -X \"https://us-south.ml.cloud.ibm.com/ml/v4/models\"\n```\n\n## Error handling\n\nThis API uses standard HTTP response codes to indicate whether a method completed successfully.\nA `200` type response indicates success.\n\n| HTTP Code | Description | Recovery |\n|-----------|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `200` | Success | The request was successful. |\n| `400` | Bad Request | The input parameters in the request body are either incomplete, or in the wrong format, or some other input validation failed. Be sure to include all required parameters in your request and check the request body. |\n| `401` | Unauthorized | You are not authorized to make this request. Log in and try again or provide a valid token. See [Authenticating with IAM tokens](https://cloud.ibm.com/docs/watson?topic=watson-iam#iam) for instructions on logging in. If this error persists, contact the account owner to check your permissions. |\n| `403` | Forbidden | The supplied authentication is not authorized. |\n| `404` | Not Found | The requested resource could not be found. |\n\nNote that `429` and `503` errors may mean that the model is overloaded or unavailable,\ncheck the error description for more details.\n\n### Error response\n\n| Name | Description |\n|--------|-------------------------------------------------------------------------------------------------------|\n| trace | An identifier that can be used to trace the request. This can be set using `X-Global-Transaction-Id`. |\n| errors | The list of errors. |\n\n#### Errors\n\n| Name | Description |\n|-----------|-------------------------------------------------------------------------|\n| code | A simple string code that should convey the general sense of the error. |\n| message | The message that describes the error. |\n| more_info | A reference to a more detailed explanation when available. |\n\n## Additional headers\n\nSome additional headers might be required to make successful requests to the API. Those additional headers are described below.\n\nAn optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services using one identifier. The header key must be set to `X-Global-Transaction-Id` and the value is anything that you choose.\n\nIf there is not a transaction ID that is passed in, then one is generated randomly.\n\n## API change log\n\nIn this change log you can learn about the latest changes, improvements, and updates for the `watsonx.ai` API.\nThe change log lists changes that have been made, ordered by the date they were released.\nChanges to existing API versions are designed to be compatible with existing client applications,\nif this is not the case then a new version date will be created.\n\n### 14 March 2024\n\nThe `watsonx.ai` API is generally available. Use the `watsonx.ai` API to work with foundation models programmatically.\n\n### 18 April 2024\n\nThe [/ml/v1/text/embeddings](#text-embeddings) API was added to `watsonx.ai`, this is a non-breaking change\nand just adds this single API operation.\n\n## Versioning\n\nAPI requests require a version parameter that takes the date in the format `version=YYYY-MM-DD`. Send the version parameter with every API request.\n\nWhen the API is changed in a way that is not compatible with previous versions, a new minor version is released. To take advantage of the changes in a new version, change the value of the version parameter to the new date. If you're not ready to update to that version, don't change your version date.\n\n\n\n## Active Version Dates\n\n| Version date | Summary of changes |\n|--------------|-----------------------------------|\n| `2024-03-14` | Publication of the `/ml/v1` APIs. |\n\n\n\n## Data References\n\nAccessing data in a remote location (such as a Cloud Object Storage bucket, or an SQL/no-SQL database) requires\nthe use of `connection_asset` or `data_asset` reference types.\nThese reference types are created within a space or a project and are referenced in requests to represent input\ndata and results locations. These types contain two parameter objects, `connection` and `location`, which require\ndifferent values to be supplied based on the reference type. Using a `data_asset`, requires an `href` to be supplied\nto the `location` object whereas using a `connection_asset` requires the `connection_id` for the `connection` object\nand different `location` fields depending on the data source type.\n\n\n\nExample `connection_asset` payload:\n\n```json\n{\n \"training_data_references\": [\n {\n \"type\": \"connection_asset\",\n \"connection\": {\n \"id\": \"\"\n },\n \"location\": {\n \"\": \"\"\n }\n }\n ]\n}\n```\n\nExample `data_asset` payload:\n\n```json\n{\n \"training_data_references\": [\n {\n \"type\": \"data_asset\",\n \"location\": {\n \"href\": \"/v2/assets/?space_id=\"\n }\n }\n ]\n}\n```\n\nExample `container` payload:\n\n```json\n{\n \"training_data_references\": [\n {\n \"location\":{\n \"path\":\"filename_in_project_or_space\"\n },\n \"type\":\"container\"\n }\n ]\n}\n```\n\n## Activity Tracker events\n\nYou can monitor API activity within your account by using the IBM Cloud Activity Tracker service.\nWhenever an API method is called, an event is generated that you can then track and audit from within Activity Tracker.\nThe specific event type is listed for each individual method.\n\n\n\n", "x-last-updated": "2025-12-02" }, "tags": [ { "name": "AI Services", "x-cli-command-group": "AI service", "description": "Manage AI services.", "x-displayName": "AI Services" }, { "name": "Files", "description": "Operations for managing uploaded files", "x-displayName": "Files" }, { "name": "Batches", "description": "Operations for managing batch jobs", "x-displayName": "Batches" }, { "name": "AutoAI RAG", "x-cli-command-group": "autoai_rag", "description": "Find the best RAG patterns.", "x-displayName": "AutoAI RAG" }, { "name": "Deployments", "x-cli-command-group": "Deployment", "description": "Manage Deployments.", "x-displayName": "Deployments" }, { "name": "Evaluations", "x-cli-command-group": "Evaluation", "description": "Manage Evaluation Jobs for foundation models.", "x-displayName": "Evaluations" }, { "name": "Fine Tunings (Beta)", "x-cli-command-group": "Fine Tuning", "description": "Fine tune an LLM.", "x-displayName": "Fine Tunings (Beta)" }, { "name": "Foundation Model Specs", "x-cli-command-group": "Foundation model", "description": "Operations to query the details of the deployed foundation models.", "x-displayName": "Foundation Model Specs" }, { "name": "GPUs", "description": "List available GPUs.", "x-displayName": "GPUs" }, { "name": "Notebooks", "x-cli-command-group": "Notebook", "description": "A notebook here refers to all the information about a Jupyter Notebook, such as its name, creation time, associated project, environment, asset etc.", "x-displayName": "Notebooks" }, { "name": "Notebook Versions", "x-cli-command-group": "Notebook version", "description": "A notebook can be saved in different versions. Users can revert their changes to a specific version.", "x-displayName": "Notebook Versions" }, { "name": "Prompts", "x-cli-command-group": "Prompt", "description": "Prompts for foundational models.", "x-displayName": "Prompts" }, { "name": "Prompt Sessions", "x-cli-command-group": "Prompt Session", "description": "Prompt sessions for foundational model inferencing.", "x-displayName": "Prompt Sessions" }, { "name": "Batch", "description": "OpenAI-compatible batch processing APIs.", "x-displayName": "Batch" }, { "name": "Text Chat", "description": "Operations to infer text from a chat context.", "x-displayName": "Text Chat" }, { "name": "Text Classification", "description": "Classify text from a document or image.", "x-displayName": "Text Classification" }, { "name": "Create Schema", "description": "Create Schema from a input document or image.", "x-displayName": "Create Schema" }, { "name": "Improve Schema", "description": "Improve Schema from a input schema.", "x-displayName": "Improve Schema" }, { "name": "Merge Schema", "description": "Merge multiple schemas.", "x-displayName": "Merge Schema" }, { "name": "Cluster Schema", "description": "Cluster same kind of schemas.", "x-displayName": "Cluster Schema" }, { "name": "Text Detection", "description": "Operations for text detection.", "x-displayName": "Text Detection" }, { "name": "Text Embeddings", "description": "Operations for text embeddings.", "x-displayName": "Text Embeddings" }, { "name": "Text Extraction", "description": "Operations to extract text and metadata from documents.", "x-displayName": "Text Extraction" }, { "name": "Text Generation", "description": "Operations to infer text from a prompt.", "x-displayName": "Text Generation" }, { "name": "Text To Image", "description": "Operations to generate images from a textual description.", "x-displayName": "Text To Image" }, { "name": "Text Rerank", "description": "Operations for text reranking.", "x-displayName": "Text Rerank" }, { "name": "Text Tokenization", "description": "Operations to calculate tokens.", "x-displayName": "Text Tokenization" }, { "name": "Time Series", "description": "Operation for time series.", "x-displayName": "Time Series" }, { "name": "Trainings", "x-cli-command-group": "Training", "description": "Manage Trainings.", "x-displayName": "Trainings" }, { "name": "Vector Indexes", "description": "Create a vector index asset.", "x-displayName": "Vector Indexes" }, { "name": "Vector Indexes - transactional API", "description": "Create a vector index asset.", "x-displayName": "Vector Indexes - transactional API" }, { "name": "Geospatial (Private)", "x-cli-command-group": "Geospatial", "description": "Private operations for EIS.", "x-displayName": "Geospatial (Private)" }, { "name": "Document Extraction (Beta)", "description": "Operations for document Extractions.", "x-displayName": "Document Extraction (Beta)" }, { "name": "Synthetic Data", "description": "Operations for Synthetic Data Generation.", "x-displayName": "Synthetic Data" }, { "name": "Synthetic Data Generation (Beta)", "description": "Operations for Synthetic Data Generation.", "x-displayName": "Synthetic Data Generation (Beta)" }, { "name": "Taxonomy (Beta)", "description": "Operations for Taxonomy.", "x-displayName": "Taxonomy (Beta)" }, { "name": "Utility Agent tools (Beta)", "x-cli-command-group": "Agent tool", "description": "Run an agent tool.", "x-displayName": "Utility Agent tools (Beta)" }, { "name": "Model Gateway", "description": "Operations for the Model Gateway.", "x-displayName": "Model Gateway" }, { "name": "Utility Agent Tools (Beta)", "x-displayName": "Utility Agent Tools (Beta)" } ], "paths": { "/ml/v1/text/generation": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "text_generation", "x-cli-command": "generate", "x-cli-command-group": "text", "tags": [ "Text Generation" ], "summary": "Infer text", "description": "Infer the next tokens for a given deployed model with a set of parameters.\n\nThis API is legacy, consider using [Text Chat](#text-chat).\n", "requestBody": { "required": true, "description": "From a given prompt, infer the next tokens.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextGenRequest" }, "examples": { "request": { "summary": "A request without moderations.", "description": "A simple request.\n", "value": { "model_id": "google/flan-ul2", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "input": "Generate a marketing email advertising a new sale with the following characteristics:\n\nCompany: Swimwear Unlimited\n\nOffer Keywords: {Select customers only, mid-summer fun, swimwear sale}\n\nOffer End Date: July 15\n\nAdvertisement Tone: Exciting!\n\nInclude no URLs.\n\nInclude no telephone numbers.\n", "parameters": { "temperature": 0.8, "max_new_tokens": 30 } } }, "moderations_request": { "summary": "A request with moderations.", "description": "A simple request with moderations.\n", "value": { "model_id": "google/flan-t5-xl", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "input": "Tell me how to reach the US Postal service", "parameters": { "max_new_tokens": 120, "min_new_tokens": 100, "repetition_penalty": 2 }, "moderations": { "hap": { "output": { "enabled": true, "threshold": 0.5 } }, "pii": { "output": { "enabled": true }, "mask": { "remove_entity_value": true } } } } } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextGenResponse" }, "examples": { "response": { "summary": "A response without moderations.", "description": "The generated text from the model along with other details.\n", "value": { "model_id": "google/flan-ul2", "created_at": "2023-07-21T16:52:32.190Z", "results": [ { "generated_text": "4,000 km", "generated_token_count": 4, "input_token_count": 12, "stop_reason": "eos_token" } ] } }, "moderated_response": { "summary": "A response with moderations.", "description": "The generated text from the model along with other details.\n", "value": { "model_id": "google/flan-t5-xl", "created_at": "2023-07-21T16:52:32.190Z", "results": [ { "generated_text": "c/o USPS, PO Box 3000, Washington, D.C. 20001-5000, www.usps.com, or call **************. You can also visit the website at https://www.usps.com/contactus/. You can also contact them by telephone at 1-************. You can also send an email to ***************. You can find the US Postal Service on Facebook at https://www.facebook.com/postalservice/.", "generated_token_count": 118, "input_token_count": 11, "stop_reason": "eos_token", "moderations": { "pii": [ { "score": 0.8, "input": false, "position": { "start": 74, "end": 88 }, "entity": "PhoneNumber" }, { "score": 0.8, "input": false, "position": { "start": 200, "end": 212 }, "entity": "PhoneNumber" }, { "score": 0.8, "input": false, "position": { "start": 244, "end": 259 }, "entity": "EmailAddress" } ] } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.foundation-model.send" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "post request", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v1/text/generation?version=2023-05-02'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "--data-raw '{\n", " \"model_id\": \"google/flan-t5-xxl\",\n", " \"input\": \"how far is paris from bangalore:\",\n", " \"parameters\": {\n", " \"max_new_tokens\": 100,\n", " \"time_limit\": 1000\n", " },\n", " \"project_id\": \"63dc4cf1-252f-424b-b52d-5cdd9814987f\"\n", "}'" ] } ] } ] } } } }, "/ml/v1/text/generation_stream": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "text_generation_stream", "x-cli-command": "generate-stream", "x-cli-command-group": "text", "tags": [ "Text Generation" ], "summary": "Infer text event stream", "description": "Infer the next tokens for a given deployed model with a set of parameters.\nThis operation will return the output tokens as a stream of events.\n\nThis API is legacy, consider using [Text Chat Stream](#text-chat-stream).\n", "requestBody": { "required": true, "description": "From a given prompt, infer the next tokens in a server-sent events (SSE) stream.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextGenStreamRequest" }, "examples": { "request": { "summary": "A request without moderations.", "description": "A simple request.\n", "value": { "model_id": "google/flan-ul2", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "input": "Generate a marketing email advertising a new sale with the following characteristics:\n\nCompany: Swimwear Unlimited\n\nOffer Keywords: {Select customers only, mid-summer fun, swimwear sale}\n\nOffer End Date: July 15\n\nAdvertisement Tone: Exciting!\n\nInclude no URLs.\n\nInclude no telephone numbers.\n", "parameters": { "temperature": 0.8, "max_new_tokens": 30 } } }, "moderations_request": { "summary": "A request with moderations.", "description": "A simple request with moderations.\n", "value": { "model_id": "google/flan-t5-xl", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "input": "Tell me how to reach the US Postal service", "parameters": { "max_new_tokens": 120, "min_new_tokens": 100, "repetition_penalty": 2 }, "moderations": { "hap": { "output": { "enabled": true, "threshold": 0.5 } }, "pii": { "output": { "enabled": true }, "mask": { "remove_entity_value": true } } } } } } } } }, "responses": { "200": { "description": "Successful operation (`Content-Type: text/event-stream`).", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/TextGenStreamResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.foundation-model.send" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "post request", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v1/text/generation_stream?version=2023-05-02'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "--data-raw '{\n", " \"model_id\": \"google/flan-t5-xxl\",\n", " \"input\": \"how far is paris from bangalore:\",\n", " \"parameters\": {\n", " \"max_new_tokens\": 100,\n", " \"time_limit\": 1000\n", " },\n", " \"project_id\": \"63dc4cf1-252f-424b-b52d-5cdd9814987f\"\n", "}'" ] } ] } ] } } } }, "/ml/v1/text/tokenization": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "text_tokenization", "x-cli-command": "tokenize", "x-cli-command-group": "text", "tags": [ "Text Tokenization" ], "summary": "Text tokenization", "description": "The text tokenize operation allows you to check the conversion of provided input to tokens for a given model.\nIt splits text into words or sub-words, which then are converted to ids through a look-up table (vocabulary).\nTokenization allows the model to have a reasonable vocabulary size.\n", "requestBody": { "required": true, "description": "The input string to tokenize.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextTokenizeRequest" }, "examples": { "request": { "summary": "A sample request.", "value": { "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "model_id": "google/flan-ul2", "input": "Write a tagline for an alumni association: Together we", "parameters": { "return_tokens": true } } } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextTokenizeResponse" }, "examples": { "response": { "summary": "The response with the token count.", "description": "The response with the token count and the tokens, if requested.\n", "value": { "model_id": "google/flan-ul2", "result": { "token_count": 11, "tokens": [ "Write", "a", "tag", "line", "for", "an", "alumni", "associ", "ation:", "Together", "we" ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.text-tokenization.send" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "post request", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v1/text/tokenization?version=2023-05-02'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "--data-raw '{\n", " \"model_id\": \"google/flan-ul2,\",\n", " \"input\": \"Write a tagline for an alumni association: Together we\",\n", " \"parameters\": {\n", " \"return_tokens\": true\n", " },\n", " \"project_id\": \"63dc4cf1-252f-424b-b52d-5cdd9814987f\"\n", "}'" ] } ] } ] } } } }, "/ml/v1/foundation_model_specs": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/model_filters" }, { "$ref": "#/components/parameters/tech_preview" } ], "get": { "operationId": "list_foundation_model_specs", "x-cli-command": "list-models", "description": "Retrieve the list of deployed foundation models.\n", "tags": [ "Foundation Model Specs" ], "summary": "List the available foundation models", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FoundationModels" }, "examples": { "foundation_model_specs": { "summary": "The list of models.", "description": "The models that are currently deployed in the cluster.\n", "value": { "total_count": 1, "limit": 100, "first": { "href": "https://us-south.ml.cloud.ibm.com/ml/v1/foundation_model_specs?version=2023-05-02" }, "resources": [ { "model_id": "bigcode/starcoder", "label": "starcoder-15.5b", "provider": "BigCode", "source": "Hugging Face", "short_description": "The StarCoder models are 15.5B parameter models that can generate code from natural language descriptions", "tasks": [ { "id": "code", "ratings": { "quality": 3 } } ], "min_shot_size": 0, "input_tier": "class_2", "output_tier": "class_2", "number_params": "15.5b" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "get foundation models", "example": [ { "type": "code", "source": [ "curl --request GET 'https://{cluster_url}/ml/v1/foundation_model_specs?version=2019-10-25&filters=function_time_series_forecast'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Accept: application/json'\n" ] } ] } ] } } } }, "/ml/v1/foundation_model_tasks": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" } ], "get": { "operationId": "list_foundation_model_tasks", "x-cli-command": "list-tasks", "description": "Retrieve the list of tasks that are supported by the foundation models.\n", "tags": [ "Foundation Model Specs" ], "summary": "List the supported tasks", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FoundationModelTasks" }, "examples": { "foundation_model_tasks": { "summary": "The list of tasks.", "description": "The tasks that are currently supported by models deployed in the cluster.\n", "value": { "total_count": 1, "limit": 100, "first": { "href": "https://us-south.ml.cloud.ibm.com/ml/v1/foundation_model_tasks?version=2023-05-02" }, "resources": [ { "task_id": "question_answering", "label": "Question answering", "rank": 1, "description": "Based on a set of documents or dynamic content, create a chatbot or a question-answering feature grounded on specific content. E.g. building a Q&A resource from a broad knowledge base, providing customer service assistance." } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "Bearer": [] } ] } }, "/ml/v4/deployments": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "create_deployment", "x-cli-command": "create", "tags": [ "Deployments" ], "summary": "Create a new watsonx.ai deployment", "description": "Create a new deployment, currently the only supported type is `online`.\n\nIf this is a deployment for a prompt template then the `prompt_template`\nobject should\nexist and the `id` must be the `id` of the prompt template to be deployed.\n", "x-cli-generate-async-handler": true, "requestBody": { "description": "The deployment request entity.\n\nThe following important fields are described for each use case:\n1. Prompt template:\n - `base_model_id`: **required**\n - `prompt_template.id`: **required**\n - `online`: **required**\n - `hardware_spec`: **forbidden**\n - `hardware_request`: **forbidden**\n - response `deployed_asset_type`: `foundation_model`\n1. Custom foundation model:\n - `asset.id`: **required**\n - `online`: **required**\n - `online.parameters.foundation_model`: **optional**\n - `hardware_spec`: **required**\n - `hardware_request`: **forbidden**\n - `base_model_id`: **forbidden**\n - `base_deployment_id`: **forbidden**\n - response `deployed_asset_type`: `custom_foundation_model`\n1. Deploy on Demand model:\n - `asset.id`: **required**\n - `online`: **required**\n - `online.parameters.foundation_model`: **forbidden**\n - `hardware_spec`: **optional**\n - `hardware_request`: **forbidden**\n - `base_model_id`: **forbidden**\n - `base_deployment_id`: **forbidden**\n - `space_id`: **required**\n - `project_id`: **forbidden**\n - response `deployed_asset_type`: `curated_foundation_model`\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentResourcePrototype" }, "examples": { "prompt_template": { "summary": "Create a prompt template deployment.", "value": { "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "name": "text_classification", "base_model_id": "google/flan-ul2", "prompt_template": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab" }, "online": {} } }, "custom_foundation_model_saas": { "summary": "Create a custom foundation model deployment.", "value": { "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "name": "my_tuned_flan", "asset": { "id": "366c31e9-1a6b-417a-8e25-06178a1514a1" }, "hardware_spec": { "name": "1l40s-48g", "num_nodes": 1 }, "online": { "parameters": { "serving_name": "myflan", "foundation_model": { "functions": [ "text_generation" ] } } } } }, "deploy_on_demand_model": { "summary": "Deploy a curated model.", "value": { "space_id": "8ca6eec6-ce39-4285-877b-97a9720cdd03", "name": "my_granite_13b_chat_v2", "asset": { "id": "38d30589-286c-4b9f-82d5-5006d5fa3bb4" }, "online": { "parameters": { "serving_name": "granite_13b_chat_v2", "foundation_model": { "functions": [ "text_generation" ] } } } } } } } }, "required": true }, "responses": { "202": { "description": "Deployment created.", "headers": { "Location": { "description": "The location of the newly created resource (deployment).", "schema": { "type": "string", "description": "The location of the newly created resource (deployment).\n" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentResource" }, "examples": { "prompt_template_deployment": { "summary": "A prompt template deployment.", "value": { "metadata": { "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "created_at": "2023-05-02T16:27:51Z", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "name": "text_classification", "description": "Classification prompt template deployment", "tags": [ "classification" ] }, "entity": { "prompt_template": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab" }, "online": {}, "deployed_asset_type": "foundation_model", "base_model_id": "google/flan-t5-xl", "status": { "state": "ready", "message": { "level": "info", "text": "The deployment is successful" }, "inference": [ { "url": "https://us-south.ml.cloud.ibm.com/ml/v1/deployments/6213cf1-252f-424b-b52d-5cdd9814956c/text/generation" }, { "url": "https://us-south.ml.cloud.ibm.com/ml/v1/deployments/6213cf1-252f-424b-b52d-5cdd9814956c/text/generation_stream", "sse": true } ] } } } }, "custom_foundation_model_deployment_saas": { "summary": "A custom foundation model deployment.", "value": { "metadata": { "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "created_at": "2023-05-02T16:27:51Z", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "name": "my_tuned_flan" }, "entity": { "asset": { "id": "366c31e9-1a6b-417a-8e25-06178a1514a1" }, "online": { "parameters": { "serving_name": "myflan", "foundation_model": { "functions": [ "text_generation" ] } } }, "deployed_asset_type": "custom_foundation_model", "hardware_spec": { "name": "1l40s-48g", "num_nodes": 1 }, "base_model_id": "google/flan-t5-xl", "status": { "state": "ready", "message": { "level": "info", "text": "The deployment is successful" }, "inference": [ { "url": "https://us-south.ml.cloud.ibm.com/ml/v1/deployments/6213cf1-252f-424b-b52d-5cdd9814956c/text/generation" }, { "url": "https://us-south.ml.cloud.ibm.com/ml/v1/deployments/myflan/text/generation", "uses_serving_name": true }, { "url": "https://us-south.ml.cloud.ibm.com/ml/v1/deployments/6213cf1-252f-424b-b52d-5cdd9814956c/text/generation_stream", "sse": true }, { "url": "https://us-south.ml.cloud.ibm.com/ml/v1/deployments/myflan/text/generation_stream", "sse": true, "uses_serving_name": true } ] } } } }, "deploy_on_demand_model": { "summary": "A curated foundation model.", "value": { "metadata": { "id": "c9240431-8697-42ad-8ab3-1cced97fc6db", "created_at": "2024-12-12T10:42:52.298Z", "name": "my_granite_13b_chat_v2", "space_id": "8ca6eec6-ce39-4285-877b-97a9720cdd03" }, "entity": { "asset": { "id": "38d30589-286c-4b9f-82d5-5006d5fa3bb4" }, "base_model_id": "ibm/granite-13b-chat-v2-curated", "deployed_asset_type": "curated_foundation_model", "hardware_spec": { "num_nodes": 1, "name": "1l40s-48g" }, "online": { "parameters": { "serving_name": "granite_13b_chat_v2" } }, "status": { "inference": [ { "url": "https://us-south.ml.cloud.ibm.com/ml/v1/deployments/curated_test_22/text/generation", "uses_serving_name": true }, { "url": "https://us-south.ml.cloud.ibm.com/ml/v1/deployments/curated_test_22/text/generation_stream", "uses_serving_name": true, "sse": true }, { "url": "https://us-south.ml.cloud.ibm.com/ml/v1/deployments/c9240431-8697-42ad-8ab3-1cced97fc6db/text/generation" }, { "url": "https://us-south.ml.cloud.ibm.com/ml/v1/deployments/c9240431-8697-42ad-8ab3-1cced97fc6db/text/generation_stream", "sse": true } ], "state": "ready" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.deployment.create" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "A prompt tune deployment", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v4/deployments?version=2023-05-02'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "-d ", "{\n", " \"project_id\": \"12ac4cf1-252f-424b-b52d-5cdd9814987f\",\n", " \"name\": \"text_classification\",\n", " \"description\": \"Classification prompt tuned model deployment\",\n", " \"tags\": [\"classification\"],\n", " \"asset\": {\n", " \"id\": \"4cedab6d-e8e4-4214-b81a-2ddb122db2ab\"\n", " },\n", " \"online\": {}\n", "}\n" ] } ] }, { "name": "A prompt template deployment", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v4/deployments?version=2023-05-02'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "-d ", "{\n", " \"project_id\": \"12ac4cf1-252f-424b-b52d-5cdd9814987f\",\n", " \"name\": \"text_classification\",\n", " \"description\": \"Classification prompt template deployment\",\n", " \"tags\": [\"classification\"],\n", " \"prompt_template\": {\n", " \"id\": \"4cedab6d-e8e4-4214-b81a-2ddb122db2ab\"\n", " },\n", " \"base_model_id\": \"google/flan-t5-xl\",\n", " \"online\": {}\n", "}\n" ] } ] }, { "name": "A custom foundation model deployment", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v4/deployments?version=2023-05-02'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "-d ", "{\n", " \"project_id\": \"12ac4cf1-252f-424b-b52d-5cdd9814987f\"\n", " \"name\": \"my_tuned_flan\"\n", " \"asset\": {\n", " \"id\": \"366c31e9-1a6b-417a-8e25-06178a1514a1\"\n", " },\n", " \"online\": {\n", " \"parameters\": {\n", " \"serving_name\": \"myflan\"\n", " \"foundation_model\": {\n", " \"functions\": [\"text_generation\"]\n", " }\n", " }\n", " }\n", "}\n" ] } ] }, { "name": "A curated foundational model deployment", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v4/deployments?version=2023-05-02'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "-d ", "{\n", " \"space_id\": \"8ca6eec6-ce39-4285-877b-97a9720cdd03\",\n", " \"name\": \"my_granite_13b_chat_v2\",\n", " \"asset\": {\n", " \"id\": \"38d30589-286c-4b9f-82d5-5006d5fa3bb4\"\n", " },\n", " \"base_model_id\": \"ibm/granite-13b-chat-v2-curated\",\n", " \"hardware_request\": {\n", " \"size\": \"gpu_s\",\n", " \"num_nodes\": 1\n", " },\n", " \"online\": {\n", " \"parameters\": {\n", " \"serving_name\": \"granite_13b_chat_v2\"\n", " \"foundation_model\": {\n", " \"functions\":[\"text_generation\"]\n", " }\n", " }\n", " }\n", "}\n" ] } ] } ] } } }, "get": { "operationId": "list_deployments", "tags": [ "Deployments" ], "summary": "Retrieve the deployments", "description": "Retrieve the list of deployments for the specified space or project.\n", "parameters": [ { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" }, { "name": "serving_name", "description": "Retrieves the deployment, if any, that contains this `serving_name`.", "example": "classification", "in": "query", "schema": { "type": "string" } }, { "name": "tag.value", "description": "Retrieves only the resources with the given tag value.", "in": "query", "schema": { "type": "string" } }, { "name": "asset_id", "description": "Retrieves only the resources with the given asset_id,\nasset_id would be the model id.\n", "in": "query", "schema": { "type": "string" } }, { "name": "prompt_template_id", "description": "Retrieves only the resources with the given prompt_template_id.\n", "in": "query", "schema": { "type": "string" } }, { "name": "name", "description": "Retrieves only the resources with the given name.", "in": "query", "schema": { "type": "string" } }, { "name": "type", "description": "Retrieves the resources filtered with the given type. There are the deployment types as well as an additional\n`prompt_template` if the deployment type includes a prompt template.\n\nThe supported deployment types are (see the description for `deployed_asset_type` in the deployment entity):\n\n1. `foundation_model` - when a prompt template is used on a pre-deployed IBM provided model.\n2. `custom_foundation_model` - when a custom foundation model is deployed.\n3. `lora_adapter` - when a lora adapter model is deployed.\n4. `curated_foundation_model` - when a deploy on demand model is deployed.\n5. `fine_tune` - when a fine tune model is deployed.\nThese can be combined with the flag `prompt_template` like this:\n\n1. `type=foundation_model` - return all prompt template deployments.\n2. `type=foundation_model and prompt_template` - return all prompt template deployments - this is the same as the previous query because a `foundation_model` can only exist with a prompt template.\n3. `type=prompt_template` - return all deployments with a prompt template.\n", "in": "query", "schema": { "type": "string" } }, { "name": "state", "description": "Retrieves the resources filtered by state. Allowed values are `initializing`, `updating`, `ready` and `failed`.\n", "in": "query", "schema": { "type": "string" } }, { "name": "conflict", "description": "Returns whether `serving_name` is available for use or not.\nThis query parameter cannot be combined with any other parameter except for `serving_name`.\n", "in": "query", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentResourceCollection" } } } }, "204": { "description": "`serving_name` is available for use.\nReturned when `serving_name` and `conflict` query parameters are used.\n" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Returned when `serving_name` and `conflict` query parameters are used.\nThe response body will contain the reason.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "x-ibm-events": { "events": [ { "name": "pm-20.deployment.list" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Retrieve list of deployments", "example": [ { "type": "code", "source": [ "curl --request GET 'https://{cluster_url}/ml/v4/deployments?space_id=aa6dc728-958e-42b7-acdf-d403e16d1e9e&\n", "serving_name=ibm&asset_id=259efabd-7850-40fc-843d-6dddcfc286d1\n", "&state=ready&version=2023-05-02'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n" ] } ] } ] } } } }, "/ml/v4/deployments/{deployment_id}": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" }, { "name": "deployment_id", "in": "path", "description": "The deployment id.", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "deployments_get", "x-cli-command": "get", "tags": [ "Deployments" ], "summary": "Retrieve the deployment details", "description": "Retrieve the deployment details with the specified identifier.\n", "parameters": [ { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" }, { "name": "attempt_activation", "in": "query", "description": "Attempts activation for the deployment with specified `deployment_id`, if it is hibernated and if it is set to true.\n", "schema": { "type": "boolean", "default": false }, "example": true } ], "responses": { "200": { "description": "Deployment details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentResource" }, "examples": { "prompt_template_deployment": { "summary": "A prompt template deployment.", "value": { "metadata": { "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "created_at": "2023-05-02T16:27:51Z", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "name": "text_classification", "description": "Classification prompt template deployment", "tags": [ "classification" ] }, "entity": { "prompt_template": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab" }, "online": {}, "deployed_asset_type": "foundation_model", "base_model_id": "google/flan-t5-xl", "status": { "state": "ready", "message": { "level": "info", "text": "The deployment is successful" }, "inference": [ { "url": "https://us-south.ml.cloud.ibm.com/ml/v1/deployments/2cd0bcda-581d-4f04-8028-ec2bc90cc375/text/generation" }, { "url": "https://us-south.ml.cloud.ibm.com/ml/v1/deployments/2cd0bcda-581d-4f04-8028-ec2bc90cc375/text/generation_stream", "sse": true } ] } } } }, "custom_foundation_model_deployment_saas": { "summary": "A custom foundation model deployment.", "value": { "metadata": { "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "created_at": "2023-05-02T16:27:51Z", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "name": "my_tuned_flan" }, "entity": { "asset": { "id": "366c31e9-1a6b-417a-8e25-06178a1514a1" }, "online": { "parameters": { "serving_name": "myflan", "foundation_model": { "functions": [ "text_generation" ] } } }, "deployed_asset_type": "custom_foundation_model", "hardware_spec": { "name": "1l40s-48g", "num_nodes": 1 }, "base_model_id": "google/flan-t5-xl", "status": { "state": "ready", "message": { "level": "info", "text": "The deployment is successful" }, "inference": [ { "url": "https://us-south.ml.cloud.ibm.com/ml/v1/deployments/6213cf1-252f-424b-b52d-5cdd9814956c/text/generation" }, { "url": "https://us-south.ml.cloud.ibm.com/ml/v1/deployments/myflan/text/generation", "uses_serving_name": true }, { "url": "https://us-south.ml.cloud.ibm.com/ml/v1/deployments/6213cf1-252f-424b-b52d-5cdd9814956c/text/generation_stream", "sse": true }, { "url": "https://us-south.ml.cloud.ibm.com/ml/v1/deployments/myflan/text/generation_stream", "sse": true, "uses_serving_name": true } ] } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.deployment.read" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Retrieve deployment details", "example": [ { "type": "code", "source": [ "curl --request GET \"https://{cluster_url}/ml/v4/deployments/{deployment_id}?space_id=aa6dc728-958e-42b7-acdf-d403e16d1e9e&version=2023-05-02\"\n", "-H \"Authorization: Bearer eyJhbGciOiJSUzUxM...\"" ] } ] } ] } } }, "patch": { "operationId": "deployments_update", "x-cli-command": "update", "x-cli-generate-async-handler": true, "tags": [ "Deployments" ], "summary": "Update the deployment metadata", "parameters": [ { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" } ], "description": "Update the deployment metadata.\nThe following parameters of deployment metadata are supported for the patch operation.\n\n- `/name`\n- `/description`\n- `/tags`\n- `/custom`\n- `/online/parameters`\n- `/asset` - `replace` only\n- `/prompt_template` - `replace` only\n- `/hardware_spec`\n- `/hardware_request`\n- `/base_model_id` - `replace` only (applicable only to prompt template deployments referring to IBM base foundation models) \n\nThe PATCH operation with path specified as `/online/parameters` can be used to update the `serving_name`.\n", "requestBody": { "description": "The json patch.\n", "content": { "application/json-patch+json": { "schema": { "$ref": "#/components/schemas/JsonPatch" } } }, "required": true }, "x-json-patch-helper-model": "DeploymentResourcePatch", "responses": { "202": { "description": "Deployment accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentResource" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codegen-request-body-name": "json-patch", "x-ibm-events": { "events": [ { "name": "pm-20.deployment.update" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Update the deployment metadata.", "example": [ { "type": "code", "source": [ "curl --request PATCH \"https://{cluster_url}/ml/v4/deployments/{deployment_id}?space_id=aa6dc728-958e-42b7-acdf-d403e16d1e9e&version=2023-05-02\"\n", "-H \"Authorization: Bearer eyJhbGciOiJSUzUxM...\"\n", "-H \"Content-Type: application/json\"\n", "-H \"Accept: application/json\"\n", "-d \n", "[\n", " {\n", " \"op\": \"replace\",\n", " \"path\": \"/description\",\n", " \"value\": \"New Description\",\n", " }\n", "]" ] } ] } ] } } }, "delete": { "operationId": "deployments_delete", "x-cli-command": "delete", "tags": [ "Deployments" ], "summary": "Delete the deployment", "description": "Delete the deployment with the specified identifier.\n", "parameters": [ { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "204": { "description": "Deployment deleted." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.deployment.delete" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Delete deployment", "example": [ { "type": "code", "source": [ "curl --request DELETE 'https://{cluster_url}/ml/v4/deployments/{deployment_id}?space_id=aa6dc728-958e-42b7-acdf-d403e16d1e9e&version=2023-05-02'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n" ] } ] } ] } } } }, "/ml/v1/deployments/{id_or_name}/text/generation": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/id_or_name" }, { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "deployments_text_generation", "x-cli-command": "text-generate", "tags": [ "Deployments" ], "summary": "Infer text", "description": "Infer the next tokens for a given deployed model with a set of parameters.\nIf a `serving_name` is used then it must match the `serving_name` that is returned in the `inference` section when the deployment was created.\n\nThis API is legacy, consider using [Deployment Text Chat](#deployments-text-chat).\n\n### Return options\n\nNote that there is currently a limitation in this operation when using `return_options`,\nfor input only `input_text` will be returned if requested,\nfor output the `input_tokens` and `generated_tokens` will not be returned.\n", "requestBody": { "description": "From a given prompt, infer the next tokens.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentTextGenRequest" }, "examples": { "prompt_template": { "summary": "A prompt template request.", "description": "A prompt template request.\n", "value": { "space_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "input": "how far is paris from bangalore:\n", "parameters": { "max_new_tokens": 100 } } }, "custom_foundation_model": { "summary": "A custom_foundation_model request", "description": "A text generation request for curated and custom foundation model.\n", "value": { "space_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "input": "how far is paris from bangalore:\n", "parameters": { "max_new_tokens": 100, "min_new_tokens": 20 } } } } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextGenResponse" }, "examples": { "prompt_template": { "summary": "A prompt template response.", "description": "The generated text from the model along with other details for a prompt template.\n", "value": { "model_id": "google/flan-ul2", "created_at": "2023-07-21T16:52:32.190Z", "results": [ { "generated_text": "4,000 km", "generated_token_count": 4, "input_token_count": 12, "stop_reason": "eos_token" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.foundation-model.send" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "prompt tune", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v1/deployments/{id_or_name}/text/generation?version=2023-05-02'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "--data-raw '{\n", " \"input\": \"how far is paris from bangalore:\",\n", " \"parameters\": {\n", " \"max_new_tokens\": 100,\n", " \"time_limit\": 1000\n", " },\n", "}'" ] } ] }, { "name": "prompt template", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v1/deployments/{id_or_name}/text/generation?version=2023-05-02'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "--data-raw '{\n", " \"parameters\": {\n", " \"max_new_tokens\": 100,\n", " \"time_limit\": 1000,\n", " \"prompt_variables\": {\n", " \"name\": \"joe\",\n", " \"count\": 3\n", " },\n", " },\n", "}'" ] } ] } ] } } } }, "/ml/v1/deployments/{id_or_name}/text/generation_stream": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/id_or_name" }, { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "deployments_text_generation_stream", "x-cli-command": "text-generate-stream", "tags": [ "Deployments" ], "summary": "Infer text event stream", "description": "Infer the next tokens for a given deployed model with a set of parameters.\nThis operation will return the output tokens as a stream of events.\nIf a `serving_name` is used then it must match the `serving_name` that is returned in the `inference` section when the deployment was created.\n\nThis API is legacy, consider using [Deployment Text Chat Stream](#deployments-text-chat-stream).\n### Return options\n\nNote that there is currently a limitation in this operation when using `return_options`,\nfor input only `input_text` will be returned if requested,\nfor output the `input_tokens` and `generated_tokens` will not be returned, also the\n`rank` and `top_tokens` will not be returned.\n", "requestBody": { "description": "From a given prompt, infer the next tokens in a server-sent events (SSE) stream.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentTextGenRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful operation (`Content-Type: text/event-stream`).", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/TextGenStreamResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.foundation-model.send" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "prompt tune", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v1/deployments/{id_or_name}/text/generation_stream?version=2023-05-02'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "--data-raw '{\n", " \"input\": \"how far is paris from bangalore:\",\n", " \"parameters\": {\n", " \"max_new_tokens\": 100,\n", " \"time_limit\": 1000\n", " },\n", "}'" ] } ] }, { "name": "prompt template", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v1/deployments/{id_or_name}/text/generation_stream?version=2023-05-02'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "--data-raw '{\n", " \"parameters\": {\n", " \"max_new_tokens\": 100,\n", " \"time_limit\": 1000,\n", " \"prompt_variables\": {\n", " \"name\": \"joe\",\n", " \"count\": 3\n", " },\n", " },\n", "}'" ] } ] } ] } } } }, "/ml/v1/deployments/{id_or_name}/chat/completions": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/id_or_name_chat_template" } ], "post": { "operationId": "deployments_chat_completions", "x-cli-command": "chat", "tags": [ "Deployments" ], "summary": "Infer chat completions", "description": "Infers the next chat message for a given deployment. The deployment must reference either a prompt template with `input_mode` set to `chat`, a custom foundation model, or a curated foundation model. When a prompt template is referenced, the model used for the chat request is specified by the deployment's `base_model_id`. Chat parameters are derived from the prompt template's `model_parameters`. If a `serving_name` is provided, it must match the `serving_name` returned in the inference section at the time of deployment creation.\n\nRelated guides:\n - [Deployment](#create-deployment)\n - [Prompt template](#post-prompt)\n - [Text chat](#text-chat)\n\n\nIf `stream` is true, this operation will return the output tokens in a server-sent events (SSE) stream.\n", "requestBody": { "description": "From a given prompt, infer the next chat message.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentTextChatRequest" }, "examples": { "prompt_template": { "summary": "A chat prompt template request.", "description": "A prompt template request.\n", "value": { "messages": [ { "role": "user", "content": "Who won the world series in 2020?" }, { "role": "assistant", "content": "The Los Angeles Dodgers won the World Series in 2020." }, { "role": "user", "content": { "type": "text", "text": "Where was it played?" } } ] } }, "system_prompt_and_context": { "summary": "A chat prompt template request with system_prompt and context.", "description": "A prompt template request.\n", "value": { "context": "Today is Wednesday", "messages": [ { "role": "user", "content": { "type": "text", "text": "Who are you and which day is tomorrow?" } } ] } } } } }, "required": true }, "responses": { "200": { "description": "Successful operation. `Content-Type: text/event-stream` if `stream` is true.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextChatResponse" }, "examples": { "prompt_template": { "summary": "A chat prompt template response.", "description": "The generated text from the model along with other details for a prompt template.\n", "value": { "id": "cmpl-15475d0dea9b4429a55843c77997f8a9", "model_id": "ibm/granite-3-2b-instruct", "created": 1689958352, "created_at": "2023-07-21T16:52:32.190Z", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "The 2020 World Series was played at the Globe Life Field in Arlington, Texas.\n" }, "finish_reason": "stop" } ], "usage": { "completion_tokens": 27, "prompt_tokens": 186, "total_tokens": 213 } } }, "system_prompt_and_context": { "summary": "A chat prompt template with system_prompt and context response.", "description": "The generated text from the model along with other details for a prompt template.\n", "value": { "id": "cmpl-15475d0dea9b4429a55843c77997f8a9", "model_id": "ibm/granite-3-2b-instruct", "created": 1689958352, "created_at": "2023-07-21T16:52:32.190Z", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello! I am Granite Chat, created by IBM. I am here to assist you. Today is Wednesday.tomorrow is Thursday.\n" }, "finish_reason": "stop" } ], "usage": { "completion_tokens": 32, "prompt_tokens": 154, "total_tokens": 186 } } } } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/TextChatStreamResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "chat-completions.send" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/deployments/{id_or_name}/text/chat": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/id_or_name_chat_template" }, { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "deployments_text_chat", "x-cli-command": "chat", "tags": [ "Deployments" ], "summary": "Infer text chat", "description": "Infers the next chat message for a given deployment. The deployment must reference either a prompt template with `input_mode` set to `chat`, a custom foundation model, or a curated foundation model. When a prompt template is referenced, the model used for the chat request is specified by the deployment's `base_model_id`. Chat parameters are derived from the prompt template's `model_parameters`. If a `serving_name` is provided, it must match the `serving_name` returned in the inference section at the time of deployment creation.\n\nRelated guides:\n - [Deployment](#create-deployment)\n - [Prompt template](#post-prompt)\n - [Text chat](#text-chat)\n\nYou can also use [Deployment Chat Completions](#deployments_chat_completions) to achieve the same result.\n", "requestBody": { "description": "From a given prompt, infer the next chat message.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentTextChatRequest" }, "examples": { "prompt_template": { "summary": "A chat prompt template request.", "description": "A prompt template request.\n", "value": { "messages": [ { "role": "user", "content": "Who won the world series in 2020?" }, { "role": "assistant", "content": "The Los Angeles Dodgers won the World Series in 2020." }, { "role": "user", "content": { "type": "text", "text": "Where was it played?" } } ] } }, "system_prompt_and_context": { "summary": "A chat prompt template request with system_prompt and context.", "description": "A prompt template request.\n", "value": { "context": "Today is Wednesday", "messages": [ { "role": "user", "content": { "type": "text", "text": "Who are you and which day is tomorrow?" } } ] } }, "text_chat": { "summary": "A text chat request", "description": "A text chat request for curated and custom foundation model.\n", "value": { "model_id": "meta-llama/llama-3-8b-instruct", "project_id": "63dc4cf1-252f-424b-b52d-5cdd9814987f", "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "Who won the world series in 2020?" }, { "role": "assistant", "content": "The Los Angeles Dodgers won the World Series in 2020." }, { "role": "user", "content": { "type": "text", "text": "Where was it played?" } } ], "max_tokens": 100, "temperature": 0, "time_limit": 1000, "frequency_penalty": 0, "logit_bias": { "1003": -100, "1004": -100 }, "logprobs": false, "top_logprobs": 20, "max_completion_tokens": 1024, "n": 1, "presence_penalty": 0, "seed": 41, "top_p": 1 } }, "audio_chat": { "summary": "A audio chat request.", "description": "A audio chat request for curated and custom foundation model.\n", "value": { "max_tokens": 64, "messages": [ { "role": "user", "content": [ { "type": "text", "text": "What is in this recording?" }, { "type": "input_audio", "input_audio": { "data": "", "format": "mp3" } } ] } ] } }, "video_chat": { "summary": "A video chat request.", "description": "A video chat request for curated and custom foundation model.\n", "value": { "max_tokens": 4000, "messages": [ { "role": "user", "content": [ { "type": "text", "text": "What is in this video?" }, { "type": "video_url", "video_url": { "url": "data:video/mp4;base64," } } ] } ] } }, "image_chat": { "summary": "A image chat request.", "description": "A image chat request for curated and custom foundation model.\n", "value": { "max_tokens": 2000, "messages": [ { "role": "user", "content": [ { "type": "text", "text": "describe image" }, { "type": "image_url", "image_url": { "url": "data:image/png;base64," } } ] } ] } } } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextChatResponse" }, "examples": { "prompt_template": { "summary": "A chat prompt template response.", "description": "The generated text from the model along with other details for a prompt template.\n", "value": { "id": "cmpl-15475d0dea9b4429a55843c77997f8a9", "model_id": "ibm/granite-3-2b-instruct", "created": 1689958352, "created_at": "2023-07-21T16:52:32.190Z", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "The 2020 World Series was played at the Globe Life Field in Arlington, Texas.\n" }, "finish_reason": "stop" } ], "usage": { "completion_tokens": 27, "prompt_tokens": 186, "total_tokens": 213 } } }, "system_prompt_and_context": { "summary": "A chat prompt template with system_prompt and context response.", "description": "The generated text from the model along with other details for a prompt template.\n", "value": { "id": "cmpl-15475d0dea9b4429a55843c77997f8a9", "model_id": "ibm/granite-3-2b-instruct", "created": 1689958352, "created_at": "2023-07-21T16:52:32.190Z", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello! I am Granite Chat, created by IBM. I am here to assist you. Today is Wednesday.tomorrow is Thursday.\n" }, "finish_reason": "stop" } ], "usage": { "completion_tokens": 32, "prompt_tokens": 154, "total_tokens": 186 } } }, "text_chat": { "summary": "text_chat", "description": "A text chat example.\n", "value": { "id": "cmpl-15475d0dea9b4429a55843c77997f8a9", "model_id": "meta-llama/llama-3-8b-instruct", "created": 1689958352, "created_at": "2023-07-21T16:52:32.190Z", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "The 2020 World Series was played at Globe Life Field in Arlington, Texas,\nwhich is the home stadium of the Texas Rangers.\nHowever, the series was played with no fans in attendance due to the COVID-19 pandemic.\n" }, "finish_reason": "stop" } ], "usage": { "completion_tokens": 47, "prompt_tokens": 59, "total_tokens": 106 } } }, "audio_chat": { "summary": "A audio chat request.", "description": "A audio chat request for curated and custom foundation model.\n", "value": { "id": "chatcmpl-4fd9e8d781804ecade1e7c5313bd6297---74efbe2f-a569-4f12-b138-86e8d531fc6c", "object": "chat.completion", "model_id": "ibm/granite-speech-3-3-8b-curated", "model": "ibm/granite-speech-3-3-8b-curated", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "The statement refers to the ending of a movie, TV show, book, or any form of media. It expresses the user's admiration for how the narrative concluded. However, without specific context or access to the actual recording, I can't provide details about its content. It could be dialogue" }, "finish_reason": "length" } ], "created": 1756969747, "created_at": "2025-09-04T07:09:09.642Z", "usage": { "completion_tokens": 64, "prompt_tokens": 89, "total_tokens": 153 } } }, "video_chat": { "summary": "A video chat request.", "description": "A video chat request for curated and custom foundation model.\n", "value": { "id": "chatcmpl-a396544e1737120112fa105c7ddf604c---3c09453a-9b53-4aab-8e50-d91249e46534", "object": "chat.completion", "model_id": "Qwen-Qwen2-5-VL-32B-Instruct", "model": "Qwen-Qwen2-5-VL-32B-Instruct", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "This video features a large, plump, white creature with tiny ears and a small tail,\nwhich appears to be a main character in what could be a scene from a movie or game.\nThe creature is situated on a grassy surface that could be a hil with a rock and\na tree in the background. It is interacting with the environment, sitting or standing on\nrocks, and making cute face gestures with its arms and ears, which seems to show\nemotions of curiosity or friendliness\n" }, "finish_reason": "stop" } ], "created": 1759782673, "created_at": "2025-10-06T20:23:37.424Z", "usage": { "completion_tokens": 103, "prompt_tokens": 4633, "total_tokens": 4736 } } }, "image_chat": { "summary": "A image chat request.", "description": "A image chat request for curated and custom foundation model.\n", "value": { "id": "chatcmpl-a396544e1737120112fa105c7ddf604c---3c09453a-9b53-4aab-8e50-d91249e460c0", "object": "chat.completion", "model_id": "Qwen-Qwen2-5-VL-32B-Instruct", "model": "Qwen-Qwen2-5-VL-32B-Instruct", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "The image depicts a workspace setup with the following elements:\n1.Laptops:\n - In the foreground, there is a silver laptop with a visible keyboard and screen. The screen appears to be turned off or displaying a dark background.\n - In the background, another laptop is partially visible, also appearing to have its screen turned off.\n2.Desk Surface:\n - The laptops are placed on a wooden desk with a warm, natural finish. The surface has a smooth texture.\n3.Documents/Papers:\n - Scattered around the laptops are several sheets of paper. Some papers are lying flat on the desk, while others appear slightly crumpled or folded.\n4.Lighting:\n - The lighting in the scene is warm and soft, creating a cozy ambiance. The light source seems to be coming from above, casting gentle shadows and giving the image a golden hue.\n5.Background:\n - The background is blurred (bokeh effect), suggesting a shallow depth of field. There is a hint of a wall and possibly a window or lampshade, contributing to the warm tones in the image.\n6.Overall Atmosphere:\n - The image conveys a sense of productivity or work in progress, but the warm lighting and slightly disorganized setup give it a relaxed and informal feel.\n This setup could represent a home office, study area, or casual workspace. The focus is primarily on the laptop in the foreground, while the rest of the scene provides context for the environment.\n" }, "finish_reason": "stop" } ], "created": 1760106214, "created_at": "2025-10-10T14:23:37.424Z", "usage": { "completion_tokens": 313, "prompt_tokens": 623, "total_tokens": 936 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.foundation-model.send" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/deployments/{id_or_name}/text/chat_stream": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/id_or_name_chat_template" }, { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "deployments_text_chat_stream", "x-cli-command": "chat-stream", "tags": [ "Deployments" ], "summary": "Infer text chat event stream", "description": "Infers the next chat message for a given deployment. This operation will return the output tokens as a stream of events. The deployment must reference either a prompt template with `input_mode` set to `chat`, a custom foundation model, or a curated foundation model. When a prompt template is referenced, the model used for the chat request is specified by the deployment's `base_model_id`. Chat parameters are derived from the prompt template's `model_parameters`. If a `serving_name` is provided, it must match the `serving_name` returned in the inference section at the time of deployment creation.\nRelated guides:\n - [Deployment](#create-deployment)\n - [Prompt template](#post-prompt)\n - [Text chat](#text-chat)\n\nYou can also use [Deployment Chat Completions](#deployments_chat_completions) with `stream` option set to true to achieve the same result.\n", "requestBody": { "description": "From a given prompt, infer the next chat message in a server-sent events (SSE)\nstream.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentTextChatRequest" }, "examples": { "prompt_template": { "summary": "A chat prompt template request.", "description": "A prompt template request.\n", "value": { "messages": [ { "role": "user", "content": "Who won the world series in 2020?" }, { "role": "assistant", "content": "The Los Angeles Dodgers won the World Series in 2020." }, { "role": "user", "content": { "type": "text", "text": "Where was it played?" } } ] } }, "system_prompt_and_context": { "summary": "A chat prompt template request with system_prompt and context.", "description": "A prompt template request.\n", "value": { "context": "Today is Wednesday", "messages": [ { "role": "user", "content": { "type": "text", "text": "Who are you and which day is tomorrow?" } } ] } }, "text_chat": { "summary": "A text chat request", "description": "A text chat request for curated and custom foundation model.\n", "value": { "model_id": "meta-llama/llama-3-8b-instruct", "project_id": "63dc4cf1-252f-424b-b52d-5cdd9814987f", "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "Who won the world series in 2020?" }, { "role": "assistant", "content": "The Los Angeles Dodgers won the World Series in 2020." }, { "role": "user", "content": { "type": "text", "text": "Where was it played?" } } ], "max_tokens": 100, "temperature": 0, "time_limit": 1000, "frequency_penalty": 0, "logit_bias": { "1003": -100, "1004": -100 }, "logprobs": false, "top_logprobs": 20, "max_completion_tokens": 1024, "n": 1, "presence_penalty": 0, "seed": 41, "top_p": 1 } }, "audio_chat": { "summary": "A audio chat request.", "description": "A audio chat request for curated and custom foundation model.\n", "value": { "max_tokens": 64, "messages": [ { "role": "user", "content": [ { "type": "text", "text": "What is in this recording?" }, { "type": "input_audio", "input_audio": { "data": "", "format": "mp3" } } ] } ] } }, "video_chat": { "summary": "A video chat request.", "description": "A video chat request for curated and custom foundation model.\n", "value": { "max_tokens": 4000, "messages": [ { "role": "user", "content": [ { "type": "text", "text": "What is in this video?" }, { "type": "video_url", "video_url": { "url": "data:video/mp4;base64," } } ] } ] } }, "image_chat": { "summary": "A image chat request.", "description": "A image chat request for curated and custom foundation model.\n", "value": { "max_tokens": 2000, "messages": [ { "role": "user", "content": [ { "type": "text", "text": "describe image" }, { "type": "image_url", "image_url": { "url": "data:image/png;base64," } } ] } ] } } } } }, "required": true }, "responses": { "200": { "description": "Successful operation (`Content-Type: text/event-stream`).", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/TextChatStreamResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.foundation-model.send" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/deployments/{id_or_name}/time_series/forecast": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/id_or_name" }, { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "deployments_time_series_forecast", "x-cli-command": "time-series-forecast", "tags": [ "Deployments" ], "summary": "Time series forecast", "description": "Generate forecasts, or predictions for future time points, given historical time series data.\n", "requestBody": { "required": true, "description": "The forecast request.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentTSForecastResource" }, "examples": { "request": { "summary": "A sample request.", "value": { "schema": { "timestamp_column": "date", "id_columns": [ "ID1" ] }, "data": { "date": [ "2020-01-01T00:00:00", "2020-01-01T01:00:00", "2020-01-05T01:00:00" ], "ID1": [ "D1", "D1", "D1" ], "TARGET1": [ 1.46, 2.34, 4.55 ] } } } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TSForecastResponse" }, "examples": { "response": { "summary": "A sample response.", "value": { "model_id": "bc35d16e-dd21-472e-9cde-c6c3ad88e3b5", "created_at": "2020-05-02T16:27:51Z", "results": [ { "date": [ "2020-01-05T02:00:00", "2020-01-05T03:00:00", "2020-01-06T00:00:00" ], "ID1": [ "D1", "D1", "D1" ], "TARGET1": [ 1.86, 3.24, 6.78 ] } ], "input_data_points": 512, "output_data_points": 1024 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.time-series-forecast.send" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v4/deployments/{id_or_name}/ai_service": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/id_or_name" }, { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "deployments_ai_service", "x-cli-command": "ai_service", "x-sdk-exclude": true, "tags": [ "Deployments" ], "summary": "Execute AI service", "description": "Execute an inference call for the AI service deployment.\nIf a `serving_name` is used then it must match the `serving_name` that is returned in the `inference` section when the deployment was created.\n", "requestBody": { "description": "Call the deployed AI service with the json payload.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentAIServiceRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentAIServiceResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.ai_service.send" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v4/deployments/{id_or_name}/ai_service_stream": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/id_or_name" }, { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "deployments_ai_service_stream", "x-cli-command": "ai_service_stream", "x-sdk-exclude": true, "tags": [ "Deployments" ], "summary": "Execute AI service stream", "description": "Execute an inference call for the AI service deployment.\nIf a `serving_name` is used then it must match the `serving_name` that is returned in the `inference` section when the deployment was created.\n", "requestBody": { "description": "Call the deployed AI service with the json payload.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentAIServiceRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/DeploymentAIServiceStreamResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.ai_service.send" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v4/trainings": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "trainings_create", "tags": [ "Trainings" ], "summary": "Create a new watsonx.ai training", "description": "Create a new watsonx.ai training in a project or a space.\n\n\nIn order to deploy the tuned model you need to follow the following steps:\n\n 1. Create a WML model asset, in a space or a project,\n by providing the `request.json` as shown below:\n ```\n curl -X POST \"https://{cpd_cluster}/ml/v4/models?version=2024-01-29\" \\\n -H \"Authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n --data '{\n \"name\": \"replace_with_a_meaningful_name\",\n \"space_id\": \"replace_with_your_space_id\",\n \"type\": \"prompt_tune_1.0\",\n \"software_spec\": {\n \"name\": \"watsonx-textgen-fm-1.0\"\n },\n \"metrics\": [ from the training job ],\n \"training\": {\n \"id\": \"05859469-b25b-420e-aefe-4a5cb6b595eb\",\n \"base_model\": {\n \"model_id\": \"google/flan-t5-xl\"\n },\n \"task_id\": \"generation\",\n \"verbalizer\": \"Input: {{input}} Output:\"\n },\n \"training_data_references\": [\n {\n \"connection\": {\n \"id\": \"20933468-7e8a-4706-bc90-f0a09332b263\"\n },\n \"id\": \"file_to_tune1.json\",\n \"location\": {\n \"bucket\": \"wxproject-donotdelete-pr-xeyivy0rx3vrbl\",\n \"path\": \"file_to_tune1.json\"\n },\n \"type\": \"connection_asset\"\n }\n ]\n }'\n ```\n\n\n **Notes:**\n\n 1. If you used the training request field `auto_update_model: true`\n then you can skip this step as the model will have been saved at\n the end of the training job.\n 1. Rather than creating the payload for the model you can use the\n generated `request.json` that was stored in the `results_reference`\n field, look for the path in the field\n `entity.results_reference.location.model_request_path`.\n 1. The model `type` must be `prompt_tune_1.0`.\n 1. The software spec name must be `watsonx-textgen-fm-1.0`.\n\n 1. Create a tuned model deployment as described in the\n [create deployment documentation](#create-deployment).\n", "x-cli-generate-async-handler": true, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrainingResourcePrototype" } } }, "required": true }, "responses": { "201": { "description": "The training job has been created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrainingResource" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.training.create" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Prompt tuning", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v4/trainings?version=2023-05-02'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "--data-raw '{\n", " \"name\": \"my-prompt-tune-training\",\n", " \"project_id\": \"12ac4cf1-252f-424b-b52d-5cdd9814987f\",\n", " \"prompt_tuning\": {\n", " \"base_model\": {\n", " \"model_id\": \"google/flan-t5-xl\"\n", " },\n", " \"task_id\": \"classification\",\n", " \"tuning_type\": \"prompt_tuning\",\n", " \"num_epochs\": 30,\n", " \"learning_rate\": 0.4,\n", " \"accumulate_steps\": 3,\n", " \"batch_size\": 10,\n", " \"max_input_tokens\": 100,\n", " \"max_output_tokens\": 100\n", " },\n", " \"training_data_references\": [\n", " {\n", " \"id\": \"tune1_data.json\",\n", " \"location\": {\n", " \"path\": \"tune1_data.json\"\n", " },\n", " \"type\": \"container\"\n", " }\n", " ],\n", " \"auto_update_model\": true,\n", " \"results_reference\": {\n", " \"location\": {\n", " \"path\": \"tune1/results\"\n", " },\n", " \"type\": \"container\"\n", " }\n", "}'" ] } ] } ] } } }, "get": { "operationId": "trainings_list", "tags": [ "Trainings" ], "summary": "Retrieve the list of trainings", "description": "Retrieve the list of trainings for the specified space or project.\n", "parameters": [ { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/total_count" }, { "name": "tag.value", "description": "Return only the resources with the given tag value.", "in": "query", "schema": { "type": "string" } }, { "name": "state", "description": "Filter based on on the training job state.\n", "in": "query", "schema": { "type": "string", "enum": [ "queued", "pending", "running", "storing", "completed", "failed", "canceled" ] } }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrainingResourceCollection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.training.list" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v4/trainings/{training_id}": { "servers": [], "parameters": [ { "name": "training_id", "in": "path", "description": "The training identifier.", "schema": { "type": "string" }, "required": true }, { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" } ], "get": { "operationId": "trainings_get", "tags": [ "Trainings" ], "summary": "Retrieve the training", "description": "Retrieve the training with the specified identifier.\n", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrainingResource" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.training.get" } ] }, "security": [ { "Bearer": [] } ] }, "delete": { "operationId": "trainings_delete", "tags": [ "Trainings" ], "summary": "Cancel or delete the training", "description": "Cancel or delete the specified training, once deleted all trace of the job is gone.\n", "parameters": [ { "$ref": "#/components/parameters/hard_delete" } ], "responses": { "204": { "description": "Training cancelled." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.training.delete" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/text/embeddings": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "text_embeddings", "x-cli-command": "calculate-embeddings", "x-cli-command-group": "text", "tags": [ "Text Embeddings" ], "summary": "Generate embeddings", "description": "Generate embeddings from text input.\n\nSee the [documentation](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-embed-overview.html?context=wx&audience=wdp)\nfor a description of text embeddings.\n", "requestBody": { "required": true, "description": "The text input for a given model to be used to generate the embeddings.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingsRequest" }, "examples": { "request": { "summary": "A sample request.", "description": "A simple request.\n", "value": { "model_id": "slate", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "inputs": [ "Youth craves thrills while adulthood cherishes wisdom." ] } } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingsResponse" }, "examples": { "response": { "summary": "A sample response.", "description": "An array of embeddings for each input string.\n", "value": { "model_id": "slate", "results": [ { "embedding": [ -0.006929283, -0.005336422, -0.024047505 ] } ], "created_at": "2024-02-21T17:32:28Z", "input_token_count": 10 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.text-embeddings.send" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "generate embeddings", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v1/text/embeddings?version=2023-10-25'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Accept: application/json'\n", "-d '{\n", " \"inputs\": [\n", " \"Youth craves thrills while adulthood cherishes wisdom.\",\n", " \"Youth seeks ambition while adulthood finds contentment.\",\n", " \"Dreams chased in youth while goals pursued in adulthood.\"\n", " ],\n", " \"model_id\": \"slate\",\n", " \"project_id\": \"12ac4cf1-252f-424b-b52d-5cdd9814987f\"\n", "}'\n" ] } ] } ] } } } }, "/ml/v1/text/similarities": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "x-sdk-exclude": true, "operationId": "text_similarities", "x-cli-command": "similarities", "x-cli-command-group": "text", "tags": [ "Text Embeddings" ], "summary": "Detect text similarities", "description": "Detect similarities between source strings and target strings.\n", "requestBody": { "required": true, "description": "The strings to be used to detect text similarities.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimilarityRequest" }, "examples": { "request": { "summary": "A sample request.", "description": "A simple request.\n", "value": { "model_id": "slate", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "source_text": "Youth is not about wisdom, contentment, and pursuit of goals", "target_texts": [ "Youth craves thrills while adulthood cherishes wisdom.", "Youth seeks ambition while adulthood finds contentment.", "Dreams chased in youth while goals pursued in adulthood." ] } } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimilarityResponse" }, "examples": { "response": { "summary": "A sample response.", "description": "An array of similarity ratings for each source string.\n", "value": { "model_id": "slate", "results": [ { "score": 0.7527929544448853 }, { "score": 0.7988557815551758 }, { "score": 0.177557945251 } ], "created_at": "2024-02-21T17:32:28Z", "input_token_count": 14 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.text-similarities.send" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/text/rerank": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "text_rerank", "x-cli-command": "rerank", "x-cli-command-group": "text", "tags": [ "Text Rerank" ], "summary": "Generate rerank", "description": "Rerank texts based on some queries.\n", "requestBody": { "required": true, "description": "The input texts and the queries for reranking.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RerankRequest" }, "examples": { "sample request": { "summary": "A sample request.", "value": { "model_id": "cross-encoder/ms-marco-minilm-l-12-v2", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "inputs": [ { "text": "In my younger years, I often reveled in the excitement of spontaneous adventures and embraced the thrill of the unknown, whereas in my grownup life, I've come to appreciate the comforting stability of a well-established routine." }, { "text": "As a young man, I frequently sought out exhilarating experiences, craving the adrenaline rush of life's novelties, while as a responsible adult, I've come to understand the profound value of accumulated wisdom and life experience." } ], "query": "As a Youth, I craved excitement while in adulthood I followed Enthusiastic Pursuit.", "parameters": { "return_options": { "top_n": 2 } } } } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RerankResponse" }, "examples": { "response": { "summary": "A sample response.", "description": "An array of embeddings for each input string.\n", "value": { "model_id": "cross-encoder/ms-marco-minilm-l-12-v2", "results": [ { "index": 1, "score": 0.7461 }, { "index": 0, "score": 0.8274 } ], "created_at": "2024-02-21T17:32:28Z", "input_token_count": 20 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.text-rerank.send" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "sample request", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v1/text/rerank?version=2023-10-25'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Accept: application/json'\n", "-d ", "'{\n", " \"model_id\": \"cross-encoder/ms-marco-minilm-l-12-v2\",\n", " \"project_id\": \"12ac4cf1-252f-424b-b52d-5cdd9814987f\",\n", " \"inputs\": [\n", " {\n", " \"text\": \"In my younger years, I often reveled in the excitement of spontaneous adventures and embraced the thrill of the unknown, whereas in my grownup life, I've come to appreciate the comforting stability of a well-established routine.\"\n", " },\n", " {\n", " \"text\": \"As a young man, I frequently sought out exhilarating experiences, craving the adrenaline rush of life's novelties, while as a responsible adult, I've come to understand the profound value of accumulated wisdom and life experience.\"\n", " }\n", " ],\n", " \"query\": \"As a Youth, I craved excitement while in adulthood I followed Enthusiastic Pursuit.\",\n", " \"parameters\": {\n", " \"return_options\": {\n", " \"top_n\": 2\n", " }\n", " }\n", "}'\n" ] } ] } ] } } } }, "/ml/v1/geospatial/transformations": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "x-sdk-exclude": true, "operationId": "create_geospatial_transformation", "tags": [ "Geospatial (Private)" ], "summary": "Create a geospatial transformation", "description": "Create a geospatial transformation from inputs using a given model.\n", "requestBody": { "required": true, "description": "The details of the inputs to transform with the given model.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeospatialTransformationRequest" } } } }, "responses": { "201": { "description": "Created. The `Content-Location` header will contain the URI reference to the created resource.", "headers": { "Content-Location": { "description": "The location of the newly created resource.\n", "schema": { "type": "string", "description": "The location of the newly created resource.\n" } }, "Location": { "description": "The location of the newly created resource.\n", "schema": { "type": "string", "description": "The location of the newly created resource.\n" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeospatialTransformationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "Bearer": [] } ] }, "get": { "x-sdk-exclude": true, "operationId": "list_geospatial_transformations", "tags": [ "Geospatial (Private)" ], "summary": "Retrieve the geospatial transformation requests", "description": "Retrieve the list of geospatial transformation requests for the specified space or project.\n\nThis operation does not save the history, any requests that were deleted or purged\nwill not appear in this list.\n", "parameters": [ { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeospatialTransformationResources" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/geospatial/transformations/{id}": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/path_id" } ], "get": { "x-sdk-exclude": true, "operationId": "get_geospatial_transformation", "tags": [ "Geospatial (Private)" ], "summary": "Get a geospatial transformation", "description": "Get a geospatial transformation.\n", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeospatialTransformationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "Bearer": [] } ] }, "delete": { "x-sdk-exclude": true, "operationId": "delete_geospatial_transformation", "tags": [ "Geospatial (Private)" ], "summary": "Delete a geospatial transformation", "description": "Delete a geospatial transformation.\n", "responses": { "204": { "description": "Deleted." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/autoai/rags": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "create_autoai_rags", "x-cli-command": "create", "x-cli-command-group": "autoai-rag", "tags": [ "AutoAI RAG" ], "summary": "Create a new AutoAI RAG run", "description": "Create a new AutoAI RAG that will find the best RAG pattern from the data that is provided in the request.\n", "requestBody": { "required": true, "description": "The details of the AutoAI RAG run with the data used to find the best RAG patterns.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoAIRAGRequest" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoAIRAGResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Create AutoAI RAG job", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v1/autoai/rags?version=2023-10-25'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "-d '{\n", " \"name\": \"AutoAI RAG #1\",\n", " \"description\": \"My autorag experiment for 2023 financial documents.\",\n", " \"hardware_spec\":{\n", " \"id\": \"c076e82c-b2a7-4d20-9c0f-1f0c2fdf5a24\",\n", " \"name\": \"L\"\n", " },\n", " \"parameters\":{\n", " \"constraints\":{\n", " \"embedding_models\": [\"ibm/slate.30m.english.rtrvr\", \"ibm/slate.125m.english.rtrvr\"],\n", " \"max_number_of_rag_patterns\": 8\n", " },\n", " \"optimization\":{\n", " \"metrics\":[\"answer_correctness\"]\n", " },\n", " \"output_logs\": true\n", " },\n", " \"input_data_references\":[\n", " {\n", " \"type\": \"connection_asset\",\n", " \"connection\": {\n", " \"id\": \"d118eb8c-b0da-44f4-abf4-c4ecba4a496a\"\n", " },\n", " \"location\":{\n", " \"bucket\": \"autorag-documents-datasets\",\n", " \"file_name\": \"docs/document_1.txt\"\n", " }\n", " },\n", " {\n", " \"type\": \"connection_asset\",\n", " \"connection\": {\n", " \"id\": \"d118eb8c-b0da-44f4-abf4-c4ecba4a496a\"\n", " },\n", " \"location\":{\n", " \"bucket\": \"autorag-documents-datasets\",\n", " \"file_name\": \"docs/document_2.txt\"\n", " }\n", " },\n", " ],\n", " \"test_data_references\":[\n", " {\n", " \"type\": \"connection_asset\",\n", " \"connection\": {\n", " \"id\": \"d118eb8c-b0da-44f4-abf4-c4ecba4a496a\"\n", " },\n", " \"location\":{\n", " \"bucket\": \"autorag-documents-datasets\",\n", " \"file_name\": \"benchmarks/q_and_a_data.json\"\n", " }\n", " }\n", " ],\n", " \"vector_store_references\":[\n", " {\n", " \"type\": \"connection_asset\",\n", " \"connection\": {\n", " \"id\": \"497956b8-626f-4800-901d-3bcba21c6770\"\n", " }\n", " }\n", " ],\n", " \"results_reference\": {\n", " \"type\": \"container\",\n", " \"connection\": {\n", " },\n", " \"location\": {\n", " \"path\": \"results_autoai\"\n", " }\n", " },\n", " \"project_id\": \"12ac4cf1-252f-424b-b52d-5cdd9814987f\"\n", "}'\n" ] } ] } ] } } }, "get": { "operationId": "list_autoai_rags", "x-cli-command": "list", "x-cli-command-group": "autoai-rag", "tags": [ "AutoAI RAG" ], "summary": "Retrieve the AutoAI RAG runs", "description": "Retrieve the list of AutoAI RAG requests for the specified space or project.\n\nThis operation does not save the history, any requests that were deleted or purged\nwill not appear in this list.\n", "parameters": [ { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoRAGResultResources" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Retrieve the AutoAI RAG runs", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v1/autoai/rags?version=2023-10-25'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Accept: application/json'\n" ] } ] } ] } } } }, "/ml/v1/autoai/rags/{id}": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/path_id" }, { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" } ], "get": { "operationId": "get_autoai_rags", "x-cli-command": "get", "x-cli-command-group": "autoai-rag", "tags": [ "AutoAI RAG" ], "summary": "Get an AutoAI RAG run", "description": "Get the results of an AutoAI RAG run, or details if the job failed.\n", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoAIRAGResponse" }, "examples": { "response": { "summary": "A sample response.", "value": { "metadata": { "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "created_at": "2023-05-02T16:27:51Z", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "description": "My autoai rag experiment for 2023 financial documents", "name": "AutoAI RAG" }, "entity": { "timestamp": "2023-09-22T02:52:03.324Z", "hardware_spec": { "id": "c076e82c-b2a7-4d20-9c0f-1f0c2fdf5a24", "name": "L" }, "parameters": { "constraints": { "embedding_models": [ "ibm/slate-125m-english-rtrvr" ], "generation": { "foundation_models": [ { "model_id": "meta-llama/llama-3-3-70b-instruct\"," }, { "model_id": "mistralai/mixtral-8x7b-instruct-v01" } ] }, "max_number_of_rag_patterns": 8 }, "optimization": { "metrics": [ "answer_correctness" ] }, "output_logs": true }, "input_data_references": [ { "type": "connection_asset", "connection": { "id": "6f5688fd-f3bf-42c2-a18b-49c0d8a1920d" }, "location": { "path": "files/document.pdf" } } ], "test_data_references": [ { "type": "connection_asset", "connection": { "id": "6f5688fd-f3bf-42c2-a18b-49c0d8a1920d" }, "location": { "path": "files/qa_document.json" } } ], "vector_store_references": [ { "type": "connection_asset", "connection": { "id": "6f5688fd-f3bf-42c2-a18b-49c0d8a1920d" } } ], "results_reference": { "type": "container", "location": { "path": "results_autoai", "training": "results_autoai/6a9362f6-7ea2-4419-8c7d-a7e07432dec5", "training_status": "results_autoai/6a9362f6-7ea2-4419-8c7d-a7e07432dec5/rag/training-status.json", "assets_path": "results_autoai/6a9362f6-7ea2-4419-8c7d-a7e07432dec5/rag/assets", "training_log": "results_autoai/6a9362f6-7ea2-4419-8c7d-a7e07432dec5/rag/training.log" } }, "results": [ { "metrics": { "test_data": [ { "metric_name": "answer_correctness", "mean": 0.51, "ci_high": 0.68, "ci_low": 0.43 } ] }, "context": { "rag_pattern": { "composition_steps": [ "vector_store", "chunking", "embeddings", "retrieval", "generation" ], "location": { "evaluation_results": "results_autoai/6a9362f6-7ea2-4419-8c7d-a7e07432dec5/rag/assets/Pattern1/evaluation_results.json", "indexing_notebook": "results_autoai/6a9362f6-7ea2-4419-8c7d-a7e07432dec5/rag/assets/Pattern1/indexing_notebook.ipynb", "inference_notebook": "results_autoai/6a9362f6-7ea2-4419-8c7d-a7e07432dec5/rag/assets/Pattern1/inference_notebook.ipynb", "inference_service_code": "results_autoai/6a9362f6-7ea2-4419-8c7d-a7e07432dec5/rag/assets/Pattern1/inference_service_code.gz", "inference_service_metadata": "results_autoai/6a9362f6-7ea2-4419-8c7d-a7e07432dec5/rag/assets/Pattern1/inference_service_metadata.json" }, "name": "Pattern 1", "settings": { "vector_store": { "datasource_type": "milvus", "index_name": "autoai_rag_1234_iteration_5_index", "distance_metric": "euclidean", "operation": "upsert", "schema": { "id": "autoai_rag_1.0.0", "name": "AutoAI RAG document schema", "type": "struct", "fields": [ { "name": "text", "description": "text field", "type": "string", "role": "text" }, { "name": "document_id", "description": "document name field", "type": "string", "role": "document_name" }, { "name": "start_index", "description": "chunk starting token position in the source document", "type": "number", "role": "start_index" }, { "name": "sequence_number", "description": "chunk number per document", "type": "number", "role": "sequence_number" }, { "name": "vector", "description": "vector embeddings", "type": "array", "role": "vector_embeddings" } ] } }, "chunking": { "method": "recursive", "chunk_size": 256, "chunk_overlap": 64 }, "embeddings": { "truncate_strategy": "left", "truncate_input_tokens": 384, "model_id": "ibm/slate-125m-english-rtrvr" }, "retrieval": { "method": "simple", "number_of_chunks": 5 }, "generation": { "model_id": "meta-llama/llama-3-1-70b-instruct", "prompt_template_text": "Answer the following questions based on provided context:\\n ...", "context_template_text": "[Document]\n{document}\n[End]", "word_to_token_ratio": 2.2 } } }, "iteration": 1, "max_combinations": 160 } } ], "status": { "state": "running", "step": "vector_store", "message": { "level": "info", "text": "Pipeline 1 of 8 is completed." }, "running_at": "2023-08-04T13:22:48.000Z" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Get an AutoAI RAG run", "example": [ { "type": "code", "source": [ "curl --request GET \"https://{cluster_url}/ml/v1/autoai/rags/{id}?space_id=12ac4cf1-252f-424b-b52d-5cdd9814987f&version=2024-10-17\"\n", "-H \"Authorization: Bearer eyJhbGciOiJSUzUxM...\"", "-H 'Accept: application/json'\n" ] } ] } ] } } }, "delete": { "operationId": "delete_autoai_rags", "x-cli-command": "delete", "x-cli-command-group": "autoai-rag", "tags": [ "AutoAI RAG" ], "summary": "Cancel or delete an AutoAI RAG run", "description": "Cancel or delete the specified AutoAI RAG run, once deleted all trace of the run job is gone.\n", "parameters": [ { "$ref": "#/components/parameters/hard_delete" } ], "responses": { "204": { "description": "Deleted." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Cancel or delete an AutoAI RAG run", "example": [ { "type": "code", "source": [ "curl --request DELETE \"https://{cluster_url}/ml/v1/autoai/rags/{id}?space_id=12ac4cf1-252f-424b-b52d-5cdd9814987f&version=2024-10-17\"\n", "-H \"Authorization: Bearer eyJhbGciOiJSUzUxM...\"" ] } ] } ] } } } }, "/ml/v1/fine_tunings": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "create_fine_tuning", "x-cli-command": "create", "x-cli-command-group": "fine-tuning", "tags": [ "Fine Tunings (Beta)" ], "summary": "Create a fine tuning job", "description": "Create a fine tuning job that will fine tune an LLM.\n", "requestBody": { "required": true, "description": "The details of the fine tuning job with the data used to tune the LLM.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FineTuningRequest" }, "examples": { "lora finetune container": { "$ref": "#/components/examples/LoraFineTuningContainerRequest" }, "qlora finetune connection": { "$ref": "#/components/examples/QLoraFineTuningConnectionAssetRequest" } } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FineTuningResource" }, "examples": { "lora finetune container": { "$ref": "#/components/examples/LoraFineTuningContainerResponse" }, "qlora finetune connection": { "$ref": "#/components/examples/QLoraFineTuningConnectionAssetResponse" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.fine-tuning.create" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Lora Fine Tuning With Container", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v1/fine_tunings?version=2024-05-16'\n", "-H 'Authorization: Bearer eyJraWQiOiIyMDI1MDcxOT...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "-d '{\n", " \"project_id\": \"dbbbfd33-1cca-4c6b-a9fa-c939b5f611eb\",\n", " \"name\": \"Example - Lora fine tuning\",\n", " \"auto_update_model\": true,\n", " \"parameters\": {\n", " \"base_model\": {\"model_id\": \"meta-llama/llama-3-1-8b\"},\n", " \"task_id\": \"classification\",\n", " \"accumulate_steps\": 1,\n", " \"num_epochs\": 10,\n", " \"learning_rate\": 0.00005,\n", " \"batch_size\": 16,\n", " \"max_seq_length\": 2048,\n", " \"response_template\": \"\n### Response:\",\n", " \"verbalizer\": \"### Input: {{input}} \n\n### Response: {{output}}\",\n", " \"gpu\": {\"num\": 1},\n", " \"peft_parameters\": {\n", " \"type\": \"lora\",\n", " \"rank\": 16,\n", " \"target_modules\": [\"all-linear\"],\n", " \"lora_alpha\": 32,\n", " \"lora_dropout\": 0.05\n", " },\n", " \"gradient_checkpointing\": true\n", " },\n", " \"results_reference\": {\n", " \"connection\": {},\n", " \"location\": {\"path\": \"fine-tuning/experiment1\"},\n", " \"type\": \"container\"\n", " },\n", " \"training_data_references\": [\n", " {\n", " \"connection\": {},\n", " \"location\": {\n", " \"id\": \"69f07f10-ccfa-4137-816c-7a781f8c6b74\",\n", " \"href\": \"https://{cluster_url}/v2/assets/69f07f10-ccfa-4137-816c-7a781f8c6b74?project_id=dbbbfd33-1cca-4c6b-a9fa-c939b5f611eb\"\n", " },\n", " \"type\": \"data_asset\"\n", " }\n", " ]\n", "}'\n" ] } ] }, { "name": "QLora Fine Tuning With Connection Asset", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v1/fine_tunings?version=2024-05-16'\n", "-H 'Authorization: Bearer eyJraWQiOiIyMDI1MDcxOT...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "-d '{\n", " \"project_id\": \"dbbbfd33-1cca-4c6b-a9fa-c939b5f611eb\",\n", " \"name\": \"Example - QLora fine tuning\",\n", " \"auto_update_model\": false,\n", " \"parameters\": {\n", " \"base_model\" : {\"model_id\": \"meta-llama/llama-3-1-70b-gptq\"},\n", " \"peft_parameters\": {\"type\": \"qlora\"}\n", " },\n", " \"results_reference\": {\n", " \"connection\": {\"id\": \"c4225076-74fa-4033-bf93-1183a9b6c611\"},\n", " \"location\": {\n", " \"bucket\": \"ftys1prod-donotdelete-pr-fegvx5zvy5ob8q\",\n", " \"path\" : \"fine-tuning/experiment2\"\n", " },\n", " \"type\": \"connection_asset\"\n", " },\n", " \"training_data_references\": [\n", " {\n", " \"connection\": {},\n", " \"location\": {\n", " \"id\": \"69f07f10-ccfa-4137-816c-7a781f8c6b74\",\n", " \"href\": \"https://{cluster_url}/v2/assets/69f07f10-ccfa-4137-816c-7a781f8c6b74?project_id=dbbbfd33-1cca-4c6b-a9fa-c939b5f611eb\"\n", " },\n", " \"type\": \"data_asset\"\n", " }\n", " ]\n", "}'\n" ] } ] } ] } } }, "get": { "operationId": "fine_tuning_list", "x-cli-command": "list", "x-cli-command-group": "fine-tuning", "tags": [ "Fine Tunings (Beta)" ], "summary": "Retrieve the list of fine tuning jobs", "description": "Retrieve the list of fine tuning jobs for the specified space or project.\n", "parameters": [ { "$ref": "#/components/parameters/start" }, { "name": "limit", "description": "How many resources should be returned.\n", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 200 } }, { "name": "total_count", "description": "Compute the total count. May have performance impact.", "in": "query", "schema": { "type": "boolean" } }, { "name": "tag.value", "description": "Return only the resources with the given tag value.", "in": "query", "schema": { "type": "string" } }, { "name": "state", "description": "Filter based on on the job state: queued, running, completed, failed etc.\n", "in": "query", "schema": { "type": "string" } }, { "name": "type", "description": "The `type` of Fine Tuning training. The `type` is set to `ilab` for InstructLab training.", "in": "query", "schema": { "type": "string", "enum": [ "ilab" ] } }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FineTuningResources" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.fine-tuning.list" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/fine_tunings/{id}": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/path_id" }, { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" } ], "get": { "operationId": "get_fine_tuning", "x-cli-command": "get", "x-cli-command-group": "fine-tuning", "tags": [ "Fine Tunings (Beta)" ], "summary": "Get a fine tuning job", "description": "Get the results of a fine tuning job, or details if the job failed.\n", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FineTuningResource" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.fine-tuning.get" } ] }, "security": [ { "Bearer": [] } ] }, "delete": { "operationId": "delete_fine_tuning", "x-cli-command": "delete", "x-cli-command-group": "fine-tuning", "tags": [ "Fine Tunings (Beta)" ], "summary": "Cancel or delete a fine tuning job", "description": "Delete a fine tuning job if it exists, once deleted all trace of the job is gone.\n", "parameters": [ { "name": "hard_delete", "description": "Set to true in order to also delete the job and request metadata.", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "204": { "description": "Deleted." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.fine-tuning.delete" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/text/extractions": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "text_extraction", "x-cli-command": "create", "x-cli-command-group": "text-extraction", "tags": [ "Text Extraction" ], "summary": "Start a text extraction request", "description": "Start a request to extract text and metadata from documents.\n\nSee the [documentation](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-api-text-extraction.html?context=wx&audience=wdp) for a description of text extraction.\n", "requestBody": { "required": true, "description": "The input for the text extraction request.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextExtractionRequest" }, "examples": { "simple request": { "summary": "simple_request", "description": "A simple request.\n", "value": { "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "document_reference": { "type": "connection_asset", "connection": { "id": "6f5688fd-f3bf-42c2-a18b-49c0d8a1920d" }, "location": { "file_name": "files/document.pdf" } }, "results_reference": { "type": "connection_asset", "connection": { "id": "2a7c11bc-2913-48d0-9581-a8d9f40fa159" }, "location": { "file_name": "results" } } } }, "container request": { "summary": "container_request", "description": "A simple request with docuemt and result reference to container.\n", "value": { "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "document_reference": { "type": "container", "location": { "path": "files/document.pdf" } }, "results_reference": { "type": "container", "location": { "path": "results/" } }, "parameters": { "requested_outputs": [ "assembly" ], "mode": "high_quality", "ocr_mode": "enabled", "languages": [ "latn" ] } } }, "ocr request": { "summary": "ocr_request", "description": "An OCR request.\n", "value": { "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "document_reference": { "type": "connection_asset", "connection": { "id": "6f5688fd-f3bf-42c2-a18b-49c0d8a1920d" }, "location": { "file_name": "files/document.pdf" } }, "results_reference": { "type": "connection_asset", "connection": { "id": "2a7c11bc-2913-48d0-9581-a8d9f40fa159" }, "location": { "file_name": "results" } }, "parameters": { "ocr_mode": "enabled" } } }, "multiple outputs": { "summary": "Multiple outputs", "description": "A request for multiple outputs.\n", "value": { "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "document_reference": { "type": "connection_asset", "connection": { "id": "6f5688fd-f3bf-42c2-a18b-49c0d8a1920d" }, "location": { "file_name": "files/document.pdf" } }, "results_reference": { "type": "connection_asset", "connection": { "id": "2a7c11bc-2913-48d0-9581-a8d9f40fa159" }, "location": { "file_name": "results" } }, "parameters": { "requested_outputs": [ "assembly", "md" ], "mode": "high_quality", "ocr_mode": "enabled" } } } } } } }, "responses": { "201": { "description": "Created. The `Content-Location` header will contain the URI reference to the created resource.", "headers": { "Content-Location": { "description": "The location of the newly created resource.\n", "schema": { "type": "string", "description": "The location of the newly created resource.\n" } }, "Location": { "description": "The location of the newly created resource.\n", "schema": { "type": "string", "description": "The location of the newly created resource.\n" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextExtractionResponse" }, "examples": { "simple response": { "summary": "A simple response.", "value": { "metadata": { "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "created_at": "2023-05-02T16:27:51Z", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "name": "extract" }, "entity": { "document_reference": { "type": "connection_asset", "connection": { "id": "6f5688fd-f3bf-42c2-a18b-49c0d8a1920d" }, "location": { "file_name": "files/document.pdf" } }, "results_reference": { "type": "connection_asset", "connection": { "id": "2a7c11bc-2913-48d0-9581-a8d9f40fa159" }, "location": { "file_name": "results" } }, "results": { "status": "submitted", "number_pages_processed": 0 } } } }, "container response": { "summary": "A container response.", "value": { "metadata": { "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "created_at": "2023-05-02T16:27:51Z", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "name": "extract" }, "entity": { "document_reference": { "type": "container", "location": { "path": "files/document.pdf" } }, "results_reference": { "type": "container", "location": { "path": "results/" } }, "parameters": { "requested_outputs": [ "assembly" ], "mode": "high_quality", "ocr_mode": "enabled" }, "results": { "status": "submitted", "number_pages_processed": 0 } } } }, "ocr response": { "summary": "An OCR response.", "value": { "metadata": { "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "created_at": "2023-05-02T16:27:51Z", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "name": "extract" }, "entity": { "document_reference": { "type": "connection_asset", "connection": { "id": "6f5688fd-f3bf-42c2-a18b-49c0d8a1920d" }, "location": { "file_name": "files/document.pdf" } }, "results_reference": { "type": "connection_asset", "connection": { "id": "2a7c11bc-2913-48d0-9581-a8d9f40fa159" }, "location": { "file_name": "results" } }, "parameters": { "ocr_mode": "enabled" }, "results": { "status": "submitted", "number_pages_processed": 0 } } } }, "multiple outputs": { "summary": "Multiple outputs.", "value": { "metadata": { "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "created_at": "2023-05-02T16:27:51Z", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "name": "extract" }, "entity": { "document_reference": { "type": "connection_asset", "connection": { "id": "6f5688fd-f3bf-42c2-a18b-49c0d8a1920d" }, "location": { "file_name": "files/document.pdf" } }, "results_reference": { "type": "connection_asset", "connection": { "id": "2a7c11bc-2913-48d0-9581-a8d9f40fa159" }, "location": { "file_name": "results" } }, "parameters": { "requested_outputs": [ "assembly", "md" ], "mode": "high_quality", "ocr_mode": "enabled" }, "results": { "status": "submitted", "number_pages_processed": 0 } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.text-extraction.send" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "simple request", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v1/text/extractions?version=2023-10-25'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "-d ", "'{\n", " \"project_id\": \"12ac4cf1-252f-424b-b52d-5cdd9814987f\",\n", " \"document_reference\": {\n", " \"type\": \"connection_asset\",\n", " \"connection\": {\n", " \"id\": \"6f5688fd-f3bf-42c2-a18b-49c0d8a1920d\"\n", " },\n", " \"location\": {\n", " \"file_name\": \"files/document.pdf\"\n", " }\n", " },\n", " \"results_reference\": {\n", " \"type\": \"connection_asset\",\n", " \"connection\": {\n", " \"id\": \"2a7c11bc-2913-48d0-9581-a8d9f40fa159\"\n", " },\n", " \"location\": {\n", " \"file_name\": \"results\"\n", " }\n", " },\n", " \"steps\": {\n", " \"tables_processing\": {\n", " \"enabled\": true\n", " }\n", " }\n", "}'\n" ] } ] }, { "name": "ocr request", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v1/text/extractions?version=2023-10-25'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "-d ", "'{\n", " \"project_id\": \"12ac4cf1-252f-424b-b52d-5cdd9814987f\",\n", " \"document_reference\": {\n", " \"type\": \"connection_asset\",\n", " \"connection\": {\n", " \"id\": \"6f5688fd-f3bf-42c2-a18b-49c0d8a1920d\"\n", " },\n", " \"location\": {\n", " \"file_name\": \"files/document.pdf\"\n", " }\n", " },\n", " \"results_reference\": {\n", " \"type\": \"connection_asset\",\n", " \"connection\": {\n", " \"id\": \"2a7c11bc-2913-48d0-9581-a8d9f40fa159\"\n", " },\n", " \"location\": {\n", " \"file_name\": \"results\"\n", " }\n", " },\n", " \"steps\": {\n", " \"ocr\": {\n", " \"languages_list\": [\n", " \"en\"\n", " ]\n", " },\n", " \"tables_processing\": {\n", " \"enabled\": false\n", " }\n", " }\n", "}'\n" ] } ] }, { "name": "multiple outputs", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v1/text/extractions?version=2023-10-25'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "-d ", "'{\n", " \"project_id\": \"12ac4cf1-252f-424b-b52d-5cdd9814987f\",\n", " \"document_reference\": {\n", " \"type\": \"connection_asset\",\n", " \"connection\": {\n", " \"id\": \"6f5688fd-f3bf-42c2-a18b-49c0d8a1920d\"\n", " },\n", " \"location\": {\n", " \"file_name\": \"files/document.pdf\"\n", " }\n", " },\n", " \"results_reference\": {\n", " \"type\": \"connection_asset\",\n", " \"connection\": {\n", " \"id\": \"2a7c11bc-2913-48d0-9581-a8d9f40fa159\"\n", " },\n", " \"location\": {\n", " \"file_name\": \"results\"\n", " }\n", " },\n", " \"parameters\": {\n", " \"requested_outputs\": [\n", " \"assembly\",\n", " \"md\"\n", " ],\n", " \"mode\": \"high_quality\",\n", " \"ocr_mode\": \"enabled\"\n", " }\n", "}'\n" ] } ] } ] } } }, "get": { "operationId": "list_text_extractions", "x-cli-command": "list", "x-cli-command-group": "text-extraction", "tags": [ "Text Extraction" ], "summary": "Retrieve the text extraction requests", "description": "Retrieve the list of text extraction requests for the specified space or project.\n\nThis operation does not save the history, any requests that were deleted or purged\nwill not appear in this list.\n", "parameters": [ { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextExtractionResources" }, "examples": { "get_all_resources": { "summary": "Get all text extraction requests.", "value": { "limit": 10, "first": { "href": "https://us-south.ml.cloud.ibm.com/ml/v1/text_extractions" }, "resources": [ { "metadata": { "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "created_at": "2023-05-02T16:27:51Z", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "name": "extract" }, "entity": { "document_reference": { "type": "connection_asset", "connection": { "id": "6f5688fd-f3bf-42c2-a18b-49c0d8a1920d" }, "location": { "file_name": "files/document.pdf" } }, "results_reference": { "type": "connection_asset", "connection": { "id": "2a7c11bc-2913-48d0-9581-a8d9f40fa159" }, "location": { "file_name": "results" } }, "results": { "status": "completed", "number_pages_processed": 3, "running_at": "2023-05-02T16:28:03Z", "completed_at": "2023-05-02T16:29:31Z" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.text-extraction.list" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/text/extractions/{id}": { "servers": [], "parameters": [ { "name": "id", "in": "path", "description": "The identifier of the extraction request.", "schema": { "type": "string" }, "required": true }, { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" } ], "get": { "operationId": "text_extraction_get", "x-cli-command": "get", "x-cli-command-group": "text-extraction", "tags": [ "Text Extraction" ], "summary": "Get the results of the request", "description": "Retrieve the text extraction request with the specified identifier.\n\nNote that there is a retention period of 2 days. If this retention\nperiod is exceeded then the request will be deleted and the results\nno longer available. In this case this operation will return `404`.\n", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextExtractionResponse" }, "examples": { "response": { "summary": "A sample response.", "value": { "metadata": { "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "created_at": "2023-05-02T16:27:51Z", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "name": "extract" }, "entity": { "document_reference": { "type": "connection_asset", "connection": { "id": "6f5688fd-f3bf-42c2-a18b-49c0d8a1920d" }, "location": { "file_name": "files/document.pdf" } }, "results_reference": { "type": "connection_asset", "connection": { "id": "2a7c11bc-2913-48d0-9581-a8d9f40fa159" }, "location": { "file_name": "results" } }, "steps": { "tables_processing": { "enabled": true } }, "results": { "status": "running", "number_pages_processed": 2, "running_at": "2023-05-02T16:28:03Z" } } } }, "ocr response": { "summary": "An ocr response.", "value": { "metadata": { "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "created_at": "2023-05-02T16:27:51Z", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "name": "extract" }, "entity": { "document_reference": { "type": "connection_asset", "connection": { "id": "6f5688fd-f3bf-42c2-a18b-49c0d8a1920d" }, "location": { "file_name": "files/document.pdf" } }, "results_reference": { "type": "connection_asset", "connection": { "id": "2a7c11bc-2913-48d0-9581-a8d9f40fa159" }, "location": { "file_name": "results" } }, "steps": { "ocr": { "languages_list": [ "en", "fr" ] }, "tables_processing": { "enabled": false } }, "results": { "status": "submitted", "number_pages_processed": 0 } } } }, "multiple outputs": { "summary": "Multiple outputs.", "value": { "metadata": { "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "created_at": "2023-05-02T16:27:51Z", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "name": "extract" }, "entity": { "document_reference": { "type": "connection_asset", "connection": { "id": "6f5688fd-f3bf-42c2-a18b-49c0d8a1920d" }, "location": { "file_name": "files/document.pdf" } }, "results_reference": { "type": "connection_asset", "connection": { "id": "2a7c11bc-2913-48d0-9581-a8d9f40fa159" }, "location": { "file_name": "results" } }, "parameters": { "requested_outputs": [ "assembly", "md" ], "mode": "high_quality", "ocr_mode": "enabled" }, "results": { "status": "running", "number_pages_processed": 2, "running_at": "2023-05-02T16:28:03Z" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.text-extraction.get" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "get results", "example": [ { "type": "code", "source": [ "curl --request GET 'https://{cluster_url}/ml/v1/text/extractions/{id}?version=2023-10-25&project_id=12ac4cf1-252f-424b-b52d-5cdd9814987f'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Accept: application/json'\n" ] } ] } ] } } }, "delete": { "operationId": "text_extraction_delete", "x-cli-command": "delete", "x-cli-command-group": "text-extraction", "parameters": [ { "$ref": "#/components/parameters/hard_delete" } ], "tags": [ "Text Extraction" ], "summary": "Delete the request", "description": "Cancel the specified text extraction request and delete any associated results.\n", "responses": { "204": { "description": "Request deleted." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.text-extraction.delete" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "delete results", "example": [ { "type": "code", "source": [ "curl --request DELETE 'https://{cluster_url}/ml/v1/text/extractions/{id}?version=2023-10-25&project_id=12ac4cf1-252f-424b-b52d-5cdd9814987f'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n" ] } ] } ] } } } }, "/ml/v1/text/image": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "text_image", "x-cli-command": "image", "x-cli-command-group": "text", "x-sdk-exclude": true, "tags": [ "Text To Image" ], "summary": "Create an image", "description": "Create an image from a textual description.\n\nSee the [documentation](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/TBD?context=wx&audience=wdp)\nfor a description of image generation.\n", "requestBody": { "required": true, "description": "The input for the image generation request.\n\nSet the HTTP header `Accept: image/png` in order to get the image in `png` format.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextImageRequest" }, "examples": { "request": { "summary": "A sample request.", "description": "A simple request.\n", "value": { "model_id": "stable-diffusion-xl-1024-v1-0", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "input": "Create an image of a sunset.", "parameters": { "height": 1024, "width": 1024 } } } } } } }, "responses": { "200": { "description": "Ok.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.text-image.send" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/chat/completions": { "servers": [], "post": { "operationId": "chat_completions", "x-cli-command": "chat", "x-cli-command-group": "text", "tags": [ "Text Chat" ], "summary": "Chat Completions", "description": "Infer the next tokens for a given deployed model with a set of PARAMS1.\n\nIf `stream` is true, this operation will return the output tokens in a server-sent events (SSE) stream.\n", "requestBody": { "required": true, "description": "From a given prompt, infer the next tokens.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionsRequest" }, "examples": { "chat completions": { "summary": "chat_completions", "description": "A chat example.\n", "value": { "model": "meta-llama/llama-3-8b-instruct", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "Who won the world series in 2020?" }, { "role": "assistant", "content": "The Los Angeles Dodgers won the World Series in 2020." }, { "role": "user", "content": { "type": "text", "text": "Where was it played?" } } ], "max_tokens": 100, "temperature": 0, "time_limit": 1000 } }, "tool call": { "summary": "tool_call", "description": "A tool calling example.\n", "value": { "model": "meta-llama/llama-3-8b-instruct", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "messages": [ { "role": "user", "content": { "type": "text", "text": "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": { "description": "The city, e.g. San Francisco, CA", "type": "string" }, "unit": { "enum": [ "celsius", "fahrenheit" ], "type": "string" } }, "required": [ "location" ] } } } ], "tool_choice": { "type": "function", "function": { "name": "get_current_weather", "description": "Get the current weather for a location.\nCall this whenever you need to know the weather,\nor for example when a customer asks 'What is the weather like in New York'\n" } } } }, "json mode": { "summary": "json_mode", "description": "A chat example with json output.\n", "value": { "model": "meta-llama/llama-3-8b-instruct", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "response_format": { "type": "json_object" }, "messages": [ { "role": "system", "content": "You are a helpful assistant designed to output JSON." }, { "role": "user", "content": { "type": "text", "text": "Who won the world series in 2020?" } } ] } } } } } }, "responses": { "200": { "description": "Successful operation. `Content-Type: text/event-stream` if `stream` is true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextChatResponse" }, "examples": { "chat completions": { "summary": "chat_completions", "description": "A chat example.\n", "value": { "id": "cmpl-15475d0dea9b4429a55843c77997f8a9", "model": "meta-llama/llama-3-8b-instruct", "model_id": "meta-llama/llama-3-8b-instruct", "created": 1689958352, "created_at": "2023-07-21T16:52:32.190Z", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "The 2020 World Series was played at Globe Life Field in Arlington, Texas,\nwhich is the home stadium of the Texas Rangers.\nHowever, the series was played with no fans in attendance due to the COVID-19 pandemic.\n" }, "finish_reason": "stop" } ], "usage": { "completion_tokens": 47, "prompt_tokens": 59, "total_tokens": 106 } } }, "tool call": { "summary": "tool_call", "description": "A tool calling example.\n", "value": { "id": "cmpl-15475d0dea9b4429a55843c77997f8a9", "model": "meta-llama/llama-3-8b-instruct", "model_id": "meta-llama/llama-3-8b-instruct", "created": 1689958352, "created_at": "2023-07-21T16:52:32.190Z", "choices": [ { "index": 0, "message": { "role": "assistant", "tool_calls": [ { "id": "chatcmpl-tool-ef093f0cbbff4c6a973aa0873f73fc99", "type": "function", "function": { "name": "get_current_weather", "arguments": "{\n \"location\": \"Boston, MA\",\n \"unit\": \"fahrenheit\"\n}\n" } } ] }, "finish_reason": "stop" } ], "usage": { "completion_tokens": 18, "prompt_tokens": 19, "total_tokens": 37 } } }, "json mode": { "summary": "json_mode", "description": "A chat example with json output.\n", "value": { "id": "cmpl-09945b25c805491fb49e15439b8e5d84", "model": "meta-llama/llama-3-8b-instruct", "model_id": "meta-llama/llama-3-8b-instruct", "created": 1689958352, "created_at": "2023-07-21T16:52:32.190Z", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "[\"The Los Angeles Dodgers won the World Series in 2020. They defeated the Tampa Bay Rays in six games.\"]" }, "finish_reason": "stop" } ], "usage": { "completion_tokens": 35, "prompt_tokens": 20, "total_tokens": 55 } } } } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/TextChatStreamResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "chat-completions.send" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/text/chat": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "text_chat", "x-cli-command": "chat", "x-cli-command-group": "text", "tags": [ "Text Chat" ], "summary": "Infer text", "description": "Infer the next tokens for a given deployed model with a set of PARAMS2.\n\nYou can also use [/v1/chat/completions](#chat_completions)\nto achieve the same result.\n", "requestBody": { "required": true, "description": "From a given prompt, infer the next tokens.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextChatRequest" }, "examples": { "text chat": { "summary": "text_chat", "description": "A text chat example.\n", "value": { "model_id": "meta-llama/llama-3-8b-instruct", "project_id": "63dc4cf1-252f-424b-b52d-5cdd9814987f", "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "Who won the world series in 2020?" }, { "role": "assistant", "content": "The Los Angeles Dodgers won the World Series in 2020." }, { "role": "user", "content": { "type": "text", "text": "Where was it played?" } } ], "max_tokens": 100, "temperature": 0, "time_limit": 1000 } }, "tool call": { "summary": "tool_call", "description": "A tool calling example.\n", "value": { "model_id": "meta-llama/llama-3-8b-instruct", "project_id": "63dc4cf1-252f-424b-b52d-5cdd9814987f", "messages": [ { "role": "user", "content": { "type": "text", "text": "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": { "description": "The city, e.g. San Francisco, CA", "type": "string" }, "unit": { "enum": [ "celsius", "fahrenheit" ], "type": "string" } }, "required": [ "location" ] } } } ], "tool_choice": { "type": "function", "function": { "name": "get_current_weather", "description": "Get the current weather for a location.\nCall this whenever you need to know the weather,\nor for example when a customer asks 'What is the weather like in New York'\n" } } } }, "json mode": { "summary": "json_mode", "description": "A text chat example with json output.\n", "value": { "model_id": "meta-llama/llama-3-8b-instruct", "project_id": "63dc4cf1-252f-424b-b52d-5cdd9814987f", "response_format": { "type": "json_object" }, "messages": [ { "role": "system", "content": "You are a helpful assistant designed to output JSON." }, { "role": "user", "content": { "type": "text", "text": "Who won the world series in 2020?" } } ] } }, "moderations_request": { "summary": "moderations_request", "description": "A text chat example with moderations.\n", "value": { "model_id": "meta-llama/llama-3-8b-instruct", "project_id": "63dc4cf1-252f-424b-b52d-5cdd9814987f", "messages": [ { "role": "user", "content": { "type": "text", "text": "Tell me how to reach the US Postal service" } } ], "max_tokens": 120, "temperature": 0, "moderations": { "hap": { "input": { "enabled": true, "threshold": 0.5 }, "output": { "enabled": true, "threshold": 0.5 } }, "pii": { "input": { "enabled": true }, "output": { "enabled": true } } } } } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextChatResponse" }, "examples": { "text chat": { "summary": "text_chat", "description": "A text chat example.\n", "value": { "id": "cmpl-15475d0dea9b4429a55843c77997f8a9", "model_id": "meta-llama/llama-3-8b-instruct", "created": 1689958352, "created_at": "2023-07-21T16:52:32.190Z", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "The 2020 World Series was played at Globe Life Field in Arlington, Texas,\nwhich is the home stadium of the Texas Rangers.\nHowever, the series was played with no fans in attendance due to the COVID-19 pandemic.\n" }, "finish_reason": "stop" } ], "usage": { "completion_tokens": 47, "prompt_tokens": 59, "total_tokens": 106 } } }, "tool call": { "summary": "tool_call", "description": "A tool calling example.\n", "value": { "id": "cmpl-15475d0dea9b4429a55843c77997f8a9", "model_id": "meta-llama/llama-3-8b-instruct", "created": 1689958352, "created_at": "2023-07-21T16:52:32.190Z", "choices": [ { "index": 0, "message": { "role": "assistant", "tool_calls": [ { "id": "chatcmpl-tool-ef093f0cbbff4c6a973aa0873f73fc99", "type": "function", "function": { "name": "get_current_weather", "arguments": "{\n \"location\": \"Boston, MA\",\n \"unit\": \"fahrenheit\"\n}\n" } } ] }, "finish_reason": "stop" } ], "usage": { "completion_tokens": 18, "prompt_tokens": 19, "total_tokens": 37 } } }, "json mode": { "summary": "json_mode", "description": "A text chat example with json output.\n", "value": { "id": "cmpl-09945b25c805491fb49e15439b8e5d84", "model_id": "meta-llama/llama-3-8b-instruct", "created": 1689958352, "created_at": "2023-07-21T16:52:32.190Z", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "[\"The Los Angeles Dodgers won the World Series in 2020. They defeated the Tampa Bay Rays in six games.\"]" }, "finish_reason": "stop" } ], "usage": { "completion_tokens": 35, "prompt_tokens": 20, "total_tokens": 55 } } }, "moderated_response": { "summary": "moderated_response", "description": "A text chat response with moderations.\n", "value": { "id": "cmpl-15475d0dea9b4429a55843c77997f8a9", "model_id": "meta-llama/llama-3-8b-instruct", "created": 1689958352, "created_at": "2023-07-21T16:52:32.190Z", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "c/o USPS, PO Box 3000, Washington, D.C. 20001-5000, www.usps.com, or call **************." }, "finish_reason": "stop" } ], "usage": { "completion_tokens": 18, "prompt_tokens": 19, "total_tokens": 37 }, "moderations": { "pii": [ { "score": 0.8, "input": false, "position": { "start": 74, "end": 88 }, "entity": "PhoneNumber" } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.text-chat.send" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "text chat", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v1/text/chat?version=2023-10-25'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "-d ", "'{\n", " \"model_id\": \"meta-llama/llama-3-8b-instruct\",\n", " \"project_id\": \"63dc4cf1-252f-424b-b52d-5cdd9814987f\",\n", " \"messages\": [\n", " {\n", " \"role\": \"system\",\n", " \"content\": \"You are a helpful assistant.\"\n", " },\n", " {\n", " \"role\": \"user\",\n", " \"content\": [\n", " {\n", " \"type\": \"text\",\n", " \"text\": \"Who won the world series in 2020?\"\n", " }\n", " ]\n", " },\n", " {\n", " \"role\": \"assistant\",\n", " \"content\": \"The Los Angeles Dodgers won the World Series in 2020.\"\n", " },\n", " {\n", " \"role\": \"user\",\n", " \"content\": [\n", " {\n", " \"type\": \"text\",\n", " \"text\": \"Where was it played?\"\n", " }\n", " ]\n", " }\n", " ],\n", " \"max_tokens\": 100,\n", " \"temperature\": 0,\n", " \"time_limit\": 1000\n", "}'\n" ] } ] }, { "name": "tool call", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v1/text/chat?version=2023-10-25'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "-d ", "'{\n", " \"model_id\": \"meta-llama/llama-3-8b-instruct\",\n", " \"project_id\": \"63dc4cf1-252f-424b-b52d-5cdd9814987f\",\n", " \"messages\": [\n", " {\n", " \"role\": \"user\",\n", " \"content\": [\n", " {\n", " \"type\": \"text\",\n", " \"text\": \"What is the weather like in Boston today?\"\n", " }\n", " ]\n", " }\n", " ],\n", " \"tools\": [\n", " {\n", " \"type\": \"function\",\n", " \"function\": {\n", " \"name\": \"get_current_weather\",\n", " \"description\": \"Get the current weather in a given location\",\n", " \"parameters\": {\n", " \"type\": \"object\",\n", " \"properties\": {\n", " \"location\": {\n", " \"description\": \"The city, e.g. San Francisco, CA\",\n", " \"type\": \"string\"\n", " },\n", " \"unit\": {\n", " \"enum\": [\n", " \"celsius\",\n", " \"fahrenheit\"\n", " ],\n", " \"type\": \"string\"\n", " }\n", " },\n", " \"required\": [\n", " \"location\"\n", " ]\n", " }\n", " }\n", " }\n", " ],\n", " \"tool_choice\": {\n", " \"type\": \"function\",\n", " \"function\": {\n", " \"name\": \"get_current_weather\",\n", " }\n", " }\n", "}'\n" ] } ] }, { "name": "json mode", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v1/text/chat?version=2023-10-25'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "-d ", "'{\n", " \"model_id\": \"meta-llama/llama-3-8b-instruct\",\n", " \"project_id\": \"63dc4cf1-252f-424b-b52d-5cdd9814987f\",\n", " \"response_format\": {\n", " \"type\": \"json_object\"\n", " },\n", " \"messages\": [\n", " {\n", " \"role\": \"system\",\n", " \"content\": \"You are a helpful assistant designed to output JSON.\"\n", " },\n", " {\n", " \"role\": \"user\",\n", " \"content\": [\n", " {\n", " \"type\": \"user\",\n", " \"text\": \"Who won the world series in 2020?\"\n", " }\n", " ]\n", " }\n", " ]\n", "}'\n" ] } ] } ] } } } }, "/ml/v1/text/chat_stream": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "text_chat_stream", "x-cli-command": "chat-stream", "x-cli-command-group": "text", "tags": [ "Text Chat" ], "summary": "Infer text event stream", "description": "Infer the next tokens for a given deployed model with a set of PARAMS3.\nThis operation will return the output tokens as a stream of events.\n\nThis operation will set `stream` in the request body to true and\nreturn the output tokens as a stream of events.\n\nYou can also use [/v1/chat/completions](#chat_completions)\nwith `stream` option set to true to achieve the same result.\n", "requestBody": { "required": true, "description": "From a given prompt, infer the next tokens in a server-sent events (SSE) stream.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextChatStreamRequest" }, "examples": { "request": { "summary": "A request without moderations.", "description": "A simple request.\n", "value": { "model_id": "meta-llama/llama-3-8b-instruct", "project_id": "63dc4cf1-252f-424b-b52d-5cdd9814987f", "messages": [ { "role": "user", "content": { "type": "text", "text": "Where was the 2020 world series played?" } } ], "max_tokens": 30, "temperature": 0.8 } }, "moderations_request": { "summary": "A request with moderations.", "description": "A simple request with moderations.\n", "value": { "model_id": "meta-llama/llama-3-8b-instruct", "project_id": "63dc4cf1-252f-424b-b52d-5cdd9814987f", "messages": [ { "role": "user", "content": { "type": "text", "text": "Tell me how to reach the US Postal service" } } ], "max_tokens": 120, "temperature": 0, "moderations": { "hap": { "input": { "enabled": true, "threshold": 0.5 }, "output": { "enabled": true, "threshold": 0.5 } }, "pii": { "input": { "enabled": true }, "output": { "enabled": true } } } } } } } } }, "responses": { "200": { "description": "Successful operation (`Content-Type: text/event-stream`).", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/TextChatStreamResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.text-chat.send" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/files": { "servers": [], "post": { "tags": [ "Files" ], "summary": "Upload file", "description": "Uploads a file to be used for batch inferencing. The file must be uploaded with purpose=batch and can later be referenced when submitting a batch job.\n", "operationId": "upload_batch_file", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "X-IBM-Project-ID", "in": "header", "required": true, "description": "Watsonx project identifier", "schema": { "type": "string", "example": "63dc4cf1-252f-424b-b52d-5cdd9814987f" } }, { "name": "X-IBM-Space-ID", "in": "header", "required": false, "description": "Watsonx space identifier", "schema": { "type": "string", "example": "4c8f2a91-8a7d-4dbe-9c7c-1c2a3b4d5e6f" } } ], "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "JSONL file containing batch requests.", "example": "@mydata.jsonl" }, "purpose": { "type": "string", "enum": [ "batch" ], "description": "Purpose of the uploaded file. Must be set to batch.", "example": "batch" } } } } } }, "responses": { "200": { "description": "File successfully uploaded for batch processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "file-CAMS_ASSET_ID" }, "object": { "type": "string", "example": "file" }, "bytes": { "type": "integer", "example": 120000 }, "created_at": { "type": "integer", "description": "Unix timestamp", "example": 1677610602 }, "expires_at": { "type": "integer", "example": 0 }, "filename": { "type": "string", "example": "mydata.jsonl" }, "purpose": { "type": "string", "example": "batch" } } } } } }, "400": { "description": "Invalid request payload" }, "401": { "description": "Unauthorized – insufficient permissions" } } }, "get": { "tags": [ "Files" ], "summary": "List files", "description": "Returns a list of files that have been uploaded to watsonx.ai. Files can be filtered by purpose and sorted by creation time. This endpoint is commonly used to locate batch input or output files.\n", "operationId": "list_files", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "X-IBM-Project-ID", "in": "header", "required": true, "description": "Watsonx project identifier", "schema": { "type": "string", "example": "63dc4cf1-252f-424b-b52d-5cdd9814987f" } }, { "name": "X-IBM-Space-ID", "in": "header", "required": false, "description": "Watsonx space identifier", "schema": { "type": "string", "example": "4c8f2a91-8a7d-4dbe-9c7c-1c2a3b4d5e6f" } }, { "name": "after", "in": "query", "description": "A cursor for pagination. Use the last file ID from the previous response to retrieve the next page.\n", "schema": { "type": "string", "example": "file-abc123" } }, { "name": "limit", "in": "query", "description": "Maximum number of files to return. Must be between 1 and 10,000.\n", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 10000, "example": 100 } }, { "name": "order", "in": "query", "required": false, "description": "Sort order by created_at timestamp.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "example": "desc" } }, { "name": "purpose", "in": "query", "required": false, "description": "Only return files with the specified purpose.", "schema": { "type": "string", "example": "batch" } } ], "responses": { "200": { "description": "Successfully retrieved list of files", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "example": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "file-CAMS_ASSET_ID1" }, "object": { "type": "string", "example": "file" }, "bytes": { "type": "integer", "example": 175 }, "created_at": { "type": "integer", "description": "Unix timestamp", "example": 1613677385 }, "expires_at": { "type": "integer", "nullable": true, "example": 0 }, "filename": { "type": "string", "example": "mydata.jsonl" }, "purpose": { "type": "string", "example": "batch" } } }, "example": [ { "id": "file-CAMS_ASSET_ID1", "object": "file", "bytes": 175, "created_at": 1613677385, "expires_at": 0, "filename": "mydata1.jsonl", "purpose": "batch" }, { "id": "file-CAMS_ASSET_ID2", "object": "file", "bytes": 12000, "created_at": 1677610602, "expires_at": 0, "filename": "mydata2.jsonl", "purpose": "batch" } ] }, "first_id": { "type": "string", "nullable": true, "example": "file-CAMS_ASSET_ID1" }, "last_id": { "type": "string", "nullable": true, "example": "file-CAMS_ASSET_ID2" }, "has_more": { "type": "boolean", "example": false } } } } } }, "401": { "description": "Unauthorized – insufficient permissions" }, "403": { "description": "Forbidden" } } } }, "/ml/v1/files/{file_id}/content": { "servers": [], "get": { "tags": [ "Files" ], "summary": "Retrieve file", "description": "Retrieves the contents and metadata of a file previously uploaded. This endpoint is typically used to download or inspect batch input or output files.\n", "operationId": "get_file_content", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file to retrieve", "schema": { "type": "string", "example": "file-CAMS_ASSET_ID" } }, { "name": "X-IBM-Project-ID", "in": "header", "required": true, "description": "Watsonx project identifier", "schema": { "type": "string", "example": "63dc4cf1-252f-424b-b52d-5cdd9814987f" } }, { "name": "X-IBM-Space-ID", "in": "header", "required": false, "description": "Watsonx space identifier", "schema": { "type": "string", "example": "4c8f2a91-8a7d-4dbe-9c7c-1c2a3b4d5e6f" } }, { "name": "Content-Type", "in": "header", "description": "Content type of the request", "schema": { "type": "string", "example": "application/json" } } ], "responses": { "200": { "description": "Successfully retrieved file metadata and contents", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "file-CAMS_ASSET_ID" }, "object": { "type": "string", "example": "file" }, "bytes": { "type": "integer", "description": "Size of the file in bytes", "example": 120000 }, "created_at": { "type": "integer", "description": "Unix timestamp when the file was created", "example": 1677610602 }, "expires_at": { "type": "integer", "description": "Unix timestamp when the file expires (0 if no expiration)", "example": 0 }, "filename": { "type": "string", "example": "mydata.jsonl" }, "purpose": { "type": "string", "example": "batch" } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized – insufficient permissions" }, "404": { "description": "File not found" } } } }, "/ml/v1/batches": { "servers": [], "post": { "tags": [ "Batches" ], "summary": "Create batch", "description": "Creates a new batch job using an uploaded input file. The batch job will process the requests in the input file for the specified endpoint.\n", "operationId": "create_batch", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "X-IBM-Project-ID", "in": "header", "required": true, "description": "Watsonx project identifier", "schema": { "type": "string", "example": "63dc4cf1-252f-424b-b52d-5cdd9814987f" } }, { "name": "X-IBM-Space-ID", "in": "header", "required": false, "description": "Watsonx space identifier", "schema": { "type": "string", "example": "4c8f2a91-8a7d-4dbe-9c7c-1c2a3b4d5e6f" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "input_file_id", "endpoint", "completion_window" ], "properties": { "input_file_id": { "type": "string", "description": "ID of the uploaded input file for the batch job.", "example": "file-CAMS_ASSET_ID" }, "endpoint": { "type": "string", "description": "API endpoint to use for processing each batch item.", "example": "/v1/chat/completions" }, "completion_window": { "type": "string", "description": "Time window for completion of the batch job.", "example": "24h" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "customer_id": "user_123456789", "batch_description": "Nightly eval job" } } } } } } }, "responses": { "200": { "description": "Batch job successfully created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "batch_id" }, "object": { "type": "string", "example": "batch" }, "endpoint": { "type": "string", "example": "/v1/chat/completions" }, "input_file_id": { "type": "string", "example": "file-CAMS_ASSET_ID" }, "completion_window": { "type": "string", "example": "24h" }, "status": { "type": "string", "example": "validating" }, "output_file_id": { "type": "string", "nullable": true, "example": null }, "error_file_id": { "type": "string", "nullable": true, "example": null }, "created_at": { "type": "integer", "description": "Unix timestamp", "example": 1711471533 }, "in_progress_at": { "type": "integer", "nullable": true, "example": null }, "expires_at": { "type": "integer", "nullable": true, "example": null }, "finalizing_at": { "type": "integer", "nullable": true, "example": null }, "completed_at": { "type": "integer", "nullable": true, "example": null }, "failed_at": { "type": "integer", "nullable": true, "example": null }, "expired_at": { "type": "integer", "nullable": true, "example": null }, "cancelling_at": { "type": "integer", "nullable": true, "example": null }, "cancelled_at": { "type": "integer", "nullable": true, "example": null }, "request_counts": { "type": "object", "properties": { "total": { "type": "integer", "example": 0 }, "completed": { "type": "integer", "example": 0 }, "failed": { "type": "integer", "example": 0 } } }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "customer_id": "user_123456789", "batch_description": "Nightly eval job" } } } } } } }, "400": { "description": "Invalid request payload" }, "401": { "description": "Unauthorized – insufficient permissions" } } }, "get": { "tags": [ "Batches" ], "summary": "List batches", "description": "Returns a list of batch jobs created in the current watsonx.ai project. This endpoint is commonly used to monitor batch job status and retrieve batch identifiers for further inspection.\n", "operationId": "list_all_batches", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "X-IBM-Project-ID", "in": "header", "required": true, "description": "Watsonx project identifier", "schema": { "type": "string", "example": "63dc4cf1-252f-424b-b52d-5cdd9814987f" } }, { "name": "X-IBM-Space-ID", "in": "header", "required": false, "description": "Watsonx space identifier", "schema": { "type": "string", "example": "4c8f2a91-8a7d-4dbe-9c7c-1c2a3b4d5e6f" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of batch jobs to return", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "example": 2 } } ], "responses": { "200": { "description": "Successfully retrieved list of batch jobs", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "example": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "batch_id" }, "object": { "type": "string", "example": "batch" }, "endpoint": { "type": "string", "example": "/v1/chat/completions" }, "input_file_id": { "type": "string", "example": "file-CAMS_ASSET_ID" }, "completion_window": { "type": "string", "example": "24h" }, "status": { "type": "string", "example": "completed" }, "output_file_id": { "type": "string", "nullable": true, "example": "file-CAMS_OUTPUT_FILE_ASSET_ID" }, "error_file_id": { "type": "string", "nullable": true, "example": null }, "created_at": { "type": "integer", "example": 1711471533 }, "completed_at": { "type": "integer", "nullable": true, "example": 1721471533 }, "request_counts": { "type": "object", "properties": { "total": { "type": "integer", "example": 6000 }, "completed": { "type": "integer", "example": 6000 }, "failed": { "type": "integer", "example": 0 } } }, "metadata": { "type": "object", "additionalProperties": true, "example": {} } } } }, "first_id": { "type": "string", "example": "batch_abc123" }, "last_id": { "type": "string", "example": "batch_xyz789" }, "has_more": { "type": "boolean", "example": false } } }, "examples": { "batch_list": { "summary": "List batches response", "value": { "object": "list", "data": [ { "id": "batch_id", "object": "batch", "endpoint": "/v1/chat/completions", "input_file_id": "file-CAMS_ASSET_ID", "completion_window": "24h", "status": "completed", "output_file_id": "file-CAMS_OUTPUT_FILE_ASSET_ID", "error_file_id": null, "created_at": 1711471533, "completed_at": 1721471533, "request_counts": { "total": 6000, "completed": 6000, "failed": 0 }, "metadata": {} } ], "first_id": "batch_abc123", "last_id": "batch_xyz789", "has_more": false } } } } } }, "401": { "description": "Unauthorized – insufficient permissions" } } } }, "/ml/v1/batches/{batch_id}": { "servers": [], "get": { "tags": [ "Batches" ], "summary": "Retrieve batch", "description": "Retrieves details for a specific batch job, including status, input/output files, request counts, timestamps, and user-defined metadata.\n", "operationId": "get_batch_by_id", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "description": "The ID of the batch job to retrieve", "schema": { "type": "string", "example": "batch_id" } }, { "name": "X-IBM-Project-ID", "in": "header", "required": true, "description": "Watsonx project identifier", "schema": { "type": "string", "example": "63dc4cf1-252f-424b-b52d-5cdd9814987f" } }, { "name": "X-IBM-Space-ID", "in": "header", "required": false, "description": "Watsonx space identifier", "schema": { "type": "string", "example": "4c8f2a91-8a7d-4dbe-9c7c-1c2a3b4d5e6f" } } ], "responses": { "200": { "description": "Successfully retrieved batch job", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "batch_id" }, "object": { "type": "string", "example": "batch" }, "endpoint": { "type": "string", "example": "/v1/chat/completions" }, "errors": { "type": "array", "items": { "type": "string" }, "nullable": true, "example": null }, "input_file_id": { "type": "string", "example": "file-CAMS_ASSET_ID" }, "completion_window": { "type": "string", "example": "24h" }, "status": { "type": "string", "example": "completed" }, "output_file_id": { "type": "string", "nullable": true, "example": "file-CAMS_OUTPUT_FILE_ASSET_ID" }, "error_file_id": { "type": "string", "nullable": true, "example": null }, "created_at": { "type": "integer", "example": 1711471533 }, "in_progress_at": { "type": "integer", "nullable": true, "example": null }, "expires_at": { "type": "integer", "nullable": true, "example": null }, "finalizing_at": { "type": "integer", "nullable": true, "example": null }, "completed_at": { "type": "integer", "nullable": true, "example": 1721471533 }, "failed_at": { "type": "integer", "nullable": true, "example": null }, "expired_at": { "type": "integer", "nullable": true, "example": null }, "cancelling_at": { "type": "integer", "nullable": true, "example": null }, "cancelled_at": { "type": "integer", "nullable": true, "example": null }, "request_counts": { "type": "object", "properties": { "total": { "type": "integer", "example": 6000 }, "completed": { "type": "integer", "example": 6000 }, "failed": { "type": "integer", "example": 0 } } }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "customer_id": "user_123456789", "batch_description": "Nightly eval job" } } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Batch job not found" } } } }, "/ml/v1/batches/{batch_id}/cancel": { "servers": [], "post": { "tags": [ "Batches" ], "summary": "Cancel batch", "description": "Cancels an in-progress batch job. The batch will transition to the `cancelling` state and may take several minutes to reach the `cancelled` state. Partial results, if available, will be preserved and accessible via the output file.\n", "operationId": "cancel_batch_by_id", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "description": "The ID of the batch job to cancel", "schema": { "type": "string", "example": "batch_id" } }, { "name": "X-IBM-Project-ID", "in": "header", "required": true, "description": "Watsonx project identifier", "schema": { "type": "string", "example": "63dc4cf1-252f-424b-b52d-5cdd9814987f" } }, { "name": "X-IBM-Space-ID", "in": "header", "required": false, "description": "Watsonx space identifier", "schema": { "type": "string", "example": "4c8f2a91-8a7d-4dbe-9c7c-1c2a3b4d5e6f" } } ], "responses": { "200": { "description": "Batch cancellation initiated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "batch_id" }, "object": { "type": "string", "example": "batch" }, "endpoint": { "type": "string", "example": "/v1/chat/completions" }, "errors": { "type": "array", "items": { "type": "string" }, "nullable": true, "example": null }, "input_file_id": { "type": "string", "example": "file-CAMS_ASSET_ID" }, "completion_window": { "type": "string", "example": "24h" }, "status": { "type": "string", "example": "cancelling" }, "output_file_id": { "type": "string", "nullable": true, "example": null }, "error_file_id": { "type": "string", "nullable": true, "example": null }, "created_at": { "type": "integer", "example": 1711471533 }, "in_progress_at": { "type": "integer", "nullable": true, "example": 1711471538 }, "expires_at": { "type": "integer", "nullable": true, "example": 1711557933 }, "finalizing_at": { "type": "integer", "nullable": true, "example": null }, "completed_at": { "type": "integer", "nullable": true, "example": null }, "failed_at": { "type": "integer", "nullable": true, "example": null }, "expired_at": { "type": "integer", "nullable": true, "example": null }, "cancelling_at": { "type": "integer", "nullable": true, "example": 1711475133 }, "cancelled_at": { "type": "integer", "nullable": true, "example": null }, "request_counts": { "type": "object", "properties": { "total": { "type": "integer", "example": 100 }, "completed": { "type": "integer", "example": 23 }, "failed": { "type": "integer", "example": 1 } } }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "customer_id": "user_123456789", "batch_description": "Nightly eval job" } } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Batch job not found" }, "409": { "description": "Batch cannot be cancelled in its current state" } } } }, "/ml/v4/ai_services": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "ai_services_create", "tags": [ "AI Services" ], "summary": "Create a new AI service", "description": "Create a new AI service with the given payload. A AI service is some code that can be deployed as a deployment.\n", "requestBody": { "description": "Payload for creating the AI service. Either `space_id` or `project_id` has to be provided and is mandatory.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIServiceRequest" }, "examples": { "request": { "summary": "A sample request.", "value": { "name": "ai-app-1", "software_spec": { "id": "45f12dfe-aa78-5b8d-9f38-0ee223c47309" }, "space_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "documentation": { "request": { "application/json": { "$schema": "https://json-schema.org/draft/2020-12/schema#", "type": "object", "properties": { "query": { "type": "string" }, "parameters": { "properties": { "max_new_tokens": { "type": "integer" }, "top_p": { "type": "number" } }, "required": [ "max_new_tokens", "top_p" ] } }, "required": [ "query" ] }, "application/png": { "$schema": "https://json-schema.org/draft/2020-12/schema#", "type": "object", "properties": { "image": { "type": "string", "format": "binary" } }, "required": [ "image" ] } }, "response": { "application/json": { "$schema": "https://json-schema.org/draft/2020-12/schema#", "type": "object", "properties": { "query": { "type": "string" }, "result": { "type": "string" } }, "required": [ "query", "result" ] }, "application/png": { "$schema": "https://json-schema.org/draft/2020-12/schema#", "type": "string", "format": "binary" } } }, "tooling": { "reference_format": true } } } } } }, "required": true }, "responses": { "201": { "description": "AI service created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIServiceResource" }, "examples": { "response": { "summary": "The AI service response.", "description": "The response with the result.\n", "value": { "metadata": { "id": "b53c5118-b1ca-43ef-a597-ef839ff7129f", "name": "ai-app-1", "space_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "created_at": "2023-05-02T16:27:51Z" }, "entity": { "software_spec": { "id": "45f12dfe-aa78-5b8d-9f38-0ee223c47309" }, "documentation": { "request": { "application/json": { "$schema": "https://json-schema.org/draft/2020-12/schema#", "type": "object", "properties": { "query": { "type": "string" }, "parameters": { "properties": { "max_new_tokens": { "type": "integer" }, "top_p": { "type": "number" } }, "required": [ "max_new_tokens", "top_p" ] } }, "required": [ "query" ] }, "application/png": { "$schema": "https://json-schema.org/draft/2020-12/schema#", "type": "object", "properties": { "image": { "type": "string", "format": "binary" } }, "required": [ "image" ] } }, "response": { "application/json": { "$schema": "https://json-schema.org/draft/2020-12/schema#", "type": "object", "properties": { "query": { "type": "string" }, "result": { "type": "string" } }, "required": [ "query", "result" ] }, "application/png": { "$schema": "https://json-schema.org/draft/2020-12/schema#", "type": "string", "format": "binary" } } } } } } } } }, "headers": { "Location": { "description": "The location of the new AI service artifact, e.g. `/ml/v1/ai_services/53dc4cf1-252f-424b-b52d-5cdd9814987f?space_id=fab7ac25-2f97-41e1-8f77-203c3423e5f4`.\n", "schema": { "type": "string", "description": "The location of the new AI service artifact.\n" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.ai_service.create" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Create request AI Service", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v4/ai_services?version=2024-10-17'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "-d ", "'{\n", " \"name\": \"ai-service-1\",\n", " \"space_id\": \"12ac4cf1-252f-424b-b52d-5cdd9814987f\",\n", " \"software_spec\": {\n", " \"id\": \"45f12dfe-aa78-5b8d-9f38-0ee223c47309\"\n", " },\n", " \"documentation\": {\n", " \"request\": {\n", " \"application/json\": {\n", " \"$schema\": \"https://json-schema.org/draft/2020-12/schema#\",\n", " \"type\": \"object\",\n", " \"properties\": {\n", " \"query\": {\n", " \"type\": \"string\"\n", " },\n", " \"parameters\": {\n", " \"properties\": {\n", " \"max_new_tokens\": {\n", " \"type\": \"integer\"\n", " },\n", " \"top_p\": {\n", " \"type\": \"number\"\n", " }\n", " },\n", " \"required\": [\n", " \"max_new_tokens\",\n", " \"top_p\"\n", " ]\n", " }\n", " },\n", " \"required\": [\n", " \"query\"\n", " ]\n", " },\n", " \"application/png\": {\n", " \"$schema\": \"https://json-schema.org/draft/2020-12/schema#\",\n", " \"type\": \"object\",\n", " \"properties\": {\n", " \"image\": {\n", " \"type\": \"string\",\n", " \"format\": \"binary\"\n", " }\n", " },\n", " \"required\": [\n", " \"image\"\n", " ]\n", " }\n", " },\n", " \"response\": {\n", " \"application/json\": {\n", " \"$schema\": \"https://json-schema.org/draft/2020-12/schema#\",\n", " \"type\": \"object\",\n", " \"properties\": {\n", " \"query\": {\n", " \"type\": \"string\"\n", " },\n", " \"result\": {\n", " \"type\": \"string\"\n", " }\n", " },\n", " \"required\": [\n", " \"query\",\n", " \"result\"\n", " ]\n", " },\n", " \"application/png\": {\n", " \"$schema\": \"https://json-schema.org/draft/2020-12/schema#\",\n", " \"type\": \"string\",\n", " \"format\": \"binary\"\n", " }\n", " }\n", " }\n", "}'" ] } ] } ] } } }, "get": { "operationId": "ai_services_list", "tags": [ "AI Services" ], "summary": "Retrieve the AI services", "description": "Retrieve the AI services for the specified space or project.\n", "parameters": [ { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/tag.value" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIServiceResources" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.ai_service.list" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Retrieve all AI services", "example": [ { "type": "code", "source": [ "curl --request GET 'https://{cluster_url}/ml/v4/ai_services?space_id=12ac4cf1-252f-424b-b52d-5cdd9814987f&limit=100&version=2024-10-17'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n" ] } ] } ] } } } }, "/ml/v4/ai_services/{id}": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/path_ai_service_id" }, { "$ref": "#/components/parameters/version" } ], "get": { "operationId": "ai_services_get", "tags": [ "AI Services" ], "summary": "Retrieve the AI service", "description": "Retrieve the AI service with the specified identifier. If `rev` query parameter is provided,\n`rev=latest` will fetch the latest revision. A call with `rev={revision_number}` will fetch the given revision_number record. Either `space_id` or `project_id` has to be provided and is mandatory.\n", "parameters": [ { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/rev" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIServiceResource" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.ai_service.read" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Retrieve a AI service", "example": [ { "type": "code", "source": [ "curl --request GET \"https://{cluster_url}/ml/v4/ai_services/{id}?space_id=12ac4cf1-252f-424b-b52d-5cdd9814987f&version=2024-10-17\"\n", "-H \"Authorization: Bearer eyJhbGciOiJSUzUxM...\"" ] } ] } ] } } }, "patch": { "operationId": "ai_services_update", "tags": [ "AI Services" ], "summary": "Update the AI service", "description": "Update the AI service with the provided patch data.\nThe following fields can be patched:\n- `/tags`\n- `/name`\n- `/description`\n- `/custom`\n", "parameters": [ { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" } ], "requestBody": { "description": "Input For Patch. This is the patch body which corresponds to the JavaScript Object Notation (JSON) Patch standard (RFC 6902).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonPatch" } } }, "required": true }, "x-json-patch-helper-model": "common_patch_request_helper", "responses": { "200": { "description": "AI service has been patched successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIServiceResource" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codegen-request-body-name": "json-patch", "x-ibm-events": { "events": [ { "name": "pm-20.ai_service.update" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Update AI Services", "example": [ { "type": "code", "source": [ "curl --request PATCH \"https://{cluster_url}/ml/v4/ai_services/{id}?space_id=12ac4cf1-252f-424b-b52d-5cdd9814987f&version=2024-10-17\"\n", "-H \"Authorization: Bearer eyJhbGciOiJSUzUxM...\"\n", "-H \"Content-Type: application/json\"\n", "-H \"Accept: application/json\"\n", "-d \n", "[\n", " {\n", " \"op\": \"replace\",\n", " \"path\": \"/description\",\n", " \"value\": \"New Description\"\n", " }\n", "]" ] } ] } ] } } }, "delete": { "operationId": "ai_services_delete", "tags": [ "AI Services" ], "summary": "Delete the AI service", "description": "Delete the AI service with the specified identifier. This will delete all revisions of this flow as well. For each revision all attachments will also be deleted.\n", "parameters": [ { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "204": { "description": "AI service deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.ai_service.delete" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Delete the AI service", "example": [ { "type": "code", "source": [ "curl --request DELETE \"https://{cluster_url}/ml/v4/ai_services/{id}?space_id=12ac4cf1-252f-424b-b52d-5cdd9814987f&version=2024-10-17\"\n", "-H \"Authorization: Bearer eyJhbGciOiJSUzUxM...\"" ] } ] } ] } } } }, "/ml/v4/ai_services/{id}/code": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/path_ai_service_id" }, { "$ref": "#/components/parameters/version" } ], "put": { "operationId": "ai_services_upload_code", "tags": [ "AI Services" ], "summary": "Upload the AI service code", "description": "Upload the flow code. AI services expect a zip file that contains the code files that make up the flow.\n", "parameters": [ { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" } ], "requestBody": { "$ref": "#/components/requestBodies/AIServiceBody" }, "responses": { "201": { "description": "AI service code uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIServiceContentMetadata" } } }, "headers": { "Location": { "description": "The location of the new AI service attachment,\ne.g. `/ml/v1/ai_services/459afef1-252f-424b-b52d-5cdd98128fa3/code?space_id=fab7ac25-2f97-41e1-8f77-203c3423e5f4`.\n", "schema": { "type": "string", "description": "The location of the new AI service attachment.\n" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codegen-request-body-name": "upload-code", "x-ibm-events": { "events": [ { "name": "pm-20.ai_service.add" } ] }, "x-cli-generate-adapter-method": true, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Upload the flow code", "example": [ { "type": "code", "source": [ "curl --request PUT \"https://{cluster_url}/ml/v4/ai_services/{id}/code?space_id=12ac4cf1-252f-424b-b52d-5cdd9814987f&version=2024-10-17\"\n", "-H \"Authorization: Bearer eyJhbGciOiJSUzUxM...\"\n", "-H \"Content-Type: application/gzip\"\n" ] } ] } ] } } }, "get": { "operationId": "ai_services_download_code", "tags": [ "AI Services" ], "summary": "Download the AI service code", "description": "Download the AI service code.\nIt is possible to download the `code` for a given revision of the `flow`.\nAI services expect a zip file that contains the code files that make up the flow.\n", "parameters": [ { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/rev" } ], "responses": { "200": { "$ref": "#/components/responses/ApplicationZip" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.ai_service.read" } ] }, "x-cli-generate-adapter-method": true, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Download the AI service code", "example": [ { "type": "code", "source": [ "curl --request GET \"https://{cluster_url}/ml/v4/ai_services/{id}/code?space_id=12ac4cf1-252f-424b-b52d-5cdd9814987f&rev=1&version=2024-10-17\"\n", "-H \"Authorization: Bearer eyJhbGciOiJSUzUxM...\"" ] } ] } ] } } } }, "/ml/v4/ai_services/{id}/revisions": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/path_ai_service_id" }, { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "ai_services_create_revision", "tags": [ "AI Services" ], "summary": "Create a new AI service revision", "description": "Create a new AI service revision.\nThe current metadata and content for\n`id` will be taken and a new revision created.\nEither `space_id` or `project_id` has to be provided and is mandatory.\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionEntitySpaceProjectRequest" } } }, "required": true }, "responses": { "201": { "description": "AI service revision created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIServiceResource" } } }, "headers": { "Location": { "description": "The location of the new created AI service, e.g. `/ml/v1/ai_services/53dc4cf1-252f-424b-b52d-5cdd9814987f?space_id=fab7ac25-2f97-41e1-8f77-203c3423e5f4`.\n", "schema": { "type": "string", "description": "The location of the new created AI service.\n" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.ai_service.create" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Create new AI service revision", "example": [ { "type": "code", "source": [ "curl --request POST \"https://{cluster_url}/ml/v4/ai_services/{id}/revisions?space_id=12ac4cf1-252f-424b-b52d-5cdd9814987f&version=2024-10-17\"\n", "-H \"Authorization: Bearer eyJhbGciOiJSUzUxM...\"\n", "-H \"Content-Type: application/json\"\n", "-H \"Accept: application/json\"\n", "-d \n", "{\n", " \"space_id\": \"12ac4cf1-252f-424b-b52d-5cdd9814987f\",\n", " \"commit_message\": \"New Code\"\n", "}\n" ] } ] } ] } } }, "get": { "operationId": "ai_services_list_revisions", "tags": [ "AI Services" ], "summary": "Retrieve the AI service revisions", "description": "Retrieve the AI service revisions.\n", "parameters": [ { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "AI service revisions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIServiceResources" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.ai_service.list" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Retrieve AI service revisions", "example": [ { "type": "code", "source": [ "curl --request GET \"https://{cluster_url}/ml/v4/ai_services/{id}/revisions?space_id=12ac4cf1-252f-424b-b52d-5cdd9814987f&limit=100&version=2024-10-17\"\n", "-H \"Authorization: Bearer eyJhbGciOiJSUzUxM...\"" ] } ] } ] } } } }, "/ml/v1/text/detection": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "text_detection_content", "x-cli-command": "content", "x-cli-command-group": "text-detection", "tags": [ "Text Detection" ], "summary": "HAP and PII detection for text", "description": "This operation is used mainly for Hate And Profanity (`HAP`)\nand Personal Identifiable Information (`PII`) filtering.\n\nThis is a detection-only end-point.\nIt supports natural language input and output and returns the result of the detection.\nIt can be configured for HAP, PII, or any combination with other available detectors.\n", "requestBody": { "required": true, "description": "From a content, detect text.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextDetectionContentRequest" }, "examples": { "detect_pii": { "summary": "text PII detection", "description": "A PII text detection example.\n", "value": { "input": "my text to check", "project_id": "63dc4cf1-252f-424b-b52d-5cdd9814987f", "detectors": { "pii": {} } } }, "detect_hap": { "summary": "A PII text detection example.", "description": "A HAP text detection example.\n", "value": { "input": "my text to check", "project_id": "63dc4cf1-252f-424b-b52d-5cdd9814987f", "detectors": { "hap": { "threshold": 0.5 } } } }, "detect_multiple": { "summary": "text detection with multiple detectors", "description": "A text detection with multiple detectors.\n", "value": { "input": "my text to check", "project_id": "63dc4cf1-252f-424b-b52d-5cdd9814987f", "detectors": { "pii": {}, "hap": { "threshold": 0.6 } } } } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextDetectionContentResponse" }, "examples": { "detect_pii": { "summary": "text PII detection", "description": "A PII text detection example.\n", "value": { "detections": [ { "start": 20, "end": 24, "detection_type": "pii", "detection": "xxxx", "score": 0.846 } ] } }, "detect_hap": { "summary": "A HAP text detection example.", "description": "A HAP text detection example.\n", "value": { "detections": [ { "start": 122, "end": 239, "detection_type": "hap", "detection": "xxxxxxxxxxxxxxxxxxxxxxxxxx", "score": 0.846 } ] } }, "detect_multiple": { "summary": "text detection with multiple detectors", "description": "A text detection with multiple detectors.\n", "value": { "detections": [ { "start": 20, "end": 24, "detection_type": "pii", "detection": "xxxx", "score": 0.846 }, { "start": 122, "end": 239, "detection_type": "hap", "detection": "xxxxxxxxxxxxxxxxxxxxxxxxxx", "score": 0.846 } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.text-detection-content.send" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/text/detection/context": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "text_detection_context", "x-cli-command": "context", "x-cli-command-group": "text-detection", "tags": [ "Text Detection" ], "summary": "Detection task on input content based on context documents", "description": "This operation supports `context relevance` and `faithfulness` (or `groundedness`).\n\nThe `input` is analyzed, along with the context information,\nand the model will return any detections that it found.\n", "requestBody": { "required": true, "description": "From a content, detect text using a detection model.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextDetectionContextRequest" } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextDetectionContextResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.text-detection-context.send" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/text/detection/generated": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "text_detection_generated", "x-cli-command": "generated", "x-cli-command-group": "text-detection", "tags": [ "Text Detection" ], "summary": "Detection task performing detection on prompt and generated text", "description": "This operation supports `answer relevance`.\n\nThe `prompt` is analyzed, along with the `generated text`,\nand the model will return any detections that it found.\n", "requestBody": { "required": true, "description": "From a content, detect text using a detection model.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextDetectionGeneratedRequest" } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextDetectionGeneratedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.text-detection-generated.send" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/time_series/forecast": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "time_series_forecast", "x-cli-command": "forecast", "x-cli-command-group": "time-series", "tags": [ "Time Series" ], "summary": "Time series forecast", "description": "Generate forecasts, or predictions for future time points, given historical time series data.\n", "requestBody": { "required": true, "description": "The forecast request.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TSForecastRequest" }, "examples": { "request": { "summary": "A sample request.", "value": { "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "model_id": "ibm/ttm-1024-96-r2", "schema": { "timestamp_column": "date", "id_columns": [ "ID1" ] }, "data": { "date": [ "2020-01-01T00:00:00", "2020-01-01T01:00:00", "2020-01-05T01:00:00" ], "ID1": [ "D1", "D1", "D1" ], "TARGET1": [ 1.46, 2.34, 4.55 ] } } } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TSForecastResponse" }, "examples": { "response": { "summary": "A sample response.", "value": { "model_id": "ibm/ttm-1024-96-r2", "created_at": "2020-05-02T16:27:51Z", "results": [ { "date": [ "2020-01-05T02:00:00", "2020-01-05T03:00:00", "2020-01-06T00:00:00" ], "ID1": [ "D1", "D1", "D1" ], "TARGET1": [ 1.86, 3.24, 6.78 ] } ], "input_data_points": 512, "output_data_points": 1024 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.time-series-forecast.send" } ] }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "sample request", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v1/time_series/forecast?version=2023-10-25'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Accept: application/json'\n", "-d ", "'{\n", " \"project_id\": \"12ac4cf1-252f-424b-b52d-5cdd9814987f\",\n", " \"model_id\": \"ibm/ttm-1024-96-r2\",\n", " \"schema\": {\n", " \"timestamp_column\": \"date\",\n", " \"id_columns\": [\n", " \"ID1\"\n", " ]\n", " },\n", " \"data\": {\n", " \"date\": [\n", " \"2020-01-01T00:00:00\",\n", " \"2020-01-01T01:00:00\",\n", " \"2020-01-05T01:00:00\"\n", " ],\n", " \"ID1\": [\n", " \"D1\",\n", " \"D1\",\n", " \"D1\"\n", " ],\n", " \"TARGET1\": [\n", " 1.46,\n", " 2.34,\n", " 4.55\n", " ]\n", " }\n", "}'\n" ] } ] } ] } } } }, "/ml/v1/tuning/documents": { "servers": [], "post": { "operationId": "create_document_extraction", "x-cli-command": "create", "x-cli-command-group": "document-extraction", "summary": "Create a document extraction", "description": "Create a document extraction.\n", "tags": [ "Document Extraction (Beta)" ], "parameters": [ { "$ref": "#/components/parameters/version" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentExtractionRequest" } } } }, "responses": { "201": { "description": "The document extraction job has been created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentExtractionResource" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "Bearer": [] } ] }, "get": { "operationId": "list_document_extractions", "x-cli-command": "list", "x-cli-command-group": "document-extraction", "summary": "Get document extractions", "description": "Get document extractions.\n", "tags": [ "Document Extraction (Beta)" ], "parameters": [ { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/SpaceId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentExtractionResources" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/tuning/documents/{id}": { "servers": [], "get": { "operationId": "get_document_extraction", "x-cli-command": "get", "x-cli-command-group": "document-extraction", "summary": "Get document extraction", "description": "Get document extraction.\n", "tags": [ "Document Extraction (Beta)" ], "parameters": [ { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/path_id" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/SpaceId" } ], "responses": { "200": { "description": "The document extraction job has been created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentExtractionResource" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "Bearer": [] } ] }, "delete": { "operationId": "cancel_document_extractions", "x-cli-command": "delete", "x-cli-command-group": "document-extraction", "summary": "Cancel the document extraction", "description": "Cancel the specified document extraction and remove it.\n", "tags": [ "Document Extraction (Beta)" ], "parameters": [ { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/path_id" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/SpaceId" }, { "name": "hard_delete", "description": "Set to true in order to also delete the job metadata information.", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "204": { "description": "Document extraction cancelled." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/tuning/synthetic_data": { "servers": [], "post": { "operationId": "create_synthetic_data_generation", "x-cli-command": "create", "x-cli-command-group": "synthetic-data-generation", "summary": "Create a synthetic data generation job", "description": "Create a synthetic data generation job.\n", "tags": [ "Synthetic Data Generation (Beta)" ], "parameters": [ { "$ref": "#/components/parameters/version" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyntheticDataGenerationRequest" } } } }, "responses": { "201": { "description": "The synthetic data generation job has been created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyntheticDataGenerationResource" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "Bearer": [] } ] }, "get": { "operationId": "list_synthetic_data_generations", "x-cli-command": "list", "x-cli-command-group": "synthetic-data-generation", "summary": "Get synthetic data generation jobs", "tags": [ "Synthetic Data Generation (Beta)" ], "parameters": [ { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/SpaceId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyntheticDataGenerationResources" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/tuning/synthetic_data/{id}": { "servers": [], "get": { "operationId": "get_synthetic_data_generation", "x-cli-command": "get", "x-cli-command-group": "synthetic-data-generation", "summary": "Get synthetic data generation job", "tags": [ "Synthetic Data Generation (Beta)" ], "parameters": [ { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/path_id" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/SpaceId" } ], "responses": { "200": { "description": "The synthetic data generation job has been created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyntheticDataGenerationResource" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "Bearer": [] } ] }, "delete": { "operationId": "cancel_synthetic_data_generation", "x-cli-command": "delete", "x-cli-command-group": "synthetic-data-generation", "summary": "Cancel the synthetic data generation", "description": "Cancel the synthetic data generation and remove it.\n", "tags": [ "Synthetic Data Generation (Beta)" ], "parameters": [ { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/path_id" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/SpaceId" }, { "name": "hard_delete", "description": "Set to true in order to also delete the job metadata information.", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "204": { "description": "Synthetic data generation cancelled." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/tuning/taxonomies_imports": { "servers": [], "post": { "operationId": "create_taxonomy", "x-cli-command": "create", "x-cli-command-group": "taxonomy", "summary": "Create a taxonomy job", "description": "Create a taxonomy job.\n", "tags": [ "Taxonomy (Beta)" ], "parameters": [ { "$ref": "#/components/parameters/version" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyRequest" } } } }, "responses": { "201": { "description": "The taxonomy job has been created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyResource" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "InstructLab Taxonomy", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/ml/v1/tuning/taxonomies_imports?version=2023-10-25'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "--data-raw ", "'{\n", " \"name\": \"taxonomyName\",\n", " \"description\": \"Taxonomy\",\n", " \"project_id\": \"bfdae754-f0ef-45c6-a982-50b222f82015\",\n", " \"data_reference\": {\n", " \"type\": \"github\",\n", " \"location\": {\n", " \"secret_manager_url\": \"https://5db94803-9c37-498b-b4bd-d601ac4a0518.eu-gb.secrets-manager.test.appdomain.cloud/api/v2/secrets\",\n", " \"secret_id\": \"539f678e-3436-5d70-5c62-e98250bf0427\",\n", " \"path\": \".\"\n", " }\n", " }\n", "}'\n" ] } ] } ] } } }, "get": { "operationId": "list_taxonomies", "x-cli-command": "list", "x-cli-command-group": "taxonomy", "summary": "Get taxonomy jobs", "tags": [ "Taxonomy (Beta)" ], "parameters": [ { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/SpaceId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyResources" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/tuning/taxonomies_imports/{id}": { "servers": [], "get": { "operationId": "get_taxonomy", "x-cli-command": "get", "x-cli-command-group": "taxonomy", "summary": "Get taxonomy job", "tags": [ "Taxonomy (Beta)" ], "parameters": [ { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/path_id" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/SpaceId" } ], "responses": { "200": { "description": "The taxonomy job has been created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyResource" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "Bearer": [] } ] }, "delete": { "operationId": "delete_taxonomy", "x-cli-command": "delete", "x-cli-command-group": "taxonomy", "summary": "Cancel or delete the taxonomy job", "description": "Cancel or delete the taxonomy job.\n", "tags": [ "Taxonomy (Beta)" ], "parameters": [ { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/path_id" }, { "name": "hard_delete", "description": "Set to `true` in order to also delete the job metadata information.", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "204": { "description": "Taxonomy cancelled." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/text/evaluations": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "submit_evaluation", "tags": [ "Evaluations" ], "summary": "Submit a new Evaluation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationRequest" } } }, "required": true }, "responses": { "201": { "description": "Job successfully submitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "Bearer": [] } ] }, "get": { "operationId": "list_evaluations", "tags": [ "Evaluations" ], "summary": "Get list of Evaluations", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationResources" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/text/evaluations/{id}": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/path_id" }, { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" } ], "get": { "operationId": "get_evaluation", "tags": [ "Evaluations" ], "summary": "Get Evalutation with given ID", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationResource" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "Bearer": [] } ] }, "delete": { "operationId": "delete_evaluation", "tags": [ "Evaluations" ], "summary": "Cancel or delete Evaluation with given ID", "parameters": [ { "in": "query", "name": "hard_delete", "schema": { "type": "boolean" }, "description": "If set to `true`, evaluation job gets deleted instead of cancelled." } ], "responses": { "204": { "description": "No Content" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "Bearer": [] } ] } }, "/v2/synthetic_data/generation/unstructured": { "servers": [], "post": { "operationId": "create_synthetic_data_generation_unstructured", "x-cli-command": "create", "x-cli-command-group": "synthetic-data-generation-unstructured", "summary": "Create a synthetic unstructured data generation job", "description": "Create a synthetic unstructured data generation job.\n", "tags": [ "Synthetic Data" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SDGUnstructuredGenerationRequest-v2" }, "examples": { "nl2sql": { "summary": "nl2sql", "description": "A nl2sql unstructured data generation example.\n", "value": { "name": "my-resource", "description": "This is my first resource.", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "configuration": { "pipeline": "nl2sql", "generator": { "model_id": "ibm/granite-3-8b-instruct" }, "num_outputs_to_generate": 100, "seed_data_reference": { "type": "container", "location": { "path": "qna_nl2sql.yaml" } }, "results_reference": { "type": "container", "location": { "path": "output.jsonl" } }, "overwrite_output_file": true } } } } } } }, "responses": { "201": { "description": "The synthetic data generation job has been created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SDGUnstructuredGenerationResource-v2" }, "examples": { "nl2sql": { "summary": "nl2sql", "description": "A nl2sql unstructured data generation example response.\n", "value": { "metadata": { "name": "my-resource", "description": "This is my first resource.", "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab" }, "entity": { "configuration": { "pipeline": "nl2sql", "generator": { "model_id": "ibm/granite-3-8b-instruct" }, "num_outputs_to_generate": 100, "seed_data_reference": { "type": "container", "location": { "path": "qna_nl2sql.yaml" } }, "results_reference": { "type": "container", "location": { "path": "output.jsonl" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/gpus": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "get": { "operationId": "/MGErrorResponse.yaml", "tags": [ "GPUs" ], "summary": "See available GPUs", "description": "See all available GPUs on the cluster.\n", "parameters": [ { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/GPUId" }, { "$ref": "#/components/parameters/GPUType" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GPUResources" }, "examples": { "gpus": { "summary": "available gpus", "value": { "total_count": 12, "limit": 2, "first": { "href": "https://{cluster_url}/ml/v1/gpus?version=2025-01-12" }, "next": { "href": "https://{cluster_url}/ml/v1/gpus?version=2025-01-12&start=..." }, "gpu_configurations": [ { "gpu_id": "1l40s-48g", "description": "Single L40S GPU with 48 GB of memory", "gpu_type": "L40S", "gpu_count": 1, "memory_per_unit_gb": 48, "total_memory_gb": 48, "price": 4.43, "currency": "USD", "billing": "hourly", "hardware_spec": "1l40s-48g" }, { "gpu_id": "2l40s-96g", "description": "Two L40S GPUs with 96 GB of memory", "gpu_type": "L40S", "gpu_count": 2, "memory_per_unit_gb": 48, "total_memory_gb": 96, "price": 8.86, "currency": "USD", "billing": "hourly", "hardware_spec": "2l40s-96g" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.gpus.list" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/text/classifications": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "text_classification", "x-cli-command": "create", "x-cli-command-group": "text-classification", "tags": [ "Text Classification" ], "summary": "Start a text classification request", "description": "Start a request to classify text from a document or an image (using OCR).\n", "requestBody": { "required": true, "description": "The input for the text classification request.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextClassificationRequest" } } } }, "responses": { "201": { "description": "Created. The `Content-Location` header will contain the URI reference to the created resource.", "headers": { "Content-Location": { "description": "The location of the newly created resource.\n", "schema": { "type": "string", "description": "The location of the newly created resource.\n" } }, "Location": { "description": "The location of the newly created resource.\n", "schema": { "type": "string", "description": "The location of the newly created resource.\n" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextClassificationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.text-classification.send" } ] }, "security": [ { "Bearer": [] } ] }, "get": { "operationId": "list_text_classifications", "x-cli-command": "list", "x-cli-command-group": "text-classification", "tags": [ "Text Classification" ], "summary": "Retrieve the text classification requests", "description": "Retrieve the list of text classification requests for the specified space or project.\n\nThis operation does not save the history, any requests that were deleted or purged\nwill not appear in this list.\n", "parameters": [ { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextClassificationResources" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.text-classification.list" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/text/classifications/{id}": { "servers": [], "parameters": [ { "name": "id", "in": "path", "description": "The identifier of the classification request.", "schema": { "type": "string" }, "required": true }, { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" } ], "get": { "operationId": "text_classification_get", "x-cli-command": "get", "x-cli-command-group": "text-classification", "tags": [ "Text Classification" ], "summary": "Get the results of the request", "description": "Retrieve the text classification request with the specified identifier.\n\nNote that there is a retention period of 2 days. If this retention\nperiod is exceeded then the request will be deleted and the results\nno longer available. In this case this operation will return `404`.\n", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextClassificationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.text-classification.get" } ] }, "security": [ { "Bearer": [] } ] }, "delete": { "operationId": "text_classification_delete", "x-cli-command": "delete", "x-cli-command-group": "text-classification", "parameters": [ { "$ref": "#/components/parameters/hard_delete" } ], "tags": [ "Text Classification" ], "summary": "Delete the request", "description": "Cancel the specified text classification request and delete any associated results.\n", "responses": { "204": { "description": "Request deleted." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.text-classification.delete" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/text/schemas/create": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "create_schema", "x-cli-command": "create", "x-cli-command-group": "create-schema", "tags": [ "Create Schema" ], "summary": "Start a create schema request", "description": "Start a request to create the custom schema for text extraction\n", "requestBody": { "required": true, "description": "The input for the create schema request.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSchemaRequest" }, "examples": { "simple request": { "summary": "simple_request", "description": "A simple request.\n", "value": { "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "document_reference": { "type": "connection_asset", "connection": { "id": "6f5688fd-f3bf-42c2-a18b-49c0d8a1920d" }, "location": { "file_name": "files/document.pdf" } }, "parameters": { "mode": "high_quality", "ocr_mode": "enabled", "enable_grounding": false, "auto_rotation_correction": false, "languages": [ "latn" ] } } }, "container request": { "summary": "container_request", "description": "A simple request with docuemt and result reference to container.\n", "value": { "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "document_reference": { "type": "container", "location": { "path": "files/document.pdf" } }, "parameters": { "mode": "high_quality", "ocr_mode": "enabled", "enable_grounding": true, "languages": [ "latn" ] } } } } } } }, "responses": { "201": { "description": "Created. The `Content-Location` header will contain the URI reference to the created resource.", "headers": { "Content-Location": { "description": "The location of the newly created resource.\n", "schema": { "type": "string", "description": "The location of the newly created resource.\n" } }, "Location": { "description": "The location of the newly created resource.\n", "schema": { "type": "string", "description": "The location of the newly created resource.\n" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSchemaResponse" }, "examples": { "simple response": { "summary": "A simple response.", "value": { "metadata": { "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "created_at": "2023-05-02T16:27:51Z", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f" }, "entity": { "document_reference": { "type": "connection_asset", "connection": { "id": "6f5688fd-f3bf-42c2-a18b-49c0d8a1920d" }, "location": { "file_name": "files/document.pdf" } }, "parameters": { "mode": "high_quality", "ocr_mode": "enabled", "enable_grounding": false, "auto_rotation_correction": false }, "results": { "completed_at": "2026-03-31T06:31:50.070Z", "grounding_hints": { "fields": "" }, "number_pages_processed": 1, "running_at": "2026-03-31T06:31:35.693Z", "schema": { "document_description": "A detailed corporate profile of IBM, including financial performance, board and shareholder information, and headquarters details.", "document_type": "Corporate_Profile" }, "status": "completed", "total_pages": 1 } } } }, "container response": { "summary": "A container response.", "value": { "metadata": { "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "created_at": "2023-05-02T16:27:51Z", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f" }, "entity": { "document_reference": { "type": "container", "location": { "path": "files/document.pdf" } }, "parameters": { "mode": "high_quality", "ocr_mode": "enabled", "enable_grounding": true }, "results": { "status": "submitted", "number_pages_processed": 0 } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.create-schema.send" } ] }, "security": [ { "Bearer": [] } ] }, "get": { "operationId": "list_create_schema", "x-cli-command": "list", "x-cli-command-group": "create_schema", "tags": [ "Create Schema" ], "summary": "Retrieve the create schema requests", "description": "Retrieve the list of create schema requests for the specified space or project.\n\nThis operation does not save the history, any requests that were deleted or purged\nwill not appear in this list.\n", "parameters": [ { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSchemaResources" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.create-schema.list" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/text/schemas/create/{id}": { "servers": [], "parameters": [ { "name": "id", "in": "path", "description": "The identifier of the create schema request.", "schema": { "type": "string" }, "required": true }, { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" } ], "get": { "operationId": "create_schema_get", "x-cli-command": "get", "x-cli-command-group": "create-schema", "tags": [ "Create Schema" ], "summary": "Get the results of the request", "description": "Retrieve the create schema request with the specified identifier.\n\nNote that there is a retention period of 2 days. If this retention\nperiod is exceeded then the request will be deleted and the results\nno longer available. In this case this operation will return `404`.\n", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSchemaResponse" }, "examples": { "response": { "summary": "A sample response.", "value": { "metadata": { "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "created_at": "2023-05-02T16:27:51Z", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f" }, "entity": { "document_reference": { "type": "connection_asset", "connection": { "id": "6f5688fd-f3bf-42c2-a18b-49c0d8a1920d" }, "location": { "file_name": "files/document.pdf" } }, "results": { "status": "running", "number_pages_processed": 2, "running_at": "2023-05-02T16:28:03Z" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.create-schema.get" } ] }, "security": [ { "Bearer": [] } ] }, "delete": { "operationId": "create_schema_delete", "x-cli-command": "delete", "x-cli-command-group": "create-schema", "parameters": [ { "$ref": "#/components/parameters/hard_delete" } ], "tags": [ "Create Schema" ], "summary": "Delete the request", "description": "Cancel the specified create schema request and delete any associated results.\n", "responses": { "204": { "description": "Request deleted." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.create-schema.delete" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/text/schemas/improve": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "improve_schema", "x-cli-command": "improve", "x-cli-command-group": "improve-schema", "tags": [ "Improve Schema" ], "summary": "Start a improve schema request", "description": "Start a request to create the custom schema for text extraction\n", "requestBody": { "required": true, "description": "The input for the improve schema request.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImproveSchemaRequest" }, "examples": { "simple request": { "summary": "simple_request", "description": "A simple request.\n", "value": { "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "parameters": { "schema": { "document_type": "Passport", "document_description": "Passport document to get the schema", "fields": { "description": "Name", "example": "name of the user" } } } } } } } } }, "responses": { "201": { "description": "Created. The `Content-Location` header will contain the URI reference to the created resource.", "headers": { "Content-Location": { "description": "The location of the newly created resource.\n", "schema": { "type": "string", "description": "The location of the newly created resource.\n" } }, "Location": { "description": "The location of the newly created resource.\n", "schema": { "type": "string", "description": "The location of the newly created resource.\n" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImproveSchemaResponse" }, "examples": { "simple response": { "summary": "A simple response.", "value": { "metadata": { "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "created_at": "2023-05-02T16:27:51Z", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f" }, "entity": { "parameters": { "schema": { "document_type": "Passport", "document_description": "Passport document to get the schema", "fields": { "description": "Name", "example": "name of the user" } } }, "results": { "status": "submitted" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.improve-schema.send" } ] }, "security": [ { "Bearer": [] } ] }, "get": { "operationId": "list_improve_schema", "x-cli-command": "list", "x-cli-command-group": "improve_schema", "tags": [ "Improve Schema" ], "summary": "Retrieve the improve schema requests", "description": "Retrieve the list of improve schema requests for the specified space or project.\n\nThis operation does not save the history, any requests that were deleted or purged\nwill not appear in this list.\n", "parameters": [ { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImproveSchemaResources" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.improve-schema.list" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/text/schemas/improve/{id}": { "servers": [], "parameters": [ { "name": "id", "in": "path", "description": "The identifier of the improve schema request.", "schema": { "type": "string" }, "required": true }, { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" } ], "get": { "operationId": "improve_schema_get", "x-cli-command": "get", "x-cli-command-group": "improve-schema", "tags": [ "Improve Schema" ], "summary": "Get the results of the request", "description": "Retrieve the improve schema request with the specified identifier.\n\nNote that there is a retention period of 2 days. If this retention\nperiod is exceeded then the request will be deleted and the results\nno longer available. In this case this operation will return `404`.\n", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImproveSchemaResponse" }, "examples": { "sample request": { "summary": "sample_response", "description": "A sample response.\n", "value": { "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "parameters": { "schema": { "document_type": "Passport", "document_description": "Passport document to get the schema", "fields": { "description": "Name", "example": "name of the user" } } }, "results": { "status": "running", "running_at": "2023-05-02T16:28:03Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.improve-schema.get" } ] }, "security": [ { "Bearer": [] } ] }, "delete": { "operationId": "improve_schema_delete", "x-cli-command": "delete", "x-cli-command-group": "improve-schema", "parameters": [ { "$ref": "#/components/parameters/hard_delete" } ], "tags": [ "Improve Schema" ], "summary": "Delete the request", "description": "Cancel the specified improve schema request and delete any associated results.\n", "responses": { "204": { "description": "Request deleted." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.improve-schema.delete" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/text/schemas/merge": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "merge_schema", "x-cli-command": "merge", "x-cli-command-group": "merge-schema", "tags": [ "Merge Schema" ], "summary": "Start a merge schema request", "description": "Start a request to merge a list of semantically similar custom schemas for text extraction into a single schema.\n", "requestBody": { "required": true, "description": "The input for the merge schema request.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeSchemaRequest" }, "examples": { "sample request": { "summary": "sample_request", "description": "A sample request.\n", "value": { "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "parameters": { "schemas": [ { "document_type": "Passport", "document_description": "Passport document to get the schema", "fields": { "description": "Name", "example": "name of the user" } }, { "document_type": "National ID Card", "document_description": "National ID Cards are government-issued identification documents", "fields": { "description": "Name", "example": "Holder legal name as shown on the ID" } } ] } } } } } } }, "responses": { "201": { "description": "Created. The `Content-Location` header will contain the URI reference to the created resource.", "headers": { "Content-Location": { "description": "The location of the newly created resource.\n", "schema": { "type": "string", "description": "The location of the newly created resource.\n" } }, "Location": { "description": "The location of the newly created resource.\n", "schema": { "type": "string", "description": "The location of the newly created resource.\n" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeSchemaResponse" }, "examples": { "sample request": { "summary": "sample_response", "description": "A sample response.\n", "value": { "metadata": { "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "created_at": "2023-05-02T16:27:51Z", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f" }, "entity": { "parameters": { "schemas": [ { "document_type": "Passport", "document_description": "Passport document to get the schema", "fields": { "description": "Name", "example": "name of the user" } }, { "document_type": "National ID Card", "document_description": "National ID Cards are government-issued identification documents", "fields": { "description": "Name", "example": "Holder legal name as shown on the ID" } } ] }, "results": { "status": "running", "running_at": "2023-05-02T16:28:03Z" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.improve-schema.send" } ] }, "security": [ { "Bearer": [] } ] }, "get": { "operationId": "list_merge_schema", "x-cli-command": "list", "x-cli-command-group": "merge_schema", "tags": [ "Merge Schema" ], "summary": "Retrieve the merge schema requests", "description": "Retrieve the list of merge schema requests for the specified space or project.\n\nThis operation does not save the history, any requests that were deleted or purged\nwill not appear in this list.\n", "parameters": [ { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeSchemaResources" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.merge-schema.list" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/text/schemas/merge/{id}": { "servers": [], "parameters": [ { "name": "id", "in": "path", "description": "The identifier of the merge schema request.", "schema": { "type": "string" }, "required": true }, { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" } ], "get": { "operationId": "merge_schema_get", "x-cli-command": "get", "x-cli-command-group": "merge-schema", "tags": [ "Merge Schema" ], "summary": "Get the results of the request", "description": "Retrieve the merge schema request with the specified identifier.\n\nNote that there is a retention period of 2 days. If this retention\nperiod is exceeded then the request will be deleted and the results\nno longer available. In this case this operation will return `404`.\n", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeSchemaResponse" }, "examples": { "sample response": { "summary": "sample_response", "description": "A sample response.\n", "value": { "metadata": { "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "created_at": "2023-05-02T16:27:51Z", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f" }, "entity": { "parameters": { "schemas": [ { "document_type": "Passport", "document_description": "Passport document to get the schema", "fields": { "description": "Name", "example": "name of the user" } } ] }, "results": { "status": "running", "running_at": "2023-05-02T16:28:03Z" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.merge-schema.get" } ] }, "security": [ { "Bearer": [] } ] }, "delete": { "operationId": "merge_schema_delete", "x-cli-command": "delete", "x-cli-command-group": "merge-schema", "parameters": [ { "$ref": "#/components/parameters/hard_delete" } ], "tags": [ "Merge Schema" ], "summary": "Delete the request", "description": "Cancel the specified merge schema request and delete any associated results.\n", "responses": { "204": { "description": "Request deleted." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.merge-schema.delete" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/text/schemas/cluster": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/version" } ], "post": { "operationId": "cluster_schema", "x-cli-command": "cluster", "x-cli-command-group": "cluster-schema", "tags": [ "Cluster Schema" ], "summary": "Start a cluster schema request", "description": "Start a request to cluster a list of custom schemas into semantically similar groups.\n", "requestBody": { "required": true, "description": "The input for the cluster schema request.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterSchemaRequest" }, "examples": { "sample request": { "summary": "sample_request", "description": "A sample request.\n", "value": { "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "parameters": { "schemas": [ { "document_name": "Passport", "schema": { "document_type": "Passport", "document_description": "Passport document to get the schema", "fields": { "description": "Name", "example": "name of the user" } } }, { "document_name": "National_ID_Card", "schema": { "document_type": "National ID Card", "document_description": "National ID Cards are government-issued identification documents", "fields": { "description": "Alice Marie Smith", "example": "Holder legal name as shown on the ID" } } } ] } } } } } } }, "responses": { "201": { "description": "Created. The `Content-Location` header will contain the URI reference to the created resource.", "headers": { "Content-Location": { "description": "The location of the newly created resource.\n", "schema": { "type": "string", "description": "The location of the newly created resource.\n" } }, "Location": { "description": "The location of the newly created resource.\n", "schema": { "type": "string", "description": "The location of the newly created resource.\n" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterSchemaResponse" }, "examples": { "sample request": { "summary": "sample_request", "description": "A sample request.\n", "value": { "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "parameters": { "schemas": [ { "document_name": "Passport", "schema": { "document_type": "Passport", "document_description": "Passport document to get the schema", "fields": { "description": "Name", "example": "name of the user" } } }, { "document_name": "National_ID_Card", "schema": { "document_type": "National ID Card", "document_description": "National ID Cards are government-issued identification documents", "fields": { "description": "Name", "example": "Holder legal name as shown on the ID" } } } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.cluster-schema.send" } ] }, "security": [ { "Bearer": [] } ] }, "get": { "operationId": "list_cluster_schema", "x-cli-command": "list", "x-cli-command-group": "cluster_schema", "tags": [ "Cluster Schema" ], "summary": "Retrieve the cluster schema requests", "description": "Retrieve the list of cluster schema requests for the specified space or project.\n\nThis operation does not save the history, any requests that were deleted or purged\nwill not appear in this list.\n", "parameters": [ { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterSchemaResources" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.cluster-schema.list" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/v1/text/schemas/cluster/{id}": { "servers": [], "parameters": [ { "name": "id", "in": "path", "description": "The identifier of the cluster schema request.", "schema": { "type": "string" }, "required": true }, { "$ref": "#/components/parameters/version" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ProjectId" } ], "get": { "operationId": "cluster_schema_get", "x-cli-command": "get", "x-cli-command-group": "cluster-schema", "tags": [ "Cluster Schema" ], "summary": "Get the results of the request", "description": "Retrieve the cluster schema request with the specified identifier.\n\nNote that there is a retention period of 2 days. If this retention\nperiod is exceeded then the request will be deleted and the results\nno longer available. In this case this operation will return `404`.\n", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterSchemaResponse" }, "examples": { "sample response": { "summary": "sample_response", "description": "A sample response.\n", "value": { "metadata": { "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "created_at": "2023-05-02T16:27:51Z", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f" }, "entity": { "parameters": { "schemas": [ { "document_name": "Passport", "schema": { "document_type": "Passport", "document_description": "Passport document to get the schema", "fields": { "description": "Name", "example": "name of the user" } } } ] }, "results": { "status": "running", "running_at": "2023-05-02T16:28:03Z" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.cluster-schema.get" } ] }, "security": [ { "Bearer": [] } ] }, "delete": { "operationId": "cluster_schema_delete", "x-cli-command": "delete", "x-cli-command-group": "cluster-schema", "parameters": [ { "$ref": "#/components/parameters/hard_delete" } ], "tags": [ "Cluster Schema" ], "summary": "Delete the request", "description": "Cancel the specified cluster schema request and delete any associated results.\n", "responses": { "204": { "description": "Request deleted." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-ibm-events": { "events": [ { "name": "pm-20.cluster-schema.delete" } ] }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/audio/speech": { "servers": [], "post": { "tags": [ "Model Gateway" ], "summary": "Create Speech", "description": "Generates speech from text using the specified model.", "operationId": "create_speech", "requestBody": { "description": "Create Speech Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSpeechRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Speech Generation", "content": { "application/json": { "schema": { "type": "array", "minItems": 0, "items": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 255 }, "description": "Audio data as an array of bytes" }, "examples": { "SpeechAudio": { "value": [ 82, 73, 70, 70 ] } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/chat/completions": { "servers": [], "post": { "tags": [ "Model Gateway" ], "summary": "Create Chat Completions", "description": "Generate a chat completion based on the provided messages and parameters using the provided model.", "operationId": "create_chat_completions", "requestBody": { "description": "Chat Completion Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChatsRequest" } } }, "required": true }, "responses": { "201": { "description": "Created Successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletion" }, "examples": { "CreateChatCompletion": { "value": { "object": "chat.completion", "id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG", "created": 1741570283, "model": "gpt-4o-2024-08-06", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "The capital of France is Paris.", "tool_calls": [] }, "logprobs": { "content": [ { "token": "The", "logprob": -1.23, "bytes": [ 84, 104, 101 ], "top_logprobs": [ { "token": "The", "logprob": -1.23, "bytes": [ 84, 104, 101 ] }, { "token": "A", "logprob": -1.57, "bytes": [ 65 ] }, { "token": "In", "logprob": -2.12, "bytes": [ 73, 110 ] } ] }, { "token": " ", "logprob": -0.01, "bytes": [ 32 ], "top_logprobs": [ { "token": " ", "logprob": -0.01, "bytes": [ 32 ] } ] }, { "token": "capital", "logprob": -2.04, "bytes": [ 99, 97, 112, 105, 116, 97, 108 ], "top_logprobs": [ { "token": "capital", "logprob": -2.04, "bytes": [ 99, 97, 112, 105, 116, 97, 108 ] }, { "token": "city", "logprob": -2.41, "bytes": [ 99, 105, 116, 121 ] }, { "token": "largest", "logprob": -2.66, "bytes": [ 108, 97, 114, 103, 101, 115, 116 ] } ] }, { "token": " of", "logprob": -0.89, "bytes": [ 32, 111, 102 ], "top_logprobs": [ { "token": " of", "logprob": -0.89, "bytes": [ 32, 111, 102 ] }, { "token": " for", "logprob": -1.52, "bytes": [ 32, 102, 111, 114 ] }, { "token": " in", "logprob": -1.63, "bytes": [ 32, 105, 110 ] } ] } ], "refusal": [] }, "finish_reason": "stop" } ], "service_tier": "auto", "system_fingerprint": "fp_fc9f1d7035", "usage": { "completion_tokens": 281, "completion_tokens_details": { "accepted_prediction_tokens": 91, "audio_tokens": 0, "reasoning_tokens": 74, "rejected_prediction_tokens": 0 }, "prompt_tokens": 66, "prompt_tokens_details": { "audio_tokens": 0, "cached_tokens": 13 }, "total_tokens": 347 }, "cached": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/completions": { "servers": [], "post": { "tags": [ "Model Gateway" ], "summary": "Create Text Completions", "description": "Generate a text completion based on the provided prompt and parameters using the provided model.", "operationId": "create_completions", "requestBody": { "description": "Completion Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCompletionsRequest" } } }, "required": true }, "responses": { "201": { "description": "Created Successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Completion" }, "examples": { "CreateCompletion": { "value": { "object": "text_completion", "id": "cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7", "created": 1589478378, "model": "gpt-4-turbo", "choices": [ { "index": 0, "text": "The capital of France is Paris.", "finish_reason": "stop", "logprobs": { "tokens": [ "The", " capital", " of", " France", " is", " Paris", "." ], "text_offset": [ 0, 3, 11, 14, 21, 24, 30 ], "token_logprobs": [ -1.23, -2.11, -0.85, -1.44, -0.76, -0.54, -0.31 ], "top_logprobs": [ { "The": -1.23, "A": -1.58, "In": -2.14, "It": -2.3, "This": -2.82 }, { " capital": -2.11, " city": -2.43, " location": -2.66, " capitol": -3.05 }, { " of": -0.85, " for": -1.52, " in": -1.63, " from": -1.74, " at": -1.88 }, { " France": -1.44, " Paris": -1.87, " France's": -1.98, " the": -2.13, " French": -2.29 }, { " is": -0.76, " was": -1.43, " has been": -1.6, " remains": -1.74, " will be": -1.78 }, { " Paris": -0.54, " Paris.": -0.83, " Marseille": -1.96, " Lyon": -2.02, " Nice": -2.13 }, { ".": -0.31, "!": -2.05, "?": -2.12, "\n": -2.25, "": -3 } ] } } ], "system_fingerprint": "fp_fc9f1d7035", "usage": { "completion_tokens": 281, "completion_tokens_details": { "accepted_prediction_tokens": 91, "audio_tokens": 0, "reasoning_tokens": 74, "rejected_prediction_tokens": 0 }, "prompt_tokens": 66, "prompt_tokens_details": { "audio_tokens": 0, "cached_tokens": 13 }, "total_tokens": 347 }, "cached": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/embeddings": { "servers": [], "post": { "tags": [ "Model Gateway" ], "summary": "Create Embeddings", "description": "Generate embeddings based on the provided input using the provided model.", "operationId": "create_embeddings", "requestBody": { "description": "Create Embedding Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEmbeddingsRequest" } } }, "required": true }, "responses": { "201": { "description": "Created Successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Embeddings" }, "examples": { "CreateEmbeddings": { "value": { "object": "list", "model": "gpt-4o", "data": [ { "object": "embedding", "index": 0, "embedding": [ 0.0023064255, -0.009327292, -0.0028842222 ] } ], "usage": { "completion_tokens": 281, "completion_tokens_details": { "accepted_prediction_tokens": 91, "audio_tokens": 0, "reasoning_tokens": 74, "rejected_prediction_tokens": 0 }, "prompt_tokens": 66, "prompt_tokens_details": { "audio_tokens": 0, "cached_tokens": 13 }, "total_tokens": 347 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/images/generations": { "servers": [], "post": { "tags": [ "Model Gateway" ], "summary": "Create Image Generations", "description": "Generates an image from a prompt using the provided model.", "operationId": "create_image", "requestBody": { "description": "Image Generation Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateImageRequest" } } }, "required": true }, "responses": { "201": { "description": "Image Created Successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGeneration" }, "examples": { "ImageGeneration": { "value": { "created": 1741570283, "data": [ { "b64_json": "..." } ], "background": "transparent", "output_format": "png", "size": "1024x1024", "quality": "high", "usage": { "total_tokens": 100, "input_tokens": 50, "output_tokens": 50, "input_tokens_details": { "text_tokens": 10, "image_tokens": 40 } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/models": { "servers": [], "get": { "operationId": "list_models", "summary": "List All Models", "tags": [ "Model Gateway" ], "description": "Lists all configured model details aggregated across all configured providers.", "responses": { "200": { "description": "List of all configured models.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelCollection" }, "examples": { "ListAllModels": { "value": { "object": "list", "data": [ { "uuid": "123e4567-e89b-12d3-a456-426614174000", "object": "model", "created": 1677649963, "owned_by": "azureOpenai:my-azure-provider", "id": "gpt-3.5-turbo-456723", "alias": "gpt-3.5-turbo", "metadata": { "cost": 0.02, "model_family": "gpt-3.5", "region": "us-east-1" } }, { "uuid": "123e0987-d89c-45d6-a789-426614174000", "object": "model", "created": 1677193491, "owned_by": "openai", "id": "gpt-4o-mini-2024-07-18", "alias": "gpt-4o-mini", "metadata": { "cost": 0.02, "model_family": "gpt-4o", "region": "us-east-1" } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/models/{model_uuid}": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/model_uuid" } ], "get": { "tags": [ "Model Gateway" ], "summary": "Get Existing Model", "description": "Retrieves a specific model configuration by model UUID.", "operationId": "get_model", "responses": { "200": { "description": "Model configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" }, "examples": { "GetGptModelDetails": { "value": { "object": "model", "id": "gpt-3.5-turbo-456723", "alias": "gpt-3.5-turbo", "created": 1677649963, "metadata": { "cost": 0.02, "model_family": "gpt-3.5", "region": "us-east-1" }, "owned_by": "openai:vllm4", "uuid": "123e4567-e89b-12d3-a456-426614174000" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "Model Gateway" ], "summary": "Delete Existing Model", "description": "Removes a specific model configuration from the tenant by UUID.", "operationId": "delete_model", "responses": { "204": { "description": "No Content" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/tenant": { "servers": [], "get": { "tags": [ "Model Gateway" ], "summary": "Get Current Tenant", "description": "Retrieves details of the currently authenticated tenant.", "operationId": "get_tenant", "responses": { "200": { "description": "Tenant Details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantInfo" }, "examples": { "GetTenantDetails": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "my-tenant" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] }, "put": { "tags": [ "Model Gateway" ], "summary": "Replace Current Tenant", "description": "Replaces details of the currently authenticated tenant's information.", "operationId": "replace_tenant", "requestBody": { "description": "Replacement tenant information details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceTenantRequest" } } }, "required": true }, "responses": { "200": { "description": "Replaced tenant information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantInfo" }, "examples": { "ReplacedTenantDetails": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "my-tenant" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] }, "patch": { "tags": [ "Model Gateway" ], "summary": "Update Current Tenant", "description": "Updates details of the currently authenticated tenant's information.", "operationId": "update_tenant", "requestBody": { "description": "Updated tenant information details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTenantRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated tenant information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantInfo" }, "examples": { "UpdateTenantDetails": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "my-tenant" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "Model Gateway" ], "summary": "Delete Current Tenant", "description": "Deletes an existing tenant.", "operationId": "delete_tenant", "responses": { "204": { "description": "Tenant Deleted Successfully" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/tenant/config": { "servers": [], "get": { "operationId": "get_tenant_config", "summary": "Get Current Tenant Configuration", "tags": [ "Model Gateway" ], "description": "Retrieves the current tenant configuration including default space_id, project_id, and default_algorithm", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantConfig" }, "examples": { "TenantConfig": { "value": { "space_id": "7f9c7c8a-36b1-4d4f-b4d7-6c1f8e9d1111", "project_id": "8f9c7c8a-36b1-4d4f-b4d7-6c1f8e9d2222", "default_algorithm": "least_connections" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] }, "put": { "operationId": "replace_tenant_config", "summary": "Update Current Tenant Configuration", "tags": [ "Model Gateway" ], "description": "Updates the tenant configuration with default space_id, project_id, and/or default_algorithm", "requestBody": { "description": "Tenant configuration to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantConfigRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantConfig" }, "examples": { "TenantConfig": { "value": { "space_id": "7f9c7c8a-36b1-4d4f-b4d7-6c1f8e9d1111", "project_id": "8f9c7c8a-36b1-4d4f-b4d7-6c1f8e9d2222", "default_algorithm": "least_connections" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] }, "delete": { "operationId": "delete_tenant_config", "summary": "Delete Current Tenant Configuration", "tags": [ "Model Gateway" ], "description": "Deletes the tenant configuration by clearing the default space_id, project_id, and default_algorithm", "responses": { "204": { "description": "Configuration deleted successfully" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/tenant/jwt": { "servers": [], "post": { "operationId": "create_jwt", "summary": "Create Tenant JWT", "tags": [ "Model Gateway" ], "description": "Creates a JWT token for direct access to backend services using the tenant UUID.", "responses": { "200": { "description": "JWT Token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" }, "examples": { "Token": { "value": { "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/policies": { "servers": [], "get": { "tags": [ "Model Gateway" ], "summary": "List All Policies", "description": "Lists all the existing policies for the tenant.", "operationId": "list_policies", "responses": { "200": { "description": "List of Policies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantPolicyCollection" }, "examples": { "ListTenantPolicies": { "value": { "object": "list", "data": [ { "uuid": "550e8400-e29b-41d4-a716-446655440000", "action": "write", "effect": "allow", "resource": "model:62a04a11-07bf-5309-a78e-95323dbbc333", "subject": "AccessGroupId-56c5e703-80d4-4f06-a7e6-844618ec39b3" }, { "uuid": "550e8400-e29b-41d4-a716-446655440000", "action": "read", "effect": "deny", "resource": "model:6d9234a11-07bf-q309-a38e-95323dbbc333", "subject": "AccessGroupId-203dad03-123d4-f4e206-a7e6-844618e5321" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "Model Gateway" ], "summary": "Create New Policy", "description": "Creates a new policy.", "operationId": "create_policy", "requestBody": { "description": "Policy configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTenantPolicyRequest" }, "examples": { "CreateTenantPolicy": { "value": { "subject": "AccessGroupId-56c5e703-80d4-4f06-a7e6-844618ec39b3", "resource": "model:62a04a11-07bf-5309-a78e-95323dbbc333", "action": "write", "effect": "allow" } } } } }, "required": true }, "responses": { "201": { "description": "Policy Created Successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantPolicy" }, "examples": { "CreatedTenantPolicy": { "value": { "uuid": "550e8400-e29b-41d4-a716-446655440000", "action": "write", "effect": "allow", "resource": "model:62a04a11-07bf-5309-a78e-95323dbbc333", "subject": "AccessGroupId-56c5e703-80d4-4f06-a7e6-844618ec39b3" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/policies/{policy_uuid}": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/policy_uuid" } ], "get": { "tags": [ "Model Gateway" ], "summary": "Get Specific Policy", "description": "Retrieves a specific policy by its UUID.", "operationId": "get_policy", "responses": { "200": { "description": "Policy Retrieved Successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantPolicy" }, "examples": { "Policy": { "value": { "uuid": "550e8400-e29b-41d4-a716-446655440000", "subject": "AccessGroupId-56c5e703-80d4-4f06-a7e6-844618ec39b3", "resource": "model:62a04a11-07bf-5309-a78e-95323dbbc333", "action": "write", "effect": "allow" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] }, "put": { "tags": [ "Model Gateway" ], "summary": "Update Existing Policy", "description": "Updates an existing policy with the specified UUID. Only provided fields are updated; omitted fields retain their current values.", "operationId": "replace_policy", "requestBody": { "description": "Updated Policy Configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTenantPolicyRequest" } } }, "required": true }, "responses": { "200": { "description": "Policy Updated Successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantPolicy" }, "examples": { "Policy": { "value": { "uuid": "550e8400-e29b-41d4-a716-446655440000", "subject": "AccessGroupId-56c5e703-80d4-4f06-a7e6-844618ec39b3", "resource": "model:62a04a11-07bf-5309-a78e-95323dbbc333", "action": "write", "effect": "deny" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "Model Gateway" ], "summary": "Delete Existing Policy", "description": "Deletes an existing policy with the specified UUID from the tenant.", "operationId": "delete_policy", "responses": { "204": { "description": "No Content" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers": { "servers": [], "get": { "tags": [ "Model Gateway" ], "summary": "List All Providers", "description": "Lists all configured model providers for the tenant.", "operationId": "list_providers", "responses": { "200": { "description": "List of model providers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderCollection" }, "examples": { "ListProviders": { "value": { "object": "list", "data": [ { "uuid": "56c5e703-80d4-4f06-a7e6-844618ec39b3", "name": "my-openai-provider", "type": "openai", "data": { "base_url": "https://api.openai.com/v1", "apikey": "AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe" }, "models": [ { "object": "model", "id": "gpt-3.5-turbo-456723", "alias": "gpt-3.5-turbo", "created": 1677649963, "metadata": { "cost": 0.02, "model_family": "gpt-3.5", "region": "us-east-1" }, "owned_by": "openai:vllm4", "uuid": "123e4567-e89b-12d3-a456-426614174000" }, { "object": "model", "id": "gpt-4o-mini-2024-07-18", "alias": "gpt-4o-mini", "created": 1677193491, "metadata": { "cost": 0.02, "model_family": "gpt-4o", "region": "us-east-1" }, "owned_by": "openai:vllm4", "uuid": "123e0987-d89c-45d6-a789-426614174000" } ] } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/anthropic": { "servers": [], "post": { "tags": [ "Model Gateway" ], "summary": "Create New Anthropic Provider", "description": "Creates a new Anthropic model provider configuration with the supplied details.", "operationId": "create_anthropic_provider", "requestBody": { "description": "Anthropic provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicProviderRequest" } } }, "required": true }, "responses": { "201": { "description": "Created Anthropic provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "NewAnthropicProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "my-anthropic-provider", "type": "anthropic" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/azure_openai": { "servers": [], "post": { "tags": [ "Model Gateway" ], "summary": "Create New Azure OpenAI Provider", "description": "Creates a new Azure OpenAI model provider configuration with the supplied details.", "operationId": "create_azure_openai_provider", "requestBody": { "description": "Azure OpenAI provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AzureOpenAIProviderRequest" } } }, "required": true }, "responses": { "201": { "description": "Created Azure OpenAI provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "NewAzureOpenAiProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "my-azure-openai-provider", "type": "azureOpenai" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/bedrock": { "servers": [], "post": { "tags": [ "Model Gateway" ], "summary": "Create New AWS Bedrock Provider", "description": "Creates a new AWS Bedrock model provider configuration with the supplied details.", "operationId": "create_bedrock_provider", "requestBody": { "description": "AWS Bedrock provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AWSBedrockProviderRequest" } } }, "required": true }, "responses": { "201": { "description": "Created AWS Bedrock provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "NewAWSBedrockProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "my-aws-bedrock-provider", "type": "bedrock" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/cerebras": { "servers": [], "post": { "tags": [ "Model Gateway" ], "summary": "Create New Cerebras Provider", "description": "Creates a new Cerebras model provider configuration with the supplied details.", "operationId": "create_cerebras_provider", "requestBody": { "description": "Cerebras provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CerebrasProviderRequest" } } }, "required": true }, "responses": { "201": { "description": "Created Cerebras provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "NewCerebrasProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "my-cerebras-provider", "type": "cerebras" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/cohere": { "servers": [], "post": { "tags": [ "Model Gateway" ], "summary": "Create New Cohere Provider", "description": "Creates a new Cohere model provider configuration with the supplied details.", "operationId": "create_cohere_provider", "requestBody": { "description": "Cohere provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereProviderRequest" } } }, "required": true }, "responses": { "201": { "description": "Created Cohere provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "NewCohereProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "my-cohere-provider", "type": "cohere" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/gemini": { "servers": [], "post": { "tags": [ "Model Gateway" ], "summary": "Create New Gemini Provider", "description": "Creates a new Google Gemini model provider configuration with the supplied details.", "operationId": "create_gemini_provider", "requestBody": { "description": "Gemini provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiProviderRequest" } } }, "required": true }, "responses": { "201": { "description": "Created Gemini provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "NewGeminiProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "my-gemini-provider", "type": "gemini" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/groq": { "servers": [], "post": { "tags": [ "Model Gateway" ], "summary": "Create New Groq Provider", "description": "Creates a new Groq model provider configuration with the supplied details.", "operationId": "create_groq_provider", "requestBody": { "description": "Groq Provider Configuration Details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroqProviderRequest" } } }, "required": true }, "responses": { "201": { "description": "Created Groq Provider Configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "NewGroqProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "my-groq-provider", "type": "groq" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/mistral": { "servers": [], "post": { "tags": [ "Model Gateway" ], "summary": "Create New Mistral Provider", "description": "Creates a new Mistral model provider configuration with the supplied details.", "operationId": "create_mistral_provider", "requestBody": { "description": "Mistral provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MistralProviderRequest" } } }, "required": true }, "responses": { "201": { "description": "Created Mistral provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "NewMistralProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "my-mistral-provider", "type": "mistral" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/nim": { "servers": [], "post": { "tags": [ "Model Gateway" ], "summary": "Create New Nvidia NIM Provider", "description": "Creates a new Nvidia NIM model provider configuration with the supplied details.", "operationId": "create_nim_provider", "requestBody": { "description": "Nvidia NIM provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NvidiaNIMProviderRequest" } } }, "required": true }, "responses": { "201": { "description": "Created Nvidia NIM provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "NewNvidiaNIMProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "my-nvidia-nim-provider", "type": "nvidiaNim" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/ollama": { "servers": [], "post": { "tags": [ "Model Gateway" ], "summary": "Create New Ollama Provider", "description": "Creates a new Ollama model provider configuration with the supplied details.", "operationId": "create_ollama_provider", "requestBody": { "description": "Ollama provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OllamaProviderRequest" } } }, "required": true }, "responses": { "201": { "description": "Created Ollama provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "NewOllamaProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "my-ollama-provider", "type": "ollama" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/openai": { "servers": [], "post": { "tags": [ "Model Gateway" ], "summary": "Create New OpenAI Provider", "description": "Creates a new OpenAI model provider configuration with the supplied details.", "operationId": "create_openai_provider", "requestBody": { "description": "OpenAI provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIProviderRequest" } } }, "required": true }, "responses": { "201": { "description": "Created OpenAI provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "NewOpenAiProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "my-openai-provider", "type": "openai" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/search": { "servers": [], "get": { "tags": [ "Model Gateway" ], "summary": "Find Existing Providers", "description": "Searches for providers by name.", "operationId": "find_providers", "parameters": [ { "name": "name", "in": "query", "description": "Provider name to search for", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of matching Providers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderCollection" }, "examples": { "ListMatchingProviders": { "value": { "object": "list", "data": [ { "uuid": "56c5e703-80d4-4f06-a7e6-844618ec39b3", "name": "my-openai-provider", "type": "openai", "data": { "base_url": "https://api.openai.com/v1", "apikey": "sk-proj-2_IN3221...IWZkA" }, "models": [ { "uuid": "123e4567-e89b-12d3-a456-426614174000", "object": "model", "created": 1677649963, "owned_by": "openai:vllm4", "id": "gpt-3.5-turbo-456723", "alias": "gpt-3.5-turbo", "metadata": { "cost": 0.02, "model_family": "gpt-3.5", "region": "us-east-1" } }, { "uuid": "123e0987-d89c-45d6-a789-426614174000", "object": "model", "created": 1677193491, "owned_by": "openai:vllm4", "id": "gpt-4o-mini-2024-07-18", "alias": "gpt-4o-mini", "metadata": { "cost": 0.02, "model_family": "gpt-4o", "region": "us-east-1" } } ] } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/validate": { "servers": [], "post": { "operationId": "validate_provider_credentials", "summary": "Validate Provider Credentials", "tags": [ "Model Gateway" ], "description": "Validates provider credentials before creating a provider instance. Returns 200 OK with valid field indicating success or failure. Supports both direct credentials via the data field and credential references via data_reference. If both are provided, data takes precedence.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvidersValidateRequest" } } }, "description": "Validation Request", "required": true }, "responses": { "200": { "description": "Validation result (check valid field for success/failure)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvidersValidateResponse" }, "examples": { "ProvidersValidationResponse": { "value": { "provider_type": "openai", "valid": true, "message": "Credentials validated successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/watsonxai": { "servers": [], "post": { "tags": [ "Model Gateway" ], "summary": "Create New IBM Watsonx.ai Provider", "description": "Creates a new IBM Watsonx.ai model provider configuration with the supplied details.", "operationId": "create_watsonxai_provider", "requestBody": { "description": "IBM Watsonx.ai provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatsonxAIProviderRequest" } } }, "required": true }, "responses": { "201": { "description": "Created IBM Watsonx.ai provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "NewWatsonxaiProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "my-watsonxai-provider", "type": "watsonxai" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/xai": { "servers": [], "post": { "tags": [ "Model Gateway" ], "summary": "Create New xAI Provider", "description": "Creates a new xAI model provider configuration with the supplied details.", "operationId": "create_xai_provider", "requestBody": { "description": "xAI provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XaiProviderRequest" } } }, "required": true }, "responses": { "201": { "description": "Created xAI provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "NewXaiProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "my-xai-provider", "type": "xai" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/{provider_uuid}": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/provider_uuid" } ], "get": { "tags": [ "Model Gateway" ], "summary": "Get Existing Provider", "description": "Retrieves the details of an existing model provider with the specified UUID.", "operationId": "get_provider", "responses": { "200": { "description": "Provider Details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Provider" }, "examples": { "GetProviderById": { "value": { "uuid": "56c5e703-80d4-4f06-a7e6-844618ec39b3", "name": "vllm4", "type": "openai", "data": { "base_url": "https://api.openai.com/v1", "apikey": "AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe" }, "models": [ { "uuid": "123e4567-e89b-12d3-a456-426614174000", "object": "model", "created": 1677649963, "owned_by": "openai:vllm4", "id": "gpt-3.5-turbo-456723", "alias": "gpt-3.5-turbo", "metadata": { "cost": 0.02, "model_family": "gpt-3.5", "region": "us-east-1" } }, { "uuid": "123e0987-d89c-45d6-a789-426614174000", "object": "model", "created": 1677193491, "owned_by": "openai:vllm4", "id": "gpt-4o-mini-2024-07-18", "alias": "gpt-4o-mini", "metadata": { "cost": 0.02, "model_family": "gpt-4o", "region": "us-east-1" } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "Model Gateway" ], "summary": "Delete Existing Provider", "description": "Deletes an existing model provider configuration with the specified UUID.", "operationId": "delete_provider", "responses": { "204": { "description": "No Content" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/{provider_uuid}/anthropic": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/provider_uuid" } ], "put": { "tags": [ "Model Gateway" ], "summary": "Replace Existing Anthropic Provider", "description": "Replace information for an existing Anthropic provider configuration with new details.", "operationId": "replace_provider_anthropic", "requestBody": { "description": "Replacement Anthropic model provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "Replaced Anthropic provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "ReplacedAnthropicProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "anthropic-prod2", "type": "anthropic" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/{provider_uuid}/azure_openai": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/provider_uuid" } ], "put": { "tags": [ "Model Gateway" ], "summary": "Replace Existing Azure OpenAI Provider", "description": "Replace information for an existing Azure OpenAI provider configuration with new details.", "operationId": "replace_provider_azure_openai", "requestBody": { "description": "Replacement Azure OpenAI model provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AzureOpenAIProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "Replaced Azure OpenAI provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "ReplacedAzureOpenAiProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "azure-provider", "type": "azureOpenai" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/{provider_uuid}/bedrock": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/provider_uuid" } ], "put": { "tags": [ "Model Gateway" ], "summary": "Replace Existing AWS Bedrock Provider", "description": "Replaces information for an existing AWS Bedrock provider configuration with new details.", "operationId": "replace_provider_bedrock", "requestBody": { "description": "Replacement AWS Bedrock model provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AWSBedrockProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "Replaced AWS Bedrock provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "ReplacedAWSBedrockProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "bedrock-provider", "type": "bedrock" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/{provider_uuid}/cerebras": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/provider_uuid" } ], "put": { "tags": [ "Model Gateway" ], "summary": "Replace Existing Cerebras Provider", "description": "Replaces information for an existing Cerebras model provider configuration with new details.", "operationId": "replace_provider_cerebras", "requestBody": { "description": "Replacement Cerebras provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CerebrasProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "Replaced Cerebras provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "ReplacedCerebrasProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "cerebrasProvider2", "type": "cerebras" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/{provider_uuid}/cohere": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/provider_uuid" } ], "put": { "tags": [ "Model Gateway" ], "summary": "Replace Existing Cohere Provider", "description": "Replaces information for an existing Cohere provider configuration with new details.", "operationId": "replace_provider_cohere", "requestBody": { "description": "Replacement Cohere provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "Replaced Cohere provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "ReplacedCohereProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "new-cohere-provider", "type": "cohere" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/{provider_uuid}/gemini": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/provider_uuid" } ], "put": { "tags": [ "Model Gateway" ], "summary": "Replace Existing Gemini Provider", "description": "Replace information for an existing Google Gemini provider configuration with new details.", "operationId": "replace_provider_gemini", "requestBody": { "description": "Replacement Gemini model provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "Replaced Gemini provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "ReplacedGeminiProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "gemini-prod2", "type": "gemini" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/{provider_uuid}/groq": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/provider_uuid" } ], "put": { "tags": [ "Model Gateway" ], "summary": "Replace Existing Groq Provider", "description": "Replace information for an existing Groq provider configuration with new details.", "operationId": "replace_provider_groq", "requestBody": { "description": "Replacement Groq model provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroqProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "Replaced Groq provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "ReplacedGroqProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "groq-prod2", "type": "groq" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/{provider_uuid}/mistral": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/provider_uuid" } ], "put": { "tags": [ "Model Gateway" ], "summary": "Replace Existing Mistral Provider", "description": "Replaces information for an existing Mistral provider configuration with new details.", "operationId": "replace_provider_mistral", "requestBody": { "description": "Replacement Mistral provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MistralProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "Replaced Mistral provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "ReplacedMistralProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "new-mistral-provider", "type": "mistral" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/{provider_uuid}/ollama": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/provider_uuid" } ], "put": { "tags": [ "Model Gateway" ], "summary": "Replace Existing Ollama Provider", "description": "Replaces information for an existing Ollama provider configuration with new details.", "operationId": "replace_provider_ollama", "requestBody": { "description": "Replacement Ollama provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OllamaProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "Replaced Ollama provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "ReplacedOllamaProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "new-ollama-provider", "type": "ollama" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/{provider_uuid}/models": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/provider_uuid" } ], "get": { "tags": [ "Model Gateway" ], "summary": "List Provider Models", "description": "Lists all model configurations for the specified provider.", "operationId": "list_provider_models", "responses": { "200": { "description": "List of Models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelCollection" }, "examples": { "ListModels": { "value": { "object": "list", "data": [ { "uuid": "123e4567-e89b-12d3-a456-426614174000", "object": "model", "created": 1677649963, "owned_by": "openai:vllm4", "id": "gpt-3.5-turbo-456723", "alias": "gpt-3.5-turbo", "metadata": { "cost": 0.02, "model_family": "gpt-3.5", "region": "us-east-1" } }, { "uuid": "123e0987-d89c-45d6-a789-426614174000", "object": "model", "created": 1677193491, "owned_by": "openai:vllm4", "id": "gpt-4o-mini-2024-07-18", "alias": "gpt-4o-mini", "metadata": { "cost": 0.02, "model_family": "gpt-4o", "region": "us-east-1" } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "Model Gateway" ], "summary": "Create New Model", "description": "Creates a new model configuration for the specified provider.", "operationId": "create_provider_model", "requestBody": { "description": "Model Configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateModelRequest" } } }, "required": true }, "responses": { "201": { "description": "Model Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" }, "examples": { "CreateModel": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "object": "model", "created": 1677649963, "owned_by": "openai:vllm4", "id": "gpt-3.5-turbo-456723", "alias": "gpt-3.5-turbo", "metadata": { "cost": 0.02, "model_family": "gpt-3.5", "region": "us-east-1" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/{provider_uuid}/models/{model_uuid}": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/provider_uuid" }, { "$ref": "#/components/parameters/model_uuid" } ], "put": { "tags": [ "Model Gateway" ], "summary": "Replace Existing Model", "description": "Replace an existing model configuration with the specified UUID with the supplied information.", "operationId": "replace_provider_model", "requestBody": { "description": "Replacement model configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceModelRequest" } } }, "required": true }, "responses": { "201": { "description": "Replaced model configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" }, "examples": { "GetGptModelDetails": { "value": { "object": "model", "id": "gpt-3.5-turbo-456723", "alias": "gpt-3.5-turbo", "created": 1677649963, "metadata": { "cost": 0.02, "model_family": "gpt-3.5", "region": "us-east-1" }, "owned_by": "openai:vllm4", "uuid": "123e4567-e89b-12d3-a456-426614174000" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] }, "patch": { "tags": [ "Model Gateway" ], "summary": "Update Existing Model", "description": "Update information for an existing specific model configuration with the specified UUID.", "operationId": "update_provider_model", "requestBody": { "description": "Updated model configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateModelRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated model configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" }, "examples": { "GetGptModelDetails": { "value": { "object": "model", "id": "gpt-3.5-turbo-456723", "alias": "gpt-3.5-turbo", "created": 1677649963, "metadata": { "cost": 0.02, "model_family": "gpt-3.5", "region": "us-east-1" }, "owned_by": "openai:vllm4", "uuid": "123e4567-e89b-12d3-a456-426614174000" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "Model Gateway" ], "summary": "Delete Existing Model", "description": "Deletes an existing model configuration with the specified UUID.", "operationId": "delete_provider_model", "responses": { "204": { "description": "No Content" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/{provider_uuid}/models_available": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/provider_uuid" } ], "get": { "tags": [ "Model Gateway" ], "summary": "List Available Models", "description": "Lists all models available for the specified provider.", "operationId": "list_provider_available_models", "responses": { "200": { "description": "List of Information on Available Models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelCardCollection" }, "examples": { "ListAllModelsAvailable": { "value": { "object": "list", "data": [ { "object": "model", "id": "gpt-3.5-turbo-456723", "created": 1677649963, "owned_by": "openai:vllm4" }, { "object": "model", "id": "gpt-4o", "created": 1677295812, "owned_by": "openai:vllm4" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/{provider_uuid}/nim": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/provider_uuid" } ], "put": { "tags": [ "Model Gateway" ], "summary": "Replace Existing Nvidia NIM Provider", "description": "Replaces information for an existing Nvidia NIM provider configuration with new details.", "operationId": "replace_provider_nim", "requestBody": { "description": "Replacement Nvidia NIM provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NvidiaNIMProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "Replaced Nvidia NIM provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "ReplacedNvidiaNIMProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "my-nim-provider", "type": "nvidiaNim" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/{provider_uuid}/openai": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/provider_uuid" } ], "put": { "tags": [ "Model Gateway" ], "summary": "Replace Existing OpenAI Provider", "description": "Replaces information for an existing OpenAI provider configuration with new details.", "operationId": "replace_provider_openai", "requestBody": { "description": "Replacement OpenAI provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "Replaced OpenAI provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "ReplacedOpenAIProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "new-openai-provider", "type": "openai" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/{provider_uuid}/watsonxai": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/provider_uuid" } ], "put": { "tags": [ "Model Gateway" ], "summary": "Replace Existing IBM Watsonx.ai Provider", "description": "Replaces information for an existing IBM WatsonX.ai provider configuration with new details.", "operationId": "replace_provider_watsonxai", "requestBody": { "description": "Replacement IBM Watsonx.ai provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatsonxAIProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "Replaced IBM WatsonX.ai provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "ReplacedWatsonxaiProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "my-watsonxai-provider2", "type": "watsonxai" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/providers/{provider_uuid}/xai": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/provider_uuid" } ], "put": { "tags": [ "Model Gateway" ], "summary": "Replace Existing xAI Provider", "description": "Replaces information for an existing xAI provider configuration with new details.", "operationId": "replace_provider_xai", "requestBody": { "description": "Replacement xAI provider configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XaiProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "Replaced xAI provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "examples": { "ReplacedXaiProvider": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "new-xai-provider", "type": "xai" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/load_balancers": { "servers": [], "get": { "operationId": "list_load_balancers", "summary": "List Load Balancers", "tags": [ "Model Gateway" ], "description": "Lists all load balancers (both user-defined and system-generated) for the tenant.", "responses": { "200": { "description": "List of Load Balancers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoadBalancersLoadBalancerCollection" }, "examples": { "LoadBalancerCollection": { "value": { "object": "list", "data": [ { "uuid": "550e8400-e29b-41d4-a716-446655440000", "name": "My Load Balancer", "alias": "my-custom-model", "algorithm": "least_connections", "is_user_defined": true, "backends": [ { "id": "backend-550e8400-e29b-41d4-a716-446655440000", "load_balancer_id": "550e8400-e29b-41d4-a716-446655440000", "model_uuid": "550e8400-e29b-41d4-a716-446655440000", "model_id": "llama-3.3-70b", "provider_name": "watsonxai", "alias": "my-custom-model", "status": "active", "priority": 0, "quota": 10, "weight": 1, "created_at": "2023-03-01T12:00:00Z", "updated_at": "2023-03-01T12:00:00Z" } ], "created_at": "2023-03-01T12:00:00Z", "updated_at": "2023-03-01T12:00:00Z" } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] }, "post": { "operationId": "create_load_balancer", "summary": "Create Load Balancer", "tags": [ "Model Gateway" ], "description": "Creates a new user-defined load balancer for the tenant.", "requestBody": { "description": "Load Balancer Creation Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoadBalancersLoadBalancerPrototype" } } }, "required": true }, "responses": { "201": { "description": "Created Load Balancer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoadBalancersLoadBalancer" }, "examples": { "NewLoadBalancer": { "value": { "uuid": "550e8400-e29b-41d4-a716-446655440000", "name": "My Load Balancer", "alias": "my-custom-model", "algorithm": "least_connections", "is_user_defined": true, "backends": [ { "id": "backend-550e8400-e29b-41d4-a716-446655440000", "load_balancer_id": "550e8400-e29b-41d4-a716-446655440000", "model_uuid": "550e8400-e29b-41d4-a716-446655440000", "model_id": "llama-3.3-70b", "provider_name": "watsonxai", "alias": "my-custom-model", "status": "active", "priority": 0, "quota": 10, "weight": 1, "created_at": "2023-03-01T12:00:00Z", "updated_at": "2023-03-01T12:00:00Z" } ], "created_at": "2023-03-01T12:00:00Z", "updated_at": "2023-03-01T12:00:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/load_balancers/{load_balancer_uuid}": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/load_balancer_uuid" } ], "get": { "operationId": "get_load_balancer", "summary": "Get Load Balancer", "tags": [ "Model Gateway" ], "description": "Retrieves a specific load balancer by ID (supports both user-defined and system-generated load balancers).", "responses": { "200": { "description": "Load Balancer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoadBalancersLoadBalancer" }, "examples": { "LoadBalancer": { "value": { "uuid": "550e8400-e29b-41d4-a716-446655440000", "name": "My Load Balancer", "alias": "my-custom-model", "algorithm": "least_connections", "is_user_defined": true, "backends": [ { "id": "backend-550e8400-e29b-41d4-a716-446655440000", "load_balancer_id": "550e8400-e29b-41d4-a716-446655440000", "model_uuid": "550e8400-e29b-41d4-a716-446655440000", "model_id": "llama-3.3-70b", "provider_name": "watsonxai", "alias": "my-custom-model", "status": "active", "priority": 0, "quota": 10, "weight": 1, "created_at": "2023-03-01T12:00:00Z", "updated_at": "2023-03-01T12:00:00Z" } ], "created_at": "2023-03-01T12:00:00Z", "updated_at": "2023-03-01T12:00:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] }, "put": { "operationId": "replace_load_balancer", "summary": "Update Load Balancer", "tags": [ "Model Gateway" ], "description": "Updates an existing user-defined load balancer by ID.", "requestBody": { "description": "Load Balancer update request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoadBalancersUpdateLoadBalancerRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated Load Balancer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoadBalancersLoadBalancer" }, "examples": { "LoadBalancer": { "value": { "uuid": "550e8400-e29b-41d4-a716-446655440000", "name": "My Load Balancer", "alias": "my-custom-model", "algorithm": "least_connections", "is_user_defined": true, "backends": [ { "id": "backend-550e8400-e29b-41d4-a716-446655440000", "load_balancer_id": "550e8400-e29b-41d4-a716-446655440000", "model_uuid": "550e8400-e29b-41d4-a716-446655440000", "model_id": "llama-3.3-70b", "provider_name": "watsonxai", "alias": "my-custom-model", "status": "active", "priority": 0, "quota": 10, "weight": 1, "created_at": "2023-03-01T12:00:00Z", "updated_at": "2023-03-01T12:00:00Z" } ], "created_at": "2023-03-01T12:00:00Z", "updated_at": "2023-03-01T12:00:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] }, "delete": { "operationId": "delete_load_balancer", "summary": "Delete Load Balancer", "tags": [ "Model Gateway" ], "description": "Removes a user-defined load balancer by ID.", "responses": { "204": { "description": "No Content" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/load_balancers/{load_balancer_uuid}/backends": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/load_balancer_uuid" } ], "get": { "operationId": "list_load_balancer_backends", "summary": "List Backends", "tags": [ "Model Gateway" ], "description": "Lists all backends for the specified load balancer.", "responses": { "200": { "description": "List of Backends", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoadBalancersBackendCollection" }, "examples": { "LoadBalancerBackendCollection": { "value": { "object": "list", "data": [ { "id": "backend-550e8400-e29b-41d4-a716-446655440000", "load_balancer_id": "550e8400-e29b-41d4-a716-446655440000", "model_uuid": "550e8400-e29b-41d4-a716-446655440000", "model_id": "llama-3.3-70b", "provider_name": "watsonxai", "alias": "my-custom-model", "status": "active", "priority": 0, "quota": 10, "weight": 1, "created_at": "2023-03-01T12:00:00Z", "updated_at": "2023-03-01T12:00:00Z" } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] }, "post": { "operationId": "create_load_balancer_backend", "summary": "Create Backend", "tags": [ "Model Gateway" ], "description": "Creates a new backend for the specified load balancer.", "requestBody": { "description": "Backend configuration", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoadBalancersBackendPrototype" } } } }, "responses": { "201": { "description": "Created Load Balancer Backend", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoadBalancersBackend" }, "examples": { "LoadBalancerBackend": { "value": { "id": "backend-550e8400-e29b-41d4-a716-446655440000", "load_balancer_id": "550e8400-e29b-41d4-a716-446655440000", "model_uuid": "550e8400-e29b-41d4-a716-446655440000", "model_id": "llama-3.3-70b", "provider_name": "watsonxai", "alias": "my-custom-model", "status": "active", "priority": 0, "quota": 10, "weight": 1, "created_at": "2023-03-01T12:00:00Z", "updated_at": "2023-03-01T12:00:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "$ref": "#/components/responses/ConflictError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/load_balancers/{load_balancer_uuid}/backends/{load_balancer_backend_uuid}": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/load_balancer_uuid" }, { "$ref": "#/components/parameters/load_balancer_backend_uuid" } ], "get": { "operationId": "get_load_balancer_backend", "summary": "Get Load Balancer Backend", "tags": [ "Model Gateway" ], "description": "Retrieves a specific load balancer backend by ID from a load balancer.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoadBalancersBackend" }, "examples": { "LoadBalancerBackend": { "value": { "id": "backend-550e8400-e29b-41d4-a716-446655440000", "load_balancer_id": "550e8400-e29b-41d4-a716-446655440000", "model_uuid": "550e8400-e29b-41d4-a716-446655440000", "model_id": "llama-3.3-70b", "provider_name": "watsonxai", "alias": "my-custom-model", "status": "active", "priority": 0, "quota": 10, "weight": 1, "created_at": "2023-03-01T12:00:00Z", "updated_at": "2023-03-01T12:00:00Z" } } } } }, "description": "Load Balancer Backend Configuration" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] }, "put": { "operationId": "replace_load_balancer_backend", "summary": "Replace Load Balancer Backend", "tags": [ "Model Gateway" ], "description": "Replaces a load balancer backend's configuration (currently only weight).", "requestBody": { "description": "Replacement Load Balancer Backend Configuration", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoadBalancersUpdateBackendRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoadBalancersBackend" }, "examples": { "LoadBalancerBackend": { "value": { "id": "backend-550e8400-e29b-41d4-a716-446655440000", "load_balancer_id": "550e8400-e29b-41d4-a716-446655440000", "model_uuid": "550e8400-e29b-41d4-a716-446655440000", "model_id": "llama-3.3-70b", "provider_name": "watsonxai", "alias": "my-custom-model", "status": "active", "priority": 0, "quota": 10, "weight": 1, "created_at": "2023-03-01T12:00:00Z", "updated_at": "2023-03-01T12:00:00Z" } } } } }, "description": "Updated Backend" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] }, "delete": { "operationId": "delete_load_balancer_backend", "summary": "Delete Load Balancer Backend", "tags": [ "Model Gateway" ], "description": "Removes a load balancer backend from the specified load balancer.", "responses": { "204": { "description": "Load Balancer Backend Deleted" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/rate_limits": { "servers": [], "get": { "operationId": "list_rate_limits", "summary": "List Rate Limit Configurations", "tags": [ "Model Gateway" ], "description": "Lists all rate limit configurations for the tenant making the request.", "responses": { "200": { "description": "List of rate limit configurations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitCollection" }, "examples": { "RateLimits": { "value": { "object": "list", "data": [ { "uuid": "123e4567-e89b-12d3-a456-426614174000", "type": "tenant", "request": { "amount": 10, "capacity": 100, "duration": "1m" }, "token": { "amount": 10, "capacity": 100, "duration": "1m" } }, { "uuid": "123e4567-e89b-12d3-a456-426614174000", "type": "provider", "provider_uuid": "123e4567-e89b-12d3-a456-426614174000", "request": { "amount": 10, "capacity": 100, "duration": "1m" }, "token": { "amount": 10, "capacity": 100, "duration": "1m" } }, { "uuid": "123e4567-e89b-12d3-a456-426614174000", "type": "model", "model_uuid": "123e4567-e89b-12d3-a456-426614174000", "request": { "amount": 10, "capacity": 100, "duration": "1m" }, "token": { "amount": 10, "capacity": 100, "duration": "1m" } } ], "has_more": true, "next_page": "https://gateway-url/v1/rate_limits?page=2" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] }, "post": { "operationId": "create_rate_limit", "summary": "Create Rate Limit Configuration", "tags": [ "Model Gateway" ], "description": "Creates a new rate limit configuration for the tenant making the request.", "requestBody": { "description": "Rate limit Configuration", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitPrototype" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimit" }, "examples": { "TenantRateLimit": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "type": "tenant", "request": { "amount": 10, "capacity": 100, "duration": "1m" }, "token": { "amount": 10, "capacity": 100, "duration": "1m" } } }, "ProviderRateLimit": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "type": "provider", "provider_uuid": "123e4567-e89b-12d3-a456-426614174000", "request": { "amount": 10, "capacity": 100, "duration": "1m" }, "token": { "amount": 10, "capacity": 100, "duration": "1m" } } }, "ModelRateLimit": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "type": "model", "model_uuid": "123e4567-e89b-12d3-a456-426614174000", "request": { "amount": 10, "capacity": 100, "duration": "1m" }, "token": { "amount": 10, "capacity": 100, "duration": "1m" } } } } } }, "description": "Rate limit created successfully" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/rate_limits/{ratelimit_uuid}": { "servers": [], "parameters": [ { "$ref": "#/components/parameters/rate_limit_uuid" } ], "get": { "operationId": "get_rate_limit", "summary": "Get Rate Limit Configuration", "tags": [ "Model Gateway" ], "description": "Retrieves the current rate limit configuration for the tenant making the request.", "responses": { "200": { "description": "Rate limit configuration retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimit" }, "examples": { "TenantRateLimit": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "type": "tenant", "request": { "amount": 10, "capacity": 100, "duration": "1m" }, "token": { "amount": 10, "capacity": 100, "duration": "1m" } } }, "ProviderRateLimit": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "type": "provider", "provider_uuid": "123e4567-e89b-12d3-a456-426614174000", "request": { "amount": 10, "capacity": 100, "duration": "1m" }, "token": { "amount": 10, "capacity": 100, "duration": "1m" } } }, "ModelRateLimit": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "type": "model", "model_uuid": "123e4567-e89b-12d3-a456-426614174000", "request": { "amount": 10, "capacity": 100, "duration": "1m" }, "token": { "amount": 10, "capacity": 100, "duration": "1m" } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] }, "put": { "operationId": "replace_rate_limit", "summary": "Replace Rate Limit Configuration", "tags": [ "Model Gateway" ], "description": "Replaces the rate limit configuration for the tenant making the request.", "requestBody": { "description": "Replacement Rate Limit Configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitPrototype" } } }, "required": true }, "responses": { "200": { "description": "Rate Limit Configuration Replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimit" }, "examples": { "TenantRateLimit": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "type": "tenant", "request": { "amount": 10, "capacity": 100, "duration": "1m" }, "token": { "amount": 10, "capacity": 100, "duration": "1m" } } }, "ProviderRateLimit": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "type": "provider", "provider_uuid": "123e4567-e89b-12d3-a456-426614174000", "request": { "amount": 10, "capacity": 100, "duration": "1m" }, "token": { "amount": 10, "capacity": 100, "duration": "1m" } } }, "ModelRateLimit": { "value": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "type": "model", "model_uuid": "123e4567-e89b-12d3-a456-426614174000", "request": { "amount": 10, "capacity": 100, "duration": "1m" }, "token": { "amount": 10, "capacity": 100, "duration": "1m" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] }, "delete": { "operationId": "delete_rate_limit", "summary": "Delete Rate Limit Configuration", "tags": [ "Model Gateway" ], "description": "Deletes the rate limit configuration identified by the provided UUID for the tenant making the request.", "responses": { "204": { "description": "Rate Limit Configuration Deleted" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/responses": { "servers": [], "post": { "tags": [ "Model Gateway" ], "summary": "Create Response", "description": "Creates a model response using the OpenAI-compatible Responses API.", "operationId": "create_response", "requestBody": { "description": "Create Response Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateResponseRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseResource" }, "examples": { "Response": { "value": { "id": "resp_123", "object": "response", "created_at": 1704067200, "model": "openai:gpt-4o-mini", "status": "completed", "output": [] } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/usage": { "servers": [], "get": { "tags": [ "Model Gateway" ], "summary": "Get Tenant Usage", "description": "Retrieves aggregated usage statistics associated with the tenant making the request.", "operationId": "get_tenant_usage", "parameters": [ { "name": "start_time", "in": "query", "description": "Start time in Unix seconds", "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 4102444800 } }, { "name": "end_time", "in": "query", "description": "End time in Unix seconds", "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 4102444800 } }, { "name": "bucket_width", "in": "query", "description": "Bucket width for aggregation: 1m, 1h, 1d (default 1d)", "schema": { "type": "string" } }, { "name": "group_by", "in": "query", "description": "Fields to group results by (e.g., user_uuid, model, service_provider, credential_uuid, usage_type, load_balancer_uuid, load_balancer_alias)", "schema": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 20 } }, { "name": "limit", "in": "query", "description": "Maximum number of buckets to return (default 10)", "schema": { "type": "integer", "format": "int64", "default": 10, "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "description": "Pagination cursor from previous request", "schema": { "type": "string" } }, { "name": "user_ids", "in": "query", "description": "Filter by user UUIDs (use 'self' for current user)", "schema": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 100 } }, { "name": "models", "in": "query", "description": "Filter by model names", "schema": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 100 } }, { "name": "usage_types", "in": "query", "description": "Filter by usage types (e.g., completion, embedding, moderation, image)", "schema": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 20 } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketEntryCollection" }, "examples": { "TenantUsage": { "value": { "object": "list", "data": [ { "object": "bucket", "start_time": 1704067200, "end_time": 1704153600, "results": [ { "object": "organization.usage.completions.result", "input_tokens": 120, "output_tokens": 42, "num_model_requests": 3 } ] } ], "has_more": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/ml/gateway/v1/usage/user": { "servers": [], "get": { "tags": [ "Model Gateway" ], "summary": "Get User Usage", "description": "Retrieves aggregated usage statistics associated with the current user under the tenant.", "operationId": "get_user_usage", "parameters": [ { "name": "start_time", "in": "query", "description": "Start time in Unix seconds", "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 4102444800 } }, { "name": "end_time", "in": "query", "description": "End time in Unix seconds", "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 4102444800 } }, { "name": "bucket_width", "in": "query", "description": "Bucket width for aggregation: 1m, 1h, 1d (default 1d)", "schema": { "type": "string" } }, { "name": "group_by", "in": "query", "description": "Fields to group results by (e.g., user_uuid, model, service_provider, credential_uuid, usage_type, load_balancer_uuid, load_balancer_alias)", "schema": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 20 } }, { "name": "limit", "in": "query", "description": "Maximum number of buckets to return (default 10)", "schema": { "type": "integer", "format": "int64", "default": 10, "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "description": "Pagination cursor from previous request", "schema": { "type": "string" } }, { "name": "user_ids", "in": "query", "description": "Filter by user UUIDs (use 'self' for current user)", "schema": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 100 } }, { "name": "models", "in": "query", "description": "Filter by model names", "schema": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 100 } }, { "name": "usage_types", "in": "query", "description": "Filter by usage types (completion, embedding)", "schema": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 20 } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketEntryCollection" }, "examples": { "UserUsage": { "value": { "object": "list", "data": [ { "object": "bucket", "start_time": 1704067200, "end_time": 1704153600, "results": [ { "object": "organization.usage.completions.result", "input_tokens": 120, "output_tokens": 42, "num_model_requests": 3 } ] } ], "has_more": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "Bearer": [] } ] } }, "/v1/prompt_sessions": { "servers": [ { "url": "https://{region}.dataplatform.cloud.ibm.com/wx", "variables": { "region": { "default": "api", "enum": [ "api", "api.eu-de", "api.eu-gb", "api.jp-tok" ] } } } ], "post": { "tags": [ "Prompt Sessions" ], "summary": "Create a new prompt session", "description": "This creates a new prompt session.", "operationId": "post_prompt_session", "x-cli-command": "create", "parameters": [ { "$ref": "#/components/parameters/project_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wxPromptSession" } } }, "required": true }, "responses": { "201": { "description": "Created - Returned when created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wxPromptResponse" } } } }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } } }, "/v1/prompt_sessions/{session_id}": { "servers": [ { "url": "https://{region}.dataplatform.cloud.ibm.com/wx", "variables": { "region": { "default": "api", "enum": [ "api", "api.eu-de", "api.eu-gb", "api.jp-tok" ] } } } ], "get": { "tags": [ "Prompt Sessions" ], "summary": "Get a prompt session", "description": "This retrieves a prompt session with the given id.", "operationId": "get_prompt_session", "x-cli-command": "get", "parameters": [ { "$ref": "#/components/parameters/session_id" }, { "$ref": "#/components/parameters/project_id" }, { "name": "prefetch", "in": "query", "description": "Include the most recent entry", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK - Returned from GET when it succeeds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wxPromptSession" } } } }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } }, "patch": { "tags": [ "Prompt Sessions" ], "summary": "Update a prompt session", "description": "This updates a prompt session with the given id.", "operationId": "patch_prompt_session", "x-cli-command": "update", "parameters": [ { "$ref": "#/components/parameters/session_id" }, { "$ref": "#/components/parameters/project_id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": "^.{0,100}$", "example": "Session 1" }, "description": { "type": "string", "pattern": "^[\\s\\S]{0,250}", "description": "An optional description for the prompt.", "example": "My First Prompt Session" } } } } }, "required": true }, "responses": { "200": { "description": "OK - Returned from GET when it succeeds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wxPromptSession" } } } }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } }, "delete": { "tags": [ "Prompt Sessions" ], "summary": "Delete a prompt session", "description": "This deletes a prompt session with the given id.", "operationId": "delete_prompt_session", "x-cli-command": "delete", "parameters": [ { "$ref": "#/components/parameters/session_id" }, { "$ref": "#/components/parameters/project_id" } ], "responses": { "204": { "description": "No Content - Returned on success" }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } } }, "/v1/prompt_sessions/{session_id}/entries": { "servers": [ { "url": "https://{region}.dataplatform.cloud.ibm.com/wx", "variables": { "region": { "default": "api", "enum": [ "api", "api.eu-de", "api.eu-gb", "api.jp-tok" ] } } } ], "post": { "tags": [ "Prompt Sessions" ], "summary": "Add a new prompt to a prompt session", "description": "This creates a new prompt associated with the given session.", "operationId": "post_prompt_session_entry", "x-cli-command": "add-entry", "parameters": [ { "$ref": "#/components/parameters/session_id" }, { "$ref": "#/components/parameters/project_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wxPromptSessionEntry" } } }, "required": true }, "responses": { "201": { "description": "Created - Returned when created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wxPromptSessionEntry" } } } }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } }, "get": { "tags": [ "Prompt Sessions" ], "summary": "Get entries for a prompt session", "description": "List entries from a given session.", "operationId": "get_prompt_session_entries", "x-cli-command": "list-entries", "parameters": [ { "$ref": "#/components/parameters/session_id" }, { "$ref": "#/components/parameters/project_id" }, { "name": "bookmark", "in": "query", "description": "Bookmark from a previously limited get request", "required": false, "schema": { "type": "string", "pattern": "[a-zA-Z0-9-]*" } }, { "name": "limit", "in": "query", "description": "Limit for results to retrieve, default 20", "required": false, "schema": { "type": "string", "pattern": "[a-zA-Z0-9-]*" } } ], "responses": { "200": { "description": "Success - Returned when search completes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wxPromptSessionEntryList" } } } }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } } }, "/v1/prompt_sessions/{session_id}/entries/{entry_id}/chat_items": { "servers": [ { "url": "https://{region}.dataplatform.cloud.ibm.com/wx", "variables": { "region": { "default": "api", "enum": [ "api", "api.eu-de", "api.eu-gb", "api.jp-tok" ] } } } ], "post": { "tags": [ "Prompt Sessions" ], "summary": "Add a new chat item to a prompt session entry", "description": "This adds new chat items to the given entry.", "operationId": "post_prompt_session_entry_chat_item", "x-cli-command": "add-chat-item", "parameters": [ { "$ref": "#/components/parameters/session_id" }, { "$ref": "#/components/parameters/entry_id" }, { "$ref": "#/components/parameters/project_id" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "An array containing a question chat item and an answer chat item.", "type": "array", "items": { "$ref": "#/components/schemas/chatItem" }, "minItems": 2, "maxItems": 2 } } }, "required": true }, "responses": { "201": { "description": "Created - Returned when created" }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } } }, "/v1/prompt_sessions/{session_id}/lock": { "servers": [ { "url": "https://{region}.dataplatform.cloud.ibm.com/wx", "variables": { "region": { "default": "api", "enum": [ "api", "api.eu-de", "api.eu-gb", "api.jp-tok" ] } } } ], "put": { "tags": [ "Prompt Sessions" ], "summary": "Prompt session lock modifications", "description": "Modifies the current locked state of a prompt session.", "operationId": "put_prompt_session_lock", "x-cli-command": "update-lock", "parameters": [ { "$ref": "#/components/parameters/session_id" }, { "$ref": "#/components/parameters/project_id" }, { "name": "force", "in": "query", "description": "Override a lock if it is currently taken.", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/promptLock" } } }, "required": true }, "responses": { "200": { "description": "Ok - Returned when lock change is successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/promptLock" } } } }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } }, "get": { "tags": [ "Prompt Sessions" ], "summary": "Get current prompt session lock status", "description": "Retrieves the current locked state of a prompt session.", "operationId": "get_prompt_session_lock", "x-cli-command": "get-lock", "parameters": [ { "$ref": "#/components/parameters/session_id" }, { "$ref": "#/components/parameters/project_id" } ], "responses": { "200": { "description": "Ok - Returned on success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/promptLock" } } } }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } } }, "/v1/prompt_sessions/{session_id}/entries/{entry_id}": { "servers": [ { "url": "https://{region}.dataplatform.cloud.ibm.com/wx", "variables": { "region": { "default": "api", "enum": [ "api", "api.eu-de", "api.eu-gb", "api.jp-tok" ] } } } ], "get": { "tags": [ "Prompt Sessions" ], "summary": "Get a prompt session entry", "description": "This retrieves a prompt session entry with the given id.", "operationId": "get_prompt_session_entry", "x-cli-command": "get-entry", "parameters": [ { "$ref": "#/components/parameters/session_id" }, { "$ref": "#/components/parameters/project_id" }, { "$ref": "#/components/parameters/entry_id" } ], "responses": { "200": { "description": "OK - Returned from GET when it succeeds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wxPromptResponse" } } } }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } }, "delete": { "tags": [ "Prompt Sessions" ], "summary": "Delete a prompt session entry", "description": "This deletes a prompt session entry with the given id.", "operationId": "delete_prompt_session_entry", "x-cli-command": "delete-entry", "parameters": [ { "$ref": "#/components/parameters/session_id" }, { "$ref": "#/components/parameters/project_id" }, { "$ref": "#/components/parameters/entry_id" } ], "responses": { "204": { "description": "No Content - Returned on success" }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } } }, "/v1/prompts": { "servers": [ { "url": "https://{region}.dataplatform.cloud.ibm.com/wx", "variables": { "region": { "default": "api", "enum": [ "api", "api.eu-de", "api.eu-gb", "api.jp-tok" ] } } } ], "post": { "tags": [ "Prompts" ], "summary": "Create a new prompt / prompt template", "description": "This creates a new prompt with the provided parameters.", "operationId": "post_prompt", "x-cli-command": "create", "parameters": [ { "$ref": "#/components/parameters/project_id" }, { "$ref": "#/components/parameters/space_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wxPromptPost" } } }, "required": true }, "responses": { "201": { "description": "Created - Returned when created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wxPromptResponse" } } } }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } } }, "/v1/prompts/{prompt_id}": { "servers": [ { "url": "https://{region}.dataplatform.cloud.ibm.com/wx", "variables": { "region": { "default": "api", "enum": [ "api", "api.eu-de", "api.eu-gb", "api.jp-tok" ] } } } ], "get": { "tags": [ "Prompts" ], "summary": "Get a prompt", "description": "This retrieves a prompt / prompt template with the given id.", "operationId": "get_prompt", "x-cli-command": "get", "parameters": [ { "$ref": "#/components/parameters/project_id" }, { "$ref": "#/components/parameters/space_id" }, { "$ref": "#/components/parameters/prompt_id" }, { "$ref": "#/components/parameters/restrict_model_parameters" } ], "responses": { "200": { "description": "OK - Returned from GET when it succeeds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wxPromptResponse" } } } }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } }, "patch": { "tags": [ "Prompts" ], "summary": "Update a prompt", "description": "This updates a prompt / prompt template with the given id.", "operationId": "patch_prompt", "x-cli-command": "update", "parameters": [ { "$ref": "#/components/parameters/project_id" }, { "$ref": "#/components/parameters/space_id" }, { "$ref": "#/components/parameters/prompt_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wxPromptPatch" } } }, "required": true }, "responses": { "200": { "description": "OK - Returned on success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wxPromptResponse" } } } }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } }, "delete": { "tags": [ "Prompts" ], "summary": "Delete a prompt", "description": "This deletes a prompt / prompt template with the given id.", "operationId": "delete_prompt", "x-cli-command": "delete", "parameters": [ { "$ref": "#/components/parameters/project_id" }, { "$ref": "#/components/parameters/space_id" }, { "$ref": "#/components/parameters/prompt_id" } ], "responses": { "204": { "description": "No Content - Returned on success" }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } } }, "/v1/prompts/{prompt_id}/lock": { "servers": [ { "url": "https://{region}.dataplatform.cloud.ibm.com/wx", "variables": { "region": { "default": "api", "enum": [ "api", "api.eu-de", "api.eu-gb", "api.jp-tok" ] } } } ], "put": { "tags": [ "Prompts" ], "summary": "Prompt lock modifications", "description": "Modifies the current locked state of a prompt.", "operationId": "put_prompt_lock", "x-cli-command": "update-lock", "parameters": [ { "$ref": "#/components/parameters/prompt_id" }, { "$ref": "#/components/parameters/project_id" }, { "$ref": "#/components/parameters/space_id" }, { "name": "force", "in": "query", "description": "Override a lock if it is currently taken.", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/promptLock" } } }, "required": true }, "responses": { "200": { "description": "Ok - Returned when lock change is successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/promptLock" } } } }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } }, "get": { "tags": [ "Prompts" ], "summary": "Get current prompt lock status", "description": "Retrieves the current locked state of a prompt.", "operationId": "get_prompt_lock", "x-cli-command": "get-lock", "parameters": [ { "$ref": "#/components/parameters/prompt_id" }, { "$ref": "#/components/parameters/space_id" }, { "$ref": "#/components/parameters/project_id" } ], "responses": { "200": { "description": "Ok - Returned on success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/promptLock" } } } }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } } }, "/v1/prompts/{prompt_id}/input": { "servers": [ { "url": "https://{region}.dataplatform.cloud.ibm.com/wx", "variables": { "region": { "default": "api", "enum": [ "api", "api.eu-de", "api.eu-gb", "api.jp-tok" ] } } } ], "post": { "tags": [ "Prompts" ], "summary": "Get the inference input string for a given prompt", "description": "Computes the inference input string based on state of a prompt. Optionally replaces template params", "operationId": "get_prompt_input", "x-cli-command": "get-input", "parameters": [ { "$ref": "#/components/parameters/prompt_id" }, { "$ref": "#/components/parameters/space_id" }, { "$ref": "#/components/parameters/project_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wxPromptInputRequest" } } }, "required": false }, "responses": { "200": { "description": "Ok - Returned on success", "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The prompt's input string used for inferences." } } } } } }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } } }, "/v1/prompts/{prompt_id}/chat_items": { "servers": [ { "url": "https://{region}.dataplatform.cloud.ibm.com/wx", "variables": { "region": { "default": "api", "enum": [ "api", "api.eu-de", "api.eu-gb", "api.jp-tok" ] } } } ], "post": { "tags": [ "Prompts" ], "summary": "Add a new chat item to a prompt", "description": "This adds new chat items to the given prompt.", "operationId": "post_prompt_chat_item", "x-cli-command": "add-chat-item", "parameters": [ { "$ref": "#/components/parameters/prompt_id" }, { "$ref": "#/components/parameters/space_id" }, { "$ref": "#/components/parameters/project_id" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "An array containing a question chat item and an answer chat item.", "type": "array", "items": { "$ref": "#/components/schemas/chatItem" }, "minItems": 2, "maxItems": 2 } } }, "required": true }, "responses": { "200": { "description": "Ok - Returned on success" }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } } }, "/v1/vector_indexes": { "servers": [], "post": { "tags": [ "Vector Indexes" ], "summary": "Create a vector index.", "description": "This creates a new vector index with the provided parameters.", "operationId": "post_vector_index", "x-cli-command": "create-vector-index", "parameters": [ { "$ref": "#/components/parameters/project_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wxVectorIndexPost" } } }, "required": true }, "responses": { "201": { "description": "Created - Returned when created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vectorIndexResponse" }, "examples": { "get_vector_indexes": { "summary": "create_vector_index", "description": "Create a vector index.", "value": { "id": "43499a2a-7656-43d6-8ce0-374d34449d4f", "name": "Milvus-VI-New", "description": "", "created_at": 1739888788777, "created_by": "IBMid-6910003SE8", "last_updated_at": 1739888804362, "last_updated_by": "IBMid-6910003SE8", "data_assets": [ "9624a20d-ecd0-450e-b7d2-9941ce7d1c57" ], "store": { "type": "watsonx.data", "connection_id": "9bdb5dbe-d896-4539-b969-5bf17fcc1f0a", "index": "wx_test_collection_japanese", "new_index": true, "database": "default" }, "settings": { "chunk_size": 2000, "chunk_overlap": 200, "split_pdf_pages": true, "top_k": 3, "rerank": false, "embedding_model_id": "sentence-transformers/all-minilm-l6-v2", "schema_fields": { "document_name": "document_name", "text": "text", "page_number": "page" } }, "build": { "notebook_id": "53a61d7d-7d09-4392-9d5d-eb90e46aee1c", "job_id": "843e36f9-3550-4b0c-8755-4976e41bce35" }, "status": "ready" } } } } } }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } } }, "/v1/vector_indexes/{index_id}": { "servers": [], "get": { "tags": [ "Vector Indexes" ], "summary": "Get a vector index", "description": "This retrieves a vector index with the given id.", "operationId": "get_vector_index", "x-cli-command": "get-vector-index", "parameters": [ { "$ref": "#/components/parameters/project_id" }, { "$ref": "#/components/parameters/index_id" } ], "responses": { "200": { "description": "OK - Returned from GET when it succeeds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vectorIndexResponse" }, "examples": { "get_vector_indexes": { "summary": "get_vector_indexes", "description": "Get vector index.", "value": { "id": "43499a2a-7656-43d6-8ce0-374d34449d4f", "name": "Milvus-VI-New", "description": "", "created_at": 1739888788777, "created_by": "IBMid-6910003SE8", "last_updated_at": 1739888804362, "last_updated_by": "IBMid-6910003SE8", "data_assets": [ "9624a20d-ecd0-450e-b7d2-9941ce7d1c57" ], "store": { "type": "watsonx.data", "connection_id": "9bdb5dbe-d896-4539-b969-5bf17fcc1f0a", "index": "wx_test_collection_japanese", "new_index": true, "database": "default" }, "settings": { "chunk_size": 2000, "chunk_overlap": 200, "split_pdf_pages": true, "top_k": 3, "rerank": false, "embedding_model_id": "sentence-transformers/all-minilm-l6-v2", "schema_fields": { "document_name": "document_name", "text": "text", "page_number": "page" } }, "build": { "notebook_id": "53a61d7d-7d09-4392-9d5d-eb90e46aee1c", "job_id": "843e36f9-3550-4b0c-8755-4976e41bce35" }, "status": "ready" } } } } } }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } }, "patch": { "tags": [ "Vector Indexes" ], "summary": "Update a vector index", "description": "This updates a vector index with the given id.", "operationId": "patch_vector_index", "x-cli-command": "update-vector-index", "parameters": [ { "$ref": "#/components/parameters/project_id" }, { "$ref": "#/components/parameters/index_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wxVectorIndexPatch" } } }, "required": true }, "responses": { "200": { "description": "OK - Returned from GET when it succeeds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vectorIndexResponse" }, "examples": { "get_vector_indexes": { "summary": "patch_vector_indexes", "description": "Response with updated vector index.", "value": { "id": "43499a2a-7656-43d6-8ce0-374d34449d4f", "name": "Milvus-VI-Patched", "description": "", "created_at": 1739888788777, "created_by": "IBMid-6910003SE8", "last_updated_at": 1739888804362, "last_updated_by": "IBMid-6910003SE8", "data_assets": [ "9624a20d-ecd0-450e-b7d2-9941ce7d1c57" ], "store": { "type": "watsonx.data", "connection_id": "9bdb5dbe-d896-4539-b969-5bf17fcc1f0a", "index": "wx_test_collection_japanese", "new_index": true, "database": "default" }, "settings": { "chunk_size": 2000, "chunk_overlap": 200, "split_pdf_pages": true, "top_k": 3, "rerank": false, "embedding_model_id": "sentence-transformers/all-minilm-l6-v2", "schema_fields": { "document_name": "document_name", "text": "text", "page_number": "page" } }, "build": { "notebook_id": "53a61d7d-7d09-4392-9d5d-eb90e46aee1c", "job_id": "843e36f9-3550-4b0c-8755-4976e41bce35" }, "status": "ready" } } } } } }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } }, "delete": { "tags": [ "Vector Indexes" ], "summary": "Delete a vector index", "description": "This deletes a vector index with the given id.", "operationId": "delete_vector_index", "x-cli-command": "delete-vector-index", "parameters": [ { "$ref": "#/components/parameters/project_id" }, { "$ref": "#/components/parameters/index_id" } ], "responses": { "204": { "description": "No Content - Returned on success" }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } } }, "/v1/vector_indexes/{index_id}/attachment": { "servers": [], "put": { "tags": [ "Vector Indexes" ], "summary": "Vector Index attachments modifications", "description": "TO BE USED ONLY WITH IN-MEMORY VECTOR STORE. This is to update the attachments/objects associated with the vector index.", "operationId": "put_vector_indexes", "x-cli-command": "update-attachments", "parameters": [ { "$ref": "#/components/parameters/index_id" }, { "$ref": "#/components/parameters/project_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wxVectorIndexPut" } } }, "required": true }, "responses": { "200": { "description": "Ok - Returned when the attachment is successfull.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vectorIndexResponse" } } } }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } } }, "/v1/transactional_vector_indexes": { "servers": [], "post": { "tags": [ "Vector Indexes - transactional API" ], "summary": "Create a vector index.", "description": "This creates a new vector index with the provided parameters.", "operationId": "post_vector_index_transactional", "x-cli-command": "create-vector-index", "parameters": [ { "$ref": "#/components/parameters/project_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wxVectorIndexTransactionalPost" } } }, "required": true }, "responses": { "201": { "description": "Created - Returned when created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vectorIndexResponse" }, "examples": { "get_vector_indexes": { "summary": "create_vector_index", "description": "Create a vector index.", "value": { "id": "43499a2a-7656-43d6-8ce0-374d34449d4f", "name": "Milvus-VI-New", "description": "", "created_at": 1739888788777, "created_by": "IBMid-6910003SE8", "last_updated_at": 1739888804362, "last_updated_by": "IBMid-6910003SE8", "data_assets": [ "9624a20d-ecd0-450e-b7d2-9941ce7d1c57" ], "store": { "type": "watsonx.data", "connection_id": "9bdb5dbe-d896-4539-b969-5bf17fcc1f0a", "index": "wx_test_collection_japanese", "new_index": true, "database": "default" }, "settings": { "chunk_size": 2000, "chunk_overlap": 200, "split_pdf_pages": true, "top_k": 3, "rerank": false, "embedding_model_id": "sentence-transformers/all-minilm-l6-v2", "schema_fields": { "document_name": "document_name", "text": "text", "page_number": "page" } }, "build": { "notebook_id": "53a61d7d-7d09-4392-9d5d-eb90e46aee1c", "job_id": "843e36f9-3550-4b0c-8755-4976e41bce35" }, "status": "ready" } } } } } }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } } }, "/v1/transactional_vector_indexes/{index_id}": { "servers": [], "patch": { "tags": [ "Vector Indexes - transactional API" ], "summary": "Update a vector index", "description": "This updates a vector index with the given id.", "operationId": "patch_vector_index_transactional", "x-cli-command": "update-vector-index", "parameters": [ { "$ref": "#/components/parameters/project_id" }, { "$ref": "#/components/parameters/index_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wxVectorIndexPatch" } } }, "required": true }, "responses": { "200": { "description": "OK - Returned from GET when it succeeds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vectorIndexResponse" }, "examples": { "get_vector_indexes": { "summary": "patch_vector_index_transactional", "description": "Response with updated vector index.", "value": { "id": "43499a2a-7656-43d6-8ce0-374d34449d4f", "name": "Milvus-VI-Patched", "description": "", "created_at": 1739888788777, "created_by": "IBMid-6910003SE8", "last_updated_at": 1739888804362, "last_updated_by": "IBMid-6910003SE8", "data_assets": [ "9624a20d-ecd0-450e-b7d2-9941ce7d1c57" ], "store": { "type": "watsonx.data", "connection_id": "9bdb5dbe-d896-4539-b969-5bf17fcc1f0a", "index": "wx_test_collection_japanese", "new_index": true, "database": "default" }, "settings": { "chunk_size": 2000, "chunk_overlap": 200, "split_pdf_pages": true, "top_k": 3, "rerank": false, "embedding_model_id": "sentence-transformers/all-minilm-l6-v2", "schema_fields": { "document_name": "document_name", "text": "text", "page_number": "page" } }, "build": { "notebook_id": "53a61d7d-7d09-4392-9d5d-eb90e46aee1c", "job_id": "843e36f9-3550-4b0c-8755-4976e41bce35" }, "status": "ready" } } } } } }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } } }, "/v1/transactional_vector_indexes/{index_id}/status": { "servers": [], "get": { "tags": [ "Vector Indexes - transactional API" ], "summary": "Get status of a vector index", "description": "This retrieves a vector index with the given id.", "operationId": "get_vector_index_status", "x-cli-command": "get-vector-index-status", "parameters": [ { "$ref": "#/components/parameters/project_id" }, { "$ref": "#/components/parameters/index_id" } ], "responses": { "200": { "description": "OK - Returned from GET when it succeeds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vectorIndexStatusResponse" }, "examples": { "get_vector_index_status": { "summary": "get_vector_index_status", "description": "Get vector index.", "value": { "status": "COMPLETED", "asset": { "id": "43499a2a-7656-43d6-8ce0-374d34449d4f", "name": "Milvus-VI-New", "description": "", "created_at": 1739888788777, "created_by": "IBMid-6910003SE8", "last_updated_at": 1739888804362, "last_updated_by": "IBMid-6910003SE8", "data_assets": [ "9624a20d-ecd0-450e-b7d2-9941ce7d1c57" ], "store": { "type": "watsonx.data", "connection_id": "9bdb5dbe-d896-4539-b969-5bf17fcc1f0a", "index": "wx_test_collection_japanese", "new_index": true, "database": "default" }, "settings": { "chunk_size": 2000, "chunk_overlap": 200, "split_pdf_pages": true, "top_k": 3, "rerank": false, "embedding_model_id": "sentence-transformers/all-minilm-l6-v2", "schema_fields": { "document_name": "document_name", "text": "text", "page_number": "page" } }, "build": { "notebook_id": "53a61d7d-7d09-4392-9d5d-eb90e46aee1c", "job_id": "843e36f9-3550-4b0c-8755-4976e41bce35" }, "status": "ready" } } } } } } }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } } } }, "/v2/notebooks": { "servers": [ { "url": "https://{region}.dataplatform.cloud.ibm.com/wx", "variables": { "region": { "default": "api", "enum": [ "api", "api.eu-de", "api.eu-gb", "api.jp-tok" ] } } } ], "post": { "summary": "Create a new notebook.", "tags": [ "Notebooks" ], "operationId": "notebooks_create", "description": "Create a new notebook\n- either from scratch\n- or by copying another notebook.\n\nTo create a notebook from scratch, you need to first upload the notebook content(`ipynb` format) to the project Cloud Object Storage (COS)\nand then reference it with the attribute `file_reference`.\nThe other required attributes are `name`, `project` and `runtime`. \nThe attribute `runtime` is used to specify the environment on which the notebook runs.\n\nTo copy a notebook, you only need to provide `name` and `source_guid` in the request body.", "x-cli-generate-adapter-method": true, "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/NotebookCreateBodyInProject" }, { "$ref": "#/components/schemas/NotebookCopyBody" } ] }, "examples": { "createNewNotebook": { "$ref": "#/components/examples/NotebookCreateBodyInProject" }, "copyNotebook": { "$ref": "#/components/examples/NotebookCopyBody" } } } }, "description": "Specification of the notebook to be created.", "required": true }, "responses": { "201": { "$ref": "#/components/responses/NotebookCreateResponse" }, "400": { "$ref": "#/components/responses/HTTP400Response" }, "401": { "$ref": "#/components/responses/HTTP401Response" }, "403": { "$ref": "#/components/responses/HTTP403Response" }, "429": { "$ref": "#/components/responses/HTTP429Response" } }, "security": [ { "Bearer": [] } ] } }, "/v2/notebooks/list": { "servers": [ { "url": "https://{region}.dataplatform.cloud.ibm.com/wx", "variables": { "region": { "default": "api", "enum": [ "api", "api.eu-de", "api.eu-gb", "api.jp-tok" ] } } } ], "post": { "description": "Retrieve the details of a large number of notebooks inside a project.", "tags": [ "Notebooks" ], "operationId": "notebooks_list", "summary": "Retrieve the details of a large number of notebooks inside a project.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotebookListBody" }, "examples": { "listNotebooks": { "$ref": "#/components/examples/NotebooksListBody" } } } } }, "parameters": [ { "name": "project_id", "required": true, "in": "query", "description": "The guid of the project.", "schema": { "type": "string" } }, { "name": "include", "required": true, "in": "query", "description": "Additional info that will be included into the notebook details.\nPossible values are:\n- runtime\n", "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/NotebooksListResponse" }, "400": { "$ref": "#/components/responses/HTTP400Response" }, "401": { "$ref": "#/components/responses/HTTP401Response" }, "403": { "$ref": "#/components/responses/HTTP403Response" } }, "security": [ { "Bearer": [] } ] } }, "/v2/notebooks/{notebook_guid}": { "servers": [ { "url": "https://{region}.dataplatform.cloud.ibm.com/wx", "variables": { "region": { "default": "api", "enum": [ "api", "api.eu-de", "api.eu-gb", "api.jp-tok" ] } } } ], "delete": { "summary": "Delete a particular notebook, including the notebook asset.\n", "tags": [ "Notebooks" ], "operationId": "notebooks_delete", "description": "Delete a particular notebook, including the notebook asset.", "parameters": [ { "name": "notebook_guid", "in": "path", "required": true, "description": "The guid of the notebook.", "schema": { "type": "string" }, "x-cli-flag-name": "notebook-id" } ], "responses": { "204": { "description": "Successful request. Notebook is deleted." }, "400": { "$ref": "#/components/responses/HTTP400Response" }, "401": { "$ref": "#/components/responses/HTTP401Response" }, "403": { "$ref": "#/components/responses/HTTP403Response" } }, "security": [ { "Bearer": [] } ] }, "put": { "summary": "Revert the main notebook to a version.\n", "tags": [ "Notebooks" ], "operationId": "notebooks_revert", "description": "Revert the main notebook to a version.", "parameters": [ { "name": "notebook_guid", "in": "path", "required": true, "description": "The guid of the main notebook.", "schema": { "type": "string" }, "x-cli-flag-name": "notebook-id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotebookRevertBody" }, "examples": { "revertNotebooks": { "$ref": "#/components/examples/NotebookRevertBody" } } } } }, "responses": { "200": { "$ref": "#/components/responses/NotebookRevertResponse" }, "400": { "$ref": "#/components/responses/HTTP400Response" }, "401": { "$ref": "#/components/responses/HTTP401Response" }, "403": { "$ref": "#/components/responses/HTTP403Response" } }, "security": [ { "Bearer": [] } ] }, "patch": { "summary": "Update a particular notebook.\n", "tags": [ "Notebooks" ], "operationId": "notebooks_update", "description": "Update a particular notebook.", "parameters": [ { "name": "notebook_guid", "in": "path", "required": true, "description": "The guid of the notebook.", "schema": { "type": "string" }, "x-cli-flag-name": "notebook-id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotebookUpdateBody" }, "examples": { "updateNotebook": { "$ref": "#/components/examples/NotebookUpdateBody" } } } } }, "responses": { "200": { "$ref": "#/components/responses/NotebookUpdateResponse" }, "400": { "$ref": "#/components/responses/HTTP400Response" }, "401": { "$ref": "#/components/responses/HTTP401Response" }, "403": { "$ref": "#/components/responses/HTTP403Response" } }, "security": [ { "Bearer": [] } ] } }, "/v2/notebooks/{notebook_guid}/versions": { "servers": [ { "url": "https://{region}.dataplatform.cloud.ibm.com/wx", "variables": { "region": { "default": "api", "enum": [ "api", "api.eu-de", "api.eu-gb", "api.jp-tok" ] } } } ], "parameters": [ { "name": "notebook_guid", "in": "path", "required": true, "description": "The guid of the notebook.", "schema": { "type": "string" }, "x-cli-flag-name": "notebook-id" } ], "post": { "summary": "Create a new version.", "tags": [ "Notebook Versions" ], "operationId": "versions_create", "description": "Create a version of a given notebook.\n", "responses": { "200": { "$ref": "#/components/responses/NotebookVersionCreateResponse" }, "400": { "$ref": "#/components/responses/HTTP400Response" }, "401": { "$ref": "#/components/responses/HTTP401Response" }, "403": { "$ref": "#/components/responses/HTTP403Response" } }, "security": [ { "Bearer": [] } ] }, "get": { "summary": "List the versions of a notebook.", "tags": [ "Notebook Versions" ], "operationId": "versions_list", "description": "List all versions of a particular notebook.\n", "responses": { "200": { "$ref": "#/components/responses/NotebookVersionsListResponse" }, "400": { "$ref": "#/components/responses/HTTP400Response" }, "401": { "$ref": "#/components/responses/HTTP401Response" }, "403": { "$ref": "#/components/responses/HTTP403Response" } }, "security": [ { "Bearer": [] } ] } }, "/v2/notebooks/{notebook_guid}/versions/{version_guid}": { "servers": [ { "url": "https://{region}.dataplatform.cloud.ibm.com/wx", "variables": { "region": { "default": "api", "enum": [ "api", "api.eu-de", "api.eu-gb", "api.jp-tok" ] } } } ], "parameters": [ { "name": "notebook_guid", "in": "path", "required": true, "description": "The guid of the notebook.", "schema": { "type": "string" }, "x-cli-flag-name": "notebook-id" }, { "name": "version_guid", "in": "path", "required": true, "description": "The guid of the version.", "schema": { "type": "string" }, "x-cli-flag-name": "version-id" } ], "get": { "summary": "Retrieve a notebook version.", "tags": [ "Notebook Versions" ], "operationId": "versions_get", "description": "Retrieve a particular version of a notebook.\n", "responses": { "200": { "$ref": "#/components/responses/NotebookVersionRetrieveResponse" }, "400": { "$ref": "#/components/responses/HTTP400Response" }, "401": { "$ref": "#/components/responses/HTTP401Response" }, "403": { "$ref": "#/components/responses/HTTP403Response" } }, "security": [ { "Bearer": [] } ] }, "delete": { "summary": "Delete a notebook version.", "tags": [ "Notebook Versions" ], "operationId": "versions_delete", "description": "Delete a particular version of a given notebook.\n", "responses": { "204": { "description": "Success. The version is deleted." }, "400": { "$ref": "#/components/responses/HTTP400Response" }, "401": { "$ref": "#/components/responses/HTTP401Response" }, "403": { "$ref": "#/components/responses/HTTP403Response" } }, "security": [ { "Bearer": [] } ] } }, "/v1-beta/utility_agent_tools": { "servers": [ { "url": "/wx" } ], "get": { "tags": [ "Utility Agent Tools (Beta)" ], "summary": "Get utility agent tools", "description": "This retrieves the complete list of supported utility agent tools and contains information required for running each tool.", "operationId": "get_utility_agent_tools", "x-cli-command": "list", "x-cli-command-group": "utility-agent-tools", "responses": { "200": { "description": "OK - Returned from GET when it succeeds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wxUtilityAgentToolsResponse" }, "examples": { "get_tool": { "summary": "get_tools", "description": "Get all utility agent tools.", "value": { "resources": [ { "name": "GoogleSearch", "description": "Search for online trends, news, current events, real-time information, or research topics.", "agent_description": "Search for online trends, news, current events, real-time information, or research topics.", "config_schema": { "title": "config schema for GoogleSearch tool", "type": "object", "properties": { "maxResults": { "title": "Max number of results to return", "type": "integer", "minimum": 1, "maximum": 20, "wx_ui_name": "Max results", "wx_ui_field_type": "numberInput", "wx_ui_default": 10 } } } }, { "name": "WebCrawler", "description": "Useful for when you need to summarize a webpage. Do not use for Web search.", "agent_description": "Useful for when you need to summarize a webpage. Do not use for Web search.", "input_schema": { "type": "object", "properties": { "url": { "title": "url", "description": "URL for the webpage to be scraped", "type": "string", "pattern": "^(https?://)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([/\\w \\.-]*)*/?$" } }, "required": [ "url" ] } } ] } } } } } } }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Get tools", "example": [ { "type": "code", "source": [ "curl --request GET 'https://{cluster_url}/v1-beta/utility_agent_tools'\n", "-H 'Accept: application/json'\n" ] } ] } ] } } } }, "/v1-beta/utility_agent_tools/{tool_id}": { "servers": [ { "url": "/wx" } ], "get": { "tags": [ "Utility Agent Tools (Beta)" ], "summary": "Get utility agent tool", "description": "This retrieves the details of an utility agent tool and contains information required for running the tool. Providing authentication and configuration params may return additional details.", "operationId": "get_utility_agent_tool", "x-cli-command": "get", "x-cli-command-group": "utility-agent-tools", "parameters": [ { "$ref": "#/components/parameters/tool_id" } ], "responses": { "200": { "description": "OK - Returned from GET when it succeeds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/utilityAgentTool" }, "examples": { "get_rag_query": { "summary": "get_rag_query", "description": "Get RAGQuery agent tool with dynamic agent_description.", "value": { "name": "RAGQuery", "description": "Search the documents in a vector index.", "agent_description": "Search information in documents to provide context to a user query. Useful when asked to ground the answer in specific knowledge about watsonx documentation.", "config_schema": { "title": "config schema for RAGQuery tool", "type": "object", "properties": { "vectorIndexId": { "title": "Vector index identifier", "type": "string" }, "projectId": { "title": "Project identifier", "type": "string" }, "spaceId": { "title": "Space identifier", "type": "string" } }, "required": [ "vectorIndexId" ], "oneOf": [ { "required": [ "projectId" ] }, { "required": [ "spaceId" ] } ] } } } } } } } }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "RAG query", "example": [ { "type": "code", "source": [ "curl --request GET 'https://{cluster_url}/v1-beta/utility_agent_tools/RAGQuery'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n" ] } ] } ] } } } }, "/v1-beta/utility_agent_tools/run": { "servers": [ { "url": "/wx" } ], "post": { "tags": [ "Utility Agent Tools (Beta)" ], "summary": "Run a utility agent tool", "description": "This runs a utility agent tool given an input and optional configuration parameters.\n\nSome tools can choose to tailor the response based on the access token identity.", "operationId": "post_utility_agent_tools_run", "x-cli-command": "run", "x-cli-command-group": "utility-agent-tools", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wxUtilityAgentToolsRunRequest" }, "examples": { "run_google_tool": { "summary": "run_google_tool", "description": "Run the GoogleSearch tool.", "value": { "tool_name": "GoogleSearch", "input": "What was the weather in Toronto on January 13th 2025?", "config": { "maxResults": 3 } } }, "run_web_crawler_tool": { "summary": "run_web_crawler_tool", "description": "Run the WebCrawler tool.", "value": { "tool_name": "WebCrawler", "input": { "url": "https://www.ibm.com/us-en" } } } } } }, "required": true }, "responses": { "200": { "description": "OK - Returned when tool ran succesfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wxUtilityAgentToolsRunResponse" }, "examples": { "run_google_tool_results": { "summary": "run_google_tool_results", "description": "Results of the GoogleSearch tool.", "value": { "output": "[{\"title\":\"Toronto, Ontario, Canada Monthly Weather | AccuWeather\",\"description\":\"January. January February March April May June July August September October November December. 2025 ... 13°. 29. 37°. 18°. 30. 34°. 16°. 31. 36°. 18°. 1. 18°. 11 ...\",\"url\":\"https://www.accuweather.com/en/ca/toronto/m5h/january-weather/55488\"},{\"title\":\"Anthony Slater on X: \\\"Draymond Green missed the Warriors ...\",\"description\":\"Draymond Green missed the Warriors shootaround in Toronto this morning. Under the weather. He is questionable tonight with an illness. 4:45 PM · Jan 13, ...\",\"url\":\"https://x.com/anthonyVslater/status/1878845945854730255\"},{\"title\":\"Canada weather forecast for Tuesday, 13 January 2026\",\"description\":\"Weather in Canada during the last few years on January 13 ; 2025 - January 13, 32 ° / 26 °, 0 in ; 2024 - January 13, 39 ° / 26 °, 0.46 in ; 2023 - January 13, 32 ...\",\"url\":\"https://www.weather25.com/north-america/canada?page=date&date=13-1\"}]" } }, "run_web_crawler_tool_results": { "summary": "run_web_crawler_tool_results", "description": "Results of the WebCrawler tool.", "value": { "output": "\"{\\\"url\\\":\\\"https://www.ibm.com/us-en\\\",\\\"contentType\\\":\\\"text/html;charset=utf-8\\\",\\\"content\\\":\\\"IBM - United States\\\\n\\\\nBoost developer productivity with AI\\\\n\\\\nAchieve 59% average time savings on code documentation¹ and reduce development costs by 30%²\\\\n\\\\nOvercome developer challenges\\\\n\\\\nExplore watsonx Code Assistant\\\\n\\\\nLatest news\\\\n\\\\nArvind Krishna Celebrates the Work of a Pioneer at the TIME100 AI Impact Awards\\\\n\\\\nIBM and Lenovo Expand Strategic Technology Partnership in the Kingdom of Saudi Arabia\\\\n\\\\nIBM Study: Gen AI Will Elevate Financial Performance of Banks in 2025\\\\n\\\\nTelefónica Tech and IBM Sign a Collaboration Agreement for Quantum-Safe Technology\\\\n\\\\nIBM RELEASES FOURTH-QUARTER RESULTS\\\\n\\\\nIBM BOARD APPROVES REGULAR QUARTERLY CASH DIVIDEND\\\\n\\\\nIBM and Palo Alto Networks Find Platformization is Key to Reduce Cybersecurity Complexity\\\\n\\\\ne& Collaborates with IBM to Launch Pioneering End-to-End AI Governance Platform\\\\n\\\\nRecommended for you\\\\n\\\\nRead why tailor-made AI delivers precision power\\\\n\\\\nLearn AI skills you’ll need for 2025\\\\n\\\\nListen to the episode: DeepSeek facts vs hype and more\\\\n\\\\nMeet Meta Llama 3.2 models on watsonx\\\\n\\\\nAI insights and tools\\\\n\\\\nFor developers\\\\n\\\\nGrow your skills and create something new with our AI tools and foundation models. Then connect, collaborate and innovate with your peers.\\\\n\\\\nStart building with IBM Granite models\\\\n\\\\nExplore AI courses, APIs, data sets and more\\\\n\\\\nAccelerate software development with watsonx Code Assistant\\\\n\\\\nCheck out the watsonx.ai Developer Toolkit\\\\n\\\\nFor business leaders\\\\n\\\\nTransform business and drive growth with AI tools, technology and insights that help you stay competitive—and responsibly map your organization's future.\\\\n\\\\nRead the CEO's guide to generative AI\\\\n\\\\nGet the AI in Action report\\\\n\\\\nExplore IBM's approach to AI ethics\\\\n\\\\nSubscribe to the Think newsletter\\\\n\\\\nThink 2025\\\\n\\\\nJoin 5,000+ senior business and technology leaders at Think 2025 on 5–8 May 2025 in Boston, Massachusetts\\\\n\\\\nRegister today\\\\n\\\\nTechnology & Consulting\\\\n\\\\nFrom next-generation AI to cutting edge hybrid cloud solutions to the deep expertise of IBM Consulting, IBM has what it takes to help you reinvent how your business works in the age of AI.\\\\n\\\\nGet the latest product offers and discounts\\\\n\\\\nAI solutions\\\\n\\\\nGo from AI pilots to production with AI technologies built for business\\\\n\\\\nAI models\\\\n\\\\nGet started with cost-efficient AI models, tailored for business and optimized for scale\\\\n\\\\nConsulting\\\\n\\\\nEngage with IBM Consulting to design, build and operate high-performing businesses\\\\n\\\\nAnalytics\\\\n\\\\nSupport data-driven decisions for your business\\\\n\\\\nIT automation\\\\n\\\\nDiscover how automation solutions increase productivity while managing costs\\\\n\\\\nCompute & servers\\\\n\\\\nHandle mission-critical workloads while maintaining security, reliability and control of your entire IT infrastructure\\\\n\\\\nDatabases\\\\n\\\\nRun your applications, analytics and generative AI with databases on any cloud\\\\n\\\\nSecurity & identity\\\\n\\\\nSecure hybrid cloud and AI with data and identity-centric cybersecurity solutions\\\\n\\\\nInside IBM\\\\n\\\\nOur company\\\\n\\\\nExplore IBM history and culture of putting technology to work in the real world\\\\n\\\\nAbout IBM\\\\n\\\\nOur history\\\\n\\\\nOur impact\\\\n\\\\nLearn about IBM's commitment to environmental, equitable and ethical pillars\\\\n\\\\nCorporate social responsibility\\\\n\\\\nDiversity and inclusion\\\\n\\\\nOur innovations\\\\n\\\\nVisit the IBM lab, and see what's in store for the future of computing\\\\n\\\\nIBM Research\\\\n\\\\nQuantum computing\\\\n\\\\nTake the next step\\\\n\\\\nSolving the world’s problems through technology wouldn’t be possible without people with the right skills. See what it takes to become an IBMer, or build your skills with our educational courses.\\\\n\\\\nBecome an IBMer\\\\n\\\\nExplore jobs\\\\n\\\\nExplore learning opportunities\\\\n\\\\nStart learning\\\\n\\\\nFootnotes\\\\n\\\\n¹ Keep the data flowing. Keep the water flowing. IBM case study on Water Corporation, January 2024.\\\\n2 Accelerating software development with gen AI, IBM, 2024.\\\"}\"" } } } } } }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "run google", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/v1-beta/utility_agent_tools/run'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "--data-raw ", "'{\n", " \"tool_name\": \"GoogleSearch\",\n", " \"input\": \"What was the weather in Toronto on January 13th 2025?\",\n", " \"config\": {\n", " \"maxResults\": 3\n", " }\n", "}'\n" ] } ] }, { "name": "run python interpreter", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/v1-beta/utility_agent_tools/run'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "--data-raw ", "'{\n", " \"tool_name\": \"PythonInterpreter\",\n", " \"input\": \"print(4*5)\"\n", "}'\n" ] } ] }, { "name": "run web crawler", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/v1-beta/utility_agent_tools/run'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "-H 'Accept: application/json'\n", "--data-raw ", "'{\n", " \"tool_name\": \"WebCrawler\",\n", " \"input\": {\n", " \"url\": \"https://www.ibm.com/us-en\"\n", " }\n", "}'\n" ] } ] } ] } } } }, "/v1-beta/utility_agent_tools/run/{tool_id}": { "servers": [ { "url": "/wx" } ], "post": { "tags": [ "Utility Agent Tools (Beta)" ], "summary": "Run a utility agent tool", "description": "This runs a utility agent tool given an input and optional configuration parameters.\n\nSome tools can choose to tailor the response based on the access token identity.", "operationId": "post_utility_agent_tools_run_by_name", "x-cli-command": "run-by-name", "x-cli-command-group": "utility-agent-tools", "parameters": [ { "$ref": "#/components/parameters/tool_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wxUtilityAgentToolsRunRequest" }, "examples": { "run_rag_query_tool": { "summary": "run_rag_query", "description": "Run the RAGQuery tool on a vector index.", "value": { "input": "What is a project?", "config": { "projectId": "d514c8ef-423f-429c-8947-fa900dee338a", "vectorIndexId": "dda284ec-22e9-4091-89d5-19b8e526ea0d" } } } } } }, "required": true }, "responses": { "200": { "description": "OK - Returned when tool ran succesfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wxUtilityAgentToolsRunResponse" }, "examples": { "run_rag_query_tool": { "summary": "run_rag_query_tool", "description": "Results of the RAGQuery tool.", "value": { "output": "Working in projects A project is a collaborative workspace where you work with data and other assets to accomplish a particular goal. By default, your sandbox project is created automatically when you sign up for watsonx.ai. Your project can include these types of resources: Collaborators are the people who you work with in your project. Data assets are what you work with. Data assets often consist of raw data that you work with to refine. Tools and their associated assets are how you work with\n\ndeployment spaces. Projects and tools Projects are where your data science and model builder teams work with data to create assets, such as, saved prompts, notebooks, models, or pipelines. Your first project, which is known as your sandbox project, is created automatically when you\n\nTask 2 . If you don't see any projects, then follow these steps to create a project. 1. Click Create a sandbox project . When the project is created, you will see the sandbox project in the Projects section. For more information or to watch a video, see Creating a project {: new_window}.\n\nTask 2 . If you don't see any projects, then follow these steps to create a project. 1. Click Create a sandbox project . When the project is created, you will see the sandbox project in the Projects section. For more information or to watch a video, see Creating a project {: new_window}.\n\ncharacters plus a unique identifier. Watch this video to see how to create both an empty project, imported project, and a project from a sample. This video provides a visual method to learn the concepts and tasks in this documentation. Next steps Add collaborators Add data Learn more Object storage Importing a project Troubleshooting Cloud Object Storage for projects Parent topic: Projects\n\nis saved in the project. Many tasks include samples that you can use. You can find sample prompts, notebooks, data sets, and other assets in the Samples from the home page. You can share your work by adding collaborators to your project. If you need to work with data, you can add data assets to your project. If your sandbox project is your only project, then any task that you select occurs in the context of your sandbox project. When you have multiple projects, you can change the default project\n\na project, you can add a short description to document the purpose or goal of the project. You can edit the description later, on the project's Settings page. You can mark the project as sensitive. When users open a project that is marked as sensitive, a notification is displayed stating that no data assets can be downloaded or exported from the project. The Overview page of a project contains a readme file where you can document the status or results of the project. The readme file uses standard\n\nproject. Asset storage is where project information and files are stored. Integrations are how you incorporate external tools. You can customize projects to suit your goals. You can change the contents of your project and almost all of its properties at any time. However, you must make these choices when you create the project because you can't change them later: The instance of IBM Cloud Object Storage to use for project storage. You can view projects that you create and collaborate in by" } } } } } }, "400": { "description": "Bad Request - Returned when the request parameters are invalid" }, "401": { "description": "Unauthorized - Returned when caller does not have a valid authorization token, or it is missing" } }, "security": [ { "Bearer": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "RAG query", "example": [ { "type": "code", "source": [ "curl --request POST 'https://{cluster_url}/v1-beta/utility_agent_tools/run/RAGQuery'\n", "-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'\n", "-H 'Content-Type: application/json'\n", "--data-raw ", "'{\n", " \"input\": \"What is a project?\",\n", " \"config\": {\n", " \"projectId\": \"d514c8ef-423f-429c-8947-fa900dee338a\",\n", " \"vectorIndexId\": \"30964b43-f090-44a6-a379-4ab4c00498ca\"\n", " }\n", "}'\n" ] } ] } ] } } } } }, "components": { "securitySchemes": { "Bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "You can authorize using an access token obtained from the authentication endpoint, the access token needs to be prepended with `Bearer` in the `Authorization` header.\n" }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Send your API key in the `Authorization` header for endpoints that require API key auth.\n" } }, "schemas": { "TextGenCommon": { "type": "object", "description": "A prompt to be used to infer the next tokens. Each request expects a `project_id` or a `space_id`, and the `project` or `space` must have an associated WML instance that will be used for limits and billing (if a paid plan).\n", "required": [ "input" ], "properties": { "input": { "type": "string", "description": "The prompt to generate completions.\nNote: The method tokenizes the input internally.\nIt is recommended not to leave any trailing spaces.\n" } } }, "SpaceId": { "type": "string", "pattern": "^[a-zA-Z0-9-]*$", "minLength": 36, "maxLength": 36, "description": "The space that contains the resource.\nEither `space_id` or `project_id` has to be given.\n", "example": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }, "ProjectId": { "type": "string", "pattern": "^[a-zA-Z0-9-]*$", "minLength": 36, "maxLength": 36, "description": "The project that contains the resource.\nEither `space_id` or `project_id` has to be given.\n", "example": "12ac4cf1-252f-424b-b52d-5cdd9814987f" }, "TextGenLengthPenalty": { "type": "object", "description": "It can be used to exponentially increase the likelihood of the text generation terminating once a specified number of tokens have been generated.\n\nIn future implementations, this parameter will be ignored.\n", "properties": { "decay_factor": { "type": "number", "description": "Represents the factor of exponential decay.\nLarger values correspond to more aggressive decay.\n", "minimum": 1, "exclusiveMinimum": true, "example": 2.5 }, "start_index": { "type": "integer", "description": "A number of generated tokens after which this should take effect.\n\n\nIn newer implementations of the service, this parameter will be ignored.\n", "minimum": 0, "example": 5 } } }, "ParameterTruncateInputTokensFromStart": { "type": "integer", "description": "Represents the maximum number of input tokens accepted.\nThis can be used to avoid requests failing due to input being longer than configured limits. If the text is truncated, then it truncates the start of the input (on the left), so the end of the input will remain the same.\nIf this value exceeds the `maximum sequence length` (refer to the documentation to find this value for the model) then the call will fail if the total number of tokens exceeds the `maximum sequence length`.\n", "minimum": 1 }, "ReturnOptionProperties": { "type": "object", "description": "Properties that control what is returned.\n", "properties": { "input_text": { "type": "boolean", "description": "Include input text in the `generated_text` field.\n", "example": true, "default": false }, "generated_tokens": { "type": "boolean", "description": "Include the list of individual generated tokens.\nExtra token information is included based on the other flags below.\n", "example": true, "default": false }, "input_tokens": { "type": "boolean", "description": "Include the list of input tokens. Extra token information is included based\non the other flags here, but only for decoder-only models.\n", "example": true, "default": false }, "token_logprobs": { "type": "boolean", "description": "Include logprob (natural log of probability) for each returned token.\nApplicable only if generated_tokens == true and/or input_tokens == true.\n", "example": true, "default": false }, "token_ranks": { "type": "boolean", "description": "Include rank of each returned token.\nApplicable only if generated_tokens == true and/or input_tokens == true.\n\n\nIn future implementations, this parameter will be ignored and token rank\nwill not be included in the response.\n", "example": true, "default": false }, "top_n_tokens": { "type": "integer", "description": "Include top n candidate tokens at the position of each returned token.\nThe maximum value permitted is 5, but more may be returned if there is a tie for nth place.\nApplicable only if generated_tokens == true and/or input_tokens == true.\n", "example": 2, "minimum": 0 } } }, "TextGenParameters": { "type": "object", "description": "Properties that control the model and response.\n", "example": { "temperature": 0.8, "top_p": 0.5, "top_k": 50, "random_seed": 111, "repetition_penalty": 2, "min_new_tokens": 30, "max_new_tokens": 50 }, "properties": { "decoding_method": { "type": "string", "description": "Represents the strategy used for picking the tokens during generation of the output text.\n\nDuring text generation when parameter value is set to greedy, each successive token corresponds\nto the highest probability token given the text that has already been generated.\nThis strategy can lead to repetitive results especially for longer output sequences.\nThe alternative sample strategy generates text by picking subsequent tokens based on the\nprobability distribution of possible next tokens defined by (i.e., conditioned on) the\nalready-generated text and the top_k and top_p parameters described below.\nSee this [url](https://huggingface.co/blog/how-to-generate) for an informative article about text generation.\n\nIn future implementations, this parameter will be automatically set depending on the `temperature` parameter so this parameter will be ignored.\n", "enum": [ "sample", "greedy" ], "default": "sample", "example": "greedy" }, "length_penalty": { "$ref": "#/components/schemas/TextGenLengthPenalty" }, "max_new_tokens": { "type": "integer", "description": "The maximum number of new tokens to be generated.\nThe maximum supported value for this field depends on the model being used.\n\nHow the \"token\" is defined depends on the tokenizer and vocabulary size,\nwhich in turn depends on the model. Often the tokens are a mix of full words and sub-words.\nTo learn more about tokenization, [see here](https://huggingface.co/course/chapter2/4).\n\nDepending on the users plan, and on the model being used, there may be an enforced maximum number of new tokens.\n", "minimum": 0, "default": 20, "example": 30 }, "min_new_tokens": { "type": "integer", "description": "If stop sequences are given, they are ignored until minimum tokens are generated.\n", "minimum": 0, "default": 0, "example": 5 }, "random_seed": { "type": "integer", "description": "Random number generator seed to use in sampling mode for experimental repeatability.\n", "minimum": 1, "example": 1 }, "stop_sequences": { "type": "array", "minItems": 0, "maxItems": 6, "uniqueItems": true, "description": "Stop sequences are one or more strings which will cause the text generation to stop if/when they are produced as part of the output.\nStop sequences encountered prior to the minimum number of tokens being generated will be ignored.\n", "example": [ "fail" ], "items": { "type": "string" } }, "temperature": { "type": "number", "description": "A value used to modify the next-token probabilities in sampling mode.\nValues less than 1.0 sharpen the probability distribution, resulting in \"less random\" output.\nValues greater than 1.0 flatten the probability distribution, resulting in \"more random\" output.\nA value of 1.0 has no effect.\n", "minimum": 0.05, "maximum": 2, "default": 1, "example": 1.5 }, "time_limit": { "type": "integer", "description": "Time limit in milliseconds - if not completed within this time, generation will stop.\nThe text generated so far will be returned along with the TIME_LIMIT stop reason.\n\nDepending on the users plan, and on the model being used, there may be an enforced maximum time limit.\n", "minimum": 0, "exclusiveMinimum": true, "example": 600000 }, "top_k": { "type": "integer", "description": "The number of highest probability vocabulary tokens to keep for top-k-filtering.\nOnly applies for sampling mode. When decoding_strategy is set to sample,\nonly the top_k most likely tokens are considered as candidates for the next generated token.\n", "minimum": 1, "maximum": 100, "example": 50 }, "top_p": { "type": "number", "description": "Similar to top_k except the candidates to generate the next token are the most likely tokens\nwith probabilities that add up to at least top_p. Also known as nucleus sampling.\nA value of 1.0 is equivalent to disabled.\n", "minimum": 0, "exclusiveMinimum": true, "maximum": 1, "example": 0.5, "default": 1 }, "repetition_penalty": { "type": "number", "description": "Represents the penalty for penalizing tokens that have already been generated or\nbelong to the context. The value 1.0 means that there is no penalty.\n", "minimum": 1, "maximum": 2, "default": 1, "example": 1.5 }, "truncate_input_tokens": { "$ref": "#/components/schemas/ParameterTruncateInputTokensFromStart" }, "return_options": { "$ref": "#/components/schemas/ReturnOptionProperties" }, "include_stop_sequence": { "type": "boolean", "description": "Pass `false` to omit matched stop sequences from the end of the output text.\nThe default is `true`, meaning that the output will end with the stop sequence text when matched.\n", "default": true } } }, "TextModeration": { "type": "object", "description": "Properties that control the moderation on the text.\n", "properties": { "enabled": { "type": "boolean", "description": "Should this moderation be enabled on the text.\n\n\nThe default value is `true` which means that if the parent object exists\nbut the `enabled` field does not exist then this is considered to be enabled.\n", "default": true }, "threshold": { "type": "number", "description": "The threshold probability that this is a real match.\n", "format": "float", "minimum": 0, "maximum": 1 } }, "additionalProperties": { "type": "object" } }, "ModerationProperties": { "type": "object", "description": "The properties for the moderation. Each type of moderation\nmay have additional properties that are specific to that moderation.\n", "properties": { "input": { "$ref": "#/components/schemas/TextModeration" }, "output": { "$ref": "#/components/schemas/TextModeration" } }, "additionalProperties": { "type": "object" } }, "MaskProperties": { "type": "object", "description": "The properties specific to masking. If this object exists,\neven if it is empty, then masking will be applied.\n", "properties": { "remove_entity_value": { "type": "boolean", "description": "If this field is `true` then the entity value, that contains the text that was masked,\nwill also be removed from the output.\n", "default": false } } }, "HapProperties": { "type": "object", "description": "The properties specific to HAP.\n", "properties": { "mask": { "$ref": "#/components/schemas/MaskProperties" } } }, "ModerationHapProperties": { "allOf": [ { "$ref": "#/components/schemas/ModerationProperties" }, { "$ref": "#/components/schemas/HapProperties" } ] }, "TextModerationWithoutThreshold": { "type": "object", "description": "Properties that control the moderation on the text.\n", "properties": { "enabled": { "type": "boolean", "description": "Should this moderation be enabled on the text.\n\n\nThe default value is `true` which means that if the parent object exists\nbut the `enabled` field does not exist then this is considered to be enabled.\n", "default": true } }, "additionalProperties": { "type": "object" } }, "ModerationPropertiesWithoutThreshold": { "type": "object", "description": "The properties for the moderation. Each type of moderation\nmay have additional properties that are specific to that moderation.\n", "properties": { "input": { "$ref": "#/components/schemas/TextModerationWithoutThreshold" }, "output": { "$ref": "#/components/schemas/TextModerationWithoutThreshold" } }, "additionalProperties": { "type": "object" } }, "PiiProperties": { "type": "object", "description": "The properties specific to PII.\n", "properties": { "mask": { "$ref": "#/components/schemas/MaskProperties" } } }, "ModerationPiiProperties": { "allOf": [ { "$ref": "#/components/schemas/ModerationPropertiesWithoutThreshold" }, { "$ref": "#/components/schemas/PiiProperties" } ] }, "GraniteGuardianProperties": { "type": "object", "description": "The properties specific to Granite Guardian. This detector is in beta and may change.\n", "properties": { "input": { "$ref": "#/components/schemas/TextModeration" }, "mask": { "$ref": "#/components/schemas/MaskProperties" } } }, "ModerationGraniteGuardianProperties": { "allOf": [ { "$ref": "#/components/schemas/GraniteGuardianProperties" } ] }, "ModerationTextRange": { "type": "object", "description": "A range of text.\n", "properties": { "start": { "type": "integer", "description": "The start index of the range.\n", "minimum": 0 }, "end": { "type": "integer", "description": "The end index of the range. The end index is exclusive meaning that the character at this index will not be included in the range.\n", "minimum": 0 } }, "required": [ "start", "end" ] }, "Moderations": { "type": "object", "description": "Properties that control the moderations, for usages such as `Hate and profanity` (HAP) and `Personal identifiable information` (PII) filtering. This list can be extended with new types of moderations.\n", "properties": { "hap": { "$ref": "#/components/schemas/ModerationHapProperties" }, "pii": { "$ref": "#/components/schemas/ModerationPiiProperties" }, "granite_guardian": { "$ref": "#/components/schemas/ModerationGraniteGuardianProperties" }, "input_ranges": { "type": "array", "description": "If set, then only these ranges will be applied to the moderations. This is useful in the case that certain parts of the input text have already been checked.\n", "items": { "$ref": "#/components/schemas/ModerationTextRange" } } }, "additionalProperties": { "$ref": "#/components/schemas/ModerationProperties" }, "example": { "hap": { "output": { "enabled": true, "threshold": 0.5 } }, "pii": { "output": { "enabled": true }, "mask": { "remove_entity_value": true } } } }, "CryptoInfo": { "type": "object", "description": "To enable encryption, configure credentials for your chosen keys management service. For details, see [Encrypting inference requests](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-api-chat.html?context=wx&audience=wdp).\n", "required": [ "key_ref" ], "properties": { "key_ref": { "type": "string", "description": "Identifier of the DEK in the chosen keys management service.\n* IBM Key Protect - full CRN (e.g. `crn:v1:bluemix:public:kms:us-south:a/12345::key::wdek:`)\nThis field is required, but its exact format depends on the selected\n`keys_manager`. No strict pattern is enforced here - validation\nwill be performed by the keys management service.\n" } }, "example": { "key_ref": "crn:v1:bluemix:public:kms:us-south:a/12345:b/67890::key:abcd-1234-ef56-7890" } }, "TextGenRequest": { "allOf": [ { "$ref": "#/components/schemas/TextGenCommon" }, { "type": "object", "properties": { "model_id": { "type": "string", "description": "The `id` of the model to be used for this request.\nPlease refer to the [list of models](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models.html?context=wx).\n", "example": "google/flan-ul2" }, "space_id": { "$ref": "#/components/schemas/SpaceId" }, "project_id": { "$ref": "#/components/schemas/ProjectId" }, "parameters": { "$ref": "#/components/schemas/TextGenParameters" }, "moderations": { "$ref": "#/components/schemas/Moderations" }, "crypto": { "$ref": "#/components/schemas/CryptoInfo" } }, "required": [ "model_id" ] } ], "example": { "model_id": "google/flan-ul2", "input": "Generate a marketing email advertising a new sale with the following characteristics:\n\nCompany: Swimwear Unlimited\n\nOffer Keywords: {Select customers only, mid-summer fun, swimwear sale}\n\nOffer End Date: July 15\n\nAdvertisement Tone: Exciting!\n\nInclude no URLs.\n\nInclude no telephone numbers.\n", "parameters": { "temperature": 0.8, "max_new_tokens": 30 }, "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "moderations": { "hap": { "output": { "enabled": true, "threshold": 0.5 } }, "pii": { "output": { "enabled": true }, "mask": { "remove_entity_value": true } } } } }, "ModelVersion": { "type": "string", "description": "The model version (using semantic versioning) if set.\n", "pattern": "^\\d+.\\d+.\\d+$", "minLength": 5, "maxLength": 20 }, "CreatedAt": { "type": "string", "format": "date-time", "example": "2020-05-02T16:27:51Z", "description": "The time when the response was created in ISO 8601 format.\n" }, "TextGenStopReason": { "type": "string", "description": "The reason why the call stopped, can be one of:\n- not_finished - Possibly more tokens to be streamed.\n- max_tokens - Maximum requested tokens reached.\n- eos_token - End of sequence token encountered.\n- cancelled - Request canceled by the client.\n- time_limit - Time limit reached.\n- stop_sequence - Stop sequence encountered.\n- token_limit - Token limit reached.\n- error - Error encountered.\n\nNote that these values will be lower-cased so test for values case insensitive.\n", "enum": [ "not_finished", "max_tokens", "eos_token", "cancelled", "time_limit", "stop_sequence", "token_limit", "error" ], "example": "token_limit" }, "TextGenResult": { "type": "object", "properties": { "generated_text": { "type": "string", "description": "The text that was generated by the model.\n", "example": "Swimwear Unlimited- Mid-Summer Sale! ..." }, "stop_reason": { "$ref": "#/components/schemas/TextGenStopReason" } }, "required": [ "generated_text", "stop_reason" ] }, "TextGenTopTokenInfo": { "type": "object", "description": "The top tokens.\n", "properties": { "text": { "type": "string", "description": "The token text.\n" }, "logprob": { "type": "number", "description": "The natural log of probability for the token.\n" } } }, "TextGenTokenInfo": { "type": "object", "description": "The generated token.\n", "properties": { "text": { "type": "string", "description": "The token text.\n" }, "logprob": { "type": "number", "description": "The natural log of probability for the token.\n" }, "rank": { "type": "integer", "description": "The rank of the token relative to the other tokens.\n" }, "top_tokens": { "type": "array", "description": "The top tokens.\n", "items": { "$ref": "#/components/schemas/TextGenTopTokenInfo" }, "minItems": 0 } } }, "ModerationResult": { "type": "object", "description": "A specific moderation result.\n", "properties": { "score": { "type": "number", "description": "the probability that this is a real match.\n", "format": "float", "minimum": 0, "maximum": 1 }, "input": { "type": "boolean", "description": "This defines if this was found in the input (`true`) or the output (`false`).\n" }, "position": { "$ref": "#/components/schemas/ModerationTextRange" }, "entity": { "type": "string", "description": "The entity that was identified by the moderation.\n", "example": "EmailAddress" }, "word": { "type": "string", "description": "The text that was identified for this entity.\n\nThis field may be removed if requested in the moderation request body.\n" } }, "required": [ "score", "input", "position", "entity" ] }, "ModerationResults": { "type": "object", "description": "The result of any detected moderations.\n", "properties": { "hap": { "type": "array", "description": "The HAP results.\n", "items": { "$ref": "#/components/schemas/ModerationResult" } }, "pii": { "type": "array", "description": "The PII results.\n", "items": { "$ref": "#/components/schemas/ModerationResult" } } }, "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/ModerationResult" } } }, "TextGenResultFields": { "type": "object", "properties": { "generated_token_count": { "type": "integer", "description": "The number of generated tokens.\n", "example": 3 }, "input_token_count": { "type": "integer", "description": "The number of input tokens consumed.\n", "example": 11 }, "seed": { "type": "integer", "description": "The seed used, if it exists.\n", "example": 42 }, "generated_tokens": { "type": "array", "description": "The list of individual generated tokens.\nExtra token information is included based on the other flags in the `return_options` of the request.\n", "items": { "$ref": "#/components/schemas/TextGenTokenInfo" }, "minItems": 1, "example": [ { "text": "_", "rank": 1, "logprob": -2.5, "top_tokens": [ { "text": "_", "logprob": -2.5 }, { "text": "_2", "logprob": -3.1777344 } ] }, { "text": "4,000", "rank": 1, "logprob": -3.0957031, "top_tokens": [ { "text": "4,000", "logprob": -3.0957031 }, { "text": "57", "logprob": -3.3691406 } ] } ] }, "input_tokens": { "type": "array", "description": "The list of input tokens.\nExtra token information is included based on the other flags in the `return_options` of the request, but for decoder-only models.\n", "items": { "$ref": "#/components/schemas/TextGenTokenInfo" }, "minItems": 1, "example": [ { "text": "_how" }, { "text": "_far" }, { "text": "_is" }, { "text": "" } ] }, "moderations": { "$ref": "#/components/schemas/ModerationResults" } } }, "TextGenResponseFields": { "type": "object", "description": "The tokens that are inferred from the prompt.\n\nNote that the events are different between a request with moderation and\na request without moderations.\nA request with moderation will have events that are on a sentence level\nand a request without moderations will have events that are on a token level.\n", "properties": { "model_id": { "type": "string", "description": "The `id` of the model for inference.\n", "example": "google/flan-ul2" }, "model_version": { "$ref": "#/components/schemas/ModelVersion" }, "created_at": { "$ref": "#/components/schemas/CreatedAt" }, "results": { "type": "array", "description": "The generated tokens.\n", "items": { "allOf": [ { "$ref": "#/components/schemas/TextGenResult" }, { "$ref": "#/components/schemas/TextGenResultFields" } ] }, "minItems": 1 } }, "required": [ "model_id", "created_at", "results" ] }, "Warning": { "type": "object", "description": "A warning message.\n", "properties": { "message": { "type": "string", "description": "The message.\n", "example": "The framework TF 1.1 is deprecated." }, "id": { "type": "string", "description": "An `id` associated with the message.\n", "example": "2fc54cf1-252f-424b-b52d-5cdd98149871" }, "more_info": { "type": "string", "description": "A reference to a more detailed explanation when available.\n" }, "additional_properties": { "type": "object", "description": "Additional key-value pairs that depend on the specific warning.\n" } }, "required": [ "message" ] }, "SystemDetails": { "type": "object", "description": "Optional details coming from the service and related to the API call or the associated resource.\n", "properties": { "warnings": { "type": "array", "description": "Any warnings coming from the system.\n", "items": { "$ref": "#/components/schemas/Warning" } } } }, "System": { "type": "object", "description": "System details.\n", "properties": { "system": { "$ref": "#/components/schemas/SystemDetails" } } }, "TextGenResponse": { "allOf": [ { "$ref": "#/components/schemas/TextGenResponseFields" }, { "$ref": "#/components/schemas/System" } ] }, "ApiErrorTarget": { "type": "object", "description": "The target of the error.\n", "properties": { "type": { "description": "The type of the problematic field.\n", "type": "string", "enum": [ "field", "parameter", "header" ] }, "name": { "description": "The name of the problematic field.\n", "type": "string" } }, "required": [ "type", "name" ] }, "ApiError": { "type": "object", "description": "An error message.\n", "properties": { "code": { "type": "string", "example": "missing_field", "description": "A simple code that should convey the general sense of the error.\n" }, "message": { "type": "string", "example": "The 'name' field is required.", "description": "The message that describes the error.\n" }, "more_info": { "type": "string", "example": "https://cloud.ibm.com/apidocs/machine-learning#models-get", "description": "A reference to a more detailed explanation when available.\n" }, "target": { "$ref": "#/components/schemas/ApiErrorTarget" } }, "required": [ "code", "message" ] }, "ApiErrorResponse": { "type": "object", "description": "The data returned when an error is encountered.\n", "properties": { "trace": { "type": "string", "example": "3fd543d2-36e0-4f83-9be3-5c6dd498af4f", "description": "An identifier that can be used to trace the request.\n" }, "status_code": { "type": "integer", "example": 400, "description": "The corresponding error code in integer.\n" }, "errors": { "type": "array", "description": "The list of errors.\n", "items": { "$ref": "#/components/schemas/ApiError" } } }, "required": [ "trace", "errors" ] }, "TextGenStreamRequest": { "allOf": [ { "$ref": "#/components/schemas/TextGenCommon" }, { "type": "object", "properties": { "model_id": { "type": "string", "description": "The `id` of the model to be used for this request.\nPlease refer to the [list of models](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models.html?context=wx).\n", "example": "google/flan-ul2" }, "space_id": { "$ref": "#/components/schemas/SpaceId" }, "project_id": { "$ref": "#/components/schemas/ProjectId" }, "parameters": { "$ref": "#/components/schemas/TextGenParameters" }, "moderations": { "$ref": "#/components/schemas/Moderations" } }, "required": [ "model_id" ] } ], "example": { "model_id": "google/flan-ul2", "input": "Generate a marketing email advertising a new sale with the following characteristics:\n\nCompany: Swimwear Unlimited\n\nOffer Keywords: {Select customers only, mid-summer fun, swimwear sale}\n\nOffer End Date: July 15\n\nAdvertisement Tone: Exciting!\n\nInclude no URLs.\n\nInclude no telephone numbers.\n", "parameters": { "temperature": 0.8, "max_new_tokens": 30 }, "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "moderations": { "hap": { "output": { "enabled": true, "threshold": 0.5 } }, "pii": { "output": { "enabled": true }, "mask": { "remove_entity_value": true } } } } }, "TextGenStreamResponse": { "description": "A set of server sent events, each event contains a response for one or more tokens. The results will be an array of events of the form `data: {}` where the schema of the individual `json event` is described below.\n", "type": "array", "items": { "$ref": "#/components/schemas/TextGenResponse" } }, "TextTokenizeParameters": { "type": "object", "description": "The parameters for text tokenization.\n", "properties": { "return_tokens": { "type": "boolean", "description": "If this is `true` then the actual tokens will also be returned in the response.\n", "default": false, "example": true } } }, "TextTokenizeRequest": { "type": "object", "description": "The input string to tokenize along with the associated model id and any parameters.\nOne of `space_id` or `project_id` must be provided.\n", "required": [ "input", "model_id" ], "properties": { "space_id": { "$ref": "#/components/schemas/SpaceId" }, "project_id": { "$ref": "#/components/schemas/ProjectId" }, "model_id": { "type": "string", "description": "The `id` of the model to be used for this request.\nPlease refer to the [list of models](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models.html?context=wx).\n", "example": "google/flan-ul2" }, "input": { "type": "string", "description": "The input string to tokenize.\n", "example": "Write a tagline for an alumni association: Together we" }, "parameters": { "$ref": "#/components/schemas/TextTokenizeParameters" }, "crypto": { "$ref": "#/components/schemas/CryptoInfo" } } }, "TextTokenizeResult": { "type": "object", "description": "The result of tokenizing the input string.\n", "properties": { "token_count": { "type": "integer", "description": "The number of tokens in the input string.\n", "example": 11 }, "tokens": { "type": "array", "description": "The input string broken up into the tokens, if requested.\n", "items": { "type": "string" }, "example": [ "Write", "a", "tag", "line", "for", "an", "alumni", "associ", "ation:", "Together", "we" ] } }, "required": [ "token_count" ] }, "TextTokenizeResponse": { "type": "object", "description": "The tokenization result.\n", "required": [ "model_id", "result" ], "properties": { "model_id": { "type": "string", "description": "The `id` of the model to be used for this request.\nPlease refer to the [list of models](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models.html?context=wx).\n", "example": "google/flan-ul2" }, "result": { "$ref": "#/components/schemas/TextTokenizeResult" } } }, "PaginationFirst": { "type": "object", "description": "The reference to the first item in the current page.\n", "properties": { "href": { "description": "The uri of the first resource returned.\n", "type": "string" } }, "required": [ "href" ] }, "PaginationNext": { "type": "object", "description": "A reference to the first item of the next page, if any.\n", "properties": { "href": { "description": "The uri of the next set of resources.\n", "type": "string" } }, "required": [ "href" ] }, "PaginationBase": { "type": "object", "properties": { "total_count": { "description": "Computed explicitly only when `total_count=true` query parameter is present.\nThis is in order to avoid performance penalties.\n", "type": "integer" }, "limit": { "type": "integer", "description": "The number of items to return in each page.\n", "example": 10, "minimum": 1, "maximum": 200 }, "first": { "$ref": "#/components/schemas/PaginationFirst" }, "next": { "$ref": "#/components/schemas/PaginationNext" } }, "required": [ "limit", "first" ] }, "PaginationTC": { "allOf": [ { "$ref": "#/components/schemas/PaginationBase" }, { "type": "object", "properties": { "total_count": { "description": "The total number of resources.\n", "type": "integer", "example": 1 } } } ], "description": "Information for paging when querying resources.\n" }, "ConsumptionsLimit": { "type": "object", "description": "The limits that may be set per request.\n", "properties": { "call_time": { "type": "string", "description": "The hard limit on the call time for a request, if set.\n", "example": "3S" }, "max_input_tokens": { "type": "integer", "description": "The hard limit on the number of input tokens for a request, if set.\nA value of zero will disable this feature.\n", "example": 200 }, "max_output_tokens": { "type": "integer", "description": "The hard limit on the number of output tokens for a request, if set.\nA value of zero will disable this feature.\n", "example": 1000 } } }, "FoundationModelLimits": { "type": "object", "description": "Limits per plan that may be set per request.\n", "properties": { "lite": { "$ref": "#/components/schemas/ConsumptionsLimit" } } }, "TaskRating": { "type": "object", "description": "The ratings for this task for this model.\n", "properties": { "cost": { "type": "integer", "minimum": 1, "maximum": 5, "description": "A metric that indicates the cost expected to be incurred by the model's support of an inference task,\nin terms of resource consumption and processing time,\non a scale of 1 to 5, where 5 is the least cost and 1 is the most cost.\nA missing value means that the cost is not known.\n", "example": 2 }, "quality": { "type": "integer", "minimum": 1, "maximum": 5, "description": "A metric that indicates the quality of the model's support of an inference task,\non a scale of 1 to 5, where 5 is the best support and 1 is poor support.\nA missing value means that the quality is not known.\n", "example": 3 } } }, "TaskBenchmarkMetric": { "type": "object", "description": "The metric for a given property.\n", "properties": { "name": { "type": "string", "description": "The name of the metric.\n", "example": "rougeL" }, "value": { "type": "number", "description": "The mean value calculated over all records in the dataset.\n", "example": 0.5197 } } }, "Tags": { "type": "array", "description": "A list of tags for this resource.\n", "items": { "type": "string" }, "maxItems": 64, "example": [ "t1", "t2" ] }, "TaskBenchmark": { "type": "object", "description": "The benchmarking result for this task for this model.\n", "properties": { "type": { "type": "string", "description": "Type of benchmarks used.", "example": "academic" }, "name": { "type": "string", "description": "Name of benchmarks used.", "example": "bluebench" }, "description": { "type": "string", "description": "Description of benchmark used.", "example": "MultiLingual Summarization dataset with 1.5M+ article/summary pairs across five languages. Evaluated using rougeL with 5 shots." }, "language": { "type": "string", "description": "Benchmarked language (multilingual benchmarks). ISO 639 2 letter language code.", "example": "fr" }, "dataset": { "type": "object", "description": "Benchmarking dataset properties.", "properties": { "name": { "type": "string", "description": "The benchmarking dataset name.", "example": "mlsum.de" } } }, "prompt": { "type": "object", "description": "The benchmarking prompt properties.", "properties": { "number_of_shots": { "type": "integer", "example": 5 } } }, "metrics": { "type": "array", "description": "The scores for a given benchmark.\n", "items": { "$ref": "#/components/schemas/TaskBenchmarkMetric" } }, "tags": { "$ref": "#/components/schemas/Tags" } } }, "TaskDescription": { "type": "object", "description": "The attributes of the task for this model.\n", "properties": { "id": { "type": "string", "description": "The `id` of the task.\n", "example": "summarization" }, "ratings": { "$ref": "#/components/schemas/TaskRating" }, "benchmarks": { "type": "array", "description": "The benchmarks for a given task.\n", "items": { "$ref": "#/components/schemas/TaskBenchmark" } }, "tags": { "type": "array", "description": "The tags for a given task.\n", "items": { "type": "string", "description": "The tag.\n" } } }, "required": [ "id" ] }, "FoundationModelTier": { "type": "string", "description": "The tier of the model, depending on the `tier` the billing will be different, refer to the plan for the details. Note that input tokens and output tokens may be charged differently.\n", "enum": [ "class_1", "class_2", "class_3", "class_c1" ] }, "ModelLimits": { "type": "object", "description": "The limits that are applied for the model, for all the plans.\n", "properties": { "max_sequence_length": { "type": "integer", "description": "This is the maximum allowed value for the number of tokens in the input\nprompt plus the number of tokens in the output generated by the model.\n", "example": 4096 }, "training_data_max_records": { "type": "integer", "description": "This is the maximum number of records that can be accepted when training this model.\n", "example": 1024 } } }, "LifeCycleState": { "type": "object", "description": "The lifecycle details.\n", "properties": { "id": { "type": "string", "enum": [ "available", "deprecated", "constricted", "withdrawn" ], "description": "The possible lifecycle stages, in order, are described below:\n\n- `available`: this means that the model is available for use.\n- `deprecated`: this means that the model is still available but the model will be removed soon, so an alternative model should be used.\n- `constricted`: this means that the model is still available for inferencing but cannot be used for training or in a deployment. The model will be removed soon so an alternative model should be used.\n- `withdrawn`: this means that the model is no longer available, check the `alternative_model_ids` to see what it can be replaced by.\n", "example": "available" }, "label": { "type": "string", "description": "An optional label that may be used in the UI.\n" }, "start_date": { "type": "string", "format": "date", "description": "The date (ISO 8601 format YYYY-MM-DD) when this lifecycle stage starts.\n", "example": "2023-07-23", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "minLength": 10, "maxLength": 10 }, "alternative_model_ids": { "type": "array", "description": "Alternative models, or model versions, that can be used instead of this model.\n", "items": { "type": "string" } }, "url": { "type": "string", "format": "url", "description": "A link to the documentation specifying details on the lifecycle plan for this model.\n" } }, "required": [ "id" ] }, "TrainingInitMethod": { "type": "object", "description": "Initialization methods for a training.\n", "properties": { "supported": { "type": "array", "description": "The supported initialization methods.\n", "items": { "type": "string", "description": "A supported initialization method.\n" }, "example": [ "random", "text" ] }, "default": { "type": "string", "description": "The default value, which will be one of the values from the `supported` field.\n", "example": "random" } } }, "TrainingInitText": { "type": "object", "description": "Initialization text to be used if init_method is set to `text`, otherwise this will be ignored.\n", "properties": { "default": { "type": "string", "description": "Initialization text.\n", "example": "text" } } }, "TrainingNumVirtualTokens": { "type": "object", "description": "Number of virtual tokens to be used for training.\nIn prompt tuning we are essentially learning the embedded representations for soft prompts,\nwhich are known as virtual tokens, via back propagation for a specific task(s) while keeping\nthe rest of the model fixed. `num_virtual_tokens` is the number of dimensions for these virtual tokens.\n", "properties": { "supported": { "type": "array", "description": "The possible values for the number of virtual tokens.\n", "items": { "type": "integer" }, "example": [ 20, 50, 100 ] }, "default": { "type": "integer", "description": "The default number of virtual tokens.\n", "example": 100 } } }, "TrainingNumEpochs": { "type": "object", "description": "The number of epochs is the number of complete passes through the training dataset.\nThe quality depends on the number of epochs.\n", "properties": { "default": { "type": "integer", "description": "The default value.\n", "example": 20 }, "min": { "type": "integer", "description": "The minimum value.\n", "example": 1 }, "max": { "type": "integer", "description": "The maximum value.\n", "example": 50 } } }, "TrainingVerbalizer": { "type": "object", "description": "Verbalizer template to be used for formatting data at train and inference time.\nThis template may use brackets to indicate where fields from the data model\nTrainGenerationRecord must be rendered.\n", "properties": { "default": { "type": "string", "description": "The default verbalizer.\n", "example": "Input: {{input}} Output:" } } }, "TrainingBatchSize": { "type": "object", "description": "The batch size is a number of samples processed before the model is updated.\n", "properties": { "default": { "type": "integer", "description": "The default value.\n", "example": 16 }, "min": { "type": "integer", "description": "The minimum value.\n", "example": 1 }, "max": { "type": "integer", "description": "The maximum value.\n", "example": 16 } } }, "TrainingMaxInputTokens": { "type": "object", "description": "Maximum length of input tokens being considered.\n", "properties": { "default": { "type": "integer", "description": "The default value.\n", "example": 256 }, "min": { "type": "integer", "description": "The minimum value.\n", "example": 1 }, "max": { "type": "integer", "description": "The maximum value.\n", "example": 1024 } } }, "TrainingMaxOutputTokens": { "type": "object", "description": "Maximum length of output tokens being predicted.\n", "properties": { "default": { "type": "integer", "description": "The default value.\n", "example": 128 }, "min": { "type": "integer", "description": "The minimum value.\n", "example": 1 }, "max": { "type": "integer", "description": "The maximum value.\n", "example": 256 } } }, "TrainingTorchDtype": { "type": "object", "description": "Datatype to use for training of the underlying text generation model.\nIf no value is provided, we pull from torch_dtype in config.\nIf an in memory resource is provided which does not match the specified data type,\nthe model underpinning the resource will be converted in place to the correct torch dtype.\n", "properties": { "default": { "type": "string", "description": "The datatype.\n", "example": "bfloat16" } } }, "TrainingAccumulatedSteps": { "type": "object", "description": "Number of steps to be used for gradient accumulation.\nGradient accumulation refers to a method of collecting gradient for configured number of steps\ninstead of updating the model variables at every step and then applying the update to model variables.\nThis can be used as a tool to overcome smaller batch size limitation.\nOften also referred in conjunction with \"effective batch size\".\n", "properties": { "default": { "type": "integer", "description": "The default value.\n", "example": 128 }, "min": { "type": "integer", "description": "The minimum value.\n", "example": 1 }, "max": { "type": "integer", "description": "The maximum value.\n", "example": 128 } } }, "TrainingLearningRate": { "type": "object", "description": "Learning rate to be used for training.\n", "properties": { "default": { "type": "number", "description": "The default value.\n", "example": 0.3 }, "min": { "type": "number", "description": "The minimum value.\n", "example": 0.01 }, "max": { "type": "number", "description": "The maximum value.\n", "example": 0.5 } } }, "TrainingParameters": { "type": "object", "description": "Training parameters for a given model.\n", "properties": { "init_method": { "$ref": "#/components/schemas/TrainingInitMethod" }, "init_text": { "$ref": "#/components/schemas/TrainingInitText" }, "num_virtual_tokens": { "$ref": "#/components/schemas/TrainingNumVirtualTokens" }, "num_epochs": { "$ref": "#/components/schemas/TrainingNumEpochs" }, "verbalizer": { "$ref": "#/components/schemas/TrainingVerbalizer" }, "batch_size": { "$ref": "#/components/schemas/TrainingBatchSize" }, "max_input_tokens": { "$ref": "#/components/schemas/TrainingMaxInputTokens" }, "max_output_tokens": { "$ref": "#/components/schemas/TrainingMaxOutputTokens" }, "torch_dtype": { "$ref": "#/components/schemas/TrainingTorchDtype" }, "accumulate_steps": { "$ref": "#/components/schemas/TrainingAccumulatedSteps" }, "learning_rate": { "$ref": "#/components/schemas/TrainingLearningRate" } } }, "FoundationModelVersion": { "type": "object", "description": "A minor or patch version for the model.\n", "properties": { "version": { "type": "string", "pattern": "^\\d+.\\d+.\\d+$", "minLength": 5, "maxLength": 20, "description": "The version of the model. This must follow semantic versioning semantics.\n", "example": "1.1.0" }, "available_date": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "minLength": 10, "maxLength": 10, "description": "The date (ISO 8601 format YYYY-MM-DD) when this version first became available.\n", "example": "2023-08-23" } } }, "FoundationModel": { "type": "object", "description": "A supported foundation model.\n", "properties": { "model_id": { "type": "string", "description": "The id of the foundation model.\n", "example": "google/flan-ul2" }, "label": { "type": "string", "description": "A short label that will be displayed in the UI.\n", "example": "flan-ul2 (20B)" }, "provider": { "type": "string", "description": "The provider of the model.\n", "example": "Hugging Face" }, "tuned_by": { "type": "string", "description": "The organization or person that tuned this model.\n" }, "short_description": { "type": "string", "description": "A short description of the model suitable for a title.\n", "example": "An encoder decoder model based on the T5 architecture and instruction-tuned using the Fine-tuned LAnguage Net." }, "long_description": { "type": "string", "description": "A longer description of the model, that may be used if no `description_url` is provided.\n", "example": "flan-ul2 (20B) is an encoder decoder model based on the T5 architecture and instruction-tuned using the Fine-tuned LAnguage Net (FLAN)." }, "limits": { "$ref": "#/components/schemas/FoundationModelLimits" }, "supported_languages": { "type": "array", "description": "Languages supported by the model.\n", "items": { "type": "string", "description": "Supported language (ISO 639 2 letter language code).\n" }, "example": [ "fr", "en" ] }, "task_ids": { "type": "array", "items": { "type": "string", "description": "The `id` of the tasks.\n" }, "description": "Deprecated: please use `tasks` instead.\n", "deprecated": true }, "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/TaskDescription" }, "minItems": 1, "description": "The tasks that are supported by this model.\n", "example": [ { "id": "summarization", "ratings": { "cost": 2, "quality": 3 }, "benchmarks": [ { "type": "academic", "name": "bluebench", "language": "German", "description": "MultiLingual Summarization dataset with 1.5M+ article/summary pairs across five languages.", "dataset": { "name": "mlsum.de" }, "prompt": { "number_of_shots": 5 }, "metrics": [ { "name": "rougeL", "value": 0.56 } ] } ] }, { "id": "classification", "ratings": { "cost": 4, "quality": 2 } } ] }, "input_tier": { "$ref": "#/components/schemas/FoundationModelTier" }, "output_tier": { "$ref": "#/components/schemas/FoundationModelTier" }, "source": { "type": "string", "description": "Specifies the provider of this model.\n", "example": "Hugging Face" }, "min_shot_size": { "type": "integer", "description": "The minimum number of examples required for the model.\n", "example": 10, "minimum": 0 }, "number_params": { "type": "string", "description": "The number of parameters used for the model,\nit will accept `m` for million, `b` for billion and `t` for trillion.\n", "example": "20b" }, "model_limits": { "$ref": "#/components/schemas/ModelLimits" }, "lifecycle": { "type": "array", "description": "The information related to the lifecycle of this model.\n", "items": { "$ref": "#/components/schemas/LifeCycleState" }, "minItems": 0 }, "training_parameters": { "$ref": "#/components/schemas/TrainingParameters" }, "versions": { "type": "array", "description": "The information related to the minor versions of this model.\n", "items": { "$ref": "#/components/schemas/FoundationModelVersion" }, "minItems": 0 }, "tech_preview": { "type": "boolean", "description": "If `true` then this model is only available in the `Tech Preview`.\n", "default": false } }, "required": [ "model_id", "label", "provider", "short_description", "input_tier", "output_tier", "source", "number_params" ] }, "FoundationModelsArray": { "description": "The supported foundation models.\n", "type": "array", "items": { "$ref": "#/components/schemas/FoundationModel" } }, "FoundationModels": { "allOf": [ { "$ref": "#/components/schemas/PaginationTC" }, { "type": "object", "description": "A list of the foundation models that are supported in the service.\n", "properties": { "resources": { "$ref": "#/components/schemas/FoundationModelsArray" } } }, { "$ref": "#/components/schemas/System" } ] }, "FoundationModelTask": { "type": "object", "description": "A task that is covered by some of the foundation models that are supported in the service.\n", "properties": { "task_id": { "type": "string", "description": "The id of the task.\n", "example": "summarization" }, "label": { "type": "string", "description": "The label of the task.\n", "example": "Summarization" }, "description": { "type": "string", "description": "The description of the task.\n", "example": "Models that are able to summarize documents based on some criteria." }, "rank": { "type": "integer", "description": "The rank of the task that is mainly for the UI.\n", "example": 1 } }, "required": [ "task_id", "label", "rank" ] }, "FoundationModelTasksArray": { "type": "array", "description": "The supported foundation model tasks.\n", "items": { "$ref": "#/components/schemas/FoundationModelTask" } }, "FoundationModelTasks": { "allOf": [ { "$ref": "#/components/schemas/PaginationTC" }, { "type": "object", "description": "A list of the tasks that are covered by the foundation models that are supported in the service.\n", "properties": { "resources": { "$ref": "#/components/schemas/FoundationModelTasksArray" } } }, { "$ref": "#/components/schemas/System" } ] }, "Pagination": { "allOf": [ { "$ref": "#/components/schemas/PaginationBase" }, { "type": "object", "properties": { "total_count": { "description": "The total number of resources.\nComputed explicitly only when `total_count=true` query parameter is present.\nThis is in order to avoid performance penalties.\n", "type": "integer", "example": 1 } } } ], "description": "Information for paging when querying resources.\n" }, "ResourceMetaSimple": { "type": "object", "description": "Common metadata for a simple resource.\n", "properties": { "id": { "type": "string", "description": "The id of the resource.\n" }, "created_at": { "type": "string", "format": "date-time", "description": "The time when the resource was created.\n" } }, "required": [ "id", "created_at" ] }, "ResourceCommitInfo": { "type": "object", "description": "Information related to the revision.\n", "properties": { "committed_at": { "type": "string", "format": "date-time", "description": "The time when the revision was committed.\n" }, "commit_message": { "type": "string", "description": "The message that was provided when the revision was created.\n" } }, "required": [ "committed_at" ] }, "ResourceMetaBase": { "type": "object", "description": "Common metadata for a resource.\n", "example": { "rev": "2", "owner": "guy", "modified_at": "2020-05-02T16:30:51Z", "parent_id": "dfe1cf1-252f-424b-b52d-5cdd9814600c", "name": "my-name", "description": "My resource", "tags": [ "t1", "t2" ], "commit_info": { "committed_at": "2020-05-02T16:27:51Z", "commit_message": "Updated to TF 2.0" } }, "properties": { "id": { "type": "string", "description": "The unique id of the resource.\n" }, "rev": { "type": "string", "description": "The revision of the resource.\n" }, "owner": { "description": "The user id which created this resource.\n", "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "The time when the resource was created.\n" }, "modified_at": { "type": "string", "format": "date-time", "description": "The time when the resource was last modified.\n" }, "parent_id": { "type": "string", "description": "The id of the parent resource where applicable.\n" }, "name": { "type": "string", "description": "The name of the resource.\n" }, "description": { "type": "string", "description": "A description of the resource.\n" }, "space_id": { "type": "string", "description": "The id of the space this resource belongs to.\n" }, "tags": { "$ref": "#/components/schemas/Tags" }, "commit_info": { "$ref": "#/components/schemas/ResourceCommitInfo" } } }, "ResourceMeta": { "allOf": [ { "$ref": "#/components/schemas/ResourceMetaSimple" }, { "$ref": "#/components/schemas/ResourceMetaBase" }, { "type": "object", "description": "Common metadata for a resource where `project_id` or `space_id` must be present.\n", "properties": { "space_id": { "$ref": "#/components/schemas/SpaceId" }, "project_id": { "$ref": "#/components/schemas/ProjectId" } } } ] }, "Custom": { "description": "User defined properties specified as key-value pairs.\n", "type": "object", "additionalProperties": true, "example": { "name": "model", "size": 2 } }, "SimpleRel": { "type": "object", "description": "A reference to a resource.\n", "properties": { "id": { "description": "The id of the referenced resource.\n", "type": "string", "example": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab" } }, "required": [ "id" ] }, "OnlineDeploymentParameters": { "type": "object", "description": "A set of key-value pairs that are used to configure the deployment.\n", "properties": { "serving_name": { "type": "string", "pattern": "^[a-z,0-9,_]+$", "minLength": 3, "maxLength": 36, "description": "The `serving_name` can be used in the inference URL in place of the `deployment_id`.\n", "example": "churn" }, "foundation_model": { "allOf": [ { "type": "object", "properties": { "functions": { "type": "array", "items": { "type": "string" }, "description": "Optional list of supported functions used in deployment" } } } ] } }, "additionalProperties": { "type": "string" } }, "OnlineDeployment": { "type": "object", "description": "Indicates that this is an online deployment. An object has to be specified but can be empty.\nThe `serving_name` can be provided in the `online.parameters`.\n", "properties": { "parameters": { "$ref": "#/components/schemas/OnlineDeploymentParameters" } } }, "HardwareSpec": { "description": "A hardware specification.\n", "type": "object", "properties": { "id": { "description": "The id of the hardware specification.\n", "type": "string", "example": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab" }, "rev": { "description": "The revision of the hardware specification.\n", "type": "string", "example": "2" }, "name": { "description": "The name of the hardware specification.\n", "type": "string" }, "num_nodes": { "type": "integer", "description": "The number of nodes applied to a computation.\n", "example": 2 } } }, "HardwareRequest": { "type": "object", "description": "The requested hardware for deployment.\n", "properties": { "size": { "description": "The size of GPU requested for the deployment.\n", "type": "string", "enum": [ "gpu_s", "gpu_m", "gpu_l" ] }, "num_nodes": { "description": "The number of nodes for the GPU requested for deployment.\n", "type": "number" } } }, "DeploymentEntityCommon": { "description": "The common fields between a request and the response.\n", "type": "object", "properties": { "custom": { "$ref": "#/components/schemas/Custom" }, "prompt_template": { "$ref": "#/components/schemas/SimpleRel" }, "online": { "$ref": "#/components/schemas/OnlineDeployment" }, "hardware_spec": { "$ref": "#/components/schemas/HardwareSpec" }, "hardware_request": { "$ref": "#/components/schemas/HardwareRequest" } }, "required": [ "online" ] }, "ModelRel": { "allOf": [ { "$ref": "#/components/schemas/SimpleRel" }, { "type": "object", "properties": { "rev": { "type": "string", "description": "The revision of the referenced resource.\n", "example": "2" }, "resource_key": { "type": "string", "description": "The resource key for this asset if it exists.\n", "example": "f52fe20c-a1fe-4e54-9b78-6bf2ff61b455" } } } ] }, "ModelAssetRef": { "type": "object", "description": "The field that identifies the asset.\n", "properties": { "asset": { "$ref": "#/components/schemas/ModelRel" } } }, "DeploymentResourceEntity": { "type": "object", "description": "The properties specific to `watsonx.ai` deployments.\n", "properties": { "base_model_id": { "type": "string", "description": "The base model that is required for this deployment if this is for a prompt template for an IBM foundation model.\n", "example": "google/flan-t5-xl" } } }, "Message": { "type": "object", "description": "Optional messages related to the resource.\n", "properties": { "level": { "description": "The level of the message, normally one of `debug`, `info` or `warning`.\n", "type": "string", "example": "info" }, "text": { "description": "The message.\n", "type": "string", "example": "The deployment is successful" } } }, "Inference": { "type": "object", "description": "The details of an inference API.\n", "properties": { "url": { "type": "string", "description": "The inference URL.\n" }, "sse": { "type": "boolean", "description": "This is `true` if the inference API supports SSE streaming.\n", "default": false, "example": true }, "uses_serving_name": { "type": "boolean", "description": "This is `true` if the inference API uses the `serving_name` that was defined in this deployment.\n", "default": false, "example": true } }, "required": [ "url" ] }, "DeploymentStatus": { "type": "object", "description": "Specifies the current status, additional information about the deployment\nand any failure messages in case of deployment failures.\n", "properties": { "state": { "description": "Specifies the current state of the deployment.\n", "type": "string", "enum": [ "initializing", "updating", "ready", "failed" ], "example": "ready" }, "message": { "$ref": "#/components/schemas/Message" }, "failure": { "$ref": "#/components/schemas/ApiErrorResponse" }, "inference": { "description": "The URLs that can be used to submit inference API requests. These URLs will contain the\n`deployment_id` and the `serving_name`, if the `serving_name` was set.\n", "type": "array", "items": { "$ref": "#/components/schemas/Inference" }, "example": [ { "url": "https://us-south.ml.cloud.ibm.com/ml/v1/deployments/2cd0bcda-581d-4f04-8028-ec2bc90cc375/text/generation" }, { "url": "https://us-south.ml.cloud.ibm.com/ml/v1/deployments/classification/text/generation", "uses_serving_name": true }, { "url": "https://us-south.ml.cloud.ibm.com/ml/v1/deployments/2cd0bcda-581d-4f04-8028-ec2bc90cc375/text/generation_stream", "sse": true }, { "url": "https://us-south.ml.cloud.ibm.com/ml/v1/deployments/classification/text/generation_stream", "sse": true, "uses_serving_name": true } ] } } }, "Tooling": { "type": "object", "description": "User defined properties specified as key-value pairs, which is propagated to the deployment.\n", "additionalProperties": true, "example": { "name": "reference_format", "tag": true } }, "DeploymentEntity": { "allOf": [ { "$ref": "#/components/schemas/DeploymentEntityCommon" }, { "$ref": "#/components/schemas/ModelAssetRef" }, { "$ref": "#/components/schemas/DeploymentResourceEntity" }, { "type": "object", "description": "The definition of the deployment.\n", "properties": { "deployed_asset_type": { "type": "string", "description": "The type of the deployed model. The possible values are the following:\n\n1. `foundation_model` - when a prompt template is used on a\npre-deployed IBM provided model.\n\n2. `custom_foundation_model` - when a custom foundation model is deployed.\n\n3. `curated_foundation_model` - when a curated foundation model is deployed.\n" }, "verbalizer": { "type": "string", "description": "The verbalizer that was used to train this model.\n" }, "status": { "$ref": "#/components/schemas/DeploymentStatus" }, "tooling": { "$ref": "#/components/schemas/Tooling" } } } ] }, "DeploymentResource": { "type": "object", "description": "A deployment resource.", "properties": { "metadata": { "$ref": "#/components/schemas/ResourceMeta" }, "entity": { "$ref": "#/components/schemas/DeploymentEntity" } } }, "Stats": { "type": "object", "description": "The stats about deployments for a space.\n", "properties": { "space_id": { "type": "string", "description": "An `id` associated with the space.\n", "example": "2fc54cf1-252f-424b-b52d-5cdd98149871" }, "total_count": { "type": "number", "description": "The total number of deployments created in a space including `online` and `batch`.\n" }, "online_count": { "type": "number", "description": "The number of online deployments created in a space.\n" }, "batch_count": { "type": "number", "description": "The number of batch deployments created in a space.\n" } } }, "DeploymentSystemDetails": { "allOf": [ { "$ref": "#/components/schemas/SystemDetails" }, { "type": "object", "description": "Optional details provided by the service about statistics of the number of deployments created. The deployments that are counted will depend on the request parameters.\n", "properties": { "stats": { "type": "array", "description": "The stats about deployments.\n", "items": { "$ref": "#/components/schemas/Stats" } } } } ] }, "DeploymentSystem": { "type": "object", "description": "System details including warnings.\n", "properties": { "system": { "$ref": "#/components/schemas/DeploymentSystemDetails" } } }, "DeploymentResourceCollection": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "description": "The deployment resources.\n", "properties": { "resources": { "type": "array", "description": "A list of deployment resources.\n", "items": { "$ref": "#/components/schemas/DeploymentResource" } }, "system": { "$ref": "#/components/schemas/DeploymentSystem" } } } ] }, "EntityRequestSpaceProjectBody": { "type": "object", "description": "The properties that are part of a request that supports spaces and projects.\nEither `space_id` or `project_id` has to be provided and is mandatory.\n", "properties": { "name": { "type": "string", "description": "The name of the resource.\n", "example": "my-resource", "minLength": 1, "maxLength": 250 }, "project_id": { "$ref": "#/components/schemas/ProjectId" }, "space_id": { "$ref": "#/components/schemas/SpaceId" }, "description": { "type": "string", "description": "A description of the resource.\n", "example": "This is my first resource.", "maxLength": 1000 }, "tags": { "$ref": "#/components/schemas/Tags" } }, "required": [ "name" ] }, "Rel": { "allOf": [ { "$ref": "#/components/schemas/SimpleRel" }, { "type": "object", "properties": { "rev": { "description": "The revision of the referenced resource.\n", "type": "string", "example": "2" } } } ] }, "AssetRef": { "type": "object", "description": "The field that identifies the asset.\n", "properties": { "asset": { "$ref": "#/components/schemas/Rel" } } }, "DeploymentResourcePrototype": { "allOf": [ { "$ref": "#/components/schemas/EntityRequestSpaceProjectBody" }, { "$ref": "#/components/schemas/DeploymentEntityCommon" }, { "$ref": "#/components/schemas/AssetRef" }, { "$ref": "#/components/schemas/DeploymentResourceEntity" } ], "description": "The deployment request entity (this description is not used).\n", "example": { "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "name": "text_classification", "description": "Classification model deployment", "asset": { "id": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab" }, "online": { "parameters": { "serving_name": "classification" } }, "tags": [ "classification" ] } }, "JsonPatchOperation": { "type": "object", "description": "This model represents an individual patch operation to be performed on an object, as defined by\n[RFC 6902](https://tools.ietf.org/html/rfc6902).\n", "properties": { "op": { "type": "string", "description": "The operation to be performed.\n", "enum": [ "add", "remove", "replace" ] }, "path": { "type": "string", "description": "The pointer that identifies the field that is the target of the operation.\n" }, "value": { "type": "string", "description": "The value to be used within the operation.\n" } }, "required": [ "op", "path" ] }, "JsonPatch": { "description": "See [JSON PATCH RFC 6902](https://tools.ietf.org/html/rfc6902).\n", "type": "array", "items": { "$ref": "#/components/schemas/JsonPatchOperation" } }, "CaiKitTextGenProperties": { "type": "object", "description": "Properties that control the model and response that are only supported in caikit.\n", "properties": { "typical_p": { "type": "number", "description": "Local typicality measures how similar the conditional probability of predicting a target\ntoken next is to the expected conditional probability of predicting a random token next,\ngiven the partial text already generated. If less than 1, the smallest set of the most\nlocally typical tokens with probabilities that add up to typical_p or higher are kept for generation.\n", "minimum": 0, "exclusiveMinimum": true, "maximum": 1, "example": 0.5 } } }, "TextGenParameters2": { "allOf": [ { "$ref": "#/components/schemas/TextGenParameters" }, { "$ref": "#/components/schemas/CaiKitTextGenProperties" } ], "example": { "temperature": 0.8, "top_p": 0.5, "top_k": 50, "random_seed": 111, "repetition_penalty": 2, "min_new_tokens": 30, "max_new_tokens": 50, "typical_p": 0.5 } }, "PromptVariables": { "type": "object", "description": "The prompt variables.\n", "additionalProperties": { "type": "string" }, "example": { "doc_type": "emails", "entity_name": "Golden Retail", "country_name": "London" } }, "PromptTemplateVariables": { "type": "object", "description": "The template properties if this request refers to a prompt template.\n", "properties": { "prompt_variables": { "$ref": "#/components/schemas/PromptVariables" } } }, "DeploymentTextGenProperties": { "allOf": [ { "$ref": "#/components/schemas/TextGenParameters2" }, { "$ref": "#/components/schemas/PromptTemplateVariables" } ] }, "DeploymentTextGen": { "type": "object", "properties": { "input": { "type": "string", "description": "The prompt to generate completions.\nNote: The method tokenizes the input internally.\nIt is recommended not to leave any trailing spaces.\n\n\nThis field is ignored if there is a prompt template.\n" }, "parameters": { "$ref": "#/components/schemas/DeploymentTextGenProperties" }, "moderations": { "$ref": "#/components/schemas/Moderations" } } }, "DeploymentTextGenRequest": { "description": "A prompt to be used to infer the next tokens.\n", "allOf": [ { "$ref": "#/components/schemas/DeploymentTextGen" } ], "example": { "input": "Generate a marketing email advertising a new sale with the following characteristics:\n\nCompany: Swimwear Unlimited\n\nOffer Keywords: {Select customers only, mid-summer fun, swimwear sale}\n\nOffer End Date: July 15\n\nAdvertisement Tone: Exciting!\n\nInclude no URLs.\n\nInclude no telephone numbers.\n", "parameters": { "decoding_method": "sample", "temperature": 0.8, "max_new_tokens": 200 } } }, "TextChatMessage": { "type": "object", "description": "The base definition of a text chat message.\n", "discriminator": { "propertyName": "role" }, "properties": { "role": { "type": "string", "description": "The role of the messages author.\nNote that this parameter is case sensitive, make sure to use lower case.\n", "enum": [ "assistant", "system", "tool", "user" ] } }, "required": [ "role" ] }, "TextChatMessageFieldName": { "type": "string", "description": "An optional name for the participant.\nProvides the model information to differentiate between participants of the same role.\n" }, "TextChatFunctionCall": { "type": "object", "description": "The function call.\n", "properties": { "name": { "type": "string", "description": "The name of the function.\n" }, "arguments": { "type": "string", "description": "The arguments to call the function with,\nas generated by the model in JSON format.\n\nNote that the model does not always generate valid JSON,\nand may hallucinate parameters not defined by your function schema.\nValidate the arguments in your code before calling your function.\n" } }, "required": [ "name", "arguments" ] }, "TextChatToolCall": { "type": "object", "description": "The tool call.\n", "properties": { "id": { "type": "string", "description": "The ID of the tool call.\n" }, "type": { "type": "string", "description": "The type of the tool. Currently, only `function` is supported.\n", "enum": [ "function" ] }, "function": { "$ref": "#/components/schemas/TextChatFunctionCall" } }, "required": [ "id", "type", "function" ] }, "TextChatMessageAssistant": { "description": "The definition of an assistant message.\n", "allOf": [ { "$ref": "#/components/schemas/TextChatMessage" }, { "type": "object", "description": "The definition of an assistant message.\n", "properties": { "content": { "type": "string", "description": "The contents of the assistant message.\nRequired unless `tool_calls` is specified.\n" }, "name": { "$ref": "#/components/schemas/TextChatMessageFieldName" }, "refusal": { "type": "string", "description": "The refusal message by the assistant.\n", "nullable": true }, "tool_calls": { "type": "array", "description": "The tool calls generated by the model, such as function calls.\n", "items": { "$ref": "#/components/schemas/TextChatToolCall" }, "minItems": 1, "maxItems": 100 } } } ] }, "TextChatMessageControl": { "description": "The definition of a control message.\n", "allOf": [ { "$ref": "#/components/schemas/TextChatMessage" }, { "type": "object", "description": "The definition of a control message.\n", "properties": { "content": { "type": "string", "description": "The contents of the control message. Depending on the model, an example would be \"thinking\" for Granite reasoning models.\n" }, "name": { "$ref": "#/components/schemas/TextChatMessageFieldName" } }, "required": [ "content" ] } ] }, "TextChatMessageTool": { "description": "The definition of a tool message.\n", "allOf": [ { "$ref": "#/components/schemas/TextChatMessage" }, { "type": "object", "description": "The definition of a tool message.\n", "properties": { "content": { "type": "string", "description": "The contents of the tool message.\n" }, "tool_call_id": { "type": "string", "description": "Tool call that this message is responding to.\n" } }, "required": [ "content", "tool_call_id" ] } ] }, "TextChatUserContent": { "type": "object", "description": "The base definition of a text chat user content.\n", "discriminator": { "propertyName": "type" }, "properties": { "type": { "type": "string", "description": "The type of the user content. You can get the list of models supporting text, image, audio, video by using\n[Foundation Model Specs](#list-foundation-model-specs) with\n`filters=function_text_chat`, `filters=function_image_chat`, `filters=function_audio_chat`,\n`filters=function_video_chat` respectively.\n", "enum": [ "text", "image_url", "video_url" ] } }, "required": [ "type" ] }, "TextChatUserTextContent": { "description": "The definition of a user text content.\n", "allOf": [ { "$ref": "#/components/schemas/TextChatUserContent" }, { "type": "object", "description": "The definition of a user text content.\n", "properties": { "text": { "type": "string", "description": "The text content.\n" } }, "required": [ "text" ] } ] }, "TextChatUserImageURL": { "type": "object", "description": "The definition of a user image content.\n", "properties": { "url": { "type": "string", "description": "You can either set this string to a base64 encoded image, or use `data_asset` field to refer to an\nupload image.\n", "example": "data:image/jpeg;base64,{base64_image}" }, "detail": { "type": "string", "description": "This parameter controls how the model processes the image and generates its textual understanding.\nThe `auto` setting which will look at the image input\nsize and decide if it should use the `low` or `high` setting.\n", "enum": [ "low", "high", "auto" ], "default": "auto" } } }, "TextChatUserImageURLContent": { "description": "The definition of a user image content.\n", "allOf": [ { "$ref": "#/components/schemas/TextChatUserContent" }, { "type": "object", "description": "The definition of a user image content.\n", "properties": { "image_url": { "$ref": "#/components/schemas/TextChatUserImageURL" }, "data_asset": { "type": "object", "description": "The data asset of an image uploaded into the `space_id` or `project_id`. If `data_asset` is specified,\nthe `url` field in `image_url` will be automatically set with the URL of the uploaded image.\n", "properties": { "id": { "type": "string", "description": "The id of the asset" } }, "required": [ "id" ] } } } ] }, "TextChatUserVideoURL": { "type": "object", "description": "The definition of a user video content.\n", "properties": { "url": { "type": "string", "description": "You can either set this string to a base64 encoded video, or use `data_asset` field to refer to an\nupload video.\n", "example": "data:video/mp4;base64,{base64_video}" } } }, "TextChatUserVideoURLContent": { "description": "The definition of a user video content.\n", "allOf": [ { "$ref": "#/components/schemas/TextChatUserContent" }, { "type": "object", "description": "The definition of a user video content.\n", "properties": { "video_url": { "$ref": "#/components/schemas/TextChatUserVideoURL" }, "data_asset": { "type": "object", "description": "The data asset of a video uploaded into the `space_id` or `project_id`. If `data_asset` is specified,\nthe `url` field in `video_url` will be automatically set with the URL of the uploaded video.\n", "properties": { "id": { "type": "string", "description": "The id of the asset" } }, "required": [ "id" ] } } } ] }, "TextChatUserInputAudio": { "type": "object", "description": "The definition of a user audio content.\n", "properties": { "data": { "type": "string", "description": "You can either set this string to a base64 encoded audio, or use `data_asset` field to refer to an\nupload audio file.\n", "example": "{base64_audio}" }, "format": { "type": "string", "description": "Either `wav` or `mp3`.\n" } } }, "TextChatUserAudioContent": { "description": "The definition of a user audio content.\n", "allOf": [ { "$ref": "#/components/schemas/TextChatUserContent" }, { "type": "object", "description": "The definition of a user audio content.\n", "properties": { "input_audio": { "$ref": "#/components/schemas/TextChatUserInputAudio" }, "data_asset": { "type": "object", "description": "The data asset of an audio uploaded into the `space_id` or `project_id`. If `data_asset` is specified,\nthe `data` field in `input_audio` will be automatically set with the URL of the uploaded audio.\n", "properties": { "id": { "type": "string", "description": "The id of the asset" } }, "required": [ "id" ] } } } ] }, "TextChatUserContents": { "oneOf": [ { "$ref": "#/components/schemas/TextChatUserTextContent" }, { "$ref": "#/components/schemas/TextChatUserImageURLContent" }, { "$ref": "#/components/schemas/TextChatUserVideoURLContent" }, { "$ref": "#/components/schemas/TextChatUserAudioContent" } ], "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/TextChatUserTextContent", "image_url": "#/components/schemas/TextChatUserImageURLContent", "video_url": "#/components/schemas/TextChatUserVideoURLContent", "input_audio": "#/components/schemas/TextChatUserAudioContent" } } }, "TextChatMessageUser": { "description": "The definition of a user message.\n", "allOf": [ { "$ref": "#/components/schemas/TextChatMessage" }, { "type": "object", "description": "The definition of a user message.\n", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/TextChatUserContents" }, "minItems": 1, "maxItems": 100 }, "name": { "$ref": "#/components/schemas/TextChatMessageFieldName" } }, "required": [ "content" ] } ] }, "DeploymentTextChatMessages": { "oneOf": [ { "$ref": "#/components/schemas/TextChatMessageAssistant" }, { "$ref": "#/components/schemas/TextChatMessageControl" }, { "$ref": "#/components/schemas/TextChatMessageTool" }, { "$ref": "#/components/schemas/TextChatMessageUser" } ], "discriminator": { "propertyName": "role", "mapping": { "assistant": "#/components/schemas/TextChatMessageAssistant", "control": "#/components/schemas/TextChatMessageControl", "tool": "#/components/schemas/TextChatMessageTool", "user": "#/components/schemas/TextChatMessageUser" } } }, "TextChatPropertyTool": { "type": "string", "description": "The tool type.\n", "enum": [ "function" ] }, "TextChatParameterFunction": { "type": "object", "description": "The parameters specific to chat.\n", "properties": { "name": { "type": "string", "description": "The name of the function.\n", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z]+[a-zA-Z0-9-_]*$" }, "description": { "type": "string", "description": "A description of what the function does,\nused by the model to choose when and how to call the function.\n" }, "parameters": { "type": "object", "description": "The parameters the functions accepts, described as a JSON Schema object.\nSee the [JSON Schema reference](https://json-schema.org/learn/getting-started-step-by-step)\nfor documentation about the format.\n\nOmitting parameters defines a function with an empty parameter list.\n" } }, "required": [ "name" ] }, "TextChatParameterTools": { "type": "object", "description": "The chat tool parameters.\n", "properties": { "type": { "$ref": "#/components/schemas/TextChatPropertyTool" }, "function": { "$ref": "#/components/schemas/TextChatParameterFunction" } }, "required": [ "type" ] }, "TextChatToolChoiceOption": { "type": "string", "description": "Specify either `tool_choice_option` to allow the model to pick or `tool_choice` to force the model to call a tool.\n\nUsing `auto` means the model can pick between generating a message or calling one or more tools. Default is `auto`.\n\nUsing `none` means the model will not call any tool and instead generates a message.\n\nUsing `required` means the model must call one or more tools.\n", "enum": [ "auto", "none", "required" ] }, "TextChatToolFunction": { "type": "object", "description": "The named function.\n", "properties": { "name": { "type": "string", "description": "The name of the function.\n" } }, "required": [ "name" ] }, "TextChatToolChoiceTool": { "type": "object", "description": "Specifying a particular tool via `{\"type\": \"function\", \"function\": {\"name\": \"my_function\"}}` forces the model to call that tool.\nSpecify either `tool_choice_option` to allow the model to pick or `tool_choice` to force the model to call a tool.\n", "properties": { "type": { "$ref": "#/components/schemas/TextChatPropertyTool" }, "function": { "$ref": "#/components/schemas/TextChatToolFunction" } }, "required": [ "type", "function" ] }, "TextChatResponseFormat": { "type": "object", "description": "The chat response format parameters.\n", "properties": { "type": { "type": "string", "description": "Used to enable JSON mode, which guarantees the message the model generates is valid JSON.\n\n**Important:** when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message.\nWithout this, the model may generate an unending stream of whitespace until the generation reaches the token limit,\nresulting in a long-running and seemingly \"stuck\" request.\nAlso note that the message content may be partially cut off if `finish_reason=\"length\"`,\nwhich indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length.\n\n- `text` : **Will not** create a JSON structured output.\n- `json_object` : User will get a JSON structured output, but the schema is not guranteed.\n- `json_schema` : User needs to declare the `json_schema` object to provide the desired JSON schema in order to get a matched response.\n", "enum": [ "text", "json_object", "json_schema" ] }, "json_schema": { "type": "object", "description": "User-defined JSON schema object with optional parameters to enforce structured output.\n\n**Important:** this field will only applied when `response_format`.`type` is set to `json_schema`.\n", "properties": { "name": { "type": "string", "description": "A customized name for the JSON schema.\n" }, "schema": { "type": "object", "description": "To ensure structured responses from the model, user needs to define a JSON schema to define our output structure, which specifies the fields, their types, and which ones are required.\n" }, "strict": { "type": "boolean", "description": "Setting `strict` to **true** will enforce the schema. Setting `strict` to **false** will allow the model to return additional fields that are not specified in the schema.\n" } } } }, "required": [ "type" ] }, "TextChatParameters": { "type": "object", "description": "The parameters specific to chat.\n", "properties": { "chat_template_kwargs": { "type": "object", "description": "Additional kwargs to pass to the chat template, described as a JSON Schema object.\nSee the [JSON Schema reference](https://json-schema.org/learn/getting-started-step-by-step)\nfor documentation about the format.\n", "example": { "thinking": true } }, "frequency_penalty": { "type": "number", "description": "Positive values penalize new tokens based on their existing frequency in the text so far,\ndecreasing the model's likelihood to repeat the same line verbatim.\n", "minimum": -2, "exclusiveMinimum": true, "maximum": 2, "exclusiveMaximum": true, "default": 0, "nullable": true }, "include_reasoning": { "type": "boolean", "description": "Whether to include `reasoning_content` in the response. Default is `true`.\n" }, "logit_bias": { "type": "object", "description": "Increasing or decreasing probability of tokens being selected during generation;\na positive bias makes a token more likely to appear, while a negative bias makes it less likely.\n", "example": { "1003": -100, "1004": -100 } }, "logprobs": { "type": "boolean", "description": "Whether to return log probabilities of the output tokens or not.\nIf true, returns the log probabilities of each output token returned in the content of message.\n", "default": false, "nullable": true }, "top_logprobs": { "type": "integer", "description": "An integer specifying the number of most likely tokens to return at each token position,\neach with an associated log probability.\nThe option `logprobs` must be set to `true` if this parameter is used.\n", "minimum": 0, "maximum": 20, "nullable": true }, "max_completion_tokens": { "type": "integer", "description": "The maximum number of tokens that can be generated in the chat completion.\nThe total length of input tokens and generated tokens is limited by the model's context length.\nSet to 0 for the model's configured max generated tokens.\n", "nullable": true, "default": 1024 }, "max_tokens": { "type": "integer", "description": "The maximum number of tokens that can be generated in the chat completion.\nThe total length of input tokens and generated tokens is limited by the model's context length.\nSet to 0 for the model's configured max generated tokens.\n\nThis value is now deprecated in favor of `max_completion_tokens`. If specified together with `max_completion_tokens`,\n`max_tokens` will be ignored.\n", "nullable": true, "default": 1024 }, "n": { "type": "integer", "description": "How many chat completion choices to generate for each input message.\nNote that you will be charged based on the number of generated tokens across all of the choices.\nKeep n as 1 to minimize costs.\n", "nullable": true, "default": 1 }, "presence_penalty": { "type": "number", "description": "Positive values penalize new tokens based on whether they appear in the text so far,\nincreasing the model's likelihood to talk about new topics.\n", "minimum": -2, "exclusiveMinimum": true, "maximum": 2, "exclusiveMaximum": true, "default": 0, "nullable": true }, "reasoning_effort": { "type": "string", "description": "A lower reasoning effort can result in faster responses, fewer tokens used, and shorter `reasoning_content`\nin the responses. Supported values are `low`, `medium`, and `high`.\n", "enum": [ "low", "medium", "high" ] }, "response_format": { "$ref": "#/components/schemas/TextChatResponseFormat" }, "seed": { "type": "integer", "description": "Random number generator seed to use in sampling mode for experimental repeatability.\n", "example": 41 }, "stop": { "type": "array", "minItems": 0, "maxItems": 4, "uniqueItems": true, "description": "Stop sequences are one or more strings which will cause the text generation to stop if/when they are produced as part of the output.\nStop sequences encountered prior to the minimum number of tokens being generated will be ignored.\n", "example": [ "this", "the" ], "items": { "type": "string" } }, "stream": { "type": "boolean", "description": "If set to true, this operation will return the output tokens as a stream of events, and usage is always included in the response.\n", "example": true }, "temperature": { "type": "number", "description": "What sampling temperature to use,. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.\n\nWe generally recommend altering this or `top_p` but not both.\n", "minimum": 0, "exclusiveMinimum": true, "maximum": 2, "exclusiveMaximum": true, "default": 1, "nullable": true }, "top_p": { "type": "number", "description": "An alternative to sampling with temperature, called nucleus sampling,\nwhere the model considers the results of the tokens with top_p probability mass.\nSo 0.1 means only the tokens comprising the top 10% probability mass are considered.\n\nWe generally recommend altering this or `temperature` but not both.\n", "minimum": 0, "exclusiveMinimum": true, "maximum": 1, "exclusiveMaximum": true, "default": 1, "nullable": true }, "time_limit": { "type": "integer", "description": "Time limit in milliseconds - if not completed within this time, generation will stop.\nThe text generated so far will be returned along with the `TIME_LIMIT`` stop reason.\nDepending on the users plan, and on the model being used, there may be an enforced maximum time limit.\n", "minimum": 0, "exclusiveMinimum": true, "example": 600000 } } }, "DeploymentTextChat": { "allOf": [ { "type": "object", "properties": { "messages": { "type": "array", "description": "The messages for this chat session.\n\nIf the deployment references a prompt template then `system` `role` can not be in `messages`.\nFor such deployments, depending on the model, the `content` of `system` `role` may be from `system_prompt` of\nthe prompt template, and will be automatically inserted into `messages`.\nAs an example, depending on the model, if `system_prompt` of a prompt template is \"You are Granite Chat, an AI language model developed by IBM. You are a cautious assistant. You carefully follow instructions.\nYou are helpful and harmless and you follow ethical guidelines and promote positive behavior.\",\na message with `system` `role` having `content` the same as `system_prompt` is inserted.\n", "items": { "$ref": "#/components/schemas/DeploymentTextChatMessages" }, "minItems": 1, "maxItems": 1000 }, "tools": { "type": "array", "description": "Tool functions that can be called with the response.\n", "items": { "$ref": "#/components/schemas/TextChatParameterTools" }, "minItems": 1, "maxItems": 128 }, "tool_choice_option": { "$ref": "#/components/schemas/TextChatToolChoiceOption" }, "tool_choice": { "$ref": "#/components/schemas/TextChatToolChoiceTool" }, "context": { "type": "string", "description": "If specified, `context` will be inserted into `messages`. Depending on the model, `context` may be inserted into the `content` with `system` `role`; or\ninto the `content` of the last message of `user` `role`.\n\n\nIn the example, `context` \"Today is Wednesday\" is inserted as such\n`content` of `user` becomes \"Today is Wednesday. Who are you and which day is tomorrow?\"\n" } }, "required": [ "messages" ] }, { "$ref": "#/components/schemas/TextChatParameters" } ] }, "DeploymentTextChatRequest": { "description": "A prompt to be used to infer the next tokens.\n", "allOf": [ { "$ref": "#/components/schemas/DeploymentTextChat" } ] }, "TextChatUsage": { "type": "object", "description": "Usage statistics for the completion request.\n", "properties": { "completion_tokens": { "type": "integer", "format": "int64", "description": "Number of tokens in the generated completion.\n", "minimum": 0 }, "prompt_tokens": { "type": "integer", "format": "int64", "description": "Number of tokens in the prompt.\n", "minimum": 0 }, "total_tokens": { "type": "integer", "format": "int64", "description": "Total number of tokens used in the request (prompt + completion).\n", "minimum": 0 } } }, "TextChatResponseFieldsShared": { "type": "object", "description": "A chat completion.\n", "properties": { "id": { "type": "string", "description": "A unique identifier for the chat completion.\n" }, "model_id": { "type": "string", "description": "The model used for the chat completion.\n", "example": "google/flan-ul2" }, "model": { "type": "string", "description": "This field is a duplicate of `model_id` and is provided in order\nto provide better compatibility with other APIs.\n" }, "model_version": { "$ref": "#/components/schemas/ModelVersion" }, "created": { "type": "integer", "description": "The Unix timestamp (in seconds) of when the chat completion was created.\n" }, "created_at": { "$ref": "#/components/schemas/CreatedAt" }, "usage": { "$ref": "#/components/schemas/TextChatUsage" }, "moderations": { "$ref": "#/components/schemas/ModerationResults" } }, "required": [ "id", "model_id", "created" ] }, "TextChatResultMessage": { "type": "object", "description": "A message result.\n", "properties": { "role": { "type": "string", "description": "The role of the author of this message.\n" }, "content": { "type": "string", "description": "The contents of the message.\n", "nullable": true }, "refusal": { "type": "string", "description": "The refusal message generated by the model.\n", "nullable": true }, "tool_calls": { "type": "array", "description": "The tool calls generated by the model, such as function calls.\n", "items": { "$ref": "#/components/schemas/TextChatToolCall" }, "minItems": 1 } }, "required": [ "role" ] }, "TextChatFinishReason": { "type": "string", "nullable": true, "description": "The reason why the call stopped, can be one of:\n- `stop` - The model hit a natural stop point or a provided stop sequence.\n- `length` - The maximum number of tokens specified in the request was reached.\n- `tool_calls` - The model called a tool.\n- `time_limit`` - Time limit reached.\n- `cancelled`` - Request canceled by the client.\n- `error`` - Error encountered.\n- `null` - API response still in progress or incomplete.\n", "enum": [ "stop", "length", "tool_calls", "time_limit", "cancelled", "error" ] }, "TextChatResultChoice": { "allOf": [ { "type": "object", "description": "A tool related result.\n", "properties": { "index": { "type": "integer", "description": "The index of this result.\n" }, "message": { "$ref": "#/components/schemas/TextChatResultMessage" }, "finish_reason": { "$ref": "#/components/schemas/TextChatFinishReason" } } } ] }, "TextChatResponseFields": { "type": "object", "description": "A chat completion choices.\n", "properties": { "choices": { "type": "array", "description": "A list of chat completion choices. Can be more than one if `n` is greater than 1.\n", "items": { "$ref": "#/components/schemas/TextChatResultChoice" }, "minItems": 1 } }, "required": [ "choices" ] }, "TextChatResponse": { "allOf": [ { "$ref": "#/components/schemas/TextChatResponseFieldsShared" }, { "$ref": "#/components/schemas/TextChatResponseFields" }, { "$ref": "#/components/schemas/System" } ] }, "TextChatToolCallStream": { "type": "object", "description": "The tool call.\n", "properties": { "index": { "type": "number", "description": "The index of the tool call.\n" }, "id": { "type": "string", "description": "The ID of the tool call.\n" }, "type": { "type": "string", "description": "The type of the tool. Currently, only `function` is supported.\n", "enum": [ "function" ] }, "function": { "$ref": "#/components/schemas/TextChatFunctionCall" } }, "required": [ "index", "function" ] }, "TextChatResultDelta": { "type": "object", "description": "A message result.\n", "properties": { "role": { "type": "string", "description": "The role of the author of this message.\n" }, "content": { "type": "string", "description": "The contents of the message.\n", "nullable": true }, "refusal": { "type": "string", "description": "The refusal message generated by the model.\n", "nullable": true }, "tool_calls": { "type": "array", "description": "The tool calls generated by the model, such as function calls.\n", "items": { "$ref": "#/components/schemas/TextChatToolCallStream" }, "minItems": 1 } }, "required": [ "role" ] }, "TextChatResultChoiceStream": { "allOf": [ { "type": "object", "description": "A tool related result.\n", "properties": { "index": { "type": "integer", "description": "The index of this result.\n" }, "delta": { "$ref": "#/components/schemas/TextChatResultDelta" }, "finish_reason": { "$ref": "#/components/schemas/TextChatFinishReason" } } } ] }, "TextChatResponseFieldsStream": { "type": "object", "description": "A chat completion choices.\n", "properties": { "choices": { "type": "array", "description": "A list of chat completion choices. Can be more than one if `n` is greater than 1.\n", "items": { "$ref": "#/components/schemas/TextChatResultChoiceStream" }, "minItems": 1 } }, "required": [ "choices" ] }, "TextChatStreamItem": { "allOf": [ { "$ref": "#/components/schemas/TextChatResponseFieldsShared" }, { "$ref": "#/components/schemas/TextChatResponseFieldsStream" }, { "$ref": "#/components/schemas/System" } ] }, "TextChatStreamResponse": { "type": "array", "description": "A set of server sent events, each event contains a response for one or more tokens. The results will be an array of events of the form `data: {}` where the schema of the individual `json event` is described below.\n", "items": { "$ref": "#/components/schemas/TextChatStreamItem" } }, "TSCommonForecastParameters": { "type": "object", "description": "The parameters for the forecast request.\n", "properties": { "prediction_length": { "type": "integer", "nullable": true, "description": "The prediction length for the forecast. The service will return this\nmany periods beyond the last timestamp in the inference data\npayload. If specified, `prediction_length` must be an integer >=1\nand no more than the model default prediction length. When omitted\nthe model default prediction_length will be used.\n" } } }, "DeploymentTSForecastParameters": { "allOf": [ { "$ref": "#/components/schemas/TSCommonForecastParameters" }, { "type": "object", "properties": { "inference_batch_size": { "type": "integer", "nullable": true, "description": "The batch size used during inference.\nWhen multiple time series are present, the inference will be\nconducted in batches. If not specified, the model default batch\nsize will be used.\n" } } } ] }, "TSForecastInputSchema": { "type": "object", "description": "Contains metadata about your timeseries data input.\n", "properties": { "timestamp_column": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^\\S.*\\S$|^\\S$", "description": "A valid column in the data that should be treated as the timestamp.\nAlthough not absolutely necessary, if using calendar dates (simple\ninteger time offsets are also allowed), users should consider using\na format such as ISO 8601 that includes a UTC offset (e.g.,\n'2024-10-18T01:09:21.454746+00:00'). This will avoid potential\nissues such as duplicate dates appearing due to daylight savings\nchange overs. There are many date formats in existence and inferring\nthe correct one can be a challenge so please do consider adhering to\nISO 8601.\n" }, "id_columns": { "items": { "type": "string", "minLength": 0, "maxLength": 100, "pattern": "^\\S.*\\S$|^\\S$" }, "type": "array", "minItems": 0, "maxItems": 10, "description": "Columns that define a unique key for timeseries. This is similar to\na compound primary key in a database table.\n" }, "freq": { "type": "string", "minLength": 0, "maxLength": 100, "pattern": "^\\d*\\.?\\d*(B|D|W|M|Q|Y|h|min|s|ms|us|ns)?$", "description": "A frequency indicator for the given timestamp_column.\nSee https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#period-aliases\nfor a description of the allowed values. If not provided, we will attempt to\ninfer it from the data.\n", "example": "1h" }, "target_columns": { "items": { "type": "string", "minLength": 0, "maxLength": 100, "pattern": "^\\S.*\\S$|^\\S$" }, "type": "array", "minItems": 0, "maxItems": 500, "description": "An array of column headings which constitute the target variables in\nthe data. These are the data that will be forecasted.\n" } }, "required": [ "timestamp_column" ] }, "DeploymentTSForecastResource": { "type": "object", "description": "Input necessary for performing inference. These inputs\nidentify things like which model to use, the data payload\nyou are passing to the model, and other parameters which affect\nthe behavior of the inference operation.\n", "example": { "schema": { "timestamp_column": "date", "id_columns": [ "ID1" ] }, "data": { "date": [ "2020-01-01T00:00:00", "2020-01-01T01:00:00", "2020-01-01T02:00:00" ], "ID1": [ "D1", "D1", "D1" ], "TARGET1": [ 1.46, 2.34, 4.55 ] } }, "properties": { "data": { "type": "object", "description": "A payload of data matching `schema`.\nWe assume the following about your data:\n * All timeseries are of equal length and are uniform in nature (the time difference\nbetween two successive rows is constant). This implies that there are no missing rows of data;\n * The data meet the minimum model-dependent historical context length which\n can be any number of rows per timeseries;\n\nNote that the example payloads shown are for illustration purposes only. An actual payload\nwould necessary be much larger to meet minimum model-specific context lengths.\n", "additionalProperties": {} }, "parameters": { "$ref": "#/components/schemas/DeploymentTSForecastParameters" }, "schema": { "$ref": "#/components/schemas/TSForecastInputSchema" }, "future_data": { "type": "object", "description": "Exogenous or supporting features that extend into the forecasting\nhorizon (e.g., a weather forecast or calendar of special promotions)\nwhich are known in advance. `future_data` would be in the same\nformat as `data` except that all timestamps would be in the\nforecast horizon and it would not include previously specified\n`target_columns`.\n", "additionalProperties": {} } }, "required": [ "data", "schema" ] }, "TSForecastResults": { "type": "object", "description": "Prediction results.\n", "additionalProperties": {} }, "TSForecastResponse": { "type": "object", "description": "The time series forecast response.\n", "properties": { "model_id": { "type": "string", "description": "The model used to generate the forecast.\n", "example": "ibm/ttm-1024-96-r2" }, "created_at": { "$ref": "#/components/schemas/CreatedAt" }, "results": { "type": "array", "description": "The list of prediction results. There will be a forecast for each time series in the input data.\nThe `prediction_length` field in the request specifies the number of predictions in the results.\nThe actual number of rows in the results will be equal to the `prediction length` multiplied by the number of unique ids\nin `id_columns`.\nThe `timestamp_column` field in the request indicates the name of the timestamp column in the results.\n", "items": { "$ref": "#/components/schemas/TSForecastResults" }, "example": [ { "date": [ "2020-01-01T03:00:00", "2020-01-01T04:00:00", "2020-01-01T05:00:00" ], "ID1": [ "D1", "D1", "D1" ], "TARGET1": [ 1.86, 3.78, 6.78 ] } ] }, "input_data_points": { "type": "integer", "description": "The number of input data points (number of rows in `data` * number of input columns in `data`).\n", "example": 512 }, "output_data_points": { "type": "integer", "description": "The number of forecasted data points (`prediction_length` * number of `target_columns` * number of unique ids in `id_columns`).\n", "example": 1024 } } }, "DeploymentAIServiceRequest": { "type": "object", "description": "Any valid json that matches what the deployed AI service expects.\n" }, "DeploymentAIServiceResponse": { "type": "object", "description": "The response depends entirely on the deployed AI service.\nNormally this would be `json` but this is not enforced.\n" }, "DeploymentAIServiceStreamResponse": { "description": "A set of server sent events, each event contains a response for one or more tokens. The results will be an array of events of the form `id: , event: , data: <(json) message>`. Each event type will be `message`, with the last event of type `eos`.\n", "type": "array", "items": { "$ref": "#/components/schemas/DeploymentAIServiceResponse" }, "example": [ { "id": 1, "event": "message", "data": "..." }, { "id": 2, "event": "message", "data": "..." }, { "id": 3, "event": "message", "data": "..." }, { "id": 4, "event": "eos" } ] }, "DataConnection": { "type": "object", "description": "Contains a set of fields specific to each connection.\nSee here for [details about specifying connections](#datareferences).\n" }, "DataLocation": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Contains a set of fields that describe the location of the data with respect to the `connection`.\n" }, "DataSchema": { "title": "data_schema", "type": "object", "description": "The schema of the expected data, see\n[datarecord-metadata-v2-schema](https://raw.githubusercontent.com/elyra-ai/pipeline-schemas/master/common-pipeline/datarecord-metadata/datarecord-metadata-v2-schema.json)\nfor the schema definition.\n", "properties": { "id": { "description": "An id to identify a schema.\n", "type": "string", "example": "t1" }, "name": { "description": "A name for the schema.\n", "type": "string", "example": "Tasks" }, "fields": { "type": "array", "description": "The fields that describe the data schema.\n", "items": { "type": "object", "description": "A description of a field in the data schema.\n" }, "example": [ { "name": "duration", "type": "number" } ] }, "type": { "description": "The type of the schema, can be ignored or set to `struct` or `DataFrame`.\n", "type": "string", "example": "struct" } }, "required": [ "id", "fields" ] }, "DataConnectionReference": { "title": "data_connection", "type": "object", "description": "A reference to data with an optional data schema.\nIf necessary, it is possible to provide a data connection that contains\njust the data schema.\n", "properties": { "id": { "type": "string", "description": "Optional item identification inside a collection.\n", "example": "8d3682dd-2858-43c9-bfd7-12a79abcfb0c" }, "type": { "description": "The data source type like `connection_asset` or `data_asset`.\nIf the data connection contains just a schema then this field is not required.\n", "type": "string", "enum": [ "connection_asset", "data_asset", "container", "url" ], "example": "connection_asset" }, "connection": { "$ref": "#/components/schemas/DataConnection" }, "location": { "$ref": "#/components/schemas/DataLocation" }, "schema": { "$ref": "#/components/schemas/DataSchema" } }, "required": [ "type" ] }, "TrainingResourceEntityCommon": { "type": "object", "properties": { "training_data_references": { "type": "array", "description": "Training datasets.\n", "items": { "$ref": "#/components/schemas/DataConnectionReference" }, "example": [ { "id": "tune1_data.json", "location": { "path": "tune1_data.json" }, "type": "container" } ] }, "custom": { "$ref": "#/components/schemas/Custom" }, "auto_update_model": { "type": "boolean", "description": "If set to `true` then the result of the training, if successful, will be\nuploaded to the repository as a model.\n", "default": false } } }, "ObjectLocation": { "type": "object", "description": "A reference to data.\n", "properties": { "type": { "description": "The data source type.\n\n\nThe possible types will depend\non the API and platform being used.\n", "type": "string" }, "location": { "$ref": "#/components/schemas/DataLocation" }, "connection": { "$ref": "#/components/schemas/DataConnection" }, "id": { "type": "string", "description": "Item identification inside a collection, if appropriate.\n" } }, "required": [ "type", "location" ] }, "ResultsReferenceOutput": { "type": "object", "properties": { "results_reference": { "allOf": [ { "$ref": "#/components/schemas/ObjectLocation" } ], "description": "The training results. Normally this is specified as `type=container` which means that it is stored in the space or project. Note that the training will add some fields that point to the training status, the model request and the assets.\n\nThe `model_request_path` is the request body that should be used when creating the trained model in the API, if this model is to be deployed. If `auto_update_model` was set to `true` then this file is not needed.\n", "example": { "location": { "path": "results", "training": "results/360c40f7-ac0c-43ca-a95f-1a5421f93b82", "training_status": "results/360c40f7-ac0c-43ca-a95f-1a5421f93b82/training-status.json", "assets_path": "results/360c40f7-ac0c-43ca-a95f-1a5421f93b82/assets", "model_request_path": "results/360c40f7-ac0c-43ca-a95f-1a5421f93b82/assets/c29e7544-dfd0-4427-bc66-20fa6023e2e0/resources/wml_model/request.json" }, "type": "container" } } }, "required": [ "results_reference" ] }, "TrainingMLMetrics": { "type": "object", "additionalProperties": { "type": "number" }, "description": "The metrics.\n", "example": { "loss": 4.49988 } }, "FineTuningTrainingMetrics": { "type": "object", "description": "The metrics that can be returned by a fine tuning job created with InstructLab.\n", "additionalProperties": true }, "FineTuningMetricsContext": { "type": "object", "description": "This field will not be returned by prompt tuning jobs.\n\nThe context for fine tuning metrics.\n", "properties": { "metrics_location": { "type": "string", "description": "The location where the fine tuning metrics are stored.\n" } } }, "MetricsContext": { "description": "Provides extra information for this training stage in the context of auto-ml.\n", "type": "object", "properties": { "deployment_id": { "type": "string", "description": "This field will not returned by fine tuning jobs created with InstructLab.\n\nThe deployment that created the metrics.\n" }, "fine_tuning": { "$ref": "#/components/schemas/FineTuningMetricsContext" }, "locations": { "type": "object", "description": "The locations of the fine tuning jobs information when it is created with InstructLab.", "additionalProperties": { "type": "string" } } } }, "TrainingMetric": { "type": "object", "description": "A metric.\n", "properties": { "timestamp": { "type": "string", "example": "2023-09-22T02:52:03.324Z", "format": "date-time", "description": "A timestamp for the metrics.\n" }, "iteration": { "type": "integer", "example": 0, "description": "The iteration number.\n" }, "ml_metrics": { "$ref": "#/components/schemas/TrainingMLMetrics" }, "fine_tuning_metrics": { "$ref": "#/components/schemas/FineTuningTrainingMetrics" }, "context": { "$ref": "#/components/schemas/MetricsContext" } } }, "TrainingMetrics": { "type": "array", "description": "Metrics that can be returned by an operation.\n", "items": { "$ref": "#/components/schemas/TrainingMetric" }, "example": [ { "iteration": 0, "ml_metrics": { "loss": 4.49988 }, "timestamp": "2023-09-22T02:52:03.324Z" }, { "iteration": 1, "ml_metrics": { "loss": 3.86884 }, "timestamp": "2023-09-22T02:52:03.689Z" }, { "iteration": 2, "ml_metrics": { "loss": 4.05115 }, "timestamp": "2023-09-22T02:52:04.053Z" } ] }, "TrainingStatus": { "type": "object", "description": "Status of the training job.\n", "properties": { "running_at": { "type": "string", "description": "Date and Time in which current training state has started.", "example": "2017-01-30T10:11:12Z", "format": "date-time" }, "completed_at": { "type": "string", "description": "Date and Time in which training had completed.", "example": "2017-01-30T10:11:12Z", "format": "date-time" }, "state": { "type": "string", "description": "Current state of training.", "enum": [ "queued", "pending", "running", "storing", "completed", "failed", "canceled" ] }, "message": { "$ref": "#/components/schemas/Message" }, "metrics": { "$ref": "#/components/schemas/TrainingMetrics" }, "failure": { "$ref": "#/components/schemas/ApiErrorResponse" } }, "required": [ "state" ], "example": { "state": "completed", "running_at": "2023-08-04T13:22:48.000Z", "completed_at": "2023-08-04T13:22:55.289Z", "message": { "level": "info", "text": "Training job 360c40f7-ac0c-43ca-a95f-1a5421f93b82 completed" } } }, "TrainingStatusOutput": { "type": "object", "description": "Status of the training job.\n", "properties": { "status": { "$ref": "#/components/schemas/TrainingStatus" } }, "required": [ "status" ] }, "TrainingResourceModelIdOutput": { "type": "object", "properties": { "model_id": { "type": "string", "description": "This may be set to the model that was created from the results of this training.\nUsing the option `auto_update_model` will cause this field to get set.\n" } } }, "TrainingResourceEntity": { "allOf": [ { "$ref": "#/components/schemas/TrainingResourceEntityCommon" }, { "$ref": "#/components/schemas/ResultsReferenceOutput" }, { "$ref": "#/components/schemas/TrainingStatusOutput" }, { "$ref": "#/components/schemas/TrainingResourceModelIdOutput" } ], "example": { "prompt_tuning": { "base_model": { "model_id": "google/flan-t5-xl" }, "task_id": "classification" }, "training_data_references": [ { "id": "tune1_data.json", "location": { "path": "tune1_data.json" }, "type": "container" } ], "auto_update_model": true, "results_reference": { "location": { "path": "tune1/results", "training": "tune1/results/360c40f7-ac0c-43ca-a95f-1a5421f93b82", "training_status": "tune1/results/360c40f7-ac0c-43ca-a95f-1a5421f93b82/training-status.json", "assets_path": "tune1/results/360c40f7-ac0c-43ca-a95f-1a5421f93b82/assets", "model_request_path": "tune1/results/360c40f7-ac0c-43ca-a95f-1a5421f93b82/assets/c29e7544-dfd0-4427-bc66-20fa6023e2e0/resources/wml_model/request.json" }, "type": "container" }, "status": { "state": "completed", "running_at": "2023-08-04T13:22:48.000Z", "completed_at": "2023-08-04T13:22:55.289Z", "message": { "level": "info", "text": "Training job 360c40f7-ac0c-43ca-a95f-1a5421f93b82 completed" } } } }, "TrainingResource": { "type": "object", "description": "Training resource.\n", "properties": { "metadata": { "$ref": "#/components/schemas/ResourceMeta" }, "entity": { "$ref": "#/components/schemas/TrainingResourceEntity" } } }, "TrainingResourceCollection": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "properties": { "resources": { "type": "array", "description": "The training resources.\n", "items": { "$ref": "#/components/schemas/TrainingResource" } }, "system": { "allOf": [ { "$ref": "#/components/schemas/SystemDetails" } ], "example": { "warnings": [ { "message": "This model is a Non-IBM Product governed by a third-party license that may impose use restrictions and other obligations.", "id": "DisclaimerWarning" } ] } } } } ] }, "TrainingResourceDetails": { "type": "object", "description": "The training details required when creating the job.\n", "properties": { "name": { "type": "string", "description": "The name of the training.\n", "example": "my-prompt-training" }, "space_id": { "$ref": "#/components/schemas/SpaceId" }, "project_id": { "$ref": "#/components/schemas/ProjectId" }, "description": { "type": "string", "description": "A description of the training.\n", "example": "My prompt training." }, "tags": { "$ref": "#/components/schemas/Tags" } }, "required": [ "name" ] }, "ResultsLocation": { "type": "object", "description": "A reference to data.\n", "properties": { "id": { "type": "string", "description": "Item identification inside a collection.\n" }, "type": { "description": "The data source type like `connection_asset`, `container` (Service) or `fs` (Software).\n", "type": "string", "enum": [ "connection_asset", "container" ], "example": "connection_asset" }, "connection": { "$ref": "#/components/schemas/DataConnection" }, "location": { "$ref": "#/components/schemas/DataLocation" } }, "required": [ "type", "location" ] }, "ResultsReferenceInput": { "type": "object", "properties": { "results_reference": { "allOf": [ { "$ref": "#/components/schemas/ResultsLocation" } ], "description": "The training results. Normally this is specified as `type=container` (Service) or `type=fs` (Software) which\nmeans that it is stored in the space or project.\n", "example": { "location": { "path": "results" }, "type": "container" } } }, "required": [ "results_reference" ] }, "TrainingResourcePrototype": { "description": "The `training_data_references` contain the training datasets and the\n`results_reference` the connection where results will be stored.\n", "allOf": [ { "$ref": "#/components/schemas/TrainingResourceDetails" }, { "$ref": "#/components/schemas/TrainingResourceEntityCommon" }, { "$ref": "#/components/schemas/ResultsReferenceInput" } ], "example": { "name": "my-prompt-tune-training", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "prompt_tuning": { "base_model": { "model_id": "google/flan-t5-xl" }, "tuning_type": "prompt_tuning", "num_epochs": 30, "learning_rate": 0.4, "accumulate_steps": 3, "batch_size": 10, "max_input_tokens": 100, "max_output_tokens": 100, "task_id": "classification" }, "training_data_references": [ { "id": "tune1_data.json", "location": { "path": "tune1_data.json" }, "type": "container" } ], "auto_update_model": true, "results_reference": { "location": { "path": "tune1/results" }, "type": "container" } } }, "EmbeddingModelId": { "type": "string", "description": "The `id` of the model to be used for this request.\nPlease refer to the [list of models](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models-embed.html?context=wx&audience=wdp).\n" }, "TextInput": { "type": "string", "description": "The text input to the model.\n" }, "ParameterTruncateInputTokensFromEnd": { "type": "integer", "description": "Represents the maximum number of tokens accepted per input.\n\nThis can be used to avoid requests failing due to input being longer than configured limits. If the text is truncated, then it truncates the end of the input (on the right), so the start of the input will remain the same.\n\nIf this value exceeds the `maximum sequence length` (refer to the documentation to find this value for the model) then the call will fail if the total number of tokens exceeds the `maximum sequence length`.\n", "minimum": 1 }, "EmbeddingReturnOptions": { "type": "object", "description": "The return options for text embeddings.\n", "properties": { "input_text": { "type": "boolean", "description": "Include the `input` text in each of the `results` documents.\n" } } }, "EmbeddingParameters": { "type": "object", "description": "Parameters for text embedding requests.\n", "properties": { "truncate_input_tokens": { "$ref": "#/components/schemas/ParameterTruncateInputTokensFromEnd" }, "return_options": { "$ref": "#/components/schemas/EmbeddingReturnOptions" } } }, "EmbeddingsRequest": { "type": "object", "description": "The text input for a given model to be used to generate the embeddings.\n", "properties": { "space_id": { "$ref": "#/components/schemas/SpaceId" }, "project_id": { "$ref": "#/components/schemas/ProjectId" }, "model_id": { "$ref": "#/components/schemas/EmbeddingModelId" }, "inputs": { "type": "array", "description": "The input text.\n", "items": { "$ref": "#/components/schemas/TextInput" }, "maxItems": 1000, "nullable": false }, "parameters": { "$ref": "#/components/schemas/EmbeddingParameters" }, "crypto": { "$ref": "#/components/schemas/CryptoInfo" } }, "required": [ "model_id", "inputs" ] }, "EmbeddingInputResult": { "type": "object", "description": "The input text, this is only output if `parameters.return_options.input_text`\nis set to `true` in the request.\n", "properties": { "text": { "type": "string", "description": "The input text.\n" } }, "required": [ "text" ] }, "Embedding": { "type": "object", "description": "The embedding values for a text string. The `input` field is only set if the corresponding `return_option` is set.\n", "properties": { "input": { "$ref": "#/components/schemas/EmbeddingInputResult" }, "embedding": { "type": "array", "description": "The embedding values.\n", "items": { "type": "number", "description": "An embedding value.\n" }, "minItems": 0 } }, "required": [ "embedding" ] }, "InputTokenCount": { "type": "integer", "description": "The number of input tokens that were consumed.\n" }, "EmbeddingsResponseFields": { "type": "object", "description": "The embeddings per input.\n", "properties": { "model_id": { "$ref": "#/components/schemas/EmbeddingModelId" }, "results": { "type": "array", "description": "The embedding values for a given text.\n", "items": { "$ref": "#/components/schemas/Embedding" }, "minItems": 0 }, "created_at": { "$ref": "#/components/schemas/CreatedAt" }, "input_token_count": { "$ref": "#/components/schemas/InputTokenCount" } }, "required": [ "model_id", "results", "created_at", "input_token_count" ] }, "EmbeddingsResponse": { "allOf": [ { "$ref": "#/components/schemas/EmbeddingsResponseFields" }, { "$ref": "#/components/schemas/System" } ] }, "SimilarityReturnOptions": { "type": "object", "description": "The return options for text similarity.\n" }, "SimilarityParameters": { "type": "object", "description": "Parameters for text similarity.\n", "properties": { "truncate_input_tokens": { "$ref": "#/components/schemas/ParameterTruncateInputTokensFromEnd" }, "return_options": { "$ref": "#/components/schemas/SimilarityReturnOptions" } } }, "SimilarityRequest": { "type": "object", "description": "The source and target text that will be checked for similarity.\n", "properties": { "space_id": { "$ref": "#/components/schemas/SpaceId" }, "project_id": { "$ref": "#/components/schemas/ProjectId" }, "model_id": { "$ref": "#/components/schemas/EmbeddingModelId" }, "source_text": { "type": "string", "description": "A source text.\n" }, "target_texts": { "type": "array", "description": "The target texts.\n", "items": { "type": "string", "description": "A target text.\n" } }, "parameters": { "$ref": "#/components/schemas/SimilarityParameters" } }, "required": [ "model_id", "source_text", "target_texts" ] }, "SimilarityResult": { "type": "object", "description": "The similarity results.\n", "properties": { "score": { "type": "number", "description": "A similarity score between the source and target text.\n" } }, "required": [ "score" ] }, "SimilarityResponseFields": { "type": "object", "description": "The similarity scores per source string.\n", "properties": { "model_id": { "$ref": "#/components/schemas/EmbeddingModelId" }, "results": { "type": "array", "description": "The similarity scores.\n", "items": { "$ref": "#/components/schemas/SimilarityResult" }, "minItems": 0 }, "created_at": { "$ref": "#/components/schemas/CreatedAt" }, "input_token_count": { "$ref": "#/components/schemas/InputTokenCount" } }, "required": [ "model_id", "results", "created_at", "input_token_count" ] }, "SimilarityResponse": { "allOf": [ { "$ref": "#/components/schemas/SimilarityResponseFields" }, { "$ref": "#/components/schemas/System" } ] }, "RerankInput": { "type": "object", "description": "The input text.\n", "properties": { "text": { "type": "string", "description": "The input text.\n" } }, "required": [ "text" ] }, "RerankQuery": { "type": "string", "description": "The rank query.\n" }, "RerankReturnOptions": { "type": "object", "description": "The return options for text reranking.\n", "properties": { "top_n": { "type": "integer", "description": "Just show the top `n` results if set.\n", "minimum": 1 }, "inputs": { "type": "boolean", "description": "If `true` then the inputs will be returned in the response.\n", "default": false }, "query": { "type": "boolean", "description": "If `true` then the queries will be returned in the response.\n", "default": false } } }, "RerankParameters": { "type": "object", "description": "The properties used for reranking.\n", "properties": { "truncate_input_tokens": { "$ref": "#/components/schemas/ParameterTruncateInputTokensFromEnd" }, "return_options": { "$ref": "#/components/schemas/RerankReturnOptions" } } }, "RerankRequest": { "type": "object", "description": "The request to rerank texts.\n", "properties": { "space_id": { "$ref": "#/components/schemas/SpaceId" }, "project_id": { "$ref": "#/components/schemas/ProjectId" }, "model_id": { "$ref": "#/components/schemas/EmbeddingModelId" }, "inputs": { "type": "array", "description": "The rank input strings.\n", "items": { "$ref": "#/components/schemas/RerankInput" }, "minItems": 0, "maxItems": 1000 }, "query": { "$ref": "#/components/schemas/RerankQuery" }, "parameters": { "$ref": "#/components/schemas/RerankParameters" }, "crypto": { "$ref": "#/components/schemas/CryptoInfo" } }, "required": [ "model_id", "inputs", "query" ] }, "RerankInputResult": { "type": "object", "description": "The input text, this is only output if `parameters.return_options.inputs`\nis set to `true` in the request.\n", "properties": { "text": { "type": "string", "description": "The input text.\n" } }, "required": [ "text" ] }, "RerankedResults": { "type": "object", "description": "The ranking score for the input.\n", "properties": { "index": { "type": "integer", "description": "The index of the text from the input in the original request `inputs` array.\n", "minimum": 0 }, "score": { "type": "number", "description": "The score of the input.\n" }, "input": { "$ref": "#/components/schemas/RerankInputResult" } }, "required": [ "index", "score" ] }, "RerankResponseFields": { "type": "object", "description": "The ranked results.\n", "properties": { "model_id": { "$ref": "#/components/schemas/EmbeddingModelId" }, "model_version": { "$ref": "#/components/schemas/ModelVersion" }, "results": { "description": "The ranked results.\n", "type": "array", "items": { "$ref": "#/components/schemas/RerankedResults" }, "minItems": 0 }, "created_at": { "$ref": "#/components/schemas/CreatedAt" }, "input_token_count": { "$ref": "#/components/schemas/InputTokenCount" }, "query": { "type": "string", "description": "The rank query, if requested.\n" } }, "required": [ "model_id", "results", "created_at", "input_token_count" ] }, "RerankResponse": { "allOf": [ { "$ref": "#/components/schemas/RerankResponseFields" }, { "$ref": "#/components/schemas/System" } ] }, "SpaceIdOnly": { "type": "string", "pattern": "^[a-zA-Z0-9-]*$", "minLength": 36, "maxLength": 36, "description": "The space that contains the resource.\n", "example": "3fc54cf1-252f-424b-b52d-5cdd9814987f" }, "GeospatialTransformationMetadataFields": { "type": "object", "description": "The specific fields for the geospatial transformation metadata fields.\n", "properties": { "space_id": { "$ref": "#/components/schemas/SpaceIdOnly" } }, "required": [ "space_id" ] }, "GeospatialTransformationMetadata": { "allOf": [ { "$ref": "#/components/schemas/ResourceMetaSimple" }, { "$ref": "#/components/schemas/GeospatialTransformationMetadataFields" } ] }, "GeospatialTransformationModelId": { "type": "string", "description": "The `id` of the model to be used for this request.\n" }, "GeospatialTransformationData": { "type": "object", "description": "A data location of the input or output data.\n", "properties": { "url": { "type": "string", "description": "A signed url for the data in COS or elsewhere. This url will be used to download if this is input, or upload if this is output.\n", "example": "https://pre_signed_url" } } }, "GeospatialTransformationEntity": { "type": "object", "description": "The inputs and outputs required to create a transformation for the given model.\n", "properties": { "model_id": { "$ref": "#/components/schemas/GeospatialTransformationModelId" }, "inputs": { "type": "array", "description": "The input text.\n", "items": { "$ref": "#/components/schemas/GeospatialTransformationData" }, "maxItems": 20, "nullable": false }, "output": { "$ref": "#/components/schemas/GeospatialTransformationData" } }, "required": [ "model_id", "inputs", "output" ] }, "GeospatialTransformationResults": { "type": "object", "description": "The transformation results.\n", "properties": { "status": { "type": "string", "description": "The status of the transformation.\n", "enum": [ "completed", "failed", "running" ] }, "running_at": { "type": "string", "format": "date-time", "description": "The time when the job is successfully submitted to the processor.\n" }, "completed_at": { "type": "string", "format": "date-time", "description": "The time when the job completed or failed.\n" } } }, "GeospatialTransformationResource": { "type": "object", "description": "The geospatial transformation resource.\n", "properties": { "metadata": { "$ref": "#/components/schemas/GeospatialTransformationMetadata" }, "entity": { "allOf": [ { "$ref": "#/components/schemas/GeospatialTransformationEntity" }, { "type": "object", "properties": { "results": { "$ref": "#/components/schemas/GeospatialTransformationResults" } } } ] } } }, "GeospatialTransformationResources": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "description": "Pagination information and list of resources.\n", "properties": { "resources": { "type": "array", "description": "A list of resources.\n", "items": { "$ref": "#/components/schemas/GeospatialTransformationResource" } } } }, { "$ref": "#/components/schemas/System" } ], "description": "A paginated list of resources.\n" }, "GeospatialTransformationRequestFields": { "type": "object", "properties": { "space_id": { "$ref": "#/components/schemas/SpaceIdOnly" } }, "required": [ "space_id" ] }, "GeospatialTransformationRequest": { "allOf": [ { "$ref": "#/components/schemas/GeospatialTransformationEntity" }, { "$ref": "#/components/schemas/GeospatialTransformationRequestFields" } ] }, "GeospatialTransformationResponseFields": { "type": "object", "description": "The transformation results.\n", "properties": { "results": { "$ref": "#/components/schemas/GeospatialTransformationResults" } }, "required": [ "results" ] }, "GeospatialTransformationResponseEntity": { "allOf": [ { "$ref": "#/components/schemas/GeospatialTransformationEntity" }, { "$ref": "#/components/schemas/GeospatialTransformationResponseFields" } ] }, "GeospatialTransformationResponse": { "type": "object", "description": "The response from a geospatial transformation request.\n", "properties": { "metadata": { "$ref": "#/components/schemas/GeospatialTransformationMetadata" }, "entity": { "$ref": "#/components/schemas/GeospatialTransformationResponseEntity" } }, "required": [ "metadata", "entity" ] }, "ResourceName": { "type": "string", "description": "The name of the job.\n" }, "ResourceDescription": { "type": "string", "description": "The description of the job.\n" }, "ResourceRequestFields": { "type": "object", "description": "The request fields that are not part of the returned entity.\n", "properties": { "name": { "$ref": "#/components/schemas/ResourceName" }, "description": { "$ref": "#/components/schemas/ResourceDescription" }, "tags": { "$ref": "#/components/schemas/Tags" }, "project_id": { "$ref": "#/components/schemas/ProjectId" }, "space_id": { "$ref": "#/components/schemas/SpaceId" } }, "required": [ "name" ] }, "AutoAIRAGMetadata": { "allOf": [ { "$ref": "#/components/schemas/ResourceMetaSimple" }, { "$ref": "#/components/schemas/ResourceRequestFields" } ] }, "AutoAIRAGChunking": { "type": "object", "title": "ChunkingConfiguration", "description": "The chunking details for an AutoAI RAG pattern,\n", "properties": { "method": { "type": "string", "description": "Text splitting method.\n", "enum": [ "recursive", "semantic" ], "example": "recursive", "default": "recursive" }, "chunk_size": { "type": "integer", "description": "The size (tokens) of the piece of text.\n", "minimum": 128, "maximum": 2048, "example": 256 }, "chunk_overlap": { "type": "integer", "description": "Number of overlapping (across chunks) tokens. Must be less than `chunk_size`.\n", "minimum": 64, "maximum": 512, "example": 128 } }, "required": [ "method", "chunk_size" ] }, "AutoAIRAGSparse": { "type": "object", "description": "The sparse embedding model required by hybrid search.\n", "properties": { "model_id": { "type": "string", "description": "The model id of the sparse embedding model. In-database sparse models are only supported. Defaults to `BM25` (Milvus) and `ELSER` for Elasticsearch. If `ELSER` is not available `BM25` is used.\n", "example": "BM25" } } }, "AutoAIRAGHybridRanker": { "type": "object", "description": "The ranker settings for hybrid search. If not provided the hybrid-search is disabled.\n", "properties": { "strategy": { "type": "string", "description": "The ranker strategy used in hybrid search.\n", "enum": [ "weighted", "rrf" ], "example": "rrf" }, "sparse_vectors": { "$ref": "#/components/schemas/AutoAIRAGSparse" }, "alpha": { "type": "number", "format": "float", "description": "Importance of dense embeddings used by Weighted Ranker (the higher the more important). Sparse embeddings importance is 1-alpha.\n", "minimum": 0, "maximum": 1, "example": 0.9, "default": 0.8 }, "k": { "type": "integer", "description": "The rank constant ensuring a good balance between the influence of top and low ranked documents (the higher k, the higher importance of the low ranked ones). Applies to RRF only.\n", "minimum": 1, "default": 60, "example": 70 } }, "required": [ "strategy" ] }, "AutoAIRAGRetrieval": { "type": "object", "description": "The retrieval details for RAG pattern.\n", "properties": { "method": { "type": "string", "description": "Chunks retrieval method.\n", "enum": [ "simple", "window" ], "example": "simple" }, "number_of_chunks": { "type": "integer", "description": "The number of retrieved chunks.\n", "minimum": 1, "maximum": 10, "example": 5 }, "window_size": { "type": "integer", "description": "The size of the window. Applies only to window based methods.\n", "minimum": 1, "maximum": 4, "example": 2 }, "hybrid_ranker": { "$ref": "#/components/schemas/AutoAIRAGHybridRanker" } }, "required": [ "method" ] }, "AutoAIRAGModelParams": { "type": "object", "description": "The parameters specific to chat.\n", "properties": { "max_completion_tokens": { "type": "integer", "description": "Applies to chat only. The maximum number of tokens that can be generated in the chat completion.\nThe total length of input tokens and generated tokens is limited by the model's context length.\nSet to 0 for the model's configured max generated tokens.\n", "nullable": true, "default": 1024 }, "temperature": { "type": "number", "description": "Applies to chat only.\nWhat sampling temperature to use,. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.\n", "minimum": 0, "maximum": 2, "default": 1, "nullable": true }, "decoding_method": { "deprecated": true, "type": "string", "description": "Represents the strategy used for picking the tokens during generation of the output text.\n\nDuring text generation when parameter value is set to greedy, each successive token corresponds\nto the highest probability token given the text that has already been generated.\nThis strategy can lead to repetitive results especially for longer output sequences.\nThe alternative sample strategy generates text by picking subsequent tokens based on the\nprobability distribution of possible next tokens defined by (i.e., conditioned on) the\nalready-generated text and the top_k and top_p parameters described below.\nSee this [url](https://huggingface.co/blog/how-to-generate) for an informative article about text generation.\n", "enum": [ "sample", "greedy" ], "default": "greedy", "example": "sample" }, "max_new_tokens": { "deprecated": true, "type": "integer", "description": "The maximum number of new tokens to be generated.\nThe maximum supported value for this field depends on the model being used.\n\nHow the \"token\" is defined depends on the tokenizer and vocabulary size,\nwhich in turn depends on the model. Often the tokens are a mix of full words and sub-words.\nTo learn more about tokenization, [see here](https://huggingface.co/course/chapter2/4).\n\nDepending on the users plan, and on the model being used, there may be an enforced maximum number of new tokens.\n", "minimum": 1, "default": 1000, "example": 300 }, "min_new_tokens": { "deprecated": true, "type": "integer", "description": "If stop sequences are given, they are ignored until minimum tokens are generated.\n", "minimum": 0, "default": 1, "example": 5 }, "max_sequence_length": { "deprecated": true, "type": "integer", "description": "This is the maximum allowed value for the number of tokens in the input\nprompt plus the number of tokens in the output generated by the model.\n", "example": 4096 } } }, "AutoAIRAGModel": { "type": "object", "title": "FoundationModel", "description": "Properties describing the foundation model.\n", "properties": { "model_id": { "type": "string", "description": "The foundation model id.\n", "example": "meta-llama/llama-3-3-70b-instruct" }, "parameters": { "$ref": "#/components/schemas/AutoAIRAGModelParams" }, "chat_template_messages": { "type": "object", "description": "The chat messages templates. Applies only to chat models. Either `chat_template_messages` or `prompt_template_text` has to be given. If not provided default ones are used.\n", "properties": { "system_message_text": { "type": "string", "description": "The chat system message text. If not provided default one is used.\n", "example": "You are a helpful, respectful and honest assistant. Always answer as helpfully as possible, while being safe. Your answers should not include any harmful, unethical, racist, sexist, toxic, dangerous, or illegal content. Please ensure that your responses are socially unbiased and positive in nature.\n\nIf a question does not make any sense, or is not factually coherent, explain why instead of answering something not correct. If you don't know the answer to a question, please don't share false information." }, "user_message_text": { "type": "string", "description": "The chat user message template text. Must contain variables: `{question}` and `{reference_documents}`. `{reference_documents}` variable is a placeholder for retrieved document(s) defined by `context_template_text`. If not provided default one is used.\n", "example": "Generate the next agent response by answering the question. You are provided several documents with titles. If the answer comes from different documents please mention all possibilities and use the titles of documents to separate between topics or domains. If you cannot base your answer on the given documents, please state that you do not have an answer.\n\n{reference_documents}\n\n{question}" } }, "required": [ "system_message_text", "user_message_text" ] }, "prompt_template_text": { "deprecated": true, "type": "string", "description": "The foundation model prompt template text (free form).\nUse `chat_template_messages` instead.\n", "example": "[INST] <>\nYou are a helpful, respectful and honest assistant. Always answer as helpfully as possible, while being safe. Your answers should not include any harmful, unethical, racist, sexist, toxic, dangerous, or illegal content. Please ensure that your responses are socially unbiased and positive in nature.\n\nIf a question does not make any sense, or is not factually coherent, explain why instead of answering something not correct. If you don't know the answer to a question, please don't share false information.\n\n<>\n\nGenerate the next agent response by answering the question. You are provided several documents with titles. If the answer comes from different documents please mention all possibilities and use the titles of documents to separate between topics or domains. If you cannot base your answer on the given documents, please state that you do not have an answer.\n\n{reference_documents}\n\n{question} [/INST]" }, "context_template_text": { "type": "string", "description": "The retrieved chunks template text (free form). Must contain variable: `document` representing single document chunk retrieved. > If not provided default one is used.\n", "example": "[Document]\n{document}\n[End]" }, "word_to_token_ratio": { "type": "number", "description": "Describes word to token ratio.\n", "example": 1.5 } }, "required": [ "model_id" ] }, "AutoAIRAGCustomModel": { "type": "object", "title": "CustomFoundationModel", "description": "Properties describing the custom foundation model.\n", "properties": { "deployment_id": { "type": "string", "description": "The custom foundation model deployment id.\n", "example": "2cd0bcda-581d-4f04-8028-ec2bc90cc375" }, "space_id": { "$ref": "#/components/schemas/SpaceId" }, "project_id": { "$ref": "#/components/schemas/ProjectId" }, "parameters": { "$ref": "#/components/schemas/AutoAIRAGModelParams" }, "chat_template_messages": { "type": "object", "description": "The chat messages templates. Applies only to chat models. Either `chat_template_messages` or `prompt_template_text` has to be given. If not provided default ones are used.\n", "properties": { "system_message_text": { "type": "string", "description": "The chat system message text. If not provided default one is used.\n", "example": "You are a helpful, respectful and honest assistant. Always answer as helpfully as possible, while being safe. Your answers should not include any harmful, unethical, racist, sexist, toxic, dangerous, or illegal content. Please ensure that your responses are socially unbiased and positive in nature.\n\nIf a question does not make any sense, or is not factually coherent, explain why instead of answering something not correct. If you don't know the answer to a question, please don't share false information." }, "user_message_text": { "type": "string", "description": "The chat user message template text. Must contain variables: `{question}` and `{reference_documents}`. `{reference_documents}` variable is a placeholder for retrieved document(s) defined by `context_template_text`. If not provided default one is used.\n", "example": "Generate the next agent response by answering the question. You are provided several documents with titles. If the answer comes from different documents please mention all possibilities and use the titles of documents to separate between topics or domains. If you cannot base your answer on the given documents, please state that you do not have an answer.\n\n{reference_documents}\n\n{question}" } }, "required": [ "system_message_text", "user_message_text" ] }, "prompt_template_text": { "deprecated": true, "type": "string", "description": "The (non-chat) foundation model prompt template text (free form). Must contain variables: `{question}` and `{reference_documents}`. `{reference_documents}` variable is a placeholder for retrieved document(s) defined by `context_template_text`.\nFor chat models use `chat_template_messages`.\n", "example": "[INST] <>\nYou are a helpful, respectful and honest assistant. Always answer as helpfully as possible, while being safe. Your answers should not include any harmful, unethical, racist, sexist, toxic, dangerous, or illegal content. Please ensure that your responses are socially unbiased and positive in nature.\n\nIf a question does not make any sense, or is not factually coherent, explain why instead of answering something not correct. If you don't know the answer to a question, please don't share false information.\n\n<>\n\nGenerate the next agent response by answering the question. You are provided several documents with titles. If the answer comes from different documents please mention all possibilities and use the titles of documents to separate between topics or domains. If you cannot base your answer on the given documents, please state that you do not have an answer.\n\n{reference_documents}\n\n{question} [/INST]" }, "context_template_text": { "type": "string", "description": "The retrieved chunks template text (free form). Must contain variable: `document` representing single document chunk retrieved. > If not provided default one is used.\n", "example": "[Document]\n{document}\n[End]" }, "word_to_token_ratio": { "type": "number", "description": "Describes word to token ratio.\n", "example": 1.5 } }, "required": [ "deployment_id" ] }, "AutoAIRAGGenerationModel": { "oneOf": [ { "$ref": "#/components/schemas/AutoAIRAGModel" }, { "$ref": "#/components/schemas/AutoAIRAGCustomModel" } ] }, "AutoAIRAGConstraints": { "type": "object", "description": "The constraint parameters for an AutoAI RAG run.\n", "properties": { "chunking": { "type": "array", "description": "Chunking settings to be used.\n", "items": { "$ref": "#/components/schemas/AutoAIRAGChunking" }, "minItems": 1, "maxItems": 4, "example": [ { "method": "recursive", "chunk_size": 512, "chunk_overlap": 128 }, { "method": "recursive", "chunk_size": 1024, "chunk_overlap": 512 } ] }, "embedding_models": { "type": "array", "description": "The embedding models to try in index building step. Models with \"autoai_rag\" function are supported (use Model Specs API, to retrieve list of supported models). If not provided AutoAI selects top 2 performers.\n", "items": { "type": "string", "description": "The model id of the embedding model.\n" }, "minItems": 1, "example": [ "ibm/slate-125m-english-rtrvr", "intfloat/multilingual-e5-large" ] }, "retrieval": { "type": "array", "description": "Retrieval settings to be used.\n", "items": { "$ref": "#/components/schemas/AutoAIRAGRetrieval" }, "minItems": 1, "maxItems": 4, "example": [ { "method": "simple", "number_of_chunks": 5 }, { "method": "window", "number_of_chunks": 3, "window_size": 2 } ] }, "generation": { "type": "object", "description": "Properties describing the generation step.", "properties": { "language": { "type": "object", "description": "Properties describing the generation language.", "properties": { "auto_detect": { "description": "Detect the language based on provided data.", "type": "boolean", "default": true } } }, "foundation_models": { "type": "array", "title": "GenerationModels", "description": "List of foundation models and custom foundation models.", "items": { "$ref": "#/components/schemas/AutoAIRAGGenerationModel" } } }, "example": { "language": { "auto_detect": false }, "foundation_models": [ { "model_id": "meta-llama/llama-3-1-70b-instruct" } ] } }, "max_number_of_rag_patterns": { "type": "integer", "description": "The maximum number of RAG patterns to create.\n", "minimum": 1, "maximum": 20, "default": 8 } } }, "AutoAIRAGOptimizationParameters": { "type": "object", "title": "OptimizationParameters", "description": "The optimization parameters for an AutoAI RAG run.\n", "properties": { "metrics": { "type": "array", "description": "The metric name(s) to be used for optimization. LLM as a judge metrics are supported on Service only.\n", "items": { "type": "string", "description": "The metric name to be used for optimization.\n", "enum": [ "answer_correctness", "faithfulness", "context_correctness", "answer_correctness_judge", "faithfulness_judge" ] }, "minItems": 1, "maxItems": 1, "default": [ "faithfulness" ], "example": [ "answer_correctness" ] } } }, "AutoAIRAGServiceDeployment": { "type": "object", "description": "The configuration parameters for RAG Pattern service deployment.\n", "properties": { "auto_deploy": { "type": "boolean", "description": "Automatically deploy service for the best RAG Pattern found.", "default": false, "example": true }, "space_id": { "$ref": "#/components/schemas/SpaceId" } }, "required": [ "space_id" ] }, "AutoAIRAGParameters": { "type": "object", "description": "The parameters for an AutoAI RAG run.\n", "properties": { "constraints": { "$ref": "#/components/schemas/AutoAIRAGConstraints" }, "optimization": { "$ref": "#/components/schemas/AutoAIRAGOptimizationParameters" }, "deployment": { "description": "Best pattern deployment related properties.", "properties": { "inference_service": { "$ref": "#/components/schemas/AutoAIRAGServiceDeployment" }, "indexing_service": { "$ref": "#/components/schemas/AutoAIRAGServiceDeployment" } } }, "output_logs": { "type": "boolean", "description": "Request that the output logs are also stored as part of the result.\n", "default": true } } }, "AutoAIDataLocation": { "type": "object", "description": "A reference to data.\n", "properties": { "type": { "description": "The data source type like `connection_asset`, `data_asset` or `container` (Service only).\n", "type": "string", "enum": [ "connection_asset", "data_asset", "container" ], "example": "connection_asset" }, "connection": { "$ref": "#/components/schemas/DataConnection" }, "location": { "$ref": "#/components/schemas/DataLocation" } }, "required": [ "type", "location" ] }, "ConnectionAsset": { "type": "object", "description": "A reference to connection.\n", "properties": { "type": { "description": "The data source type `connection_asset`.\n", "type": "string", "enum": [ "connection_asset" ], "example": "connection_asset" }, "connection": { "$ref": "#/components/schemas/DataConnection" } }, "required": [ "type", "connection" ] }, "AutoAIRAGField": { "type": "object", "description": "Role to field name mapping.\n", "properties": { "role": { "type": "string", "description": "Supported roles:\n * `document_name` - document filename (including the ext) from where the text chunk was extracted\n * `text` - text chunk extracted from document\n * `chunk_sequence_number` - sequential chunk number, representing its position within a larger document\n * `dense_vector_embeddings` - dense embeddings vector\n * `sparse_vector_embeddings` - sparse embeddings vector\n", "example": "dense_vector_embeddings", "enum": [ "document_name", "text", "chunk_sequence_number", "dense_vector_embeddings", "sparse_vector_embeddings" ] }, "field_name": { "type": "string", "description": "The field's name.\n", "example": "vector_embeddings" } }, "required": [ "role", "field_name" ] }, "AutoAIRAGIndex": { "type": "object", "description": "A reference to vector store knowledge.\n", "properties": { "name": { "type": "string", "description": "The name of the knowledge base.\n", "example": "2025_financial_documentation" }, "description": { "type": "string", "description": "The description of the knowledge base.\n", "example": "This knowledge base contains ABC financial documents for 2025 year." }, "type": { "type": "string", "description": "Vector Store knowledge base. One of `vector_store` or `database` is supported.", "enum": [ "vector_store" ] }, "reference": { "$ref": "#/components/schemas/ConnectionAsset" }, "settings": { "type": "object", "description": "Properties that describe the vector store index/collection.\n", "properties": { "index_name": { "type": "string", "description": "The database index name.\n", "example": "autoai_rag_id_pipeline_id_index" }, "fields_mapping": { "type": "array", "description": "Field name to role mapping. The mappings for roles: `text`, `dense_vector_embeddings` and `document_name` are required.\n", "items": { "$ref": "#/components/schemas/AutoAIRAGField" } }, "embeddings": { "type": "object", "description": "The embeddings properties.\n", "properties": { "model_id": { "type": "string", "description": "The dense embedding model id.\n", "example": "ibm/slate-125m-english-rtrvr" } } }, "hybrid_ranker": { "type": "object", "description": "The ranker settings for hybrid search. If not provided the hybrid-search is disabled.\n", "properties": { "sparse_vectors": { "$ref": "#/components/schemas/AutoAIRAGSparse" } } } }, "required": [ "index_name", "fields_mapping", "embeddings" ] } }, "required": [ "name", "description", "reference", "settings", "type" ] }, "AutoAIRAGDatabase": { "type": "object", "description": "A reference to SQL db knowledge.\n", "properties": { "name": { "type": "string", "description": "The name of the knowledge base.\n", "example": "2025_financial_documentation" }, "description": { "type": "string", "description": "The description of the knowledge base.\n", "example": "This knowledge base contains ABC financial numbers for 2025 year." }, "type": { "type": "string", "description": "Relational Database knowledge base. One of `vector_store` or `database` is supported.", "enum": [ "database" ] }, "settings": { "type": "object", "description": "Properties that describe the database collection.\n", "properties": { "dialect": { "type": "string", "description": "The SQL dialect (variation of the SQL language). If not provided default per database is used.\n", "example": "mysql" } } }, "reference": { "type": "object", "description": "A reference to data.\n", "properties": { "type": { "description": "The data source type `connection_asset`.\n", "type": "string", "enum": [ "connection_asset" ], "example": "connection_asset" }, "connection": { "$ref": "#/components/schemas/DataConnection" }, "location": { "$ref": "#/components/schemas/DataLocation" } }, "required": [ "connection", "location", "type" ] } }, "required": [ "name", "reference", "description", "type" ] }, "AutoAIRAGKnowledgeBase": { "oneOf": [ { "$ref": "#/components/schemas/AutoAIRAGIndex" }, { "$ref": "#/components/schemas/AutoAIRAGDatabase" } ], "discriminator": { "propertyName": "type" } }, "AutoAIRAGRequestEntity": { "type": "object", "description": "The request entity for an AutoAI RAG run.\n", "properties": { "hardware_spec": { "$ref": "#/components/schemas/HardwareSpec" }, "parameters": { "$ref": "#/components/schemas/AutoAIRAGParameters" }, "input_data_references": { "type": "array", "description": "A set of input data references.\n", "items": { "$ref": "#/components/schemas/AutoAIDataLocation" }, "minItems": 1, "maxItems": 20 }, "test_data_references": { "type": "array", "description": "A set of test data references.\n", "items": { "$ref": "#/components/schemas/AutoAIDataLocation" }, "minItems": 1, "maxItems": 1 }, "knowledge_base_references": { "type": "array", "description": "A set of existing knowledge base references. Applicable to multi-retrieval scenarios.\nEither `input_data_references` or `knowledge_base_references` must be provided.\n", "items": { "$ref": "#/components/schemas/AutoAIRAGKnowledgeBase" }, "minItems": 1, "maxItems": 20 }, "vector_store_references": { "type": "array", "description": "A set of vector store references.\n", "items": { "$ref": "#/components/schemas/ConnectionAsset" }, "minItems": 1, "maxItems": 1 }, "custom": { "$ref": "#/components/schemas/Custom" } }, "required": [ "hardware_spec" ] }, "AutoAIRAGMetric": { "type": "object", "description": "The metric for a given property.\n", "properties": { "metric_name": { "type": "string", "description": "The name of the metric.\n", "example": "answer_correctness" }, "mean": { "type": "number", "description": "The mean value calculated over all records in the dataset.\n", "example": 0.5197 }, "ci_high": { "type": "number", "description": "High confidence interval calculated over all records in the dataset.\n", "example": 0.61 }, "ci_low": { "type": "number", "description": "Low confidence interval calculated over all records in the dataset.\n", "example": 0.42 } } }, "AutoAIRAGMetrics": { "type": "object", "description": "The AutoAI RAG metrics, this contains the list of calculated metrics on test data (provided in the request) and (optionally) synthetic data autogenerated. Metric value is mean value calculated over all records in the dataset.\n", "properties": { "test_data": { "type": "array", "description": "List of evaluation metrics.\n", "items": { "$ref": "#/components/schemas/AutoAIRAGMetric" } } }, "required": [ "test_data" ] }, "AutoAIRAGResultLocation": { "type": "object", "description": "The location of the different result files.\n", "properties": { "evaluation_results": { "type": "string", "description": "The json file with questions, answers, retrieved contexts, correct answers and metric scores.\n", "example": "results_autoai/6a9362f6-7ea2-4419-8c7d-a7e07432dec5/rag/assets/Pattern1/evaluation_results.json" }, "indexing_notebook": { "type": "string", "description": "A Jupyter notebook with code required to build the index in the vector database.\n", "example": "results_autoai/6a9362f6-7ea2-4419-8c7d-a7e07432dec5/rag/assets/Pattern1/indexing_notebook.ipynb" }, "inference_notebook": { "type": "string", "description": "The Jupyter notebook with the python function code and steps required to store and deploy the Q&A chain.\n", "example": "results_autoai/6a9362f6-7ea2-4419-8c7d-a7e07432dec5/rag/assets/Pattern1/inference_notebook.ipynb" }, "inference_service_code": { "type": "string", "description": "The retrieve & generation AI service code (python).\n", "example": "results_autoai/6a9362f6-7ea2-4419-8c7d-a7e07432dec5/rag/assets/Pattern1/inference_service_code.gz" }, "inference_service_metadata": { "type": "string", "description": "The retrieve & generation AI service metadata.\n", "example": "results_autoai/6a9362f6-7ea2-4419-8c7d-a7e07432dec5/rag/assets/Pattern1/inference_service_metadata.json" }, "indexing_service_code": { "type": "string", "description": "The indexing AI service code (python).\n", "example": "results_autoai/6a9362f6-7ea2-4419-8c7d-a7e07432dec5/rag/assets/Pattern1/indexing_service_code.gz" }, "indexing_service_metadata": { "type": "string", "description": "The indexing AI service metadata.\n", "example": "results_autoai/6a9362f6-7ea2-4419-8c7d-a7e07432dec5/rag/assets/Pattern1/indexing_service_metadata.json" } } }, "AutoAIRAGVectorStore": { "type": "object", "description": "Properties that describe the AutoAI RAG vector store that contains the results.\n", "properties": { "datasource_type": { "type": "string", "description": "The vector database type.\n", "example": "milvus" }, "index_name": { "type": "string", "description": "The database index name.\n", "example": "autoai_rag_id_pipeline_id_index" }, "distance_metric": { "type": "string", "description": "The distance metric name.\n", "enum": [ "euclidean", "cosine" ], "example": "euclidean" }, "operation": { "type": "string", "description": "The operation type (either insert or upsert).\n", "enum": [ "insert", "upsert" ], "example": "upsert" }, "schema": { "$ref": "#/components/schemas/DataSchema" } } }, "AutoAIRAGEmbeddings": { "type": "object", "description": "The embeddings properties for RAG pattern.\n", "properties": { "truncate_strategy": { "type": "string", "description": "Truncate strategy.\n", "example": "left" }, "truncate_input_tokens": { "type": "integer", "description": "Number of input tokens.\n", "example": 384 }, "model_id": { "type": "string", "description": "The embedding model id.\n", "example": "ibm/slate-125m-english-rtrvr" } }, "required": [ "model_id" ] }, "AutoAIRAGKnowledgeRetrieval": { "type": "object", "description": "The retrieval details for an AutoAI RAG pattern,\n", "properties": { "knowledge_base_name": { "type": "string", "description": "The name of the knowledge base the retrieval settings apply to.\n" }, "retrieval": { "$ref": "#/components/schemas/AutoAIRAGRetrieval" } }, "required": [ "knowledge_base_name", "retrieval" ] }, "AutoAIRAGTool": { "type": "object", "description": "The tool's details for the agentic AutoAI RAG pattern.\n", "properties": { "name": { "type": "string", "description": "The name of the tool.\n", "example": "Retriever_Pattern_8" }, "description": { "type": "string", "description": "The description of the tool.\n", "example": "Retrieve the content of financial documents for dept. A in company B for year 2024." } } }, "JSONContentSchema": { "type": "object", "description": "A JSON schema, see the [JSON Schema reference](https://json-schema.org/learn/getting-started-step-by-step)\nfor documentation about the format.\n", "additionalProperties": {} }, "JSONContentDefinition": { "type": "object", "description": "The schema for a given content type.\nEach property defines the content type and the sub-object\nis the JSON schema that describes the content.\n", "additionalProperties": { "$ref": "#/components/schemas/JSONContentSchema" } }, "AutoAIRAGAgent": { "type": "object", "description": "The agent settings details.\n", "properties": { "framework": { "type": "string", "description": "The agentic framework used to build the RAG Pattern.\n", "enum": [ "langgraph" ], "example": "langgraph" }, "type": { "type": "string", "description": "The agent's type.\n", "enum": [ "react" ], "example": "react" }, "description": { "type": "string", "description": "The description of the agent.\n", "example": "Answer the questions related to financial documents for dept. A for last 5 years." }, "graph": { "$ref": "#/components/schemas/JSONContentDefinition" } } }, "AutoAIRAGSettings": { "type": "object", "description": "The RAG pattern configuration settings that were found during the optimization process.\n", "properties": { "vector_store": { "$ref": "#/components/schemas/AutoAIRAGVectorStore" }, "chunking": { "$ref": "#/components/schemas/AutoAIRAGChunking" }, "embeddings": { "$ref": "#/components/schemas/AutoAIRAGEmbeddings" }, "retrieval": { "$ref": "#/components/schemas/AutoAIRAGRetrieval" }, "knowledge_base_retrievals": { "type": "array", "description": "A list of knowledge base retrievers' settings. Applicable only if `knowledge_base_references` is provided.\n", "items": { "$ref": "#/components/schemas/AutoAIRAGKnowledgeRetrieval" } }, "tools": { "type": "array", "description": "A list of agentic RAG Pattern tools.\n", "items": { "$ref": "#/components/schemas/AutoAIRAGTool" } }, "generation": { "$ref": "#/components/schemas/AutoAIRAGGenerationModel" }, "agent": { "$ref": "#/components/schemas/AutoAIRAGAgent" } } }, "AutoAIRAGParamImportance": { "type": "object", "title": "ParameterImportance", "description": "The RAG pattern configuration parameter importance.\n", "properties": { "parameter": { "type": "string", "description": "The configuration parameter name.\n", "example": "chunking_size" }, "importance": { "type": "number", "format": "float", "description": "The importance of particular configuration parameter.\n", "example": 0.6 } }, "example": { "parameter": "chunking_size", "importance": 0.6 } }, "AutoAIRAGSettingsImportance": { "type": "object", "title": "SettingsImportance", "description": "The RAG pattern configuration settings importance.\n", "properties": { "chunking": { "type": "array", "description": "The chunking config parameters importance.\n", "items": { "$ref": "#/components/schemas/AutoAIRAGParamImportance" } }, "embeddings": { "type": "array", "description": "The embeddings config parameters importance.\n", "items": { "$ref": "#/components/schemas/AutoAIRAGParamImportance" } }, "retrieval": { "type": "array", "description": "The retrieval config parameters importance.\n", "items": { "$ref": "#/components/schemas/AutoAIRAGParamImportance" } }, "generation": { "type": "array", "description": "The generation config parameters importance.\n", "items": { "$ref": "#/components/schemas/AutoAIRAGParamImportance" } }, "agent": { "type": "array", "description": "The agent config parameters importance.\n", "items": { "$ref": "#/components/schemas/AutoAIRAGParamImportance" } } } }, "AutoAIRAGPattern": { "type": "object", "description": "Describes the elements and settings found during the optimization of the RAG pattern.\n", "properties": { "composition_steps": { "type": "array", "description": "The list of RAG Pattern nodes (steps).\n", "items": { "type": "string", "description": "The step type.\n" }, "minItems": 0, "maxItems": 20, "nullable": false, "example": [ "chunking", "embeddings", "vector_store", "retrieval", "generation" ] }, "duration_seconds": { "type": "integer", "description": "The duration of the optimization step in seconds.\n", "example": 3600 }, "location": { "$ref": "#/components/schemas/AutoAIRAGResultLocation" }, "name": { "type": "string", "description": "The RAG Pattern name.\n", "example": "Pattern_1" }, "settings": { "$ref": "#/components/schemas/AutoAIRAGSettings" }, "settings_importance": { "$ref": "#/components/schemas/AutoAIRAGSettingsImportance" } } }, "SoftwareSpecRel": { "title": "software_spec_rel", "description": "A software specification.\n", "type": "object", "properties": { "id": { "description": "The id of the software specification.\n", "type": "string", "example": "4cedab6d-e8e4-4214-b81a-2ddb122db2ab" }, "rev": { "description": "The revision of the software specification.\n", "type": "string", "example": "2" }, "name": { "description": "The name of the software specification.\n", "type": "string" } } }, "AutoAIRAGContext": { "type": "object", "properties": { "rag_pattern": { "$ref": "#/components/schemas/AutoAIRAGPattern" }, "iteration": { "type": "integer", "description": "The iteration of the optimization run in which the particular pattern has been built.\n", "example": 1 }, "max_combinations": { "type": "integer", "description": "Maximum number of possible parameter settings (search space cardinality).\n", "example": 160 }, "software_spec": { "$ref": "#/components/schemas/SoftwareSpecRel" }, "deployment": { "type": "object", "description": "Deployed RAG Pattern details.", "properties": { "inference_service": { "type": "object", "description": "Retrieve and generation deployed service details.", "properties": { "deployment_id": { "type": "string", "format": "identifier", "pattern": "^[-0-9a-z]+$", "maxLength": 128, "description": "The inference service deployment `id` that would be used for retrieve & generation.\n", "example": "a12b278b-e40c-4ca4-bfa0-a4e8583b58e1" }, "space_id": { "$ref": "#/components/schemas/SpaceId" } } }, "indexing_service": { "type": "object", "description": "Index building service (batch) deployment details.", "properties": { "deployment_id": { "type": "string", "format": "identifier", "pattern": "^[-0-9a-z]+$", "maxLength": 128, "description": "The indexing service deployment `id` that would be used for index building.\n", "example": "d12b278b-e40c-4ca4-bfa0-a4e8583b58e1" }, "space_id": { "$ref": "#/components/schemas/SpaceId" } } } } } } }, "AutoAIRAGResults": { "type": "object", "description": "The AutoAI RAG results.\n", "properties": { "metrics": { "$ref": "#/components/schemas/AutoAIRAGMetrics" }, "context": { "$ref": "#/components/schemas/AutoAIRAGContext" } } }, "AutoAIRAGResponseResults": { "type": "object", "description": "The AutoAI RAG results.\n", "properties": { "results": { "type": "array", "description": "The list of results.\n", "items": { "$ref": "#/components/schemas/AutoAIRAGResults" }, "minItems": 1, "maxItems": 20, "nullable": false }, "timestamp": { "type": "string", "format": "date-time", "description": "The timestamp when the results were created.\n", "minLength": 24, "maxLength": 24, "example": "2024-02-28T11:33:58.000Z" } }, "required": [ "results", "timestamp" ] }, "AutoAIRAGStatusObject": { "type": "object", "description": "Status of the training job.\n", "properties": { "running_at": { "type": "string", "description": "Date and Time in which current training state has started.", "example": "2017-01-30T10:11:12Z", "format": "date-time" }, "completed_at": { "type": "string", "description": "Date and Time in which training had completed.", "example": "2017-01-30T10:11:12Z", "format": "date-time" }, "state": { "type": "string", "description": "Current state of training.", "enum": [ "queued", "pending", "running", "completed", "failed", "canceled" ] }, "message": { "$ref": "#/components/schemas/Message" }, "failure": { "$ref": "#/components/schemas/ApiErrorResponse" }, "step": { "type": "string", "description": "The step type.\n", "example": "data_reading" } }, "example": { "state": "completed", "running_at": "2023-08-04T13:22:48.000Z", "completed_at": "2023-08-04T13:22:55.289Z", "message": { "level": "info", "text": "Training job 360c40f7-ac0c-43ca-a95f-1a5421f93b82 completed" } }, "required": [ "state" ] }, "AutoAIRAGStatus": { "type": "object", "description": "The status of an AutoAI RAG run.\n", "properties": { "status": { "$ref": "#/components/schemas/AutoAIRAGStatusObject" } }, "required": [ "status" ] }, "AutoAIRAGResponseEntity": { "allOf": [ { "$ref": "#/components/schemas/AutoAIRAGRequestEntity" }, { "$ref": "#/components/schemas/AutoAIRAGResponseResults" }, { "$ref": "#/components/schemas/ResultsReferenceOutput" }, { "$ref": "#/components/schemas/AutoAIRAGStatus" } ] }, "AutoAIRAGResponse": { "type": "object", "description": "The response of an AutoAI RAG run.\n", "properties": { "metadata": { "$ref": "#/components/schemas/AutoAIRAGMetadata" }, "entity": { "$ref": "#/components/schemas/AutoAIRAGResponseEntity" }, "system": { "$ref": "#/components/schemas/SystemDetails" } } }, "AutoRAGResultResources": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "description": "Pagination information and list of runs definitions.\n", "properties": { "resources": { "type": "array", "description": "A list of training definitions.\n", "items": { "$ref": "#/components/schemas/AutoAIRAGResponse" } } } }, { "$ref": "#/components/schemas/System" } ], "description": "A paginated list of training definitions.\n" }, "AutoAIRAGRequest": { "allOf": [ { "$ref": "#/components/schemas/ResourceRequestFields" }, { "$ref": "#/components/schemas/AutoAIRAGRequestEntity" }, { "$ref": "#/components/schemas/ResultsReferenceInput" } ] }, "BaseModel": { "type": "object", "description": "The model id of the base model for this job.\n", "properties": { "model_id": { "type": "string", "description": "The model id of the base model.\n", "example": "google/flan-t5-xl" } } }, "GPU": { "type": "object", "description": "The name and number of GPUs used for the Fine Tuning job.\n", "properties": { "num": { "description": "The number of GPUs used for the Fine Tuning job.\n", "type": "number", "example": 4 }, "name": { "description": "The name of the GPU(s) used for the Fine Tuning job. The GPU specified must be available on the cluster.\n", "type": "string", "example": "NVIDIA-A100-80GB-PCIe" } } }, "FineTuningPeftParameters": { "type": "object", "description": "Parameters to be set when running a Fine Tuning job with LoRA/QLoRA.\n\nThese fields must not be set while creating a fine tuning job with InstructLab.\n", "properties": { "type": { "type": "string", "description": "The type specification for a LoRA or QLoRA Fine Tuning job.\nIf type is set to `none`, no other parameters in this object need to be specified.\n", "enum": [ "lora", "qlora", "none" ] }, "rank": { "type": "integer", "description": "The Lora attention dimension. The rank should be a power of two (eg. `8`, `16`, `32`, `64`, ...)\n", "default": 8, "example": 32 }, "target_modules": { "type": "array", "items": { "type": "string" }, "description": "The names of the modules to apply the adapter to. If this is specified, only the modules with the specified names will be replaced. Please specify modules as per model architecture.\nIf the value is [\"all-linear\"], then LORA selects all linear and Conv1D modules as per model architecture, except for the output layer.\n\nIf the value is [] (empty array), an attempt will be made to automatically set the target modules using defaults for the model architecture.\n", "default": [] }, "lora_alpha": { "type": "integer", "description": "The alpha parameter for Lora scaling.\n", "default": 32 }, "lora_dropout": { "type": "number", "description": "The dropout probability for Lora layers.\n", "default": 0.05 } } }, "FineTuningParameters": { "type": "object", "description": "This field must not be set while creating a fine tuning job with InstructLab.\n\nThe parameters for the job. Note that if `verbalizer` is provided\nthen `response_template` must also be provided (and vice versa).\n", "properties": { "task_id": { "type": "string", "description": "The task that is targeted for this model.\n" }, "accumulate_steps": { "type": "integer", "description": "Number of updates steps to accumulate the gradients for,\nbefore performing a backward/update pass.\n", "example": 1 }, "base_model": { "$ref": "#/components/schemas/BaseModel" }, "num_epochs": { "type": "integer", "description": "Total number of training epochs to perform.\n", "example": 5 }, "learning_rate": { "type": "number", "description": "The initial learning rate for AdamW optimizer.\n", "example": 0.2 }, "batch_size": { "type": "integer", "description": "The batch size per GPU/XPU/TPU/MPS/NPU core/CPU for training.\n", "example": 5 }, "max_seq_length": { "type": "integer", "description": "Maximum sequence length in terms of number of tokens.\nAny sequence beyond this maximum length will be truncated.\n", "example": 1024 }, "response_template": { "type": "string", "description": "Separator for the prediction/response in the single sequence to train on completions only.\n", "default": "\\n\\n### Response:" }, "verbalizer": { "type": "string", "description": "Verbalizer template to be used for formatting data at train and inference\ntime.\n\nThis template may use brackets to indicate where fields from the data\nmodel must be rendered.\n", "default": "### Input: {{input}} \\n\\n### Response: {{output}}" }, "gpu": { "$ref": "#/components/schemas/GPU" }, "peft_parameters": { "$ref": "#/components/schemas/FineTuningPeftParameters" }, "gradient_checkpointing": { "type": "boolean", "description": "Enabling gradient checkpointing reduces GPU memory required at the cost of slowing training by approx 20%.\n", "default": true } }, "required": [ "base_model" ] }, "FineTuningResourceEntity": { "type": "object", "description": "The fine tuning resource.\n", "properties": { "auto_update_model": { "type": "boolean", "description": "This field must not be set while creating a fine tuning job with InstructLab.\n\nIf set to `true` then the result of the training, if successful, will be\nuploaded to the repository as a model.\n", "default": false }, "parameters": { "$ref": "#/components/schemas/FineTuningParameters" }, "type": { "type": "string", "description": "The `type` of Fine Tuning training. The `type` is set to `ilab` for InstructLab training.\n", "enum": [ "ilab" ] }, "training_data_references": { "type": "array", "description": "The training datasets.\n", "items": { "$ref": "#/components/schemas/ObjectLocation" }, "minItems": 1, "maxItems": 20 }, "test_data_references": { "type": "array", "description": "This field must not be set while creating a fine tuning job with InstructLab.\n\nThe holdout/test datasets.\n", "items": { "$ref": "#/components/schemas/ObjectLocation" }, "minItems": 1, "maxItems": 20 }, "results_reference": { "allOf": [ { "$ref": "#/components/schemas/ObjectLocation" } ], "description": "The training results.\n\nWhen specified as `type=container` the results will be stored in the space or project.\n\nWhen specified as `type=connection_asset` the connection must be to a COS or S3 connection with a defined endpoint url.\n", "example": { "connection": { "id": "c4225076-74fa-4033-bf93-1183a9b6c611" }, "location": { "bucket": "experiment_results_bucket", "path": "results" }, "type": "connection_asset" } }, "custom": { "$ref": "#/components/schemas/Custom" } }, "required": [ "training_data_references", "results_reference" ] }, "FineTuningEntity": { "allOf": [ { "$ref": "#/components/schemas/FineTuningResourceEntity" }, { "$ref": "#/components/schemas/TrainingStatusOutput" } ] }, "FineTuningResource": { "type": "object", "description": "The response of a fine tuning job.\n", "properties": { "metadata": { "allOf": [ { "$ref": "#/components/schemas/ResourceMeta" } ], "example": { "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "name": "my-fine-tuning-job", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "owner": "guy", "created_at": "2023-08-04T13:22:55.289Z" } }, "entity": { "$ref": "#/components/schemas/FineTuningEntity" }, "system": { "$ref": "#/components/schemas/SystemDetails" } } }, "FineTuningResourceList": { "type": "object", "properties": { "resources": { "type": "array", "items": { "$ref": "#/components/schemas/FineTuningResource" } } } }, "FineTuningResources": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "$ref": "#/components/schemas/FineTuningResourceList" }, { "$ref": "#/components/schemas/System" } ] }, "FineTuningRequest": { "allOf": [ { "$ref": "#/components/schemas/ResourceRequestFields" }, { "$ref": "#/components/schemas/FineTuningResourceEntity" } ] }, "ResourceSpaceProjectMetadata": { "type": "object", "description": "Common metadata for a resource where `project_id` or `space_id` must be present.\n", "properties": { "space_id": { "$ref": "#/components/schemas/SpaceId" }, "project_id": { "$ref": "#/components/schemas/ProjectId" } } }, "TextExtractionMetadata": { "allOf": [ { "$ref": "#/components/schemas/ResourceMetaSimple" }, { "$ref": "#/components/schemas/ResourceSpaceProjectMetadata" } ] }, "CosDataConnection": { "type": "object", "description": "Contains a set of location fields specific to each data source.\n", "properties": { "id": { "type": "string", "description": "The id of the connection asset that contains the credentials required to access the data.\n" } }, "required": [ "id" ] }, "CosDataLocation": { "type": "object", "description": "Contains a set of fields specific to each connection.\n", "properties": { "file_name": { "type": "string", "description": "The name of the file. It has to be given only when the type is set as `connection_asset`. If multiple files are expected, for the output only, then the\n`file_name` must specify a directory and the value must end with a trailing `/`.\n", "example": "/results/" }, "bucket": { "type": "string", "description": "Can be used to override the bucket name from the connection asset.\n" }, "path": { "type": "string", "description": "Path of the file. Path only needs to be given when the `type` is given as `container`.\n" } } }, "TextExtractionDataReference": { "type": "object", "description": "A reference to data.\n", "properties": { "type": { "description": "The data source type.\n", "type": "string", "enum": [ "connection_asset", "container" ] }, "connection": { "$ref": "#/components/schemas/CosDataConnection" }, "location": { "$ref": "#/components/schemas/CosDataLocation" } }, "required": [ "type" ] }, "TextExtractionLanguagesList": { "type": "array", "description": "Set of languages to be expected in the document.\nThe language codes follow `ISO 639` where possible.\nSee the documentation for the currently supported languages.\n", "items": { "type": "string", "description": "A language that is expected in the document.\n" }, "minItems": 1, "maxItems": 100 }, "TextExtractionSemanticKvpField": { "type": "object", "description": "A mapping of fields to identify within the schema, where each key is the short-form name of the field, and the corresponding value is an object is a schema as defined below.\n`fields` and `pages` are mutually exclusive, you may define either fields or pages, but not both.\n", "properties": { "description": { "type": "string", "description": "Description of the field to identify.\n" }, "example": { "type": "string", "description": "An example value to help inform the LLM of structure and format.\n" }, "available_options": { "type": "array", "description": "Required for inferred fields to provide the available_options list of values to return from.\n", "items": { "type": "string", "description": "Provide a closed list of valid values to return and reduces the likelihood of model hallucinations.\n" } } }, "required": [ "description", "example" ], "oneOf": [ { "$ref": "#/components/schemas/TextExtractionSemanticKvpFieldWithTable" }, { "$ref": "#/components/schemas/TextExtractionSemanticKvpField" } ] }, "TextExtractionSemanticKvpFieldWithTable": { "type": "object", "description": "The fields are used to define variable layout schema\n", "properties": { "type": { "type": "string", "description": "For table schema, value always has to `array`.\n" }, "description": { "type": "string", "description": "The description of the table to identify\n" }, "columns": { "$ref": "#/components/schemas/TextExtractionSemanticKvpField" } }, "required": [ "columns" ] }, "TextExtractionSemanticKvpSlice": { "type": "object", "description": "Each slice represents a portion of a complex page or, in simpler layouts, can represent the entire page.\n", "properties": { "fields": { "description": "Mapping of fields to identify inside the schema. Each key should be the short-form name of the field, and the value can be one of the following:\nThe key will be used in the output as the field name.\n", "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/TextExtractionSemanticKvpFieldWithTable" }, { "$ref": "#/components/schemas/TextExtractionSemanticKvpField" }, { "type": "object" } ] } }, "normalized_bbox": { "type": "array", "description": "A normalized bounding box representing the page slice location, with the format\n`[left, top, right, bottom]`,where values are expressed as percentages ranging from 0 to 100.\n", "items": { "minItems": 1, "maxItems": 100 } } }, "required": [ "fields", "normalized_bbox" ] }, "TextExtractionSemanticKvpPage": { "type": "object", "description": "Mapping of page numbers and their coresponding page schema to identify. Required for fixed custom schema.\n", "properties": { "page_description": { "type": "string", "description": "A long-form description of the page that matches the page schema in the coresponding slices. Should be one or two sentences to ensure the LLM gets an accurate understanding.\n" }, "slices": { "type": "array", "description": "List of page slices.\n", "items": { "$ref": "#/components/schemas/TextExtractionSemanticKvpSlice" } } }, "required": [ "page_description" ] }, "TextExtractionSchema": { "type": "object", "description": "A custom schemas.\n", "properties": { "document_type": { "type": "string", "description": "Should be a short one or two word title like Passport or Bill Of Lading.\n" }, "document_description": { "type": "string", "description": "Should be one or two sentences to ensure the LLM gets an accurate understanding.\n" }, "fields": { "$ref": "#/components/schemas/TextExtractionSemanticKvpField" }, "pages": { "$ref": "#/components/schemas/TextExtractionSemanticKvpPage" }, "additional_prompt_instructions": { "type": "string", "description": "Optional, defaults to None. If configured, additional instructions that will be added to the vLLM prompt.\n" } }, "required": [ "document_type", "document_description" ] }, "TaskModelNameOverride": { "description": "User defined properties specified as key-value pairs. Supported task/key names are\nare `classification_exact`, `extraction`.\n", "type": "object", "example": { "create_schema": "pixtral-small-something-else" } }, "TextExtractionSemanticConfig": { "type": "object", "description": "Properties related to semantic config.\n", "properties": { "enable_text_hints": { "type": "boolean", "default": true, "description": "Determines whether to use text hints when extracting values—both for the schemas predefined keys and for generic KVP extraction.\n" }, "enable_schema_kvp": { "type": "boolean", "default": true, "description": "Indicates whether to perform schema Key-Value Pair (KVP) extraction.\n" }, "grounding_mode": { "type": "string", "enum": [ "precise", "fast" ], "default": "precise", "description": "Sets the level of Key-Value Pair (KVP) grounding precision.\n" }, "schemas_merge_strategy": { "type": "string", "enum": [ "merge", "replace" ], "default": "merge", "description": "Sets the merge strategy of the predefined and user defined input schemas.\n" }, "force_schema_name": { "type": "string", "default": "None", "description": "If provided, overrides the document classification step and forces the kvp extractor to use a\nspecified schema directly for value extraction by setting the schema document_type.\nIt must exactly match the document_type of one of the predefined or custom schemas currently in use.\n" }, "schemas": { "type": "array", "description": "Specifies custom schemas that should be used for semantic KVP extraction, outside the predefined schemas.\n", "items": { "$ref": "#/components/schemas/TextExtractionSchema" } }, "default_model_name": { "type": "string", "description": "By default, the model documented in [this page](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-api-text-extraction.html?context=wx&audience=wdp) is used.\nThis parameter allows changing the default model to another compatible vision model. A list of compatible vision models is\navailable [here](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-api-text-extraction.html?context=wx&audience=wdp).\n" }, "task_model_name_override": { "$ref": "#/components/schemas/TaskModelNameOverride" } } }, "TextExtractionParameters": { "type": "object", "description": "The parameters for the text extraction.\n", "properties": { "requested_outputs": { "type": "array", "description": "A list of requested outputs.\n", "items": { "type": "string", "description": "A requested output.\n", "enum": [ "assembly", "html", "md", "plain_text", "page_images" ] }, "default": [ "plain_text" ] }, "mode": { "type": "string", "description": "Which processing mode to use for this request.\n", "enum": [ "standard", "high_quality" ], "default": "standard" }, "ocr_mode": { "type": "string", "description": "If OCR should be used when processing a document.\nAn empty value allows the service to select the best option for your processing mode.\n- `enabled`: OCR is run on embedded images, OCR is only run if no programmatic text could be extracted from the area.\n- `disabled`: OCR is not run, no information is extracted from images or scanned documents.\n- `forced`: Document processing will take a picture of the page and run OCR across it, this applies to all documents even purely programmatic ones.\n", "enum": [ "disabled", "enabled", "forced" ] }, "languages": { "$ref": "#/components/schemas/TextExtractionLanguagesList" }, "auto_rotation_correction": { "type": "boolean", "description": "Should the service attempt to fix a rotated page or image.\n", "default": false }, "create_embedded_images": { "type": "string", "description": "If the service should return embedded images in the output markdown and JSON formats.\n", "enum": [ "disabled", "enabled_placeholder", "enabled_text", "enabled_verbalization", "enabled_verbalization_all" ], "default": "disabled" }, "output_dpi": { "type": "number", "description": "The DPI for extracted images.\n", "default": 72 }, "output_tokens": { "type": "boolean", "description": "Disables returning the individual tokens.\n", "default": true }, "kvp_mode": { "type": "string", "description": "Which version of KVP should be used when processing, if not set then KVP is disabled.\nSee the documentation for more information about the available modes.\n", "enum": [ "generic_with_semantic" ] }, "semantic_config": { "$ref": "#/components/schemas/TextExtractionSemanticConfig" } } }, "TextExtractionEntity": { "type": "object", "description": "The parameters for the text extraction.\n", "required": [ "document_reference", "results_reference" ], "properties": { "document_reference": { "$ref": "#/components/schemas/TextExtractionDataReference" }, "results_reference": { "$ref": "#/components/schemas/TextExtractionDataReference" }, "parameters": { "$ref": "#/components/schemas/TextExtractionParameters" }, "custom": { "$ref": "#/components/schemas/Custom" } } }, "ServiceError": { "type": "object", "description": "A service error message.\n", "properties": { "code": { "type": "string", "description": "A simple code that should convey the general sense of the error.\n" }, "message": { "type": "string", "description": "The message that describes the error.\n" }, "more_info": { "type": "string", "description": "A URL to a more detailed explanation when available.\n" } }, "required": [ "code", "message" ] }, "TextExtractionResults": { "type": "object", "description": "The current status of the text extraction.\n", "properties": { "status": { "type": "string", "description": "The status of the request.\n", "enum": [ "submitted", "uploading", "running", "downloading", "downloaded", "completed", "failed" ] }, "running_at": { "type": "string", "format": "date-time", "description": "The time when the request is successfully running on the processor.\n" }, "completed_at": { "type": "string", "format": "date-time", "description": "The time when the request completed or failed.\n" }, "number_pages_processed": { "type": "integer", "description": "The number of pages that have been processed in the document.\nIf the status is `completed` then this is the number of pages\nthat will be billed.\n" }, "total_pages": { "type": "integer", "description": "The total number of pages to be processed.\n" }, "location": { "type": "array", "description": "The location of the output files that were produced.\n", "items": { "type": "string" } }, "error": { "$ref": "#/components/schemas/ServiceError" } }, "required": [ "status", "number_pages_processed" ] }, "TextExtractionResource": { "type": "object", "description": "The text extraction resource.\n", "properties": { "metadata": { "$ref": "#/components/schemas/TextExtractionMetadata" }, "entity": { "allOf": [ { "$ref": "#/components/schemas/TextExtractionEntity" }, { "type": "object", "properties": { "results": { "$ref": "#/components/schemas/TextExtractionResults" } }, "required": [ "results" ] } ] } } }, "TextExtractionResources": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "description": "Pagination information and list of resources.\n", "properties": { "resources": { "type": "array", "description": "A list of resources.\n", "items": { "$ref": "#/components/schemas/TextExtractionResource" } } } }, { "$ref": "#/components/schemas/System" } ], "description": "A paginated list of resources.\n" }, "EntityRequestSpaceProjectOnly": { "type": "object", "description": "The properties that are part of a request that supports spaces and projects.\nEither `space_id` or `project_id` has to be provided and is mandatory.\n", "properties": { "project_id": { "$ref": "#/components/schemas/ProjectId" }, "space_id": { "$ref": "#/components/schemas/SpaceId" } } }, "TextExtractionRequest": { "allOf": [ { "$ref": "#/components/schemas/TextExtractionEntity" }, { "$ref": "#/components/schemas/EntityRequestSpaceProjectOnly" } ] }, "TextExtractionResponse": { "type": "object", "description": "The text extraction response.\n", "allOf": [ { "$ref": "#/components/schemas/TextExtractionResource" }, { "$ref": "#/components/schemas/System" } ] }, "TextImageParameters": { "type": "object", "description": "Properties that control the image generation.\n", "example": { "height": 1024, "width": 1024 }, "properties": { "height": { "type": "integer", "description": "The height of the generated image.\n\nNote that only certain heights may be supported depending on the model being used.\n", "minimum": 320, "maximum": 1536 }, "width": { "type": "integer", "description": "The width of the generated image.\n\nNote that only certain widths may be supported depending on the model being used.\n", "minimum": 320, "maximum": 1536 } } }, "ModerationInputProperties": { "type": "object", "description": "The properties for the moderation. Each type of moderation\nmay have additional properties that are specific to that moderation.\n", "properties": { "input": { "$ref": "#/components/schemas/TextModeration" } }, "additionalProperties": { "type": "object" } }, "ModerationHapInputProperties": { "allOf": [ { "$ref": "#/components/schemas/ModerationInputProperties" }, { "$ref": "#/components/schemas/HapProperties" } ] }, "ModerationPiiInputProperties": { "allOf": [ { "$ref": "#/components/schemas/ModerationInputProperties" }, { "$ref": "#/components/schemas/PiiProperties" } ] }, "ModerationsInput": { "type": "object", "description": "Properties that control the moderations, for usages such as `Hate and profanity` (HAP) and `Personal identifiable information` (PII) filtering. This list can be extended with new types of moderations.\n", "properties": { "hap": { "$ref": "#/components/schemas/ModerationHapInputProperties" }, "pii": { "$ref": "#/components/schemas/ModerationPiiInputProperties" } }, "additionalProperties": { "$ref": "#/components/schemas/ModerationInputProperties" }, "example": { "hap": { "input": { "enabled": true, "threshold": 0.5 } }, "pii": { "input": { "enabled": true }, "mask": { "remove_entity_value": true } } } }, "TextImageRequest": { "type": "object", "description": "The model id and textual description of the image to be generated.\n\nOne of `space_id` or `project_id` must be provided.\n", "required": [ "model_id", "input" ], "properties": { "space_id": { "$ref": "#/components/schemas/SpaceId" }, "project_id": { "$ref": "#/components/schemas/ProjectId" }, "model_id": { "type": "string", "description": "The `id` of the model to be used for this request.\n\nPlease refer to the [list of\nmodels](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models.html?context=wx).\n" }, "input": { "type": "string", "description": "The textual description of the image to be generated.\n" }, "parameters": { "$ref": "#/components/schemas/TextImageParameters" }, "moderations": { "$ref": "#/components/schemas/ModerationsInput" } } }, "TextChatMessageSystem": { "description": "The definition of a system message.\n", "allOf": [ { "$ref": "#/components/schemas/TextChatMessage" }, { "type": "object", "description": "The definition of a system message.\n", "properties": { "content": { "type": "string", "description": "The contents of the system message.\n" }, "name": { "$ref": "#/components/schemas/TextChatMessageFieldName" } }, "required": [ "content" ] } ] }, "TextChatMessages": { "oneOf": [ { "$ref": "#/components/schemas/TextChatMessageAssistant" }, { "$ref": "#/components/schemas/TextChatMessageControl" }, { "$ref": "#/components/schemas/TextChatMessageSystem" }, { "$ref": "#/components/schemas/TextChatMessageTool" }, { "$ref": "#/components/schemas/TextChatMessageUser" } ], "discriminator": { "propertyName": "role", "mapping": { "assistant": "#/components/schemas/TextChatMessageAssistant", "control": "#/components/schemas/TextChatMessageControl", "system": "#/components/schemas/TextChatMessageSystem", "tool": "#/components/schemas/TextChatMessageTool", "user": "#/components/schemas/TextChatMessageUser" } } }, "ChatCompletionsRequest": { "allOf": [ { "type": "object", "description": "The request for chat.\n\nNote that some models might not support all the tool calling functionality.\nIn the case that the functionality is not supported the API will return\nan error code.\n\nOnly one of `tool_choice_option` or `tool_choice` must be present.\n", "properties": { "model": { "type": "string", "description": "The model to use for the chat completion.\n\nPlease refer to the [list of\nmodels](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models.html?context=wx).\n" }, "messages": { "type": "array", "description": "The messages for this chat session.\n", "items": { "$ref": "#/components/schemas/TextChatMessages" }, "minItems": 1, "maxItems": 1000 }, "space_id": { "$ref": "#/components/schemas/SpaceId" }, "project_id": { "$ref": "#/components/schemas/ProjectId" }, "tools": { "type": "array", "description": "Tool functions that can be called with the response.\n", "items": { "$ref": "#/components/schemas/TextChatParameterTools" }, "minItems": 1, "maxItems": 128 }, "tool_choice_option": { "$ref": "#/components/schemas/TextChatToolChoiceOption" }, "tool_choice": { "$ref": "#/components/schemas/TextChatToolChoiceTool" } }, "required": [ "model", "messages" ] }, { "$ref": "#/components/schemas/TextChatParameters" } ] }, "TextChatRequest": { "allOf": [ { "type": "object", "description": "The request for chat.\n\nNote that some models might not support all the tool calling functionality.\nIn the case that the functionality is not supported the API will return\nan error code.\n\nOnly one of `tool_choice_option` or `tool_choice` must be present.\n", "properties": { "model_id": { "type": "string", "description": "The model to use for the chat completion.\n\nPlease refer to the [list of\nmodels](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models.html?context=wx).\n" }, "model": { "type": "string", "description": "This is an alias for `model_id` and can be used instead of `model_id`.\n\nThe field `model_id` is marked as mandatory but it can be replaced by the `model` field for compatibility\nwith other APIs.\n" }, "messages": { "type": "array", "description": "The messages for this chat session.\n", "items": { "$ref": "#/components/schemas/TextChatMessages" }, "minItems": 1, "maxItems": 1000 }, "space_id": { "$ref": "#/components/schemas/SpaceId" }, "project_id": { "$ref": "#/components/schemas/ProjectId" }, "moderations": { "$ref": "#/components/schemas/Moderations" }, "tools": { "type": "array", "description": "Tool functions that can be called with the response.\n", "items": { "$ref": "#/components/schemas/TextChatParameterTools" }, "minItems": 1, "maxItems": 128 }, "tool_choice_option": { "$ref": "#/components/schemas/TextChatToolChoiceOption" }, "tool_choice": { "$ref": "#/components/schemas/TextChatToolChoiceTool" }, "guided_choice": { "type": "array", "description": "If specified, the output will be exactly one of the choices.\n", "items": { "type": "string" } }, "guided_regex": { "type": "string", "description": "If specified, the output will follow the regex pattern.\n" }, "guided_grammar": { "type": "string", "description": "If specified, the output will follow the context free grammar.\n" }, "guided_json": { "type": "object", "description": "If specified, the output will follow the JSON schema.\nSee the [JSON Schema reference](https://json-schema.org/learn/getting-started-step-by-step)\nfor documentation about the format.\n" }, "crypto": { "$ref": "#/components/schemas/CryptoInfo" } }, "required": [ "model_id", "messages" ] }, { "$ref": "#/components/schemas/TextChatParameters" } ] }, "TextChatStreamRequest": { "allOf": [ { "type": "object", "description": "The request for chat stream.\n\nNote that some models might not support all the tool calling functionality.\nIn the case that the functionality is not supported the API will return\nan error code.\n\nOnly one of `tool_choice_option` or `tool_choice` must be present.\n", "properties": { "model_id": { "type": "string", "description": "The model to use for the chat completion.\n\nPlease refer to the [list of\nmodels](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models.html?context=wx).\n" }, "model": { "type": "string", "description": "This is an alias for `model_id` and can be used instead of `model_id`.\n\nThe field `model_id` is marked as mandatory but it can be replaced by the `model` field for compatibility\nwith other APIs.\n" }, "messages": { "type": "array", "description": "The messages for this chat session.\n", "items": { "$ref": "#/components/schemas/TextChatMessages" }, "minItems": 1, "maxItems": 1000 }, "space_id": { "$ref": "#/components/schemas/SpaceId" }, "project_id": { "$ref": "#/components/schemas/ProjectId" }, "moderations": { "$ref": "#/components/schemas/Moderations" }, "tools": { "type": "array", "description": "Tool functions that can be called with the response.\n", "items": { "$ref": "#/components/schemas/TextChatParameterTools" }, "minItems": 1, "maxItems": 128 }, "tool_choice_option": { "$ref": "#/components/schemas/TextChatToolChoiceOption" }, "tool_choice": { "$ref": "#/components/schemas/TextChatToolChoiceTool" }, "guided_choice": { "type": "array", "description": "If specified, the output will be exactly one of the choices.\n", "items": { "type": "string" } }, "guided_regex": { "type": "string", "description": "If specified, the output will follow the regex pattern.\n" }, "guided_grammar": { "type": "string", "description": "If specified, the output will follow the context free grammar.\n" }, "guided_json": { "type": "object", "description": "If specified, the output will follow the JSON schema.\nSee the [JSON Schema reference](https://json-schema.org/learn/getting-started-step-by-step)\nfor documentation about the format.\n" } }, "required": [ "model_id", "messages" ] }, { "$ref": "#/components/schemas/TextChatParameters" } ] }, "AIServiceDocumentationInit": { "allOf": [ { "$ref": "#/components/schemas/JSONContentSchema" }, { "type": "object", "description": "A JSON schema describing the init parameters.\n" } ] }, "AIServiceDocumentationFunctions": { "type": "object", "description": "The documentation for which endpoints are supported. If any of the fields do not exist then they are assumed to be `true`.\n\nIf the deployment only supports batch jobs then the `functions` object would be declared like this:\n\n\n ```json\n \"functions\": {\n \"generate\": false,\n \"generate_stream\": false\n }\n ```\n\n\nIf the deployment only supports online scoring, with streaming support as well, then the `functions` object would be declared like this:\n\n\n ```json\n \"functions\": {\n \"generate_batch\": false\n }\n ```", "properties": { "generate": { "type": "boolean", "description": "Is the generate endpoint supported?\n", "default": true }, "generate_stream": { "type": "boolean", "description": "Is the generate_stream endpoint supported?\n", "default": true }, "generate_batch": { "type": "boolean", "description": "Is the generate_batch endpoint supported?\n", "default": true } } }, "AIServiceDocumentation": { "type": "object", "description": "The documentation of the AI service request body and response body.\n", "properties": { "request": { "$ref": "#/components/schemas/JSONContentDefinition" }, "response": { "$ref": "#/components/schemas/JSONContentDefinition" }, "init": { "$ref": "#/components/schemas/AIServiceDocumentationInit" }, "functions": { "$ref": "#/components/schemas/AIServiceDocumentationFunctions" } } }, "AIServiceEntity": { "type": "object", "description": "The details of the AI service to be created.\n", "properties": { "software_spec": { "$ref": "#/components/schemas/SoftwareSpecRel" }, "code_type": { "type": "string", "description": "The type that allows the deployment service to know\nhow to setup the code during deployment.\n", "enum": [ "python" ] }, "documentation": { "$ref": "#/components/schemas/AIServiceDocumentation" }, "custom": { "$ref": "#/components/schemas/Custom" }, "tooling": { "$ref": "#/components/schemas/Tooling" } }, "required": [ "software_spec" ] }, "AIServiceResource": { "type": "object", "description": "The information for a flow.\n", "properties": { "metadata": { "$ref": "#/components/schemas/ResourceMeta" }, "entity": { "allOf": [ { "$ref": "#/components/schemas/AIServiceEntity" } ] }, "system": { "$ref": "#/components/schemas/SystemDetails" } }, "required": [ "metadata", "entity" ] }, "AIServiceResources": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "description": "Pagination information and list of AI services.\n", "properties": { "resources": { "type": "array", "description": "A list of AI services.\n", "items": { "$ref": "#/components/schemas/AIServiceResource" } } } }, { "$ref": "#/components/schemas/System" } ], "description": "A paginated list of AI services.\n" }, "EntityRequestSpaceBody": { "type": "object", "description": "The properties that are part of a request that supports spaces.\n", "properties": { "space_id": { "$ref": "#/components/schemas/SpaceIdOnly" }, "name": { "type": "string", "description": "The name of the resource.\n", "example": "my-resource" }, "description": { "type": "string", "description": "A description of the resource.\n", "example": "This is my first resource." }, "tags": { "$ref": "#/components/schemas/Tags" } }, "required": [ "space_id", "name" ] }, "AIServiceRequest": { "allOf": [ { "$ref": "#/components/schemas/EntityRequestSpaceBody" }, { "$ref": "#/components/schemas/AIServiceEntity" } ] }, "AIServiceContentMetadata": { "type": "object", "description": "The metadata related to the attachment.\n", "properties": { "attachment_id": { "type": "string", "description": "The content id for the attachment.\n", "example": "fd45606f-8098-459c-8961-32b136123fgc" } }, "required": [ "attachment_id" ] }, "RevisionEntitySpaceProjectRequest": { "type": "object", "description": "The details for the revision.\n", "properties": { "space_id": { "$ref": "#/components/schemas/SpaceId" }, "project_id": { "$ref": "#/components/schemas/ProjectId" }, "commit_message": { "type": "string", "description": "An optional commit message for the revision.\n" } }, "example": { "space_id": "3fc54cf1-252f-424b-b52d-5cdd9814987f", "commit_message": "Updated for TF 2.0" } }, "TextDetectionPropertyThreshold": { "type": "number", "format": "float", "description": "The threshold probability that this is a real match.\nA higher threshold makes the detector less sensitive, reducing false positives but possibly missing some detections.\n", "minimum": 0, "maximum": 1, "default": 0.5 }, "TextDetectionHAPDetector": { "type": "object", "description": "The definition of a `Hate and profanity` (HAP) text detector.\n", "properties": { "threshold": { "$ref": "#/components/schemas/TextDetectionPropertyThreshold" } }, "additionalProperties": {} }, "TextDetectionPIIDetector": { "type": "object", "description": "The definition of a `Personal identifiable information` (PII) text detector.\n", "additionalProperties": {} }, "TextDetectionGraniteGuardianDetector": { "type": "object", "description": "The definition of a `Granite Guardian` text detector. This detector is in beta and may change.\n", "properties": { "threshold": { "$ref": "#/components/schemas/TextDetectionPropertyThreshold" } }, "additionalProperties": {} }, "TextDetectionDetector": { "type": "object", "description": "The optional key/value pairs for the detector.\n", "additionalProperties": { "type": "string" } }, "TextDetectionDetectors": { "type": "object", "description": "The detectors to use, this is a map of `detector-name` with a map of optional key/value pairs.\n", "additionalProperties": { "$ref": "#/components/schemas/TextDetectionDetector" } }, "TextDetectionContentDetectors": { "type": "object", "description": "The detectors to use, these can be IBM provided `HAP` or `PII` detectors or a custom content detector.\n", "properties": { "hap": { "$ref": "#/components/schemas/TextDetectionHAPDetector" }, "pii": { "$ref": "#/components/schemas/TextDetectionPIIDetector" }, "granite_guardian": { "$ref": "#/components/schemas/TextDetectionGraniteGuardianDetector" } }, "additionalProperties": { "$ref": "#/components/schemas/TextDetectionDetectors" } }, "TextDetectionContentRequest": { "type": "object", "description": "The request for text detection on input content.\n", "properties": { "input": { "type": "string", "description": "The text to be examined.\n" }, "detectors": { "$ref": "#/components/schemas/TextDetectionContentDetectors" }, "space_id": { "$ref": "#/components/schemas/SpaceId" }, "project_id": { "$ref": "#/components/schemas/ProjectId" } }, "required": [ "input", "detectors" ] }, "TextDetectionScore": { "type": "number", "format": "float", "description": "The threshold probability that this is a real match.\n", "minimum": 0, "maximum": 1, "example": 0.823 }, "TextDetectionDetectionItem": { "type": "object", "description": "Detection details.\n", "properties": { "detection_type": { "type": "string", "description": "The type of the detection identified.\n" }, "detection": { "type": "string", "description": "The detected string.\n" }, "score": { "$ref": "#/components/schemas/TextDetectionScore" } }, "required": [ "detection_type", "detection", "score" ] }, "TextDetectionContextPosition": { "type": "object", "description": "The text that was detected.\n", "properties": { "start": { "type": "integer", "description": "The position in the content where the detected text starts.\n" }, "end": { "type": "integer", "description": "The position in the content where the detected text ends.\n" } }, "required": [ "start", "end" ] }, "TextDetectionContentItem": { "allOf": [ { "$ref": "#/components/schemas/TextDetectionDetectionItem" }, { "$ref": "#/components/schemas/TextDetectionContextPosition" } ] }, "TextDetectionContentResponse": { "type": "object", "description": "The response for text detection.\n", "properties": { "detections": { "type": "array", "description": "The text that was detected.\n", "items": { "$ref": "#/components/schemas/TextDetectionContentItem" }, "minItems": 0 } } }, "TextDetectionContext": { "type": "string", "format": "url", "description": "The context item.\n" }, "TextDetectionContextRequest": { "type": "object", "description": "The request for text detection based on context documents.\n", "properties": { "input": { "type": "string", "description": "The text to be examined.\n" }, "detectors": { "$ref": "#/components/schemas/TextDetectionDetectors" }, "context_type": { "type": "string", "description": "The type of the context.\n", "enum": [ "docs" ] }, "context": { "description": "Context documents.\n", "items": { "$ref": "#/components/schemas/TextDetectionContext" }, "minItems": 1, "maxItems": 100, "example": [ "https://en.wikipedia.org/wiki/IBM", "https://research.ibm.com/" ] }, "space_id": { "$ref": "#/components/schemas/SpaceId" }, "project_id": { "$ref": "#/components/schemas/ProjectId" } }, "required": [ "input", "detectors", "context_type", "context" ] }, "TextDetectionEvidenceObject": { "type": "object", "description": "The details for a given evidence.\n", "properties": { "name": { "type": "string", "description": "The name for the evidence.\n" }, "value": { "type": "string", "description": "The value for the evidence.\n" }, "score": { "$ref": "#/components/schemas/TextDetectionScore" } }, "required": [ "name", "value", "score" ] }, "TextDetectionChildEvidence": { "allOf": [ { "$ref": "#/components/schemas/TextDetectionEvidenceObject" }, { "type": "object", "description": "Child evidence.\n", "properties": { "evidence": { "type": "array", "description": "The child evidence details.\n", "items": { "$ref": "#/components/schemas/TextDetectionEvidenceObject" }, "minItems": 0, "maxItems": 100 } } } ] }, "TextDetectionEvidenceReference": { "type": "object", "description": "Detection evidence.\n", "properties": { "evidence": { "type": "array", "description": "The evidence details.\n", "items": { "$ref": "#/components/schemas/TextDetectionChildEvidence" }, "minItems": 0, "maxItems": 100 } }, "required": [ "evidence" ] }, "TextDetectionContextItem": { "allOf": [ { "$ref": "#/components/schemas/TextDetectionDetectionItem" }, { "$ref": "#/components/schemas/TextDetectionEvidenceReference" } ] }, "TextDetectionContextResponse": { "type": "object", "description": "The response for text context detection.\n", "properties": { "detections": { "type": "array", "description": "The text that was detected.\n", "items": { "$ref": "#/components/schemas/TextDetectionContextItem" }, "minItems": 0 } }, "required": [ "detections" ] }, "TextDetectionGeneratedRequest": { "type": "object", "description": "The request for text detection on prompt and generated text.\n", "properties": { "prompt": { "type": "string", "description": "The text prompt.\n" }, "generated_text": { "type": "string", "description": "The generated text.\n" }, "detectors": { "$ref": "#/components/schemas/TextDetectionDetectors" }, "space_id": { "$ref": "#/components/schemas/SpaceId" }, "project_id": { "$ref": "#/components/schemas/ProjectId" } }, "required": [ "prompt", "generated_text", "detectors" ] }, "TextDetectionGeneratedResponse": { "type": "object", "description": "The response for generated text detection.\n", "properties": { "detections": { "type": "array", "description": "The text that was detected.\n", "items": { "$ref": "#/components/schemas/TextDetectionDetectionItem" }, "minItems": 0 } }, "required": [ "detections" ] }, "TSForecastResource": { "type": "object", "description": "Input necessary for performing inference. These inputs\nidentify things like which model to use, the data payload\nyou are passing to the model, and other parameters which affect\nthe behavior of the inference operation.\n", "example": { "schema": { "timestamp_column": "date", "id_columns": [ "ID1" ] }, "data": { "date": [ "2020-01-01T00:00:00", "2020-01-01T01:00:00", "2020-01-01T02:00:00" ], "ID1": [ "D1", "D1", "D1" ], "TARGET1": [ 1.46, 2.34, 4.55 ] }, "model_id": "ibm/ttm-1024-96-r2" }, "properties": { "model_id": { "type": "string", "description": "The model to be used for generating a forecast. You can get the list of models by using\n[Foundation Model Specs](#list-foundation-model-specs) with\n`filters=function_time_series_forecast`.\n", "minLength": 1, "maxLength": 256, "pattern": "^\\S+$" }, "parameters": { "$ref": "#/components/schemas/TSCommonForecastParameters" }, "project_id": { "type": "string", "description": "The project id of the resource.\n" }, "data": { "type": "object", "description": "A payload of data matching `schema`.\nWe assume the following about your data:\n * All timeseries are of equal length and are uniform in nature (the time difference\nbetween two successive rows is constant). This implies that there are no missing rows of data;\n * The data meet the minimum model-dependent historical context length which\n can be 512 or more rows per timeseries;\n\nNote that the example payloads shown are for illustration purposes only. An actual payload\nwould necessary be much larger to meet minimum model-specific context lengths.\n", "additionalProperties": {} }, "schema": { "$ref": "#/components/schemas/TSForecastInputSchema" } }, "required": [ "model_id", "data", "schema" ] }, "TSForecastRequest": { "allOf": [ { "$ref": "#/components/schemas/EntityRequestSpaceProjectOnly" }, { "$ref": "#/components/schemas/TSForecastResource" } ] }, "DocumentExtractionObjectLocation": { "type": "object", "description": "A reference to data.\n", "properties": { "type": { "description": "The data source type. This field must be set to `container`.\n", "type": "string", "enum": [ "container" ], "example": "container" }, "location": { "$ref": "#/components/schemas/DataLocation" } }, "required": [ "type", "location" ] }, "FilePaths": { "type": "object", "properties": { "filepaths": { "type": "array", "items": { "type": "string" }, "description": "This is a vector of strings where each string will be the filepath of the .md file stored in the user's github repository.\n", "example": [ "results/text_extraction/1.md" ] } } }, "Commit": { "type": "object", "properties": { "commit": { "type": "string", "minLength": 40, "maxLength": 40, "description": "The hash of the git commit when the results were saved.\n" } } }, "ObjectLocationGithub": { "type": "object", "description": "A reference to data.\n", "properties": { "type": { "description": "The data source type, for now only `github` is supported.\n", "type": "string", "enum": [ "github" ], "example": "github" }, "location": { "allOf": [ { "$ref": "#/components/schemas/DataLocation" }, { "$ref": "#/components/schemas/FilePaths" }, { "$ref": "#/components/schemas/Commit" } ] } }, "required": [ "type", "location" ] }, "DocumentExtractionCommon": { "type": "object", "description": "The details needed to create document extraction job.", "properties": { "name": { "type": "string", "description": "The name of the document.\n" }, "document_references": { "type": "array", "description": "The documents for text extraction.\n", "items": { "$ref": "#/components/schemas/DocumentExtractionObjectLocation" }, "minLength": 1 }, "results_reference": { "$ref": "#/components/schemas/ObjectLocationGithub" }, "tags": { "$ref": "#/components/schemas/Tags" } }, "required": [ "name", "document_references", "results_reference" ] }, "DocumentExtractionStatus": { "type": "object", "description": "Status of the document extraction job.\n", "properties": { "state": { "type": "string", "description": "Current state of document extraction.\n", "enum": [ "queued", "pending", "running", "storing", "completed_at", "failed", "canceled" ], "example": "running" }, "completed_at": { "type": "string", "format": "date-time", "description": "The time when the job completed or failed.\n" } }, "required": [ "state" ] }, "DocumentExtractionResponse": { "allOf": [ { "$ref": "#/components/schemas/DocumentExtractionCommon" }, { "type": "object", "description": "The document extraction job properties.\n", "properties": { "status": { "$ref": "#/components/schemas/DocumentExtractionStatus" } } } ] }, "DocumentExtractionResource": { "type": "object", "description": "The response from getting a specified document extraction job.", "properties": { "metadata": { "$ref": "#/components/schemas/ResourceMeta" }, "entity": { "$ref": "#/components/schemas/DocumentExtractionResponse" }, "system": { "$ref": "#/components/schemas/SystemDetails" } } }, "DocumentExtractionResources": { "type": "object", "description": "The response of getting all document extraction jobs.", "properties": { "limit": { "type": "integer", "description": "The number of items to return in each page.\n", "example": 10, "minimum": 1, "maximum": 200 }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentExtractionResource" } } }, "required": [ "limit" ] }, "DocumentExtractionRequest": { "allOf": [ { "$ref": "#/components/schemas/DocumentExtractionCommon" }, { "$ref": "#/components/schemas/EntityRequestSpaceProjectOnly" } ] }, "SyntheticDataGenerationSample": { "type": "object", "description": "The Synthetic Data Generation sample metrics.\n", "properties": { "knowledge": { "description": "The knowledge metric value.", "type": "integer" }, "skills": { "description": "The skills metric value.", "type": "integer" }, "total": { "description": "The combined value of the metric values.", "type": "integer" } } }, "SyntheticDataGenerationMetric": { "type": "object", "description": "The Synthetic Data Generation metrics.\n", "properties": { "samples": { "$ref": "#/components/schemas/SyntheticDataGenerationSample" } } }, "SyntheticDataGenerationLocations": { "type": "object", "description": "The Synthetic Data Generation location metrics.\n", "properties": { "knowledge": { "description": "The path to the created Knowledge file.", "type": "string" }, "skills": { "description": "The path to the created Skills file.", "type": "string" }, "logs": { "description": "The path to the created Logs file.", "type": "string" }, "artifacts": { "description": "The path to the created Artifacts file.", "type": "string" } } }, "SyntheticDataGenerationContext": { "type": "object", "description": "The Synthetic Data Generation context.\n", "properties": { "samples": { "$ref": "#/components/schemas/SyntheticDataGenerationLocations" }, "locations": { "$ref": "#/components/schemas/DataLocation" } } }, "SyntheticDataGenerationMetrics": { "type": "object", "description": "All the Synthetic Data Generation metrics.\n", "properties": { "synthetic_data_generation_metrics": { "$ref": "#/components/schemas/SyntheticDataGenerationMetric" }, "context": { "$ref": "#/components/schemas/SyntheticDataGenerationContext" }, "timestamp": { "type": "string", "format": "date-time", "description": "The timestamp when the metrics were gathered.\n", "minLength": 24, "maxLength": 24, "example": "2024-02-28T11:30:26.000Z" } } }, "SyntheticDataGenerationStatus": { "type": "object", "description": "The status of a Synthetic Data Generation job.\n", "properties": { "state": { "type": "string", "description": "The status of the job.\n", "enum": [ "queued", "pending", "running", "storing", "completed", "failed", "canceled" ] }, "metrics": { "type": "array", "description": "The computed metrics.\n", "items": { "$ref": "#/components/schemas/SyntheticDataGenerationMetrics" }, "minItems": 0 }, "step": { "type": "string", "description": "The step the job is currently in.\n" }, "completed_at": { "type": "string", "format": "date-time", "description": "The timestamp when the job completed.\n", "minLength": 24, "maxLength": 24, "example": "2024-02-28T11:30:26.000Z" }, "running_at": { "type": "string", "format": "date-time", "description": "The timestamp when the job completed.\n", "minLength": 24, "maxLength": 24, "example": "2024-02-28T11:30:26.000Z" }, "locations": { "$ref": "#/components/schemas/DataLocation" } }, "required": [ "state" ] }, "SyntheticDataGenerationResponse": { "type": "object", "description": "The synthetic data generation job properties.", "properties": { "results_reference": { "$ref": "#/components/schemas/ObjectLocation" }, "status": { "$ref": "#/components/schemas/SyntheticDataGenerationStatus" }, "data_reference": { "$ref": "#/components/schemas/ObjectLocation" } } }, "SyntheticDataGenerationResource": { "type": "object", "description": "The response from getting a specified synthetic data generation job.", "properties": { "metadata": { "$ref": "#/components/schemas/ResourceMeta" }, "entity": { "$ref": "#/components/schemas/SyntheticDataGenerationResponse" }, "system": { "$ref": "#/components/schemas/SystemDetails" } } }, "SyntheticDataGenerationResources": { "type": "object", "description": "The response of getting all synthetic data generation jobs.", "properties": { "limit": { "type": "integer", "description": "The number of items to return in each page.\n", "example": 10 }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/SyntheticDataGenerationResource" } } }, "required": [ "limit" ] }, "SyntheticDataGenerationRequest": { "type": "object", "description": "The details needed to create synthetic data generation job.\n\nThe `data_reference.type` must be `taxonomy_asset` and the `results_reference.type`\nwill normally be something like `connection_asset` or `data_asset`.\n", "properties": { "name": { "type": "string", "description": "The name of the data.\n\nThe value must be a lowercase alphanumeric value but it can also have non-consecutive dashes (-)\nand underscores (_). The value must start and end with an alphanumeric character.\n", "minLength": 1, "maxLength": 250, "pattern": "^[^><%\\\\]*$", "example": "example-name" }, "space_id": { "$ref": "#/components/schemas/SpaceId" }, "project_id": { "$ref": "#/components/schemas/ProjectId" }, "data_reference": { "$ref": "#/components/schemas/ObjectLocation" }, "results_reference": { "$ref": "#/components/schemas/ObjectLocation" } }, "required": [ "name" ] }, "TaxonomyStatus": { "type": "object", "description": "The status of a Taxonomy job.\n", "properties": { "state": { "type": "string", "description": "The status of the job.\n", "enum": [ "queued", "pending", "running", "storing", "completed", "failed", "canceled" ], "example": "running" }, "completed_at": { "type": "string", "description": "The timestamp when the job completed.\n", "minLength": 24, "maxLength": 24, "example": "2024-02-28T11:33:58.000Z" }, "running_at": { "type": "string", "description": "Date and Time in which current training state has started.\n", "minLength": 24, "maxLength": 24, "example": "2024-02-28T11:33:58.000Z" } } }, "TaxonomyResponse": { "type": "object", "description": "The Taxonomy entity.\n\n\nThe `data_reference.type` will be `github` and the `results_reference.type` will be set to `taxonomy_asset`.\n", "properties": { "results_reference": { "$ref": "#/components/schemas/ObjectLocation" }, "status": { "$ref": "#/components/schemas/TaxonomyStatus" }, "data_reference": { "$ref": "#/components/schemas/ObjectLocation" } } }, "TaxonomyResource": { "type": "object", "description": "The response fields from a Taxonomy request.", "properties": { "metadata": { "$ref": "#/components/schemas/ResourceMeta" }, "entity": { "$ref": "#/components/schemas/TaxonomyResponse" }, "system": { "$ref": "#/components/schemas/SystemDetails" } } }, "TaxonomyResources": { "type": "object", "description": "The list of Taxonomy jobs in specified project or space.", "properties": { "limit": { "type": "integer", "description": "The number of items to return in each page.\n", "example": 10 }, "resources": { "type": "array", "description": "The Taxonomy jobs in a project or space.", "items": { "$ref": "#/components/schemas/TaxonomyResource" } } }, "required": [ "limit" ] }, "TaxonomyRequest": { "type": "object", "description": "The request fields to create Taxonomy job.\n\n\nThe `data_reference.type` must be set to `github`.\n", "properties": { "name": { "type": "string", "description": "The name of the document.\n", "minLength": 1, "maxLength": 32, "pattern": "^[a-zA-Z][a-zA-Z-_]*[a-zA-Z]$" }, "description": { "type": "string", "description": "The description of the Taxonomy job." }, "space_id": { "$ref": "#/components/schemas/SpaceId" }, "project_id": { "$ref": "#/components/schemas/ProjectId" }, "data_reference": { "$ref": "#/components/schemas/ObjectLocation" } }, "required": [ "name" ] }, "EvaluationModelConfig": { "type": "object", "description": "Settings related to evaluated foundation model.", "properties": { "model_id": { "type": "string", "description": "The ID of the pre-installed foundation model. Either `model_id` or `deployment_id` parameter has to be given." }, "deployment_id": { "type": "string", "description": "The ID of the deployed foundation model. Either `model_id` or `deployment_id` parameter has to be given." }, "generation_parameters": { "$ref": "#/components/schemas/TextGenParameters" } } }, "EvaluationAcademicTask": { "type": "object", "description": "Definition of industry-based benchmarking task (academic).", "properties": { "name": { "type": "string", "description": "The name of predefined academic (industry) benchmarking task", "example": "bluebench" }, "type": { "type": "string", "description": "Type of benchmarks used.", "enum": [ "academic" ] }, "description": { "type": "string", "description": "Description of benchmarking task", "example": "Bluebench benchmarks for fine-tuned llama model" } }, "required": [ "name", "type" ] }, "BenchmarkingRecord": { "type": "object", "description": "Definition of single benchmarking record.", "properties": { "input": { "type": "string", "description": "Input to the model." }, "output": { "type": "string", "description": "The response to the input." }, "ground_truth": { "type": "array", "description": "Array of Ground-truth responses for the input.", "items": { "type": "string" } }, "contexts": { "type": "array", "description": "Array of the input-output contexts relevant for governance tasks.", "items": { "type": "string" } } }, "required": [ "input", "output" ] }, "EvaluationGovernanceTask": { "type": "object", "description": "Definition of governance benchmarking task.", "properties": { "name": { "type": "string", "description": "The name of predefined governance benchmarking task (extraction, classification, RAG, etc...)", "example": "RAG" }, "type": { "type": "string", "description": "Type of benchmarks used.", "enum": [ "governance" ] }, "description": { "type": "string", "description": "Description of benchmarking task", "example": "RAG governance metrics for my customized RAG Pattern" }, "task_recipe": { "type": "object", "description": "The properties (recipe) of the task", "properties": { "evaluation_data": { "type": "array", "description": "Array of benchmarking records.", "items": { "$ref": "#/components/schemas/BenchmarkingRecord" } }, "evaluation_data_references": { "type": "array", "description": "A set of input data references. The input data reference should point to `json` file containing array of records. Each record should be compliant with the `evaluation_data` record defined above (e.g.: `[{\"input\": \"abc\", \"output\": bcd}, {\"input\": \"123\", \"output\": \"456\"}]`).\n", "items": { "$ref": "#/components/schemas/AutoAIDataLocation" } }, "metrics": { "type": "array", "description": "List of metrics to be calculated (supported by selected task).", "items": { "type": "string", "description": "metric name" }, "example": [ "answer_correctness", "faithfulness" ] } } } }, "required": [ "name", "type", "task_recipe" ] }, "EvaluationCustomTask": { "type": "object", "description": "Definition of custom benchmarking task.", "properties": { "name": { "type": "string", "description": "Name of benchmarking task" }, "type": { "type": "string", "description": "Type of benchmarks used.", "enum": [ "custom" ] }, "description": { "type": "string", "description": "Description of benchmarking task" }, "task_recipe": { "type": "object", "description": "The properties (recipe) of the task", "properties": { "evaluation_data": { "type": "array", "description": "Array of benchmarking records.", "items": { "$ref": "#/components/schemas/BenchmarkingRecord" } }, "evaluation_data_references": { "type": "array", "description": "A set of input data references.\n", "items": { "$ref": "#/components/schemas/AutoAIDataLocation" } }, "card": { "type": "string", "description": "ID of a Unitxt card from the Unitxt catalog." }, "template": { "type": "string", "description": "ID of a Unitxt template from the Unitxt catalog." }, "task": { "type": "string", "description": "ID of a Unitxt task from the Unitxt catalog." }, "system_prompt": { "type": "string", "description": "ID of a Unitxt system prompt from the Unitxt catalog." }, "metrics": { "type": "array", "items": { "type": "string" }, "description": "List of of Unitxt metrics from the Unitxt catalog." }, "format": { "type": "string", "description": "ID of a Unitxt format from the Unitxt catalog." }, "num_demos": { "type": "integer", "description": "Number of fewshot to be used." }, "demos_pool_size": { "type": "integer", "description": "Size of the fewshot pool." } } } }, "required": [ "name", "type", "task_recipe" ] }, "EvaluationTaskConfig": { "type": "object", "description": "Settings related to evaluation job.", "properties": { "tasks": { "type": "array", "description": "The evaluation tasks to be run.", "items": { "oneOf": [ { "$ref": "#/components/schemas/EvaluationAcademicTask" }, { "$ref": "#/components/schemas/EvaluationGovernanceTask" }, { "$ref": "#/components/schemas/EvaluationCustomTask" } ], "discriminator": { "propertyName": "type" } } }, "sample_size": { "type": "integer", "description": "Sample size limit for given tasks." } }, "required": [ "tasks" ] }, "EvaluationRequestEntity": { "type": "object", "description": "The evaluation request entity.\n", "properties": { "model_settings": { "$ref": "#/components/schemas/EvaluationModelConfig" }, "task_settings": { "$ref": "#/components/schemas/EvaluationTaskConfig" } }, "required": [ "task_settings" ] }, "EvaluationTaskBenchmarkMetric": { "type": "object", "description": "The metric for a given property.\n", "properties": { "name": { "type": "string", "description": "The name of the metric.\n", "example": "rougeL" }, "value": { "type": "number", "description": "The mean value calculated over all records in the dataset.\n", "example": 0.3197 }, "max": { "type": "number", "description": "The max value calculated over all records in the dataset.\n", "example": 0.5197 }, "min": { "type": "number", "description": "The min value calculated over all records in the dataset.\n", "example": 0.197 }, "record_level": { "type": "array", "description": "The metric value calculated per each record in the dataset.\n", "items": { "type": "object", "properties": { "value": { "type": "number", "description": "The metric value calculated per single record in the dataset.\n", "example": 0.2197 }, "id": { "type": "string", "description": "The unique identifier of the record.\n", "example": "123456" } } } } }, "required": [ "name", "value" ] }, "EvaluationTaskBenchmark": { "type": "object", "description": "The benchmarking result for this task for this model.\n", "properties": { "type": { "type": "string", "description": "Type of benchmarks used.", "example": "academic" }, "name": { "type": "string", "description": "Name of benchmarks used.", "example": "bluebench" }, "description": { "type": "string", "description": "Description of benchmark used.", "example": "MultiLingual Summarization dataset with 1.5M+ article/summary pairs across five languages. Evaluated using rougeL with 5 shots." }, "language": { "type": "string", "description": "Benchmarked language (multilingual benchmarks). ISO 639 2 letter language code.", "example": "fr" }, "dataset": { "type": "object", "description": "Benchmarking dataset properties.", "properties": { "name": { "type": "string", "description": "The benchmarking dataset name.", "example": "mlsum.de" } } }, "prompt": { "type": "object", "description": "The benchmarking prompt properties.", "properties": { "number_of_shots": { "type": "integer", "example": 5 } } }, "metrics": { "type": "array", "description": "The scores for a given benchmark.\n", "items": { "$ref": "#/components/schemas/EvaluationTaskBenchmarkMetric" } }, "tags": { "$ref": "#/components/schemas/Tags" } } }, "EvaluationResults": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/EvaluationTaskBenchmark" } } } }, "EvaluationStatus": { "type": "object", "description": "Status of the evaluation job.", "properties": { "running_at": { "type": "string", "description": "Date and Time in which current evaluation state has started.", "example": "2017-01-30T10:11:12Z", "format": "date-time" }, "completed_at": { "type": "string", "description": "Date and Time in which evaluation job had completed.", "example": "2017-01-30T10:11:12Z", "format": "date-time" }, "state": { "type": "string", "description": "Current state of evaluation.", "enum": [ "queued", "pending", "running", "completed", "failed", "canceled" ] }, "message": { "$ref": "#/components/schemas/Message" }, "failure": { "$ref": "#/components/schemas/ApiErrorResponse" } }, "required": [ "state" ], "example": { "state": "completed", "running_at": "2023-08-04T13:22:48.000Z", "completed_at": "2023-08-04T13:22:55.289Z", "message": { "level": "info", "text": "Evaluation job 360c40f7-ac0c-43ca-a95f-1a5421f93b82 completed" } } }, "EvaluationResourceEntity": { "allOf": [ { "$ref": "#/components/schemas/EvaluationRequestEntity" }, { "$ref": "#/components/schemas/EvaluationResults" }, { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/EvaluationStatus" } } } ] }, "EvaluationEntity": { "allOf": [ { "$ref": "#/components/schemas/EvaluationResourceEntity" } ] }, "EvaluationResource": { "type": "object", "description": "The response of an AI evaluation job.\n", "properties": { "metadata": { "allOf": [ { "$ref": "#/components/schemas/ResourceMeta" } ], "example": { "id": "6213cf1-252f-424b-b52d-5cdd9814956c", "name": "my-eval-job", "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f", "owner": "guy", "created_at": "2023-08-04T13:22:55.289Z" } }, "entity": { "$ref": "#/components/schemas/EvaluationEntity" }, "system": { "$ref": "#/components/schemas/SystemDetails" } } }, "EvaluationResourceList": { "type": "object", "properties": { "resources": { "type": "array", "items": { "$ref": "#/components/schemas/EvaluationResource" } } } }, "EvaluationResources": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "$ref": "#/components/schemas/EvaluationResourceList" }, { "$ref": "#/components/schemas/System" } ] }, "EvaluationRequest": { "allOf": [ { "$ref": "#/components/schemas/ResourceRequestFields" }, { "$ref": "#/components/schemas/EvaluationRequestEntity" } ] }, "EvaluationResponse": { "type": "object", "description": "The response of an Evaluation job run.\n", "properties": { "metadata": { "$ref": "#/components/schemas/AutoAIRAGMetadata" }, "entity": { "$ref": "#/components/schemas/EvaluationResourceEntity" }, "system": { "$ref": "#/components/schemas/SystemDetails" } } }, "SDGUnstructuredGenerationBaseEntity": { "type": "object", "description": "Common platform parameters for creating an unstructured synthetic data generation job.\n", "properties": { "name": { "type": "string", "description": "The name of the resource.\n", "example": "my-resource", "minLength": 1, "maxLength": 250 }, "description": { "type": "string", "description": "A description of the resource.\n", "example": "This is my first resource.", "maxLength": 1000 } }, "required": [ "name" ] }, "ProjectIdOnly": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "minLength": 36, "maxLength": 36, "description": "The project that contains the resource.\n", "example": "12ac4cf1-252f-424b-b52d-5cdd9814987f" }, "SDGUnstructuredGenerationLLMConfig": { "type": "object", "description": "Data builder configuration.\n", "properties": { "model_id": { "description": "A model from the list of certified models that support unstructured generation. Refer to the product documentation to know the list of certified model IDs.\n", "type": "string", "minLength": 1 }, "min_new_tokens": { "description": "Ensures that the model generates at least the specified number of tokens, which prevents it from stopping too early.\n", "type": "integer", "minimum": 50 }, "max_new_tokens": { "description": "Sets a hard cap on the number of tokens that are generated in one response, which prevents overly-long outputs.\n", "type": "integer", "minimum": 50, "maximum": 1024 }, "temperature": { "description": "Controls the balance between creativity and determinism in text generation. Lower values (≤0.3) make the output more deterministic, focused, and repeatable. Higher values (≥0.7) encourage more diverse and creative responses, but sometimes at the cost of accuracy.\n", "type": "number", "minimum": 0.05, "maximum": 2 }, "top_p": { "description": "Defines the pool of candidate tokens for the next output. The model calculates probabilities for all possible tokens, sorts them, and then selects the smallest set whose cumulative probability is at least p. Higher values for p (0.9) include less-probable tokens, producing more diverse and creative text. You can set any value between 0 and 1.\n", "type": "number", "exclusiveMinimum": true, "minimum": 0, "maximum": 1 }, "top_k": { "description": "Limits the pool of candidate tokens to the k most likely options at each step. For example, k = 50 restricts generation to the 50 most-probable tokens, ignoring the rest. Smaller values generate more predictable output. Larger values increase variety. A midrange value (50) helps to balance diversity and relevance. You can set any value between 1 and 100.\n", "type": "integer", "minimum": 1, "maximum": 100 } } }, "SDGUnstructuredGenerationValidatorRS": { "type": "object", "description": "Validator settings.\n", "properties": { "type": { "type": "string", "enum": [ "rouge_scorer" ] }, "threshold": { "type": "number", "description": "Sets the similarity score that is used to decide when two outputs are considered duplicates. The model uses the Rouge-L scoring method to determine similarity. If set to 0, all QnA pairs are treated as invalid, which produces no output. If set to 1, no duplicates are removed.\n", "exclusiveMinimum": true, "minimum": 0, "maximum": 1 } }, "required": [ "type" ] }, "SDGObjectLocation": { "type": "object", "description": "A reference to data.\n", "properties": { "type": { "description": "The data source type.\n", "type": "string", "enum": [ "container" ] }, "location": { "description": "The location of the data.\n", "properties": { "path": { "type": "string", "description": "The file name of the data.\n" } } } }, "required": [ "type", "location" ] }, "SDGUnstructuredGenerationConfig": { "type": "object", "description": "The details needed to create unstructured synthetic data generation job.\n", "properties": { "configuration": { "properties": { "pipeline": { "type": "string", "description": "The pipeline type.\n", "enum": [ "nl2sql", "tool_calling", "knowledge" ] }, "num_outputs_to_generate": { "type": "integer", "minimum": 1, "description": "How many QnA pairs to generate.\n" }, "generator": { "$ref": "#/components/schemas/SDGUnstructuredGenerationLLMConfig" }, "validators": { "type": "array", "items": { "$ref": "#/components/schemas/SDGUnstructuredGenerationValidatorRS" } }, "seed_data_reference": { "$ref": "#/components/schemas/SDGObjectLocation" }, "results_reference": { "$ref": "#/components/schemas/SDGObjectLocation" }, "knowledge_base_references": { "type": "array", "items": { "$ref": "#/components/schemas/SDGObjectLocation" } }, "overwrite_output_file": { "type": "boolean", "description": "Flag to allow overwriting existing output file. If false or not set, job creation will fail if output file already exists.\n" } }, "required": [ "pipeline", "seed_data_reference", "results_reference" ] } } }, "SDGUnstructuredGenerationRequest-v2": { "allOf": [ { "$ref": "#/components/schemas/SDGUnstructuredGenerationBaseEntity" }, { "type": "object", "properties": { "project_id": { "$ref": "#/components/schemas/ProjectIdOnly" } }, "required": [ "project_id" ] }, { "$ref": "#/components/schemas/SDGUnstructuredGenerationConfig" } ] }, "SDGUnstructuredGenerationResource-v2": { "type": "object", "description": "The response from getting a specified synthetic data generation job.", "properties": { "metadata": { "allOf": [ { "$ref": "#/components/schemas/SimpleRel" }, { "$ref": "#/components/schemas/SDGUnstructuredGenerationBaseEntity" } ] }, "entity": { "$ref": "#/components/schemas/SDGUnstructuredGenerationConfig" } } }, "GPUResource": { "type": "object", "description": "The information for a GPU.\n", "properties": { "gpu_id": { "type": "string", "description": "The id of the GPU.\n", "example": "1l40s-48g" }, "description": { "type": "string", "description": "A description of the GPU.\n", "example": "Single L40S GPU with 48 GB of memory" }, "gpu_type": { "type": "string", "description": "The type of the GPU.\n", "example": "L40S" }, "gpu_count": { "type": "integer", "description": "The number of available GPUs for this GPU.\n", "example": 1 }, "memory_per_unit_gb": { "type": "integer", "description": "The number of GBs per unit of the GPU.\n", "example": 48 }, "total_memory_gb": { "type": "integer", "description": "The total amount of memory of the GPU.\n", "example": 48 }, "price": { "type": "number", "description": "The price of the GPU based on the billing field.\n\nEither `price` or `resource_units` must be provided.\n", "example": 4.43 }, "resource_units": { "type": "number", "description": "The number of resource units for the GPU based on the billing field.\n\nEither `price` or `resource_units` must be provided.\n", "example": 4.43 }, "currency": { "type": "string", "description": "The billing currency.\n", "example": "USD" }, "billing": { "type": "string", "description": "The billing period.\n", "example": "hourly" }, "hardware_spec": { "type": "string", "description": "The associated hardware spec that should be used to get this GPU.\n", "example": "1l40s-48g" } }, "required": [ "gpu_id", "gpu_type", "memory_per_unit_gb", "total_memory_gb", "currency", "billing", "hardware_spec" ] }, "GPUConfigurations": { "type": "object", "description": "Pagination information and list of available GPUs.\n", "properties": { "gpu_configurations": { "type": "array", "description": "A list of available GPUs.\n", "items": { "$ref": "#/components/schemas/GPUResource" } } } }, "GPUResources": { "allOf": [ { "$ref": "#/components/schemas/PaginationBase" }, { "$ref": "#/components/schemas/GPUConfigurations" } ], "description": "A paginated list of available GPUs.\n" }, "TextClassificationDataReference": { "type": "object", "description": "A reference to data.\n", "properties": { "type": { "description": "The data source type.\n", "type": "string", "enum": [ "connection_asset", "container" ] }, "connection": { "$ref": "#/components/schemas/CosDataConnection" }, "location": { "$ref": "#/components/schemas/CosDataLocation" } }, "required": [ "type" ] }, "TextClassificationParameters": { "type": "object", "description": "The parameters for the text extraction.\n", "properties": { "ocr_mode": { "type": "string", "description": "If OCR should be used when processing a document.\nAn empty value allows the service to select the best option for your processing mode.\n- `enabled`: OCR is run on embedded images, OCR is only run if no programmatic text could be extracted from the area.\n- `disabled`: OCR is not run, no information is extracted from images or scanned documents.\n- `forced`: Document processing will take a picture of the page and run OCR across it, this applies to all documents even purely programmatic ones.\n", "enum": [ "disabled", "enabled", "forced" ] }, "classification_mode": { "type": "string", "description": "The classification mode. The value `exact` gives\nthe exact schema name the the document is classified to.\nThe option `binary`` only gives\nwhether the document is classified to a known schema or not.\n", "default": "exact", "enum": [ "exact", "binary" ] }, "auto_rotation_correction": { "type": "boolean", "description": "Should the service attempt to fix a rotated page or image.\n", "default": false }, "languages": { "$ref": "#/components/schemas/TextExtractionLanguagesList" }, "semantic_config": { "$ref": "#/components/schemas/TextExtractionSemanticConfig" } } }, "TextClassificationEntity": { "type": "object", "description": "The parameters for the text classification.\n", "required": [ "document_reference" ], "properties": { "document_reference": { "$ref": "#/components/schemas/TextClassificationDataReference" }, "parameters": { "$ref": "#/components/schemas/TextClassificationParameters" }, "custom": { "$ref": "#/components/schemas/Custom" } } }, "TextClassificationResults": { "type": "object", "description": "The current status of the text extraction.\n", "properties": { "status": { "type": "string", "description": "The status of the request.\n", "enum": [ "submitted", "uploading", "running", "downloading", "downloaded", "completed", "failed" ] }, "running_at": { "type": "string", "format": "date-time", "description": "The time when the request is successfully running on the processor.\n" }, "completed_at": { "type": "string", "format": "date-time", "description": "The time when the request completed or failed.\n" }, "document_classified": { "type": "boolean", "description": "A flag to indicate if the classification was found.\n" }, "document_type": { "type": "string", "description": "The classification of the document if found.\n" }, "error": { "$ref": "#/components/schemas/ServiceError" } }, "required": [ "status" ] }, "TextClassificationResource": { "type": "object", "description": "The text classification resource.\n", "properties": { "metadata": { "$ref": "#/components/schemas/TextExtractionMetadata" }, "entity": { "allOf": [ { "$ref": "#/components/schemas/TextClassificationEntity" }, { "type": "object", "properties": { "results": { "$ref": "#/components/schemas/TextClassificationResults" } }, "required": [ "results" ] } ] } } }, "TextClassificationResources": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "description": "Pagination information and list of resources.\n", "properties": { "resources": { "type": "array", "description": "A list of resources.\n", "items": { "$ref": "#/components/schemas/TextClassificationResource" } } } }, { "$ref": "#/components/schemas/System" } ], "description": "A paginated list of resources.\n" }, "TextClassificationRequest": { "allOf": [ { "$ref": "#/components/schemas/TextClassificationEntity" }, { "$ref": "#/components/schemas/EntityRequestSpaceProjectOnly" } ] }, "TextClassificationResponse": { "type": "object", "description": "The text classification response.\n", "allOf": [ { "$ref": "#/components/schemas/TextClassificationResource" }, { "$ref": "#/components/schemas/System" } ] }, "SchemaSemanticConfig": { "type": "object", "description": "Properties related to semantic config.\n", "properties": { "default_model_name": { "type": "string", "description": "By default, the model documented in [this page](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-api-text-extraction.html?context=wx&audience=wdp) is used.\nThis parameter allows changing the default model to another compatible vision model. A list of compatible vision models is\navailable [here](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-api-text-extraction.html?context=wx&audience=wdp).\n" } } }, "CreateSchemaParameters": { "type": "object", "description": "The parameters for the create schema.\n", "properties": { "mode": { "type": "string", "description": "Which processing mode to use for this request.\n", "enum": [ "standard", "high_quality" ], "default": "standard" }, "ocr_mode": { "type": "string", "description": "If OCR should be used when processing a document. An empty value allows the service to select the best option for your processing mode.\n- `enabled`: OCR is run on embedded images, OCR is only run if no programmatic text could be extracted from the area.\n- `disabled`: OCR is not run, no information is extracted from images or scanned documents.\n- `forced`: WDU will take a picture of the page and run OCR across it, this applies to all documents even purely programmatic ones.", "enum": [ "disabled", "enabled", "forced" ] }, "auto_rotation_correction": { "type": "boolean", "description": "Should the service attempt to fix a rotated page or image.\n", "default": false }, "languages": { "$ref": "#/components/schemas/TextExtractionLanguagesList" }, "additional_prompt_instructions": { "type": "string", "description": "Additional instructions to guide schema creation.\n" }, "enable_grounding": { "type": "boolean", "description": "If we should return grounding data with examples of each field.\n", "default": false }, "max_pages_to_process": { "type": "integer", "description": "How many pages we should create a schema for.\n", "default": 20 }, "semantic_config": { "$ref": "#/components/schemas/SchemaSemanticConfig" } } }, "CreateSchemaEntity": { "type": "object", "description": "The parameters to create schema.\n", "required": [ "document_reference" ], "properties": { "document_reference": { "$ref": "#/components/schemas/TextExtractionDataReference" }, "parameters": { "$ref": "#/components/schemas/CreateSchemaParameters" } } }, "SchemaSemanticKvpField": { "type": "object", "description": "A mapping of fields to identify within the schema, where each key is the short-form name of the field, and the corresponding value is an object is a schema as defined below.\n", "properties": { "description": { "type": "string", "description": "Description of the field to identify.\n" }, "example": { "type": "string", "description": "An example value to help inform the LLM of structure and format.\n" }, "available_options": { "type": "array", "description": "Required for inferred fields to provide the available_options list of values to return from.\n", "items": { "type": "string", "description": "Provide a closed list of valid values to return and reduces the likelihood of model hallucinations.\n" } } }, "required": [ "description", "example" ] }, "TextExtractionBaseSchema": { "type": "object", "description": "Defines the base schema used for Create, Improve, Merge and Cluster Schema operations, containing the core attributes required for Text Extraction workflows.\n", "properties": { "document_type": { "type": "string", "description": "Should be a short one or two word title like Passport or Bill Of Lading.\n" }, "document_description": { "type": "string", "description": "Should be one or two sentences to ensure the LLM gets an accurate understanding.\n" }, "fields": { "$ref": "#/components/schemas/SchemaSemanticKvpField" }, "additional_prompt_instructions": { "type": "string", "description": "Optional, defaults to None. If configured, additional instructions that will be added to the vLLM prompt.\n" } }, "required": [ "document_type", "document_description" ] }, "CreateSchemaResults": { "type": "object", "description": "The current status of the create schema.\n", "properties": { "status": { "type": "string", "description": "The status of the request.\n", "enum": [ "submitted", "uploading", "running", "downloading", "downloaded", "completed", "failed" ] }, "running_at": { "type": "string", "format": "date-time", "description": "The time when the request is successfully running on the processor.\n" }, "completed_at": { "type": "string", "format": "date-time", "description": "The time when the request completed or failed.\n" }, "number_pages_processed": { "type": "integer", "description": "The number of pages that have been processed in the document.\nIf the status is `completed` then this is the number of pages\nthat will be billed.\n" }, "total_pages": { "type": "integer", "description": "The total number of pages to be processed.\n" }, "schema": { "items": { "$ref": "#/components/schemas/TextExtractionBaseSchema" } }, "grounding_hints": { "type": "object", "description": "The grounding hints for each generated field.\n" }, "error": { "$ref": "#/components/schemas/ServiceError" } }, "required": [ "status" ] }, "CreateSchemaResource": { "type": "object", "description": "The create schema resource.\n", "properties": { "metadata": { "$ref": "#/components/schemas/TextExtractionMetadata" }, "entity": { "allOf": [ { "$ref": "#/components/schemas/CreateSchemaEntity" }, { "type": "object", "properties": { "results": { "$ref": "#/components/schemas/CreateSchemaResults" } }, "required": [ "results" ] } ] } } }, "CreateSchemaResources": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "description": "Pagination information and list of resources.\n", "properties": { "resources": { "type": "array", "description": "A list of resources.\n", "items": { "$ref": "#/components/schemas/CreateSchemaResource" } } } }, { "$ref": "#/components/schemas/System" } ], "description": "A paginated list of resources.\n" }, "CreateSchemaRequest": { "allOf": [ { "$ref": "#/components/schemas/CreateSchemaEntity" }, { "$ref": "#/components/schemas/EntityRequestSpaceProjectOnly" } ] }, "CreateSchemaResponse": { "type": "object", "description": "The text create schema response.\n", "allOf": [ { "$ref": "#/components/schemas/CreateSchemaResource" }, { "$ref": "#/components/schemas/System" } ] }, "CustomSchema": { "type": "object", "description": "A custom input schema given by the user.\n", "properties": { "document_type": { "type": "string", "description": "Should be a short one or two word title like Passport or Bill Of Lading.\n" }, "document_description": { "type": "string", "description": "Should be one or two sentences to ensure the LLM gets an accurate understanding.\n" }, "fields": { "$ref": "#/components/schemas/TextExtractionSemanticKvpField" }, "additional_prompt_instructions": { "type": "string", "description": "Optional, defaults to None. If configured, additional instructions that will be added to the vLLM prompt.\n" } }, "required": [ "document_type", "document_description" ] }, "ImproveSchemaParameters": { "type": "object", "description": "The parameters to improve schema.\n", "required": [ "schema" ], "properties": { "schema": { "$ref": "#/components/schemas/CustomSchema" }, "semantic_config": { "$ref": "#/components/schemas/SchemaSemanticConfig" } } }, "ImproveSchemaEntity": { "type": "object", "description": "The parameters to improve schema.\n", "required": [ "parameters" ], "properties": { "parameters": { "$ref": "#/components/schemas/ImproveSchemaParameters" } } }, "ImproveSchemaResults": { "type": "object", "description": "The current status of the improve schema.\n", "properties": { "status": { "type": "string", "description": "The status of the request.\n", "enum": [ "submitted", "running", "completed", "failed" ] }, "running_at": { "type": "string", "format": "date-time", "description": "The time when the request is successfully running on the processor.\n" }, "completed_at": { "type": "string", "format": "date-time", "description": "The time when the request completed or failed.\n" }, "schema": { "items": { "$ref": "#/components/schemas/TextExtractionBaseSchema" } }, "grounding_hints": { "type": "object", "description": "The grounding hints for each generated field.\n" }, "error": { "$ref": "#/components/schemas/ServiceError" } }, "required": [ "status" ] }, "ImproveSchemaResource": { "type": "object", "description": "The improve schema resource.\n", "properties": { "metadata": { "$ref": "#/components/schemas/TextExtractionMetadata" }, "entity": { "allOf": [ { "$ref": "#/components/schemas/ImproveSchemaEntity" }, { "type": "object", "properties": { "results": { "$ref": "#/components/schemas/ImproveSchemaResults" } }, "required": [ "results" ] } ] } } }, "ImproveSchemaResources": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "description": "Pagination information and list of resources.\n", "properties": { "resources": { "type": "array", "description": "A list of resources.\n", "items": { "$ref": "#/components/schemas/ImproveSchemaResource" } } } }, { "$ref": "#/components/schemas/System" } ], "description": "A paginated list of resources.\n" }, "ImproveSchemaRequest": { "allOf": [ { "$ref": "#/components/schemas/ImproveSchemaEntity" }, { "$ref": "#/components/schemas/EntityRequestSpaceProjectOnly" } ] }, "ImproveSchemaResponse": { "type": "object", "description": "The text create schema response.\n", "allOf": [ { "$ref": "#/components/schemas/ImproveSchemaResource" }, { "$ref": "#/components/schemas/System" } ] }, "MergeSchemaParameters": { "type": "object", "description": "The parameters to merge schema.\n", "required": [ "schemas" ], "properties": { "schemas": { "type": "array", "description": "A list of input schemas.\n", "items": { "$ref": "#/components/schemas/CustomSchema" } }, "semantic_config": { "$ref": "#/components/schemas/SchemaSemanticConfig" } } }, "MergeSchemaEntity": { "type": "object", "description": "The parameters to merge schema.\n", "required": [ "parameters" ], "properties": { "parameters": { "$ref": "#/components/schemas/MergeSchemaParameters" } } }, "MergeSchemaResults": { "type": "object", "description": "The current status of the text extraction.\n", "properties": { "status": { "type": "string", "description": "The status of the request.\n", "enum": [ "submitted", "running", "completed", "failed" ] }, "running_at": { "type": "string", "format": "date-time", "description": "The time when the request is successfully running on the processor.\n" }, "completed_at": { "type": "string", "format": "date-time", "description": "The time when the request completed or failed.\n" }, "schema": { "$ref": "#/components/schemas/TextExtractionBaseSchema" }, "error": { "$ref": "#/components/schemas/ServiceError" } }, "required": [ "status" ] }, "MergeSchemaResource": { "type": "object", "description": "The merge schema resource.\n", "properties": { "metadata": { "$ref": "#/components/schemas/TextExtractionMetadata" }, "entity": { "allOf": [ { "$ref": "#/components/schemas/MergeSchemaEntity" }, { "type": "object", "properties": { "results": { "$ref": "#/components/schemas/MergeSchemaResults" } }, "required": [ "results" ] } ] } } }, "MergeSchemaResources": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "description": "Pagination information and list of resources.\n", "properties": { "resources": { "type": "array", "description": "A list of resources.\n", "items": { "$ref": "#/components/schemas/MergeSchemaResource" } } } }, { "$ref": "#/components/schemas/System" } ], "description": "A paginated list of resources.\n" }, "MergeSchemaRequest": { "allOf": [ { "$ref": "#/components/schemas/MergeSchemaEntity" }, { "$ref": "#/components/schemas/EntityRequestSpaceProjectOnly" } ] }, "MergeSchemaResponse": { "type": "object", "description": "The text merge schema response.\n", "allOf": [ { "$ref": "#/components/schemas/MergeSchemaResource" }, { "$ref": "#/components/schemas/System" } ] }, "ClusterSchemas": { "type": "object", "description": "Represents a single document schema entry for clustering.\n", "properties": { "document_name": { "type": "string", "description": "Unique name to define the document.\n" }, "schema": { "$ref": "#/components/schemas/CustomSchema" } }, "required": [ "document_name", "schema" ] }, "ClusterSchemaParameters": { "type": "object", "description": "The parameters to cluster schemas.\n", "required": [ "schemas" ], "properties": { "schemas": { "type": "array", "description": "A list of document schemas.\n", "items": { "$ref": "#/components/schemas/ClusterSchemas" } }, "semantic_config": { "$ref": "#/components/schemas/SchemaSemanticConfig" } } }, "ClusterSchemaEntity": { "type": "object", "description": "The parameters to cluster schema.\n", "required": [ "parameters" ], "properties": { "parameters": { "$ref": "#/components/schemas/ClusterSchemaParameters" } } }, "ClusterSchemaResults": { "type": "object", "description": "The current status of the text extraction.\n", "properties": { "status": { "type": "string", "description": "The status of the request.\n", "enum": [ "submitted", "completed", "running", "failed" ] }, "running_at": { "type": "string", "format": "date-time", "description": "The time when the request started processing.\n" }, "completed_at": { "type": "string", "format": "date-time", "description": "The time when the request completed or failed.\n" }, "schemas": { "type": "array", "description": "Schemas after getting clustered.\n", "items": { "type": "array", "description": "A group of clustered document schemas.\n", "items": { "type": "object", "description": "Represents one document schema in a cluster.\n", "properties": { "document_name": { "type": "string", "description": "Unique document name.\n" }, "schema": { "items": { "$ref": "#/components/schemas/TextExtractionBaseSchema" } } }, "required": [ "document_name", "schema" ] } } }, "error": { "$ref": "#/components/schemas/ServiceError" } }, "required": [ "status" ] }, "ClusterSchemaResource": { "type": "object", "description": "The cluster schema resource.\n", "properties": { "metadata": { "$ref": "#/components/schemas/TextExtractionMetadata" }, "entity": { "allOf": [ { "$ref": "#/components/schemas/ClusterSchemaEntity" }, { "type": "object", "properties": { "results": { "$ref": "#/components/schemas/ClusterSchemaResults" } }, "required": [ "results" ] } ] } } }, "ClusterSchemaResources": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "description": "Pagination information and list of resources.\n", "properties": { "resources": { "type": "array", "description": "A list of resources.\n", "items": { "$ref": "#/components/schemas/ClusterSchemaResource" } } } }, { "$ref": "#/components/schemas/System" } ], "description": "A paginated list of resources.\n" }, "ClusterSchemaRequest": { "allOf": [ { "$ref": "#/components/schemas/ClusterSchemaEntity" }, { "$ref": "#/components/schemas/EntityRequestSpaceProjectOnly" } ] }, "ClusterSchemaResponse": { "type": "object", "description": "The text create schema response.\n", "allOf": [ { "$ref": "#/components/schemas/ClusterSchemaResource" }, { "$ref": "#/components/schemas/System" } ] }, "AudioResponseFormat": { "type": "string", "description": "Specify the format of the audio data being generated.\nFor OpenAI, supported formats are `\"mp3\"`, `\"opus\"`, `\"aac\"`, `\"flac\"`, `\"wav\"`, and `\"pcm\"`.", "enum": [ "mp3", "opus", "aac", "flac", "wav", "pcm" ], "default": "mp3", "example": "wav", "x-enum-varnames": [ "ResponseFormatMP3", "ResponseFormatOpus", "ResponseFormatAAC", "ResponseFormatFLAC", "ResponseFormatWAV", "ResponseFormatPCM" ] }, "AudioStreamFormat": { "type": "string", "description": "The format to stream the audio in. Supported formats are `\"sse\"` and `\"audio\"`.\n`\"sse\"` is not supported for OpenAI's `tts-1` or `tts-1-hd` models.", "enum": [ "sse", "audio" ], "default": "audio", "example": "sse", "x-enum-varnames": [ "StreamFormatSSE", "StreamFormatAudio" ] }, "AudioVoice": { "type": "string", "description": "The voice to use when generating the audio.\nFor OpenAI, supported voices are `\"alloy\"`, `\"ash\"`, `\"ballad\"`, `\"coral\"`, `\"echo\"`, `\"fable\"`, `\"onyx\"`, `\"nova\"`, `\"sage\"`, `\"shimmer\"`, and `\"verse\"`.\nPreviews of supported voices for OpenAI are available in their [Text to speech guide].\n\n[Text to speech guide]: https://platform.openai.com/docs/guides/text-to-speech#voice-options", "enum": [ "alloy", "ash", "ballad", "coral", "echo", "fable", "onyx", "nova", "sage", "shimmer", "verse" ], "example": "alloy", "x-enum-varnames": [ "VoiceAlloy", "VoiceAsh", "VoiceBallad", "VoiceCoral", "VoiceEcho", "VoiceFable", "VoiceOnyx", "VoiceNova", "VoiceSage", "VoiceShimmer", "VoiceVerse" ] }, "CreateSpeechRequest": { "type": "object", "description": "Request body for creating speech from text", "required": [ "input", "model", "voice" ], "properties": { "input": { "type": "string", "description": "The text to generate audio for. The maximum length is 4096 characters.", "maxLength": 4096, "example": "Some input text" }, "instructions": { "type": "string", "description": "Control the voice of your generated audio with additional instructions.\nFor OpenAI, does not work with `tts-1` or `tts-1-hd`.", "example": "Answer in a deep monotone voice" }, "model": { "type": "string", "description": "The ID or alias of the model to use for speech generation.\nFor OpenAI, one of the available TTS models: `tts-1`, `tts-1-hd` or `gpt-4o-mini-tts`.", "example": "tts-1" }, "response_format": { "$ref": "#/components/schemas/AudioResponseFormat" }, "speed": { "type": "number", "description": "The speed of the generated audio. Select a value from `0.25` to `4.0`. `1.0` is the default.", "default": 1, "maximum": 4, "minimum": 0.25, "example": 0.5 }, "stream_format": { "$ref": "#/components/schemas/AudioStreamFormat" }, "voice": { "$ref": "#/components/schemas/AudioVoice" } } }, "ErrorDetail": { "type": "object", "description": "Error message details.", "properties": { "code": { "type": "string", "description": "The error code as a string.", "example": "429" }, "message": { "type": "string", "description": "The error message.", "example": "Rate limit reached for requests." }, "param": { "type": "string", "description": "The erroneous request parameter, if any.", "example": "role" }, "type": { "type": "string", "description": "Type descriptor classifying the error's kind.", "example": "invalid request error" } } }, "MGErrorResponse": { "type": "object", "description": "Error message response", "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail" }, "trace": { "type": "string", "description": "The error trace." } } }, "ChatsTextContentPart": { "type": "object", "description": "A part of the content of a message that contains text.", "properties": { "text": { "type": "string", "description": "The text content for this part of the message.", "example": "This is some text part of a message." }, "type": { "type": "string", "description": "The type of the content part, in this case should always be `\"text\"`.", "enum": [ "text" ], "example": "text" } }, "required": [ "type", "text" ] }, "ChatsDeveloperContentPart": { "type": "object", "description": "A part of the content for a developer chat message.", "oneOf": [ { "$ref": "#/components/schemas/ChatsTextContentPart" } ] }, "ChatsDeveloperContent": { "description": "The content of a chat message with the `\"developer\"` role.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/ChatsDeveloperContentPart" } } ] }, "ChatsDeveloperMessage": { "type": "object", "description": "A message with the `\"developer\"` role. Contains developer-provided instructions that the model should follow, regardless of messages sent by the user. With OpenAI `o1` models and newer, `\"developer\"` messages replaces the previous `\"system\"` messages.", "properties": { "role": { "type": "string", "description": "The role of the message's author, in this case should always be `\"developer\"`.\nNote that this parameter is case sensitive, make sure to use lower case.\n", "enum": [ "developer" ] }, "content": { "$ref": "#/components/schemas/ChatsDeveloperContent" }, "name": { "type": "string", "description": "A name for the participant. Provides the model information to differentiate between participants of the same role.", "example": "my-username" } }, "required": [ "role", "content" ] }, "ChatsSystemContentPart": { "type": "object", "description": "A part of the content for a system message.", "oneOf": [ { "$ref": "#/components/schemas/ChatsTextContentPart" } ] }, "ChatsSystemContent": { "description": "The content of a chat message with the `\"system\"` role.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/ChatsSystemContentPart" } } ] }, "ChatsSystemMessage": { "type": "object", "description": "A message with the `\"system\"` role. Contains developer-provided instructions that the model should follow, regardless of messages sent by the user. With OpenAI `o1` models and newer, use `\"developer\"` messages for this purpose instead.", "properties": { "role": { "type": "string", "description": "The role of the messages author, in this case should always be `\"system\"`.\nNote that this parameter is case sensitive, make sure to use lower case.\n", "enum": [ "system" ], "example": "system" }, "content": { "$ref": "#/components/schemas/ChatsSystemContent" }, "name": { "type": "string", "description": "A name for the participant. Provides the model information to differentiate between participants of the same role.", "example": "John" } }, "required": [ "role", "content" ] }, "ChatsImageURLDetail": { "type": "string", "description": "Detail specifies the detail level of an image.\n\nSee [OpenAI's Vision guide](https://platform.openai.com/docs/guides/vision#low-or-high-fidelity-image-understanding) for more information.", "enum": [ "auto", "low", "high" ], "default": "auto", "example": "high", "x-enum-varnames": [ "ImageURLDetailAuto", "ImageURLDetailLow", "ImageURLDetailHigh" ] }, "ChatsImageURL": { "type": "object", "description": "The URL of an image.", "properties": { "url": { "type": "string", "description": "URL is either a URL of the image or the base64 encoded image data.", "example": "https://some/image/url" }, "detail": { "$ref": "#/components/schemas/ChatsImageURLDetail" } }, "required": [ "url" ] }, "ChatsImageContentPart": { "type": "object", "description": "Part of a message's content that contains an image.", "properties": { "type": { "type": "string", "description": "The type of the content part, in this case should always be `\"image_url\"`.", "enum": [ "image_url" ], "example": "image_url" }, "image_url": { "$ref": "#/components/schemas/ChatsImageURL" } }, "required": [ "type", "image_url" ] }, "ChatsAudioInputFormat": { "type": "string", "description": "The format of the encoded audio data. Currently supports `\"wav\"` and `\"mp3\"`.", "enum": [ "wav", "mp3" ], "x-enum-varnames": [ "AudioInputFormatWAV", "AudioInputFormatMp3" ] }, "ChatsInputAudio": { "type": "object", "description": "The audio input for an audio content part.", "properties": { "data": { "type": "string", "description": "The base64 encoded audio data.", "example": "SGVsbG8sIHdvcmxkIS==" }, "format": { "$ref": "#/components/schemas/ChatsAudioInputFormat" } }, "required": [ "data", "format" ] }, "ChatsAudioContentPart": { "type": "object", "description": "A part of the contents of chat message that contains audio.", "properties": { "type": { "type": "string", "description": "The type of the content part, in this case should always be `\"input_audio\"`.", "enum": [ "input_audio" ], "example": "input_audio" }, "input_audio": { "$ref": "#/components/schemas/ChatsInputAudio" } }, "required": [ "type", "input_audio" ] }, "ChatsUserContentPart": { "type": "object", "description": "A part of the content of a user chat message.", "oneOf": [ { "$ref": "#/components/schemas/ChatsTextContentPart" }, { "$ref": "#/components/schemas/ChatsImageContentPart" }, { "$ref": "#/components/schemas/ChatsAudioContentPart" } ] }, "ChatsUserContent": { "description": "The content of a chat message with the `\"user\"` role.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/ChatsUserContentPart" } } ] }, "ChatsUserMessage": { "type": "object", "description": "A message with the `\"user\"` role. User messages are sent by an end user, containing prompts or additional context information.", "properties": { "role": { "type": "string", "description": "The role of the messages author, in this case should always be `\"user\"`.\nNote that this parameter is case sensitive, make sure to use lower case.\n", "enum": [ "user" ], "example": "user" }, "content": { "$ref": "#/components/schemas/ChatsUserContent" }, "name": { "type": "string", "description": "A name for the participant. Provides the model information to differentiate between participants of the same role.", "example": "my-username" } }, "required": [ "role", "content" ] }, "ChatsRefusalContentPart": { "type": "object", "description": "A part of the content of a message that contains a refusal.", "properties": { "type": { "type": "string", "description": "The type of the content part, in this case should always be `\"refusal\"`.", "enum": [ "refusal" ], "example": "refusal" }, "refusal": { "type": "string", "description": "The refusal message generated by the model.", "example": "I'm sorry, I cannot assist with that request." } }, "required": [ "type", "refusal" ] }, "ChatsAssistantContentPart": { "type": "object", "description": "A part of the content of an assistant chat message.", "oneOf": [ { "$ref": "#/components/schemas/ChatsTextContentPart" }, { "$ref": "#/components/schemas/ChatsRefusalContentPart" } ] }, "ChatsAssistantContent": { "description": "The content of a chat message with the `\"assistant\"` role. Required unless `tool_calls` or `function_call` are specified.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/ChatsAssistantContentPart" } } ] }, "ChatsAssistantAudio": { "type": "object", "description": "Data about a previous audio response from the model.", "properties": { "id": { "type": "string", "description": "The unique identifier of a previous audio response from the model.", "example": "audio_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b" } }, "required": [ "id" ] }, "FunctionCall": { "type": "object", "description": "The name and arguments of a function that should be called, as generated by the model.\n\nDeprecated: `function_call` has been deprecated by OpenAI and replaced by `tool_calls`.", "properties": { "name": { "type": "string", "description": "The name of the function to call.", "example": "my-function" }, "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.", "example": "{\"location\":\"Paris, France\"}" } }, "required": [ "name", "arguments" ] }, "ChatsToolCall": { "type": "object", "description": "A function tool call in a chat request.", "properties": { "id": { "type": "string", "description": "A unique identifier of the tool call.", "example": "call_9876abc" }, "type": { "type": "string", "description": "The type of the tool. Currently, only `\"function\"` is supported.", "enum": [ "function" ], "example": "function" }, "function": { "$ref": "#/components/schemas/FunctionCall" } }, "required": [ "id", "type", "function" ] }, "ChatsAssistantMessage": { "type": "object", "description": "A message with the `\"assistant\"` role. Assistant messages are sent by the model in response to user messages.", "properties": { "role": { "type": "string", "description": "The role of the message's author, in this case should always be `\"assistant\"`.\nNote that this parameter is case sensitive, make sure to use lower case.\n", "enum": [ "assistant" ], "example": "assistant" }, "content": { "$ref": "#/components/schemas/ChatsAssistantContent" }, "name": { "type": "string", "description": "A name for the participant. Provides the model information to differentiate between participants of the same role.", "example": "my-name" }, "audio": { "$ref": "#/components/schemas/ChatsAssistantAudio" }, "refusal": { "type": "string", "description": "A refusal message by the assistant.", "example": "refusal text" }, "function_call": { "$ref": "#/components/schemas/FunctionCall" }, "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ChatsToolCall" }, "description": "An array of tool calls generated by the model, such as function calls.", "minItems": 0, "maxItems": 128 } }, "required": [ "role" ] }, "ChatsToolContentPart": { "type": "object", "description": "A part of the content of a tool chat message. Currently only supports `\"text\"`.", "oneOf": [ { "$ref": "#/components/schemas/ChatsTextContentPart" } ] }, "ChatsToolContent": { "type": "string", "description": "The content of a chat message with the `\"tool\"` role.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/ChatsToolContentPart" } } ] }, "ChatsToolMessage": { "type": "object", "description": "A message with the `\"tool\"` role. Tool messages are sent by the model in response to a tool call in a user request.", "properties": { "role": { "type": "string", "enum": [ "tool" ], "description": "The role of the messages author, in this case should always be `\"tool\"`.\nNote that this parameter is case sensitive, make sure to use lower case.\n", "example": "tool" }, "content": { "$ref": "#/components/schemas/ChatsToolContent" }, "tool_call_id": { "type": "string", "description": "The unique identifier of the tool call that this message is responding to.", "example": "call_JIdwa8wJw7Hw8ssj3sawjJ4k" } }, "required": [ "role", "content", "tool_call_id" ] }, "ChatsFunctionMessage": { "type": "object", "description": "A message with the `\"function\"` role. Function messages are sent by the model in response to a function call in a user request.\n\nDeprecated: Function messages have been deprecated by OpenAI in favor of tool messages.", "properties": { "role": { "type": "string", "description": "The role of the messages author, in this case should always be \"function\".\nNote that this parameter is case sensitive, make sure to use lower case.\n", "enum": [ "function" ], "example": "function" }, "content": { "type": "string", "description": "The content of the function message.", "example": "Some function message string content" }, "name": { "type": "string", "description": "The name of the function to call.", "example": "myFunc" } }, "required": [ "role", "content", "name" ] }, "ChatsMessage": { "description": "A message of a supported type for a chat completion.", "oneOf": [ { "$ref": "#/components/schemas/ChatsDeveloperMessage" }, { "$ref": "#/components/schemas/ChatsSystemMessage" }, { "$ref": "#/components/schemas/ChatsUserMessage" }, { "$ref": "#/components/schemas/ChatsAssistantMessage" }, { "$ref": "#/components/schemas/ChatsToolMessage" }, { "$ref": "#/components/schemas/ChatsFunctionMessage" } ] }, "ChatsFunctionMode": { "type": "string", "description": "Controls which (if any) function is called by the model.\n - `\"none\"` means the model will not call a function and instead generates a message.\n - `\"auto\"` means the model can pick between generating a message or calling a function.\n\n `\"none\"` is the default when no functions are present. `\"auto\"` is the default if functions are present.", "enum": [ "none", "auto" ], "example": "auto" }, "ChatsFunctionCall": { "description": "Controls which (if any) function is called by the model.\n- `\"none\"` means the model will not call a function and instead generates a message.\n- `\"auto\"` means the model can pick between generating a message or calling a function.\n- Specifying a particular function via `{\"name\": \"my_function\"}` forces the model to call that function.\n\n`\"none\"` is the default when no functions are present. `\"auto\"` is the default if functions are present.\n\nDeprecated: `function_call` has been deprecated by OpenAI in favor of `tool_choice`.", "oneOf": [ { "$ref": "#/components/schemas/FunctionCall" }, { "$ref": "#/components/schemas/ChatsFunctionMode" } ] }, "ChatsMetadata": { "type": "object", "description": "Contains developer-defined tags and values used for filtering completions.", "additionalProperties": { "type": "string" }, "example": { "customer_id": "user_123456789" } }, "ChatsPredictionContentPart": { "type": "object", "description": "A part of the content of a message that contains a prediction.", "oneOf": [ { "$ref": "#/components/schemas/ChatsTextContentPart" } ] }, "ChatsPredictionContent": { "description": "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" }, { "type": "array", "items": { "$ref": "#/components/schemas/ChatsPredictionContentPart" } } ] }, "ChatsPrediction": { "type": "object", "description": "The configuration for a [Predicted Output], which can greatly improve response times when\nlarge parts of the model response are known ahead of time.\nThis is most common when you are regenerating a file with only minor changes to most of the content.\n\n[Predicted Output]: https://platform.openai.com/docs/guides/predicted-outputs", "properties": { "type": { "type": "string", "enum": [ "content" ], "description": "Type of predicted content you want to provide, should always be `\"content\"`.", "example": "content" }, "content": { "$ref": "#/components/schemas/ChatsPredictionContent" } }, "required": [ "type", "content" ] }, "ChatsReasoningEffort": { "type": "string", "description": "Constrains effort on reasoning for reasoning models. For OpenAI, currently supported by `o1` models only. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response.", "enum": [ "low", "medium", "high" ], "default": "medium", "x-enum-varnames": [ "ReasoningEffortLow", "ReasoningEffortMedium", "ReasoningEffortHigh" ], "example": "high" }, "ChatsResponseFormatText": { "type": "object", "description": "Represents text format for a chat response.", "properties": { "type": { "type": "string", "description": "The type of the response format, in this case should always be `\"text\"`.", "enum": [ "text" ], "example": "text" } }, "required": [ "type" ] }, "ChatsResponseFormatJSON": { "type": "object", "description": "Represents JSON format for a chat response.", "properties": { "type": { "type": "string", "description": "The type of the response format, in this case should always be `\"json_object\"`.", "enum": [ "json_object" ], "example": "json_object" } }, "required": [ "type" ] }, "ChatsJSONSchema": { "type": "object", "description": "The custom schema used to generate structures JSON responses.", "properties": { "name": { "type": "string", "description": "Name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.", "pattern": "^[a-zA-Z0-9\\-_]*$", "maxLength": 64, "example": "my-username" }, "description": { "type": "string", "description": "A custom description of what the response format is for. Used by the model to determine how to respond in the format.", "example": "Some schema description text." }, "schema": { "type": "object", "description": "Schema for the response format, described as a JSON Schema object.\n\nSee [JSON Schema](https://json-schema.org/) for more information.", "additionalProperties": { "type": "string" } }, "strict": { "type": "boolean", "description": "Indicates 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`.", "default": false, "example": true } }, "required": [ "name" ] }, "ChatsResponseFormatJSONSchema": { "type": "object", "description": "Represents custom JSON schema format for a chat response.", "properties": { "type": { "type": "string", "description": "The type of the response format, in this case should always be `\"json_schema\"`.", "enum": [ "json_schema" ], "example": "json_schema" }, "json_schema": { "$ref": "#/components/schemas/ChatsJSONSchema" } }, "required": [ "type", "json_schema" ] }, "ChatsResponseFormat": { "type": "object", "description": "An object specifying the format that the model must output.\n- Setting to `{ \"type\": \"json_schema\", \"json_schema\": {...} }` enables [Structured Outputs] which ensures the model will match your supplied JSON schema.\n- Setting to `{ \"type\": \"json_object\" }` enables JSON mode, which ensures the message the model generates is valid JSON.\n\nImportant: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message.\nWithout this, the model may generate an unending stream of whitespace until the generation reaches the token limit,\nresulting in a long-running and seemingly \"stuck\" request. Also note that the message content may be partially\ncut off if `\"finish_reason\"` is set to `\"length\"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length.\n\n[Structured Outputs]: https://platform.openai.com/docs/guides/structured-outputs", "oneOf": [ { "$ref": "#/components/schemas/ChatsResponseFormatText" }, { "$ref": "#/components/schemas/ChatsResponseFormatJSON" }, { "$ref": "#/components/schemas/ChatsResponseFormatJSONSchema" } ] }, "ChatsServiceTier": { "type": "string", "description": "The service tier used for processing a request.", "enum": [ "auto", "default", "flex", "priority" ], "default": "auto", "example": "auto" }, "ChatsStop": { "description": "Specifies up to 4 sequences where the API will stop generating further tokens.", "oneOf": [ { "type": "string", "default": "<|endoftext|>", "example": "\n" }, { "type": "array", "minItems": 1, "maxItems": 4, "items": { "type": "string" }, "example": [ "\n", "EOL" ] } ] }, "StreamOptions": { "type": "object", "description": "Options for streaming response. Only set this when you set `stream` to `true`.", "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.", "default": false, "example": true } } }, "ChatsToolChoiceString": { "type": "string", "description": "A string tool choice message in a chat request.", "enum": [ "none", "auto", "required" ], "x-enum-varnames": [ "ToolChoiceStringNone", "ToolChoiceStringAuto", "ToolChoiceStringRequired" ] }, "ChatsRequestToolChoiceFunction": { "type": "object", "description": "Function to call for a tool choice.", "properties": { "name": { "type": "string", "description": "Name of the function.", "example": "myToolFunction" } }, "required": [ "name" ] }, "ChatsRequestTool": { "type": "object", "description": "A tool that can be called by models.", "properties": { "type": { "type": "string", "description": "Type of the tool. Currently, only `\"function\"` is supported.", "enum": [ "function" ], "example": "function" }, "function": { "$ref": "#/components/schemas/ChatsRequestToolChoiceFunction" } }, "required": [ "type", "function" ] }, "ChatsToolChoice": { "description": "Controls which (if any) tool is called by the model.\n- `\"none\"` means the model will not call any tool and instead generates a message.\n- `\"auto\"` means the model can pick between generating a message or calling one or more tools.\n- `\"required\"` means the model must call one or more tools.\n- Specifying a particular tool via `{\"type\": \"function\", \"function\": {\"name\": \"my_function\"}}` forces the model to call that tool.\n\n`\"none\"` is the default when no tools are present. `\"auto\"` is the default if tools are present.", "oneOf": [ { "$ref": "#/components/schemas/ChatsToolChoiceString" }, { "$ref": "#/components/schemas/ChatsRequestTool" } ] }, "ChatsCache": { "type": "object", "description": "Contains the caching configuration for a request. Cache is only supported for non-streaming requests.", "properties": { "enabled": { "type": "boolean", "description": "Specifies whether to enable caching for the current request.", "default": false, "example": true }, "filter": { "type": "object", "description": "The filter criteria for caching.", "additionalProperties": { "type": "string" } }, "threshold": { "type": "number", "description": "The threshold for caching the request; required if cache is enabled.", "example": 0.5 } } }, "CreateChatsRequest": { "type": "object", "description": "A request to a model to generate chat completion(s).", "properties": { "model": { "description": "The ID or alias of the model to forward the chat request to.", "type": "string", "example": "gpt-4o" }, "messages": { "type": "array", "description": "A list of messages comprising the chat conversation so far. Depending on the model you use, different message types (modalities) are supported, like `\"text\"`, `\"images\"`, and `\"audio\"`.", "items": { "$ref": "#/components/schemas/ChatsMessage" }, "minItems": 1, "maxItems": 100 }, "audio": { "type": "object", "description": "Parameters for audio output.\nOnly required when audio output is requested with modalities: `[\"audio\"]`.\n\nSee: [OpenAI's Audio Guide](https://platform.openai.com/docs/guides/audio) for more information.", "additionalProperties": { "type": "string" } }, "frequency_penalty": { "type": "number", "description": "A 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.", "maximum": 2, "minimum": -2, "default": 0, "example": 0.4 }, "function_call": { "$ref": "#/components/schemas/ChatsFunctionCall" }, "functions": { "type": "object", "description": "A list of functions the model may generate JSON inputs for.\n\nDeprecated: `functions` has been deprecated by OpenAI in favor of `tools`.", "additionalProperties": { "type": "string" } }, "logit_bias": { "type": "object", "description": "Modifies 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.", "additionalProperties": { "type": "integer", "format": "int64", "minimum": -100, "maximum": 100, "example": 50 } }, "logprobs": { "type": "boolean", "description": "Indicates 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.", "default": false, "example": true }, "max_completion_tokens": { "type": "integer", "description": "Specifies an upper bound for the number of tokens that can be generated for a completion,\nincluding visible output tokens and [reasoning tokens].\n\n[reasoning tokens]: https://platform.openai.com/docs/guides/reasoning", "format": "int64", "minimum": 0, "maximum": 4096, "example": 1000 }, "max_tokens": { "type": "integer", "description": "Specifies a maximum number of tokens that can be generated in the chat completion.\nThis value can be used to control costs for text generated via API.\n\nDeprecated: `max_tokens` has been deprecated by OpenAI in favor of `max_completion_tokens`, and is not compatible with `o1` series models.", "format": "int64", "minimum": 0, "maximum": 4096, "example": 1000 }, "metadata": { "$ref": "#/components/schemas/ChatsMetadata" }, "modalities": { "type": "array", "description": "Specifies the output types that you would like the model to generate for this request.\nMost models are capable of generating text, which is the default (`[\"text\"]`).\nSome models can generate audio. For OpenAI, the `gpt-4o-audio-preview` model can be used to [generate audio].\nTo request that this model generate both text and audio responses, you can use `[\"text\", \"audio\"]`.\n\n[generate audio]: https://platform.openai.com/docs/guides/audio", "items": { "type": "string" }, "minItems": 1, "maxItems": 2, "default": [ "text" ], "example": [ "text", "audio" ] }, "n": { "type": "integer", "description": "Specifies how many chat completion choices to generate for each input message.\n\nNote: you will be charged based on the number of generated tokens across all choices, keep `\"n\"` set to `1` to minimize costs.", "format": "int32", "minimum": 1, "maximum": 128, "default": 1, "example": 3 }, "parallel_tool_calls": { "type": "boolean", "description": "Specifies whether to enable parallel function calling during tool use.", "default": true, "example": true }, "prediction": { "$ref": "#/components/schemas/ChatsPrediction" }, "presence_penalty": { "type": "number", "description": "A 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.", "minimum": -2, "maximum": 2, "default": 0, "example": 0.4 }, "reasoning_effort": { "$ref": "#/components/schemas/ChatsReasoningEffort" }, "response_format": { "$ref": "#/components/schemas/ChatsResponseFormat" }, "seed": { "type": "integer", "description": "The seed for the model request. For OpenAI, this feature is in Beta. If specified, OpenAI's system will make a best effort attempt 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.", "format": "int64", "example": 239847829 }, "service_tier": { "$ref": "#/components/schemas/ChatsServiceTier" }, "stop": { "$ref": "#/components/schemas/ChatsStop" }, "store": { "type": "boolean", "description": "Indicates whether to store the output of this chat completion request for use in OpenAI's [model distillation] or [evals] products.\n\n[model distillation]: https://platform.openai.com/docs/guides/distillation\n[evals]: https://platform.openai.com/docs/guides/evals", "default": false, "example": true }, "stream": { "type": "boolean", "description": "Indicates whether to stream the model response to the user. If set, partial message deltas will be sent, like in ChatGPT. Tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a data: `[DONE]` message.", "default": false, "example": true }, "stream_options": { "$ref": "#/components/schemas/StreamOptions" }, "temperature": { "type": "number", "description": "Specifies what sampling temperature to use.\nHigher values like `0.8` will make the output more random, while lower values like `0.2` will make it more focused and deterministic.\n\nNote: OpenAI generally recommends altering this or `top_p` but not both.", "minimum": 0, "maximum": 2, "default": 1, "example": 0.8 }, "tool_choice": { "$ref": "#/components/schemas/ChatsToolChoice" }, "tools": { "type": "array", "description": "A list of tools the model may call. Currently, only functions are supported as tools. 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/ChatsRequestTool" }, "minItems": 0, "maxItems": 128 }, "top_logprobs": { "type": "integer", "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.", "format": "int64", "minimum": 0, "maximum": 20, "example": 10 }, "top_p": { "type": "number", "description": "An alternative to sampling with `temperature`, called nucleus sampling, where the model considers the\nresults of the tokens with `top_p` probability mass.\nExample: `0.1` means only the tokens comprising the top 10% probability mass are considered.\n\nNote: OpenAI generally recommends altering this or `temperature` but not both.", "maximum": 1, "minimum": 0, "default": 1, "example": 0.1 }, "user": { "type": "string", "description": "A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse.", "example": "my-username" }, "router": { "type": "object", "description": "Specifies model routing configurations for the request.", "additionalProperties": { "type": "string" } }, "cache": { "$ref": "#/components/schemas/ChatsCache" } }, "required": [ "model", "messages" ] }, "ChatsMessageResponse": { "type": "object", "description": "A chat completion message generated by a model.", "properties": { "role": { "type": "string", "description": "The role of the author of this message.\nNote that this parameter is case sensitive, make sure to use lower case.\n", "example": "user" }, "content": { "type": "string", "description": "The content of the message.", "example": "This is some generated text response." }, "function_call": { "$ref": "#/components/schemas/FunctionCall" }, "refusal": { "type": "string", "description": "A refusal message generated by the model, if any.", "example": "refused text" }, "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ChatsToolCall" }, "description": "A list of tool calls generated by the model, such as function calls.", "minItems": 0, "maxItems": 128 } }, "required": [ "role", "content", "tool_calls" ] }, "ChatsFinishReason": { "type": "string", "description": "The reason the model stopped generating tokens.\n\nThis will be one of:\n- `\"stop\"` if the model hit a natural stop point or a provided stop sequence\n- `\"length\"` if the maximum number of tokens specified in the request was reached\n- `\"content_filter\"` if content was omitted due to a flag from our content filters\n- `\"tool_calls\"` if the model called a tool\n- `\"function_call\"` if the model called a function (deprecated in favor of `\"tool_calls\"`)", "enum": [ "stop", "length", "content_filter", "tool_calls", "function_call" ], "x-enum-varnames": [ "FinishReasonStop", "FinishReasonLength", "FinishReasonFunctionCall", "FinishReasonToolCalls", "FinishReasonContentFilter", "FinishReasonNull" ] }, "ChatsTopLogProbs": { "type": "object", "description": "The top log probabilities for a chat.", "properties": { "token": { "type": "string", "description": "The token that this log probability information is for.", "example": "the " }, "bytes": { "type": "array", "items": { "type": "integer", "format": "int64", "minimum": 0, "example": 60 }, "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.", "minItems": 0, "maxItems": 128, "example": [ 116, 104, 101, 32 ] }, "logprob": { "type": "number", "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.", "example": -5 } }, "required": [ "token", "bytes", "logprob" ] }, "ChatsLogProb": { "type": "object", "description": "The log probability of a token in a chat.", "properties": { "token": { "type": "string", "description": "Token that this log probability information is for.", "example": "The " }, "bytes": { "type": "array", "description": "A list of integers representing the UTF-8 bytes representation of the token.\nUseful in instances where characters are represented by multiple tokens and their byte representations must be\ncombined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.", "items": { "type": "integer", "minimum": 0, "format": "int32", "example": 10 }, "minItems": 0, "maxItems": 1000, "nullable": true, "example": [ 123, 67, 80, 102, 23, 68 ] }, "logprob": { "type": "number", "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.", "example": -5 }, "top_logprobs": { "type": "array", "items": { "$ref": "#/components/schemas/ChatsTopLogProbs" }, "description": "A 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.", "minItems": 0, "maxItems": 1000 } }, "required": [ "token", "bytes", "logprob", "top_logprobs" ] }, "ChatsLogProbs": { "type": "object", "description": "The log probability information for the choice.", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/ChatsLogProb" }, "description": "A list of message content tokens with log probability information.", "minItems": 0, "maxItems": 1000 }, "refusal": { "type": "array", "items": { "$ref": "#/components/schemas/ChatsLogProb" }, "description": "A list of message refusal tokens with log probability information.", "minItems": 0, "maxItems": 1000 } }, "nullable": true, "required": [ "content", "refusal" ] }, "ChatsChoice": { "type": "object", "description": "A chat choice from a list of chat choices.", "properties": { "index": { "type": "integer", "description": "Index of the choice in the list of choices.", "format": "int64", "minimum": 0, "example": 1 }, "message": { "$ref": "#/components/schemas/ChatsMessageResponse" }, "finish_reason": { "$ref": "#/components/schemas/ChatsFinishReason" }, "logprobs": { "$ref": "#/components/schemas/ChatsLogProbs" } }, "required": [ "index", "message", "finish_reason" ] }, "CompletionTokensDetails": { "type": "object", "description": "A breakdown of the tokens used in a completion.", "properties": { "accepted_prediction_tokens": { "type": "integer", "description": "When using Predicted Outputs, the number of tokens in the prediction that appeared in the completion.", "format": "int64", "minimum": 0, "example": 100 }, "audio_tokens": { "type": "integer", "description": "Audio input tokens generated by the model.", "format": "int64", "minimum": 0, "example": 60 }, "reasoning_tokens": { "type": "integer", "description": "Tokens generated by the model for reasoning.", "format": "int64", "minimum": 0, "example": 70 }, "rejected_prediction_tokens": { "type": "integer", "description": "When using Predicted Outputs, the number of tokens in the prediction that did not appear in the completion.\nHowever, like reasoning tokens, these tokens are still counted in the total completion tokens for\npurposes of billing, output, and context window limits.", "format": "int64", "minimum": 0, "example": 20 } } }, "PromptTokensDetails": { "type": "object", "description": "A breakdown of tokens used in the prompt.", "properties": { "audio_tokens": { "type": "integer", "description": "The audio input tokens present in the prompt.", "format": "int64", "minimum": 0, "example": 100 }, "cached_tokens": { "type": "integer", "description": "The cached tokens present in the prompt.", "format": "int64", "minimum": 0, "example": 30 } } }, "Usage": { "type": "object", "description": "Usage information for a model request.", "properties": { "completion_tokens": { "type": "integer", "description": "The number of tokens in the generated completion.", "format": "int64", "minimum": 0, "example": 81 }, "completion_tokens_details": { "$ref": "#/components/schemas/CompletionTokensDetails" }, "prompt_tokens": { "type": "integer", "description": "The number of tokens in the prompt.", "format": "int64", "minimum": 0, "example": 66 }, "prompt_tokens_details": { "$ref": "#/components/schemas/PromptTokensDetails" }, "total_tokens": { "type": "integer", "description": "The total number of tokens used in the request (prompt + completion).", "format": "int64", "minimum": 0, "example": 122 } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ] }, "ChatCompletion": { "type": "object", "description": "A chat completion response generated by a model.", "properties": { "id": { "type": "string", "description": "The unique identifier for the chat completion.", "example": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG" }, "object": { "type": "string", "description": "Object is the response object's type, which should always be `\"chat.completion\"`.", "example": "chat.completion" }, "created": { "type": "integer", "description": "The UNIX timestamp (in seconds) of when the chat completion was created.", "format": "int64", "minimum": 0, "example": 1741570283 }, "model": { "type": "string", "description": "The ID of the model used for the chat completion.", "example": "gpt-4o-2024-08-06" }, "choices": { "type": "array", "items": { "$ref": "#/components/schemas/ChatsChoice" }, "description": "A list of chat completion choices. Can be more than one if `n` is greater than `1` in the request.", "minItems": 1, "maxItems": 128 }, "service_tier": { "$ref": "#/components/schemas/ChatsServiceTier" }, "system_fingerprint": { "type": "string", "description": "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.", "example": "fp_fc9f1d7035" }, "usage": { "$ref": "#/components/schemas/Usage" }, "cached": { "type": "boolean", "description": "Indicates whether the request was cached.", "default": false, "example": true } }, "required": [ "id", "object", "created", "model", "choices", "service_tier", "usage" ] }, "CompletionsLogitBias": { "type": "object", "description": "Used to modify the likelihood of specified tokens appearing in the completion. Accepts a JSON object\nthat maps tokens (specified by their token ID in the GPT tokenizer) to an associated bias value from -100 to 100.\nYou can use this tokenizer tool to convert text to token IDs. Mathematically, the bias is added to the logits\ngenerated by the model prior to sampling.\n\nThe exact effect will vary per model, but:\n- values between `-1` and `1` should decrease or increase likelihood of selection and\n- values like `-100` or `100` should result in a ban or exclusive selection of the relevant token.\n\nAs an example, you can pass `{\"50256\": -100}` to prevent the `<|endoftext|>` token from being generated.", "additionalProperties": { "type": "integer", "format": "int64", "minimum": -100, "maximum": 100, "example": 10 }, "example": { "50256": -100 } }, "CompletionsCache": { "type": "object", "description": "The caching configuration for the request. Cache is only supported for non-streaming requests.", "properties": { "enabled": { "type": "boolean", "description": "Indicates whether caching is enabled.", "example": true }, "filter": { "type": "object", "description": "The filtering criteria for caching.", "additionalProperties": { "type": "string" } }, "threshold": { "type": "number", "description": "The threshold for caching the request; required if caching is enabled.", "example": 0.8 } }, "required": [ "enabled" ] }, "ModelRouter": { "type": "object", "description": "The model routing configuration for a request.", "properties": { "family_model": { "type": "array", "items": { "type": "string" }, "description": "The model families to include into the assessment in the case of smart routing.", "minItems": 0, "maxItems": 1000, "example": [ "gpt", "claude" ] }, "max_cost": { "type": "number", "description": "The maximum cost of the model to include into the assessment in the case of smart routing.", "minimum": 0, "example": 0.1 }, "models": { "type": "array", "items": { "type": "string" }, "description": "The model names to include into the assessment in the case of smart routing.", "minItems": 0, "maxItems": 1000, "example": [ "gpt-4o" ] }, "optimization": { "type": "string", "enum": [ "cost", "efficacy" ], "description": "The model selection optimization parameter. Options are `\"efficacy\"` (default) and `\"cost\"`.", "default": "efficacy", "example": "cost" }, "quality_tradeoff": { "type": "number", "description": "How much of quality possible to sacrifice during most optimal model selection, value between 0 and 1. Where, e.g. `0.8` means the quality can be reduced by 20%.", "example": 0.5 }, "region": { "type": "string", "description": "The region of the model to include into the assessment in the case of smart routing.", "example": "us-south" } } }, "CreateCompletionsRequest": { "type": "object", "description": "A (legacy) request to a model to generate text completion(s).", "properties": { "model": { "type": "string", "description": "The ID or alias of the model to use.", "example": "gpt-4o" }, "prompt": { "type": "string", "description": "The prompt(s) to generate completions for, encoded as a string, array of strings, array of tokens, or array of token arrays.\n\nNote: `<|endoftext|>` is the document separator that the model sees during training,\nso if a prompt is not specified the model will generate as if from the beginning of a new document.", "example": "What is the capital of France?" }, "best_of": { "type": "integer", "description": "Generates `best_of` number of completions server-side and returns the \"best\" (the one with the highest\nlog probability per token). Results cannot be streamed. When used with `n`, `best_of` controls the number of\ncandidate completions and `n` specifies how many to return – `best_of` must be greater than `n`.\n\nNote: Because this parameter generates many completions, it can quickly consume your token quota.\nUse carefully and ensure that you have reasonable settings for `max_tokens` and `stop`.", "format": "int32", "minimum": 0, "maximum": 128, "default": 1, "example": 2 }, "echo": { "type": "boolean", "description": "Indicate whether to echo back the prompt in addition to the completion", "default": false, "example": true }, "frequency_penalty": { "type": "number", "description": "A number between `-2.0` and `2.0`. Positive values penalize new tokens based on their\nexisting frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.", "maximum": 2, "minimum": -2, "default": 0, "example": 1.4 }, "logit_bias": { "$ref": "#/components/schemas/CompletionsLogitBias" }, "logprobs": { "type": "integer", "description": "The number of most likely output tokens to include the log probabilities of, as well the chosen tokens.\nFor example, if `logprobs` is `5`, the API will return a list of the 5 most likely tokens.\nThe API will always return the `logprob` of the sampled token, so there may be up to `logprobs+1` elements in the response.\nThe maximum value for `logprobs` is `5`.", "format": "int64", "maximum": 5, "minimum": 0, "example": 4 }, "max_tokens": { "type": "integer", "description": "The maximum number of tokens that can be generated in the completion.\nThe token count of your prompt plus `max_tokens` cannot exceed the model's context length.", "format": "int64", "minimum": 0, "maximum": 4096, "default": 16, "example": 1000 }, "metadata": { "$ref": "#/components/schemas/ChatsMetadata" }, "n": { "type": "integer", "description": "Specifies how many completions to generate for each prompt.\n\nNote: Because this parameter generates many completions, it can quickly consume your token quota.\nUse carefully and ensure that you have reasonable settings for `max_tokens` and `stop`.", "format": "int32", "minimum": 0, "maximum": 128, "default": 1, "example": 3 }, "presence_penalty": { "type": "number", "description": "A 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.", "maximum": 2, "minimum": -2, "default": 0, "example": 0.4 }, "seed": { "type": "integer", "description": "The seed for the model request. If specified, OpenAI's system will make a best effort to sample\ndeterministically, such that repeated requests with the same `seed` and parameters should return the same result.\n\nNote: Determinism is not guaranteed, and you should refer to the `system_fingerprint` response parameter to monitor changes in the backend.", "format": "int64", "example": 239847829 }, "stop": { "$ref": "#/components/schemas/ChatsStop" }, "stream": { "type": "boolean", "description": "Indicates whether to stream back partial progress.\nIf set, tokens will be sent as data-only [server-sent events] as they become available,\nwith the stream terminated by a `data: [DONE]` message.\n\n[server-sent events]: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format", "default": false, "example": true }, "stream_options": { "$ref": "#/components/schemas/StreamOptions" }, "suffix": { "type": "string", "description": "Text that comes after a completion of inserted text. On OpenAI, this parameter is only supported for `gpt-3.5-turbo-instruct`.", "example": "some text" }, "temperature": { "type": "number", "description": "Specifies what temperature to use for sample, between `0` and `2`. Higher values like `0.8` will make the output more random,\nwhile lower values like `0.2` will make it more focused and deterministic.\n\nNote: OpenAI generally recommends altering this or `top_p` but not both.", "minimum": 0, "maximum": 2, "default": 1, "example": 1.3 }, "top_p": { "type": "number", "description": "An alternative to sampling with `temperature`, called nucleus sampling, where the model considers the\nresults of the tokens with `top_p` probability mass. So `0.1` means only the tokens comprising the top 10%\nprobability mass are considered.\n\nNote: OpenAI generally recommends altering this or `temperature` but not both.", "minimum": 0, "maximum": 1, "default": 1, "example": 0.8 }, "user": { "type": "string", "description": "A unique identifier representing your end-user, which can help Services to monitor and detect abuse.", "example": "my-username" }, "cache": { "$ref": "#/components/schemas/CompletionsCache" }, "router": { "$ref": "#/components/schemas/ModelRouter" } }, "required": [ "model", "prompt" ] }, "CompletionsLogprobResult": { "type": "object", "description": "Log probabilities associated with the generated tokens.", "properties": { "tokens": { "type": "array", "items": { "type": "string", "example": "the" }, "description": "Tokens generated by the model.", "minItems": 0, "maxItems": 4096, "example": [ "The ", "capital ", "of ", "France ", "is ", "Paris." ] }, "text_offset": { "type": "array", "items": { "type": "integer", "format": "int64", "minimum": 0, "example": 10 }, "description": "Text offsets for the generated tokens.", "minItems": 0, "maxItems": 4096, "example": [ 0, 4, 12, 15, 22, 25 ] }, "token_logprobs": { "type": "array", "items": { "type": "number" }, "description": "Log probabilities of the generated tokens.", "minItems": 0, "maxItems": 4096, "example": [ -1.2, -2.12, -0.95, -1.35, -0.8, -0.5 ] }, "top_logprobs": { "type": "array", "description": "The top log probabilities for the generated tokens.", "items": { "type": "object", "additionalProperties": { "type": "number" } }, "minItems": 0, "maxItems": 4096 } }, "nullable": true, "required": [ "tokens", "text_offset", "token_logprobs", "top_logprobs" ] }, "CompletionsChoice": { "type": "object", "description": "A legacy text completions response choice.", "properties": { "index": { "type": "integer", "description": "The index of this choice in the response.", "format": "int64", "minimum": 0, "example": 1 }, "text": { "type": "string", "description": "The text generated by the model for the choice.", "example": "The capital of France is Paris." }, "finish_reason": { "type": "string", "description": "The reason the model stopped generating tokens.\nThis will be:\n- `\"stop\"` if the model hit a natural stop point or a provided stop sequence\n- `\"length\"` if the maximum number of tokens specified in the request was reached\n- `\"content_filter\"` if content was omitted due to a flag from our content filters", "enum": [ "stop", "length", "content_filter" ], "example": "stop" }, "logprobs": { "$ref": "#/components/schemas/CompletionsLogprobResult" } }, "required": [ "index", "text", "finish_reason" ] }, "Completion": { "type": "object", "description": "A legacy text completion response generated by a model.", "properties": { "id": { "type": "string", "description": "A unique identifier for the completion.", "example": "cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7" }, "object": { "type": "string", "description": "The object type, which is always `\"text_completion\"`.", "enum": [ "text_completion" ], "example": "text_completion" }, "created": { "type": "integer", "description": "The UNIX timestamp (in seconds) of when the completion was created.", "format": "int64", "minimum": 0, "example": 1589478378 }, "model": { "type": "string", "description": "The ID of the model used for the completion.", "example": "gpt-4-turbo" }, "choices": { "type": "array", "items": { "$ref": "#/components/schemas/CompletionsChoice" }, "description": "A list of completion choices the model generated for the input prompt.", "minItems": 0, "maxItems": 128 }, "system_fingerprint": { "type": "string", "description": "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.", "example": "fp_fc9f1d7035" }, "usage": { "$ref": "#/components/schemas/Usage" }, "cached": { "type": "boolean", "description": "Indicates whether the request was cached.", "example": true } }, "required": [ "id", "object", "model", "choices", "usage" ] }, "EmbeddingsInput": { "description": "Input text to embed, encoded as a string, array of strings, array of integers, or array of integer arrays. The input must not exceed the max input tokens for the model (8192 tokens for OpenAI's `text-embedding-ada-002`) and cannot be an empty string. Any array must be 2048 dimensions or less. Some models may also impose a limit on total number of tokens summed across inputs.", "oneOf": [ { "type": "string", "example": "This is some text to embed." }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 2048, "example": [ "this", "is", "some", "text", "to", "embed" ] }, { "type": "array", "items": { "type": "integer", "format": "int64", "minimum": 0 }, "minItems": 0, "maxItems": 2048, "example": [ 123, 67, 80, 102, 23, 68 ] }, { "type": "array", "items": { "type": "array", "items": { "type": "integer", "format": "int64", "minimum": 0, "example": 123 }, "minItems": 0, "maxItems": 2048, "example": [ 123, 67, 80, 102, 23, 68 ] }, "minItems": 0, "maxItems": 2048, "example": [ [ 123, 67 ], [ 80, 102 ], [ 23, 68 ] ] } ] }, "CreateEmbeddingsRequest": { "type": "object", "description": "A request to a model to generate new embeddings.", "properties": { "model": { "description": "The ID or alias of the model to use.", "type": "string", "example": "gpt-4o" }, "input": { "$ref": "#/components/schemas/EmbeddingsInput" }, "dimensions": { "type": "integer", "description": "The number of dimensions the resulting output embeddings should have. For OpenAI, only supported in `text-embedding-3` and later models.", "format": "int32", "minimum": 0, "maximum": 2048, "example": 10 }, "encoding_format": { "type": "string", "description": "The format to return the embeddings in. Can be either `\"float\"` or `\"base64\"`.", "default": "float", "example": "base64" }, "user": { "description": "A unique identifier representing your end-user.", "type": "string", "example": "my-username" } }, "required": [ "input", "model" ] }, "EmbeddingsEmbeddingData": { "description": "An embedding vector, which is a list of floats or a base64 string.\nThe length of vector depends on the model. For OpenAI's models, as listed in their [embedding guide].\n\n[embedding guide]: https://platform.openai.com/docs/guides/embeddings", "oneOf": [ { "type": "string", "example": "SGVsbG8sIHdvcmxkIS==" }, { "type": "array", "items": { "type": "number" }, "minItems": 0, "maxItems": 4096 } ] }, "EmbeddingsEmbedding": { "type": "object", "description": "An embedding in an embedding vector.", "properties": { "index": { "type": "integer", "description": "The index of the embedding in the list of embeddings.", "format": "int64", "minimum": 0, "example": 10 }, "object": { "type": "string", "description": "The object type, which is always `\"embedding\"`.", "enum": [ "embedding" ], "example": "embedding" }, "embedding": { "$ref": "#/components/schemas/EmbeddingsEmbeddingData" } }, "required": [ "index", "object", "embedding" ] }, "Embeddings": { "type": "object", "description": "A list of embeddings generated by a model.", "properties": { "object": { "type": "string", "description": "The object type, which is always `\"list\"`.", "enum": [ "list" ], "example": "list" }, "model": { "type": "string", "description": "The ID of the model used to create the embeddings. The same as the `model` provided in the request.", "example": "gpt-4o" }, "data": { "type": "array", "description": "A list of embedding objects generated by the model.", "items": { "$ref": "#/components/schemas/EmbeddingsEmbedding" }, "minItems": 0, "maxItems": 2048 }, "usage": { "$ref": "#/components/schemas/Usage" } }, "required": [ "object", "model", "data", "usage" ] }, "ImageBackground": { "type": "string", "description": "The background parameter allows to set transparency for the background for image generation.\n\nIn a request this parameter can be `\"auto\"` (default), `\"transparent\"` or `\"opaque\"`.\nIn the response this value not be `\"auto\"`.\nWhen `\"auto\"` is used, the model will automatically determine the best background for the image.\nIf `\"transparent\"`, the `\"output_format\"` needs to support transparency,\nso it should be set to either `\"png\"` (default value) or `\"webp\"`.\n\nFor OpenAI, this parameter is only supported for the `gpt-image-1` model.", "enum": [ "auto", "transparent", "opaque" ], "default": "auto", "example": "opaque" }, "ImageModeration": { "type": "string", "description": "Control the content-moderation level for images.\nFor OpenAI, this parameter is only supported by the `gpt-image-1` model.\n\nMust be either `\"low\"` for less restrictive filtering or `\"auto\"` (default value).", "enum": [ "low", "auto" ], "default": "auto", "example": "low" }, "ImageOutputFormat": { "type": "string", "description": "The output format of the image generation.\nFor OpenAI, this parameter is only supported by the `gpt-image-1` model.\n\nIn a request this parameter can be `\"auto\"`, `\"png\"`, `\"webp\"`, or `\"jpeg\"`.\nIn the response this value will not be `\"auto\"`.", "enum": [ "auto", "png", "webp", "jpeg" ], "default": "jpeg", "example": "webp" }, "ImageQuality": { "type": "string", "description": "The quality of the image generated.\n\nIn a request this parameter can be `\"auto\"`, `\"hd\"`, `\"standard\"`, `\"low\"`, `\"medium\"`, or `\"high\"`.\nIn the response this value will not be `\"auto\"`.\n\n`\"auto\"` (default value) will automatically select the best quality for the given model.\nFor OpenAI:\n- `\"high\"`, `\"medium\"` and `\"low\"` are only supported for the `gpt-image-1` model.\n- `\"hd\"` and `\"standard\"` are supported for the `dall-e-3` model.\n- `\"standard\"` is the only option for the `dall-e-2` model.", "enum": [ "auto", "hd", "standard", "low", "medium", "high" ], "default": "auto", "example": "high" }, "ImageResponseFormat": { "type": "string", "description": "The format in which generated images are returned.\nMust be one of `\"url\"` or `\"b64_json\"`. URLs are only valid for 60 minutes after the image has been generated.\n\nFor OpenAI, this parameter is only supported by the `dall-e-2` and `dall-e-3` models.\nThis parameter is not supported for the `gpt-image-1` model which will always return base64-encoded images.", "enum": [ "url", "b64_json" ], "default": "url", "example": "url" }, "ImageSize": { "type": "string", "description": "The size of the generated images.\n\nIn a request this parameter must be one of:\n- `\"1024x1024\"`, `\"1536x1024\"` (landscape), `\"1024x1536\"` (portrait), or `\"auto\"` (default value) for OpenAI's `gpt-image-1` model.\n- `\"256x256\"`, `\"512x512\"`, or `\"1024x1024\"` for OpenAI's `dall-e-2` model.\n- `\"1024x1024\"`, `\"1792x1024\"`, or `\"1024x1792\"` for OpenAI's `dall-e-3` model.\nIn the response this value will not be `\"auto\"`.", "default": "1024x1024", "example": "512x512" }, "ImageStyle": { "type": "string", "description": "Style of the generated images.\nMust be one of:\n- `\"vivid\"` causes the model to lean towards generating hyper-real and dramatic images.\n- `\"natural\"` causes the model to produce more natural, less hyper-real looking images.\n\nFor OpenAI, this param is only supported for `dall-e-3`.", "enum": [ "vivid", "natural" ], "default": "vivid", "example": "natural" }, "CreateImageRequest": { "type": "object", "description": "A request to a model to generate image(s).", "properties": { "model": { "default": "dall-e-2", "description": "The ID or alias of model to use for image generation.", "example": "dall-e-3", "type": "string" }, "prompt": { "type": "string", "description": "A text description of the desired image(s).\nFor OpenAI, the maximum length is 32000 characters for `gpt-image-1`, and 1000 and 4000 characters respectively for `dall-e-2` and `dall-e-3`.", "minLength": 1, "example": "Create an image of a dog" }, "background": { "$ref": "#/components/schemas/ImageBackground" }, "moderation": { "$ref": "#/components/schemas/ImageModeration" }, "n": { "type": "integer", "format": "int32", "description": "The number of images to generate.\nMust be between `1` and `10`. For OpenAI's `dall-e-3`, `n` only supports a value of `1`.", "minimum": 1, "maximum": 10, "default": 1, "example": 5 }, "output_compression": { "type": "integer", "description": "The compression level (0-100%) for the generated images.\nThis parameter is only supported for OpenAI's `gpt-image-1` model with the `\"webp\"` or `\"jpeg\"` output formats, and defaults to `100`.", "default": 100, "example": 50 }, "output_format": { "$ref": "#/components/schemas/ImageOutputFormat" }, "partial_images": { "type": "integer", "format": "int32", "description": "The number of partial images to generate.\nThis parameter is used for streaming responses that return partial images.\nValue must be between `0` and `3`. When set to `0`, the response will be a single image sent in one streaming event.\n\nNote: The final image may be sent before the full number of partial images are generated if the full image is generated more quickly.", "minimum": 0, "maximum": 3, "default": 0, "example": 2 }, "quality": { "$ref": "#/components/schemas/ImageQuality" }, "response_format": { "$ref": "#/components/schemas/ImageResponseFormat" }, "size": { "$ref": "#/components/schemas/ImageSize" }, "style": { "$ref": "#/components/schemas/ImageStyle" }, "user": { "type": "string", "description": "A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse.", "example": "John Doe" } }, "required": [ "model", "prompt" ] }, "ImageData": { "type": "object", "description": "Image data generated by a model containing either a URL or base64 encoded JSON.", "properties": { "b64_json": { "type": "string", "description": "The base64-encoded JSON of the generated image.\n\nFor OpenAI, always used by the `gpt-image-1` model.\nOnly present for the `dall-e-2` and `dall-e-3` models when `\"response_format\" is set to `\"b64_json\".", "example": "VGhpcyBp..." }, "url": { "type": "string", "description": "A link to the generated image.\n\nFor OpenAI, supported by the `dall-e-2` or `dall-e-3` models when `\"response_format\"` set to `\"url\"` (default value).\nUnsupported for the `gpt-image-1` model.", "example": "https://example.website/path-to-image" }, "revised_prompt": { "type": "string", "description": "The revised prompt that was used to generate the image.\n\nFor OpenAI, supported by the `dall-e-3` model only.", "example": "An image of a dog" } } }, "ImageInputTokensDetails": { "type": "object", "description": "The input tokens detailed information for the image generation.", "properties": { "image_tokens": { "type": "integer", "format": "int64", "description": "The number of image tokens in the input prompt.", "minimum": 0, "example": 10 }, "text_tokens": { "type": "integer", "format": "int64", "description": "The number of text tokens in the input prompt.", "minimum": 0, "example": 100 } }, "required": [ "image_tokens", "text_tokens" ] }, "ImageUsage": { "type": "object", "description": "The token usage information for the image generation.\n\nFor OpenAI, supported by the `gpt-image-1` model only.", "properties": { "input_tokens_details": { "$ref": "#/components/schemas/ImageInputTokensDetails" }, "input_tokens": { "type": "integer", "format": "int64", "description": "The number of tokens (images and text) in the input prompt.", "minimum": 0, "example": 100 }, "output_tokens": { "type": "integer", "format": "int64", "description": "The number of output tokens generated by the model.", "minimum": 0, "example": 100 }, "total_tokens": { "type": "integer", "format": "int64", "description": "The total number of tokens (images and text) used for the image generation.", "minimum": 0, "example": 100 } }, "required": [ "input_tokens_details", "input_tokens", "output_tokens", "total_tokens" ] }, "ImageGeneration": { "type": "object", "description": "The image object generated by the model.", "properties": { "created": { "type": "integer", "format": "int64", "description": "Created is a UNIX timestamp of the time that the model response was created (in seconds).", "minimum": 0, "example": 1713833628 }, "data": { "type": "array", "description": "A list of the image objects generated by the model.", "items": { "$ref": "#/components/schemas/ImageData" }, "minItems": 1, "maxItems": 10 }, "background": { "$ref": "#/components/schemas/ImageBackground" }, "output_format": { "$ref": "#/components/schemas/ImageOutputFormat" }, "quality": { "$ref": "#/components/schemas/ImageQuality" }, "size": { "$ref": "#/components/schemas/ImageSize" }, "usage": { "$ref": "#/components/schemas/ImageUsage" } }, "required": [ "created", "data", "background", "output_format", "quality", "size" ] }, "ModelMetadata": { "type": "object", "description": "Contains additional configuration for the model.", "additionalProperties": true, "properties": { "cost": { "type": "number", "description": "The cost per 1000 tokens for the model. This represents the pricing in USD for processing 1000 tokens. A nil value indicates the cost is not available or applicable.", "minimum": 0, "example": 0.02 }, "model_family": { "type": "string", "description": "The family or series that this model belongs to.\nExamples:\n- \"gpt-3.5\" for GPT-3.5 series models\n- \"gpt-4\" for GPT-4 series models\n- \"llama-2\" for Llama 2 series models", "example": "gpt-3.5" }, "recommender_label": { "type": "string", "description": "When calling the Recommender API, this value is used to map to the supported model in the Recommender API. For example, \"openai-gpt-4o-mini\" could be the recommender label for a specific model.", "example": "openai-gpt-4o-mini" }, "region": { "type": "string", "description": "The region where this model is deployed in. This indicates the geographical location of the model deployment. Important for data residency requirements and latency considerations.", "example": "us-east-1" }, "batch": { "type": "boolean", "description": "Marks the model as eligible or preferred for batch requests.", "default": false, "example": true }, "context_window": { "type": "integer", "format": "int64", "description": "The maximum number of tokens the model can process in a single request.", "minimum": 1, "example": 128000 } } }, "Model": { "type": "object", "description": "Configuration for a model, Large Language Model (LLM) or otherwise, that's available through a configured model provider. For example, `id` could be set to \"gpt-o\", which is the official server-side name of the model. The `alias` field can be used by clients to refer to that model in a more convenient or custom manner. When a client provides the alias instead of the official name, the middleware will map the alias back to the underlying `id` (e.g., `\"gpt-o\"`) and execute requests against the correct model.", "properties": { "uuid": { "type": "string", "description": "The unique identifier for the model.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "object": { "type": "string", "description": "The object type, which is always \"model\".", "example": "model" }, "created": { "type": "integer", "description": "The Unix timestamp (in seconds) when the model configuration was created.", "format": "int64", "minimum": 0, "example": 1677649963 }, "owned_by": { "type": "string", "description": "The provider that owns the model.\n\nFormat: `\":\"", "example": "openai:vllm4" }, "id": { "type": "string", "description": "The official provider-specific server-side unique identifier of the model instance.", "example": "gpt-3.5-turbo-456723" }, "alias": { "type": "string", "description": "An optional friendly name for the model. If not set, the default is the value of ID. The Alias can be used by clients to refer to that model in a more convenient or custom manner. When a client provides the alias (e.g., `\"my-gpt\"`) instead of the official name, the middleware will map the alias back to the underlying ID (e.g., `\"gpt-4.1-2025-04-14\"`) and execute requests against the correct model.", "example": "my-gpt" }, "description": { "type": "string", "description": "A custom user-defined description for the model.", "example": "Some custom description string" }, "metadata": { "$ref": "#/components/schemas/ModelMetadata" } }, "required": [ "uuid", "object", "created", "owned_by", "id" ] }, "ModelCollection": { "type": "object", "description": "A list of models.", "properties": { "object": { "type": "string", "description": "The object type, which is always \"list\".", "enum": [ "list" ], "example": "list" }, "data": { "type": "array", "description": "The array of models.", "items": { "$ref": "#/components/schemas/Model" }, "minItems": 0, "maxItems": 1000 } }, "required": [ "object", "data" ] }, "TenantInfo": { "type": "object", "description": "Information about a tenant account.", "properties": { "uuid": { "type": "string", "description": "The unique identifier of the tenant.", "example": "09b2d701-4592-4386-85cf-326c6b3c94c7" }, "name": { "type": "string", "description": "The custom name of the tenant.", "example": "my-tenant" } }, "required": [ "uuid", "name" ] }, "ReplaceTenantRequest": { "type": "object", "description": "Request body for replacing a tenant", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The new name for the tenant. Currently, the tenant's name is the only mutable field.", "example": "my-account" } } }, "UpdateTenantRequest": { "type": "object", "description": "Request body for updating a tenant", "properties": { "name": { "type": "string", "description": "A new name for the tenant. Currently, the tenant's name is the only mutable field.", "example": "my-account" } } }, "TenantConfig": { "type": "object", "description": "Tenant configuration including default space_id, project_id, and default_algorithm", "properties": { "space_id": { "type": "string", "description": "Default space ID for the tenant" }, "project_id": { "type": "string", "description": "Default project ID for the tenant" }, "default_algorithm": { "type": "string", "description": "The load balancing algorithm to use for distributing requests.\nSupported algorithms: \"least_connections\", \"weighted_round_robin\", \"round_robin\", \"quota_priority\"\n", "enum": [ "least_connections", "weighted_round_robin", "round_robin", "quota_priority" ] } } }, "TenantConfigRequest": { "type": "object", "description": "Request to update tenant configuration", "properties": { "space_id": { "type": "string", "description": "Default space ID for the tenant" }, "project_id": { "type": "string", "description": "Default project ID for the tenant" }, "default_algorithm": { "type": "string", "description": "The load balancing algorithm to use for distributing requests.\nSupported algorithms: \"least_connections\", \"weighted_round_robin\", \"round_robin\", \"quota_priority\"\n", "enum": [ "least_connections", "weighted_round_robin", "round_robin", "quota_priority" ] } } }, "Token": { "type": "object", "description": "JWT token response", "required": [ "token" ], "properties": { "token": { "type": "string", "description": "The raw authorization token string.", "example": "eyJhbG..." } } }, "TenantPolicy": { "type": "object", "description": "A policy is used to restrict access to specific resources. Policies can be created or deleted, there is no updating.", "properties": { "uuid": { "type": "string", "description": "The unique identifier for the policy.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "subject": { "type": "string", "description": "A unique identifier for the party subject to this resource access policy.\nFor IBM Cloud IAM this can be the Access Group ID.", "example": "AccessGroupId-56c5e703-80d4-4f06-a7e6-844618ec39b3" }, "resource": { "type": "string", "description": "A unique identifier for the resource this policy is restricting access to.\n\nFormat: `\":\"`\nCurrently, the supported resource types are: `tenant`, `provider`, `model`, and `policy`.", "example": "model:62a04a11-07bf-5309-a78e-95323dbbc333" }, "action": { "type": "string", "description": "The action to perform on the policy. Currently only one of `\"read\"` or `\"write\"` are supported.", "enum": [ "read", "write" ], "example": "write" }, "effect": { "type": "string", "description": "The effect that the policy is to have, either `\"allow\"` or `\"deny\"`.", "enum": [ "allow", "deny" ], "example": "deny" } }, "required": [ "uuid", "subject", "action", "resource", "effect" ] }, "TenantPolicyCollection": { "type": "object", "description": "A list of tenant policies.", "properties": { "object": { "type": "string", "description": "The object type, always `\"list\"`.", "enum": [ "list" ], "example": "list" }, "data": { "type": "array", "description": "The array of tenant policies.", "items": { "$ref": "#/components/schemas/TenantPolicy" }, "minItems": 0, "maxItems": 1000 } }, "required": [ "object", "data" ] }, "CreateTenantPolicyRequest": { "type": "object", "description": "A request to create a new policy for the tenant.", "properties": { "subject": { "type": "string", "description": "A unique identifier for the party subject to this resource access policy.\nFor IBM Cloud IAM this can be the Access Group ID.", "example": "AccessGroupId-56c5e703-80d4-4f06-a7e6-844618ec39b3" }, "resource": { "type": "string", "description": "A unique identifier for the resource this policy is restricting access to.\n\nFormat: `\":\"`\nCurrently, the supported resource types are: `tenant`, `provider`, `model`, and `policy`.", "example": "model:62a04a11-07bf-5309-a78e-95323dbbc333" }, "action": { "type": "string", "description": "The action to perform on the policy. Currently only one of `\"read\"` or `\"write\"` are supported.", "enum": [ "read", "write" ], "example": "write" }, "effect": { "type": "string", "description": "The effect that the policy is to have, either `\"allow\"` or `\"deny\"`.", "enum": [ "allow", "deny" ], "default": "allow", "example": "deny" } }, "required": [ "subject", "resource", "action" ] }, "UpdateTenantPolicyRequest": { "type": "object", "description": "A request to update an existing policy for the tenant. All fields are optional; only provided fields will be updated.", "properties": { "subject": { "type": "string", "description": "A unique identifier for the party subject to this resource access policy.\nFor IBM Cloud IAM this can be the Access Group ID.", "example": "AccessGroupId-56c5e703-80d4-4f06-a7e6-844618ec39b3" }, "resource": { "type": "string", "description": "A unique identifier for the resource this policy is restricting access to.\n\nFormat: `\":\"`\nCurrently, the supported resource types are: `tenant`, `provider`, `model`, and `policy`.", "example": "model:62a04a11-07bf-5309-a78e-95323dbbc333" }, "action": { "type": "string", "description": "The action to perform on the policy. Currently only one of `\"read\"` or `\"write\"` are supported.", "enum": [ "read", "write" ], "example": "write" }, "effect": { "type": "string", "description": "The effect that the policy is to have, either `\"allow\"` or `\"deny\"`.", "enum": [ "allow", "deny" ], "example": "deny" } } }, "DataReference": { "type": "object", "description": "Data Reference is a reference to a remote credential store. For example, an IBM Cloud Secrets Manager secret. The value in the remote store is expected to be a JSON representation of the `data` field of a provider request.", "properties": { "resource": { "type": "string", "description": "A unique identifier for the remote store that references the credential data object.", "example": "crn:v1:bluemix:public:secrets-manager:..." } } }, "Provider": { "type": "object", "description": "A model provider configured for a tenant.", "properties": { "uuid": { "type": "string", "description": "The unique identifier of the model provider.", "example": "56c5e703-80d4-4f06-a7e6-844618ec39b3" }, "name": { "type": "string", "description": "The custom name of the model provider.", "example": "my-openai-provider" }, "type": { "type": "string", "description": "The provider type that the credential is for.", "example": "openai" }, "description": { "type": "string", "description": "The custom description of the model provider.", "example": "Some custom description string" }, "data_reference": { "$ref": "#/components/schemas/DataReference" }, "data": { "type": "object", "description": "Data to be mapped to a provider credential config.", "additionalProperties": { "type": "string" } }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/Model" }, "description": "The configured models for this provider.", "minItems": 0, "maxItems": 1000 } }, "required": [ "uuid", "name", "type", "models" ] }, "ProviderCollection": { "type": "object", "description": "A list of model providers.", "properties": { "object": { "type": "string", "description": "The object type, always \"list\".", "enum": [ "list" ], "example": "list" }, "data": { "type": "array", "description": "The array of model providers.", "items": { "$ref": "#/components/schemas/Provider" }, "minItems": 0, "maxItems": 1000 } }, "required": [ "object", "data" ] }, "AnthropicConfig": { "type": "object", "description": "Configuration details for an Anthropic provider.", "properties": { "apikey": { "type": "string", "description": "The required authentication key for accessing the Anthropic API.", "example": "sk-ant-api03-R2D...igAA" } }, "required": [ "apikey" ] }, "AnthropicProviderRequest": { "type": "object", "description": "A request to create a new or replace an existing Anthropic provider with the supplied configuration data. The Anthropic provider's credentials must be supplied by either the `data_reference` or inlined JSON `data` fields.", "properties": { "name": { "type": "string", "description": "A custom name for the Anthropic model provider instance. The name can only contain alphanumeric characters, single spaces (no consecutive spaces), hyphens (-), parentheses (), and square brackets []. No leading or trailing spaces are allowed.", "example": "fast-llm" }, "description": { "type": "string", "description": "A custom description for the Anthropic model provider instance.", "example": "Some custom description string" }, "data": { "$ref": "#/components/schemas/AnthropicConfig" }, "data_reference": { "$ref": "#/components/schemas/DataReference" } }, "required": [ "name" ] }, "ProviderInfo": { "type": "object", "description": "Information on a configured model provider instance.", "properties": { "uuid": { "type": "string", "description": "The unique identifier of the model provider.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "name": { "type": "string", "description": "The name of the model provider.", "example": "my-openai-provider" }, "type": { "type": "string", "description": "The model provider type of this instance.", "example": "openai" }, "description": { "type": "string", "description": "A custom description of the provider.", "example": "Some custom description string." } }, "required": [ "uuid", "name", "type" ] }, "AzureOpenAIConfig": { "type": "object", "description": "Configuration details for an Azure OpenAI provider.", "properties": { "account_name": { "type": "string", "description": "The Azure account name; required to use `/v1/providers/{provider_uuid}/models`.", "example": "my-azure-account" }, "api_version": { "type": "string", "description": "Version of the Azure OpenAI API to use (default: `\"2024-10-21\"`).", "default": "2024-10-21", "example": "2024-10-21" }, "apikey": { "type": "string", "description": "The required authentication key for accessing Azure OpenAI services.", "example": "AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe" }, "resource_group_name": { "type": "string", "description": "The Azure resource group name; required to use `/v1/providers/{provider_uuid}/models`.", "example": "my-resource-group" }, "resource_name": { "type": "string", "description": "The Azure OpenAI resource to connect to.", "example": "my-resource-name" }, "subscription_id": { "type": "string", "description": "The Azure subscription ID; required to use `/v1/providers/{provider_uuid}/models`.", "example": "acde070d-8c4c-4f0d-9d8a-162843c10333" } }, "required": [ "api_version", "apikey", "resource_name" ] }, "AzureOpenAIProviderRequest": { "type": "object", "description": "A request to create a new or replace an existing Azure OpenAI provider with the supplied configuration data. The Azure OpenAI provider's credentials must be supplied by either the `data_reference` or inlined JSON `data` fields.", "properties": { "name": { "type": "string", "description": "A custom name for the Azure OpenAI model provider instance. The name can only contain alphanumeric characters, single spaces (no consecutive spaces), hyphens (-), parentheses (), and square brackets []. No leading or trailing spaces are allowed.", "example": "fast-llm" }, "description": { "type": "string", "description": "A custom description for the Azure OpenAI model provider instance.", "example": "Some custom description string" }, "data": { "$ref": "#/components/schemas/AzureOpenAIConfig" }, "data_reference": { "$ref": "#/components/schemas/DataReference" } }, "required": [ "name" ] }, "AWSBedrockConfig": { "type": "object", "description": "Configuration details for an AWS Bedrock provider.", "properties": { "access_key_id": { "type": "string", "description": "The AWS access key ID required to authenticate with the Bedrock API.", "example": "acde070d-8c4c-4f0d-9d8a-162843c10333" }, "base_url": { "type": "string", "description": "Overrides the default AWS Bedrock Runtime API endpoint with the provided URL.", "example": "https://bedrock-runtime.us-east-1.amazonaws.com" }, "region": { "type": "string", "description": "The AWS region where the Bedrock API is hosted.", "example": "us-east-1" }, "secret_access_key": { "type": "string", "description": "The AWS secret access key required to authenticate with the Bedrock API.", "example": "AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe" }, "session_token": { "type": "string", "description": "Optional AWS session token for temporary credentials.", "example": "AQoDYXdzEJr......HVkDR45Kg==" } }, "required": [ "access_key_id", "region", "secret_access_key" ] }, "AWSBedrockProviderRequest": { "type": "object", "description": "A request to create a new or replace an existing AWS Bedrock provider with the supplied configuration data. The AWS Bedrock provider's credentials must be supplied by either the `data_reference` or inlined JSON `data` fields.", "properties": { "name": { "type": "string", "description": "A custom name for the AWS Bedrock model provider instance. The name can only contain alphanumeric characters, single spaces (no consecutive spaces), hyphens (-), parentheses (), and square brackets []. No leading or trailing spaces are allowed.", "example": "fast-llm" }, "description": { "type": "string", "description": "A custom description for the AWS Bedrock model provider instance.", "example": "Some custom description string" }, "data": { "$ref": "#/components/schemas/AWSBedrockConfig" }, "data_reference": { "$ref": "#/components/schemas/DataReference" } }, "required": [ "name" ] }, "CerebrasConfig": { "type": "object", "description": "Configuration details for a Cerebras provider.", "properties": { "apikey": { "type": "string", "description": "The required authentication key for accessing the Cerebras API.", "example": "AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe" } }, "required": [ "apikey" ] }, "CerebrasProviderRequest": { "type": "object", "description": "A request to create a new or replace an existing Cerebras provider with the supplied configuration data. The Cerebras provider's credentials must be supplied by either the `data_reference` or inlined JSON `data` fields.", "properties": { "name": { "type": "string", "description": "A custom name for the Cerebras model provider instance. The name can only contain alphanumeric characters, single spaces (no consecutive spaces), hyphens (-), parentheses (), and square brackets []. No leading or trailing spaces are allowed.", "example": "fast-llm" }, "description": { "type": "string", "description": "A custom description for the Cerebras model provider instance.", "example": "Some custom description string" }, "data": { "$ref": "#/components/schemas/CerebrasConfig" }, "data_reference": { "$ref": "#/components/schemas/DataReference" } }, "required": [ "name" ] }, "CohereConfig": { "type": "object", "description": "Configuration details for a Cohere provider.", "properties": { "apikey": { "type": "string", "description": "The required authentication key for accessing the Cohere API.", "example": "AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe" } }, "required": [ "apikey" ] }, "CohereProviderRequest": { "type": "object", "description": "Request body for creating or replacing a Cohere provider.", "properties": { "description": { "description": "A custom user-defined description for the model provider.", "example": "Some custom description string", "type": "string" }, "name": { "description": "Name can only contain alphanumeric characters, single spaces (no consecutive spaces), underscores (_), hyphens (-), parentheses (), and square brackets []. No leading or trailing spaces are allowed.", "example": "openai-prod", "type": "string" }, "data": { "$ref": "#/components/schemas/CohereConfig" }, "data_reference": { "$ref": "#/components/schemas/DataReference" } }, "required": [ "name" ] }, "GeminiConfig": { "type": "object", "description": "Configuration details for a Gemini provider.", "properties": { "apikey": { "type": "string", "description": "The required Google AI Studio API key for accessing the Gemini API.", "example": "AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe" } }, "required": [ "apikey" ] }, "GeminiProviderRequest": { "type": "object", "description": "A request to create a new or replace an existing Google Gemini provider with the supplied configuration data. The Gemini provider's credentials must be supplied by either the `data_reference` or inlined JSON `data` fields.", "properties": { "name": { "description": "A custom name for the Gemini model provider instance. The name can only contain alphanumeric characters, single spaces (no consecutive spaces), hyphens (-), parentheses (), and square brackets []. No leading or trailing spaces are allowed.", "example": "fast-llm", "type": "string" }, "description": { "type": "string", "description": "A custom description for the Gemini model provider instance.", "example": "Some custom description string" }, "data": { "$ref": "#/components/schemas/GeminiConfig" }, "data_reference": { "$ref": "#/components/schemas/DataReference" } }, "required": [ "name" ] }, "GroqConfig": { "type": "object", "description": "Contains the credential details for configuring the provider instance.", "properties": { "apikey": { "type": "string", "description": "APIKey is the required authentication key for accessing the Groq API." } }, "required": [ "apikey" ] }, "GroqProviderRequest": { "type": "object", "description": "A request to create a new or replace an existing Groq provider with the supplied configuration data. The Groq provider's credentials must be supplied by either the `data_reference` or inlined JSON `data` fields.", "properties": { "name": { "type": "string", "description": "A custom name for the Groq model provider instance. The name can only contain alphanumeric characters, single spaces (no consecutive spaces), hyphens (-), parentheses (), and square brackets []. No leading or trailing spaces are allowed.", "example": "my-groq" }, "description": { "type": "string", "description": "A custom description for the Groq model provider instance.", "example": "Some custom description string" }, "data": { "$ref": "#/components/schemas/GroqConfig" }, "data_reference": { "$ref": "#/components/schemas/DataReference" } }, "required": [ "name" ] }, "MistralConfig": { "type": "object", "description": "Configuration details for a Mistral provider.", "properties": { "apikey": { "type": "string", "description": "The required authentication key for accessing the Mistral API.", "example": "mistral-1234567890abcdef1234567890abcdef" } }, "required": [ "apikey" ] }, "MistralProviderRequest": { "type": "object", "description": "Request body for creating or replacing a Mistral provider.", "properties": { "description": { "description": "A custom user-defined description for the model provider.", "example": "Some custom description string", "type": "string" }, "name": { "description": "Name can only contain alphanumeric characters, single spaces (no consecutive spaces), underscores (_), hyphens (-), parentheses (), and square brackets []. No leading or trailing spaces are allowed.", "example": "openai-prod", "type": "string" }, "data": { "$ref": "#/components/schemas/MistralConfig" }, "data_reference": { "$ref": "#/components/schemas/DataReference" } }, "required": [ "name" ] }, "NvidiaNIMConfig": { "type": "object", "description": "Configuration details for an Nvidia NIM provider.", "properties": { "apikey": { "type": "string", "description": "The required authentication key for accessing the Nvidia NIM API.", "example": "AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe" } }, "required": [ "apikey" ] }, "NvidiaNIMProviderRequest": { "type": "object", "description": "A request to create a new or replace an existing Nvidia NIM provider with the supplied configuration data. The Nvidia NIM provider's credentials must be supplied by either the `data_reference` or inlined JSON `data` fields.", "properties": { "name": { "description": "A custom name for the Nvidia NIM model provider instance. The name can only contain alphanumeric characters, single spaces (no consecutive spaces), hyphens (-), parentheses (), and square brackets []. No leading or trailing spaces are allowed.", "example": "fast-llm", "type": "string" }, "description": { "type": "string", "description": "A custom description for the Nvidia NIM model provider instance.", "example": "Some custom description string" }, "data": { "$ref": "#/components/schemas/NvidiaNIMConfig" }, "data_reference": { "$ref": "#/components/schemas/DataReference" } }, "required": [ "name" ] }, "OllamaConfig": { "type": "object", "description": "Configuration details for an Ollama provider.", "properties": { "host": { "type": "string", "description": "The base URL of the Ollama server.", "example": "https://localhost:11434" }, "keep_alive": { "type": "integer", "format": "int64", "description": "Number of minutes to keep the model loaded after a request.", "minimum": 0, "example": 5 }, "clean_on_close": { "type": "boolean", "description": "Whether to unload the model when the provider is closed.", "example": false } }, "required": [ "host" ] }, "OllamaProviderRequest": { "type": "object", "description": "Request body for creating or replacing an Ollama provider.", "properties": { "description": { "description": "A custom user-defined description for the model provider.", "example": "Some custom description string", "type": "string" }, "name": { "description": "Name can only contain alphanumeric characters, single spaces (no consecutive spaces), underscores (_), hyphens (-), parentheses (), and square brackets []. No leading or trailing spaces are allowed.", "example": "ollama-prod", "type": "string" }, "data": { "$ref": "#/components/schemas/OllamaConfig" }, "data_reference": { "$ref": "#/components/schemas/DataReference" } }, "required": [ "name" ] }, "OpenAIConfig": { "type": "object", "description": "Configuration details for an OpenAI provider.", "properties": { "apikey": { "type": "string", "description": "The required authentication key for accessing the OpenAI API.", "example": "sk-proj-2_IN3221...IWZkA" }, "base_url": { "type": "string", "description": "Override the URL used to access the OpenAI provider services.\nThis URL can point to any OpenAI-compatible model provider service.", "default": "https://api.openai.com/v1", "example": "https://api.openai.com/v1" } }, "required": [ "apikey" ] }, "OpenAIProviderRequest": { "type": "object", "description": "A request to create a new or replace an existing OpenAI provider with the supplied configuration data. The OpenAI provider's credentials must be supplied by either the `data_reference` or inlined JSON `data` fields.", "properties": { "name": { "description": "A custom name for the OpenAI model provider instance. The name can only contain alphanumeric characters, single spaces (no consecutive spaces), hyphens (-), parentheses (), and square brackets []. No leading or trailing spaces are allowed.", "example": "fast-llm", "type": "string" }, "description": { "type": "string", "description": "A custom description for the OpenAI model provider instance.", "example": "Some custom description string" }, "data": { "$ref": "#/components/schemas/OpenAIConfig" }, "data_reference": { "$ref": "#/components/schemas/DataReference" } }, "required": [ "name" ] }, "ProvidersValidateRequest": { "type": "object", "description": "A request to validate a provider's credentials. Should contain the credentials either by `data_reference` or `data`.", "properties": { "type": { "type": "string", "description": "The type of provider to validate (e.g., \"openai\", \"anthropic\", \"watsonxai\").", "example": "openai" }, "data_reference": { "$ref": "#/components/schemas/DataReference" }, "data": { "type": "object", "description": "The credential details for validating the provider. This should be a JSON object matching the provider's configuration schema.", "additionalProperties": true } }, "required": [ "type" ] }, "ProvidersValidateResponse": { "type": "object", "description": "The result of validating provider credentials.", "properties": { "provider_type": { "type": "string", "description": "The provider type that was validated.", "example": "openai" }, "valid": { "type": "boolean", "description": "Indicates whether the credential validation was successful.\ntrue = credentials are valid, false = validation failed", "example": true }, "message": { "type": "string", "description": "A human-readable message describing the validation result.\nFor successful validations (valid=true), this confirms the credentials are valid.\nFor failed validations (valid=false), this provides details about why validation failed.", "example": "Credentials validated successfully" } }, "required": [ "provider_type", "valid" ] }, "WatsonxAIConfig": { "type": "object", "description": "Configuration details for a WatsonX.ai provider.", "properties": { "api_version": { "type": "string", "description": "Overrides the WatsonX.ai API version to use.", "default": "2023-07-07" }, "apikey": { "type": "string", "description": "Optional authentication key for accessing WatsonX.ai services.", "example": "AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe" }, "auth_url": { "type": "string", "description": "Overrides the URL to use for IBM Cloud IAM authentication.", "default": "https://iam.cloud.ibm.com/identity/token", "example": "https://iam.cloud.ibm.com/identity/token" }, "base_url": { "type": "string", "description": "Overrides the URL to use to access the IBM WatsonX.ai services.", "example": "https://us-south.ml.cloud.ibm.com", "default": "https://us-south.ml.cloud.ibm.com" }, "project_id": { "type": "string", "description": "The IBM WatsonX.ai project ID (required if `space_id` is not provided).", "example": "09b2r701-4592-4386-85cf-326c6b3c94c7" }, "space_id": { "type": "string", "description": "The IBM WatsonX.ai space ID (required if `project_id` is not provided).", "example": "q9b2d701-4592-4386-85cf-326c6b3c94c7" } }, "required": [ "base_url" ] }, "WatsonxAIProviderRequest": { "type": "object", "description": "A request to create a new or replace an existing Watsonx.ai provider with the supplied configuration data. The Watsonx.ai provider's credentials must be supplied by either the `data_reference` or inlined JSON `data` fields.", "properties": { "name": { "type": "string", "description": "A custom name for the Watsonx.ai model provider instance. The name can only contain alphanumeric characters, single spaces (no consecutive spaces), hyphens (-), parentheses (), and square brackets []. No leading or trailing spaces are allowed.", "example": "fast-llm" }, "description": { "type": "string", "description": "A custom description for the Watsonx.ai model provider instance.", "example": "Some custom description string" }, "data": { "$ref": "#/components/schemas/WatsonxAIConfig" }, "data_reference": { "$ref": "#/components/schemas/DataReference" } }, "required": [ "name" ] }, "XaiConfig": { "type": "object", "description": "Configuration details for an xAI provider.", "properties": { "apikey": { "type": "string", "description": "The required authentication key for accessing the xAI API.", "example": "xai-1234567890abcdef1234567890abcdef" } }, "required": [ "apikey" ] }, "XaiProviderRequest": { "type": "object", "description": "Request body for creating or replacing an xAI provider.", "properties": { "description": { "description": "A custom user-defined description for the model provider.", "example": "Some custom description string", "type": "string" }, "name": { "description": "Name can only contain alphanumeric characters, single spaces (no consecutive spaces), underscores (_), hyphens (-), parentheses (), and square brackets []. No leading or trailing spaces are allowed.", "example": "openai-prod", "type": "string" }, "data": { "$ref": "#/components/schemas/XaiConfig" }, "data_reference": { "$ref": "#/components/schemas/DataReference" } }, "required": [ "name" ] }, "CreateModelRequest": { "type": "object", "description": "A request to create a new model configuration for some provider.", "properties": { "id": { "type": "string", "description": "The unique identifier of a model, as specified by the model provider that its hosting and providing it. For example, ID could be `\"gpt-4.1\"` or a specific snapshot like `\"gpt-4.1-2025-04-14\"`, which are official server-side IDs for a model offered by the OpenAI provider.", "example": "gpt-3.5-turbo-456723" }, "alias": { "type": "string", "description": "An optional friendly name for the model. If not set, the default is the value of ID. The Alias can be used by clients to refer to that model in a more convenient or custom manner. When a client provides the alias (e.g., `\"my-gpt\"`) instead of the official name, the middleware will map the alias back to the underlying ID (e.g., `\"gpt-4.1-2025-04-14\"`) and execute requests against the correct model.", "example": "gpt-3.5-turbo" }, "description": { "type": "string", "description": "A custom user-defined description for the model.", "example": "Some custom description string" }, "metadata": { "$ref": "#/components/schemas/ModelMetadata" } }, "required": [ "id" ] }, "ReplaceModelRequest": { "type": "object", "description": "A request to replace the details of an existing model configuration. Any details not supplied will receive default values in the replaced configuration.", "properties": { "id": { "type": "string", "description": "The unique identifier of a model, as specified by the model provider that its hosting and providing it. For example, ID could be `\"gpt-4.1\"` or a specific snapshot like `\"gpt-4.1-2025-04-14\"`, which are official server-side IDs for a model offered by the OpenAI provider.", "example": "gpt-4.1-2025-04-14" }, "alias": { "type": "string", "description": "An optional friendly name for the model. If not set, the default is the value of ID. The Alias can be used by clients to refer to that model in a more convenient or custom manner. When a client provides the alias (e.g., `\"my-gpt\"`) instead of the official name, the middleware will map the alias back to the underlying ID (e.g., `\"gpt-4.1-2025-04-14\"`) and execute requests against the correct model.", "example": "my-gpt" }, "description": { "type": "string", "description": "A custom user-defined description for the model.", "example": "A custom description string" }, "metadata": { "$ref": "#/components/schemas/ModelMetadata" } }, "required": [ "id" ] }, "UpdateModelRequest": { "type": "object", "description": "A request to update the details for an existing model configuration. Only details supplied will be updated in the model configuration.", "properties": { "id": { "type": "string", "description": "The unique identifier of a model, as specified by the model provider that its hosting and providing it. For example, ID could be `\"gpt-4.1\"` or a specific snapshot like `\"gpt-4.1-2025-04-14\"`, which are official server-side IDs for a model offered by the OpenAI provider.", "example": "gpt-4.1-2025-04-14" }, "alias": { "type": "string", "description": "An optional friendly name for the model. If not set, the default is the value of ID. The Alias can be used by clients to refer to that model in a more convenient or custom manner. When a client provides the alias (e.g., `\"my-gpt\"`) instead of the official name, the middleware will map the alias back to the underlying ID (e.g., `\"gpt-4.1-2025-04-14\"`) and execute requests against the correct model.", "example": "my-gpt" }, "description": { "type": "string", "description": "A custom user-defined description for the model.", "example": "A custom description string" }, "metadata": { "$ref": "#/components/schemas/ModelMetadata" } }, "required": [ "id" ] }, "ModelCard": { "type": "object", "description": "Contains details on an available model through some provider. Does not describe a configured model instance, a tenant/user must still create a new configuration for this model on their provider if they choose to use it.", "properties": { "object": { "type": "string", "description": "The object type, which is always \"model\".", "enum": [ "model" ], "example": "model" }, "created": { "type": "integer", "description": "The UNIX timestamp (in seconds) when the model was created.", "format": "int64", "minimum": 0, "example": 1677649963 }, "id": { "type": "string", "description": "The model identifier, unique for the provider.", "example": "gpt-3.5-turbo-456723" }, "owned_by": { "type": "string", "description": "The provider that owns the model.\n\nFormat: \"provider type:provider name\"", "example": "openai:vllm4" } }, "required": [ "object", "created", "id", "owned_by" ] }, "ModelCardCollection": { "type": "object", "description": "A list of model cards containing info on models available for configuration.", "properties": { "object": { "type": "string", "description": "The object type, always \"list\".", "enum": [ "list" ], "example": "list" }, "data": { "type": "array", "description": "The array of model responses.", "items": { "$ref": "#/components/schemas/ModelCard" }, "minItems": 0, "maxItems": 1000 } }, "required": [ "object", "data" ] }, "LoadBalancersBackendStatus": { "type": "string", "description": "The status of the load balancer backend. Can be \"active\" or \"unhealthy\".", "enum": [ "active", "unhealthy" ], "example": "active" }, "LoadBalancersBackend": { "type": "object", "description": "A backend that supplies load balancing.", "properties": { "id": { "type": "string", "description": "The unique identifier for the backend.", "example": "backend-550e8400-e29b-41d4-a716-446655440000" }, "load_balancer_id": { "type": "string", "description": "The unique identifier of the load balancer this backend belongs to.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "model_uuid": { "type": "string", "description": "The UUID of the model used by this backend.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "model_id": { "type": "string", "description": "The model identifier as specified by the provider.", "example": "llama-3.3-70b" }, "provider_name": { "type": "string", "description": "The type of provider that hosts this model.", "example": "openai" }, "alias": { "type": "string", "description": "The alias of the model used by this backend.", "example": "my-custom-model" }, "status": { "$ref": "#/components/schemas/LoadBalancersBackendStatus" }, "priority": { "type": "integer", "format": "int64", "description": "The priority order used during quota-priority routing (lower values evaluated first).", "minimum": 0, "example": 0 }, "quota": { "type": "integer", "format": "int64", "description": "The quota for this backend when quota-priority strategy is used.\nZero means unlimited.", "minimum": 0, "example": 10 }, "weight": { "type": "integer", "format": "int64", "description": "The weight of this backend for weighted load balancing algorithms.", "minimum": 1, "example": 1 }, "created_at": { "type": "string", "format": "date-time", "description": "The Unix timestamp (in seconds) when the backend was created.", "example": "2023-03-01T12:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "The Unix timestamp (in seconds) when the backend was last updated.", "example": "2023-03-01T12:00:00Z" }, "request_count_24h": { "type": "integer", "format": "int64", "description": "The number of requests served by this model in the last 24 hours.", "minimum": 0, "example": 1523 }, "stats": { "type": "object", "description": "Additive 24-hour usage and effective rate-limit metadata for this backend.", "properties": { "avg_response_time_ms": { "type": "integer", "format": "int64", "description": "The average end-to-end response time in milliseconds.", "minimum": 0, "example": 102 }, "avg_dispatch_time_ms": { "type": "integer", "format": "int64", "description": "The average time in milliseconds from request receipt to first backend dispatch.", "minimum": 0, "example": 9 }, "num_retries": { "type": "integer", "format": "int64", "description": "The total number of transport retries recorded for requests served by this backend.", "minimum": 0, "example": 1 }, "num_load_balancer_fallbacks": { "type": "integer", "format": "int64", "description": "The total number of cross-load-balancer fallbacks recorded for requests served by this backend.", "minimum": 0, "example": 0 }, "rate_limit": { "type": "object", "description": "The effective rate limit currently applied to this backend, if any.", "properties": { "scope": { "type": "string", "description": "The scope that contributed the effective rate limit.", "example": "model" }, "request": { "type": "object", "description": "Effective request-count rate limit for this backend.", "properties": { "capacity": { "type": "integer", "format": "int64", "description": "Maximum number of request tokens the bucket can hold.", "minimum": 0, "example": 5000 }, "amount": { "type": "integer", "format": "int64", "description": "Number of request tokens refilled each interval.", "minimum": 0, "example": 5000 }, "duration_seconds": { "type": "integer", "format": "int64", "description": "Refill interval in seconds for request tokens.", "minimum": 0, "example": 60 } } }, "token": { "type": "object", "description": "Effective token-count rate limit for this backend.", "properties": { "capacity": { "type": "integer", "format": "int64", "description": "Maximum number of token credits the bucket can hold.", "minimum": 0, "example": 5000 }, "amount": { "type": "integer", "format": "int64", "description": "Number of token credits refilled each interval.", "minimum": 0, "example": 5000 }, "duration_seconds": { "type": "integer", "format": "int64", "description": "Refill interval in seconds for token credits.", "minimum": 0, "example": 60 } } } } } } } }, "required": [ "id", "load_balancer_id", "model_uuid", "model_id", "provider_name", "alias", "status", "priority", "quota", "weight", "created_at", "updated_at" ] }, "LoadBalancersLoadBalancer": { "type": "object", "description": "A load balancer object.", "properties": { "uuid": { "type": "string", "description": "The unique identifier for the load balancer.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "description": "The name of the load balancer.", "example": "My Load Balancer" }, "alias": { "type": "string", "description": "The alias that clients use to reference this load balancer.", "example": "my-custom-model" }, "algorithm": { "type": "string", "description": "The load balancing algorithm used for distributing requests.", "example": "least_connections" }, "config": { "type": "object", "description": "Algorithm-specific configuration parameters as raw JSON.", "additionalProperties": true }, "is_user_defined": { "type": "boolean", "description": "Indicates whether this load balancer was created by a user (true) or generated from model aliases (false).", "example": true }, "backends": { "type": "array", "description": "The list of backends associated with this load balancer.\nThis field is populated when requesting a specific load balancer or when explicitly requested.", "items": { "$ref": "#/components/schemas/LoadBalancersBackend" }, "minItems": 0, "maxItems": 100 }, "stats": { "type": "object", "description": "Optional usage and rate-limit statistics for this load balancer over the last 24 hours.", "properties": { "request_count_24h": { "type": "integer", "format": "int64", "description": "The total number of requests served by this load balancer in the last 24 hours.", "minimum": 0, "example": 1523 }, "avg_response_time_ms": { "type": "integer", "format": "int64", "description": "The average end-to-end response time in milliseconds.", "minimum": 0, "example": 107 }, "avg_dispatch_time_ms": { "type": "integer", "format": "int64", "description": "The average time in milliseconds from request receipt to first backend dispatch.", "minimum": 0, "example": 12 }, "num_retries": { "type": "integer", "format": "int64", "description": "The total number of transport retries recorded for requests served by this load balancer.", "minimum": 0, "example": 3 }, "num_load_balancer_fallbacks": { "type": "integer", "format": "int64", "description": "The total number of cross-load-balancer fallbacks recorded for requests served by this load balancer.", "minimum": 0, "example": 0 }, "has_rate_limit": { "type": "boolean", "description": "Indicates whether any backend in this load balancer currently has an effective rate limit.", "example": true }, "rate_limited_backend_count": { "type": "integer", "format": "int64", "description": "The number of backends in this load balancer that currently have an effective rate limit.", "minimum": 0, "example": 2 } } }, "created_at": { "type": "string", "format": "date-time", "description": "The Unix timestamp (in seconds) when the load balancer was created.", "example": "2023-03-01T12:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "The Unix timestamp (in seconds) when the load balancer was last updated.", "example": "2023-03-01T12:00:00Z" } }, "required": [ "uuid", "name", "alias", "algorithm", "is_user_defined", "created_at", "updated_at" ] }, "LoadBalancersLoadBalancerCollection": { "type": "object", "description": "A list of load balancers.", "properties": { "object": { "type": "string", "description": "The object type, which is always \"list\".", "enum": [ "list" ], "example": "list" }, "data": { "type": "array", "description": "The list of load balancers.", "items": { "$ref": "#/components/schemas/LoadBalancersLoadBalancer" }, "minItems": 0, "maxItems": 100 } }, "required": [ "object", "data" ] }, "LoadBalancersLoadBalancerConfig": { "type": "object", "description": "Optional algorithm-specific configuration parameters.\nThe structure of this object depends on the selected algorithm.", "properties": { "default_weight": { "type": "integer", "format": "int64", "description": "DefaultWeight is the default weight assigned to backends when using\nweighted algorithms\n\nUsed by: weighted_round_robin", "minimum": 1, "example": 1 } } }, "LoadBalancersModelAlgorithm": { "type": "string", "description": "The load balancing algorithm to use for distributing requests.\nSupported algorithms: \"least_connections\", \"weighted_round_robin\", \"round_robin\", \"quota_priority\"", "enum": [ "least_connections", "weighted_round_robin", "round_robin", "quota_priority" ], "example": "least_connections" }, "LoadBalancersBackendPrototype": { "type": "object", "description": "Request body for creating a load balancer backend.", "properties": { "model_uuid": { "type": "string", "description": "The UUID of the model to use as a backend (required).", "example": "550e8400-e29b-41d4-a716-446655440000" }, "priority": { "type": "integer", "format": "int64", "description": "Priority determines the evaluation order for quota-priority routing (lower values have higher priority).", "minimum": 0, "example": 0 }, "quota": { "type": "integer", "format": "int64", "description": "Optional quota for quota-priority strategy specifying the maximum number of concurrent connections.", "minimum": 0, "example": 10 }, "weight": { "type": "integer", "format": "int64", "description": "The weight for this backend in weighted load balancing algorithms.\nMust be a positive integer.", "example": 1, "minimum": 1 } }, "required": [ "model_uuid" ] }, "LoadBalancersLoadBalancerPrototype": { "type": "object", "description": "A request to create a new load balancer.", "properties": { "name": { "type": "string", "description": "A custom name for the new load balancer.", "example": "My Load Balancer" }, "alias": { "type": "string", "description": "The alias that clients will use to reference this load balancer.\nThis alias must be unique within the tenant and cannot conflict with existing model aliases.", "example": "my-custom-model" }, "config": { "$ref": "#/components/schemas/LoadBalancersLoadBalancerConfig" }, "algorithm": { "$ref": "#/components/schemas/LoadBalancersModelAlgorithm" }, "backends": { "type": "array", "description": "Optional list of backends to create along with the load balancer.\nIf provided, backends will be created in the same transaction as the load balancer.", "items": { "$ref": "#/components/schemas/LoadBalancersBackendPrototype" }, "minItems": 0, "maxItems": 100 } }, "required": [ "name", "alias", "algorithm" ] }, "LoadBalancersUpdateLoadBalancerRequest": { "type": "object", "description": "A request to update a load balancer.", "properties": { "name": { "type": "string", "description": "A new name for the load balancer.", "example": "Updated Load Balancer" }, "alias": { "type": "string", "description": "A new alias for the load balancer.", "example": "updated-custom-model" }, "algorithm": { "type": "string", "description": "The load balancing algorithm to use for distributing requests.\n\nSupported algorithms: \"least_connections\", \"weighted_round_robin\",\n\"round_robin\", \"quota_priority\"", "enum": [ "least_connections", "weighted_round_robin", "round_robin", "quota_priority" ], "example": "weighted_round_robin" }, "config": { "type": "object", "description": "Algorithm-specific configuration parameters.\nThe structure of this object depends on the selected algorithm.", "additionalProperties": true }, "backends": { "type": "array", "description": "Optional full replacement list of backends. When provided, all existing backends are removed and replaced in a single transaction.", "items": { "$ref": "#/components/schemas/LoadBalancersBackendPrototype" }, "minItems": 0, "maxItems": 100 } } }, "LoadBalancersBackendCollection": { "type": "object", "description": "A list of load balancer backends.", "properties": { "object": { "type": "string", "description": "The object type, always \"list\".", "enum": [ "list" ], "example": "list" }, "data": { "type": "array", "description": "The list of load balancer backends.", "items": { "$ref": "#/components/schemas/LoadBalancersBackend" }, "minItems": 0, "maxItems": 100 } }, "required": [ "object", "data" ] }, "LoadBalancersUpdateBackendRequest": { "type": "object", "description": "A request to update a backend in a load balancer.", "properties": { "priority": { "type": "integer", "format": "int64", "description": "Optional priority override for quota-priority routing (smaller numbers evaluated first).", "minimum": 0, "example": 0 }, "quota": { "type": "integer", "format": "int64", "description": "Optional quota override for quota-priority strategy.", "minimum": 1, "example": 5 }, "weight": { "type": "integer", "format": "int64", "description": "The new weight for this backend in weighted load balancing algorithms.\nMust be a positive integer.", "minimum": 1, "example": 2 } } }, "RateLimitItem": { "type": "object", "description": "Request rate limiting settings (per request origin).", "properties": { "amount": { "type": "integer", "format": "int64", "description": "Amount is the number of tokens refilled into the bucket each interval.", "minimum": 0, "example": 10 }, "capacity": { "type": "integer", "format": "int64", "description": "Capacity is the maximum number of tokens (requests) the bucket can hold.", "minimum": 0, "example": 100 }, "duration": { "type": "string", "description": "Duration is the refill interval, formatted as a Go duration string", "example": "1m" } }, "required": [ "amount", "capacity", "duration" ] }, "RateLimitTenant": { "type": "object", "description": "A rate limit for a tenant.", "properties": { "uuid": { "type": "string", "description": "Unique identifier for the rate limit.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "type": { "type": "string", "description": "The type of rate limit, in this case should always be `\"tenant\"`.", "enum": [ "tenant" ], "example": "tenant" }, "request": { "$ref": "#/components/schemas/RateLimitItem" }, "token": { "$ref": "#/components/schemas/RateLimitItem" } }, "required": [ "uuid", "type" ] }, "RateLimitProvider": { "type": "object", "description": "A rate limit object for a provider.", "properties": { "uuid": { "type": "string", "description": "Unique identifier for the rate limit.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "type": { "type": "string", "description": "The type of rate limit, in this case should always be `\"provider\"`.", "enum": [ "provider" ], "example": "provider" }, "provider_uuid": { "type": "string", "description": "Unique identifier for the provider being rate limited.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "token": { "$ref": "#/components/schemas/RateLimitItem" }, "request": { "$ref": "#/components/schemas/RateLimitItem" } }, "required": [ "uuid", "type", "provider_uuid" ] }, "RateLimitModel": { "type": "object", "description": "A rate limit object for a model.", "properties": { "uuid": { "type": "string", "description": "Unique identifier for the rate limit.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "type": { "type": "string", "description": "The type of rate limit, in this case should always be `\"model\"`.", "enum": [ "model" ], "example": "model" }, "model_uuid": { "type": "string", "description": "Unique identifier for the model being rate limited.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "request": { "$ref": "#/components/schemas/RateLimitItem" }, "token": { "$ref": "#/components/schemas/RateLimitItem" } }, "required": [ "uuid", "type", "model_uuid" ] }, "RateLimit": { "type": "object", "description": "A rate limit object. Either a tenant, provider, or model rate limit.", "anyOf": [ { "$ref": "#/components/schemas/RateLimitTenant" }, { "$ref": "#/components/schemas/RateLimitProvider" }, { "$ref": "#/components/schemas/RateLimitModel" } ] }, "RateLimitCollection": { "type": "object", "description": "A list of rate limits.", "properties": { "object": { "type": "string", "description": "The object type, which is always `\"list\"`.", "enum": [ "list" ], "example": "list" }, "data": { "type": "array", "description": "The list of objects.", "items": { "$ref": "#/components/schemas/RateLimit" }, "minItems": 0, "maxItems": 100 }, "has_more": { "type": "boolean", "description": "Whether there are more items in the list.", "example": true }, "next_page": { "type": "string", "description": "The URL of the next page of results.", "example": "https://gateway-url/v1/rate_limits?page=2" } }, "required": [ "object", "data" ] }, "RateLimitTenantPrototype": { "type": "object", "description": "A tenant rate limit request.", "properties": { "type": { "type": "string", "description": "The type of rate limit request, in this case should always be `\"tenant\"`.", "enum": [ "tenant" ], "example": "tenant" }, "request": { "$ref": "#/components/schemas/RateLimitItem" }, "token": { "$ref": "#/components/schemas/RateLimitItem" } }, "required": [ "type" ] }, "RateLimitProviderPrototype": { "type": "object", "description": "A provider rate limit request.", "properties": { "type": { "type": "string", "description": "The type of rate limit request, in this case should always be `\"provider\"`.", "enum": [ "provider" ], "example": "provider" }, "provider_uuid": { "type": "string", "description": "The unique identifier of the provider being rate limited.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "token": { "$ref": "#/components/schemas/RateLimitItem" }, "request": { "$ref": "#/components/schemas/RateLimitItem" } }, "required": [ "type", "provider_uuid" ] }, "RateLimitModelPrototype": { "type": "object", "description": "A model rate limit request.", "properties": { "type": { "type": "string", "description": "The type of rate limit request, in this case should always be `\"model\"`.", "enum": [ "model" ], "example": "model" }, "model_uuid": { "type": "string", "description": "The UUID of the model for which the rate limit is being requested.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "request": { "$ref": "#/components/schemas/RateLimitItem" }, "token": { "$ref": "#/components/schemas/RateLimitItem" } }, "required": [ "type", "model_uuid" ] }, "RateLimitPrototype": { "type": "object", "description": "A request to rate limit a resource.", "oneOf": [ { "$ref": "#/components/schemas/RateLimitTenantPrototype" }, { "$ref": "#/components/schemas/RateLimitProviderPrototype" }, { "$ref": "#/components/schemas/RateLimitModelPrototype" } ] }, "CreateResponseRequest": { "type": "object", "required": [ "model" ], "properties": { "model": { "type": "string", "example": "gpt-4.1", "description": "The model to use for generating the response" }, "input": { "description": "The input for response generation. Provide either a plain string or an array of input items.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "additionalProperties": true } } ] }, "instructions": { "type": "string", "description": "Instructions for the model" }, "max_output_tokens": { "type": "integer", "description": "Maximum number of tokens to generate" }, "max_tool_calls": { "type": "integer", "description": "Maximum number of tool calls allowed" }, "temperature": { "type": "number", "description": "Sampling temperature" }, "top_p": { "type": "number", "description": "Nucleus sampling parameter" }, "frequency_penalty": { "type": "number", "description": "Frequency penalty" }, "presence_penalty": { "type": "number", "description": "Presence penalty" }, "stream": { "type": "boolean", "description": "Whether to stream the response" }, "stream_options": { "$ref": "#/components/schemas/StreamOptions" }, "store": { "type": "boolean", "description": "Whether to store the response" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional metadata" }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Tools available for the model" }, "tool_choice": { "type": "object", "additionalProperties": true, "description": "Tool choice configuration" }, "parallel_tool_calls": { "type": "boolean", "description": "Whether to allow parallel tool calls" }, "reasoning": { "type": "object", "additionalProperties": true, "description": "Reasoning configuration" }, "text": { "type": "object", "additionalProperties": true, "description": "Text configuration" }, "background": { "type": "boolean", "description": "Whether to run in background" }, "include": { "type": "array", "items": { "type": "string" }, "description": "Fields to include in response" }, "previous_response_id": { "type": "string", "example": "resp_123", "description": "ID of previous response to continue from" }, "prompt_cache_key": { "type": "string", "description": "Cache key for prompt" }, "safety_identifier": { "type": "string", "description": "Safety identifier" }, "service_tier": { "type": "string", "description": "Service tier" }, "top_logprobs": { "type": "integer", "description": "Number of top log probabilities to return" }, "truncation": { "type": "string", "description": "Truncation strategy" } } }, "ResponseResource": { "type": "object", "description": "A response generated by the model gateway Responses API.", "required": [ "id", "object", "created_at", "model", "status", "output" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the response" }, "object": { "type": "string", "enum": [ "response" ], "example": "response", "description": "Object type" }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the response was created", "minimum": 0 }, "model": { "type": "string", "description": "The model used for the response" }, "status": { "type": "string", "description": "Status of the response (e.g., completed, in_progress, failed)" }, "output": { "type": "array", "minItems": 0, "maxItems": 1000, "items": { "type": "object", "additionalProperties": true }, "description": "The generated output items" }, "completed_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the response was completed", "minimum": 0 }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code returned by the model gateway." }, "message": { "type": "string", "description": "Human-readable error message." }, "param": { "type": "string", "description": "Request parameter related to the error, if applicable." }, "type": { "type": "string", "description": "Error category." } }, "required": [ "message" ], "description": "Error information if the response failed" }, "incomplete_details": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason the response is incomplete." } }, "description": "Details about why the response is incomplete" }, "instructions": { "type": "string", "description": "Instructions used for the model" }, "max_output_tokens": { "type": "integer", "format": "int64", "description": "Maximum number of tokens to generate", "minimum": 0 }, "max_tool_calls": { "type": "integer", "format": "int64", "description": "Maximum number of tool calls allowed", "minimum": 0 }, "temperature": { "type": "number", "description": "Sampling temperature used" }, "top_p": { "type": "number", "description": "Nucleus sampling parameter used" }, "frequency_penalty": { "type": "number", "description": "Frequency penalty used" }, "presence_penalty": { "type": "number", "description": "Presence penalty used" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional metadata" }, "tools": { "type": "array", "minItems": 0, "maxItems": 1000, "items": { "type": "object", "additionalProperties": true }, "description": "Tools that were available" }, "tool_choice": { "type": "object", "additionalProperties": true, "description": "Tool choice configuration used" }, "parallel_tool_calls": { "type": "boolean", "description": "Whether parallel tool calls were allowed" }, "reasoning": { "type": "object", "additionalProperties": true, "description": "Reasoning configuration used" }, "text": { "type": "object", "additionalProperties": true, "description": "Text configuration used" }, "background": { "type": "boolean", "description": "Whether the response ran in background" }, "previous_response_id": { "type": "string", "description": "ID of previous response this continued from" }, "prompt_cache_key": { "type": "string", "description": "Cache key for prompt" }, "safety_identifier": { "type": "string", "description": "Safety identifier" }, "service_tier": { "type": "string", "description": "Service tier used" }, "store": { "type": "boolean", "description": "Whether the response was stored" }, "top_logprobs": { "type": "integer", "format": "int64", "description": "Number of top log probabilities returned", "minimum": 0 }, "truncation": { "type": "string", "description": "Truncation strategy used" }, "usage": { "type": "object", "description": "Token usage information", "required": [ "input_tokens", "output_tokens", "total_tokens" ], "properties": { "input_tokens": { "type": "integer", "format": "int64", "description": "Number of input tokens billed for the response.", "minimum": 0 }, "output_tokens": { "type": "integer", "format": "int64", "description": "Number of output tokens generated by the response.", "minimum": 0 }, "total_tokens": { "type": "integer", "format": "int64", "description": "Total number of input and output tokens.", "minimum": 0 }, "input_tokens_details": { "type": "object", "description": "Breakdown of input token usage by token category.", "properties": { "cached_tokens": { "type": "integer", "description": "Number of input tokens served from cache.", "format": "int64", "minimum": 0 }, "text_tokens": { "type": "integer", "description": "Number of text input tokens.", "format": "int64", "minimum": 0 }, "audio_tokens": { "type": "integer", "description": "Number of audio input tokens.", "format": "int64", "minimum": 0 }, "image_tokens": { "type": "integer", "description": "Number of image input tokens.", "format": "int64", "minimum": 0 } } }, "output_tokens_details": { "type": "object", "description": "Breakdown of output token usage by token category.", "properties": { "reasoning_tokens": { "type": "integer", "description": "Number of output tokens used for reasoning.", "format": "int64", "minimum": 0 }, "audio_tokens": { "type": "integer", "description": "Number of audio output tokens.", "format": "int64", "minimum": 0 }, "accepted_prediction_tokens": { "type": "integer", "description": "Number of accepted predicted output tokens.", "format": "int64", "minimum": 0 }, "rejected_prediction_tokens": { "type": "integer", "description": "Number of rejected predicted output tokens.", "format": "int64", "minimum": 0 } } } } } } }, "UsageResultRow": { "type": "object", "description": "A single row of usage data with dynamic fields based on grouping and usage type.", "additionalProperties": true }, "BucketEntry": { "type": "object", "description": "A time bucket containing aggregated usage statistics", "required": [ "object", "start_time", "end_time", "results" ], "properties": { "object": { "type": "string", "description": "\"bucket\"", "example": "bucket" }, "start_time": { "type": "integer", "format": "int64", "description": "inclusive unix seconds", "minimum": 0, "maximum": 4102444800, "example": 1704067200 }, "end_time": { "type": "integer", "format": "int64", "description": "exclusive unix seconds", "minimum": 0, "maximum": 4102444800, "example": 1704153600 }, "results": { "type": "array", "description": "Array of usage result rows with aggregated data", "items": { "$ref": "#/components/schemas/UsageResultRow" }, "minItems": 0, "maxItems": 100 } } }, "BucketEntryCollection": { "type": "object", "description": "A paginated collection of usage bucket entries", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "description": "The object type, which is always `\"list\"`.", "enum": [ "list" ], "example": "list" }, "data": { "type": "array", "description": "The list of bucket entries.", "items": { "$ref": "#/components/schemas/BucketEntry" }, "minItems": 0, "maxItems": 100 }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available" }, "next_page": { "type": "string", "description": "Pagination cursor for the next page of results" } } }, "wxPromptResponse": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The prompt's id. This value cannot be set. It is returned in responses only.", "example": "1c29d9a1-9ba6-422d-aa39-517b26adc147" }, "name": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "Name used to display the prompt.", "example": "My Prompt" }, "description": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "An optional description for the prompt.", "example": "My First Prompt" }, "created_at": { "type": "integer", "description": "Time the prompt was created.", "example": 1711504485261 }, "created_by": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The ID of the original prompt creator.", "example": "IBMid-000000YYY0" }, "last_updated_at": { "type": "integer", "description": "Time the prompt was updated.", "example": 1711504485261 }, "last_updated_by": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The ID of the last user that modifed the prompt.", "example": "IBMid-000000YYY0" }, "task_ids": { "type": "array", "items": { "type": "string", "pattern": "[a-zA-Z0-9-]*" }, "minItems": 1, "maxItems": 1 }, "governance_tracked": { "type": "boolean" }, "lock": { "$ref": "#/components/schemas/promptLock" }, "input_mode": { "type": "string", "description": "Input mode in use for the prompt", "enum": [ "structured", "freeform", "chat", "detached" ] }, "model_version": { "type": "object", "properties": { "number": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", "description": "User provided semantic version for tracking in IBM AI Factsheets", "example": "2.0.0-rc.7" }, "tag": { "type": "string", "pattern": ".*", "description": "User provived tag.", "example": "tag" }, "description": { "type": "string", "pattern": ".*", "description": "Description of the version.", "example": "Description of the model version." } } }, "prompt_variables": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/promptVariable" } }, "is_template": { "type": "boolean" }, "resource_key": { "type": "string", "pattern": "[a-zA-Z0-9-]*" }, "prompt": { "$ref": "#/components/schemas/promptWithExternal" } }, "required": [ "name", "prompt" ] }, "wxPromptPost": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "Name used to display the prompt.", "example": "My Prompt" }, "description": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "An optional description for the prompt.", "example": "My First Prompt" }, "created_at": { "type": "integer", "description": "Time the prompt was created.", "example": 1711504485261 }, "task_ids": { "type": "array", "items": { "type": "string", "pattern": "[a-zA-Z0-9-]*" }, "minItems": 1, "maxItems": 1 }, "lock": { "$ref": "#/components/schemas/promptLock" }, "model_version": { "type": "object", "properties": { "number": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", "description": "User provided semantic version for tracking in IBM AI Factsheets", "example": "2.0.0-rc.7" }, "tag": { "type": "string", "pattern": ".*", "description": "User provived tag.", "example": "tag" }, "description": { "type": "string", "pattern": ".*", "description": "Description of the version.", "example": "Description of the model version." } } }, "prompt_variables": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/promptVariable" } }, "input_mode": { "type": "string", "description": "Input mode in use for the prompt", "enum": [ "structured", "freeform", "chat", "detached" ] }, "prompt": { "$ref": "#/components/schemas/promptWithExternal" } }, "required": [ "name", "prompt" ] }, "wxPromptPatch": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The prompt's id. This value cannot be set. It is returned in responses only.", "example": "1c29d9a1-9ba6-422d-aa39-517b26adc147" }, "name": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "Name used to display the prompt.", "example": "My Prompt" }, "description": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "An optional description for the prompt.", "example": "My First Prompt" }, "task_ids": { "type": "array", "items": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "example": "generation" }, "minItems": 1, "maxItems": 1 }, "governance_tracked": { "type": "boolean" }, "model_version": { "type": "object", "properties": { "number": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", "description": "User provided semantic version for tracking in IBM AI Factsheets", "example": "2.0.0-rc.7" }, "tag": { "type": "string", "pattern": ".*", "description": "User provived tag.", "example": "tag" }, "description": { "type": "string", "pattern": ".*", "description": "Description of the version.", "example": "Description of the model version." } } }, "prompt_variables": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/promptVariable" } }, "input_mode": { "type": "string", "description": "Input mode in use for the prompt", "enum": [ "structured", "freeform" ] }, "prompt": { "$ref": "#/components/schemas/prompt" } }, "required": [ "name", "prompt" ] }, "wxPromptSession": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "[a-zA-Z0-9-]{32}", "description": "The prompt session's id. This value cannot be set. It is returned in responses only.", "example": "1c29d9a1-9ba6-422d-aa39-517b26adc147" }, "name": { "type": "string", "pattern": "^.{0,100}$", "description": "Name used to display the prompt session.", "example": "Session 1" }, "description": { "type": "string", "pattern": "^[\\s\\S]{0,250}", "description": "An optional description for the prompt session.", "example": "My First Prompt Session" }, "created_at": { "type": "integer", "description": "Time the session was created.", "example": 1711504485261 }, "created_by": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The ID of the original session creator.", "example": "IBMid-000000YYY0" }, "last_updated_at": { "type": "integer", "description": "Time the session was updated.", "example": 1711504485261 }, "last_updated_by": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The ID of the last user that modifed the session.", "example": "IBMid-000000YYY0" }, "lock": { "$ref": "#/components/schemas/promptLock" }, "prompts": { "type": "array", "items": { "$ref": "#/components/schemas/wxPromptSessionEntry" }, "minItems": 0, "maxItems": 50 } }, "required": [ "name" ] }, "wxPromptSessionEntry": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The prompt's id. This value cannot be set. It is returned in responses only.", "example": "1c29d9a1-9ba6-422d-aa39-517b26adc147" }, "name": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "Name used to display the prompt.", "example": "My Prompt" }, "description": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "An optional description for the prompt.", "example": "My First Prompt" }, "prompt_variables": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/promptVariable" } }, "is_template": { "type": "boolean" }, "created_at": { "type": "integer", "description": "Time the prompt was created.", "example": 1711504485261 }, "input_mode": { "type": "string", "description": "Input mode in use for the prompt", "enum": [ "structured", "freeform", "chat" ] }, "prompt": { "$ref": "#/components/schemas/prompt" } }, "required": [ "name", "prompt", "created_at" ] }, "wxPromptSessionEntryList": { "type": "object", "additionalProperties": false, "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The prompt entry's ID", "example": "1c29d9a1-9ba6-422d-aa39-517b26adc147" }, "name": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The prompt entry's name", "example": "Name of an entry" }, "description": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The prompt entry's description", "example": "Description of an entry" }, "created_at": { "type": "integer", "description": "The prompt entry's create time in millis", "example": 1711504485261 } } } }, "bookmark": { "type": "string", "pattern": "[a-zA-Z0-9-]*" } } }, "prompt": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "array", "items": { "type": "array", "items": { "type": "string", "pattern": "[a-zA-Z0-9-]*" }, "minItems": 2, "maxItems": 2 }, "default": [] }, "model_id": { "type": "string", "pattern": "[a-zA-Z0-9-//]*", "example": "ibm/granite-13b-chat-v2" }, "model_parameters": { "type": "object", "properties": { "decoding_method": { "type": "string", "pattern": "[a-zA-Z0-9-]*" }, "max_new_tokens": { "type": "integer" }, "min_new_tokens": { "type": "integer" }, "random_seed": { "type": "integer" }, "stop_sequences": { "type": "array", "items": { "type": "string", "pattern": "[a-zA-Z0-9-]*" } }, "temperature": { "type": "number" }, "top_k": { "type": "number" }, "top_p": { "type": "number" }, "repetition_penalty": { "type": "number" } } }, "data": { "$ref": "#/components/schemas/promptData" }, "system_prompt": { "type": "string", "pattern": "[a-zA-Z0-9-]*" }, "chat_items": { "type": "array", "items": { "$ref": "#/components/schemas/chatItem" } } }, "required": [ "model_id", "data" ] }, "promptWithExternal": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "array", "items": { "type": "array", "items": { "type": "string", "pattern": "[a-zA-Z0-9-]*" }, "minItems": 2, "maxItems": 2 }, "default": [] }, "model_id": { "type": "string", "pattern": "[a-zA-Z0-9-//]*", "example": "ibm/granite-13b-chat-v2" }, "model_parameters": { "type": "object", "properties": { "decoding_method": { "type": "string", "pattern": "[a-zA-Z0-9-]*" }, "max_new_tokens": { "type": "integer" }, "min_new_tokens": { "type": "integer" }, "random_seed": { "type": "integer" }, "stop_sequences": { "type": "array", "items": { "type": "string", "pattern": "[a-zA-Z0-9-]*" } }, "temperature": { "type": "number" }, "top_k": { "type": "number" }, "top_p": { "type": "number" }, "repetition_penalty": { "type": "number" } } }, "data": { "$ref": "#/components/schemas/promptData" }, "system_prompt": { "type": "string", "pattern": "[a-zA-Z0-9-]*" }, "chat_items": { "type": "array", "items": { "$ref": "#/components/schemas/chatItem" } }, "external_information": { "$ref": "#/components/schemas/externalInformation" } }, "required": [ "model_id", "data" ] }, "externalInformation": { "type": "object", "additionalProperties": false, "properties": { "external_prompt_id": { "type": "string", "pattern": ".*" }, "external_model_id": { "type": "string", "pattern": ".*" }, "external_model_provider": { "type": "string", "pattern": ".*" }, "external_prompt": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "pattern": ".*" }, "additional_information": { "type": "array", "items": { "$ref": "#/components/schemas/externalPromptAdditionalInformation" }, "minItems": 1 } }, "required": [ "url" ] }, "external_model": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": ".*" }, "url": { "type": "string", "pattern": ".*" } }, "required": [ "name", "url" ] } }, "required": [ "external_prompt_id", "external_model_id", "external_model_provider" ] }, "externalPromptAdditionalInformation": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "key": { "type": "string", "pattern": "^[\\s\\S]{0,250}$" } } }, "example": [ { "key": "value" }, { "key": "value" } ] }, "chatItem": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "question", "answer" ] }, "content": { "type": "string", "pattern": ".*", "example": "Some text" }, "status": { "type": "string", "enum": [ "ready", "error" ] }, "timestamp": { "type": "integer", "example": 1711504485261 } } }, "promptData": { "type": "object", "additionalProperties": false, "properties": { "instruction": { "type": "string", "pattern": "[\\s\\S]*" }, "input_prefix": { "type": "string", "pattern": "[\\s\\S]*" }, "output_prefix": { "type": "string", "pattern": "[\\s\\S]*" }, "examples": { "type": "array", "items": { "type": "array", "items": { "type": "string", "pattern": "^[\\s\\S]*" }, "minItems": 2, "maxItems": 2 }, "default": [] } } }, "promptLock": { "type": "object", "additionalProperties": false, "properties": { "locked": { "type": "boolean", "description": "True if the prompt is currently locked." }, "lock_type": { "type": "string", "description": "Lock type: 'edit' for working on prompts/templates or 'governance'. Can only be supplied in PUT /lock requests.", "enum": [ "edit", "governance" ] }, "locked_by": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "Locked by is computed by the server and shouldn't be passed.", "example": "IBMid-000000YYY0" } }, "required": [ "locked" ] }, "wxPromptInputRequest": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "string", "pattern": ".*", "description": "Override input string that will be used to generate the response. The string can contain template parameters.", "example": "Some text with variables." }, "prompt_variables": { "type": "object", "description": "Supply only to replace placeholders. Object content must be key:value pairs where the 'key' is the parameter to replace and 'value' is the value to use.", "additionalProperties": { "$ref": "#/components/schemas/promptVariableString" } } } }, "promptVariable": { "type": "object", "additionalProperties": true }, "promptVariableString": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "example": "var1" }, "vectorIndexResponse": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The vector index's id. This value cannot be set. It is returned in responses only.", "example": "12c45f78-a2b4-1b3d-aa2c-zy09y87w6a3a" }, "name": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "Name used to display the vector index.", "example": "My vector index" }, "description": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "An optional description for the vector index asset.", "example": "My first vector index" }, "created_at": { "type": "integer", "description": "Time the vector index was created.", "example": 1711504485261 }, "created_by": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The ID of the original vector index creator.", "example": "IBMid-000000YYY0" }, "last_updated_at": { "type": "integer", "description": "Time the vector index was updated.", "example": 1711504485261 }, "last_updated_by": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The ID of the last user that modifed the vector index.", "example": "IBMid-000000YYY0" }, "data_assets": { "type": "array", "description": "The IDs of the associated data assets used in the vector index.", "items": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "example": "713259df-0540-4301-982e-693a81da462c" }, "example": [ "713259df-0540-4301-982e-693a81da462c", "713259df-0540-4301-982e-693a81da573d" ] }, "store": { "oneOf": [ { "$ref": "#/components/schemas/externalVectorStore" }, { "$ref": "#/components/schemas/inMemoryVectorStore" } ] }, "settings": { "oneOf": [ { "$ref": "#/components/schemas/externalStoreSettings" }, { "$ref": "#/components/schemas/inMemorySettings" } ] }, "build": { "type": "object", "description": "The associated build to process the data for external vector stores", "properties": { "notebook_id": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The ID of the associated notebook.", "example": "12c45f78-a2b4-1b3d-aa2c-zy09y87w6a3a" }, "job_id": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The ID of the associated job run.", "example": "12c45f78-a2b4-1b3d-aa2c-zy09y87w6a3a" } } }, "status": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The status of the vector index.", "example": "ready" }, "sample_questions": { "type": "array", "items": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "example": "Summarize the document" }, "maxItems": 6, "description": "Frequently asked questions", "example": [ "summarize the document, name of the author" ] } } }, "vectorIndexStatusResponse": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "description": "Current status of vector index", "enum": [ "STARTING", "PENDING", "READY", "RUNNING", "COMPLETED", "FAILED" ] }, "asset": { "type": "object", "description": "The vector asset data", "properties": { "id": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The vector index's id. This value cannot be set. It is returned in responses only.", "example": "12c45f78-a2b4-1b3d-aa2c-zy09y87w6a3a" }, "name": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "Name used to display the vector index.", "example": "My vector index" }, "description": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "An optional description for the vector index asset.", "example": "My first vector index" }, "created_at": { "type": "integer", "description": "Time the vector index was created.", "example": 1711504485261 }, "created_by": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The ID of the original vector index creator.", "example": "IBMid-000000YYY0" }, "last_updated_at": { "type": "integer", "description": "Time the vector index was updated.", "example": 1711504485261 }, "last_updated_by": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The ID of the last user that modifed the vector index.", "example": "IBMid-000000YYY0" }, "data_assets": { "type": "array", "description": "The IDs of the associated data assets used in the vector index.", "items": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "example": "713259df-0540-4301-982e-693a81da462c" }, "example": [ "713259df-0540-4301-982e-693a81da462c", "713259df-0540-4301-982e-693a81da573d" ] }, "store": { "oneOf": [ { "$ref": "#/components/schemas/externalVectorStore" }, { "$ref": "#/components/schemas/inMemoryVectorStore" } ] }, "settings": { "oneOf": [ { "$ref": "#/components/schemas/externalStoreSettings" }, { "$ref": "#/components/schemas/inMemorySettings" } ] }, "build": { "type": "object", "description": "The associated build to process the data for external vector stores", "properties": { "notebook_id": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The ID of the associated notebook.", "example": "12c45f78-a2b4-1b3d-aa2c-zy09y87w6a3a" }, "job_id": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The ID of the associated job run.", "example": "12c45f78-a2b4-1b3d-aa2c-zy09y87w6a3a" } } }, "status": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The status of the vector index.", "example": "ready" }, "sample_questions": { "type": "array", "items": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "example": "Summarize the document" }, "maxItems": 6, "description": "Frequently asked questions", "example": [ "summarize the document, name of the author" ] } } } } }, "wxVectorIndexPatch": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "Name used to display the vector index.", "example": "My vector index" }, "description": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "An optional description for the vector index asset.", "example": "My first vector index" }, "data_assets": { "type": "array", "description": "The IDs of the associated data assets used in the vector index.", "items": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "example": "713259df-0540-4301-982e-693a81da462c" }, "example": [ "713259df-0540-4301-982e-693a81da462c", "713259df-0540-4301-982e-693a81da573d" ] }, "store": { "oneOf": [ { "$ref": "#/components/schemas/externalVectorStore" }, { "$ref": "#/components/schemas/inMemoryVectorStore" } ] }, "settings": { "oneOf": [ { "$ref": "#/components/schemas/externalStoreSettings" }, { "$ref": "#/components/schemas/inMemorySettings" } ] }, "build": { "type": "object", "description": "The associated build to process the data for external vector stores", "properties": { "notebook_id": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The ID of the associated notebook.", "example": "12c45f78-a2b4-1b3d-aa2c-zy09y87w6a3a" }, "job_id": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The ID of the associated job run.", "example": "12c45f78-a2b4-1b3d-aa2c-zy09y87w6a3a" } } }, "status": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The status of the vector index.", "example": "ready" }, "sample_questions": { "type": "array", "items": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "example": "Summarize the document" }, "maxItems": 6, "description": "Frequently asked questions", "example": [ "summarize the document, name of the author" ] } } }, "wxVectorIndexPost": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "Name used to display the vector index.", "example": "My vector index" }, "description": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "An optional description for the vector index asset.", "example": "My first vector index" }, "data_assets": { "type": "array", "description": "The IDs of the associated data assets used in the vector index.", "items": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "example": "713259df-0540-4301-982e-693a81da462c" }, "example": [ "713259df-0540-4301-982e-693a81da462c", "713259df-0540-4301-982e-693a81da573d" ] }, "store": { "oneOf": [ { "$ref": "#/components/schemas/externalVectorStore" }, { "$ref": "#/components/schemas/inMemoryVectorStore" } ] }, "settings": { "oneOf": [ { "$ref": "#/components/schemas/externalStoreSettings" }, { "$ref": "#/components/schemas/inMemorySettings" } ] }, "build": { "type": "object", "description": "The associated build to process the data for external vector stores. REQUIRED FOR EXTERNAL VECTOR STORES", "properties": { "notebook_id": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The ID of the associated notebook.", "example": "12c45f78-a2b4-1b3d-aa2c-zy09y87w6a3a" }, "job_id": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The ID of the associated job run.", "example": "12c45f78-a2b4-1b3d-aa2c-zy09y87w6a3a" } } }, "sample_questions": { "type": "array", "items": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "example": "Summarize the document" }, "maxItems": 6, "description": "Frequently asked questions", "example": [ "summarize the document, name of the author" ] } }, "required": [ "name", "build", "data_assets", "store", "settings" ] }, "wxVectorIndexPut": { "type": "object", "additionalProperties": false, "properties": { "object_key": { "type": "string", "pattern": "vector_index/[a-zA-Z0-9-]__da__*.gz", "description": "The object key of the gzipped file, that is available in the attached COS Bucket.", "example": "vector_index/myvectorindex__da__vi82w8pghq.gz" } }, "example": { "object_key": "vector_index/canadaConstitution__da__5bpykqpyzx.gz" } }, "wxVectorIndexTransactionalPost": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "Name used to display the vector index.", "example": "My vector index" }, "description": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "An optional description for the vector index asset.", "example": "My first vector index" }, "data_assets": { "type": "array", "description": "The IDs of the associated data assets used in the vector index.", "items": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "example": "713259df-0540-4301-982e-693a81da462c" }, "example": [ "713259df-0540-4301-982e-693a81da462c", "713259df-0540-4301-982e-693a81da573d" ] }, "store": { "oneOf": [ { "$ref": "#/components/schemas/externalVectorStore" }, { "$ref": "#/components/schemas/inMemoryVectorStore" } ] }, "settings": { "oneOf": [ { "$ref": "#/components/schemas/externalStoreSettings" }, { "$ref": "#/components/schemas/inMemorySettings" } ] }, "sample_questions": { "type": "array", "items": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "example": "Summarize the document" }, "maxItems": 6, "description": "Frequently asked questions", "example": [ "summarize the document, name of the author" ] } }, "required": [ "name", "data_assets", "store", "settings" ] }, "externalStoreSettings": { "type": "object", "properties": { "chunk_size": { "type": "number", "minimum": 100, "maximum": 10000, "description": "The number of text (or tokens) that are grouped together before converting into a vector." }, "chunk_overlap": { "type": "number", "minimum": 0, "maximum": 2000, "description": "The number of characters to overlap for chunking data" }, "top_k": { "type": "number", "minimum": 1, "maximum": 10, "description": "number of most similar results to retrieve (lower values lead to greater similarity between the question and answer)" }, "split_pdf_pages": { "type": "boolean" }, "rerank": { "type": "boolean" }, "embedding_model_id": { "type": "string", "pattern": "[a-zA-Z0-9-//]*", "example": "sentence-transformers/all-minilm-l6-v2" }, "schema_fields": { "type": "object", "properties": { "document_name": { "type": "string", "description": "Field to use for finding the document name.", "pattern": "[a-zA-Z0-9-//]*", "example": "document_name" }, "text": { "type": "string", "description": "Field to use for the text in the document.", "pattern": "[a-zA-Z0-9-//]*", "example": "text" }, "page_number": { "type": "string", "description": "Field to use for finding the document page number.", "pattern": "[a-zA-Z0-9-//]*", "example": "page" }, "vector_query": { "type": "string", "description": "The vector_query_field that contains the text_expansion query. Only applicable for Elasticsearch", "pattern": "[a-zA-Z0-9-//]*", "example": "vector" }, "document_url": { "type": "string", "description": "The optional field that contains a url for the document.", "pattern": "[a-zA-Z0-9-//]*", "example": "documentURL" } } } } }, "inMemorySettings": { "type": "object", "properties": { "chunk_size": { "type": "number", "description": "The number of text (or tokens) that are grouped together before converting into a vector.", "minimum": 100, "maximum": 10000 }, "chunk_overlap": { "type": "number", "description": "The number of characters to overlap for chunking data", "minimum": 0, "maximum": 2000 }, "top_k": { "type": "number", "minimum": 1, "maximum": 10, "description": "number of most similar results to retrieve (lower values lead to greater similarity between the question and answer)" }, "split_pdf_pages": { "type": "boolean" }, "rerank": { "type": "boolean" }, "embedding_model_id": { "type": "string", "pattern": "[a-zA-Z0-9-//]*", "example": "sentence-transformers/all-minilm-l6-v2" } } }, "inMemoryVectorStore": { "title": "inMemoryVectorStore", "type": "string", "description": "vector store for in-memory vector index", "pattern": "memory", "example": "memory" }, "externalVectorStore": { "type": "object", "description": "External vector store. (elasticsearch or watsonx.data)", "properties": { "type": { "type": "string", "description": "The type of the vector store", "example": "watsonx.data" }, "connection_id": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The ID of the external store connection.", "example": "1c29d9a1-9ba6-422d-aa39-517b26adc147" }, "index": { "type": "string", "pattern": "[a-zA-Z0-9-]*", "description": "The name of the index in the vector store", "example": "wx_my_sample_collection" }, "new_index": { "type": "boolean", "description": "To determine if a new index was used." }, "database": { "type": "string", "description": "Name of the database", "enum": [ "default", "rag" ] } }, "required": [ "type", "connection_id", "index", "new_index", "database" ] }, "NotebookInProject": { "description": "Notebook information in a project as returned by a GET request.", "properties": { "metadata": { "$ref": "#/components/schemas/NotebookMetadataInProject" }, "entity": { "$ref": "#/components/schemas/NotebookEntity" } } }, "NotebooksResourceList": { "description": "A list of notebook info as returned by a list query.", "required": [ "total_results", "resources" ], "properties": { "total_results": { "type": "integer", "description": "The number of items in the resources list.", "example": 1 }, "resources": { "type": "array", "description": "An array of notebooks.", "items": { "$ref": "#/components/schemas/NotebookResource" } } } }, "Notebook": { "description": "Notebook information as returned by a GET request.", "properties": { "metadata": { "$ref": "#/components/schemas/NotebookMetadata" }, "entity": { "$ref": "#/components/schemas/NotebookEntity" } } }, "NotebookForCopy": { "description": "Information of a copied notebook as returned by a GET request.", "properties": { "metadata": { "$ref": "#/components/schemas/NotebookMetadataInProject" }, "entity": { "$ref": "#/components/schemas/NotebookEntityForCopy" } } }, "NotebookMetadata": { "description": "Metadata of a notebook.", "properties": { "name": { "type": "string", "description": "The name of the notebook.", "example": "my notebook" }, "description": { "type": "string", "description": "A more verbose description.", "example": "this is my notebook" }, "asset_type": { "type": "string", "description": "Asset type, always \"notebook\".", "example": "notebook" }, "created": { "type": "integer", "description": "Creation date, ms since epoch.", "example": 1540471021134 }, "created_at": { "type": "string", "description": "Creation date, ISO format.", "example": "2018-10-25T12:37:01Z" }, "owner_id": { "type": "string", "description": "IAM ID of the asset's owner.", "example": "IBMid-310000SG2Y" }, "catalog_id": { "type": "string", "description": "UUID of the asset's catalog.", "example": "463cb8d8-8480-4a98-b75a-f7443b7d0af9" }, "asset_id": { "type": "string", "description": "UUID of the asset.", "example": "41d09a9a-f771-48a2-9534-50c0c622356d" } } }, "NotebookMetadataInProject": { "description": "Metadata of a notebook in a project.", "allOf": [ { "$ref": "#/components/schemas/NotebookMetadata" }, { "required": [ "project_id" ], "properties": { "project_id": { "type": "string", "description": "UUID of the asset's project.", "example": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf" } } } ] }, "NotebookEntity": { "description": "Entity of a notebook.", "properties": { "notebook": { "$ref": "#/components/schemas/NotebookEntityDefinition" }, "runtime": { "$ref": "#/components/schemas/NotebookRuntime" }, "href": { "type": "string", "description": "Full URI of the notebook.", "example": "/v2/assets/41d09a9a-f771-48a2-9534-50c0c622356d?project_id=b275be5f-10ff-47ee-bfc9-63f1ce5addbf" } } }, "NotebookEntityForCopy": { "description": "Entity of a notebook copied from a source.", "properties": { "notebook": { "$ref": "#/components/schemas/NotebookEntityDefinitionForCopy" }, "runtime": { "$ref": "#/components/schemas/NotebookRuntime" }, "href": { "type": "string", "description": "Full URI of the notebook.", "example": "/v2/assets/41d09a9a-f771-48a2-9534-50c0c622356d?project_id=b275be5f-10ff-47ee-bfc9-63f1ce5addbf" } } }, "NotebookEntityDefinition": { "description": "Definition part of a notebook entity.", "properties": { "kernel": { "$ref": "#/components/schemas/NotebookKernel" }, "originates_from": { "$ref": "#/components/schemas/NotebookOrigin" } } }, "NotebookEntityDefinitionForCopy": { "description": "Definition part of a notebook entity copied from a source.", "properties": { "kernel": { "$ref": "#/components/schemas/NotebookKernel" }, "originates_from": { "$ref": "#/components/schemas/NotebookOriginFromSource" } } }, "NotebookResource": { "description": "Notebook info returned in a listing.", "properties": { "metadata": { "$ref": "#/components/schemas/NotebookResourceMetadata" }, "entity": { "$ref": "#/components/schemas/NotebookResourceEntity" } } }, "NotebookResourceMetadata": { "description": "Metadata of notebook info returned in a listing.", "properties": { "guid": { "type": "string", "description": "UUID of the notebook.", "example": "299993bf-9a42-48ae-aadd-1336f31d5556" }, "url": { "type": "string", "description": "URL of the notebook.", "example": "/v2/notebooks/299993bf-9a42-48ae-aadd-1336f31d5556" } } }, "NotebookResourceEntity": { "description": "Entity of notebook info returned in a listing.", "properties": { "asset": { "$ref": "#/components/schemas/NotebookResourceEntityAsset" }, "runtime": { "$ref": "#/components/schemas/NotebookResourceEntityRuntime" } } }, "NotebookResourceEntityAsset": { "description": "Asset API asset description returned with a notebook listing.", "properties": { "asset_id": { "type": "string", "description": "The UUID of the asset.", "example": "41d09a9a-f771-48a2-9534-50c0c622356d" }, "asset_type": { "type": "string", "description": "The asset type. Always \"notebook\".", "example": "notebook" }, "created": { "type": "integer", "description": "Timestamp of the creation date, ms since epoch.", "example": 1540471021134 }, "created_at": { "type": "string", "description": "Date the asset was created, ISO format.", "example": "2018-10-25T12:37:01Z" }, "catalog_id": { "type": "string", "description": "The asset catalog ID.", "example": "463cb8d8-8480-4a98-b75a-f7443b7d0af9" }, "project_id": { "type": "string", "description": "The project the notebook belongs to.", "example": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf" }, "version": { "type": "integer", "description": "Version of the asset.", "example": 2 }, "href": { "type": "string", "description": "The asset URL.", "example": "/v2/assets/299993bf-9a42-48ae-aadd-1336f31d5556?project_id=850d08c4-31f1-4722-a7ef-eeefd796e995" } } }, "NotebookResourceEntityRuntime": { "description": "Runtime info returned with a notebook listing.", "properties": { "spark_monitoring_enabled": { "type": "boolean", "description": "If Spark monitoring is enabled.", "example": true }, "environment": { "type": "string", "description": "UUID of the environment of the notebook.", "example": "conda4x16-850d08c4-31f1-4722-a7ef-eeefd796e995" } } }, "NotebookCreateBodyInProject": { "description": "Payload for creating a notebook in a project.", "allOf": [ { "$ref": "#/components/schemas/NotebookCreateBodyGeneral" }, { "required": [ "project" ], "properties": { "project": { "type": "string", "description": "The guid of the project in which to create the notebook.", "example": "92ae0e27-9b11-4de9-a646-d46ca3c183d4", "x-cli-option-name": "project-id" } } } ] }, "NotebookCreateBodyGeneral": { "description": "Payload for creating a notebook.", "required": [ "name", "file_reference", "runtime" ], "properties": { "name": { "type": "string", "description": "The name of the new notebook.", "example": "my notebook" }, "description": { "type": "string", "description": "A more verbose description of the notebook.", "example": "this is my notebook" }, "file_reference": { "type": "string", "description": "The reference to the file in the object storage.", "example": "notebook/my_notebook.ipynb" }, "originates_from": { "$ref": "#/components/schemas/NotebookOrigin" }, "runtime": { "$ref": "#/components/schemas/NotebookRuntime" }, "kernel": { "$ref": "#/components/schemas/NotebookKernel" } } }, "NotebookCopyBody": { "description": "Payload for copying a notebook.", "required": [ "source_guid", "name" ], "properties": { "name": { "type": "string", "description": "The name of the new notebook.", "example": "my notebook" }, "source_guid": { "type": "string", "description": "The guid of the notebook to be copied.", "example": "ca3c0e27-46ca-83d4-a646-d49b11c14de9" } } }, "NotebookRevertBody": { "description": "Payload for a request to revert to a specific notebook version.", "required": [ "source" ], "properties": { "source": { "type": "string", "description": "The guid of the notebook version.", "example": "ca3c0e27-46ca-83d4-a646-d49b11c14de9" } } }, "NotebookOrigin": { "description": "The notebook origin.", "properties": { "type": { "type": "string", "description": "The orgin type of the notebook, either blank, file or url.", "example": "blank" } } }, "NotebookOriginFromSource": { "description": "The origin of a notebook from a source.", "properties": { "type": { "type": "string", "description": "The orgin type of the notebook, either blank, file or url.", "example": "notebook" }, "guid": { "type": "string", "description": "The guid of the source file", "example": "ca3c0e27-46ca-83d4-a646-d49b11c14de9" } } }, "NotebookRuntime": { "description": "A notebook runtime.", "required": [ "environment" ], "properties": { "environment": { "type": "string", "description": "The guid of the environment on which the notebook runs.", "example": "conda4x16-d46ca0e27-a646-4de9-a646-9b113c183d4" }, "spark_monitoring_enabled": { "type": "boolean", "description": "Spark monitoring enabled or not." } } }, "NotebookKernel": { "description": "A notebook kernel.", "properties": { "display_name": { "type": "string", "description": "The display name of the environment kernel.", "example": "Python 3.9 with Spark" }, "name": { "type": "string", "description": "The name of the environment kernel.", "example": "python3" }, "language": { "type": "string", "description": "The language of the environment kernel.", "example": "python3" } } }, "NotebookListBody": { "description": "Payload for a notebook list request.", "properties": { "notebooks": { "type": "array", "description": "The list of notebooks whose details will be retrieved.", "items": { "type": "string", "description": "The guid of the notebook.", "example": "ca3c0e27-46ca-83d4-a646-d49b11c14de9" } } } }, "NotebookUpdateBody": { "description": "Payload for a notebook update request.", "properties": { "environment": { "type": "string", "description": "The guid of the environment on which the notebook runs.", "example": "d46ca0e27-a646-4de9-a646-9b113c183d4" }, "spark_monitoring_enabled": { "type": "boolean", "description": "Spark monitoring enabled or not.", "example": false }, "kernel": { "$ref": "#/components/schemas/NotebookKernel" } } }, "NotebookVersionInProject": { "description": "A notebook version in a project.", "properties": { "metadata": { "$ref": "#/components/schemas/NotebookVersionMetadata" }, "entity": { "$ref": "#/components/schemas/NotebookVersionEntityInProject" } } }, "NotebookVersionMetadata": { "description": "Notebook version metadata.", "properties": { "guid": { "type": "string", "description": "The guid of the version.", "example": "19d63b6b-81a1-4c05-bad2-36a2957bd6d0" }, "url": { "type": "string", "description": "The URL of the version.", "example": "v2/notebooks/a528b427-d1cd-4039-8ddc-04203c2521e2/versions/1a1329e0-fd05-409a-8411-52db106e2142" }, "created_at": { "type": "integer", "description": "The creation timestamp in UTC millisecond since UNIX Epoch time.", "example": 1543681714106 } } }, "NotebookVersionEntity": { "description": "A notebook version entity.", "properties": { "master_notebook_guid": { "type": "string", "description": "The guid of the versioned notebook.", "example": "a528b427-d1cd-4039-8ddc-04203c2521e2" }, "created_by_iui": { "type": "string", "description": "The IUI of the user that has created the version.", "example": "IBMid-123456ABCD" }, "file_reference": { "type": "string", "description": "The file reference in the corresponding COS.", "example": "myproject-donotdelete-pr-6p65nym92j1bv0/notebooks/GPU_ENVIRONMENT_DEFAULT_GBUXVKHH_version_1543781324804.ipynb" }, "rev_id": { "type": "integer", "description": "The revision id of the notebook.", "example": 1 } } }, "NotebookVersionEntityInProject": { "description": "A notebook version entity in a project.", "allOf": [ { "$ref": "#/components/schemas/NotebookVersionEntity" }, { "required": [ "project_id" ], "properties": { "project_id": { "type": "string", "description": "The guid of the project.", "example": "0f7c1111-a79d-45b2-9699-d4950e742964" } } } ] }, "NotebookVersionsListInProject": { "description": "A list of notebook versions in a project.", "required": [ "total_results", "resources" ], "properties": { "total_results": { "description": "The number of items in the resources array.", "type": "integer", "example": 1 }, "resources": { "description": "An array of notebook versions.", "type": "array", "items": { "$ref": "#/components/schemas/NotebookVersionInProject" } } } }, "ErrorResponse": { "description": "An error response.", "required": [ "trace", "errors" ], "properties": { "trace": { "description": "The trace ID used in logs.", "type": "string" }, "errors": { "description": "The error objects.", "type": "array", "items": { "$ref": "#/components/schemas/Error" } } } }, "Error": { "description": "An error object.", "required": [ "code", "message" ], "properties": { "code": { "description": "The code describing the error.", "type": "string" }, "message": { "description": "The detailed information about the error.", "type": "string" }, "target": { "$ref": "#/components/schemas/ErrorTarget" } } }, "ErrorTarget": { "description": "The target of the error.", "required": [ "type", "name" ], "properties": { "type": { "description": "The type of the problematic field.", "type": "string", "enum": [ "field", "query", "header" ] }, "name": { "description": "The name of the problematic field.", "type": "string" } } }, "wxUtilityAgentToolsResponse": { "type": "object", "additionalProperties": false, "properties": { "resources": { "type": "array", "items": { "$ref": "#/components/schemas/utilityAgentTool" } } }, "required": [ "resources" ] }, "utilityAgentTool": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Name of the tool", "example": "GoogleSearch" }, "description": { "type": "string", "description": "A plain text description of what the tool is used for.", "example": "Search for online trends, news, current events, real-time information, or research topics." }, "agent_description": { "type": "string", "description": "The precise instruction to agent LLMs and should be treated as part of the system prompt. If not provided, `description` can be used in it's place.", "example": "Search for online trends, news, current events, real-time information, or research topics." }, "input_schema": { "type": "object", "additionalProperties": true, "properties": {}, "description": "The JSON schema of the input that is provided when running the tool if applicable." }, "config_schema": { "type": "object", "additionalProperties": true, "properties": {}, "description": "The JSON schema of the config that can be provided when running the tool if applicable.", "example": { "title": "config schema for GoogleSearch tool", "type": "object", "properties": { "maxResults": { "title": "Max number of results to return", "type": "integer", "minimum": 1, "maximum": 20, "wx_ui_name": "Max results", "wx_ui_field_type": "numberInput", "wx_ui_default": 10 } } } } }, "required": [ "name", "description" ] }, "wxUtilityAgentToolsRunRequest": { "oneOf": [ { "$ref": "#/components/schemas/utilityAgentToolUnstructuredInput" }, { "$ref": "#/components/schemas/utilityAgentToolStructuredInput" } ] }, "wxUtilityAgentToolsRunResponse": { "type": "object", "additionalProperties": false, "properties": { "output": { "description": "The output from running the tool.", "example": "[{\"title\":\"Toronto, Ontario, Canada Monthly Weather | AccuWeather\",\"description\":\"January. January February March April May June July August September October November December. 2025 ... 13°. 29. 37°. 18°. 30. 34°. 16°. 31. 36°. 18°. 1. 18°. 11 ...\",\"url\":\"https://www.accuweather.com/en/ca/toronto/m5h/january-weather/55488\"},{\"title\":\"Canada weather forecast for Tuesday, 13 January 2026\",\"description\":\"Weather in Canada during the last few years on January 13 ; 2025 - January 13, 32 ° / 26 °, 0 in ; 2024 - January 13, 39 ° / 26 °, 0.46 in ; 2023 - January 13, 32 ...\",\"url\":\"https://www.weather25.com/north-america/canada?page=date&date=13-1\"},{\"title\":\"Toronto January 2025 Historical Weather Data (Ontario, Canada ...\",\"description\":\"January 2025 Weather History in Toronto Ontario, Canada. The data for ... -SN, BR. Mon, Jan 13, Light Snow, Light Snow and Ice Pellets, Mist, Drifting ...\",\"url\":\"https://weatherspark.com/h/m/19863/2025/1/Historical-Weather-in-January-2025-in-Toronto-Ontario-Canada\"}]" } }, "required": [ "output" ] }, "utilityAgentToolUnstructuredInput": { "type": "object", "title": "Unstructured input", "additionalProperties": false, "properties": { "tool_name": { "type": "string", "description": "The name of the tool to be run.", "example": "GoogleSearch" }, "input": { "type": "string", "description": "Input to be used when running tool that has no input_schema.", "example": "What was the weather in Toronto on January 13th 2025?" }, "config": { "$ref": "#/components/schemas/toolConfig" } }, "required": [ "input" ] }, "utilityAgentToolStructuredInput": { "type": "object", "title": "Structured input", "additionalProperties": false, "properties": { "tool_name": { "type": "string", "description": "The name of the tool to be run.", "example": "WebCrawler" }, "input": { "type": "object", "description": "Input to be used when running tool that has an input_schema.", "additionalProperties": true, "properties": {}, "example": { "url": "https://www.ibm.com" } }, "config": { "$ref": "#/components/schemas/toolConfig" } }, "required": [ "input" ] }, "toolConfig": { "description": "Optional configuration options that can be passed for some tools. This must match the config schema for that tool.", "type": "object", "additionalProperties": true, "properties": {}, "example": { "maxResults": 3 } } }, "parameters": { "version": { "name": "version", "description": "The version date for the API of the form `YYYY-MM-DD`.\n", "example": "2023-07-07", "in": "query", "schema": { "type": "string", "format": "date" }, "required": true, "x-sdk-global-param": true }, "start": { "name": "start", "description": "Token required for token-based pagination. This token cannot be determined by end user.\nIt is generated by the service and it is set in the href available in the `next` field.\n", "in": "query", "schema": { "type": "string" } }, "limit": { "name": "limit", "description": "How many resources should be returned. By default limit is 100. Max limit allowed is 200.", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 }, "example": 50 }, "model_filters": { "name": "filters", "description": "A set of filters to specify the list of models, filters are described as the `pattern` shown below.\n```text\n pattern: tfilter[,tfilter][:(or|and)]\n tfilter: filter | !filter\n filter: Requires existence of the filter.\n !filter: Requires absence of the filter.\n filter: one of\n modelid_*: Filters by model id.\n Namely, select a model with a specific model id.\n provider_*: Filters by provider.\n Namely, select all models with a specific provider.\n source_*: Filters by source.\n Namely, select all models with a specific source.\n input_tier_*: Filters by input tier.\n Namely, select all models with a specific input tier.\n output_tier_*: Filters by output tier.\n Namely, select all models with a specific output tier.\n tier_*: Filters by tier.\n Namely, select all models with a specific input or output tier.\n task_*: Filters by task id.\n Namely, select all models that support a specific task id.\n lifecycle_*: Filters by lifecycle state.\n Namely, select all models that are currently in the specified lifecycle state.\n function_*: Filters by function. \n Namely, select all models that support a specific function.\n```", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "^([!]?[^,!]+)(,[!]?[^,!]+)*(:(or|and))?$" }, "example": "modelid_ibm/granite-13b-instruct-v1,modelid_ibm/granite-13b-instruct-v2:or" }, "tech_preview": { "name": "tech_preview", "description": "See all the `Tech Preview` models if entitled.\n", "in": "query", "schema": { "type": "boolean", "default": false } }, "SpaceId": { "name": "space_id", "description": "The space that contains the resource.\nEither `space_id` or `project_id` query parameter has to be given.\n", "in": "query", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9-]*$", "minLength": 36, "maxLength": 36 }, "example": "63dc4cf1-252f-424b-b52d-5cdd9814987f" }, "ProjectId": { "name": "project_id", "description": "The project that contains the resource.\nEither `space_id` or `project_id` query parameter has to be given.\n", "in": "query", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9-]*$", "minLength": 36, "maxLength": 36 }, "example": "a77190a2-f52d-4f2a-be3d-7867b5f46edc" }, "id_or_name": { "name": "id_or_name", "in": "path", "description": "The `id_or_name` can be either the `deployment_id` that identifies the deployment or a `serving_name` that allows a predefined URL to be used to post a prediction.\n\nThe WML instance that is associated with the deployment will be used for limits and billing (if a paid plan).\n", "schema": { "type": "string" }, "required": true }, "id_or_name_chat_template": { "name": "id_or_name", "in": "path", "description": "The `id_or_name` can be either the `deployment_id` that identifies the deployment or a `serving_name` that allows a predefined URL to be used to post a prediction. The deployment must reference either a prompt template with input_mode set to chat, a custom foundation model, or a curated foundation model.\n\nThe WML instance that is associated with the deployment will be used for limits and billing (if a paid plan).\n", "schema": { "type": "string" }, "required": true }, "total_count": { "name": "total_count", "description": "Compute the total count. May have performance impact.", "in": "query", "schema": { "type": "boolean" } }, "hard_delete": { "name": "hard_delete", "description": "Set to true in order to also delete the job or request metadata.", "in": "query", "schema": { "type": "boolean" } }, "path_id": { "name": "id", "in": "path", "description": "The `id` is the identifier that was returned in the `metadata.id` field of the request.\n", "schema": { "type": "string" }, "required": true }, "tag.value": { "name": "tag.value", "description": "Return only the resources with the given tag values, separated by `or` or `and` to support multiple tags.", "in": "query", "schema": { "type": "string" }, "example": "tf2.0 or tf2.1" }, "search": { "name": "search", "in": "query", "description": "Returns only resources that match this search string.\nThe path to the field must be the complete path to the field, and this field\nmust be one of the indexed fields for this resource type. Note that the\nsearch string must be URL encoded.\n\n\nThese are the fields that can be searched in the `metadata`:\n - `/metadata/name`\n\nNote that `tags` are filtered using the `tag` query parameter and the `tag` query parameter\ntakes precedence over the `search` query parameter.\n\nThe metadata fields, on all assets, can be searched like this:\n\n - `/metadata/name=asset2` -> `search=%2Fmetadata%2Fname%3Dasset2`\n\n\nThese are the fields that can be searched in the `entity` and that depend on the asset type:\n - `model`\n - `/entity/type`\n - `/entity/software_spec.id`\n - `function`\n - `/entity/software_spec.id`\n - `ai_service`\n - `/entity/software_spec.id`\n\nThe entity fields can be searched like this:\n\n`/entity.type=tensorflow_2.14` -> `search=%2Fentity%2Ftype%3Dtensorflow_2.14`\n", "schema": { "type": "string", "minLength": 1 } }, "path_ai_service_id": { "name": "id", "in": "path", "x-cli-option-name": "ai-service-id", "description": "AI service identifier.\n", "schema": { "type": "string" }, "example": "64dc8921-345f-234b-462d-78e41246987f", "required": true }, "rev": { "name": "rev", "description": "The revision number of the resource.\n", "in": "query", "schema": { "type": "string" }, "example": "2" }, "GPUId": { "name": "gpu_id", "description": "The GPU id for filtering.\n", "in": "query", "schema": { "type": "string", "pattern": "^[0-9]{1,2}[a-z0-9]{2,6}[-][0-9]{2,4}[g]$", "minLength": 1, "maxLength": 12 }, "example": "1l40s-48g" }, "GPUType": { "name": "gpu_type", "description": "The GPU type for filtering.\n", "in": "query", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9]{4,12}$", "minLength": 4, "maxLength": 12 }, "example": "L40S" }, "model_uuid": { "name": "model_uuid", "in": "path", "description": "Model UUID", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, "policy_uuid": { "name": "policy_uuid", "in": "path", "description": "Tenant Policy UUID", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, "provider_uuid": { "name": "provider_uuid", "in": "path", "description": "Provider UUID", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, "load_balancer_uuid": { "name": "load_balancer_uuid", "in": "path", "description": "Load Balancer UUID", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, "load_balancer_backend_uuid": { "description": "Load Balancer Backend UUID", "in": "path", "name": "load_balancer_backend_uuid", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, "rate_limit_uuid": { "name": "ratelimit_uuid", "in": "path", "description": "Rate limit UUID", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, "session_id": { "name": "session_id", "in": "path", "description": "Prompt Session ID", "required": true, "schema": { "type": "string", "pattern": "[a-zA-Z0-9-]*" } }, "entry_id": { "name": "entry_id", "in": "path", "description": "Prompt Session Entry ID", "required": true, "schema": { "type": "string", "pattern": "[a-zA-Z0-9-]*" } }, "prompt_id": { "name": "prompt_id", "in": "path", "description": "Prompt ID", "required": true, "schema": { "type": "string", "pattern": "[a-zA-Z0-9-]*" } }, "project_id": { "name": "project_id", "in": "query", "description": "[REQUIRED] Specifies the project ID as the target. One target must be supplied per request.", "required": true, "schema": { "type": "string", "pattern": "[a-zA-Z0-9-]*" } }, "space_id": { "name": "space_id", "in": "query", "description": "[REQUIRED] Specifies the space ID as the target. One target must be supplied per request.", "schema": { "type": "string", "pattern": "[a-zA-Z0-9-]*" } }, "restrict_model_parameters": { "name": "restrict_model_parameters", "in": "query", "description": "Only return a set of model parameters compatiable with inferencing", "required": false, "schema": { "type": "string", "default": "true" } }, "index_id": { "name": "index_id", "in": "path", "description": "Vector index ID", "required": true, "schema": { "type": "string", "pattern": "[a-zA-Z0-9-]*" } }, "tool_id": { "name": "tool_id", "in": "path", "description": "Tool name", "required": true, "schema": { "type": "string", "pattern": "[a-zA-Z0-9-]*" } } }, "responses": { "BadRequest": { "description": "Bad request, the response body should contain the reason.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "Unauthorized": { "description": "Unauthorized.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "Forbidden": { "description": "Forbidden, an authentication error including trying to access an unauthorized space or project.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "NotFound": { "description": "The specified resource was not found.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "ApplicationZip": { "description": "OK.\n", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "BadRequestError": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MGErrorResponse" } } } }, "UnauthorizedError": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MGErrorResponse" } } } }, "InternalServerError": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MGErrorResponse" } } } }, "NotFoundError": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MGErrorResponse" } } } }, "ForbiddenError": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MGErrorResponse" } } } }, "ConflictError": { "description": "Conflict error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MGErrorResponse" } } } }, "HTTP400Response": { "description": "Bad request. One of the fields has invalid format/content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "BadRequestError": { "$ref": "#/components/examples/BadRequestError" } } } } }, "HTTP401Response": { "description": "Unauthorized. No/Malformed authentication provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "AuthenticationError": { "$ref": "#/components/examples/AuthenticationError" } } } } }, "HTTP403Response": { "description": "Forbidden. User is not allowed to perform the target operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "AuthorizationError": { "$ref": "#/components/examples/AuthorizationError" } } } } }, "HTTP429Response": { "description": "The number of requests has exceeded the rate limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "RateLimitError": { "$ref": "#/components/examples/RateLimitError" } } } } }, "NotebookCreateResponse": { "description": "Success. Created and returned a new notebook asset. Format follows v2/assets.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/NotebookInProject" }, { "$ref": "#/components/schemas/NotebookForCopy" } ] }, "examples": { "NotebookCreatedFromScratchInProject": { "$ref": "#/components/examples/NotebookInProject" }, "NotebookCreatedByCopying": { "$ref": "#/components/examples/NotebookForCopy" } } } } }, "NotebooksListResponse": { "description": "Success. Returned a list of notebook assets. Format follows v2/assets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotebooksResourceList" }, "examples": { "ListOfNotebooks": { "$ref": "#/components/examples/NotebooksList" } } } } }, "NotebookRevertResponse": { "description": "Success. Reverted the main notebook to a version. Format follows v2/assets.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/NotebookInProject" } ] }, "examples": { "NotebookReverted": { "$ref": "#/components/examples/NotebookReverted" } } } } }, "NotebookUpdateResponse": { "description": "Success. Updated the notebook. Format follows v2/assets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notebook" }, "examples": { "NotebookUpdated": { "$ref": "#/components/examples/NotebookUpdated" } } } } }, "NotebookVersionCreateResponse": { "description": "Success. Returned the notebook version definition.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/NotebookVersionInProject" } ] }, "examples": { "NotebookVersionInProject": { "$ref": "#/components/examples/NotebookVersionInProject" } } } } }, "NotebookVersionsListResponse": { "description": "Success. Returned a list of versions of the notebook.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/NotebookVersionsListInProject" } ] }, "examples": { "ListOfNotebookVersionsInProject": { "$ref": "#/components/examples/NotebookVersionsListInProject" } } } } }, "NotebookVersionRetrieveResponse": { "description": "Success. Returned the version definition.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/NotebookVersionInProject" } ] }, "examples": { "NotebookVersionInProject": { "$ref": "#/components/examples/NotebookVersionInProject" } } } } } }, "examples": { "LoraFineTuningContainerRequest": { "summary": "lora fine tuning with container results reference", "description": "An example of a request to create a fine-tuning job with container asset result reference.\n", "value": { "project_id": "dbbbfd33-1cca-4c6b-a9fa-c939b5f611eb", "name": "Example - Lora fine tuning", "auto_update_model": true, "parameters": { "base_model": { "model_id": "ibm/granite-3-1-8b-base" }, "task_id": "classification", "accumulate_steps": 1, "num_epochs": 10, "learning_rate": 0.00005, "batch_size": 16, "max_seq_length": 2048, "response_template": "\n### Response:", "verbalizer": "### Input: {{input}} \n\n### Response: {{output}}", "gpu": { "num": 1 }, "peft_parameters": { "type": "lora", "rank": 16, "target_modules": [ "all-linear" ], "lora_alpha": 32, "lora_dropout": 0.05 }, "gradient_checkpointing": true }, "results_reference": { "connection": {}, "location": { "path": "fine-tuning/experiment1" }, "type": "container" }, "training_data_references": [ { "connection": {}, "location": { "id": "69f07f10-ccfa-4137-816c-7a781f8c6b74", "href": "https://{cluster_url}/v2/assets/69f07f10-ccfa-4137-816c-7a781f8c6b74?project_id=dbbbfd33-1cca-4c6b-a9fa-c939b5f611eb" }, "type": "data_asset" } ] } }, "QLoraFineTuningConnectionAssetRequest": { "summary": "qlora fine tuning with connection asset results reference", "description": "An example of a request to create a fine-tuning job with qlora minimal parameters.\n", "value": { "project_id": "dbbbfd33-1cca-4c6b-a9fa-c939b5f611eb", "name": "Example - QLora fine tuning", "auto_update_model": false, "parameters": { "base_model": { "model_id": "meta-llama/llama-3-1-70b-gptq" }, "peft_parameters": { "type": "qlora" } }, "results_reference": { "connection": { "id": "c4225076-74fa-4033-bf93-1183a9b6c611" }, "location": { "bucket": "ftys1prod-donotdelete-pr-fegvx5zvy5ob8q", "path": "fine-tuning/experiment2" }, "type": "connection_asset" }, "training_data_references": [ { "connection": {}, "location": { "id": "69f07f10-ccfa-4137-816c-7a781f8c6b74", "href": "https://{cluster_url}/v2/assets/69f07f10-ccfa-4137-816c-7a781f8c6b74?project_id=dbbbfd33-1cca-4c6b-a9fa-c939b5f611eb" }, "type": "data_asset" } ] } }, "LoraFineTuningContainerResponse": { "summary": "lora fine tuning with container results reference", "description": "A lora fine tuning response with a container asset result reference.\n", "value": { "entity": { "auto_update_model": true, "parameters": { "accumulate_steps": 1, "base_model": { "model_id": "meta-llama/llama-3-1-8b" }, "batch_size": 16, "gpu": { "num": 1 }, "gradient_checkpointing": true, "learning_rate": 0.00005, "max_seq_length": 2048, "num_epochs": 10, "peft_parameters": { "lora_alpha": 32, "lora_dropout": 0.05, "rank": 16, "target_modules": [ "all-linear" ], "type": "lora" }, "response_template": "\n### Response:", "task_id": "classification", "verbalizer": "### Input: {{input}} \n\n### Response: {{output}}" }, "results_reference": { "connection": {}, "location": { "path": "fine-tuning/experiment1", "training": "fine-tuning/experiment1/585de69e-1c27-464b-b32e-817343f03ddb", "training_status": "fine-tuning/experiment1/585de69e-1c27-464b-b32e-817343f03ddb/training-status.json", "model_path": "fine-tuning/experiment1/585de69e-1c27-464b-b32e-817343f03ddb/model", "model_request_path": "fine-tuning/experiment1/585de69e-1c27-464b-b32e-817343f03ddb/assets/585de69e-1c27-464b-b32e-817343f03ddb/resources/wml_model/request.json", "training_log": "fine-tuning/experiment1/585de69e-1c27-464b-b32e-817343f03ddb/data/fine_tunings/training.log", "assets_path": "fine-tuning/experiment1/585de69e-1c27-464b-b32e-817343f03ddb/assets" }, "type": "container" }, "status": { "completed_at": "2025-07-22T19:47:56.677Z", "metrics": [ { "context": { "fine_tuning": { "metrics_location": "fine-tuning/experiment1/585de69e-1c27-464b-b32e-817343f03ddb/assets/585de69e-1c27-464b-b32e-817343f03ddb/resources/training_logs.jsonl" } }, "fine_tuning_metrics": { "training_loss": [ { "epoch": 1, "step": 13, "timestamp": "2025-07-22T19:46:18.336564", "value": 2.1197 }, { "epoch": 2, "step": 26, "timestamp": "2025-07-22T19:46:27.116879", "value": 1.5273 }, { "epoch": 3, "step": 39, "timestamp": "2025-07-22T19:46:35.900471", "value": 1.3752 }, { "epoch": 4, "step": 52, "timestamp": "2025-07-22T19:46:44.695792", "value": 1.3024 }, { "epoch": 5, "step": 65, "timestamp": "2025-07-22T19:46:53.517403", "value": 1.2499 }, { "epoch": 6, "step": 78, "timestamp": "2025-07-22T19:47:02.390767", "value": 1.1769 }, { "epoch": 7, "step": 91, "timestamp": "2025-07-22T19:47:11.262264", "value": 1.0993 }, { "epoch": 8, "step": 104, "timestamp": "2025-07-22T19:47:20.131263", "value": 1.0389 }, { "epoch": 9, "step": 117, "timestamp": "2025-07-22T19:47:29.042041", "value": 0.9976 }, { "epoch": 10, "step": 130, "timestamp": "2025-07-22T19:47:37.962070", "value": 0.9661 } ] }, "timestamp": "2025-07-22T19:47:38.390Z" } ], "running_at": "2025-07-22T19:45:14.855Z", "state": "completed" }, "training_data_references": [ { "connection": {}, "location": { "href": "https://{{cluster_url}}/v2/assets/69f07f10-ccfa-4137-816c-7a781f8c6b74?project_id=dbbbfd33-1cca-4c6b-a9fa-c939b5f611eb", "id": "69f07f10-ccfa-4137-816c-7a781f8c6b74" }, "type": "data_asset" } ], "tuned_model": { "id": "3327dd1c-4f15-4c9d-8757-1039c4dc5370", "name": "model-585de69e-1c27-464b-b32e-817343f03ddb" } }, "metadata": { "created_at": "2025-07-22T19:43:25.385Z", "id": "585de69e-1c27-464b-b32e-817343f03ddb", "modified_at": "2025-07-22T19:47:56.736Z", "name": "Example - Lora fine tuning", "project_id": "dbbbfd33-1cca-4c6b-a9fa-c939b5f611eb" } } }, "QLoraFineTuningConnectionAssetResponse": { "summary": "qlora fine tuning with connection asset results reference", "description": "A qlora fine tuning response with a connection asset result reference.\n", "value": { "entity": { "auto_update_model": false, "parameters": { "accumulate_steps": 1, "base_model": { "model_id": "meta-llama/llama-3-1-70b-gptq" }, "batch_size": 5, "gpu": { "num": 1 }, "gradient_checkpointing": true, "learning_rate": 0.00001, "max_seq_length": 1024, "num_epochs": 10, "peft_parameters": { "lora_alpha": 32, "lora_dropout": 0.05, "rank": 8, "target_modules": [], "type": "qlora" }, "response_template": "\n### Response:", "task_id": "generation", "verbalizer": "### Input: {{input}} \n\n### Response: {{output}}" }, "results_reference": { "connection": { "id": "c4225076-74fa-4033-bf93-1183a9b6c611" }, "location": { "path": "fine-tuning/experiment2", "training": "fine-tuning/experiment2/b9fe7886-a217-41b3-8cd3-871934ef8a97", "training_status": "fine-tuning/experiment2/b9fe7886-a217-41b3-8cd3-871934ef8a97/training-status.json", "model_path": "fine-tuning/experiment2/b9fe7886-a217-41b3-8cd3-871934ef8a97/model", "model_request_path": "fine-tuning/experiment2/b9fe7886-a217-41b3-8cd3-871934ef8a97/assets/b9fe7886-a217-41b3-8cd3-871934ef8a97/resources/wml_model/request.json", "assets_path": "fine-tuning/experiment2/b9fe7886-a217-41b3-8cd3-871934ef8a97/assets", "training_log": "fine-tuning/experiment2/b9fe7886-a217-41b3-8cd3-871934ef8a97/data/fine_tunings/training.log", "bucket": "ftys1prod-donotdelete-pr-fegvx5zvy5ob8q" }, "type": "connection_asset" }, "status": { "completed_at": "2025-07-22T20:19:11.438Z", "metrics": [ { "context": { "fine_tuning": { "metrics_location": "fine-tuning/experiment2/b9fe7886-a217-41b3-8cd3-871934ef8a97/assets/b9fe7886-a217-41b3-8cd3-871934ef8a97/resources/training_logs.jsonl" } }, "fine_tuning_metrics": { "training_loss": [ { "epoch": 1, "step": 41, "timestamp": "2025-07-22T20:09:03.935020", "value": 2.9077 }, { "epoch": 2, "step": 82, "timestamp": "2025-07-22T20:10:10.026188", "value": 2.5623 }, { "epoch": 3, "step": 123, "timestamp": "2025-07-22T20:11:15.669555", "value": 1.9919 }, { "epoch": 4, "step": 164, "timestamp": "2025-07-22T20:12:21.458836", "value": 1.7468 }, { "epoch": 5, "step": 205, "timestamp": "2025-07-22T20:13:27.267926", "value": 1.654 }, { "epoch": 6, "step": 246, "timestamp": "2025-07-22T20:14:32.912695", "value": 1.6263 }, { "epoch": 7, "step": 287, "timestamp": "2025-07-22T20:15:37.674088", "value": 1.6236 }, { "epoch": 8, "step": 328, "timestamp": "2025-07-22T20:16:43.060628", "value": 1.6059 }, { "epoch": 9, "step": 369, "timestamp": "2025-07-22T20:17:48.165568", "value": 1.5976 }, { "epoch": 10, "step": 410, "timestamp": "2025-07-22T20:18:53.176969", "value": 1.5774 } ] }, "timestamp": "2025-07-22T20:18:53.507Z" } ], "running_at": "2025-07-22T20:06:18.569Z", "state": "completed" }, "training_data_references": [ { "connection": {}, "location": { "href": "https://{{cluster_url}}/v2/assets/69f07f10-ccfa-4137-816c-7a781f8c6b74?project_id=dbbbfd33-1cca-4c6b-a9fa-c939b5f611eb", "id": "69f07f10-ccfa-4137-816c-7a781f8c6b74" }, "type": "data_asset" } ], "tuned_model": { "name": "model-b9fe7886-a217-41b3-8cd3-871934ef8a97" } }, "metadata": { "created_at": "2025-07-22T20:04:17.269Z", "id": "b9fe7886-a217-41b3-8cd3-871934ef8a97", "modified_at": "2025-07-22T20:19:11.510Z", "name": "Example - QLora fine tuning", "project_id": "dbbbfd33-1cca-4c6b-a9fa-c939b5f611eb" } } }, "NotebookCreateBodyInProject": { "summary": "Create a notebook from scratch in a project", "value": { "name": "my notebook", "description": "this is my notebook", "project": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "file_reference": "notebook/my_notebook.ipynb", "runtime": { "environment": "spark33py39-b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "spark_monitoring_enabled": true } } }, "NotebookCopyBody": { "summary": "Copy a notebook", "value": { "source_guid": "ca3c0e27-46ca-83d4-a646-d49b11c14de9", "name": "my notebook" } }, "NotebooksListBody": { "summary": "List notebooks", "value": { "notebooks": [ "ca3c0e27-46ca-83d4-a646-d49b11c14de9" ] } }, "NotebookRevertBody": { "summary": "Revert the notebook to a version", "value": { "source": "ca3c0e27-46ca-83d4-a646-d49b11c14de9" } }, "NotebookUpdateBody": { "summary": "Update a notebook", "value": { "environment": "d46ca0e27-a646-4de9-a646-9b113c183d4", "spark_monitoring_enabled": false, "kernel": { "display_name": "Python 3.9 with Spark", "name": "python39", "language": "python3" } } }, "NotebookInProject": { "summary": "A notebook created in a project from scratch", "value": { "metadata": { "name": "my notebook", "description": "this is my notebook", "asset_type": "notebook", "created": 1540471021134, "created_at": "2021-07-01T12:37:01Z", "owner_id": "IBMid-310000SG2Y", "catalog_id": "463cb8d8-8480-4a98-b75a-f7443b7d0af9", "asset_id": "41d09a9a-f771-48a2-9534-50c0c622356d", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf" }, "entity": { "notebook": { "kernel": { "display_name": "Python 3.9 with Spark", "name": "python3", "language": "python3" }, "originates_from": { "type": "blank" } }, "runtime": { "environment": "spark33py39-b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "spark_monitoring_enabled": true }, "href": "/v2/assets/41d09a9a-f771-48a2-9534-50c0c622356d?project_id=b275be5f-10ff-47ee-bfc9-63f1ce5addbf" } } }, "NotebookForCopy": { "summary": "A notebook created by copying another notebook", "value": { "metadata": { "name": "my notebook", "description": "this is my notebook", "asset_type": "notebook", "created": 1540471021134, "created_at": "2021-07-01T12:37:01Z", "owner_id": "IBMid-310000SG2Y", "catalog_id": "463cb8d8-8480-4a98-b75a-f7443b7d0af9", "asset_id": "41d09a9a-f771-48a2-9534-50c0c622356d", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf" }, "entity": { "notebook": { "kernel": { "display_name": "Python 3.9 with Spark", "name": "python3", "language": "python3" }, "originates_from": { "type": "notebook", "guid": "ca3c0e27-46ca-83d4-a646-d49b11c14de9" } }, "runtime": { "environment": "spark33py39-b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "spark_monitoring_enabled": true }, "href": "/v2/assets/41d09a9a-f771-48a2-9534-50c0c622356d?project_id=b275be5f-10ff-47ee-bfc9-63f1ce5addbf" } } }, "NotebooksList": { "summary": "A list of notebooks", "value": { "total_results": 1, "resources": [ { "metadata": { "guid": "41d09a9a-f771-48a2-9534-50c0c622356d", "url": "/v2/notebooks/41d09a9a-f771-48a2-9534-50c0c622356d" }, "entity": { "runtime": { "environment": "spark33py39-b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "spark_monitoring_enabled": true }, "asset": { "asset_id": "41d09a9a-f771-48a2-9534-50c0c622356d", "asset_type": "notebook", "created_at": "2021-07-01T12:37:01Z", "catalog_id": "463cb8d8-8480-4a98-b75a-f7443b7d0af9", "version": 2, "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "href": "/v2/assets/41d09a9a-f771-48a2-9534-50c0c622356d?project_id=b275be5f-10ff-47ee-bfc9-63f1ce5addbf" } } } ] } }, "NotebookReverted": { "summary": "A reverted notebook", "value": { "metadata": { "name": "my notebook v4.2", "description": "this is my notebook v4.2", "asset_type": "notebook", "created": 1540471021134, "created_at": "2021-07-01T12:37:01Z", "owner_id": "IBMid-310000SG2Y", "catalog_id": "463cb8d8-8480-4a98-b75a-f7443b7d0af9", "asset_id": "41d09a9a-f771-48a2-9534-50c0c622356d", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf" }, "entity": { "notebook": { "kernel": { "display_name": "Python 3.9 with Spark", "name": "python39", "language": "python3" }, "originates_from": { "type": "blank" } }, "runtime": { "environment": "spark33py39-b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "spark_monitoring_enabled": true }, "href": "/v2/assets/41d09a9a-f771-48a2-9534-50c0c622356d?project_id=b275be5f-10ff-47ee-bfc9-63f1ce5addbf" } } }, "NotebookUpdated": { "summary": "An updated notebook", "value": { "metadata": { "name": "my notebook", "description": "this is my notebook", "asset_type": "notebook", "created": 1540471021134, "created_at": "2021-07-01T12:37:01Z", "owner_id": "IBMid-310000SG2Y", "catalog_id": "463cb8d8-8480-4a98-b75a-f7443b7d0af9", "asset_id": "41d09a9a-f771-48a2-9534-50c0c622356d", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf" }, "entity": { "notebook": { "kernel": { "display_name": "Python 3.9 with Spark", "name": "python39", "language": "python3" }, "originates_from": { "type": "blank" } }, "runtime": { "environment": "d46ca0e27-a646-4de9-a646-9b113c183d4", "spark_monitoring_enabled": false }, "href": "/v2/assets/41d09a9a-f771-48a2-9534-50c0c622356d?project_id=b275be5f-10ff-47ee-bfc9-63f1ce5addbf" } } }, "NotebookVersionInProject": { "summary": "A notebook version in a project", "value": { "metadata": { "guid": "19d63b6b-81a1-4c05-bad2-36a2957bd6d0", "url": "v2/notebooks/a528b427-d1cd-4039-8ddc-04203c2521e2/versions/1a1329e0-fd05-409a-8411-52db106e2142", "created_at": 1543681714106 }, "entity": { "master_notebook_guid": "a528b427-d1cd-4039-8ddc-04203c2521e2", "project_id": "0f7c1111-a79d-45b2-9699-d4950e742964", "created_by_iui": "IBMid-123456ABCD", "file_reference": "myproject-donotdelete-pr-6p65nym92j1bv0/notebooks/GPU_ENVIRONMENT_DEFAULT_GBUXVKHH_version_1543781324804.ipynb", "rev_id": 1 } } }, "NotebookVersionsListInProject": { "summary": "A list of notebook versions in a project", "value": { "total_results": 1, "resources": [ { "metadata": { "guid": "19d63b6b-81a1-4c05-bad2-36a2957bd6d0", "url": "v2/notebooks/a528b427-d1cd-4039-8ddc-04203c2521e2/versions/1a1329e0-fd05-409a-8411-52db106e2142", "created_at": 1543681714106 }, "entity": { "master_notebook_guid": "a528b427-d1cd-4039-8ddc-04203c2521e2", "project_id": "0f7c1111-a79d-45b2-9699-d4950e742964", "created_by_iui": "IBMid-123456ABCD", "file_reference": "myproject-donotdelete-pr-6p65nym92j1bv0/notebooks/GPU_ENVIRONMENT_DEFAULT_GBUXVKHH_version_1543781324804.ipynb", "rev_id": 1 } } ] } }, "BadRequestError": { "summary": "Bad request error with status code 400", "value": { "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project" } } ] } }, "AuthenticationError": { "summary": "Authentication error with status code 401", "value": { "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] } }, "AuthorizationError": { "summary": "Authorization error with status code 403", "value": { "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] } }, "RateLimitError": { "summary": "Rate limit error with status code 429", "value": { "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "rate_limit", "message": "The requests from IBMid-310000A00A exceeds rate limit. Please try again later." } ] } } }, "requestBodies": { "AIServiceBody": { "description": "A gzip file containing code files.\n", "required": true, "content": { "application/gzip": { "schema": { "type": "string", "format": "binary" } } } } } } }